@reqvire-org/ads 0.3.18 → 0.3.21

package/dist/skills/ads-motion/references/layers.md

@@ -0,0 +1,123 @@
+# Components, patterns and application adapters
+
+Read this when choosing an owner, moving UI between layers, or resolving
+`component-dependency`, `component-contract`, `component-style`, `no-app-import`
+or `showcase-import`. MCP also serves this guide as `ads://guides/layers`.
+
+## Choose by responsibility
+
+A **component** provides one cohesive UI capability: semantics, input handling,
+focus, accessibility, states and appearance. It may compose other components and
+controllers. A notification using an icon, action button and spinner can still
+be one component.
+
+A **pattern** arranges capabilities and content slots into a reusable structure
+or workflow, such as navigation with search/account controls or a report screen.
+Layout parts may arrange `children` without importing several components.
+Patterns may compose other patterns. A native wrapper or a large implementation
+does not decide the layer.
+
+An **application adapter** supplies domain data, store access, route state and
+navigation/service callbacks. Domain-shaped inputs are valid in project-owned
+patterns; importing a particular application store/router is not.
+
+A **scenario** supplies demonstration inputs, local state and simulated services.
+A component scenario may compose several public components and development review helpers
+to demonstrate its subject. That does not turn its fixture or variant selectors
+into production API. Keep `covers` aligned with the scenario's subject layer.
+
+Do not classify by import count, JSX element count, names or file length. Review
+the capability and its consumer contract. Preserve valid APIs when tracing is
+inconclusive; do not make an export private or add a product prop just to pass.
+
+## Demonstrate the production implementation
+
+Product patterns are reusable application UI, not showcase replicas. A scenario
+imports the same production owner and supplies fixtures through its public API;
+the application supplies live data and callbacks to that API. Keep mock records,
+demo selections and simulated services in development files. Legitimate defaults,
+control labels and the pattern's own interaction logic remain with their owner.
+
+Demo framing must not replace a product pattern's styling or behavior. Browser
+checks should exercise both the demonstrated contract and relevant application
+integration; a successful showcase does not establish production parity. A new
+pattern need not already have an application consumer, and import counts cannot
+detect a duplicated implementation. Existing import guards prevent fixture/test
+dependencies; review and browser checks must assess hardcoded mock data and
+unrepresentative rendering that source ownership alone cannot prove.
+
+Review framing belongs in development-only `review/`, not production patterns.
+Use the separate review entry and [review.md](review.md) for the migration and
+build contract.
+
+## Dependency contracts (blocking)
+
+- Component runtime may depend on components, shared controllers and lower-level
+  helpers. It cannot depend on patterns or composition, including indirectly
+  through aliases, forwarding exports, helpers or literal dynamic imports.
+  Type-only pattern references do not introduce runtime dependencies.
+- Patterns consume component symbols published by the configured public entry,
+  including intentional public types. A relative import of a public symbol is
+  allowed inside the ADS; requiring a self-import through the barrel can create
+  cycles. Private state, class blocks and implementation helpers stay internal.
+  A public component may use its own private implementation dependencies.
+- Runtime code cannot import review implementations/types/styles, scenarios, fixtures or checks, including through
+  forwarding exports. Scenarios also cannot import application source.
+- ADS implementations receive application data/effects through inputs and
+  callbacks. Re-exporting application stores, routers or services from a helper
+  does not make them part of the ADS.
+
+For example, `components/Control → shared/helper → patterns/Navigation` fails
+`component-dependency`. Extract a lower-level capability/controller, or move the
+arrangement to a pattern. `patterns/Navigation → components/Control` is valid
+when `Control` is public. Replacing that import with its private state helper
+fails `component-contract` even through a forwarding module.
+
+## Styling contracts (blocking when ownership is established)
+
+Components own their control states and appearance. Patterns own arrangement,
+spacing and their own presentation. Use typed component props/variants, an
+intentional public class helper/hook, or registered non-state customization
+variables. Registration does not authorize overriding interaction policy.
+
+```tsx
+// Component-owned implementation; the marker is not a consumer styling API.
+function Control() {
+  return <button><span className="control-private-label">Label</span></button>;
+}
+
+// Pattern: rejected because it styles the component's private rendered part.
+const wrong = css`
+  & .control-private-label { color: var(--text-muted); }
+`;
+
+// Pattern: its own arrangement remains valid.
+const layout = css`
+  display: flex;
+  gap: var(--space-4);
+`;
+```
+
+The source guard matches component-emitted class names and unambiguous literal
+data markers to the selector's styled subject, including `:is()`/`:where()`.
+It also rejects reads of known private component variables. It does not treat
+an ancestor predicate or `:has()` query as styling that ancestor/descendant:
+`[data-layout="expanded"] > & { gap: var(--space-4); }` changes the pattern's
+own arrangement. Public hooks and registered non-state variables remain valid.
+Token definitions, namespaces and writes retain their existing guards.
+
+Opaque/computed imports, generated selectors, ambiguous shared markers, forwarded
+consumer classes and arbitrary service abstractions are not a complete static
+proof. Passing source checks does not prove that every visual override is safe.
+Review the real rendered states, computed styles, keyboard interactions and
+responsive layouts; use registered browser checks for promised behavior.
+
+## Refactoring an owner
+
+Move runtime source, its scenarios/fixtures and guides together; update public
+exports, dependent imports and documented scenario IDs. Keep callers on the
+same intentional public API. Navigation stays in an application callback or a
+normal link supplied by the consumer, rather than a hidden router mutation in
+the pattern. Validate the complete migration with project checks, product and
+preview builds, and behavior tests. An existing guard rejection is not permission
+to write around the guarded editing workflow.

