soustack 0.4.0 → 0.4.1

package/spec/stacks/storage@1.md

@@ -0,0 +1,256 @@
+#storage@1
+
+---
+
+## Purpose
+
+The `storage@1` stack enables recipes to declare storage conditions and duration for prepared dishes, with optional leftovers and reheating guidance.
+
+This stack is adoption-first: storage can be declared with minimal information, or extended with detailed leftovers and reheating instructions.
+
+---
+
+## Requirements
+
+A document that declares `storage@1`:
+
+• MUST satisfy all structural rules enabled by this stack.
+• MUST satisfy the semantic rules described below.
+
+---
+
+## Data Model
+
+When `storage@1` is declared, the document MUST include a top-level `storage` object.
+
+### Storage Object
+
+The `storage` object MUST include exactly one of:
+• `roomTemp`: storage at room temperature
+• `refrigerated`: storage in refrigeration
+• `frozen`: storage in freezing conditions
+
+Each storage method is a `storageMethod` object with:
+• `duration` (required): ISO 8601 duration string (pattern `^P`)
+• `notes` (optional): string
+• `metadata` (optional): object
+
+### Leftovers and Reheating
+
+The `storage` object MAY include an optional `leftovers` field for leftovers and reheating guidance.
+
+---
+
+## Leftovers and Reheating
+
+The `leftovers` object supports:
+
+• `notes` (optional): string with general guidance
+• `reheat` (optional): array of reheating instructions (see below)
+• `portioning` (optional): portion guidance object
+
+### Reheat Field
+
+The `reheat` field supports two formats:
+
+#### Simple (Array of Strings)
+
+An array of freeform string instructions:
+
+```json
+{
+  "storage": {
+    "refrigerated": {
+      "duration": { "iso8601": "P4D" }
+    },
+    "leftovers": {
+      "notes": "Store in an airtight container.",
+      "reheat": [
+        "Microwave 2–3 minutes, stirring halfway.",
+        "Or warm in a skillet over medium heat with a splash of water."
+      ]
+    }
+  }
+}
+```
+
+#### Structured (Array of Objects)
+
+An array of structured reheating instruction objects:
+
+```json
+{
+  "storage": {
+    "frozen": {
+      "duration": { "iso8601": "P2M" }
+    },
+    "leftovers": {
+      "portioning": { "notes": "Cool completely, then portion into containers." },
+      "reheat": [
+        {
+          "method": "microwave",
+          "duration": { "minMinutes": 2, "maxMinutes": 3 },
+          "notes": "Stir halfway."
+        },
+        {
+          "method": "oven",
+          "temp": { "value": 350, "unit": "F" },
+          "notes": "Cover and heat until hot throughout."
+        }
+      ]
+    }
+  }
+}
+```
+
+### Reheat Instruction Object
+
+Each structured reheating instruction includes:
+
+• `method` (required): string describing the reheating method (freeform in v1)
+• `temp` (optional): object with `value` (number) and `unit` ("F" or "C")
+• `duration` (optional): object with `minMinutes` and/or `maxMinutes` (integers >= 0)
+• `notes` (optional): string
+
+### Reheat Duration
+
+The `duration` object supports:
+• `minMinutes` (optional): integer >= 0
+• `maxMinutes` (optional): integer >= 0
+• At least one of `minMinutes` or `maxMinutes` must be present
+
+If both are present, `minMinutes` should be <= `maxMinutes` (semantic validation may enforce this in tooling).
+
+### Portioning
+
+The `portioning` object includes:
+• `notes` (required): string with portioning guidance
+• `recommendedPortion` (optional): object with `quantity` (number) and `unit` (string)
+
+---
+
+## Semantics
+
+### Storage Methods
+
+Storage methods (`roomTemp`, `refrigerated`, `frozen`) are mutually exclusive. Exactly one must be present.
+
+### Reheat Method
+
+The `method` field in structured reheating instructions is freeform in v1. Consumers may map common values (e.g., "microwave", "oven", "stovetop") to display or planning features, but validation does not enforce specific values.
+
+### Scaling
+
+If no scaling factor exists in the document, leftovers guidance does not change. Leftovers guidance is not scaled by recipe scale factors.
+
+---
+
+## Composition
+
+The storage stack is composable with other stacks:
+
+• No hard dependency on other stacks
+• Remains monotonic: does not close objects needed by other stacks
+• `leftovers` is optional even when the stack is present
+
+---
+
+## Semantic Validation Rules (Normative)
+
+Validators MUST enforce the following rules:
+
+1. Storage method requirement
+   The `storage` object MUST include exactly one of `roomTemp`, `refrigerated`, or `frozen`.
+
+2. Duration requirement
+   Each storage method object MUST include a `duration` field.
+
+3. Reheat instruction method requirement
+   If `leftovers.reheat` includes structured instruction objects, each object MUST include a `method` field.
+
+4. Reheat duration validation
+   If a `reheatInstruction.duration` includes both `minMinutes` and `maxMinutes`, `minMinutes` SHOULD be <= `maxMinutes` (tooling may warn but not fail validation).
+
+---
+
+## Examples
+
+Minimal storage
+
+```json
+{
+  "storage": {
+    "refrigerated": {
+      "duration": { "iso8601": "P3D" }
+    }
+  }
+}
+```
+
+Storage with simple leftovers
+
+```json
+{
+  "storage": {
+    "refrigerated": {
+      "duration": { "iso8601": "P4D" }
+    },
+    "leftovers": {
+      "notes": "Store in an airtight container.",
+      "reheat": [
+        "Microwave 2–3 minutes, stirring halfway.",
+        "Or warm in a skillet over medium heat with a splash of water."
+      ]
+    }
+  }
+}
+```
+
+Storage with structured reheating
+
+```json
+{
+  "storage": {
+    "frozen": {
+      "duration": { "iso8601": "P2M" }
+    },
+    "leftovers": {
+      "portioning": { "notes": "Cool completely, then portion into containers." },
+      "reheat": [
+        {
+          "method": "microwave",
+          "duration": { "minMinutes": 2, "maxMinutes": 3 },
+          "notes": "Stir halfway."
+        },
+        {
+          "method": "oven",
+          "temp": { "value": 350, "unit": "F" },
+          "notes": "Cover and heat until hot throughout."
+        }
+      ]
+    }
+  }
+}
+```
+
+Storage with portioning
+
+```json
+{
+  "storage": {
+    "refrigerated": {
+      "duration": { "iso8601": "P5D" }
+    },
+    "leftovers": {
+      "portioning": {
+        "notes": "Portion into individual servings before storing.",
+        "recommendedPortion": {
+          "quantity": 1,
+          "unit": "cup"
+        }
+      }
+    }
+  }
+}
+```
+

