@reqvire-org/ads 0.3.20 → 0.3.23

package/dist/skills/ads-migrate/references/contracts.md

@@ -0,0 +1,253 @@
+# Static owner contracts and development files
+
+Use one optional `<Owner>.ads.contract.ts` for owner-local tokens, constrained
+paint inputs, scoped runtime bindings, declarative parts and behavioral checks.
+The import `import type { UnitContract } from "@reqvire-org/ads/contracts"` supplies
+development typing. ADS reads its AST and resolves real symbols without importing
+or executing project modules. It adds no production runtime.
+
+## Files and ownership
+
+```text
+components/Plot/
+  Plot.tsx                     production API/root
+  Series.tsx                   production declarative API
+  renderer.tsx                 production consumer
+  paints.ts                    production binding producer
+  types.ts                     production prop types
+  tokens.css                   optional production token definitions
+  Plot.ads.contract.ts         static tool declaration
+  Plot.ads.scenario.tsx         demonstration
+  Plot.ads.fixture.ts           demonstration data
+  Tokens.ads.scenario.tsx       real owner-token samples
+  Tokens.ads.fixture.ts         sample bindings/probes
+  Plot.ads.behavior.spec.ts     registered browser checks
+  Plot.ads.test.tsx             optional unit tests
+  Plot.ads.helpers.ts           development-only adapters
+  README.md                    API/provenance
+```
+
+This is an example, not a required inventory. Use the same roles for patterns,
+controllers and relevant development owners. `review/` remains a separate
+shared development layer; its implementation filenames need no extra marker.
+Runtime components, types and styles cannot import `.ads.` files, tests, fixtures
+or review code through aliases, barrels or helpers. Unknown `.ads.` roles are
+still development-only and are diagnosed. Fixtures/helpers cannot define styles;
+put demo framing in review. Ordinary README/license files retain their names.
+
+Scenarios/fixtures/review enter only the selected preview closure. Contracts are
+never executable preview modules; derived audit descriptors are data. Specs run
+only in the configured test runner. Production declaration emission must also
+start from the public runtime entry, rather than include every file under the
+design-system folder. The starter’s `tsconfig.build.json` does this; its normal
+no-emit typecheck still checks development sources. Core import guards protect
+the runtime dependency closure. Review custom emitter configurations through
+the configuration owner before migrating a consuming project. Guards remain tooling. Production prop types
+belong in runtime files, never inferred from a development contract.
+
+## A contract uses actual implementation references
+
+```ts
+import type { UnitContract } from "@reqvire-org/ads/contracts";
+import { Plot } from "./Plot";
+import { Series } from "./Series";
+import { Renderer } from "./renderer";
+import { paints } from "./paints";
+
+export default {
+  schemaVersion: 1,
+  tokens: { namespace: "--plot-", stylesheet: "./tokens.css" },
+  paintInputs: [
+    { api: Plot, property: "config.*.paint", kind: "paint-reference" },
+    { api: Series, property: "fill", kind: "paint-reference", bindings: ["items"] },
+  ],
+  bindings: {
+    items: {
+      input: { api: Plot, property: "config" },
+      producer: paints,
+      valueFrom: "paint",
+      variable: "--plot-runtime-${key}",
+      scope: { api: Plot, selector: '[data-plot-root=""]' },
+      checks: ["isolation"],
+    },
+  },
+  declarativeParts: [
+    { api: Series, parent: Plot, consumer: Renderer, checks: ["isolation"] },
+  ],
+  behavior: {
+    subjects: { plot: { api: Plot }, renderer: { implementation: Renderer } },
+    guarantees: [{
+      id: "scoped-output",
+      description: "Changing either instance updates only its own output.",
+      subjects: ["plot", "renderer"], checks: ["isolation"],
+    }],
+    checks: {
+      isolation: {
+        file: "./Plot.ads.behavior.spec.ts", case: "isolation",
+        scenario: "components/Plot", profile: "widget",
+      },
+    },
+  },
+} satisfies UnitContract;
+```
+
+Keep contracts small; most owners need none or one section. Supported data are
+literal objects/arrays, static constants/spreads, `as const` and `satisfies`.
+Symbol references resolve through normal imports, aliases and re-exports.
+Calls, getters, methods, computed metadata and environment-dependent expressions
+are rejected. Function references are opaque identities, never executed.
+Private implementation subjects may be internal module exports without becoming
+public barrel exports. Producers/consumers must belong to the same owner. Required
+checks must exist, back named guarantees and use a browser profile with the
+corresponding scenario. A relationship is registration, not a passing guarantee.
+
+## Typed paints and runtime bindings
+
+Production-facing types can use:
+
+```ts
+export type Paint = `var(--${string})` | `url(#${string})` | "none" | "currentColor";
+export interface SeriesProps { fill?: Paint }
+export type Config = Readonly<Record<string, { paint: Paint }>>;
+```
+
+ADS follows the actual property path/type, including nested maps. A name such as
+`Paint`, an arbitrary `string`, `any` or a forged metadata role grants no waiver.
+Supported references are a single accessible token/binding `var(--name)`, a local
+SVG paint `url(#id)`, `none` or `currentColor`. Fallbacks, raw colours, external
+URLs and arbitrary CSS are outside this role. Raw domain colours need a separately
+reviewed validated input boundary; they are not implicitly supported here.
+
+A runtime family is instance data, not an infinite design-token inventory. Its
+source proof requires the declared config map, exact key/value mapping and actual
+root attachment. Supported producers use `Object.entries(config)` with a loop,
+or `Object.fromEntries(...map(...))`; same-owner helper returns are traceable.
+Guard each key before the write/return using
+`if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key")` (a loop may
+`continue`). Return only the computed map. For example:
+
+```ts
+export function paints(config: Config) {
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(config)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key");
+    result[`--plot-runtime-${key}`] = entry.paint;
+  }
+  return result;
+}
+```
+
+The runtime root attaches that returned map using `style={paints(config)}` or a
+traceable local/useMemo result and the declared class/exact data attribute.
+Place spreading props before the explicit scope/style so an unknown spread
+cannot replace them. This grants permission to that binding attachment only;
+it does not authorize arbitrary inline styling, CSSProperties APIs or bulk writes.
+Unsupported dynamic producers/attachment paths fail with an analysis diagnostic.
+Keep the implementation project-owned; there is no required ADS binding helper.
+
+Families cannot overlap shared tokens, owner-token namespaces, private runtime
+prefixes or other bindings. A broad family such as `--color-${key}` grants no
+shared-token exception. Use a distinct private family where collision freedom
+cannot be established. Registered paint consumers list their allowed binding IDs;
+borrowing a peer's family or private token remains invalid. Bindings are scoped
+to their actual root; portals outside it need deliberate project integration.
+
+The App audit checks current mounted instances, accessible values, local SVG
+resources and computed paint-property responses. Visibility and complete rendered
+output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
+and 1000 elements per instance. Exceeding a budget reports limits and complete: false; it does not invalidate a
+working component. An unobserved paint effect also remains unverified until its
+relevant consumer/state is checked. It does
+not prove every future input, visibility state or interaction. In registered
+Playwright checks, use `auditBehaviorPaints(frame)` from
+`@reqvire-org/ads/verification` after updates. Assert `result.ok` and, when claiming complete current-map
+evidence, `result.complete` and the expected `verified` entries.
+Exercise two instances with identical keys/different paints, key updates/removal,
+themes, local SVG IDs and invalid/inaccessible references. Keep normal runner
+profiles; React StrictMode still needs a project development harness.
+
+## Rendered and declarative evidence
+
+`covers` names rendered public UI. A null-returning declarative part belongs in
+`exercises`, alongside behavioral APIs:
+
+```tsx
+export const scenario = {
+  title: "Plot", covers: ["Plot"], exercises: ["Series"],
+};
+```
+
+The real part must reach its registered consumer through a rendered parent.
+ADS resolves source identity comparisons (`child.type === Series`, including a
+traceable comparison helper) and reads of that same child’s props traced from the consumer’s children input.
+A comparison against a decoy object gives no evidence. An import, unrelated parent, unused
+child or metadata claim gives no consumption credit. Unknown render branches are
+conservative. Browser checks must verify that adding/removing/changing the part
+changes output. Source relationships and current browser evidence are separate.
+Do not add fake DOM, hide public parts or rewrite a valid API to appease tracing.
+
+Scenario metadata is validated by field/entry with positions and reasons.
+A bad entry still blocks acceptance while valid independent render evidence is
+retained. Unreadable prerequisites report coverage as not established. Inspect
+the exact source diagnostic and bounded results; do not assume every subsequent
+missing preview means its runtime API is invalid.
+
+## Local tokens and project consistency
+
+`tokens.css` remains optional production design data for component/pattern owners,
+imported by the runtime owner. Controllers stay headless; review uses the shared
+vocabulary and its own development presentation state. Only root/theme definitions belong there. Tokens require real sample
+coverage, including independently built owner token scenarios. One namespace
+cannot be shared by peer components. Private references remain private through
+TS constants, re-exports, helper returns, SVG/paint props and property reads/writes.
+Normal composition of a public component using its own tokens remains valid.
+Source analysis covers supported value flows; arbitrary dynamic code is not
+proof of ownership. CSS variables remain browser-visible; namespacing is an
+architecture boundary, not browser encapsulation.
+
+Ownership does not establish a project's visual scale:
+
+- A component redefining shared `--space-4` fails.
+- Its private `--plot-gap: 7px` can be valid component geometry.
+- `--plot-gap: var(--space-4)` preserves a shared scale with local meaning.
+
+Choose project policy explicitly. A registered project check can use tooling-only
+`inspectTokens(root)` and `inspectTokenOrigins(inventory, name, { stopAt: names })`
+from `@reqvire-org/ads`. `aliasOnly` verifies every theme definition follows only
+aliases to the explicitly selected origins; `literals` and `diagnostics` explain
+violations/limits. Select the exact targets and permitted shared origins. Keep
+intentional geometry exceptions exact with documented reasons. ADS neither
+infers spacing meaning from names nor prescribes a global spacing palette.
+
+## Migration and MCP editing
+
+Legacy `tokens.json`/`<Owner>.tokens.json` and `behavior.json` remain readable.
+Use either authoring form per section; competing declarations fail. New contracts
+normalize into the same discovery, ownership, source revisions, affected-check
+selection and candidate gates. `ads_units` exposes `contractFile`; `ads_catalog`
+reports constrained paint paths and declarative parent/consumer/check references.
+Use bounded file reads and paged detailed results, not repeated whole-project dumps.
+
+Install supporting ADS tooling before migrating a consuming project and reconnect
+MCP before replacing a package used by a running server. Then:
+
+1. Discover one owner with `ads_units`.
+2. `ads_prepare_patch({ unit, action: "migrate" })` creates a normal local draft.
+3. Review the converted contract, renamed files/imports and migration notes.
+4. `ads_prepare_patch({ unit, action: "diff", draft })` emits its Git patchFile.
+5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
+
+Migration never edits live source or bypasses gates. It retains stable scenario
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
+identity when a renamed filename would otherwise be ambiguous; it must stay
+inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
+in legacy registration with a note until deliberately resolved. Unknown runner
+globs, custom adapters and documentation references require review. Ambiguous
+flat-to-directory renames stay in the legacy form with a migration note so file
+ownership cannot silently change. Preserve
+licenses, pending drafts and unrelated work; keep transactions within their limits.
+There is no alternate JSON contract editor. Do not loosen a guard or make a valid
+API private merely to complete a migration.

package/dist/skills/ads-motion/SKILL.md

@@ -337,3 +337,7 @@ native integration does not by itself make that material independent.
 
 This workflow adapts Emil Kowalski's animation skills. See
 [README.md](README.md) and [LICENSE.upstream](LICENSE.upstream) for provenance.
+
+For static owner contracts, `.ads.` development roles, typed paint/binding APIs,
+declarative evidence, token privacy and guarded migration, read
+[contracts.md](references/contracts.md) when the task touches those contracts.

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

@@ -0,0 +1,253 @@
+# Static owner contracts and development files
+
+Use one optional `<Owner>.ads.contract.ts` for owner-local tokens, constrained
+paint inputs, scoped runtime bindings, declarative parts and behavioral checks.
+The import `import type { UnitContract } from "@reqvire-org/ads/contracts"` supplies
+development typing. ADS reads its AST and resolves real symbols without importing
+or executing project modules. It adds no production runtime.
+
+## Files and ownership
+
+```text
+components/Plot/
+  Plot.tsx                     production API/root
+  Series.tsx                   production declarative API
+  renderer.tsx                 production consumer
+  paints.ts                    production binding producer
+  types.ts                     production prop types
+  tokens.css                   optional production token definitions
+  Plot.ads.contract.ts         static tool declaration
+  Plot.ads.scenario.tsx         demonstration
+  Plot.ads.fixture.ts           demonstration data
+  Tokens.ads.scenario.tsx       real owner-token samples
+  Tokens.ads.fixture.ts         sample bindings/probes
+  Plot.ads.behavior.spec.ts     registered browser checks
+  Plot.ads.test.tsx             optional unit tests
+  Plot.ads.helpers.ts           development-only adapters
+  README.md                    API/provenance
+```
+
+This is an example, not a required inventory. Use the same roles for patterns,
+controllers and relevant development owners. `review/` remains a separate
+shared development layer; its implementation filenames need no extra marker.
+Runtime components, types and styles cannot import `.ads.` files, tests, fixtures
+or review code through aliases, barrels or helpers. Unknown `.ads.` roles are
+still development-only and are diagnosed. Fixtures/helpers cannot define styles;
+put demo framing in review. Ordinary README/license files retain their names.
+
+Scenarios/fixtures/review enter only the selected preview closure. Contracts are
+never executable preview modules; derived audit descriptors are data. Specs run
+only in the configured test runner. Production declaration emission must also
+start from the public runtime entry, rather than include every file under the
+design-system folder. The starter’s `tsconfig.build.json` does this; its normal
+no-emit typecheck still checks development sources. Core import guards protect
+the runtime dependency closure. Review custom emitter configurations through
+the configuration owner before migrating a consuming project. Guards remain tooling. Production prop types
+belong in runtime files, never inferred from a development contract.
+
+## A contract uses actual implementation references
+
+```ts
+import type { UnitContract } from "@reqvire-org/ads/contracts";
+import { Plot } from "./Plot";
+import { Series } from "./Series";
+import { Renderer } from "./renderer";
+import { paints } from "./paints";
+
+export default {
+  schemaVersion: 1,
+  tokens: { namespace: "--plot-", stylesheet: "./tokens.css" },
+  paintInputs: [
+    { api: Plot, property: "config.*.paint", kind: "paint-reference" },
+    { api: Series, property: "fill", kind: "paint-reference", bindings: ["items"] },
+  ],
+  bindings: {
+    items: {
+      input: { api: Plot, property: "config" },
+      producer: paints,
+      valueFrom: "paint",
+      variable: "--plot-runtime-${key}",
+      scope: { api: Plot, selector: '[data-plot-root=""]' },
+      checks: ["isolation"],
+    },
+  },
+  declarativeParts: [
+    { api: Series, parent: Plot, consumer: Renderer, checks: ["isolation"] },
+  ],
+  behavior: {
+    subjects: { plot: { api: Plot }, renderer: { implementation: Renderer } },
+    guarantees: [{
+      id: "scoped-output",
+      description: "Changing either instance updates only its own output.",
+      subjects: ["plot", "renderer"], checks: ["isolation"],
+    }],
+    checks: {
+      isolation: {
+        file: "./Plot.ads.behavior.spec.ts", case: "isolation",
+        scenario: "components/Plot", profile: "widget",
+      },
+    },
+  },
+} satisfies UnitContract;
+```
+
+Keep contracts small; most owners need none or one section. Supported data are
+literal objects/arrays, static constants/spreads, `as const` and `satisfies`.
+Symbol references resolve through normal imports, aliases and re-exports.
+Calls, getters, methods, computed metadata and environment-dependent expressions
+are rejected. Function references are opaque identities, never executed.
+Private implementation subjects may be internal module exports without becoming
+public barrel exports. Producers/consumers must belong to the same owner. Required
+checks must exist, back named guarantees and use a browser profile with the
+corresponding scenario. A relationship is registration, not a passing guarantee.
+
+## Typed paints and runtime bindings
+
+Production-facing types can use:
+
+```ts
+export type Paint = `var(--${string})` | `url(#${string})` | "none" | "currentColor";
+export interface SeriesProps { fill?: Paint }
+export type Config = Readonly<Record<string, { paint: Paint }>>;
+```
+
+ADS follows the actual property path/type, including nested maps. A name such as
+`Paint`, an arbitrary `string`, `any` or a forged metadata role grants no waiver.
+Supported references are a single accessible token/binding `var(--name)`, a local
+SVG paint `url(#id)`, `none` or `currentColor`. Fallbacks, raw colours, external
+URLs and arbitrary CSS are outside this role. Raw domain colours need a separately
+reviewed validated input boundary; they are not implicitly supported here.
+
+A runtime family is instance data, not an infinite design-token inventory. Its
+source proof requires the declared config map, exact key/value mapping and actual
+root attachment. Supported producers use `Object.entries(config)` with a loop,
+or `Object.fromEntries(...map(...))`; same-owner helper returns are traceable.
+Guard each key before the write/return using
+`if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key")` (a loop may
+`continue`). Return only the computed map. For example:
+
+```ts
+export function paints(config: Config) {
+  const result: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(config)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(key)) throw new Error("Invalid key");
+    result[`--plot-runtime-${key}`] = entry.paint;
+  }
+  return result;
+}
+```
+
+The runtime root attaches that returned map using `style={paints(config)}` or a
+traceable local/useMemo result and the declared class/exact data attribute.
+Place spreading props before the explicit scope/style so an unknown spread
+cannot replace them. This grants permission to that binding attachment only;
+it does not authorize arbitrary inline styling, CSSProperties APIs or bulk writes.
+Unsupported dynamic producers/attachment paths fail with an analysis diagnostic.
+Keep the implementation project-owned; there is no required ADS binding helper.
+
+Families cannot overlap shared tokens, owner-token namespaces, private runtime
+prefixes or other bindings. A broad family such as `--color-${key}` grants no
+shared-token exception. Use a distinct private family where collision freedom
+cannot be established. Registered paint consumers list their allowed binding IDs;
+borrowing a peer's family or private token remains invalid. Bindings are scoped
+to their actual root; portals outside it need deliberate project integration.
+
+The App audit checks current mounted instances, accessible values, local SVG
+resources and computed paint-property responses. Visibility and complete rendered
+output still need assertions in the registered browser checks. It rejects missing/duplicate IDs and reports unobserved written values separately. It is bounded to 100 families, 20 instances per family, 100 keys
+and 1000 elements per instance. Exceeding a budget reports limits and complete: false; it does not invalidate a
+working component. An unobserved paint effect also remains unverified until its
+relevant consumer/state is checked. It does
+not prove every future input, visibility state or interaction. In registered
+Playwright checks, use `auditBehaviorPaints(frame)` from
+`@reqvire-org/ads/verification` after updates. Assert `result.ok` and, when claiming complete current-map
+evidence, `result.complete` and the expected `verified` entries.
+Exercise two instances with identical keys/different paints, key updates/removal,
+themes, local SVG IDs and invalid/inaccessible references. Keep normal runner
+profiles; React StrictMode still needs a project development harness.
+
+## Rendered and declarative evidence
+
+`covers` names rendered public UI. A null-returning declarative part belongs in
+`exercises`, alongside behavioral APIs:
+
+```tsx
+export const scenario = {
+  title: "Plot", covers: ["Plot"], exercises: ["Series"],
+};
+```
+
+The real part must reach its registered consumer through a rendered parent.
+ADS resolves source identity comparisons (`child.type === Series`, including a
+traceable comparison helper) and reads of that same child’s props traced from the consumer’s children input.
+A comparison against a decoy object gives no evidence. An import, unrelated parent, unused
+child or metadata claim gives no consumption credit. Unknown render branches are
+conservative. Browser checks must verify that adding/removing/changing the part
+changes output. Source relationships and current browser evidence are separate.
+Do not add fake DOM, hide public parts or rewrite a valid API to appease tracing.
+
+Scenario metadata is validated by field/entry with positions and reasons.
+A bad entry still blocks acceptance while valid independent render evidence is
+retained. Unreadable prerequisites report coverage as not established. Inspect
+the exact source diagnostic and bounded results; do not assume every subsequent
+missing preview means its runtime API is invalid.
+
+## Local tokens and project consistency
+
+`tokens.css` remains optional production design data for component/pattern owners,
+imported by the runtime owner. Controllers stay headless; review uses the shared
+vocabulary and its own development presentation state. Only root/theme definitions belong there. Tokens require real sample
+coverage, including independently built owner token scenarios. One namespace
+cannot be shared by peer components. Private references remain private through
+TS constants, re-exports, helper returns, SVG/paint props and property reads/writes.
+Normal composition of a public component using its own tokens remains valid.
+Source analysis covers supported value flows; arbitrary dynamic code is not
+proof of ownership. CSS variables remain browser-visible; namespacing is an
+architecture boundary, not browser encapsulation.
+
+Ownership does not establish a project's visual scale:
+
+- A component redefining shared `--space-4` fails.
+- Its private `--plot-gap: 7px` can be valid component geometry.
+- `--plot-gap: var(--space-4)` preserves a shared scale with local meaning.
+
+Choose project policy explicitly. A registered project check can use tooling-only
+`inspectTokens(root)` and `inspectTokenOrigins(inventory, name, { stopAt: names })`
+from `@reqvire-org/ads`. `aliasOnly` verifies every theme definition follows only
+aliases to the explicitly selected origins; `literals` and `diagnostics` explain
+violations/limits. Select the exact targets and permitted shared origins. Keep
+intentional geometry exceptions exact with documented reasons. ADS neither
+infers spacing meaning from names nor prescribes a global spacing palette.
+
+## Migration and MCP editing
+
+Legacy `tokens.json`/`<Owner>.tokens.json` and `behavior.json` remain readable.
+Use either authoring form per section; competing declarations fail. New contracts
+normalize into the same discovery, ownership, source revisions, affected-check
+selection and candidate gates. `ads_units` exposes `contractFile`; `ads_catalog`
+reports constrained paint paths and declarative parent/consumer/check references.
+Use bounded file reads and paged detailed results, not repeated whole-project dumps.
+
+Install supporting ADS tooling before migrating a consuming project and reconnect
+MCP before replacing a package used by a running server. Then:
+
+1. Discover one owner with `ads_units`.
+2. `ads_prepare_patch({ unit, action: "migrate" })` creates a normal local draft.
+3. Review the converted contract, renamed files/imports and migration notes.
+4. `ads_prepare_patch({ unit, action: "diff", draft })` emits its Git patchFile.
+5. Dry-run/apply with `ads_apply_patch`, or a genuinely coupled transaction.
+
+Migration never edits live source or bypasses gates. It retains stable scenario
+IDs, check case IDs and directory ownership. A canonical `<Owner>.ads.scenario.tsx` is the same
+development entry as `Scenario.tsx`, even without a production entry or owner
+contract. Explicit flat IDs and existing flat peer families remain separate.
+An optional static `scenario.id` preserves a legacy
+identity when a renamed filename would otherwise be ambiguous; it must stay
+inside the owning unit and be unique. Whole-file or unimportable private behavior subjects stay
+in legacy registration with a note until deliberately resolved. Unknown runner
+globs, custom adapters and documentation references require review. Ambiguous
+flat-to-directory renames stay in the legacy form with a migration note so file
+ownership cannot silently change. Preserve
+licenses, pending drafts and unrelated work; keep transactions within their limits.
+There is no alternate JSON contract editor. Do not loosen a guard or make a valid
+API private merely to complete a migration.

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,