package/dist/skills/ads-motion/references/motion-review.md

@@ -0,0 +1,35 @@
+# Review motion
+
+Read the item's local README before treating a choice as accidental. Compare
+the source state machine with actual rendered behavior when a browser is
+available. Mark source-only conclusions and untested performance hypotheses.
+
+Assess the following where applicable:
+
+| Area | Look for |
+|------|----------|
+| Purpose/frequency | A clear relationship to the action; repeated work is not slowed |
+| Easing | Entry decelerates naturally; continuous movement and elapsed-time motion use suitable curves |
+| Timing | Feedback starts promptly; total choreography fits its distance and task |
+| Origin/distance | Placement and scale point to the real trigger without excessive travel |
+| Continuity | Reversal and repeated updates retarget without snapping or restarting |
+| Lifecycle | Exit, cancellation, unmount, and zero-duration states clean up correctly |
+| Accessibility | Motion preference, focus, hidden content, and keyboard behavior remain correct |
+| Ownership | Motion uses tokens and owner styles; consumers do not override internals |
+| Cost | Measured rendering work matches the problem; no per-frame work is assumed harmless |
+
+The upstream guidance favors short transitions, restrained scale, and transform/
+opacity. Apply those as defaults with context. A documented 400 ms stack,
+measured height transition, or necessary loading loop is not inherently broken.
+Likewise, a transition below 300 ms is not automatically good. Verify whether an
+exception preserves the intended experience and has acceptable observed cost.
+
+Present only actionable findings. Include file/line, trigger, observed behavior,
+expected behavior, why the difference matters, and a concrete owner-level fix.
+For timing/easing proposals, name the current and proposed token policy and its
+scope. If a token is shared, identify affected neighbors before changing values.
+
+Use a before/after/why comparison for implemented fixes. Separate behavior
+defects, visual refinements, and profiling questions so a suspicion is not
+reported as a proved performance failure. If no defect is found, say what was
+checked and what remains unverified. Do not invent findings to fill a checklist.

package/dist/skills/ads-motion/references/review.md

