@soustack/spec 0.0.2

package/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/README.md

@@ -0,0 +1,275 @@
+
+# Soustack Specification
+
+**Soustack** is an open standard for representing recipes as **structured, interoperable, and computational data**.
+
+The goal of Soustack is **universal adoption**: recipes should be publishable with minimal friction, while enabling progressively more powerful capabilities such as scaling, timing, scheduling, and rich UI rendering.
+
+This repository defines the **normative specification**:
+
+* JSON Schemas
+* Profiles (adoption ladder)
+* Stack contracts
+* Conformance rules
+* Validation fixtures
+
+Runtime behavior lives in **soustack-core**.
+UI and integrations live in **Soustack Blocks**.
+
+---
+
+## What Soustack Is (and Is Not)
+
+**Soustack is:**
+
+* A stable, versioned recipe data standard
+* Designed for incremental adoption
+* Built to support *computational* recipes (not just descriptive ones)
+* The source of truth for validation and conformance
+
+**Soustack is not:**
+
+* A recipe app
+* A hosted service
+* A runtime library
+* A CMS or database schema
+
+> **The format is the product.** Everything else is derived.
+
+---
+
+## Adoption Philosophy
+
+Soustack is designed around **incremental compliance**, not all-or-nothing adoption: publishers can start at **Lite** with minimal structure, move to **Base** by adding `yield` and `time`, and then opt into stack-backed profiles like **Timed**, **Scalable**, or **Illustrated** as they add structure—without changing the overall document shape.
+
+---
+
+## Profiles (Public Contract)
+
+**Profiles** are the human-facing compatibility levels a publisher or consumer can claim.
+
+Examples:
+
+* “We publish **Base** Soustack”
+* “This site supports **Scalable** recipes”
+* “Our embed works for **Timed** recipes”
+
+Profiles define:
+
+* what fields must exist
+* what guarantees consumers can rely on
+
+Profiles are defined normatively in **SPEC.md**.
+
+### Common Profiles
+
+| Profile                       | Purpose                                |
+| ----------------------------- | -------------------------------------- |
+| Lite                          | Lowest-friction publishing             |
+| Base                          | Minimum cookable baseline              |
+| Timed                         | Step-level timing                      |
+| Scalable                      | Interoperable scaling rules            |
+| Illustrated                   | Media present                          |
+| Equipped                      | Required tools/equipment               |
+| Prepped                       | Prep guidance and/or mise en place      |
+
+---
+
+## Stacks (Enforcement Mechanism)
+
+**Stacks** are the composable capability contracts that implement profiles.
+
+They:
+
+* activate additional schema and semantic rules
+* are declared explicitly in recipe documents
+* are versioned independently
+
+Example:
+
+```json
+{
+  "profile": "scalable",
+  "stacks": { "quantified": 1, "scaling": 1 },
+  "yield": { "amount": 4, "unit": "servings" },
+  "time": { "total": { "minutes": 30 } }
+}
+```
+
+Stacks are **machine-facing**.
+Profiles are **human-facing**.
+
+---
+
+## Stack Versioning (`@1`)
+
+Stacks are versioned using the syntax:
+
+```
+<stack-name>@<major>
+```
+
+Example:
+
+* `quantified@1`
+* `scaling@1`
+* `timed@1`
+
+### Important Rules
+
+* **`@1` appears only in stack declarations and contract names**
+* Schema filenames are **version-agnostic**
+* Schema `$id`s are **version-agnostic**
+* `$ref`s are **version-agnostic**
+
+Versioning applies to the **contract**, not the implementation file.
+
+This allows:
+
+* safe evolution of stack semantics
+* future `@2` stacks without breaking existing recipes
+* stable schema paths for tooling
+
+---
+
+## Scaling (Why Soustack Exists)
+
+Soustack explicitly supports **interoperable recipe scaling**, including cases where simple multipliers fail.
+
+The `scaling@1` stack standardizes:
+
+* linear scaling
+* fixed ingredients
+* discrete items (e.g. eggs)
+* “to taste” quantities
+* baker’s percentages
+
+This ensures two independent implementations scale the same recipe the same way.
+
+Scaling semantics are defined normatively in the spec and implemented in **soustack-core**.
+
+---
+
+## Repository Structure
+
+```
+.
+├── soustack.schema.json      # Root schema
+├── SPEC.md                   # Normative specification
+├── README.md                 # This file
+├── defs/                     # Reusable schema definitions
+├── stacks/                   # Stack schemas (version-agnostic filenames)
+├── fixtures/                 # Valid/invalid conformance fixtures
+├── scripts/                  # Validation & policy scripts
+└── .github/workflows/        # CI validation
+```
+
+---
+
+## Validation & Conformance
+
+This repository provides:
+
+* JSON Schema validation
+* semantic validation (DAGs, references, scaling rules)
+* fixtures that define expected behavior
+
+### Local Validation
+
+```bash
+npm install
+npm test
+```
+
+This runs:
+
+1. policy guards
+2. schema reference resolution
+3. fixture validation
+
+If `npm test` passes, the spec is internally consistent.
+
+---
+
+## Relationship to Other Repos
+
+* **soustack-spec**
+  The authoritative definition of the standard.
+
+* **soustack-core**
+  Runtime implementation: validation, scaling, Schema.org conversion, scraping.
+
+* **Soustack Blocks**
+  UI and integration packages that drive adoption:
+
+  * embeds
+  * web components
+  * CMS/framework adapters
+  * conformance badges
+
+The spec is the source of truth. All other repos consume it.
+
+---
+
+## Stability Guarantees
+
+* Backwards-compatible evolution is preferred
+* Breaking changes require a new major stack version (`@2`)
+* Existing stack contracts (`@1`) will not be silently broken
+* Migration and canonicalization belong in **soustack-core**, not the spec
+
+---
+
+## Contributing
+
+Contributions should:
+
+* preserve incremental adoption
+* avoid adding complexity to Lite/Base
+* respect stack versioning rules
+* include fixtures for new behavior
+
+If in doubt, **opt for clarity over cleverness**.
+
+> **Note:** Do not commit `dist/`; it is build output. The `prepack` script builds it automatically before npm publishing.
+
+---
+
+## License
+
+MIT
+
+
+<!-- BEGIN GENERATED: STACK REGISTRY -->
+
+## Profiles
+
+| Profile | Requires Profiles | Requires Stacks | Description |
+| ------- | ---------------- | -------------- | ----------- |
+| **Base** | lite | — | Minimum cookable baseline with yield + time |
+| **Equipped** | base | equipment | Recipe declares required tools/equipment. |
+| **Illustrated** | base | illustrated | Media present |
+| **Lite** | — | — | Lowest-friction publishing with minimal structure |
+| **Prepped** | base | prep | Recipe includes prep guidance and/or mise en place tasks. |
+| **Scalable** | base | quantified, scaling | Quantified + scaling |
+| **Timed** | base | structured, timed | Structured + timed |
+
+## Stacks
+
+| Stack ID | Latest Major | Requires | Required by Profiles | Schema | Docs |
+| -------- | ----------- | -------- | -------------------- | ------ | ---- |
+| **compute** | 1 | quantified, timed | — | `stacks/compute.schema.json` | `stacks/compute@1.md` |
+| **dietary** | 1 | — | — | `stacks/dietary.schema.json` | `stacks/dietary@1.md` |
+| **equipment** | 1 | — | equipped | `stacks/equipment.schema.json` | `stacks/equipment@1.md` |
+| **illustrated** | 1 | — | illustrated | `stacks/illustrated.schema.json` | `stacks/illustrated@1.md` |
+| **prep** | 1 | — | prepped | `stacks/prep.schema.json` | `stacks/prep@1.md` |
+| **quantified** | 1 | — | scalable | `stacks/quantified.schema.json` | `stacks/quantified@1.md` |
+| **referenced** | 1 | structured | — | `stacks/referenced.schema.json` | `stacks/referenced@1.md` |
+| **scaling** | 1 | quantified | scalable | `stacks/scaling.schema.json` | `stacks/scaling@1.md` |
+| **storage** | 1 | — | — | `stacks/storage.schema.json` | `stacks/storage@1.md` |
+| **structured** | 1 | — | timed | `stacks/structured.schema.json` | `stacks/structured@1.md` |
+| **substitutions** | 1 | referenced | — | `stacks/substitutions.schema.json` | `stacks/substitutions@1.md` |
+| **techniques** | 1 | — | — | `stacks/techniques.schema.json` | `stacks/techniques@1.md` |
+| **timed** | 1 | structured | timed | `stacks/timed.schema.json` | `stacks/timed@1.md` |
+
+<!-- END GENERATED: STACK REGISTRY -->

