soustack 0.4.0 → 0.4.1

package/spec/stacks/prep@1.md

@@ -0,0 +1,276 @@
+#prep@1
+
+---
+
+## Purpose
+
+The `prep@1` stack enables recipes to include preparation guidance at both the ingredient level and as explicit mise en place tasks. This makes recipes more operational by providing clear prep instructions and planning checklists.
+
+This stack is adoption-first: ingredient prep can be simple strings for minimal friction, or structured objects for more detailed guidance.
+
+---
+
+## Requirements
+
+A document that declares `prep@1`:
+
+• MUST satisfy all structural rules enabled by this stack.
+• MUST satisfy the semantic rules described below.
+
+---
+
+## Data Model
+
+When `prep@1` is declared, the document MUST include a top-level `miseEnPlace` array.
+
+### Mise En Place Array
+
+The `miseEnPlace` array contains one or more tasks. Each task is a structured object that describes a prep step.
+
+### Ingredient-Level Prep
+
+Ingredient objects MAY include an optional `prep` field that describes how the ingredient should be prepared. The `prep` field supports multiple formats:
+
+• A single string (simple prep phrase)
+• An array of strings (multiple prep notes)
+• An array of structured prep items
+
+---
+
+## Ingredient Prep Formats
+
+### String Format
+
+A simple string describing the prep:
+
+```json
+{
+  "id": "onion",
+  "name": "Onion",
+  "prep": "finely diced"
+}
+```
+
+### Array of Strings
+
+Multiple prep notes:
+
+```json
+{
+  "id": "garlic",
+  "name": "Garlic",
+  "prep": ["peeled", "minced"]
+}
+```
+
+### Structured Prep Items
+
+More detailed prep instructions with verbs and details:
+
+```json
+{
+  "id": "tomato",
+  "name": "Tomato",
+  "prep": [
+    { "verb": "dice", "detail": "fine" },
+    { "verb": "reserve", "detail": "half for garnish" }
+  ]
+}
+```
+
+Each prep item object includes:
+
+• `verb` (required): string describing the action (freeform; no controlled vocabulary in v1)
+• `detail` (optional): string providing additional context
+
+---
+
+## Mise En Place Tasks
+
+### Minimal Task
+
+A task with only required text:
+
+```json
+{
+  "miseEnPlace": [
+    { "text": "Finely dice the onion" },
+    { "text": "Mince the garlic" }
+  ]
+}
+```
+
+### Task with ID
+
+Tasks may include an optional `id` for cross-referencing:
+
+```json
+{
+  "miseEnPlace": [
+    { "id": "dice-onion", "text": "Finely dice the onion" },
+    { "id": "mince-garlic", "text": "Mince the garlic" }
+  ]
+}
+```
+
+Task IDs MUST be unique within the `miseEnPlace` array (semantic validation).
+
+### Task with Ingredient References
+
+When `referenced@1` is present, tasks may reference ingredient IDs:
+
+```json
+{
+  "miseEnPlace": [
+    {
+      "text": "Prepare the vegetables",
+      "inputs": ["onion", "garlic"]
+    }
+  ]
+}
+```
+
+Each id in `inputs` MUST exist in the ingredients array (semantic validation when both stacks are present).
+
+### Task with Equipment References
+
+When `equipment@1` is present, tasks may reference equipment IDs:
+
+```json
+{
+  "miseEnPlace": [
+    {
+      "text": "Sharpen the knife",
+      "usesEquipment": ["knife"]
+    }
+  ]
+}
+```
+
+Each id in `usesEquipment` MUST exist in the equipment array (semantic validation when both stacks are present).
+
+### Combined References
+
+Tasks may include both `inputs` and `usesEquipment`:
+
+```json
+{
+  "miseEnPlace": [
+    {
+      "text": "Dice the onion with a sharp knife",
+      "inputs": ["onion"],
+      "usesEquipment": ["knife"]
+    }
+  ]
+}
+```
+
+---
+
+## Semantics
+
+### Prep Field
+
+The ingredient `prep` field is descriptive and freeform. In v1, there is no controlled vocabulary for prep verbs or details. Tools may interpret these as hints for display or planning, but validation does not enforce specific values.
+
+### Mise En Place
+
+The `miseEnPlace` array is an explicit checklist of prep tasks. Tools may render this as a prep plan, separate from the main cooking instructions. Tasks are ordered and may be presented as a sequential checklist.
+
+---
+
+## Composition
+
+The prep stack is composable with other stacks:
+
+• No hard dependency on `referenced@1` or `equipment@1` (references are optional and only validated when those stacks are present)
+• Works with `structured@1` to enable ingredient object definitions
+• Remains monotonic: does not close objects needed by other stacks
+• Ingredient `prep` is optional even when the stack is present
+
+---
+
+## Semantic Validation Rules (Normative)
+
+Validators MUST enforce the following rules:
+
+1. Mise en place task ID uniqueness
+   If tasks include `id` values, all task IDs MUST be unique within the `miseEnPlace` array.
+
+2. Ingredient reference resolution
+   If both `prep@1` and `referenced@1` are present, and a task includes `inputs`, all referenced ingredient IDs MUST exist in the ingredients array.
+
+3. Equipment reference resolution
+   If both `prep@1` and `equipment@1` are present, and a task includes `usesEquipment`, all referenced equipment IDs MUST exist in the equipment array (as object ids, not string items).
+
+---
+
+## Examples
+
+Minimal mise en place
+
+```json
+{
+  "miseEnPlace": [
+    { "text": "Finely dice the onion" },
+    { "text": "Mince the garlic" }
+  ]
+}
+```
+
+Ingredient prep with strings
+
+```json
+{
+  "ingredients": [
+    {
+      "id": "onion",
+      "name": "Onion",
+      "prep": "finely diced"
+    },
+    {
+      "id": "garlic",
+      "name": "Garlic",
+      "prep": ["peeled", "minced"]
+    }
+  ]
+}
+```
+
+Structured prep items
+
+```json
+{
+  "ingredients": [
+    {
+      "id": "tomato",
+      "name": "Tomato",
+      "prep": [
+        { "verb": "dice", "detail": "fine" },
+        { "verb": "reserve", "detail": "half for garnish" }
+      ]
+    }
+  ]
+}
+```
+
+Mise en place with references
+
+```json
+{
+  "equipment": [
+    { "id": "knife", "name": "Chef's knife" }
+  ],
+  "ingredients": [
+    { "id": "onion", "name": "Onion" }
+  ],
+  "miseEnPlace": [
+    {
+      "text": "Dice the onion with a sharp knife",
+      "inputs": ["onion"],
+      "usesEquipment": ["knife"]
+    }
+  ]
+}
+```
+

