@telorun/analyzer 0.52.0 → 0.54.0

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 {};

package/dist/zone-slot.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The single reader of the two execution-zone annotations —
+ * `x-telo-provides-zone` and `x-telo-requires-zone` (see
+ * `kernel/specs/execution-zones.md`). The analyzer's zone projection, the
+ * kernel's `withZone` / `requireZone`, and any editor surface all recognise a
+ * zone slot here and nowhere else, the same one-accessor rule `ref-slot.ts`
+ * established for `x-telo-ref`. Browser-safe: no Node built-ins.
+ *
+ * Accepted shapes:
+ *
+ *   x-telo-provides-zone: true            # uncorrelated — the zone is the kind
+ *   x-telo-provides-zone: /connection     # correlation-key pointer (own field)
+ *
+ *   x-telo-requires-zone: Self.Transaction        # uncorrelated string form
+ *   x-telo-requires-zone:                          # object form
+ *     zone: Self.Transaction
+ *     key: [/connection, /transaction/connection]  # ordered, first hit wins
+ *     reason: the statement would execute outside any transaction
+ */
+/** A body slot that establishes the declaring kind's zone when dispatched
+ *  through. The zone's identity is always the declaring kind — the annotation
+ *  never names one, so provision-on-behalf-of is unrepresentable. */
+export interface ProvidesZoneSlot {
+    /** Self-relative JSON pointer to the declaring kind's own field whose resolved
+     *  reference the zone carries as its correlation payload. Absent =
+     *  uncorrelated (`true`). */
+    key?: string;
+}
+/** A field declaring that its resource must be reached through a zone. */
+export interface RequiresZoneSlot {
+    /** The providing kind, alias-qualified as authored (`Self.Transaction`,
+     *  `<Alias>.<Kind>`) — canonical `<module>.<Kind>` once
+     *  `resolveSchemaRefKinds` has rewritten it in the declaring scope. */
+    zone: string;
+    /** Ordered self-relative JSON pointers tried in order, first hit winning; a
+     *  pointer may traverse a `!ref` into the referenced resource's own field.
+     *  Empty = uncorrelated. */
+    key: string[];
+    /** The runtime consequence, quoted after the path in diagnostics. */
+    reason?: string;
+}
+/** Reads a schema node's provides-zone declaration, or undefined when it has
+ *  none or the value is malformed (`validate-zone-slots` reports those). */
+export declare function readProvidesZone(node: Record<string, any> | undefined): ProvidesZoneSlot | undefined;
+/** True when the node carries `x-telo-provides-zone` in any shape, valid or not
+ *  — the recognition test validation needs before it judges the value. */
+export declare function hasProvidesZone(node: Record<string, any> | undefined): boolean;
+/** Reads a schema node's requires-zone declaration, or undefined when it has
+ *  none or the value is malformed (`validate-zone-slots` reports those). */
+export declare function readRequiresZone(node: Record<string, any> | undefined): RequiresZoneSlot | undefined;
+/** True when the node carries `x-telo-requires-zone` in any shape. */
+export declare function hasRequiresZone(node: Record<string, any> | undefined): boolean;
+/**
+ * Rewrites the requires-zone kind name in place, in whichever shape it is
+ * written — the write-side twin of {@link readRequiresZone}, mirroring
+ * `rewriteRefSlotKinds` so `resolveSchemaRefKinds` canonicalizes both
+ * annotations in one walk. `map` returns the replacement or `undefined` to
+ * leave the authored name untouched (idempotence + quotable diagnostics).
+ */
+export declare function rewriteRequiresZoneKind(annotationHolder: Record<string, any>, map: (kind: string) => string | undefined): void;
+//# sourceMappingURL=zone-slot.d.ts.map

package/dist/zone-slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone-slot.d.ts","sourceRoot":"","sources":["../src/zone-slot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH;;qEAEqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B;;iCAE6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B;;2EAEuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb;;gCAE4B;IAC5B,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAYD;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAKpG;AAED;0EAC0E;AAC1E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAWpG;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACxC,IAAI,CAaN"}

package/dist/zone-slot.js

