Cookwala: Plan

Cookwala: the open standard for cooking safely: people, kitchens and robots. (The first one-liner, "the world's first and largest robot cooking recipes index and CLI", was retired; see IMPACT.md and STRATEGY.md.) An open, royalty-free standard and a free public index that lets any robot, appliance or AI agent find a recipe, check that it is safe and allowed where it runs, and cook it end to end, alone or together with other machines and people.

Mission: help end world hunger and make people healthier. Every person should eat, including people who can't pay, and get the right food, cooked the right way, in the right amount, at a known cost, with minimal waste. See MISSION.md and HEALTH.md.

The architecture that ties everything together is the Cookwala Protocol (PROTOCOL.md): context-rich, signed Missions passed between providers and executed as living plans. Recipes follow the layered format in RECIPE-FORMAT.md. Prior art is reviewed in PRIOR-ART.md.

Start with CORE.md. Cookwala Core 0.2 is the normative part; everything else in this plan is vision or an experimental profile.

Status: draft v0.1, 2026-10-03. Owner: fifi.cooking. Repo: https://github.com/amado2k5/cookwala

"First and largest" is the positioning goal. Our landscape scan (RESEARCH.md) found no open recipe-execution standard or shared index today, so "first" is defensible once we publish. "Largest" becomes true when the index passes the biggest closed libraries (Posha advertises 1,000+). We start with 1,881 fifi.cooking recipes plus World Cuisines. Re-check both claims before using them in marketing.

1. What Cookwala is #

What it is not: firmware, a motion controller, a safety certification, or legal advice. Device makers stay responsible for safe hardware. Cookwala supplies the data and the coordination contracts that make safe execution possible and checkable.

2. Principles #

1. Food state first, device-agnostic. Steps say what must happen to the food and how to tell it's done, never "speed 4".
2. Every step ends on a measurable condition. Sensor or vision cue plus a time window, with a defined timeout path.
3. Safety is data. Hazards, CCPs, allergens, supervision, abort procedures and safety events are typed and enforced.
4. Rules are separate. Local food-safety, dietary, venue and device rules are versioned policy packs evaluated at run time.
5. Honest trust levels. V0 described → V1 structured → V2 simulated + reviewed → V3 field-verified. Devices choose the minimum level per supervision mode.
6. Mixed teams by default. Any step can be done by a robot, an appliance or a human, with handoffs and fallbacks (research shows long autonomous tasks still mostly fail).
7. Reuse, don't reinvent. Matter for appliances and alarms, ROS 2 / Open-RMF ideas for robots, A2A + MCP for agents, UCP/ACP/AP2 for commerce, CloudEvents + MQTT for events, schema.org / FoodOn / Wikidata / IEEE 1872.1 for meaning.
8. Local-first, cloud-optional. Kitchens keep working offline. The index is static and cacheable.
9. Verifiable. Hashes, signed manifests, recall feed, audit logs.
10. Open to everyone. Royalty-free, no keys, no membership. Any manufacturer can implement it.

3. The data model (layers) #

L4 Policy packs   jurisdiction · dietary · venue · household · device     policy.schema.json
L3 Safety         hazards · CCPs · allergens · dietary · supervision · abort
L2 Bindings       optional device-class hints (x-oven.matter, x-thermocooker …)
L1 Process graph  typed ops (vocab/ops.json) · params · until · onTimeout · assignment
L0 Semantics      dish · yield · ingredients (cw.ing ids, SI qty) · equipment · nutrition · cost · text
                                                                          recipe.schema.json
Runtime:  capabilities.schema.json → session.schema.json (plan, tasks, leases, handoffs, CCP log)
          event.schema.json (CloudEvents) · inventory.schema.json · order.schema.json · report.schema.json
Index:    catalog.schema.json (discovery, manifest, index entries, changes, vocabularies)
Existing: legacy/fifi-data-v1.schema.json (fifi.cooking /data API, unchanged)