package/spec/stacks/quantified.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/quantified.schema.json",
+  "title": "Quantified Stack",
+  "type": "object",
+  "properties": {
+    "ingredients": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/ingredient" },
+          { "$ref": "#/$defs/ingredientSection" }
+        ]
+      }
+    }
+  },
+  "required": ["ingredients"],
+  "$defs": {
+    "ingredient": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "quantity": { "$ref": "../defs/quantity.schema.json" },
+        "temperature": { "$ref": "../defs/temperature.schema.json" },
+        "notes": { "type": "string" },
+        "prep": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "anyOf": [
+                  { "type": "string", "minLength": 1 },
+                  { "$ref": "../stacks/prep.schema.json#/$defs/prepItem" }
+                ]
+              }
+            }
+          ]
+        },
+        "metadata": { "type": "object", "additionalProperties": true },
+        "scaling": { "$ref": "../defs/scalingRule.schema.json" }
+      },
+      "required": ["id", "name", "quantity"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "ingredientSection": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "ingredients": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/ingredient" },
+              { "$ref": "#/$defs/ingredientSection" }
+            ]
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["section", "ingredients"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/spec/stacks/quantified@1.md

@@ -0,0 +1,24 @@
+# quantified@1
+
+## Purpose
+The `quantified@1` stack enables recipes to declare precise ingredient quantities with units, enabling scaling and computation.
+
+## Adds
+- Top-level `ingredients` array with structured ingredient objects containing `id`, `name`, and `quantity` fields.
+- Ingredients may include `temperature`, `notes`, `prep`, `scaling`, and `metadata`.
+- Support for nested ingredient sections.
+
+## Requires
+- None
+
+## Semantics
+- MUST: Each ingredient object must include `id`, `name`, and `quantity` fields.
+- MUST: Ingredient IDs must be unique within the ingredients array.
+- NOTE: This stack is a prerequisite for `scaling@1`.
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: Required by `scaling@1` for scaling behavior. Works with `structured@1` for stable ingredient references.
+
+
+

package/spec/stacks/referenced.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/referenced.schema.json",
+  "title": "Referenced Stack",
+  "type": "object",
+  "properties": {
+    "ingredients": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/ingredient" },
+          { "$ref": "#/$defs/ingredientSection" }
+        ]
+      }
+    },
+    "instructions": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/referencedStep" },
+          { "$ref": "#/$defs/referencedSection" }
+        ]
+      }
+    }
+  },
+  "required": ["ingredients", "instructions"],
+  "allOf": [
+    { "$ref": "./structured.schema.json" }
+  ],
+  "$defs": {
+    "ingredient": {
+      "allOf": [
+        { "$ref": "../defs/entities.schema.json#/$defs/IngredientBase" },
+        { "required": ["id"] }
+      ]
+    },
+    "ingredientSection": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "ingredients": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/ingredient" },
+              { "$ref": "#/$defs/ingredientSection" }
+            ]
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["section", "ingredients"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "referencedStep": {
+      "allOf": [
+        { "$ref": "../defs/entities.schema.json#/$defs/StepBase" },
+        {
+          "properties": {
+            "inputs": {
+              "allOf": [
+                { "$ref": "../defs/entities.schema.json#/$defs/StepBase/properties/inputs" },
+                { "minItems": 1 }
+              ]
+            }
+          },
+          "required": ["id", "inputs"]
+        }
+      ]
+    },
+    "referencedSection": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "steps": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/referencedStep" },
+              { "$ref": "#/$defs/referencedSection" }
+            ]
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["section", "steps"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  }
+}

