@telorun/analyzer 0.53.0 → 0.55.0

package/dist/validate-observed-state.js

@@ -1,16 +1,8 @@
 import { OBSERVED_STATE_KEY } from "@telorun/sdk";
 import { effectiveStatusSchema } from "./extends-resolution.js";
 import { parseExportEntry } from "./flatten-for-analyzer.js";
-import { moduleScopedDefResolver } from "./alias-resolver.js";
-import { buildReferenceFieldMap, isRefEntry, isScopeEntry, resolveFieldValues, } from "./reference-field-map.js";
-/** The kernel capabilities whose `run()` the kernel dispatches. A ref slot that
- *  accepts one of them is a slot that can start a resource — `targets:` on an
- *  Application or a `Run.Sequence`, and a step's `invoke:` (whose schema accepts
- *  `Telo.Runnable` alongside `Telo.Invocable`, and which the kernel dispatches
- *  through `run()` when the target has no `invoke()`). Keyed on the declared
- *  capability, never on a field name or a kind, so any composer that accepts a
- *  runnable participates without the analyzer knowing about it. */
-const RUN_DISPATCH_CONTRACTS = new Set(["Telo.Runnable", "Telo.Service"]);
+import { moduleScopedDefResolver, } from "./alias-resolver.js";
+import { buildReferenceFieldMap, isScopeEntry, resolveFieldValues, } from "./reference-field-map.js";
 const SYSTEM_KINDS = new Set([
     "Telo.Definition",
     "Telo.Abstract",
@@ -77,89 +69,30 @@ export function observedStateRead(chain) {
     return undefined;
 }
 /**
- * The names of every resource some slot can start: referenced from a ref slot
- * that accepts a `Telo.Runnable` / `Telo.Service`, or named as a step's
- * `invoke:` target. A resource in none of them can never `run()`, so it can
- * never report observed state.
+ * The names of every resource some slot can start.
  *
- * Deliberately an over-approximation — a name reachable through any of these
- * routes counts as runnable — because the cost of a false "can never run" is a
- * valid manifest rejected, while the cost of a miss is only that the reader
- * finds out at runtime instead, with a message that names the same fix.
+ * One question, one answer: a resource is run-reachable when a control-
+ * transferring edge reaches it in the typed reference graph. `call`, `detached`,
+ * `trigger.inbound` and `trigger.consumer` all mean control arrives; `schema` and
+ * `dependency` mean it never does.
+ *
+ * This replaced two independent over-approximations that had to agree by
+ * coincidence: a field-map scan keeping slots whose *constraint capability*
+ * looked runnable, plus an untyped whole-manifest scan for the declared step
+ * invoke key at any depth. Both were guesses at the question `use` now answers —
+ * and the first was wrong in the direction that rejects valid manifests, since a
+ * slot constrained to `Telo.Invocable` can still be dispatched through `run()`.
  */
-export function collectRunReachableNames(manifests, defs, aliases) {
+export function collectRunReachableNames(graph) {
+    // By NAME, not by resolved node: a `with:`-scoped resource is started by its
+    // sequence's `targets:` while never being a top-level node, so resolving first
+    // would report it as unstartable. The graph is passed in, never built here —
+    // one build per analysis, shared with every other graph consumer.
     const names = new Set();
-    const resolve = (kind) => defs.resolve(aliases?.resolveKind(kind) ?? kind) ?? defs.resolve(kind);
-    for (const manifest of manifests) {
-        const def = resolve(manifest.kind);
-        const schema = def?.schema;
-        if (!schema)
-            continue;
-        for (const [path, entry] of buildReferenceFieldMap(schema)) {
-            if (!isRefEntry(entry))
-                continue;
-            if (!entry.refs.some((ref) => RUN_DISPATCH_CONTRACTS.has(ref)))
-                continue;
-            for (const value of resolveFieldValues(manifest, path))
-                collectRefName(value, names);
-        }
-        // Step arrays nest through `if` / `while` / `switch` / `try`, and the step
-        // `invoke:` slot sits behind a local `$ref` the field map does not follow.
-        // Match the declared invoke key at any depth instead of re-deriving the
-        // nesting rules — over-approximating in the safe direction.
-        const invokeKey = stepInvokeKey(schema);
-        if (invokeKey)
-            collectKeyedRefs(manifest, invokeKey, names);
-    }
+    for (const edge of graph.controlEdges())
+        names.add(edge.toName);
     return names;
 }
-/** The property name a kind's `x-telo-step-context` declares as its dispatch
- *  slot (`invoke`), or undefined when the kind has no step array. */
-function stepInvokeKey(schema) {
-    for (const fieldSchema of Object.values((schema.properties ?? {}))) {
-        const stepCtx = fieldSchema?.["x-telo-step-context"];
-        if (stepCtx?.invoke)
-            return stepCtx.invoke;
-    }
-    return undefined;
-}
-/** Collect ref names at every `key` property anywhere in `node`. */
-function collectKeyedRefs(node, key, out) {
-    if (Array.isArray(node)) {
-        for (const item of node)
-            collectKeyedRefs(item, key, out);
-        return;
-    }
-    if (node === null || typeof node !== "object")
-        return;
-    for (const [k, value] of Object.entries(node)) {
-        if (k === key)
-            collectRefName(value, out);
-        collectKeyedRefs(value, key, out);
-    }
-}
-/** Record the resource name a slot value points at — a resolved `{kind, name}`
- *  ref, an unresolved `!ref` sentinel, or a `{ ref }` / `{ invoke }` wrapper. */
-function collectRefName(value, out) {
-    if (value === null || typeof value !== "object")
-        return;
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectRefName(item, out);
-        return;
-    }
-    const v = value;
-    if (typeof v.name === "string")
-        out.add(v.name);
-    if (typeof v.source === "string") {
-        const dot = v.source.lastIndexOf(".");
-        out.add(dot >= 0 ? v.source.slice(dot + 1) : v.source);
-    }
-    for (const wrapper of ["ref", "invoke"]) {
-        if (v[wrapper] !== undefined)
-            collectRefName(v[wrapper], out);
-    }
-}
 /**
  * Index every resource a CEL `resources.…` read can name: the module's own
  * top-level resources, the ones declared inside `x-telo-scope` slots (a

package/dist/validate-ref-slots.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Static validation of the `x-telo-ref` annotation itself — the strict half of
+ * the accessor split. `readRefSlot` is deliberately lenient (it normalizes
+ * whatever it can read, because every surface must keep working mid-migration);
+ * this pass reads the RAW annotation and reports what leniency would otherwise
+ * silently absorb:
+ *
+ *  - an unrecognized `use` token — a typo like `use: cal` would degrade to the
+ *    legacy no-use reading, indistinguishable from a slot that never answered;
+ *  - a structured annotation with no `kind` — the editor would recognise the
+ *    slot but have nothing to pick against;
+ *  - a structured annotation with no `use` — the structured form is the
+ *    declaration that answers the question; omitting it is only legal in the
+ *    legacy bare-string spelling;
+ *  - `anyOf` branches whose declared uses disagree — a state with no meaning,
+ *    since `use` is a property of the slot, never of a branch;
+ *  - a `use` case map whose selector is written in CEL — a call graph known
+ *    only at runtime is not statically analyzable, which is the property the
+ *    typed reference graph exists to protect. There is deliberately no
+ *    fallback: no single value is conservative for every consumer.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`: schema issues are reported only for
+ * definitions in the entry's own modules, and the dynamic-selector issue only
+ * for manifests in them — a published dependency's slot is not the consumer's
+ * to fix.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import { type CallGraph } from "./call-graph.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+export interface RefSlotIssue {
+    code: "X_TELO_REF_INVALID_USE" | "X_TELO_REF_MISSING_USE" | "X_TELO_REF_MISSING_KIND" | "X_TELO_REF_USE_CONFLICT" | "X_TELO_REF_DYNAMIC_SELECTOR";
+    /** The definition (schema issues) or resource (selector issues) at fault. */
+    manifest: ResourceManifest;
+    /** Schema path of the slot (schema issues) or concrete value path of the
+     *  selector's site (dynamic-selector issues). */
+    path: string;
+    message: string;
+}
+/** Schema-level checks over one definition/abstract manifest. */
+export declare function validateRefSlotDeclarations(definition: ResourceManifest): RefSlotIssue[];
+/** Manifest-level check: a `use` case map whose selector is written in CEL.
+ *  Reads the built graph's `unresolvedReason`, so the detection lives once, in
+ *  `resolveUseAtSite`, and this pass cannot disagree with what consumers saw. */
+export declare function validateDynamicSelectors(allManifests: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>, graph?: CallGraph): RefSlotIssue[];
+//# sourceMappingURL=validate-ref-slots.d.ts.map

package/dist/validate-ref-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-ref-slots.d.ts","sourceRoot":"","sources":["../src/validate-ref-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EACA,wBAAwB,GACxB,wBAAwB,GACxB,yBAAyB,GACzB,yBAAyB,GACzB,6BAA6B,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;qDACiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAuJD,iEAAiE;AACjE,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,gBAAgB,GAAG,YAAY,EAAE,CA2CxF;AAED;;iFAEiF;AACjF,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,gBAAgB,EAAE,EAChC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAC5C,KAAK,CAAC,EAAE,SAAS,GAChB,YAAY,EAAE,CA0BhB"}

package/dist/validate-ref-slots.js

@@ -0,0 +1,219 @@
+import { buildCallGraph } from "./call-graph.js";
+import { isRefUse, REF_USES } from "./ref-slot.js";
+const VALID_USES = REF_USES.join(", ");
+/** Raw `use` tokens carried by one annotation value: scalar, list, and every
+ *  case of a case map. Returned unfiltered so a typo is visible. */
+function rawUseTokens(use) {
+    if (use === undefined)
+        return [];
+    if (Array.isArray(use))
+        return use;
+    if (use && typeof use === "object") {
+        const cases = use.cases;
+        if (!cases || typeof cases !== "object")
+            return [];
+        return Object.values(cases).flatMap((v) => Array.isArray(v) ? v : [v]);
+    }
+    return [use];
+}
+/** The declared fixed uses of one annotation (scalar/list form only), for the
+ *  branch-disagreement check. */
+function declaredUses(use) {
+    if (isRefUse(use))
+        return [use];
+    if (Array.isArray(use))
+        return use.filter(isRefUse);
+    return [];
+}
+function checkAnnotation(annotation, manifest, path, issues) {
+    if (typeof annotation === "string" || annotation === undefined)
+        return undefined;
+    if (!annotation || typeof annotation !== "object" || Array.isArray(annotation))
+        return undefined;
+    const obj = annotation;
+    const kind = obj.kind;
+    const hasKind = (typeof kind === "string" && kind.length > 0) ||
+        (Array.isArray(kind) && kind.some((k) => typeof k === "string" && k.length > 0));
+    if (!hasKind) {
+        issues.push({
+            code: "X_TELO_REF_MISSING_KIND",
+            manifest,
+            path,
+            message: `x-telo-ref at '${path}' declares no 'kind'. The structured form is ` +
+                `'{ kind: <Alias>.<Kind> | [<kinds>], use: <use> }' — without a kind the slot ` +
+                `constrains nothing and the editor has nothing to pick against.`,
+        });
+    }
+    const use = obj.use;
+    const isCaseMap = !!use && typeof use === "object" && !Array.isArray(use) && "by" in use;
+    if (use === undefined) {
+        issues.push({
+            code: "X_TELO_REF_MISSING_USE",
+            manifest,
+            path,
+            message: `x-telo-ref at '${path}' declares no 'use'. The structured form must say what the ` +
+                `declaring resource does with the target — one of: ${VALID_USES} — or a ` +
+                `'{ by, cases }' map when a sibling config field selects the mode. Only the legacy ` +
+                `bare-string spelling ('x-telo-ref: <Kind>') may omit it.`,
+        });
+    }
+    else {
+        for (const token of rawUseTokens(use)) {
+            if (isRefUse(token))
+                continue;
+            issues.push({
+                code: "X_TELO_REF_INVALID_USE",
+                manifest,
+                path,
+                message: `x-telo-ref at '${path}' declares unrecognized use '${String(token)}'. ` +
+                    `Valid uses: ${VALID_USES}. An unrecognized token would silently degrade the slot ` +
+                    `to the legacy no-use reading.`,
+            });
+        }
+        if (isCaseMap) {
+            const by = use.by;
+            if (typeof by !== "string" || !by.startsWith("/")) {
+                issues.push({
+                    code: "X_TELO_REF_INVALID_USE",
+                    manifest,
+                    path,
+                    message: `x-telo-ref at '${path}' has a 'use' case map whose 'by' is not a JSON Pointer. ` +
+                        `'by' names a sibling field of the object enclosing the slot, e.g. '/detach'.`,
+                });
+            }
+        }
+    }
+    return declaredUses(use);
+}
+/** True when a node is a reference slot: it carries `x-telo-ref` directly or on
+ *  an `anyOf`/`oneOf` branch. */
+function carriesRefAnnotation(obj) {
+    if (obj["x-telo-ref"] !== undefined)
+        return true;
+    for (const key of ["anyOf", "oneOf"]) {
+        const branches = obj[key];
+        if (!Array.isArray(branches))
+            continue;
+        if (branches.some((b) => b && typeof b === "object" && b["x-telo-ref"] !== undefined)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Walk a definition schema, invoking `onSlot` for every node that carries an
+ *  `x-telo-ref` (directly or on an `anyOf`/`oneOf` branch — the SLOT is the
+ *  node holding the branches, so a branch is never reported twice). Pure-schema
+ *  walk, so it needs — and has — a visited guard for cyclic `$defs`. */
+function walkSchema(node, path, visited, claimedBranches, onSlot) {
+    if (!node || typeof node !== "object")
+        return;
+    if (visited.has(node))
+        return;
+    visited.add(node);
+    if (Array.isArray(node)) {
+        node.forEach((item, i) => walkSchema(item, `${path}[${i}]`, visited, claimedBranches, onSlot));
+        return;
+    }
+    const obj = node;
+    if (carriesRefAnnotation(obj) && !claimedBranches.has(obj)) {
+        onSlot(obj, path);
+        for (const key of ["anyOf", "oneOf"]) {
+            const branches = obj[key];
+            if (!Array.isArray(branches))
+                continue;
+            for (const branch of branches) {
+                if (branch && typeof branch === "object")
+                    claimedBranches.add(branch);
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === "x-telo-ref" || key === "examples" || key === "default")
+            continue;
+        walkSchema(value, path ? `${path}.${key}` : key, visited, claimedBranches, onSlot);
+    }
+}
+/** Schema-level checks over one definition/abstract manifest. */
+export function validateRefSlotDeclarations(definition) {
+    const issues = [];
+    const schema = definition.schema;
+    if (!schema || typeof schema !== "object")
+        return issues;
+    walkSchema(schema, "schema", new Set(), new Set(), (node, path) => {
+        const branchUses = [];
+        const own = checkAnnotation(node["x-telo-ref"], definition, path, issues);
+        if (own)
+            branchUses.push(own);
+        for (const key of ["anyOf", "oneOf"]) {
+            const branches = node[key];
+            if (!Array.isArray(branches))
+                continue;
+            branches.forEach((branch, i) => {
+                if (!branch || typeof branch !== "object")
+                    return;
+                const declared = checkAnnotation(branch["x-telo-ref"], definition, `${path}.${key}[${i}]`, issues);
+                if (declared)
+                    branchUses.push(declared);
+            });
+        }
+        const nonEmpty = branchUses.filter((uses) => uses.length > 0);
+        if (nonEmpty.length > 1) {
+            const first = [...nonEmpty[0]].sort().join(",");
+            const disagrees = nonEmpty.some((uses) => [...uses].sort().join(",") !== first);
+            if (disagrees) {
+                issues.push({
+                    code: "X_TELO_REF_USE_CONFLICT",
+                    manifest: definition,
+                    path,
+                    message: `x-telo-ref branches at '${path}' declare disagreeing uses ` +
+                        `(${nonEmpty.map((u) => u.join("|")).join(" vs ")}). 'use' is a property of the ` +
+                        `slot, never of a branch — declare several acceptable kinds as one ` +
+                        `'kind: [<kinds>]' list with one 'use'.`,
+                });
+            }
+        }
+    });
+    return issues;
+}
+/** Manifest-level check: a `use` case map whose selector is written in CEL.
+ *  Reads the built graph's `unresolvedReason`, so the detection lives once, in
+ *  `resolveUseAtSite`, and this pass cannot disagree with what consumers saw. */
+export function validateDynamicSelectors(allManifests, registry, aliases, aliasesByModule, graph) {
+    const issues = [];
+    const callGraph = graph ?? buildCallGraph(allManifests, registry, { aliases, aliasesByModule });
+    for (const edge of callGraph.edges) {
+        if (edge.unresolvedReason !== "dynamic")
+            continue;
+        const from = callGraph.nodes.get(edge.from);
+        const owner = from?.type === "step" ? callGraph.nodes.get(from.owner) : from;
+        if (!owner || owner.type !== "resource")
+            continue;
+        // Anchor at the SELECTOR — the field the author must change — not at the
+        // ref slot several lines away. Derivable: the slot's enclosing path plus
+        // the pointer's segments.
+        const selectorPath = selectorPathOf(edge.path, edge.unresolved?.by ?? "");
+        issues.push({
+            code: "X_TELO_REF_DYNAMIC_SELECTOR",
+            manifest: owner.manifest,
+            path: selectorPath,
+            message: `The mode selector at '${selectorPath}' is a CEL expression, so which 'use' holds ` +
+                `for the reference at '${edge.path}' cannot be resolved statically. The selector must ` +
+                `be a literal or take its schema default — a call graph known only at runtime is not ` +
+                `statically analyzable. Write the mode as a literal, or split the wiring into one ` +
+                `resource per mode.`,
+        });
+    }
+    return issues;
+}
+/** Concrete path of a case-map selector: the slot's enclosing path joined with
+ *  the pointer's segments (`steps[0].invoke` + `/detach` → `steps[0].detach`). */
+function selectorPathOf(slotPath, pointer) {
+    const lastDot = slotPath.lastIndexOf(".");
+    const enclosing = lastDot < 0 ? "" : slotPath.slice(0, lastDot);
+    const segments = pointer
+        .replace(/^\//, "")
+        .split("/")
+        .map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"))
+        .join(".");
+    return enclosing ? `${enclosing}.${segments}` : segments;
+}

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAmetB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAuD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAmetB"}

package/dist/validate-references.js

@@ -35,7 +35,14 @@ function checkKind(kind, entry, registry, aliases) {
         if (targetDef.kind === "Telo.Abstract") {
             if (subtypes.length === 0)
                 return []; // partial context — no implementations loaded yet
-            const options = [...subtypeKinds].join(", ");
+            // Suggest only what an author can actually wire: with abstract-extends-
+            // abstract real (Telo.Executable over Invocable/Runnable), the transitive
+            // subtype list contains abstracts, which are non-instantiable and would
+            // read as fixes that cannot work.
+            const concrete = subtypes
+                .filter((d) => d.kind !== "Telo.Abstract")
+                .map((d) => `${d.metadata.module}.${d.metadata.name}`);
+            const options = (concrete.length > 0 ? concrete : [...subtypeKinds]).join(", ");
             errors.push(`'${kind}' does not implement '${targetKind}' (known implementations: ${options})`);
         }
         else {

package/dist/validate-zone-slots.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Static validation of the two execution-zone annotations themselves — the
+ * strict half of the accessor split, mirroring `validate-ref-slots.ts`.
+ *
+ * `readProvidesZone` / `readRequiresZone` are deliberately lenient: they return
+ * `undefined` for anything they cannot read. Without this pass that leniency is
+ * silent in the worst possible direction, because the two annotations fail in
+ * OPPOSITE ways:
+ *
+ *  - an unreadable **requires** annotation drops the requirement entirely, so a
+ *    safety constraint the author wrote is never enforced — and the resource
+ *    then throws `ERR_ZONE_REQUIRED` / `ERR_ZONE_ANNOTATION_MISSING` at
+ *    dispatch. That is exactly the silent-non-enforcement `ZONE_PROVIDER_UNRESOLVED`
+ *    exists to prevent, reached by a different route.
+ *  - an unreadable **provides** annotation drops the discharge, so the pass
+ *    reports `ZONE_REQUIREMENT_UNSATISFIED` on manifests that are correct.
+ *
+ * A third shape is worse than either: a `key` the analyzer skips but the kernel
+ * accepts (a pointer with no leading `/` — the kernel's walk splits on `/` and
+ * drops empty segments, so it resolves) makes the two halves disagree about what
+ * the manifest MEANS, which is the one outcome neither severity can express.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`: reported only for definitions in the
+ * entry's own modules — a published dependency's slot is not the consumer's to
+ * fix.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+export interface ZoneSlotIssue {
+    code: "ZONE_ANNOTATION_INVALID";
+    manifest: ResourceManifest;
+    /** Schema path of the annotated slot. */
+    path: string;
+    message: string;
+}
+/** Schema-level zone-annotation checks over one definition/abstract manifest. */
+export declare function validateZoneSlotDeclarations(definition: ResourceManifest): ZoneSlotIssue[];
+//# sourceMappingURL=validate-zone-slots.d.ts.map

package/dist/validate-zone-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-zone-slots.d.ts","sourceRoot":"","sources":["../src/validate-zone-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,yBAAyB,CAAC;IAChC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAmID,iFAAiF;AACjF,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,gBAAgB,GAAG,aAAa,EAAE,CAM1F"}

package/dist/validate-zone-slots.js

@@ -0,0 +1,114 @@
+const PROVIDES = "x-telo-provides-zone";
+const REQUIRES = "x-telo-requires-zone";
+/** A self-relative JSON Pointer, the only correlation-key spelling both halves
+ *  read identically. `""` (whole document) is meaningless as a key, so a
+ *  pointer must name at least one segment. */
+function isPointer(value) {
+    return typeof value === "string" && value.startsWith("/") && value.length > 1;
+}
+function describe(value) {
+    if (typeof value === "string")
+        return `'${value}'`;
+    if (Array.isArray(value))
+        return `a list`;
+    if (value === null)
+        return "null";
+    return typeof value;
+}
+function checkProvides(raw, definition, path, issues) {
+    if (raw === true)
+        return;
+    if (isPointer(raw))
+        return;
+    issues.push({
+        code: "ZONE_ANNOTATION_INVALID",
+        manifest: definition,
+        path,
+        message: `${PROVIDES} at '${path}' is ${describe(raw)}. It takes 'true' (the zone is ` +
+            `uncorrelated) or a self-relative JSON Pointer naming this kind's own field ` +
+            `whose resolved reference the zone carries as its correlation payload ` +
+            `(e.g. '/connection'). It never names the zone — the zone a slot provides ` +
+            `is always the declaring kind.`,
+    });
+}
+function checkRequires(raw, definition, path, issues) {
+    const fail = (message) => {
+        issues.push({ code: "ZONE_ANNOTATION_INVALID", manifest: definition, path, message });
+    };
+    // Bare-string form: the zone kind, uncorrelated.
+    if (typeof raw === "string") {
+        if (!raw)
+            fail(`${REQUIRES} at '${path}' is an empty string; name the providing kind.`);
+        return;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        fail(`${REQUIRES} at '${path}' is ${describe(raw)}. It takes an alias-qualified kind name ` +
+            `(e.g. 'Self.Transaction') or an object with 'zone', an optional 'key' and an ` +
+            `optional 'reason'.`);
+        return;
+    }
+    const obj = raw;
+    if (typeof obj.zone !== "string" || !obj.zone) {
+        fail(`${REQUIRES} at '${path}' declares no 'zone'. Name the providing kind with the same ` +
+            `alias-qualified grammar 'extends' and 'x-telo-ref' use — '<Alias>.<Kind>', ` +
+            `'Self.<Kind>', or 'Telo.<Kind>'. Without it the requirement is silently ` +
+            `unenforced, and the resource throws at dispatch instead.`);
+    }
+    if (obj.key !== undefined) {
+        const pointers = Array.isArray(obj.key) ? obj.key : [obj.key];
+        if (Array.isArray(obj.key) && obj.key.length === 0) {
+            fail(`${REQUIRES} at '${path}' declares an empty 'key' list; omit 'key' instead.`);
+        }
+        for (const pointer of pointers) {
+            if (isPointer(pointer))
+                continue;
+            fail(`${REQUIRES} at '${path}' declares the correlation key ${describe(pointer)}, which is ` +
+                `not a self-relative JSON Pointer. Write '/connection' (or a list of pointers tried ` +
+                `in order, first hit winning). A bare field name is read as a pointer by the runtime ` +
+                `but skipped by the checker, so the two halves would disagree about what this ` +
+                `manifest means.`);
+        }
+    }
+    if (obj.reason !== undefined && typeof obj.reason !== "string") {
+        fail(`${REQUIRES} at '${path}' declares a non-string 'reason'.`);
+    }
+    for (const key of Object.keys(obj)) {
+        if (key === "zone" || key === "key" || key === "reason") {
+            continue;
+        }
+        fail(`${REQUIRES} at '${path}' declares an unknown property '${key}'. The object form takes ` +
+            `'zone', 'key' and 'reason'.`);
+    }
+}
+/** Walk a definition schema, reporting every zone annotation it cannot read.
+ *  Pure-schema walk, so it needs a visited guard for cyclic `$defs`. */
+function walkSchema(node, path, visited, definition, issues) {
+    if (!node || typeof node !== "object")
+        return;
+    if (visited.has(node))
+        return;
+    visited.add(node);
+    if (Array.isArray(node)) {
+        node.forEach((item, i) => walkSchema(item, `${path}[${i}]`, visited, definition, issues));
+        return;
+    }
+    const obj = node;
+    if (obj[PROVIDES] !== undefined)
+        checkProvides(obj[PROVIDES], definition, path, issues);
+    if (obj[REQUIRES] !== undefined)
+        checkRequires(obj[REQUIRES], definition, path, issues);
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === PROVIDES || key === REQUIRES || key === "examples" || key === "default")
+            continue;
+        walkSchema(value, path ? `${path}.${key}` : key, visited, definition, issues);
+    }
+}
+/** Schema-level zone-annotation checks over one definition/abstract manifest. */
+export function validateZoneSlotDeclarations(definition) {
+    const issues = [];
+    const schema = definition.schema;
+    if (!schema || typeof schema !== "object")
+        return issues;
+    walkSchema(schema, "schema", new Set(), definition, issues);
+    return issues;
+}

package/dist/zone-module-documents.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceManifest } from "@telorun/sdk";
+/**
+ * One imported library's FULL document set, for the zone stage's per-library
+ * export derivation — what the flattened analysis view no longer holds, since
+ * it forwards only each library's export surface and never its internal
+ * dispatch chain.
+ *
+ * Plain data in a module of its own, deliberately. It is produced by the
+ * loading side (`collectZoneModuleDocuments`), named in `AnalysisOptions`, and
+ * consumed by the projection; putting it in any of the three would make the
+ * other two import that one, and `types.ts` ↔ the projection is a genuine
+ * cycle. A leaf module with no imports of its own breaks it without an inline
+ * `import(...)` type expression standing in for the dependency nobody wanted.
+ */
+export interface ZoneModuleDocuments {
+    /** The library's module name (its `Telo.Library` doc's `metadata.name`). */
+    module: string;
+    /** Stable source identity of the library's owner file — the cache key. */
+    sourceId: string;
+    /** Owner + partial manifests, stamped with `metadata.source` / `.module`. */
+    manifests: ResourceManifest[];
+    /** Precomputed content signature; derived from the documents when absent. */
+    signature?: string;
+    /** The library's declared `exports.resources` entries (bare names). */
+    exportedNames: readonly string[];
+}
+//# sourceMappingURL=zone-module-documents.d.ts.map

package/dist/zone-module-documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone-module-documents.d.ts","sourceRoot":"","sources":["../src/zone-module-documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC"}

package/dist/zone-module-documents.js

@@ -0,0 +1 @@
+export {};