@@ -0,0 +1,91 @@
+/**
+ * The single reader of the two execution-zone annotations —
+ * `x-telo-provides-zone` and `x-telo-requires-zone` (see
+ * `kernel/specs/execution-zones.md`). The analyzer's zone projection, the
+ * kernel's `withZone` / `requireZone`, and any editor surface all recognise a
+ * zone slot here and nowhere else, the same one-accessor rule `ref-slot.ts`
+ * established for `x-telo-ref`. Browser-safe: no Node built-ins.
+ *
+ * Accepted shapes:
+ *
+ *   x-telo-provides-zone: true            # uncorrelated — the zone is the kind
+ *   x-telo-provides-zone: /connection     # correlation-key pointer (own field)
+ *
+ *   x-telo-requires-zone: Self.Transaction        # uncorrelated string form
+ *   x-telo-requires-zone:                          # object form
+ *     zone: Self.Transaction
+ *     key: [/connection, /transaction/connection]  # ordered, first hit wins
+ *     reason: the statement would execute outside any transaction
+ */
+const PROVIDES = "x-telo-provides-zone";
+const REQUIRES = "x-telo-requires-zone";
+/** A self-relative JSON Pointer — the only correlation-key spelling the
+ *  analyzer and the kernel read identically. Applied to BOTH the scalar and the
+ *  list form: the kernel's walk splits on `/` and drops empty segments, so a
+ *  bare `connection` would resolve there while the checker skipped it, and the
+ *  two halves would disagree about what the manifest means. `validate-zone-slots`
+ *  reports what this rejects. */
+function isPointer(value) {
+    return typeof value === "string" && value.startsWith("/") && value.length > 1;
+}
+/** Reads a schema node's provides-zone declaration, or undefined when it has
+ *  none or the value is malformed (`validate-zone-slots` reports those). */
+export function readProvidesZone(node) {
+    const raw = node?.[PROVIDES];
+    if (raw === true)
+        return {};
+    if (isPointer(raw))
+        return { key: raw };
+    return undefined;
+}
+/** True when the node carries `x-telo-provides-zone` in any shape, valid or not
+ *  — the recognition test validation needs before it judges the value. */
+export function hasProvidesZone(node) {
+    return node?.[PROVIDES] !== undefined;
+}
+/** Reads a schema node's requires-zone declaration, or undefined when it has
+ *  none or the value is malformed (`validate-zone-slots` reports those). */
+export function readRequiresZone(node) {
+    const raw = node?.[REQUIRES];
+    if (typeof raw === "string" && raw)
+        return { zone: raw, key: [] };
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    if (typeof obj.zone !== "string" || !obj.zone)
+        return undefined;
+    // One filter for both spellings — see `isPointer`.
+    const key = (Array.isArray(obj.key) ? obj.key : [obj.key]).filter(isPointer);
+    const slot = { zone: obj.zone, key };
+    if (typeof obj.reason === "string")
+        slot.reason = obj.reason;
+    return slot;
+}
+/** True when the node carries `x-telo-requires-zone` in any shape. */
+export function hasRequiresZone(node) {
+    return node?.[REQUIRES] !== undefined;
+}
+/**
+ * Rewrites the requires-zone kind name in place, in whichever shape it is
+ * written — the write-side twin of {@link readRequiresZone}, mirroring
+ * `rewriteRefSlotKinds` so `resolveSchemaRefKinds` canonicalizes both
+ * annotations in one walk. `map` returns the replacement or `undefined` to
+ * leave the authored name untouched (idempotence + quotable diagnostics).
+ */
+export function rewriteRequiresZoneKind(annotationHolder, map) {
+    const raw = annotationHolder[REQUIRES];
+    if (typeof raw === "string") {
+        const next = map(raw);
+        if (next !== undefined)
+            annotationHolder[REQUIRES] = next;
+        return;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return;
+    const obj = raw;
+    if (typeof obj.zone === "string") {
+        const next = map(obj.zone);
+        if (next !== undefined)
+            obj.zone = next;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,13 +42,13 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.11.1"
+    "@telorun/templating": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.65.0"
+    "@telorun/sdk": "0.67.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analysis-registry.ts

@@ -177,12 +177,30 @@ export class AnalysisRegistry {
   private capabilitiesForRefs(refs: string[]): string[] {
     const out: string[] = [];
     for (const ref of refs) {
-      const cap = this.capabilityForRef(ref);
-      if (cap && !out.includes(cap)) out.push(cap);
+      for (const cap of this.leafCapabilitiesForRef(ref)) {
+        if (!out.includes(cap)) out.push(cap);
+      }
     }
     return out;
   }
 
+  /** Like {@link capabilityForRef}, but a capability GROUP — an abstract with no
+   *  `capability` of its own that other capability abstracts extend, i.e.
+   *  `Telo.Executable` over Invocable and Runnable — expands to its leaves.
+   *  Classification consumers (the editor's port flavor) match against leaf
+   *  capabilities, so without expansion every `Telo.Executable` slot would fall
+   *  out of both classification sets and silently stop rendering — and so would
+   *  slots constrained to the next abstract-of-abstracts. */
+  private leafCapabilitiesForRef(xTeloRef: string): string[] {
+    const cap = this.capabilityForRef(xTeloRef);
+    if (!cap) return [];
+    const leaves = this.defs
+      .getByExtends(cap)
+      .filter((d) => d.kind === "Telo.Abstract" && !d.capability)
+      .map((d) => `${(d.metadata as { module?: string }).module}.${d.metadata.name}`);
+    return leaves.length > 0 ? leaves : [cap];
+  }
+
   /**
    * Walks a manifest's annotation sites (refs, scopes, schema-from, CEL) via
    * the shared manifest visitor, bound to this registry's definitions and