@@ -1,35 +1,96 @@
-# Review motion
-
-Read the item's local README before treating a choice as accidental. Compare
-the source state machine with actual rendered behavior when a browser is
-available. Mark source-only conclusions and untested performance hypotheses.
-
-Assess the following where applicable:
-
-| Area | Look for |
-|------|----------|
-| Purpose/frequency | A clear relationship to the action; repeated work is not slowed |
-| Easing | Entry decelerates naturally; continuous movement and elapsed-time motion use suitable curves |
-| Timing | Feedback starts promptly; total choreography fits its distance and task |
-| Origin/distance | Placement and scale point to the real trigger without excessive travel |
-| Continuity | Reversal and repeated updates retarget without snapping or restarting |
-| Lifecycle | Exit, cancellation, unmount, and zero-duration states clean up correctly |
-| Accessibility | Motion preference, focus, hidden content, and keyboard behavior remain correct |
-| Ownership | Motion uses tokens and owner styles; consumers do not override internals |
-| Cost | Measured rendering work matches the problem; no per-frame work is assumed harmless |
-
-The upstream guidance favors short transitions, restrained scale, and transform/
-opacity. Apply those as defaults with context. A documented 400 ms stack,
-measured height transition, or necessary loading loop is not inherently broken.
-Likewise, a transition below 300 ms is not automatically good. Verify whether an
-exception preserves the intended experience and has acceptable observed cost.
-
-Present only actionable findings. Include file/line, trigger, observed behavior,
-expected behavior, why the difference matters, and a concrete owner-level fix.
-For timing/easing proposals, name the current and proposed token policy and its
-scope. If a token is shared, identify affected neighbors before changing values.
-
-Use a before/after/why comparison for implemented fixes. Separate behavior
-defects, visual refinements, and profiling questions so a suspicion is not
-reported as a proved performance failure. If no defect is found, say what was
-checked and what remains unverified. Do not invent findings to fill a checklist.
+# Development-only review UI
+
+Read this when creating or migrating demo frames, preview sizing helpers, token
+renderers or demonstration controls. MCP serves it as `ads://guides/review`.
+
+## Responsibilities and boundaries
+
+Components provide cohesive production capabilities. Patterns provide reusable
+application structures/workflows. Both receive variable application data and
+callbacks through their APIs. Their scenarios import the same implementation
+used by the application and supply fixtures; do not create a second implementation
+that only looks correct in the showcase.
+
+`design-system/review/` owns development-only presentation: example frames,
+arrangement, demonstration controls, token sample renderers and their styles.
+It remains project-owned. The MCP host shell stays generic; review code executes
+inside the preview App with the project's framework, foundation, fonts and styles.
+Nothing depends on particular helper names or an imported component library.
+
+The development entry defaults to `review/index.ts` relative to `dsDir`; configure
+`reviewEntry` for another script inside `review/`. Its import alias is the
+configured `publicAlias` plus `/review`, normally `@ds/review`. Discover the actual
+entry/alias through `ads_status.project.review`. Export helpers there, never from
+the production public barrel. Review implementations, types and styles must not
+enter application, component, pattern or controller dependencies. Tests, fixtures,
+scenarios and preview mounts can consume review code.
+
+Review helpers can own Linaria presentation, local state and demo controls. Normal
+style-token, variable ownership, measured-style-write and application separation
+gates still apply. They consume deliberate public component/pattern/controller
+contracts and may reuse local foundation helpers. They cannot target private
+component styles or replace real product behavior. Keep one-off fixture data in
+the scenario; a helper need not become a product API to frame an example.
+
+## Scenario and token contracts
+
+```tsx
+import { Panel } from "@ds";
+import { ReviewFrame } from "@ds/review";
+import { fixture } from "./Panel.fixture";
+
+export const scenario = { title: "Panel", covers: ["Panel"] };
+export default function Scenario() {
+  return <ReviewFrame><Panel {...fixture} /></ReviewFrame>;
+}
+```
+
+The names above are illustrative. `covers` names the production subjects actually
+demonstrated, not every review wrapper. A review export has no product catalogue
+entry and needs no standalone catalogue scenario. Keep review unit tests/specs
+beside their owner; optional behavior contracts can verify review guarantees
+through an existing real scenario. They establish no production coverage.
+
+A token scenario may name its real review renderer in `covers`, import it from
+the development entry, declare `samples: fixture.samples`, and pass those samples
+into the renderer. Existing real product patterns may also serve as token UI.
+Empty covers, unused samples, fabricated tokens and plain value lists remain
+invalid. The rendered App must still pass token-binding checks. See
+[scenarios.md](scenarios.md) for the full token/render contract.
+
+Review class helpers can supply source-proven Linaria classes to a scenario.
+Arbitrary scenario classes/styles remain forbidden. A review wrapper's own native
+controls do not authorize arbitrary native controls in its consuming scenario;
+slot/selector exceptions still need actual production-owner evidence. Keep
+production and review export names distinct where `covers` would be ambiguous.
+
+## Build and guarded edits
+
+The normal preview plugin registers the exact review alias before broader product
+aliases. Configure the same alias in project TypeScript and any independent
+preview/dev harness. In an ordered bundler alias map, put `@ds/review` before
+`@ds`; the broad `@ds` mapping must not resolve it as `index.ts/review`.
+Production entrypoints never import the development entry. Inspect the product
+bundle for review modules/CSS; passing static checks does not prove bundle parity.
+
+Use `ads_units` for `review/<Owner>` units. Scenarios, local specs and helper files
+follow ordinary flat/directory ownership. A review patch may update only its own
+re-exports in the development entry and its own documented style boundaries.
+Product owners retain the separate production entry companion. Use prepared
+patches/dry runs and coupled transactions as described in
+[guarded-editing.md](guarded-editing.md); do not bypass a rejected mutation.
+
+For an existing project, identify helpers by responsibility and actual consumers,
+not names or the number of imported components. Preserve real application patterns.
+Move only demo helpers, their styles and relevant guides to `review/`; update
+scenario/preview imports, style-boundary paths, TypeScript/bundler aliases and
+links. Remove their production exports and obsolete standalone product scenarios.
+Do not copy old example fixtures or export demonstration controls as product UI.
+
+Upgrade ADS before migrating a consuming project: older versions do not know the
+separate review entry. For staged guarded edits, first add distinctly named review
+exports, migrate consumers in passing owner patches, then remove the old pattern
+exports/owners once unused. Required coupled changes use a transaction. Check
+source gates, typecheck, preview and production builds, real browser rendering,
+registered behaviors and token bindings. A source move alone establishes none
+of those rendered guarantees.