package/spec/stacks/structured.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/structured.schema.json",
+  "title": "Structured Stack",
+  "type": "object",
+  "properties": {
+    "instructions": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/step" },
+          { "$ref": "#/$defs/stepSection" }
+        ]
+      }
+    }
+  },
+  "required": ["instructions"],
+  "$defs": {
+    "step": {
+      "allOf": [
+        { "$ref": "../defs/entities.schema.json#/$defs/StepBase" },
+        { "required": ["id"] }
+      ]
+    },
+    "stepSection": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "steps": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/step" },
+              { "$ref": "#/$defs/stepSection" }
+            ]
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["section", "steps"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/spec/stacks/structured@1.md

@@ -0,0 +1,24 @@
+# structured@1
+
+## Purpose
+The `structured@1` stack requires that instruction steps are structured objects with stable IDs, enabling cross-referencing, timing, and programmatic manipulation.
+
+## Adds
+- Top-level `instructions` array with structured step objects containing `id` and `text` fields.
+- Steps may include `dependsOn`, `inputs`, `techniqueIds`, `usesEquipment`, `temperature`, `timing`, `images`, `videos`, and `metadata`.
+- Support for nested step sections.
+
+## Requires
+- None
+
+## Semantics
+- MUST: Each step object must include `id` and `text` fields.
+- MUST: Step IDs must be unique within the instructions array.
+- NOTE: This stack is a prerequisite for `timed@1` and `referenced@1`.
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: Required by `timed@1` and `referenced@1`. Enables equipment references when combined with `equipment@1`.
+
+
+

package/spec/stacks/substitutions.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/substitutions.schema.json",
+  "title": "Substitutions Stack",
+  "type": "object",
+  "properties": {
+    "substitutions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "for": { "type": "string" },
+          "alternatives": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "ratio": { "type": "string" },
+                "metadata": { "type": "object", "additionalProperties": true }
+              },
+              "required": ["name", "ratio"],
+              "additionalProperties": false,
+              "patternProperties": {
+                "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+              }
+            },
+            "minItems": 1
+          },
+          "metadata": { "type": "object", "additionalProperties": true }
+        },
+        "required": ["for", "alternatives"],
+        "additionalProperties": false,
+        "patternProperties": {
+          "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+        }
+      },
+      "minItems": 1
+    }
+  },
+  "required": ["substitutions"],
+  "additionalProperties": false
+}

package/spec/stacks/substitutions@1.md

@@ -0,0 +1,24 @@
+# substitutions@1
+
+## Purpose
+The `substitutions@1` stack enables recipes to declare ingredient substitutions with alternatives and ratios.
+
+## Adds
+- Top-level `substitutions` array with substitution objects.
+- Each substitution includes `for` (ingredient ID) and `alternatives` array.
+- Each alternative includes `name` and `ratio` fields.
+
+## Requires
+- `referenced@1`
+
+## Semantics
+- MUST: The `for` field must reference an ingredient ID that exists in the ingredients array.
+- MUST: Each substitution must include at least one alternative.
+- NOTE: This stack requires `referenced@1` to ensure ingredient IDs are available for reference.
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: Requires `referenced@1` for ingredient ID resolution. Substitutions are informational and do not affect recipe structure.
+
+
+

