@telorun/analyzer 0.53.0 → 0.55.0

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.53.0",
+  "version": "0.55.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.68.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analysis-registry.ts

@@ -7,6 +7,7 @@ import { visitManifest as runVisitManifest, type ManifestVisitor } from "./manif
 import type { ContractDirection, DefResolver } from "./extends-resolution.js";
 import { resolveContract } from "./invocation-contract.js";
 import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
+import { resolveSchemaTypeRefs as resolveSchemaTypeRefsIn } from "./resolve-schema-type-refs.js";
 import type { AnalysisContext } from "./types.js";
 
 /** One reference field declared by a resource's definition, derived purely from
@@ -61,6 +62,21 @@ export class AnalysisRegistry {
     return this.aliases.resolveKind(kind);
   }
 
+  /** Rewrite `telo://Self/<type>` / `telo://<Alias>/<type>` schema references in
+   *  `manifests` to the canonical id their type registered under, in the scope
+   *  each doc was declared in. Idempotent — an already-canonical ref resolves to
+   *  no module and is left alone.
+   *
+   *  `analyze()` runs this over its own view; a caller holding a separately
+   *  flattened projection (the kernel's build-time validator warm, which must
+   *  resolve a `$ref` contract exactly as the runtime will) needs it applied to
+   *  that projection too. Exposed as a method because the alias tables are this
+   *  registry's, and handing them out would make every consumer's scoping its
+   *  own problem. */
+  resolveSchemaTypeRefs(manifests: ResourceManifest[]): void {
+    resolveSchemaTypeRefsIn(manifests, this.aliases, this.aliasesByModule);
+  }
+
   /**
    * Iterates a resource's reference and scope fields as declared by its definition.
    * Calls onRef for each plain reference field and onScope for each scope field.
@@ -177,12 +193,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

package/src/analyzer.ts

@@ -22,6 +22,7 @@ import {
   PERMISSIVE_CONTRACT,
   resolveContract,
 } from "./invocation-contract.js";
+import { buildCallGraph } from "./call-graph.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import {
   buildKernelGlobalsSchema,
@@ -42,6 +43,13 @@ import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
 import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { resolveSchemaRefKinds, type RefConstraintIssue } from "./resolve-schema-ref-kinds.js";
+import { runZoneAnalysis, type ZoneExportCache } from "./resolve-zone-requirements.js";
+import { validateZoneSlotDeclarations, type ZoneSlotIssue } from "./validate-zone-slots.js";
+import {
+  validateDynamicSelectors,
+  validateRefSlotDeclarations,
+  type RefSlotIssue,
+} from "./validate-ref-slots.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
 import { validateSchemaTypeRefs } from "./validate-schema-type-refs.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
@@ -521,24 +529,76 @@ function buildStepContextSchema(
   return undefined;
 }
 
-/**
- * Capabilities whose instances structurally expose no `invoke`/`run` method, so
- * a step `invoke` of one always fails at runtime with ERR_RESOURCE_NOT_INVOKABLE
- * (kernel dispatch checks method presence, not capability — evaluation-context.ts).
- * `Telo.Service` is intentionally absent: some services are invocable (a function
- * handler dispatched directly, e.g. `Lambda.Function`), so it can't be rejected
- * statically without false positives. This is the sound subset of the runtime rule.
- */
 /** The built-in namespace: globally resolvable, crossing no import boundary. */
 const TELO_BUILTIN_MODULE = "Telo";
 