Worked example: examples/shakshuka.cookwala.json (validates against the schema).

Schema inventory #

4. Verification levels #

5. Interoperability (summary of INTEROP.md) #

• Robots ↔ robots: through the hub. Resource leases (burner, pan, counter zone, arm) and handoffs with acknowledgement; ROS 2 action bridge; fleet managers act as one executor.
• Robots ↔ humans: per-step assignment and fallback to humans, human confirmations of vision checks, guided mode, presence requirements, overrides limited by policy.
• Appliances: Matter oven/cooktop/microwave/hood/fridge/smoke-CO bindings (bindings/matter.json), plus Home Connect / SmartThings / vendor adapters.
• Smart fridge / pantry: inventory.schema.json (Matter covers fridge state, not contents), reservations, expiry-driven suggestions.
• Ordering and delivery: OrderIntent → UCP/ACP adapters; human approval or an explicit standing budget rule; robot receive of deliveries.
• Safety and security systems: cookwala.safety.* events with a mandatory response matrix, e-stop, unattended-heat watchdog, never silencing alarms, signed data, scoped pairing.
• Notifications: urgency-based routing to phones, speakers, TVs, watches, lights, SMS/email, with escalation.
• AI agents: MCP tools and an A2A AgentCard. Agents prepare, humans confirm.

6. Interfaces (summary of API.md and CLI.md) #

REST (two OpenAPI 3.1 specs), GraphQL (one schema: catalog + kitchen, with subscriptions), events (AsyncAPI 3 over MQTT/WS/SSE + webhooks), MCP server, A2A agent, and the cookwala CLI (search, get, validate, simulate, convert, sign, hub, pair, plan, session, inventory, order, policy, estop, conformance).

7. Index operations #

• Static build from this repo (recipes/, vocab/, policies/) → GitHub Pages or Cloudflare at cookwala.ai. An edge worker serves search, match, plan-preview, reports, GraphQL and MCP.
• Signing key in CI secrets (Ed25519), rotated yearly, published in /.well-known/cookwala.json.
• Recalls: a safety report triggers triage within 24 h. A recall entry in changes makes hubs refuse the revision.
• Mirrors welcome (signed content stays verifiable anywhere).

8. Open source and governance #

• Licenses: schemas, tools, SDKs and reference hub under Apache-2.0 (patent grant). Spec text CC BY 4.0. Vocabularies, bindings and policy packs CC0. Recipe data CC BY 4.0 only where we hold the rights (see EXPORT-FIFI §2).
• Patent pledge (PATENTS.md): no assertion against conforming implementations.
• No gatekeeping: reading the index needs no key. Implementing needs no permission. The conformance suite is free, and passing it lets a product say "Cookwala Compatible" for its profile (Reader, Guided, Executor, Appliance Bridge, Hub, Inventory Source, Commerce Adapter, Notifier).
• Process (GOVERNANCE.md): public RFCs, 30-day comment period, SemVer, additive minor versions, a 3-year support window for /v1. fifi.cooking edits at first. A steering group with device makers, food-safety and dietary experts forms once there are independent adopters. Later: present to the CSA (Matter), the IEEE RAS 1872 working groups and the EU ICT standardisation rolling plan.
• Vendor extensions: x-<vendor> namespaces registered by PR. Popular ones get promoted to core.

9. Roadmap #

The full milestone plan (M0–M8, repos, team, infrastructure, metrics) is in IMPLEMENTATION.md. M0 (this draft) is done. M1 publishes the specs at cookwala.ai and ships the core library and CLI.

10. Risks #

11. Decisions needed #

1. Register cookwala.ai and point it at the index host (GitHub Pages or Cloudflare). All schema ids and endpoints already use https://cookwala.ai.
2. Content rights per collection (EXPORT-FIFI §2.1).
3. Push this draft to the public repo now?
4. First real-device target for phase 5 (Matter induction cook surface + oven is the cheapest real demo).