package/spec/stacks/techniques.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/techniques.schema.json",
+  "title": "Techniques Stack",
+  "type": "object",
+  "properties": {
+    "techniques": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "metadata": { "type": "object", "additionalProperties": true }
+        },
+        "required": ["id", "name"],
+        "additionalProperties": false,
+        "patternProperties": {
+          "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+        }
+      },
+      "minItems": 1
+    }
+  },
+  "required": ["techniques"],
+  "additionalProperties": false
+}

package/spec/stacks/techniques@1.md

@@ -0,0 +1,23 @@
+# techniques@1
+
+## Purpose
+The `techniques@1` stack enables recipes to declare cooking techniques used in the recipe, with optional descriptions.
+
+## Adds
+- Top-level `techniques` array with technique objects.
+- Each technique includes `id` and `name` fields, with optional `description` and `metadata`.
+
+## Requires
+- None
+
+## Semantics
+- MUST: The `techniques` array must contain at least one technique.
+- MUST: Each technique must include `id` and `name` fields.
+- NOTE: Technique IDs may be referenced in step `techniqueIds` arrays when `structured@1` is present.
+
+## Composition Notes
+- This stack is monotonic: it adds requirements or fields without removing expressiveness.
+- Interaction: Works with `structured@1` to enable step-level technique references. No hard dependencies on other stacks.
+
+
+

package/spec/stacks/timed.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/stacks/timed.schema.json",
+  "title": "Timed Stack",
+  "type": "object",
+  "properties": {
+    "instructions": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          { "$ref": "#/$defs/timedStep" },
+          { "$ref": "#/$defs/timedStepSection" }
+        ]
+      }
+    }
+  },
+  "required": ["instructions"],
+  "allOf": [
+    { "$ref": "./structured.schema.json" }
+  ],
+  "$defs": {
+    "timedStep": {
+      "allOf": [
+        { "$ref": "../defs/entities.schema.json#/$defs/StepBase" },
+        {
+          "properties": {
+            "timing": {
+              "allOf": [
+                { "$ref": "../defs/entities.schema.json#/$defs/StepBase/properties/timing" },
+                { "required": ["activity"], "anyOf": [ { "required": ["duration"] }, { "required": ["completionCue"] } ] }
+              ]
+            }
+          },
+          "required": ["id", "timing"]
+        }
+      ]
+    },
+    "timedStepSection": {
+      "type": "object",
+      "properties": {
+        "section": { "type": "string" },
+        "steps": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "$ref": "#/$defs/timedStep" },
+              { "$ref": "#/$defs/timedStepSection" }
+            ]
+          }
+        },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["section", "steps"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "../defs/common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  }
+}

package/spec/stacks/timed@1.md

@@ -0,0 +1,23 @@
+# timed@1
+
+## Purpose
+The `timed@1` stack enables recipes to include timing information for steps, supporting scheduling and time-based planning.
+
+## Adds
+- Step objects must include a `timing` field with `activity` (active/passive) and either `duration` or `completionCue`.
+- Timing may include duration ranges (minMinutes/maxMinutes) or completion cues.
+
+## Requires
+- `structured@1`
+
+## Semantics
+- MUST: Each step must include a `timing` object with `activity` field.
+- MUST: Each timing object must include either `duration` or `completionCue`.
+- 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 `compute@1` for deterministic scheduling. Works with `quantified@1` for computational recipe planning.
+
+
+

package/src/defs/common.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/defs/common.schema.json",
+  "title": "Common definitions for Soustack",
+  "type": "object",
+  "properties": {
+    "stackId": {
+      "type": "string",
+      "anyOf": [
+        {
+          "enum": [
+            "quantified@1",
+            "structured@1",
+            "timed@1",
+            "referenced@1",
+            "compute@1",
+            "storage@1",
+            "dietary@1",
+            "substitutions@1",
+            "techniques@1",
+            "illustrated@1",
+            "scaling@1",
+            "nutrition@1"
+          ]
+        },
+        {
+          "pattern": "^x-[A-Za-z0-9_-]+@[0-9]+$",
+          "description": "Extension stacks must use x- prefix and include a major version"
+        }
+      ]
+    },
+    "extensionLane": {
+      "type": "string",
+      "pattern": "^x-[A-Za-z0-9_-]+$"
+    },
+    "extensionLaneValue": {
+      "description": "Accept any JSON value for extension lanes while keeping the top-level property name constrained.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "uri": {
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "additionalProperties": false
+}

package/src/defs/duration.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://soustack.spec/defs/duration.schema.json",
+  "title": "Durations",
+  "type": "object",
+  "properties": {
+    "DurationMinutes": {
+      "type": "object",
+      "properties": {
+        "minutes": { "type": "number", "exclusiveMinimum": 0 },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["minutes"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "./common.schema.json#/properties/extensionLaneValue" }
+      }
+    },
+    "StorageDuration": {
+      "type": "object",
+      "properties": {
+        "iso8601": { "type": "string", "pattern": "^P" },
+        "metadata": { "type": "object", "additionalProperties": true }
+      },
+      "required": ["iso8601"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": { "$ref": "./common.schema.json#/properties/extensionLaneValue" }
+      }
+    }
+  },
+  "additionalProperties": false
+}