-const NON_INVOKABLE_CAPABILITIES = new Set([
-  "Telo.Provider",
+/** One mapping from a ref-slot issue to a diagnostic — the shape is identical
+ *  for the schema-level and the manifest-level (dynamic selector) checks. */
+function refSlotIssueDiagnostic(issue: RefSlotIssue): AnalysisDiagnostic {
+  return {
+    severity: DiagnosticSeverity.Error,
+    code: issue.code,
+    source: SOURCE,
+    message: issue.message,
+    data: {
+      resource: { kind: issue.manifest.kind, name: issue.manifest.metadata?.name as string },
+      filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+      path: issue.path,
+    },
+  };
+}
+
+/**
+ * Is this kind acceptable in a slot that transfers control?
+ *
+ * The executable side is a POSITIVE test against the `Telo.Executable`
+ * hierarchy: a capability that is, or `extends`, `Telo.Executable` is
+ * executable, so a future executable capability opts in with one `extends:`
+ * edge — no name list here to keep in step. This replaced
+ * `NON_INVOKABLE_CAPABILITIES`, a maintained set of capabilities the analyzer
+ * believed could never be invoked, which was unsound in the direction that
+ * rejects working manifests: it listed `Telo.Provider`, and `Ai.Model` is a
+ * Provider the agent controller invokes directly — the divergence being
+ * structural versus nominal, since the kernel tests method presence at dispatch
+ * while any static test can only read a declared capability.
+ *
+ * Outside the hierarchy nothing is guessed: `Telo.Provider` (entry points by
+ * convention) and `Telo.Service` (some services are invocable) pass, an unknown
+ * capability passes (rejecting it would be the wrong polarity for third-party
+ * extensions), and only the kernel-owned capabilities whose CONTRACT has no
+ * entry point — `Telo.Type`, `Telo.Mount`, `Telo.Template`, `Telo.Sink` (a sink
+ * is written to through a direct contract on the controller instance, never
+ * dispatched) — are rejected. That last set is the capabilities' own
+ * definition, not a belief about controllers.
+ */
+function isExecutableKind(kind: string, defs: DefinitionRegistry, aliases: AliasResolver): boolean {
+  const canonical = aliases.resolveKind(kind) ?? kind;
+  const def = defs.resolve(canonical);
+  if (!def) return true;
+  const capability = def.capability as string | undefined;
+  if (!capability) return true;
+  if (capabilityExtendsExecutable(capability, defs)) return true;
+  return !NO_ENTRY_POINT_CAPABILITIES.has(capability);
+}
+
+/** Does this capability name `Telo.Executable` or extend it, transitively?
+ *  Derived from the abstract hierarchy at call time, never from a name list. */
+function capabilityExtendsExecutable(capability: string, defs: DefinitionRegistry): boolean {
+  let current: string | undefined = capability;
+  const seen = new Set<string>();
+  while (current && !seen.has(current)) {
+    if (current === "Telo.Executable") return true;
+    seen.add(current);
+    current = defs.resolve(current)?.extends as string | undefined;
+  }
+  return false;
+}
+
+/** Kernel-owned capabilities whose contract declares no entry point. */
+const NO_ENTRY_POINT_CAPABILITIES = new Set([
   "Telo.Mount",
   "Telo.Type",
   "Telo.Template",
-  // A sink is written to through a direct contract on the controller instance,
-  // never dispatched — so invoking one is statically wrong.
   "Telo.Sink",
 ]);
 
@@ -557,9 +617,10 @@ const NON_INVOKABLE_CAPABILITIES = new Set([
  *     *kind* instead of an exported instance (`!ref Stream.Of`) — is a still-a-
  *     sentinel after Phase 2.5 resolution → `UNRESOLVED_REFERENCE` (runtime
  *     `ERR_RESOURCE_NOT_FOUND`).
- *   - Invokability: a resolved instance whose capability structurally has no
- *     invoke/run method (`NON_INVOKABLE_CAPABILITIES`) → `REFERENCE_KIND_MISMATCH`
- *     (runtime `ERR_RESOURCE_NOT_INVOKABLE`).
+ *   - Invokability: a resolved instance whose kind fails `isExecutableKind` —
+ *     outside the `Telo.Executable` hierarchy AND declaring a capability whose
+ *     contract has no entry point → `REFERENCE_KIND_MISMATCH` (runtime
+ *     `ERR_RESOURCE_NOT_INVOKABLE`).
  *
  * Generic and topology-driven — it walks steps via the same `x-telo-step-context`
  * / `x-telo-topology-role` annotations `buildStepContextSchema` uses (through the
@@ -656,15 +717,13 @@ function validateStepInvokeReferences(
     // Resolved `{kind, name}` (or an inline `{kind, …}` definition) — the
     // instance exists. Mirror the kernel's ERR_RESOURCE_NOT_INVOKABLE, which
     // fires when the instance has neither an `invoke` nor a `run` method
-    // (evaluation-context.ts). That is a per-instance property, not a pure
-    // capability, so only capabilities that STRUCTURALLY expose no such method
-    // are rejected statically — Service is intentionally excluded, since some
-    // services are invocable (e.g. a function handler dispatched directly).
+    // (evaluation-context.ts). That is a per-instance property, so the static
+    // test only rejects a kind whose declared capability names no entry point.
     if (!value || typeof value !== "object" || Array.isArray(value)) return;
     const kind = (value as Record<string, unknown>).kind;
     if (typeof kind !== "string") return;
-    const capability = defs.resolve(aliases.resolveKind(kind) ?? kind)?.capability;
-    if (typeof capability === "string" && NON_INVOKABLE_CAPABILITIES.has(capability)) {
+    if (!isExecutableKind(kind, defs, aliases)) {
+      const capability = defs.resolve(aliases.resolveKind(kind) ?? kind)?.capability;
       diagnostics.push({
         severity: DiagnosticSeverity.Error,
         code: "REFERENCE_KIND_MISMATCH",
@@ -986,6 +1045,7 @@ export class StaticAnalyzer {
     manifests: ResourceManifest[],
     options?: AnalysisOptions,
     registry?: AnalysisRegistry,
+    zoneExportCache?: ZoneExportCache,
   ): AnalysisDiagnostic[] {
     assertManifestPositions(manifests);
     const diagnostics: AnalysisDiagnostic[] = [];
@@ -1164,6 +1224,8 @@ export class StaticAnalyzer {
     // of alias choices. `capability` covers the legacy implements-this-abstract overload;
     // `extends` is the canonical first-class form.
     const refConstraintIssues: RefConstraintIssue[] = [];
+    const refSlotIssues: RefSlotIssue[] = [];
+    const zoneSlotIssues: ZoneSlotIssue[] = [];
     for (const m of manifests) {
       if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
       const def = m as unknown as ResourceDefinition;
@@ -1180,10 +1242,38 @@ export class StaticAnalyzer {
       // still on the deprecated form — or with a constraint that no longer
       // resolves — is not the consumer's to fix, and every import would
       // otherwise flood `telo check` with unactionable noise.
-      if (!ownModule || rootModules.has(ownModule)) refConstraintIssues.push(...issues);
+      if (!ownModule || rootModules.has(ownModule)) {
+        refConstraintIssues.push(...issues);
+        refSlotIssues.push(...validateRefSlotDeclarations(m as unknown as ResourceManifest));
+        zoneSlotIssues.push(...validateZoneSlotDeclarations(m as unknown as ResourceManifest));
+      }
       const resolvedCapability = def.capability
         ? (scopeResolver.resolveKind(def.capability) ?? def.capability)
         : def.capability;
+      // `Telo.Executable` is a slot constraint — the x-telo-ref parent of
+      // Invocable and Runnable — and names no lifecycle role. The kernel
+      // rejects it at load; without this the analyzer would report "no issues"
+      // on a manifest that cannot boot.
+      if (
+        resolvedCapability === "Telo.Executable" &&
+        (!ownModule || rootModules.has(ownModule))
+      ) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "CAPABILITY_NOT_DECLARABLE",
+          source: SOURCE,
+          message:
+            `'${def.metadata?.name}' declares capability: Telo.Executable, which is an ` +
+            `x-telo-ref slot constraint (the parent Telo.Invocable and Telo.Runnable extend), ` +
+            `not a declarable lifecycle role. Declare 'Telo.Invocable' (invoke) or ` +
+            `'Telo.Runnable' (run) instead.`,
+          data: {
+            resource: { kind: m.kind, name: m.metadata?.name as string },
+            filePath: (m.metadata as { source?: string } | undefined)?.source,
+            path: "capability",
+          },
+        });
+      }
       const resolvedExtends = def.extends
         ? (scopeResolver.resolveKind(def.extends) ?? def.extends)
         : def.extends;
@@ -1213,6 +1303,24 @@ export class StaticAnalyzer {
         };
         const filePath = (issue.manifest.metadata as { source?: string } | undefined)?.source;
         const data = { resource, filePath, path: issue.path };
+        if (issue.annotation === "zone") {
+          // Mirrors X_TELO_REF_UNRESOLVED: an unresolvable provider kind would
+          // leave the requirement silently unenforced — no provider ever
+          // matches a kind that does not exist.
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "ZONE_PROVIDER_UNRESOLVED",
+            source: SOURCE,
+            message:
+              `x-telo-requires-zone '${issue.ref}' at '${issue.path}' names no kind. The prefix ` +
+              `must be an import alias declared in this file's 'imports:' map, 'Self' for a kind ` +
+              `in this library, or 'Telo' for a built-in. An unresolvable zone would leave the ` +
+              `requirement silently unenforced. Known aliases: ` +
+              `${issue.knownAliases?.join(", ") || "(none)"}.`,
+            data,
+          });
+          continue;
+        }
         if (issue.reason === "legacy") {
           diagnostics.push({
             severity: DiagnosticSeverity.Warning,
@@ -1253,6 +1361,30 @@ export class StaticAnalyzer {
         }
       }
       diagnostics.push(...validateReferenceForms(manifests, defs, aliases, aliasesByModule));
+      // The x-telo-ref annotation's own validity — the strict half of the
+      // accessor split; `readRefSlot` stays lenient so surfaces keep working
+      // mid-migration, and this reports what leniency would silently absorb.
+      for (const issue of refSlotIssues) diagnostics.push(refSlotIssueDiagnostic(issue));
+      // Same split for the two zone annotations. Unreadable ones fail in
+      // OPPOSITE directions — a dropped requirement is silently unenforced, a
+      // dropped provision invents failures — so neither can be left to
+      // leniency.
+      for (const issue of zoneSlotIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+          },
+        });
+      }
     }
 
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
@@ -1264,6 +1396,55 @@ export class StaticAnalyzer {
     // original and inline-extracted manifests have their sentinels resolved.
     resolveRefSentinels(allManifests, aliases, aliasesByModule, [], defs);
 
+    // ONE typed reference graph per analysis. Both graph consumers in this
+    // pass (the dynamic-selector check and run-reachability) read the same
+    // build — constructing it per consumer is strictly more work than the
+    // walks it replaced, and performance is a core goal. Lazy, so a
+    // skipValidation pass with no observed state builds nothing.
+    let callGraphMemo: ReturnType<typeof buildCallGraph> | undefined;
+    const getCallGraph = () =>
+      (callGraphMemo ??= buildCallGraph(allManifests as unknown as ResourceManifest[], defs, {
+        aliases,
+        aliasesByModule,
+      }));
+
+    // A `use` case map's selector written in CEL is a hard diagnostic — a call
+    // graph known only at runtime is not statically analyzable, and no fallback
+    // is conservative for every consumer. Scoped to the entry's own modules:
+    // a published dependency's manifest is not the consumer's to fix.
+    if (!options?.skipValidation) {
+      for (const issue of validateDynamicSelectors(
+        allManifests as unknown as ResourceManifest[],
+        defs,
+        aliases,
+        aliasesByModule,
+        getCallGraph(),
+      )) {
+        const ownModule = (issue.manifest.metadata as { module?: string } | undefined)?.module;
+        if (ownModule && !rootModules.has(ownModule)) continue;
+        diagnostics.push(refSlotIssueDiagnostic(issue));
+      }
+
+      // Zone requirements — a projection over the same graph: propagate along
+      // `call` edges, discharge at providing slots under correlation, fire at
+      // terminating edges and boot. Imported libraries' export contracts are
+      // derived over their full documents (options.moduleDocuments — the
+      // flattened view no longer holds their internal dispatch chains), cached
+      // per library in the host-lifetime `zoneExportCache`.
+      diagnostics.push(
+        ...runZoneAnalysis({
+          manifests: allManifests as unknown as ResourceManifest[],
+          graph: getCallGraph(),
+          defs,
+          aliases,
+          aliasesByModule,
+          rootModules,
+          moduleDocuments: options?.moduleDocuments,
+          cache: zoneExportCache,
+        }),
+      );
+    }
+
     // Phase 2.6: register each named `Telo.Type` resource's schema under its
     // canonical module-scoped id (`telo://<module>/<name>`), validate
     // `telo://Self|Alias/Type` schema refs resolve to one, then rewrite those
@@ -1427,7 +1608,7 @@ export class StaticAnalyzer {
     const observedState = buildObservedStateIndex(allManifests, defs, aliases, moduleScopes);
     const reportsObservedState = [...observedState.values()].some((r) => r.status);
     const runReachable = reportsObservedState
-      ? collectRunReachableNames(allManifests, defs, aliases)
+      ? collectRunReachableNames(getCallGraph())
       : new Set<string>();
 
     // Build typed kernel globals schema so x-telo-context chain validation
@@ -2158,8 +2339,9 @@ export class StaticAnalyzer {
     manifests: ResourceManifest[],
     options?: AnalysisOptions,
     registry?: AnalysisRegistry,
+    zoneExportCache?: ZoneExportCache,
   ): AnalysisDiagnostic[] {
-    return this.analyze(manifests, options, registry).filter(
+    return this.analyze(manifests, options, registry, zoneExportCache).filter(
       (d) => d.severity === DiagnosticSeverity.Error,
     );
   }

package/src/builtins.ts

@@ -145,7 +145,9 @@ const ROOT_LOGGING_SCHEMA = {
       type: "array",
       items: {
         type: "object",
-        "x-telo-ref": "Telo.LogSink",
+        // A sink is written to directly by the logging pipeline, never through
+        // `ctx.invoke` — so from the Application's side it is held, not called.
+        "x-telo-ref": { kind: "Telo.LogSink", use: "dependency" },
         "x-telo-inline": true,
       },
     },
@@ -155,9 +157,22 @@ const ROOT_LOGGING_SCHEMA = {
 
 export const KERNEL_BUILTINS: ResourceDefinition[] = [
   { kind: "Telo.Abstract", metadata: { name: "Template", module: "Telo" } },
-  { kind: "Telo.Abstract", metadata: { name: "Runnable", module: "Telo" } },
+  // "Control can be transferred to this" — the parent of Invocable and Runnable,
+  // and the only thing a slot that accepts either needs to say. It is a SLOT
+  // CONSTRAINT, never a lifecycle role: `capability: Telo.Executable` is rejected
+  // because it is absent from the kernel's `KNOWN_CAPABILITIES` enum, which is
+  // what keeps "what a resource is" and "what a slot does with it" separate.
+  //
+  // `Telo.Service` is deliberately NOT under it. A Service's `run()` is a
+  // lifecycle start the kernel dispatches differently (no ambient scope, so
+  // inbound work roots its own trace), and admitting it here would make every
+  // step's `invoke:` slot accept a service. Boot-target slots that genuinely take
+  // `Runnable | Service` stay kind lists — the honest shape for a heterogeneous
+  // set.
+  { kind: "Telo.Abstract", metadata: { name: "Executable", module: "Telo" } },
+  { kind: "Telo.Abstract", metadata: { name: "Runnable", module: "Telo" }, extends: "Telo.Executable" },
   { kind: "Telo.Abstract", metadata: { name: "Service", module: "Telo" } },
-  { kind: "Telo.Abstract", metadata: { name: "Invocable", module: "Telo" } },
+  { kind: "Telo.Abstract", metadata: { name: "Invocable", module: "Telo" }, extends: "Telo.Executable" },
   { kind: "Telo.Abstract", metadata: { name: "Mount", module: "Telo" } },
   { kind: "Telo.Abstract", metadata: { name: "Type", module: "Telo" } },
   {
@@ -558,12 +573,16 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           "x-telo-step-context": { invoke: "invoke", outputType: "outputType" },
           type: "array",
           items: {
+            // A genuinely heterogeneous set stays a kind list: `Telo.Service` is
+            // deliberately outside `Telo.Executable`, since a service's `run()`
+            // is a lifecycle start the kernel dispatches without an ambient
+            // scope.
+            "x-telo-ref": { kind: ["Telo.Runnable", "Telo.Service"], use: "call" },
             anyOf: [
-              { type: "string", "x-telo-ref": "Telo.Runnable" },
-              { type: "string", "x-telo-ref": "Telo.Service" },
+              { type: "string" },
               // Post-resolution shape that `resolveRefSentinels`
               // substitutes a `!ref <name>` sentinel into. The
-              // adjacent `x-telo-ref` constraints govern the kind
+              // adjacent `x-telo-ref` constraint governs the kind
               // check; this branch only admits the structural form so
               // AJV doesn't reject a resolved ref.
               {
@@ -583,9 +602,9 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                 required: ["ref"],
                 properties: {
                   ref: {
+                    "x-telo-ref": { kind: ["Telo.Runnable", "Telo.Service"], use: "call" },
                     anyOf: [
-                      { type: "string", "x-telo-ref": "Telo.Runnable" },
-                      { type: "string", "x-telo-ref": "Telo.Service" },
+                      { type: "string" },
                       {
                         type: "object",
                         required: ["kind", "name"],
@@ -617,6 +636,11 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                   name: { type: "string" },
                   invoke: {
                     "x-telo-topology-role": "invoke",
+                    "x-telo-ref": {
+                      kind: "Telo.Executable",
+                      use: "call",
+                      inputs: "/inputs",
+                    },
                     type: "object",
                     required: ["kind", "name"],
                     properties: {
@@ -624,10 +648,6 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                       name: { type: "string" },
                     },
                     additionalProperties: true,
-                    anyOf: [
-                      { "x-telo-ref": "Telo.Invocable" },
-                      { "x-telo-ref": "Telo.Runnable" },
-                    ],
                   },
                   inputs: {
                     // Same annotation Run.Sequence steps carry: it is what makes