package/dist/skills/ads-motion/references/scenarios.md

@@ -34,10 +34,31 @@ do not add scenario `preventDefault` handlers merely to hide it. Explicit App
 bases retain their declared behavior and CSP requirements; external hosts own
 their document-loading policy. Verify link activation as well as rendering.
 
+## Forms inside Apps
+
+Use real form semantics and the runtime owner's intended submit handler. ADS's
+showcase and diagnostic explorer permit `allow-forms` at every iframe layer,
+including legacy widgets. Browser constraint validation, Submit clicks, Enter and
+`requestSubmit()` can reach the normal submit path. Client-side forms call
+`preventDefault()` in their submit handlers; the host does not synthesize clicks
+or submit events. Native action requests are blocked by CSP `form-action 'none'`.
+Submit effects that use tools or resources still follow the MCP bridge.
+
+If a click fires but the `submit` handler never runs, inspect the browser's sandbox
+diagnostic and every ancestor iframe's permissions. Distinguish that host problem
+from native constraint validation legitimately preventing submission. Do not add
+scenario click interception to disguise a missing sandbox permission. External
+MCP hosts control their own sandbox/CSP policy.
+
+Verify an invalid submit, a valid submit, implicit Enter submission and the promised
+state effects. A working Next button is not evidence that form submission works.
+Keep native action navigation separate from client-side submission behavior;
+`allow-forms` does not grant host DOM access or top-level navigation.
+
 ## Owner-local token previews load their own definitions
 
 Keep the registered token sheet imported by its runtime owner for product use.
-A colocated `kind: "tokens"` scenario may render only the public review pattern
+A colocated `kind: "tokens"` scenario may render only the development-only review renderer
 with its fixture samples. Discovery adds the registered owner sheet to the
 generated record's `stylesheets`; `previewEntriesPlugin` imports those paths
 into the token preview independently of the runtime component. Custom builders
@@ -91,7 +112,7 @@ These examples describe verification mistakes, not component-specific rules:
 
 | Situation | Do not | Do instead |
 |-----------|--------|------------|
-| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's public review/layout pattern or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
+| A reference example sets `width: 15rem`, while the native popup uses its default width. | Remove the reference width and claim the original example now matches. | Keep the baseline intact. Reproduce demo sizing through the project's development-only review helper or supported style helper. If a different native size is intentional, document it. Label any additional normalized comparison separately. |
 | Static tracing cannot prove that a public clear control renders when a value is selected. | Remove its export, drop its required coverage, or change runtime behavior merely to pass the gate. | Preserve the intended public API. Try a meaningful selected-state fixture or another real scenario. If valid rendering remains untraceable, report the tooling limitation with a small reproduction. |
 | A screenshot shows the clear control in a selected state. | Treat its presence as evidence that clearing works. | Add a browser check: start selected, activate Clear, assert the value and selection are empty, verify the control's resulting visibility and documented focus behavior, then select again. |
 
@@ -207,6 +228,6 @@ An `exercises` entry records behavioral use; it never grants styling permission.
 Keep helper signatures compatible with the product API. Fix ownership/provenance
 in the runtime owner when genuinely wrong; retain intentional public APIs when
 reporting an unsupported trace. Demo-only sizing, framing and arrangement still
-belong in public review/layout patterns. A style helper is not permission to
+belong in development-only review helpers. A style helper is not permission to
 author a second design in the scenario. For cascade risks and extraction issues,
 read [atomic-styles.md](atomic-styles.md).