package/SOUSTACK_SPEC_VERSION

@@ -0,0 +1 @@
+0.0.2

package/SPEC.md

@@ -0,0 +1,226 @@
+# Soustack Specification
+
+## 1. Scope and Purpose
+
+Soustack is an open specification for representing recipes as structured, interoperable, and progressively computable data.
+
+The primary design goal of this specification is **universal adoption**: recipes should be publishable with minimal friction, while enabling increasingly powerful capabilities (scaling, timing, scheduling, visualization) as structure is added.
+
+Soustack achieves this by defining:
+
+* a small, stable core document shape
+* **Profiles** as human-facing conformance targets
+* **Stacks** as machine-enforced capability requirements
+* semantic validation rules that ensure interoperability beyond JSON Schema alone
+
+This document is **normative** unless otherwise noted.
+
+---
+
+## 2. Terminology
+
+* **Document**: A JSON object conforming to the Soustack root schema.
+* **Profile**: A named, human-facing conformance target describing what a consumer may rely on.
+* **Stack**: A declared capability that activates additional structural and/or semantic requirements.
+* **Conformance**: Passing both schema validation and all required semantic checks.
+* **Badge**: A derived, informative label emitted by tooling based on observed conformance.
+
+---
+
+## 3. Profiles (Normative)
+
+Profiles are the **primary public contract** of the Soustack specification.
+
+A Profile defines a bundle of requirements expressed in terms of:
+
+* required `stacks`
+* required semantic validation rules
+
+Profiles support an **adoption ladder**: publishers can start at **Lite** with minimal structure, move to **Base** by adding `yield` and `time`, and then opt into stack-backed profiles like **Timed**, **Scalable**, or **Illustrated** as they add structure—without changing the overall document shape.
+
+### 3.1 Profile Declaration
+
+* A document MAY declare a profile explicitly using a top-level `profile` field. The field is OPTIONAL; omission MUST NOT change document validity.
+* Tools MAY infer the profile from declared `stacks` and required core fields when `profile` is absent.
+* `profile` is a single primary claim (no arrays or multi-profile declarations).
+* If a document declares both a `profile` and explicit `stacks`, they MUST NOT contradict. Contradictions MUST be treated as non-conformant.
+
+### 3.2 Stack Semantics
+
+If a document declares a stack in the `stacks` map (e.g., `"stacks": { "timed": 1 }`), it MUST satisfy all requirements of that stack as defined by this specification.
+
+Stacks that impose no additional structural or semantic requirements are not permitted in future major versions.
+
+---
+
+## 4. Profile Definitions
+
+### Profile: Lite
+
+**Purpose:** Lowest-friction publishing and ingestion.
+
+**Requirements**
+
+* No additional requirements beyond the core schema.
+
+**Guarantees**
+
+* Valid Soustack container structure.
+* Ingredients and instructions MAY be unstructured strings.
+
+---
+
+### Profile: Base
+
+**Purpose:** Minimum cookable baseline.
+
+**Requirements**
+
+* `yield` and `time` MUST be present.
+
+**Guarantees**
+
+* Document includes `yield` and `time`.
+
+---
+
+### Profile: Illustrated
+
+**Purpose:** Visually rich, embeddable recipes.
+
+**Requirements**
+
+* `stacks.illustrated` MUST be `1`.
+
+**Semantic Requirements**
+
+* At least one media item MUST be present at the recipe or step level.
+
+---
+
+### Profile: Equipped
+
+**Purpose:** Declare required tools/equipment.
+
+**Requirements**
+
+* `stacks.equipment` MUST be `1`.
+
+---
+
+### Profile: Prepped
+
+**Purpose:** Prep guidance and/or mise en place tasks.
+
+**Requirements**
+
+* `stacks.prep` MUST be `1`.
+
+---
+
+### Profile: Timed
+
+**Purpose:** Step-level timing.
+
+**Requirements**
+
+* `stacks.structured` MUST be `1` and `stacks.timed` MUST be `1`.
+
+---
+
+### Profile: Scalable
+
+**Purpose:** Interoperable scaling.
+
+**Requirements**
+
+* `stacks.quantified` MUST be `1` and `stacks.scaling` MUST be `1`.
+
+**Semantic Requirements**
+
+* Baker's percentage references MUST resolve to declared ingredient ids.
+* Discrete scaling ranges MUST have `min` less than or equal to `max`.
+
+---
+
+## 5. Stacks
+
+Stacks define capability-specific structural and semantic requirements. Each stack is versioned and defined in its own schema and documentation.
+
+High-value optional stacks include `equipment@1` for declaring required equipment with scaling-aware counts and step-level usage references.
+
+---
+
+## 6. Semantic Validation
+
+In addition to schema validation, conforming tools MUST enforce semantic rules, including but not limited to:
+
+* ID uniqueness
+* Reference resolution
+* Dependency graph acyclicity
+* Timing coherence
+
+---
+
+## 7. Derived Badges (Informative)
+
+Validators MAY emit derived badges such as:
+
+* **Computable**
+* **Scalable**
+
+Badges are informative and do not replace profile conformance.
+
+---
+
+## 8. Versioning
+
+This specification uses semantic versioning. Schema identifiers and conformance rules are versioned and MUST be treated as immutable once published.
+
+---
+
+## 9. Non-Normative Notes
+
+Non-normative guidance, examples, and adoption notes MAY be published separately and are not part of this specification.
+
+### 9.1 Legacy Namespace
+
+**Note:** This section is non-normative.
+
+The canonical host for Soustack schema identifiers and references is `https://spec.soustack.org`. The previous host `https://soustack.spec` is legacy and MUST NOT be used for new identifiers or references. Implementations should use `https://spec.soustack.org` for all schema resolution and validation.
+
+
+
+<!-- BEGIN GENERATED: STACK REGISTRY -->
+
+## Profiles
+
+| Profile | Requires Profiles | Requires Stacks | Description |
+| ------- | ---------------- | -------------- | ----------- |
+| **Base** | lite | — | Minimum cookable baseline with yield + time |
+| **Equipped** | base | equipment | Recipe declares required tools/equipment. |
+| **Illustrated** | base | illustrated | Media present |
+| **Lite** | — | — | Lowest-friction publishing with minimal structure |
+| **Prepped** | base | prep | Recipe includes prep guidance and/or mise en place tasks. |
+| **Scalable** | base | quantified, scaling | Quantified + scaling |
+| **Timed** | base | structured, timed | Structured + timed |
+
+## Stacks
+
+| Stack ID | Latest Major | Requires | Required by Profiles | Schema | Docs |
+| -------- | ----------- | -------- | -------------------- | ------ | ---- |
+| **compute** | 1 | quantified, timed | — | `stacks/compute.schema.json` | `stacks/compute@1.md` |
+| **dietary** | 1 | — | — | `stacks/dietary.schema.json` | `stacks/dietary@1.md` |
+| **equipment** | 1 | — | equipped | `stacks/equipment.schema.json` | `stacks/equipment@1.md` |
+| **illustrated** | 1 | — | illustrated | `stacks/illustrated.schema.json` | `stacks/illustrated@1.md` |
+| **prep** | 1 | — | prepped | `stacks/prep.schema.json` | `stacks/prep@1.md` |
+| **quantified** | 1 | — | scalable | `stacks/quantified.schema.json` | `stacks/quantified@1.md` |
+| **referenced** | 1 | structured | — | `stacks/referenced.schema.json` | `stacks/referenced@1.md` |
+| **scaling** | 1 | quantified | scalable | `stacks/scaling.schema.json` | `stacks/scaling@1.md` |
+| **storage** | 1 | — | — | `stacks/storage.schema.json` | `stacks/storage@1.md` |
+| **structured** | 1 | — | timed | `stacks/structured.schema.json` | `stacks/structured@1.md` |
+| **substitutions** | 1 | referenced | — | `stacks/substitutions.schema.json` | `stacks/substitutions@1.md` |
+| **techniques** | 1 | — | — | `stacks/techniques.schema.json` | `stacks/techniques@1.md` |
+| **timed** | 1 | structured | timed | `stacks/timed.schema.json` | `stacks/timed@1.md` |
+
+<!-- END GENERATED: STACK REGISTRY -->

package/defs/common.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spec.soustack.org/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
+}