Cookwala Core 0.2

Status: draft 0.2.1, 2026-10-05 (RFC-0012 changed what a signature covers; comment window open until 2026-11-04). This is the normative part of Cookwala. MUST, SHOULD and MAY follow RFC 2119. Everything not listed here is an optional profile (section 10).

A device should be able to implement Core in about a week. Core says what to make, when it is done and what must never happen. It does not say how a robot moves.

1. Conformance classes #

Claiming a class means passing its conformance vectors (conformance/, run with tools/run_conformance.py).

2. Core documents #

All schemas are strict: unknown fields are rejected, except x-<vendor>-… extensions. Readers ignore x- fields they don't understand. tools/bundle_schemas.py produces a single bundle so that devices validate offline. Implementations MUST NOT fetch schemas at run time.

3. What operations mean #

• Envelopes. Every heat-based or hazardous operation in vocab/ops.json has an envelope. It specifies: Example: cw.op.simmer = water-based liquid at 85–96 °C; cw.op.deep_fry = oil at 160–190 °C.
  • the medium (water, oil, air, pan surface, product…);
  • its temperature band in °C (and pressure, for pressure cooking);
  • agitation, lid, attention level and whether the step may run unattended;
  • hazards;
  • a test method.
• Targets inside envelopes. A recipe target (params.tempC or a target on the medium's sensor) MUST lie inside the envelope. The validator rejects recipes that break this.
• Executors keep the medium inside the envelope. If the recipe gives a narrower target, they keep it inside that too, once it is first reached.
• Altitude. Water and steam bands shift by −1 °C per 300 m of kitchen altitude.
• Heat levels (very_low … max) have one shared meaning: a pan-surface band in °C, defined in vocab/units.json.
• Sensor ladder. Each envelope lists ways to verify the step, best first: a specific sensor, then model (a logged estimate), then time, then human.
  • The executor uses the first rung it can satisfy and records it in verifiedBy.
  • If it can satisfy no rung, it MUST refuse the step (missing_sensor_no_fallback).
  • Operations that need constant attention and may not run unattended (sautéing, searing, frying, reducing, caramelizing…) never fall back to time alone: their last rung is a person watching.
  • Deep frying has no fallback: no oil-temperature sensor means no deep frying.
  • A Condition can narrow this with onSensorMissing.
• Refusal, not guessing. An executor that cannot meet a step's envelope, ladder, equipment or safety limits MUST answer refused with a reason before starting.

4. Numbers and units #

• Temperatures are °C on the wire. Displays may convert.
• Tolerances.
  • tolerance is relative and allowed only on ratio-scale units.
  • toleranceAbs is absolute in the value's unit, and is the only tolerance allowed on °C.
  • Target.tolerance is absolute.
• Kitchen units have exact metric values: tsp 5 ml, tbsp 15 ml, cup 240 ml, pinch ≈ 0.36 g, dash ≈ 0.6 ml.
• Volume ↔ mass needs a density (Quantity.densityGPerMl, or the ingredient vocabulary); without one it is an error, never a guess.
• Money is a decimal string ("12.70") with an ISO 4217 currency, never a float.

5. Integrity and trust #

• Hash. sha256: plus the hex digest of the RFC 8785 canonical JSON of the document, without its hash and signature fields. The reference canonicalizer reproduces the RFC 8785 example exactly.
• Signature. Ed25519 (EdDSA) over the RFC 8785 canonical JSON of the signing header {alg, hash, kid, kind, signedAt}, where hash is the document hash and kind the document kind when it has one (Event for log events, Checkpoint for checkpoints). signedAt is required and covered by the signature, so revocation and validity are checked against a time the signer cannot change afterwards; kid and alg are covered, so a signature cannot be moved to another key id or algorithm. ES256 is allowed for P-256 hardware keys. kid names a KeyRecord. (RFC-0012; 0.2.0 signed the bare hash string.)
• Keys. A KeyRecord gives the public key, its owner, a validity window and revokedAt. A signature whose signedAt falls after revocation, or outside the validity window, is invalid.
  • Catalogs publish their keys in /.well-known/cookwala.json.
  • Organizations and people publish theirs in did:web documents.
  • Devices publish theirs in their capabilities document.
  • Verifiers cache key records for offline use.
• Selective disclosure. A signed document may hold a Disclosure digest, sha256(JCS([salt, value])), instead of a sensitive value. The holder reveals the salt and value only to parties allowed to see them, and the signature still verifies.
• Event logs (Mission profile):
  • One sequencer per log assigns seq and prev, so the chain never forks.
  • Checkpoints are signed by the sequencer and counter-signed by at least one witness whose key is not the sequencer's; witnesses may include a transparency service such as IETF SCITT. Two checkpoints of one log at the same seq with different heads prove a fork. A rewrite after a witnessed checkpoint is detectable.
  • In hash_only mode, payloads live in erasable storage and the log keeps only their hashes.

6. Safety and agent rules (normative) #

1. Safety is local. Executors enforce a SafetyLimits pack on the device.
   • No recipe, agent, remote message, extension or operating mode can raise or disable a limit.
   • A stricter limit always wins.
   • profiles/core/safety-limits.default.json is a draft starting point that device makers tighten from their own safety case.
2. Local stop. A stop control on the device stops motion within 0.5 s and cuts heat within 1 s, with or without a network. POST …/stop is never refused for authorization once the caller can reach the executor.
3. Events report; they never protect. cookwalalatency: local_safety events report what a device already did. No safety function may depend on an event arriving.
4. Untrusted text. Every free-text field (annotated x-cookwala-untrusted) is data and never an instruction, for software and AI agents alike. Attempts to instruct through text are ignored and logged (cw.incident.untrusted_instruction).
5. Agents act under a mandate. A request sent by an agent carries an AgentMandate signed by the principal: scopes, spending caps, allowed providers, expiry, and actions that need confirmation.
   • irreversible and safety_override always need confirmation, whatever the mandate says.
   • Executors refuse requests outside the mandate (mandate_scope).
6. Unattended operations need a person. Operations whose envelope says unattended: false need a responsible person present, or reachable within one minute.
7. Allergen blocks refuse. Any blocked allergen in the recipe or the inventory refuses the request; there are no substitutions around a block.
8. Recalls. Catalogs publish signed recalls at GET /v1/recalls. Executors poll when online and refuse recalled revisions. block_and_stop_running also stops running executions safely.
9. Incident reports are anonymous (IncidentReport: date only, no names or ids) and submitted to catalogs so every maker learns from each near miss.

7. Execution lifecycle and API #

• API: api/core.openapi.yaml. Its endpoints are:
  • POST /v1/executions, GET /v1/executions/{id};
  • POST /v1/executions/{id}/stop, POST /v1/executions/{id}/resume, GET /v1/executions/{id}/log;
  • GET /v1/safety-limits, GET /v1/capabilities;
  • catalog side: GET /v1/recalls, POST /v1/incidents.
• States:
  • accepted → preparing → running → completed;
  • paused, needs_human and stopping → stopped along the way;
  • refused and failed are final.
  • The full transition table is in core.schema.json#/$defs/ExecutionState and the conformance vectors.
• Request rules:
  • Every POST carries an Idempotency-Key.
  • Changes to an existing execution carry If-Match: <seq>; a mismatch returns 412.
  • Stop does not require If-Match.
• Events:
  • Delivery is at least once.
  • CloudEvents id is the deduplication key.
  • cookwalaseq orders events per subject and matches the status seq.
  • Devices emit cookwala.device.heartbeat, so a hub can detect a lost device and hand off.

8. Privacy #

• Execution logs carry no personal data (privacy.personalData: "none").
• They leave the device only with opt-in consent (consent.dataset: none by default, research_only, or open). Consent can be withdrawn.
• Open datasets coarsen times to the day.
• Household, health and religious data stay home unless the person chooses otherwise. When it must travel, it travels as selective disclosures.
• The Humanitarian Profile carries no personal data at all.

9. Versioning and extensions #

• **Core versions are 0.2.x.**
  • Readers accept any patch of their minor version.
  • They reject other minors with unsupported_version.
  • They ignore unknown x- fields.
• New operations, units, sensors and incident types are added to vocabularies without a version change.
• Changing an operation's meaning is a new id; the old one is marked deprecated with replacedBy.
• Profiles version independently and declare the Core version they need.

10. Profiles and their status #

A profile becomes stable when two independent implementations pass its conformance vectors and it has real users.

11. Tools #

12. Changes from 0.1 #

To migrate a 0.1 document: convert °F to °C; replace relative tolerances on temperatures with toleranceAbs; turn money amounts into decimal strings; remove or rename unknown fields to x- fields.