package/dist/token-origins.mjs

@@ -0,0 +1,24 @@
+import valueParser from "postcss-value-parser";
+
+/** Read-only provenance for project policies. No token-name or design semantics
+ * are inferred. stopAt is an explicit project-selected vocabulary. */
+export function inspectTokenOrigins(inventory, name, { stopAt = [] } = {}) {
+  const allowed=new Set(stopAt),tokens=new Map(inventory.tokens.map(token=>[token.name,token]));
+  const origins=new Set(),literals=[],diagnostics=[];let steps=0;
+  function visit(name,seen=new Set()) {
+    if(++steps>256){diagnostics.push("Token provenance exceeded 256 branches.");return;}
+    const token=tokens.get(name);
+    if(!token){diagnostics.push(`Undefined token ${name}.`);return;}
+    if(allowed.has(name)){origins.add(name);return;}
+    if(seen.has(name)){diagnostics.push(`Cyclic alias through ${name}.`);return;}
+    seen=new Set([...seen,name]);
+    for(const definition of token.definitions) {
+      const nodes=valueParser(definition.value).nodes.filter(node=>!["space","comment"].includes(node.type));
+      const ref=nodes.length===1&&nodes[0].type==="function"&&nodes[0].value==="var"&&nodes[0].nodes.filter(node=>!["space","comment"].includes(node.type));
+      if(ref&&ref.length===1&&ref[0].type==="word"&&/^--[\w-]+$/.test(ref[0].value))visit(ref[0].value,seen);
+      else literals.push({token:name,...definition});
+    }
+  }
+  visit(name);
+  return {token:name,origins:[...origins].sort(),literals,diagnostics,aliasOnly:origins.size>0&&!literals.length&&!diagnostics.length};
+}

package/dist/tokens.mjs

@@ -45,8 +45,9 @@ function matchesType(value, type) {
   }
 }
 
