@texuli/spec 0.3.0 → 0.5.0

package/README.md

@@ -14,9 +14,17 @@ by Texuli's Kotlin Multiplatform twin. The package is framework-free: no
 DOM, no Svelte, no Node APIs and no runtime dependencies.
 
 > **Status: 0.x release.** Texuli is in development. The packages are
-> published to npm as `0.3.0`, a pre-1.0 release (1.0.0 will be the first
-> stable release). Under 0.x, a new minor (`0.4.0`) may contain breaking
-> changes, so pin the exact version or use `^0.3.0`, which accepts only 0.3.x.
+> published to npm as `0.5.0`, a pre-1.0 release (1.0.0 will be the first
+> stable release). Under 0.x, a new minor (`0.6.0`) may contain breaking
+> changes, so pin the exact version or use `^0.5.0`, which accepts only 0.5.x.
+
+> **New in `0.4.0`.** `@texuli/spec@0.4.0` carries **spec 0.4.0**: spec
+> 0.3.0 (state, bindings, closed actions, `reorder`, workflow graphs), spec
+> 0.4.0 (deck model v2 on `layout-deck` and `deck-slide`, below) and the
+> `workflow`, `migrate` and `surface` subpaths described below.
+> `@texuli/spec@0.3.0` carried spec 0.2.0 and only the root and `codegen`
+> subpaths
+> ([RELEASE](https://github.com/DailybotHQ/texuli/blob/main/docs/RELEASE.md)).
 
 ## Install
 
@@ -48,7 +56,7 @@ import {
   validateInstance,
 } from '@texuli/spec';
 
-SPEC_VERSION;                         // the spec version, e.g. '0.2.0'
+SPEC_VERSION;                         // the spec version: '0.5.0' in @texuli/spec@0.5.0 ('0.4.0' in @texuli/spec@0.4.0)
 SPEC_COMPONENT_IDS.includes('alert'); // true: the closed component vocabulary
 
 // The dialect validator: a closed subset of JSON Schema 2020-12.
@@ -68,31 +76,51 @@ const digest = sha256(canonicalJson({ b: 1, a: [true, null] }));
 
 To check a whole blueprint, pass the blueprint schema and catalog documents
 from the repository's `packages/spec/schemas/blueprint.schema.json` and
-`packages/spec/catalog/components.json`:
+`packages/spec/catalog/components.json`. Workflow graphs and migrations
+are opt-in subpaths, so the root stays small: a host that renders workflow
+graphs passes `schemas/workflow.schema.json` and `validateWorkflowGraph`
+from `@texuli/spec/workflow` (without both, a `workflow` state variable or
+a `workflowGraph` prop fails closed), and a host that reads older
+envelopes runs `migrateBlueprint` from `@texuli/spec/migrate` first:
 
 ```ts
 import { type Schema, type SpecCatalog, validateBlueprint } from '@texuli/spec';
+import { migrateBlueprint } from '@texuli/spec/migrate';
+import { validateWorkflowGraph } from '@texuli/spec/workflow';
 
-const result = validateBlueprint(blueprint, {
+const migrated = migrateBlueprint(blueprint); // 0.2.0 → 0.3.0 → 0.4.0 → 0.5.0; never throws
+const result = validateBlueprint(migrated.blueprint, {
   blueprintSchema: blueprintSchemaJson as Schema,
   catalog: componentsJson as SpecCatalog,
+  workflowSchema: workflowSchemaJson as Schema, // only for workflow graphs
+  validateWorkflowGraph, // only for workflow graphs
 });
 if (!result.ok) {
   for (const d of result.diagnostics) console.warn(d.code, d.path, d.message);
 }
+for (const w of result.warnings ?? []) console.info(w.code, w.path); // `deprecated`
 ```
 
-A node with an id outside the catalog fails with `unknown-id`; other codes
-include `schema`, `unknown-prop`, `prop-type`, `enum-value`,
+A node with an id outside the catalog fails with `unknown-id`. The other
+codes are `schema`, `unknown-prop`, `prop-type`, `enum-value`,
 `missing-required`, `extension-prop`, `catalog-mismatch`,
-`unsupported-profile` and `unknown-slot`.
+`unsupported-profile`, `unknown-slot`, and, from spec 0.3.0, `state` (a
+refused state or flow declaration), `unknown-state` (a binding or action
+names no declared variable), `binding` (a malformed, misplaced, read-only or
+ill-fitting binding), `action` (an action with the wrong fields or target),
+`unknown-event` (an `on` key the component does not fire) and `workflow` (a
+workflow graph rule). Deprecated components and props add a `deprecated`
+warning without failing.
 
 ## What's inside
 
 | Subpath | Purpose | Headline exports |
 | --- | --- | --- |
-| `@texuli/spec` | Runtime: types, vocabulary, validation, hashing | `BlueprintEnvelope`, `SpecCatalog`, `SpecValidation` and the other generated types; `SPEC_COMPONENT_IDS`, `SpecComponentProps`, `SPEC_CATALOG_HASH`, `SPEC_VERSION`; `validateBlueprint`, `validateTree`, `validateInstance`, `checkSchemaDocument`; `canonicalJson`, `sha256` |
-| `@texuli/spec/codegen` | Build time: generation and conformance | `buildSpec`, `projectCatalog`, `checkConformance`, `formatJson`, `nextSpecVersion`, `checkVersionHistory` |
+| `@texuli/spec` | Runtime: types, vocabulary, validation, hashing | `BlueprintEnvelope`, `SpecCatalog`, `SpecValidation`, `WorkflowGraph` and the other generated types; `SPEC_COMPONENT_IDS`, `SpecComponentProps`, `SPEC_CATALOG_HASH`, `SPEC_VERSION`; `validateBlueprint`, `validateTree`, `validateInstance`, `checkSchemaDocument`; the contract constants (`SPEC_ACTION_OPS`, `SPEC_EVENT_NAMES`, `SPEC_STATE_TYPES`, `SPEC_LIMITS`, `SPEC_PATTERNS`, `ACTION_FIELDS`); `canonicalJson`, `sha256` |
+| `@texuli/spec/workflow` | Runtime, opt-in: workflow graph validation | `validateWorkflowGraph` (pass it in `SpecDocuments.validateWorkflowGraph`) |
+| `@texuli/spec/migrate` | Runtime, opt-in: envelope migrations | `migrateBlueprint`, `SPEC_MIGRATIONS`, `UNDECLARED_SPEC_VERSION` |
+| `@texuli/spec/surface` | Runtime: the state surface rules every validator shares (no imports) | `checkStateSurface`, `surfaceInputs`, `SPEC_CONTROL_STATE_TYPES`, `SURFACE_PLAYER_CODES`, `LIST_TEXT_PATTERN` |
+| `@texuli/spec/codegen` | Build time: generation and conformance | `buildSpec`, `projectCatalog`, `checkConformance`, `checkCatalogContract`, `formatJson`, `nextSpecVersion`, `checkVersionHistory` |
 
 ## Key guarantees
 
@@ -107,9 +135,36 @@ include `schema`, `unknown-prop`, `prop-type`, `enum-value`,
   refused when you pass `catalogHash`.
 - **Deterministic.** Canonical JSON sorts keys at every depth, and every
   generated file carries the spec version and digest with no timestamps.
+- **Interaction as data, never code.** Spec 0.3.0 adds local state,
+  bindings (`{"$state": name}`, read-only `{"$data": name}`), a closed
+  action set (`setState`, `toggleState`, `moveItem`, `flowGo`, `emit`,
+  `submit`) on a closed event vocabulary, drag as data (`reorder`) and
+  workflow graphs (at most 500 nodes and 2,000 edges). Nothing in a
+  blueprint is evaluated.
+- **Decks as data.** Spec 0.4.0 (ADR-009) gives
+  `layout-deck` and `deck-slide` optional deck model v2 props: the 9:16
+  aspect, the `slide`, `zoom` and `morph` transitions, motion, navigation,
+  outline, a slide `layout` with its `props`, `background`, step labels and
+  component slides. The change is additive: every 0.3.0 envelope is a valid
+  0.4.0 envelope, and the `0.3.0 → 0.4.0` migration only stamps `spec`. The
+  deck model itself is validated by `@texuli/deck`, not by this package.
 - **Structure only.** This validator checks structure. URL policy, tree
   limits and rendering live in the runtime validator of
-  [`@texuli/catalog`](https://www.npmjs.com/package/@texuli/catalog).
+  [`@texuli/catalog`](https://www.npmjs.com/package/@texuli/catalog). The
+  reducers that run the actions belong to the runtime
+  ([`@texuli/player`](https://www.npmjs.com/package/@texuli/player)), which
+  runs every 0.3.0 action from `0.4.0`).
+- **A blueprint that validates paints.** The state surface rules
+  (`@texuli/spec/surface`) refuse exactly what the player refuses at paint
+  time: form fields and submits outside an `action-form`, nested forms,
+  controls and fields that name no declared variable of their type, flow
+  nodes without a matching view or event, and writers of a host-bound
+  variable. The spec, `@texuli/catalog`'s `validateDraft` and the Kotlin
+  twin run the same rules.
+- **List item text never hides or reorders itself.** String fields of list
+  state items refuse control characters, bidirectional overrides and
+  isolates, and invisible formatting characters (`SPEC_PATTERNS.listText`;
+  ZWNJ and ZWJ stay allowed for scripts and emoji).
 
 ## Versioning
 
@@ -131,8 +186,17 @@ reads. Native (Kotlin) builds compile the generated models from the same
 spec, and their decoders are closed: a blueprint that uses a field from a
 newer spec fails to decode on an older native build with a `schema`
 diagnostic instead of passing silently. A blueprint binds to an exact
-catalog hash today; an envelope field for a compatible spec range, and
-migrations between versions, are planned and not built.
+catalog hash, and from 0.3.0 may declare the exact spec version it was
+written for (`spec`; omitted means 0.2.0). `migrateBlueprint`
+(`@texuli/spec/migrate`) brings an
+envelope up to the current spec with pure, per-version steps
+(`src/migrations/`: `0.2.0 → 0.3.0`, `0.3.0 → 0.4.0` and `0.4.0 → 0.5.0`,
+each of which only stamps `spec`); a compatible version range is planned,
+not built. `@texuli/spec@0.5.0` carries spec `0.5.0`, which adds the
+`data-cohort-table`, `data-notification-inbox`, `data-filter-builder` and
+`time-field` catalog ids; `@texuli/spec@0.4.0` carried spec `0.4.0` (digest
+`fac29f542b16ddb78ab401c508e5b8346f655991c56e25aa811f4931661a8cb3`). Every
+pin is in `versions.json`.
 
 The full rules (the digest, `versions.json` pins, regeneration and the
 conformance harness) are in
@@ -166,3 +230,7 @@ bugs at [github.com/DailybotHQ/texuli/issues](https://github.com/DailybotHQ/texu
 ## License
 
 MIT © Dailybot, Inc.
+
+---
+
+Powered by [Dailybot](https://www.dailybot.com?utm_source=dailybotopensource&utm_medium=texuli-spec).

package/dist/build.d.ts

@@ -24,6 +24,11 @@ export declare const SCHEMA_UNITS: readonly [{
     readonly prefix: "Spec";
     readonly ts: "manifest.ts";
     readonly kt: "Manifest.kt";
+}, {
+    readonly name: "workflow";
+    readonly prefix: "";
+    readonly ts: "workflow.ts";
+    readonly kt: "Workflow.kt";
 }];
 export declare const TS_OUT = "generated/typescript/";
 export declare const KOTLIN_OUT = "generated/kotlin/com/texuli/spec/";

package/dist/build.js

@@ -13,6 +13,7 @@ export const SCHEMA_UNITS = [
     { name: 'catalog', prefix: 'Spec', ts: 'catalog-schema.ts', kt: 'CatalogSchema.kt' },
     { name: 'diagnostics', prefix: 'Spec', ts: 'diagnostics.ts', kt: 'Diagnostics.kt' },
     { name: 'manifest', prefix: 'Spec', ts: 'manifest.ts', kt: 'Manifest.kt' },
+    { name: 'workflow', prefix: '', ts: 'workflow.ts', kt: 'Workflow.kt' },
 ];
 export const TS_OUT = 'generated/typescript/';
 export const KOTLIN_OUT = 'generated/kotlin/com/texuli/spec/';

package/dist/canonical.js

@@ -46,16 +46,25 @@ function encode(value, stack) {
 export function prettyJson(value) {
     return `${JSON.stringify(JSON.parse(canonicalJson(value)), null, 2)}\n`;
 }
-const K = new Uint32Array([
-    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
-    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
-    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
-    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
-    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
-    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
-    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
-    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
-]);
+/**
+ * The fractional part of `p`'s square (`n` 2) or cube (`n` 3) root as a
+ * 32-bit word: the SHA-256 constants (FIPS 180-4 §4.2.2, §5.3.3). Newton
+ * steps on plain IEEE arithmetic, which every runtime computes bit for bit
+ * (`Math.cbrt` and `**` are only approximated); every word sits thousands
+ * of ulps from a truncation boundary, and the test vectors cover all 72.
+ */
+function rootWord(p, n) {
+    let x = 2;
+    for (let i = 0; i < 40; i += 1) {
+        x -= n === 2 ? (x * x - p) / (2 * x) : (x * x * x - p) / (3 * x * x);
+    }
+    return ((x - Math.floor(x)) * 0x100000000) >>> 0;
+}
+const PRIMES = [];
+for (let n = 2; PRIMES.length < 64; n += 1)
+    if (PRIMES.every((p) => n % p))
+        PRIMES.push(n);
+const K = new Uint32Array(PRIMES.map((p) => rootWord(p, 3)));
 /** UTF-8 bytes of a string (no `TextEncoder` needed). */
 function utf8(text) {
     const bytes = [];
@@ -83,9 +92,7 @@ export function sha256(text) {
     for (const word of [high, bitLength >>> 0]) {
         bytes.push((word >>> 24) & 0xff, (word >>> 16) & 0xff, (word >>> 8) & 0xff, word & 0xff);
     }
-    const hash = new Uint32Array([
-        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
-    ]);
+    const hash = new Uint32Array(PRIMES.slice(0, 8).map((p) => rootWord(p, 2)));
     const w = new Uint32Array(64);
     const rotr = (x, n) => (x >>> n) | (x << (32 - n));
     for (let offset = 0; offset < bytes.length; offset += 64) {

package/dist/catalog.d.ts

@@ -3,8 +3,8 @@
  * projection from a built catalog. The projection is the bootstrap step of
  * spec/Compose design §2.3; the parity check reruns it to catch drift.
  */
-import type { SpecCatalog, SpecComponent, SpecProp } from './generated/typescript/catalog-schema.js';
-export type { SpecCatalog, SpecComponent, SpecProp };
+import type { SpecCatalog, SpecComponent, SpecDeprecation, SpecEventName, SpecProp, SpecPropSchema } from './generated/typescript/catalog-schema.js';
+export type { SpecCatalog, SpecComponent, SpecDeprecation, SpecEventName, SpecProp, SpecPropSchema, };
 export declare const CAPABILITIES: readonly ["portable-core", "web-only", "native-only", "unknown"];
 export type Capability = SpecComponent['capability'];
 export type SpecPropKind = SpecProp['kind'];
@@ -24,17 +24,23 @@ export interface BuiltCatalogLike {
         group: string;
         tier: 'app' | 'content';
         emit: readonly string[];
+        events?: readonly SpecEventName[];
+        bindable?: readonly string[];
+        deprecated?: SpecDeprecation;
         props: readonly {
             name: string;
             kind: SpecPropKind;
             required?: boolean;
             enumValues?: readonly string[];
+            schema?: SpecPropSchema;
+            deprecated?: SpecDeprecation;
         }[];
     }[];
 }
 /**
  * Project a built catalog into the spec vocabulary. Deterministic: components
- * sorted by id, props by name, emit tiers sorted. Capability is `unknown`
+ * sorted by id, props by name, emit tiers, events and bindable props sorted;
+ * events, bindable, property schemas and deprecations only when present. Capability is `unknown`
  * unless `capabilities` (the reviewed `catalog/capabilities.json`) records an
  * audited value (ADR-003: no id is portable until audited).
  */

package/dist/catalog.js

@@ -13,7 +13,8 @@ export const WEB_ONLY_KINDS = ['slot', 'event', 'unknown'];
 export const WEB_ONLY_PROP_NAMES = ['class', 'className', 'style', 'renderer'];
 /**
  * Project a built catalog into the spec vocabulary. Deterministic: components
- * sorted by id, props by name, emit tiers sorted. Capability is `unknown`
+ * sorted by id, props by name, emit tiers, events and bindable props sorted;
+ * events, bindable, property schemas and deprecations only when present. Capability is `unknown`
  * unless `capabilities` (the reviewed `catalog/capabilities.json`) records an
  * audited value (ADR-003: no id is portable until audited).
  */
@@ -39,7 +40,12 @@ export function projectCatalog(catalog, catalogHash, capabilities = {}) {
             ...(WEB_ONLY_KINDS.includes(prop.kind) || WEB_ONLY_PROP_NAMES.includes(prop.name)
                 ? { extension: 'web' }
                 : {}),
+            ...(prop.schema ? { schema: prop.schema } : {}),
+            ...(prop.deprecated ? { deprecated: { ...prop.deprecated } } : {}),
         })),
+        ...(entry.events?.length ? { events: [...entry.events].sort() } : {}),
+        ...(entry.bindable?.length ? { bindable: [...entry.bindable].sort() } : {}),
+        ...(entry.deprecated ? { deprecated: { ...entry.deprecated } } : {}),
     }));
     return { catalogHash, components };
 }

package/dist/codegen/index.d.ts

@@ -7,8 +7,8 @@
 export { buildSpec, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, type SpecBuild, TS_OUT, } from '../build.js';
 export { prettyJson } from '../canonical.js';
 export { type BuiltCatalogLike, projectCatalog } from '../catalog.js';
-export { type ConformanceIssue, checkConformance } from '../conformance.js';
+export { type ConformanceIssue, checkCatalogContract, checkConformance, deprecationExpired, } from '../conformance.js';
 export { formatJson, LINE_WIDTH } from '../format.js';
 export { checkVersionHistory, nextSpecVersion, type SpecChangeClass, type SpecVersionHistory, type SpecVersionPin, type VersionIssue, } from '../versioning.js';
-export { KOTLIN_PACKAGE, kotlinString } from './kotlin.js';
+export { KOTLIN_PACKAGE, kotlinProperty, kotlinString } from './kotlin.js';
 export type { SchemaUnit, Stamp } from './shared.js';

package/dist/codegen/index.js

@@ -7,7 +7,7 @@
 export { buildSpec, KOTLIN_OUT, NORMATIVE_DIRS, SCHEMA_UNITS, TS_OUT, } from "../build.js";
 export { prettyJson } from "../canonical.js";
 export { projectCatalog } from "../catalog.js";
-export { checkConformance } from "../conformance.js";
+export { checkCatalogContract, checkConformance, deprecationExpired, } from "../conformance.js";
 export { formatJson, LINE_WIDTH } from "../format.js";
 export { checkVersionHistory, nextSpecVersion, } from "../versioning.js";
-export { KOTLIN_PACKAGE, kotlinString } from "./kotlin.js";
+export { KOTLIN_PACKAGE, kotlinProperty, kotlinString } from "./kotlin.js";

package/dist/codegen/kotlin.d.ts

@@ -10,6 +10,12 @@ import { type SchemaUnit, type Stamp } from './shared.js';
 export declare const KOTLIN_PACKAGE = "com.texuli.spec";
 /** A Kotlin string literal (escapes backslash, quote, dollar and controls). */
 export declare function kotlinString(value: string): string;
+/**
+ * The Kotlin property for a wire name: a leading `$` is stripped (`$state` →
+ * `state`), because `$` starts a string template in Kotlin. The wire name
+ * itself is always emitted through {@link kotlinString}.
+ */
+export declare function kotlinProperty(name: string): string;
 /** One schema document as a Kotlin file of data classes, enums and decoders. */
 export declare function schemaToKotlin(unit: SchemaUnit, stamp: Stamp): string;
 /** The JSON model and decode helpers every generated decoder uses. */

package/dist/codegen/kotlin.js

@@ -64,6 +64,18 @@ const KEYWORDS = new Set([
 function field(name) {
     return KEYWORDS.has(name) ? `\`${name}\`` : name;
 }
+/**
+ * The Kotlin property for a wire name: a leading `$` is stripped (`$state` →
+ * `state`), because `$` starts a string template in Kotlin. The wire name
+ * itself is always emitted through {@link kotlinString}.
+ */
+export function kotlinProperty(name) {
+    return name.startsWith('$') ? name.slice(1) : name;
+}
+/** `$` escaped for a Kotlin string template (`\$state`). */
+function templateText(name) {
+    return name.replaceAll('$', '\\$');
+}
 function kotlinType(node, ctx, inlineName) {
     if (node.$ref !== undefined)
         return refType(ctx.unit, node.$ref);
@@ -160,22 +172,27 @@ function dataClass(name, node, ctx) {
     const props = Object.entries(node.properties ?? {});
     const params = [];
     const args = [];
+    const seen = new Set();
     for (const [prop, child] of props) {
-        const inlineName = `${name}${pascal(prop)}`;
+        const property = kotlinProperty(prop);
+        if (seen.has(property))
+            throw new Error(`${name}: Kotlin property "${property}" collides`);
+        seen.add(property);
+        const inlineName = `${name}${pascal(property)}`;
         const type = kotlinType(child, ctx, inlineName);
-        const path = `"$path.${prop}"`;
+        const path = `"$path.${templateText(prop)}"`;
         if (required.has(prop)) {
             const defaultValue = typeof child.const === 'string'
                 ? ` = ${kotlinString(child.const)}`
                 : child.const !== undefined
                     ? ` = ${child.const}L`
                     : '';
-            params.push(`${INDENT}val ${field(prop)}: ${type}${defaultValue},`);
-            args.push(`${INDENT}${INDENT}${INDENT}${INDENT}${field(prop)} = ${decodeExpr(child, `fields.required("${prop}", path)`, path, ctx, inlineName)},`);
+            params.push(`${INDENT}val ${field(property)}: ${type}${defaultValue},`);
+            args.push(`${INDENT}${INDENT}${INDENT}${INDENT}${field(property)} = ${decodeExpr(child, `fields.required(${kotlinString(prop)}, path)`, path, ctx, inlineName)},`);
         }
         else {
-            params.push(`${INDENT}val ${field(prop)}: ${type}? = null,`);
-            args.push(`${INDENT}${INDENT}${INDENT}${INDENT}${field(prop)} = fields["${prop}"]?.let { ${decodeExpr(child, 'it', path, ctx, inlineName)} },`);
+            params.push(`${INDENT}val ${field(property)}: ${type}? = null,`);
+            args.push(`${INDENT}${INDENT}${INDENT}${INDENT}${field(property)} = fields[${kotlinString(prop)}]?.let { ${decodeExpr(child, 'it', path, ctx, inlineName)} },`);
         }
     }
     const allowed = props.map(([prop]) => kotlinString(prop)).join(', ');
@@ -299,6 +316,45 @@ export function kotlinJsonRuntime(stamp) {
     ];
     return lines.join('\n');
 }
+function deprecationExpr(value) {
+    const replacement = value.replacement === undefined ? '' : `, replacement = ${kotlinString(value.replacement)}`;
+    return `SpecDeprecation(since = ${kotlinString(value.since)}${replacement})`;
+}
+/** A `SpecPropSchema(...)` constructor call, recursively; only the keywords present. */
+function propSchemaExpr(schema) {
+    const args = [];
+    const number = (value) => (Number.isInteger(value) ? `${value}.0` : String(value));
+    if (schema.type !== undefined)
+        args.push(`type = SpecPropSchemaType.${upperSnake(schema.type)}`);
+    if (schema.description !== undefined)
+        args.push(`description = ${kotlinString(schema.description)}`);
+    if (schema.properties !== undefined) {
+        const entries = Object.entries(schema.properties).map(([name, child]) => `${kotlinString(name)} to ${propSchemaExpr(child)}`);
+        args.push(`properties = mapOf(${entries.join(', ')})`);
+    }
+    if (schema.required !== undefined)
+        args.push(`required = listOf(${schema.required.map(kotlinString).join(', ')})`);
+    if (schema.additionalProperties !== undefined) {
+        args.push(`additionalProperties = ${propSchemaExpr(schema.additionalProperties)}`);
+    }
+    if (schema.items !== undefined)
+        args.push(`items = ${propSchemaExpr(schema.items)}`);
+    if (schema.enum !== undefined)
+        args.push(`enum = listOf(${schema.enum.map(kotlinString).join(', ')})`);
+    for (const key of ['minLength', 'maxLength', 'minItems', 'maxItems']) {
+        const value = schema[key];
+        if (value !== undefined)
+            args.push(`${key} = ${value}L`);
+    }
+    for (const key of ['minimum', 'maximum']) {
+        const value = schema[key];
+        if (value !== undefined)
+            args.push(`${key} = ${number(value)}`);
+    }
+    if (schema.$ref !== undefined)
+        args.push(`ref = ${kotlinString(schema.$ref)}`);
+    return `SpecPropSchema(${args.join(', ')})`;
+}
 /** The catalog vocabulary as a Kotlin registry of `SpecComponent` values. */
 export function vocabularyToKotlin(catalog, stamp) {
     const ids = catalog.components.map((c) => c.id);
@@ -319,9 +375,25 @@ export function vocabularyToKotlin(catalog, stamp) {
             const enumValues = p.enumValues
                 ? `listOf(${p.enumValues.map(kotlinString).join(', ')})`
                 : undefined;
-            lines.push(`${INDENT}${INDENT}${INDENT}${INDENT}SpecProp(`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}name = ${kotlinString(p.name)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}kind = SpecPropKind.${upperSnake(p.kind)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}required = ${optional(p.required === undefined ? undefined : String(p.required))},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}enumValues = ${optional(enumValues)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}extension = ${optional(p.extension ? `SpecPropExtension.${upperSnake(p.extension)}` : undefined)},`, `${INDENT}${INDENT}${INDENT}${INDENT}),`);
+            lines.push(`${INDENT}${INDENT}${INDENT}${INDENT}SpecProp(`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}name = ${kotlinString(p.name)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}kind = SpecPropKind.${upperSnake(p.kind)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}required = ${optional(p.required === undefined ? undefined : String(p.required))},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}enumValues = ${optional(enumValues)},`, `${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}extension = ${optional(p.extension ? `SpecPropExtension.${upperSnake(p.extension)}` : undefined)},`);
+            // Emitted only when present, so a catalog without them stays byte-stable.
+            if (p.schema)
+                lines.push(`${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}schema = ${propSchemaExpr(p.schema)},`);
+            if (p.deprecated) {
+                lines.push(`${INDENT}${INDENT}${INDENT}${INDENT}${INDENT}deprecated = ${deprecationExpr(p.deprecated)},`);
+            }
+            lines.push(`${INDENT}${INDENT}${INDENT}${INDENT}),`);
+        }
+        lines.push(`${INDENT}${INDENT}${INDENT}),`);
+        if (c.events) {
+            lines.push(`${INDENT}${INDENT}${INDENT}events = listOf(${c.events.map((e) => `SpecEventName.${upperSnake(e)}`).join(', ')}),`);
+        }
+        if (c.bindable) {
+            lines.push(`${INDENT}${INDENT}${INDENT}bindable = listOf(${c.bindable.map(kotlinString).join(', ')}),`);
         }
-        lines.push(`${INDENT}${INDENT}${INDENT}),`, `${INDENT}${INDENT}),`);
+        if (c.deprecated)
+            lines.push(`${INDENT}${INDENT}${INDENT}deprecated = ${deprecationExpr(c.deprecated)},`);
+        lines.push(`${INDENT}${INDENT}),`);
     }
     lines.push(`${INDENT})`, '', `${INDENT}fun component(id: String): SpecComponent? = components.firstOrNull { it.id == id }`, '}', '');
     return lines.join('\n');

package/dist/conformance.d.ts

@@ -1,6 +1,7 @@
+import { type SpecCatalog } from './catalog.js';
 /** One conformance failure: drift is a failed gate, never a warning. */
 export interface ConformanceIssue {
-    check: 'dialect' | 'catalog' | 'capabilities' | 'manifest' | 'generated' | 'golden' | 'invalid';
+    check: 'dialect' | 'catalog' | 'capabilities' | 'manifest' | 'generated' | 'golden' | 'invalid' | 'contract' | 'prop-schema' | 'deprecation' | 'workflow';
     path: string;
     message: string;
 }
@@ -14,7 +15,15 @@ export interface ConformanceIssue {
  * - regenerating gives byte-identical TypeScript and Kotlin, with no file
  *   missing or extra;
  * - every golden blueprint validates, and every invalid fixture fails with
- *   exactly its expected diagnostic codes.
+ *   exactly its expected diagnostic codes (blueprints and workflow graphs);
+ * - the blueprint and workflow `$defs` stay disjoint, every catalog property
+ *   schema is usable (array and object props only, contract `$ref`s only),
+ *   bindable props are declared portable props, and no deprecation outlives
+ *   its one-minor warning window.
  * Runtime-neutral: the caller reads the files.
  */
 export declare function checkConformance(normative: Readonly<Record<string, string>>, committed: Readonly<Record<string, string>>): ConformanceIssue[];
+/** The minor-version window: a deprecation since `since` expires one minor later. */
+export declare function deprecationExpired(since: string, specVersion?: string): boolean;
+/** Catalog rules the schema cannot express: property schemas, bindable props, deprecations. */
+export declare function checkCatalogContract(catalog: SpecCatalog, specVersion?: string): ConformanceIssue[];

package/dist/conformance.js

@@ -1,7 +1,10 @@
 import { buildSpec } from "./build.js";
 import { CAPABILITIES } from "./catalog.js";
+import { checkPropSchema, defCollisions } from "./contract.js";
 import { checkSchemaDocument, isRecord, validateInstance } from "./dialect.js";
 import { validateBlueprint } from "./validate.js";
+import { SPEC_VERSION } from "./version.js";
+import { validateWorkflowGraph } from "./workflow.js";
 /**
  * Run the spec's conformance harness (spec/Compose design §7.1 and §7.3)
  * over the normative files and the committed outputs (`manifest.json`,
@@ -12,7 +15,11 @@ import { validateBlueprint } from "./validate.js";
  * - regenerating gives byte-identical TypeScript and Kotlin, with no file
  *   missing or extra;
  * - every golden blueprint validates, and every invalid fixture fails with
- *   exactly its expected diagnostic codes.
+ *   exactly its expected diagnostic codes (blueprints and workflow graphs);
+ * - the blueprint and workflow `$defs` stay disjoint, every catalog property
+ *   schema is usable (array and object props only, contract `$ref`s only),
+ *   bindable props are declared portable props, and no deprecation outlives
+ *   its one-minor warning window.
  * Runtime-neutral: the caller reads the files.
  */
 export function checkConformance(normative, committed) {
@@ -32,6 +39,16 @@ export function checkConformance(normative, committed) {
     }
     const catalogSchema = schemas['schemas/catalog.schema.json'];
     const blueprintSchema = schemas['schemas/blueprint.schema.json'];
+    const workflowSchema = schemas['schemas/workflow.schema.json'];
+    if (blueprintSchema) {
+        for (const name of defCollisions(blueprintSchema, workflowSchema)) {
+            issues.push({
+                check: 'contract',
+                path: 'schemas/blueprint.schema.json',
+                message: `$defs.${name} is also a workflow definition`,
+            });
+        }
+    }
     const catalog = json('catalog/components.json');
     if (catalogSchema) {
         for (const issue of validateInstance(catalogSchema, catalog)) {
@@ -62,6 +79,7 @@ export function checkConformance(normative, committed) {
             }
         }
     }
+    issues.push(...checkCatalogContract(catalog));
     let build;
     try {
         build = buildSpec(normative);
@@ -100,8 +118,23 @@ export function checkConformance(normative, committed) {
             }
         }
     }
+    if (workflowSchema) {
+        for (const path of Object.keys(normative).filter((p) => p.startsWith('fixtures/workflow/'))) {
+            const fixture = json(path);
+            const golden = path.startsWith('fixtures/workflow/golden/');
+            const got = validateWorkflowGraph(golden ? fixture : fixture.graph, workflowSchema).diagnostics.map((d) => d.code);
+            const expected = golden ? [] : (fixture.expect ?? []);
+            if (got.join(',') !== expected.join(',')) {
+                issues.push({
+                    check: 'workflow',
+                    path,
+                    message: `expected [${expected.join(', ')}], got [${got.join(', ')}]`,
+                });
+            }
+        }
+    }
     if (blueprintSchema) {
-        const documents = { blueprintSchema, catalog };
+        const documents = { blueprintSchema, catalog, workflowSchema, validateWorkflowGraph };
         for (const path of Object.keys(normative).filter((p) => p.startsWith('fixtures/golden/'))) {
             const result = validateBlueprint(json(path), documents);
             for (const d of result.diagnostics) {
@@ -122,3 +155,61 @@ export function checkConformance(normative, committed) {
     }
     return issues;
 }
+/** The minor-version window: a deprecation since `since` expires one minor later. */
+export function deprecationExpired(since, specVersion = SPEC_VERSION) {
+    const parse = (v) => v.split('.').map(Number);
+    const [major, minor] = parse(specVersion);
+    const [sinceMajor, sinceMinor] = parse(since);
+    return major > sinceMajor || (major === sinceMajor && minor >= sinceMinor + 1);
+}
+/** Catalog rules the schema cannot express: property schemas, bindable props, deprecations. */
+export function checkCatalogContract(catalog, specVersion = SPEC_VERSION) {
+    const issues = [];
+    const path = 'catalog/components.json';
+    const expired = (where, deprecated) => {
+        if (deprecated && deprecationExpired(deprecated.since, specVersion)) {
+            issues.push({
+                check: 'deprecation',
+                path,
+                message: `${where}: deprecated since ${deprecated.since}; remove it (one minor of warnings has passed)`,
+            });
+        }
+    };
+    for (const component of catalog?.components ?? []) {
+        expired(component.id, component.deprecated);
+        const portable = new Set(component.props.filter((p) => !p.extension).map((p) => p.name));
+        for (const name of component.bindable ?? []) {
+            if (!portable.has(name)) {
+                issues.push({
+                    check: 'prop-schema',
+                    path,
+                    message: `${component.id}: bindable "${name}" is not a portable prop`,
+                });
+            }
+        }
+        if (new Set(component.events ?? []).size !== (component.events ?? []).length) {
+            issues.push({ check: 'catalog', path, message: `${component.id}: events repeat` });
+        }
+        for (const prop of component.props) {
+            expired(`${component.id}.${prop.name}`, prop.deprecated);
+            if (!prop.schema)
+                continue;
+            if (prop.kind !== 'array' && prop.kind !== 'object') {
+                issues.push({
+                    check: 'prop-schema',
+                    path,
+                    message: `${component.id}.${prop.name}: only array and object props take a schema`,
+                });
+                continue;
+            }
+            for (const problem of checkPropSchema(prop.schema)) {
+                issues.push({
+                    check: 'prop-schema',
+                    path,
+                    message: `${component.id}.${prop.name}: ${problem}`,
+                });
+            }
+        }
+    }
+    return issues;
+}