package/spec/stacks/referenced@1.md

@@ -0,0 +1,23 @@
+# referenced@1
+
+## Purpose
+The `referenced@1` stack enables steps to explicitly reference ingredient IDs, creating clear input-output relationships for planning and validation.
+
+## Adds
+- Step objects must include an `inputs` array with at least one ingredient ID reference.
+- Ingredient objects must include `id` fields.
+
+## Requires
+- `structured@1`
+
+## Semantics
+- MUST: Each step must include an `inputs` array with at least one element.
+- MUST: All ingredient IDs referenced in step `inputs` must exist in the ingredients array.
+- NOTE: This stack implies `structured@1` (steps are objects with IDs).
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: Required by `substitutions@1` for substitution target resolution. Works with `prep@1` for mise en place task references.
+
+
+

package/spec/stacks/registry.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "../schemas/stacks-registry.schema.json",
+  "registryVersion": 1,
+  "spec": {
+    "name": "soustack",
+    "currentSpecVersion": "0.3.0",
+    "canonicalStacksFormat": "map"
+  },
+  "profiles": {
+    "lite": { "title": "Lite", "description": "Lowest-friction publishing with minimal structure", "requiresProfiles": [], "requiresStacks": [] },
+    "base": { "title": "Base", "description": "Minimum cookable baseline with yield + time", "requiresProfiles": ["lite"], "requiresStacks": [] },
+    "scalable": { "title": "Scalable", "description": "Quantified + scaling", "requiresProfiles": ["base"], "requiresStacks": ["quantified", "scaling"] },
+    "timed": { "title": "Timed", "description": "Structured + timed", "requiresProfiles": ["base"], "requiresStacks": ["structured", "timed"] },
+    "illustrated": { "title": "Illustrated", "description": "Media present", "requiresProfiles": ["base"], "requiresStacks": ["illustrated"] },
+    "equipped": { "title": "Equipped", "description": "Recipe declares required tools/equipment.", "requiresProfiles": ["base"], "requiresStacks": ["equipment"] },
+    "prepped": { "title": "Prepped", "description": "Recipe includes prep guidance and/or mise en place tasks.", "requiresProfiles": ["base"], "requiresStacks": ["prep"] }
+  },
+  "stacks": {
+    "quantified": {
+      "title": "Quantified",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/quantified.schema.json" } },
+      "docs": { "major": { "1": "stacks/quantified@1.md" } }
+    },
+    "scaling": {
+      "title": "Scaling",
+      "latestMajor": 1,
+      "requires": ["quantified"],
+      "schema": { "major": { "1": "stacks/scaling.schema.json" } },
+      "docs": { "major": { "1": "stacks/scaling@1.md" } }
+    },
+    "structured": {
+      "title": "Structured",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/structured.schema.json" } },
+      "docs": { "major": { "1": "stacks/structured@1.md" } }
+    },
+    "timed": {
+      "title": "Timed",
+      "latestMajor": 1,
+      "requires": ["structured"],
+      "schema": { "major": { "1": "stacks/timed.schema.json" } },
+      "docs": { "major": { "1": "stacks/timed@1.md" } }
+    },
+    "referenced": {
+      "title": "Referenced",
+      "latestMajor": 1,
+      "requires": ["structured"],
+      "schema": { "major": { "1": "stacks/referenced.schema.json" } },
+      "docs": { "major": { "1": "stacks/referenced@1.md" } }
+    },
+    "illustrated": {
+      "title": "Illustrated",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/illustrated.schema.json" } },
+      "docs": { "major": { "1": "stacks/illustrated@1.md" } }
+    },
+    "dietary": {
+      "title": "Dietary",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/dietary.schema.json" } },
+      "docs": { "major": { "1": "stacks/dietary@1.md" } }
+    },
+    "substitutions": {
+      "title": "Substitutions",
+      "latestMajor": 1,
+      "requires": ["referenced"],
+      "schema": { "major": { "1": "stacks/substitutions.schema.json" } },
+      "docs": { "major": { "1": "stacks/substitutions@1.md" } }
+    },
+    "techniques": {
+      "title": "Techniques",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/techniques.schema.json" } },
+      "docs": { "major": { "1": "stacks/techniques@1.md" } }
+    },
+    "storage": {
+      "title": "Storage",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/storage.schema.json" } },
+      "docs": { "major": { "1": "stacks/storage@1.md" } }
+    },
+    "compute": {
+      "title": "Compute",
+      "latestMajor": 1,
+      "requires": ["quantified", "timed"],
+      "schema": { "major": { "1": "stacks/compute.schema.json" } },
+      "docs": { "major": { "1": "stacks/compute@1.md" } }
+    },
+    "equipment": {
+      "title": "Equipment",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/equipment.schema.json" } },
+      "docs": { "major": { "1": "stacks/equipment@1.md" } }
+    },
+    "prep": {
+      "title": "Prep",
+      "latestMajor": 1,
+      "requires": [],
+      "schema": { "major": { "1": "stacks/prep.schema.json" } },
+      "docs": { "major": { "1": "stacks/prep@1.md" } }
+    }
+  }
+}
+