@telorun/analyzer 0.53.0 → 0.55.0

package/dist/ref-slot.js

@@ -0,0 +1,226 @@
+/**
+ * The single reader of the `x-telo-ref` annotation.
+ *
+ * A reference slot is *recognised* here and nowhere else. Four surfaces ask what
+ * a slot accepts — the analyzer's reference checks, the kernel's Phase-5
+ * injection, the GUI editor's reference picker, and `ide-support`'s completions
+ * / hover / go-to-definition — and before this module each recognised the
+ * annotation by pattern-matching its shape (`typeof node["x-telo-ref"] ===
+ * "string"`, plus a hand-rolled `anyOf` peel in three of them, and no peel at all
+ * in hover). That is why the shape could not change without silently turning
+ * every ref slot in the GUI into a free-text field.
+ *
+ * Browser-safe by construction: no Node built-ins, so the editor and
+ * `ide-support` import it directly and the kernel re-imports it rather than
+ * carrying a second reader — the split already used for the invocation-contract
+ * resolver, the eval-path matcher and the redaction path parser.
+ *
+ * Two annotation shapes are accepted during the migration:
+ *
+ *   x-telo-ref: Telo.Invocable                  # bare string, no declared use
+ *   x-telo-ref:                                 # structured
+ *     kind: [Telo.Invocable, Telo.Runnable]
+ *     use: call
+ *     inputs: /inputs
+ */
+export const REF_USES = [
+    "schema",
+    "dependency",
+    "call",
+    "detached",
+    "trigger.inbound",
+    "trigger.consumer",
+];
+export function isRefUse(value) {
+    return typeof value === "string" && REF_USES.includes(value);
+}
+/** True for a use that transfers control to the target at some point. Everything
+ *  but `schema` and `dependency`. */
+export function transfersControl(use) {
+    return use !== "schema" && use !== "dependency";
+}
+/** Every use a slot can take, flattening a case map. The conservative reading
+ *  for a consumer that does not resolve the selector. */
+export function possibleUses(slot) {
+    if (!slot.useCases)
+        return slot.uses;
+    const out = new Set(slot.uses);
+    for (const uses of Object.values(slot.useCases.cases)) {
+        for (const use of uses)
+            out.add(use);
+    }
+    return [...out];
+}
+/** True when the slot states what the declaring resource does with the target.
+ *  False only for the legacy bare-string form. */
+export function hasDeclaredUse(slot) {
+    return slot.uses.length > 0 || slot.useCases !== undefined;
+}
+function normalizeUses(raw) {
+    if (isRefUse(raw))
+        return [raw];
+    if (Array.isArray(raw))
+        return raw.filter(isRefUse);
+    return [];
+}
+function readUseCases(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    if (typeof obj.by !== "string")
+        return undefined;
+    const rawCases = obj.cases;
+    if (!rawCases || typeof rawCases !== "object" || Array.isArray(rawCases))
+        return undefined;
+    const cases = {};
+    for (const [key, value] of Object.entries(rawCases)) {
+        cases[key] = normalizeUses(value);
+    }
+    return { by: obj.by, cases };
+}
+/** Kind names declared by one annotation value, in either shape. */
+function readKinds(annotation) {
+    if (typeof annotation === "string")
+        return annotation ? [annotation] : [];
+    if (!annotation || typeof annotation !== "object" || Array.isArray(annotation))
+        return [];
+    const kind = annotation.kind;
+    if (typeof kind === "string")
+        return kind ? [kind] : [];
+    if (Array.isArray(kind))
+        return kind.filter((k) => typeof k === "string" && !!k);
+    return [];
+}
+/** The nodes carrying an `x-telo-ref` for this slot: the node itself plus any
+ *  `anyOf` / `oneOf` branch. The multi-kind shape the `kind:` list replaces.
+ *
+ *  `oneOf` is peeled because the editor's picker always did and the analyzer
+ *  never did — unifying on the wider reading is the point of a single accessor.
+ *  The no-op claim is scoped to THIS repo: no schema here puts an `x-telo-ref`
+ *  under `oneOf`, so for the standard library this cannot add a field-map entry
+ *  (and hence a Phase-5 injection site) that did not exist before. An
+ *  already-published third-party module that does use that spelling gains an
+ *  injection site on upgrade — behavior its author most plausibly intended (the
+ *  editor already treated the slot as a reference), but a change of behavior
+ *  nonetheless, and part of this release's contract. */
+function annotationNodes(node) {
+    if (!node || typeof node !== "object")
+        return [];
+    const out = [];
+    if (node["x-telo-ref"] !== undefined)
+        out.push(node);
+    for (const key of ["anyOf", "oneOf"]) {
+        const branches = node[key];
+        if (!Array.isArray(branches))
+            continue;
+        for (const branch of branches) {
+            if (branch && typeof branch === "object" && branch["x-telo-ref"] !== undefined) {
+                out.push(branch);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Reads a schema node as a reference slot, or `undefined` when it declares none.
+ *
+ * Unions the accepted kinds across the `kind:` list and across `anyOf` branches,
+ * which is the model the analyzer has always had internally — `RefFieldEntry`
+ * has carried a flat `refs: string[]` since before the structured form existed.
+ * A `use` declared on more than one branch is taken once; a *disagreement*
+ * between branches is left visible in the returned set rather than silently
+ * resolved here, so `validate-ref-slots.ts` reports it against the authored
+ * node (`X_TELO_REF_USE_CONFLICT`) — the same split that keeps this reader
+ * lenient about unrecognized `use` tokens while that pass rejects them.
+ */
+export function readRefSlot(node) {
+    const nodes = annotationNodes(node);
+    if (nodes.length === 0)
+        return undefined;
+    const kinds = [];
+    const uses = new Set();
+    let useCases;
+    let inputs;
+    for (const carrier of nodes) {
+        const annotation = carrier["x-telo-ref"];
+        for (const kind of readKinds(annotation)) {
+            if (!kinds.includes(kind))
+                kinds.push(kind);
+        }
+        if (!annotation || typeof annotation !== "object" || Array.isArray(annotation))
+            continue;
+        const obj = annotation;
+        for (const use of normalizeUses(obj.use))
+            uses.add(use);
+        useCases ??= readUseCases(obj.use);
+        if (typeof obj.inputs === "string")
+            inputs ??= obj.inputs;
+    }
+    const slot = {
+        kinds,
+        uses: [...uses],
+        inline: node?.["x-telo-inline"] === true || nodes.some((n) => n["x-telo-inline"] === true),
+    };
+    if (useCases)
+        slot.useCases = useCases;
+    if (inputs !== undefined)
+        slot.inputs = inputs;
+    return slot;
+}
+/** True when the node declares a reference slot in any accepted shape. The
+ *  recognition test every surface used to spell for itself. */
+export function isRefSlot(node) {
+    return annotationNodes(node).length > 0;
+}
+/**
+ * Re-emits a slot as a canonical structured annotation value.
+ *
+ * For a consumer that has to *synthesize* a schema node and keep its reference
+ * slot intact — `ide-support` merges `anyOf` branches into one node for
+ * completion, and the merged node would otherwise carry no constraint at all,
+ * because the branches that held it are gone.
+ */
+export function refSlotAnnotation(slot) {
+    const annotation = {
+        kind: slot.kinds.length === 1 ? slot.kinds[0] : slot.kinds,
+    };
+    if (slot.useCases)
+        annotation.use = slot.useCases;
+    else if (slot.uses.length === 1)
+        annotation.use = slot.uses[0];
+    else if (slot.uses.length > 1)
+        annotation.use = slot.uses;
+    if (slot.inputs !== undefined)
+        annotation.inputs = slot.inputs;
+    return annotation;
+}
+/**
+ * Rewrites every kind name an annotation declares, in place, in whichever shape
+ * it is written. `map` returns the replacement, or `undefined` to leave the name
+ * untouched (which is what keeps `resolveSchemaRefKinds` idempotent and lets it
+ * report an unresolvable constraint while quoting what the author wrote).
+ *
+ * Lives here rather than in the caller so that adding an annotation shape is a
+ * one-file change on the write side as well as the read side.
+ */
+export function rewriteRefSlotKinds(annotationHolder, map) {
+    const annotation = annotationHolder["x-telo-ref"];
+    if (typeof annotation === "string") {
+        const next = map(annotation);
+        if (next !== undefined)
+            annotationHolder["x-telo-ref"] = next;
+        return;
+    }
+    if (!annotation || typeof annotation !== "object" || Array.isArray(annotation))
+        return;
+    const obj = annotation;
+    if (typeof obj.kind === "string") {
+        const next = map(obj.kind);
+        if (next !== undefined)
+            obj.kind = next;
+        return;
+    }
+    if (Array.isArray(obj.kind)) {
+        obj.kind = obj.kind.map((k) => (typeof k === "string" ? (map(k) ?? k) : k));
+    }
+}

package/dist/reference-field-map.d.ts

@@ -1,9 +1,20 @@
+import { type RefUse, type RefUseCases } from "./ref-slot.js";
+export { readRefSlot, isRefSlot, hasDeclaredUse } from "./ref-slot.js";
+export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
 /** An entry for a field that carries one or more x-telo-ref constraints. */
 export interface RefFieldEntry {
     /** One or more canonical kind keys ("<module>.<Kind>"), or the deprecated
      *  identity form ("<namespace>/<module>#<Kind>") for a legacy published module.
-     *  Multiple entries arise from anyOf branches. */
+     *  Multiple entries arise from a `kind:` list or from anyOf branches. */
     refs: string[];
+    /** What the declaring resource does with the target — see {@link RefUse}.
+     *  Empty for a slot still on the bare-string form. */
+    uses: RefUse[];
+    /** Set when the use is selected by a sibling config field. */
+    useCases?: RefUseCases;
+    /** JSON Pointer (relative to the object enclosing the slot) naming the field
+     *  carrying this call's arguments. */
+    inputs?: string;
     /** True when the field path traversed through at least one array (path contains "[]"). */
     isArray: boolean;
     /** x-telo-context schema declared on this ref slot, if any. Describes the CEL invocation
@@ -91,6 +102,9 @@ export declare function resolveFieldValues(obj: unknown, path: string): unknown[
  * - A node with `properties` → recurse into each property
  */
 export declare function buildReferenceFieldMap(schema: Record<string, any>): ReferenceFieldMap;
+/** The accepted kinds a node declares, unioned across a `kind:` list and across
+ *  `anyOf` branches. Thin wrapper over {@link readRefSlot} — kept because
+ *  several passes want only the kind set. */
 export declare function collectRefs(node: Record<string, any>): string[];
 /** Traverses an arbitrary JSON Schema starting at the given path prefix. Used to
  *  expand x-telo-schema-from sub-schemas into nested ref/scope entries so Phase 2

package/dist/reference-field-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference-field-map.d.ts","sourceRoot":"","sources":["../src/reference-field-map.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B;;;;;;;;;;kCAU8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;2CACuC;IACvC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED;8CAC8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEnF;0FAC0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,oBAAoB,CAErF;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE;;;;;;;;;2EAS2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAItE;AAED;;;;sEAIsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;wDAUwD;AACxD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAoCpF;AAED;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAQrF;AASD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAa/D;AAED;;;8CAG8C;AAC9C,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAInB"}
+{"version":3,"file":"reference-field-map.d.ts","sourceRoot":"","sources":["../src/reference-field-map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,WAAW,EAAe,MAAM,eAAe,CAAC;AAEzF,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAElE,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;;6EAEyE;IACzE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;0DACsD;IACtD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB;0CACsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B;;;;;;;;;;kCAU8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;2CACuC;IACvC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED;8CAC8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEnF;0FAC0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,oBAAoB,CAErF;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE;;;;;;;;;2EAS2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAItE;AAED;;;;sEAIsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;wDAUwD;AACxD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAoCpF;AAED;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAQrF;AAED;;6CAE6C;AAC7C,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAE/D;AAED;;;8CAG8C;AAC9C,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAInB"}

package/dist/reference-field-map.js

@@ -1,3 +1,5 @@
+import { readRefSlot } from "./ref-slot.js";
+export { readRefSlot, isRefSlot, hasDeclaredUse } from "./ref-slot.js";
 export function isRefEntry(entry) {
     return "refs" in entry;
 }
@@ -103,26 +105,11 @@ export function buildReferenceFieldMap(schema) {
     }
     return map;
 }
-/** `x-telo-inline` declared on any `anyOf` branch marks the whole slot as
- *  inline-accepting, matching how {@link collectRefs} unions branch refs. */
-function collectInlineFlag(node) {
-    if (!Array.isArray(node.anyOf))
-        return false;
-    return node.anyOf.some((branch) => branch?.["x-telo-inline"] === true);
-}
+/** The accepted kinds a node declares, unioned across a `kind:` list and across
+ *  `anyOf` branches. Thin wrapper over {@link readRefSlot} — kept because
+ *  several passes want only the kind set. */
 export function collectRefs(node) {
-    const refs = [];
-    if (typeof node["x-telo-ref"] === "string") {
-        refs.push(node["x-telo-ref"]);
-    }
-    if (Array.isArray(node.anyOf)) {
-        for (const branch of node.anyOf) {
-            if (branch && typeof branch["x-telo-ref"] === "string") {
-                refs.push(branch["x-telo-ref"]);
-            }
-        }
-    }
-    return refs;
+    return readRefSlot(node)?.kinds ?? [];
 }
 /** Traverses an arbitrary JSON Schema starting at the given path prefix. Used to
  *  expand x-telo-schema-from sub-schemas into nested ref/scope entries so Phase 2
@@ -134,17 +121,16 @@ export function buildFieldMapAtPath(schema, pathPrefix) {
     return map;
 }
 function traverseNode(node, path, map, root, visitedRefs = new Set()) {
-    // Local `$ref` is intentionally NOT followed. Descending into shared
-    // `$defs` (notably `Run.Sequence`'s `step` definition) would surface
-    // ref slots like `steps[].invoke` that Phase 5 then injects live
-    // instances into; today's `Run.Sequence` controller calls
-    // `instance.invoke()` directly when handed an instance, bypassing
-    // the kernel's `runInvoke` emit-Invoked path. The walker fix and the
-    // dispatcher fix need to land together — see the follow-up in
-    // [kernel/nodejs/plans/reference-syntax-unification.md] and the
-    // stopgap in `resource-context.ts:ensureKindRef`. `visitedRefs`
-    // stays as a parameter so the recursive calls below thread the right
-    // signature; turning the descent back on is a single-branch change.
+    // Local `$ref` is intentionally NOT followed. This map is the kernel's
+    // Phase-5 injection surface: descending into shared `$defs` (notably
+    // `Run.Sequence`'s `step` definition) would make every step's `invoke` an
+    // injection site, and step slots resolve at dispatch — injecting there is
+    // unwanted regardless of tracing (the original dispatcher-bypass blocker
+    // has since shipped via the `REF_IDENTITY` stamp). Static analysis is NOT
+    // limited by this stop: the call graph (`call-graph.ts`) reads step slots
+    // from the item schema itself and scans the value tree, so it sees what
+    // this map deliberately hides. `visitedRefs` stays as a parameter so the
+    // recursive calls below thread the right signature.
     if (typeof node?.$ref === "string")
         return;
     // Scope slot — record and stop; do not recurse into scope contents
@@ -157,13 +143,21 @@ function traverseNode(node, path, map, root, visitedRefs = new Set()) {
         map.set(path, { schemaFrom: node["x-telo-schema-from"] });
         return;
     }
-    // Reference slot (direct or via anyOf)
-    const refs = collectRefs(node);
-    if (refs.length > 0) {
-        const entry = { refs, isArray: path.includes("[]") };
+    // Reference slot (direct, via a `kind:` list, or via anyOf)
+    const slot = readRefSlot(node);
+    if (slot && slot.kinds.length > 0) {
+        const entry = {
+            refs: slot.kinds,
+            uses: slot.uses,
+            isArray: path.includes("[]"),
+        };
+        if (slot.useCases)
+            entry.useCases = slot.useCases;
+        if (slot.inputs !== undefined)
+            entry.inputs = slot.inputs;
         if (node["x-telo-context"])
             entry.context = node["x-telo-context"];
-        if (node["x-telo-inline"] === true || collectInlineFlag(node))
+        if (slot.inline)
             entry.inline = true;
         map.set(path, entry);
         // A node can mix item-level ref branches (a bare string / `{kind, name}`)

package/dist/resolve-schema-ref-kinds.d.ts

@@ -20,6 +20,10 @@ export interface RefConstraintIssue {
     /** The `Telo.Definition` / `Telo.Abstract` doc that declares the slot. */
     manifest: ResourceManifest;
     reason: RefConstraintReason;
+    /** Which annotation carried the unresolved name: an `x-telo-ref` constraint
+     *  (the default) or an `x-telo-requires-zone` provider kind — the caller
+     *  reports the latter as ZONE_PROVIDER_UNRESOLVED. */
+    annotation?: "ref" | "zone";
     /** For `gated`: the target module and the kinds it does export. */
     gate?: {
         module: string;

package/dist/resolve-schema-ref-kinds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-schema-ref-kinds.d.ts","sourceRoot":"","sources":["../src/resolve-schema-ref-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;;;;;sDAQsD;AACtD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;sFACkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,mEAAmE;IACnE,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9C;+BAC2B;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,mBAAmB,GAAG,cAAc,CAAC,GAClE,kBAAkB,EAAE,CAiDtB"}
+{"version":3,"file":"resolve-schema-ref-kinds.d.ts","sourceRoot":"","sources":["../src/resolve-schema-ref-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAMzD;;;;;;;;sDAQsD;AACtD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;sFACkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;0DAEsD;IACtD,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC5B,mEAAmE;IACnE,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9C;+BAC2B;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,mBAAmB,GAAG,cAAc,CAAC,GAClE,kBAAkB,EAAE,CAsEtB"}

package/dist/resolve-schema-ref-kinds.js

@@ -1,3 +1,5 @@
+import { rewriteRefSlotKinds } from "./ref-slot.js";
+import { hasRequiresZone, rewriteRequiresZoneKind } from "./zone-slot.js";
 const REF_ANNOTATION = "x-telo-ref";
 /** True for the legacy identity form, which is split on `#` by the identity table. */
 export function isLegacyRefIdentity(ref) {
@@ -32,9 +34,9 @@ export function isLegacyRefIdentity(ref) {
  */
 export function resolveSchemaRefKinds(definition, resolver) {
     const issues = [];
-    const record = (ref, path) => {
+    const record = (ref, path, annotation = "ref") => {
         if (isLegacyRefIdentity(ref)) {
-            issues.push({ ref, path, manifest: definition, reason: "legacy" });
+            issues.push({ ref, path, manifest: definition, reason: "legacy", annotation });
             return;
         }
         const result = resolver.resolveKindResult(ref);
@@ -46,6 +48,7 @@ export function resolveSchemaRefKinds(definition, resolver) {
                 path,
                 manifest: definition,
                 reason: "gated",
+                annotation,
                 gate: { module: result.module, exported: result.exported },
             }
             : {
@@ -53,6 +56,7 @@ export function resolveSchemaRefKinds(definition, resolver) {
                 path,
                 manifest: definition,
                 reason: "unknown",
+                annotation,
                 knownAliases: resolver.knownAliases(),
             });
     };
@@ -64,13 +68,32 @@ export function resolveSchemaRefKinds(definition, resolver) {
             return;
         }
         const obj = value;
-        const ref = obj[REF_ANNOTATION];
-        if (typeof ref === "string" && ref) {
-            const result = isLegacyRefIdentity(ref) ? null : resolver.resolveKindResult(ref);
-            if (result?.status === "ok")
-                obj[REF_ANNOTATION] = result.kind;
-            else
+        if (obj[REF_ANNOTATION] !== undefined) {
+            // Shape knowledge stays in `ref-slot.ts`: this pass states only the
+            // alias→canonical rule and what to report when it does not apply.
+            rewriteRefSlotKinds(obj, (ref) => {
+                const result = isLegacyRefIdentity(ref) ? null : resolver.resolveKindResult(ref);
+                if (result?.status === "ok")
+                    return result.kind;
                 record(ref, path);
+                return undefined;
+            });
+        }
+        if (hasRequiresZone(obj)) {
+            // A zone requirement names its provider kind through the identical
+            // alias-qualified grammar, resolved in the same declaring scope — one
+            // walk canonicalizes both, so the kernel's `requireZone` and the zone
+            // projection never see an alias. An unresolved name is reported like an
+            // unresolved ref constraint (the caller maps it to
+            // ZONE_PROVIDER_UNRESOLVED); the legacy identity form is not accepted
+            // here — the annotation postdates its removal.
+            rewriteRequiresZoneKind(obj, (zone) => {
+                const result = resolver.resolveKindResult(zone);
+                if (result.status === "ok")
+                    return result.kind;
+                record(zone, `${path}.x-telo-requires-zone`, "zone");
+                return undefined;
+            });
         }
         for (const key of Object.keys(obj)) {
             walk(obj[key], path ? `${path}.${key}` : key);

package/dist/resolve-zone-requirements.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The zone projection — a CONSUMER of the call-graph service, with no traversal
+ * of its own (see `plans/execution-zones.md`): it filters the graph's edges by
+ * `use`, propagates zone requirements callee→caller along `call` edges,
+ * discharges them at providing slots under the correlation rule, and fires at
+ * terminating edges and at boot.
+ *
+ * Polarity: zones UNDER-approximate. A requirement is asserted only where the
+ * manifest states it, a correlation only where a key pointer resolves, and an
+ * edge whose `use` is unknown neither propagates nor terminates — it warns.
+ * The runtime (`requireZone`) stays the enforcement; a path this pass cannot
+ * see degrades to the runtime error at the right place, never to silence.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import { type CallGraph, type ResourceGraphNode } from "./call-graph.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import type { ZoneModuleDocuments } from "./zone-module-documents.js";
+import { type AnalysisDiagnostic } from "./types.js";
+/** One open requirement on a library's exported resource — the contract an
+ *  importer must satisfy. Plain data, so it caches and crosses the
+ *  per-library derivation boundary. */
+export interface ZoneRequirementSpec {
+    /** Canonical `<module>.<Kind>` of the required zone. */
+    zone: string;
+    /** Correlation identity — the resolved declaration site of the instance the
+     *  requirement correlates on (see {@link correlationIdOf}). Absent =
+     *  uncorrelated. */
+    correlation?: string;
+    /** Human label of the correlation target (`sqlite.Connection 'billingDb'`). */
+    correlationLabel?: string;
+    /** Bare name of the correlation target — what the export-satisfiability
+     *  check compares against `exports.resources`. */
+    correlationName?: string;
+    reason?: string;
+    /** Label of the requiring resource (`sql.Command 'charge'`). */
+    origin: string;
+    /** Resource names on the propagation path so far, origin first. */
+    via: string[];
+}
+/** Per-library derived export contracts: export name → open requirements. */
+export type ZoneExportRequirements = Map<string, ZoneRequirementSpec[]>;
+export interface ZoneExportCacheEntry {
+    signature: string;
+    exports: ZoneExportRequirements;
+}
+/**
+ * Host-lifetime cache for per-library export derivation, keyed by the
+ * library's source identity with a content signature guarding staleness. The
+ * HOST owns it (the editor re-analyzes on every keystroke and must not rebuild
+ * every dependency's graph each time); the CLI passes none. It deliberately
+ * does not live in `AnalysisRegistry`, which the editor constructs fresh per
+ * closure per run — a cache there dies at exactly the boundary it must cross.
+ */
+export type ZoneExportCache = Map<string, ZoneExportCacheEntry>;
+interface ProjectionArgs {
+    graph: CallGraph;
+    defs: DefinitionRegistry;
+    aliases: AliasResolver;
+    aliasesByModule: Map<string, AliasResolver>;
+    /** Modules whose files diagnostics may be reported against (the analysis
+     *  entry's own modules). Empty = derive-only, report nothing. */
+    reportModules: ReadonlySet<string>;
+    /** Extra requirements seeded at forwarded export nodes, keyed
+     *  `${module}\0${name}` — an imported library's derived contracts. */
+    seeds?: Map<string, ZoneRequirementSpec[]>;
+    /** When set, record every requirement that reaches a module-level resource
+     *  this returns an export name for. */
+    exportOf?: (node: ResourceGraphNode) => string | undefined;
+}
+interface ProjectionResult {
+    diagnostics: AnalysisDiagnostic[];
+    openExports: ZoneExportRequirements;
+}
+/** Run the projection over one graph. */
+export declare function projectZoneRequirements(args: ProjectionArgs): ProjectionResult;
+/** Content signature over a library's loaded documents — what makes a
+ *  workspace library invalidate on the keystroke that changed it while a
+ *  published library (immutable bytes) hits every time. FNV-1a over the JSON
+ *  projection; collisions only stale a warning-level derivation, and the
+ *  projection is cheap relative to the graph build it guards. */
+export declare function zoneDocumentsSignature(manifests: readonly ResourceManifest[]): string;
+/**
+ * Derive one library's export contracts: build the library-scoped graph from
+ * its full documents (which the flattened analysis view no longer holds), run
+ * the projection derive-only, and keep what reaches an exported instance.
+ */
+export declare function deriveLibraryExportRequirements(docs: ZoneModuleDocuments, defs: DefinitionRegistry, aliases: AliasResolver, aliasesByModule: Map<string, AliasResolver>, cache?: ZoneExportCache): ZoneExportRequirements;
+export interface ZoneAnalysisArgs {
+    /** The entry analysis set (post inline-normalization + sentinel resolution). */
+    manifests: ResourceManifest[];
+    graph: CallGraph;
+    defs: DefinitionRegistry;
+    aliases: AliasResolver;
+    aliasesByModule: Map<string, AliasResolver>;
+    rootModules: ReadonlySet<string>;
+    moduleDocuments?: readonly ZoneModuleDocuments[];
+    cache?: ZoneExportCache;
+}
+/**
+ * The zone stage of `analyze()`: per-library export derivation (cached), the
+ * entry projection with those contracts seeded, and — when the entry is a
+ * library — the export-satisfiability check, at the one desk where it is
+ * fixable.
+ */
+export declare function runZoneAnalysis(args: ZoneAnalysisArgs): AnalysisDiagnostic[];
+export {};
+//# sourceMappingURL=resolve-zone-requirements.d.ts.map

package/dist/resolve-zone-requirements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-zone-requirements.d.ts","sourceRoot":"","sources":["../src/resolve-zone-requirements.ts"],"names":[],"mappings":"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"}