-export function inspectTokens(directory) {
-  const options = loadConfig(directory);
+export function inspectTokens(directory, suppliedOptions) {
+  const options = suppliedOptions ?? loadConfig(directory);
+  if(options.tokenInventory)return options.tokenInventory;
   const { root, dsRoot, config } = options;
   const definitions = new Map();
   const diagnostics = [];
@@ -141,7 +142,7 @@ export function inspectTokens(directory) {
       if (type && resolved !== undefined && !matchesType(resolved, type)) report("token-type", name, entry, `${name} expects ${type}; found ${resolved}.`);
     }
   }
-  return {
+  return options.tokenInventory = {
     contractVersion: tokenContract.version,
     tokens: [...definitions].sort(([a], [b]) => a.localeCompare(b)).map(([name, entries]) => ({ name, ...tokenContract.tokens[name], ...(scopedTokenOwner(options, name) ? {owner:scopedTokenOwner(options, name).unit, namespace:scopedTokenOwner(options, name).namespace} : {owner:"tokens"}), definitions: entries })),
     diagnostics,

package/dist/unit-contracts.mjs

@@ -0,0 +1,203 @@
+import { existsSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { z } from "zod";
+import { isContractFile, isDevelopmentFile, isInside, isReviewFile, sourceFiles } from "./config.mjs";
+import { projectCompilerOptions } from "./boundaries.mjs";
+import { inspectUnits } from "./units.mjs";
+import { publicApi, reviewApi } from "./public-api.mjs";
+
+const identities = new WeakSet();
+const ref = z.custom(value => value && typeof value === "object" && identities.has(value), "Use a resolved implementation symbol, not its name or an object describing it.");
+const id = z.string().regex(/^[A-Za-z0-9][\w.-]{0,99}$/);
+const checks = z.array(id).min(1).max(100);
+const field = z.string().regex(/^[A-Za-z_$][\w$]*(?:\.(?:[A-Za-z_$][\w$]*|\*))*$/).max(200);
+const paint = z.object({ api: ref, property: field, kind: z.literal("paint-reference"), bindings: z.array(id).max(20).optional() }).strict();
+const binding = z.object({ input: z.object({ api: ref, property: field }).strict(), producer: ref, valueFrom: field,
+  variable: z.string().regex(/^--[a-z][\w-]*\$\{key\}[\w-]*$/), scope: z.object({ api: ref, selector: z.string().min(1).max(200) }).strict(), checks }).strict();
+const part = z.object({ api: ref, parent: ref, consumer: ref, checks }).strict();
+const schema = z.object({ schemaVersion: z.literal(1),
+  tokens: z.object({ namespace: z.string(), stylesheet: z.string().min(1).max(256) }).strict().optional(),
+  paintInputs: z.array(paint).max(100).optional(), bindings: z.record(id, binding).optional(),
+  declarativeParts: z.array(part).max(100).optional(), behavior: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+const slash = file => file.replaceAll("\\", "/");
+export function implementationIdentity(declaration, root) {
+  return `${slash(path.relative(root, declaration.getSourceFile().fileName))}:${declaration.pos}`;
+}
+
+export function implementationNode(program, reference, root) {
+  const source = program.getSourceFile(path.resolve(root, reference.source));
+  let found;
+  function visit(node) {
+    if (node.pos === reference.position && (ts.isFunctionDeclaration(node) || ts.isVariableDeclaration(node) || ts.isClassDeclaration(node))) found = node;
+    else if (!found) ts.forEachChild(node, visit);
+  }
+  if (source) visit(source);
+  return found;
+}
+
+/** Pure AST evaluation. Functions are opaque identities; project code never runs. */
+export function staticContractValue(expression, checker, options, locations = new Map()) {
+  let visits = 0;
+  function read(node, key = "", seen = new Set()) {
+    if (++visits > 12000 || seen.size > 60) throw new Error("Static contract expansion exceeded its bounded limit.");
+    while (node && (ts.isAsExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node))) node = node.expression;
+    if (!node || seen.has(node)) throw new Error(`Unresolved or cyclic contract value at ${key || "default export"}.`);
+    locations.set(key, node);
+    seen = new Set([...seen, node]);
+    if (ts.isStringLiteralLike(node) || ts.isNumericLiteral(node)) return ts.isNumericLiteral(node) ? Number(node.text) : node.text;
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) return -Number(node.operand.text);
+    if (ts.isArrayLiteralExpression(node)) {
+      const result = [];
+      for (const item of node.elements) {
+        if (ts.isSpreadElement(item)) { const values = read(item.expression, key, seen); if (!Array.isArray(values)) throw new Error("Contract array spreads require a static array."); result.push(...values); }
+        else result.push(read(item, `${key}.${result.length}`, seen));
+      }
+      return result;
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+      const result = Object.create(null);
+      for (const item of node.properties) {
+        if (ts.isSpreadAssignment(item)) {
+          const value = read(item.expression, key, seen);
+          if (!value || Array.isArray(value) || typeof value !== "object" || identities.has(value)) throw new Error("Contract object spreads require a plain static object.");
+          for (const [name, valueItem] of Object.entries(value)) { if (Object.hasOwn(result, name)) throw new Error(`Duplicate contract field ${key}.${name}.`); result[name] = valueItem; }
+          continue;
+        }
+        if (!ts.isPropertyAssignment(item) && !ts.isShorthandPropertyAssignment(item)) throw new Error("Contracts contain data fields, not getters, methods or executable expressions.");
+        if (!ts.isIdentifier(item.name) && !ts.isStringLiteralLike(item.name)) throw new Error("Contract property keys must be literal names.");
+        const name = item.name.text;
+        if (["__proto__", "prototype", "constructor"].includes(name) || Object.hasOwn(result, name)) throw new Error(`Invalid or duplicate contract field ${key}.${name}.`);
+        const input = ts.isShorthandPropertyAssignment(item) ? checker.getShorthandAssignmentValueSymbol(item)?.valueDeclaration : null;
+        result[name] = read(input?.initializer ?? (ts.isPropertyAssignment(item) ? item.initializer : item.name), key ? `${key}.${name}` : name, seen);
+      }
+      return result;
+    }
+    if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {
+      let symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node);
+      if (symbol?.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+      const declaration = symbol?.valueDeclaration;
+      if (!declaration) throw new Error(`Cannot resolve contract symbol ${node.getText()}.`);
+      const runtime = !isDevelopmentFile(declaration.getSourceFile().fileName, options)||isReviewFile(declaration.getSourceFile().fileName,options);
+      const initializer = ts.isVariableDeclaration(declaration) ? declaration.initializer : ts.isPropertyAssignment(declaration) ? declaration.initializer : null;
+      const callable = ts.isFunctionDeclaration(declaration) || ts.isClassDeclaration(declaration) || initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer) || ts.isCallExpression(initializer));
+      if (runtime && callable) {
+        const value = { source: slash(path.relative(options.root, declaration.getSourceFile().fileName)), symbol: symbol.name, position: declaration.pos, identity: implementationIdentity(declaration, options.root) };
+        identities.add(value); return value;
+      }
+      if (initializer && (!ts.isVariableDeclaration(declaration) || declaration.parent.flags & ts.NodeFlags.Const)) return read(initializer, key, seen);
+    }
+    throw new Error(`Unsupported static contract expression at ${key || "default export"}: ${ts.SyntaxKind[node.kind]}. Calls, getters and environment-dependent code are not evaluated.`);
+  }
+  return read(expression);
+}
+
+export function inspectUnitContracts(options) {
+  if (options.unitContracts) return options.unitContracts;
+  const files = sourceFiles(options.dsRoot).filter(isContractFile);
+  const result = { contracts: [], diagnostics: [], program: null };
+  options.unitContracts = result;
+  if (!files.length) return result;
+  const inventory = inspectUnits(options);
+  const program = ts.createProgram(sourceFiles(options.dsRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file)), { ...projectCompilerOptions(options), allowJs: true });
+  result.program = program;
+  const checker = program.getTypeChecker();
+  const publicItems = [...publicApi(program, options), ...reviewApi(program, options)];
+  const publicByIdentity = new Map(publicItems.map(api => [implementationIdentity(api.declaration, options.root), api]));
+  const seen = new Set();
+  for (const file of files) {
+    const relative = slash(path.relative(options.root, file));
+    const unit = inventory.owner(inventory.relative(relative));
+    const source = program.getSourceFile(file), locations = new Map();
+    function report(message, fieldName = "") {
+      const node = locations.get(fieldName) ?? source;
+      const position = node?.getSourceFile().getLineAndCharacterOfPosition(node.getStart());
+      result.diagnostics.push({ file: relative, rule: "unit-contract", message, line: (position?.line ?? 0) + 1, column: (position?.character ?? 0) + 1, ...(fieldName ? { entry: fieldName } : {}) });
+    }
+    try {
+      if (!source || statSync(file).size > 128 * 1024 || realpathSync(file) !== file) throw new Error("Contracts must be real owner-local files of at most 128 KiB.");
+      if (!/^(?:components|patterns|controllers|review)\//.test(unit ?? "")) throw new Error("Contracts belong to a component, pattern, controller or review owner.");
+      if (seen.has(unit)) throw new Error(`Only one TypeScript contract may describe ${unit}.`);
+      seen.add(unit);
+      for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement) || ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isExportAssignment(statement) || ts.isEmptyStatement(statement)) continue;
+        if (ts.isVariableStatement(statement) && statement.declarationList.flags & ts.NodeFlags.Const) continue;
+        throw new Error("Contract modules contain imports, types, static constants and one default data export; executable statements are forbidden.");
+      }
+      const exports = source.statements.filter(ts.isExportAssignment);
+      if (exports.length !== 1 || exports[0].isExportEquals) throw new Error("Export one default contract data object.");
+      const value = staticContractValue(exports[0].expression, checker, options, locations);
+      for(const statement of source.statements.filter(ts.isVariableStatement))for(const declaration of statement.declarationList.declarations)staticContractValue(declaration.initializer,checker,options);
+      const parsed = schema.safeParse(value);
+      if (!parsed.success) { for (const issue of parsed.error.issues.slice(0, 12)) report(`${issue.path.join(".")}: ${issue.message}`, issue.path.join(".")); continue; }
+      const data = parsed.data;
+      const apiName = (reference, fieldName) => {
+        const owner = inventory.owner(inventory.relative(reference.source));
+        const api = publicByIdentity.get(reference.identity);
+        if (owner !== unit || !api) { report(`${fieldName} must reference a real public API owned by ${unit}.`, fieldName); return null; }
+        return api.name;
+      };
+      function implementation(reference, fieldName) {
+        const absolute = path.resolve(options.root, reference.source);
+        if (!isInside(options.dsRoot, absolute) || inventory.owner(inventory.relative(reference.source)) !== unit || isDevelopmentFile(absolute, options)&&!isReviewFile(absolute,options)) report(`${fieldName} must reference runtime or review implementation inside ${unit}, not a contract, fixture or spec.`, fieldName);
+      }
+      if (data.tokens) {
+        if(!/^(?:components|patterns)\//.test(unit))report("Owner-local design token namespaces belong to components or patterns. Controllers remain headless; review uses the shared vocabulary and its own presentation state.","tokens");
+        const absolute = path.resolve(path.dirname(file), data.tokens.stylesheet);
+        if (!isInside(options.dsRoot, absolute) || inventory.owner(inventory.relative(slash(path.relative(options.root, absolute)))) !== unit || !absolute.endsWith(".css") || !existsSync(absolute)) report("Token stylesheet must be a real CSS file in this owner.", "tokens.stylesheet");
+        data.tokens.file = slash(path.relative(options.root, absolute));
+      }
+      for (const [index, input] of (data.paintInputs ?? []).entries()) {
+        if(data.paintInputs.slice(0,index).some(prior=>prior.api.identity===input.api.identity&&prior.property===input.property))report("Duplicate paint-input registration is ambiguous.",`paintInputs.${index}`);
+        input.apiName = apiName(input.api, `paintInputs.${index}.api`);
+        for (const name of input.bindings ?? []) if (!Object.hasOwn(data.bindings ?? {}, name)) report(`Unknown binding ${name}.`, `paintInputs.${index}.bindings`);
+      }
+      for (const [name, entry] of Object.entries(data.bindings ?? {})) {
+        entry.apiName = apiName(entry.input.api, `bindings.${name}.input.api`);
+        entry.scope.apiName = apiName(entry.scope.api, `bindings.${name}.scope.api`);
+        if(!publicByIdentity.get(entry.scope.api.identity)?.renderable)report("Binding scopes require a real public rendering API.",`bindings.${name}.scope.api`);
+        implementation(entry.producer, `bindings.${name}.producer`);
+        if (entry.apiName !== entry.scope.apiName) report("The binding input and attachment scope must belong to the same public API.", `bindings.${name}`);
+      }
+      for (const [index, entry] of (data.declarativeParts ?? []).entries()) {
+        if(data.declarativeParts.slice(0,index).some(prior=>prior.api.identity===entry.api.identity))report("A declarative API needs one unambiguous parent/consumer relationship.",`declarativeParts.${index}`);
+        entry.apiName = apiName(entry.api, `declarativeParts.${index}.api`);
+        entry.parentName = apiName(entry.parent, `declarativeParts.${index}.parent`);
+        if(!publicByIdentity.get(entry.parent.identity)?.renderable)report("Declarative parents require a real public rendering API.",`declarativeParts.${index}.parent`);
+        implementation(entry.consumer, `declarativeParts.${index}.consumer`);
+      }
+      let behavior;
+      if (data.behavior) {
+        if(Object.hasOwn(data.behavior,"schemaVersion"))report("Behavior inherits the owner contract's schemaVersion; remove the competing nested version.","behavior.schemaVersion");
+        behavior = { ...data.behavior, schemaVersion: 1 };
+        behavior.subjects = Object.fromEntries(Object.entries(behavior.subjects ?? {}).map(([name, subject]) => {
+          if (subject?.api && identities.has(subject.api)) return [name, { api: apiName(subject.api, `behavior.subjects.${name}.api`) ?? "" }];
+          if (subject?.implementation && identities.has(subject.implementation)) {
+            implementation(subject.implementation, `behavior.subjects.${name}.implementation`);
+            return [name, { source: `./${slash(path.relative(path.dirname(file), path.resolve(options.root, subject.implementation.source)))}`, symbol: subject.implementation.symbol }];
+          }
+          report("Behavior subjects must use an actual public api or owner-local implementation symbol.", `behavior.subjects.${name}`);
+          return [name, subject];
+        }));
+      }
+      for (const entry of [...Object.values(data.bindings ?? {}), ...(data.declarativeParts ?? [])]) for (const check of entry.checks) if (!behavior?.checks?.[check]) report(`Required check ${check} is not registered in this contract's behavior checks.`);
+      result.contracts.push({ ...data, ...(behavior ? { behavior } : {}), unit, file: relative });
+    } catch (error) { report(error.message); }
+  }
+  return result;
+}
+
+/** An ownership lookup, not source/browser certification of the declaration. */
+export function runtimeBindingOwner(options, name) {
+  for (const contract of inspectUnitContracts(options).contracts) for (const [id, binding] of Object.entries(contract.bindings ?? {})) {
+    const [prefix, suffix] = binding.variable.split("${key}");
+    const key = name.slice(prefix.length, suffix ? -suffix.length : undefined);
+    if (name.startsWith(prefix) && name.endsWith(suffix) && /^[A-Za-z0-9_-]+$/.test(key)) return { ...binding, id, unit: contract.unit };
+  }
+  return null;
+}