@telorun/analyzer 0.52.0 → 0.54.0

package/dist/validate-module-metadata.js

@@ -0,0 +1,256 @@
+import { distance } from "./levenshtein.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Static validation of the `metadata:` block on module docs (`Telo.Application` /
+ * `Telo.Library`) and of `metadata.deprecated` wherever it appears.
+ *
+ * These fields are descriptive — nothing in the kernel branches on them — but they
+ * are the module's public face: a hub indexes them, and a consumer reads them
+ * before deciding to import. That is exactly why they need checking. A field the
+ * runtime ignores has no failure mode that would ever surface it, so a mistyped
+ * `licence:` or `deprecatd:` is invisible forever, and the module ships claiming
+ * nothing while its author believes otherwise.
+ *
+ * The vocabulary stays **open** — `metadata` accepts any key, because a publisher
+ * may carry their own — so an unknown key is only reported when it is a near-miss
+ * of a known one. That catches the typo without closing the set.
+ *
+ * **Everything here is a WARNING, and fatal only at `telo publish`** (see
+ * {@link PUBLISH_BLOCKING_CODES}). Refusing to *run* a manifest over a field no
+ * runtime reads gets the cost backwards: `version: 1.0` is a YAML float rather
+ * than a string, which is a real mistake worth reporting, but stopping the app
+ * from starting over it is worse than the mistake. Publication is the moment
+ * these fields become consequential — they are projected onto the artifact's
+ * annotations and indexed by the hub — so that is where they block.
+ */
+/**
+ * Codes that must not block running a manifest but MUST block publishing one.
+ *
+ * Kept as a set rather than a severity because the two audiences differ: a
+ * developer running a manifest wants to know, a publisher must be stopped. If a
+ * later check earns the same treatment, add its code here rather than inventing
+ * a third severity level.
+ */
+export const PUBLISH_BLOCKING_CODES = new Set([
+    "METADATA_INVALID_TYPE",
+    "METADATA_UNKNOWN_FIELD",
+    "INVALID_DEPRECATION",
+    "DEPRECATION_REPLACEMENT_UNRESOLVED",
+]);
+/** Conventional module-doc metadata, and the type each carries. Descriptive only;
+ *  `name` is the sole field anything resolves against. */
+const MODULE_METADATA_TYPES = {
+    name: "string",
+    module: "string",
+    version: "string",
+    description: "string",
+    repository: "string",
+    homepage: "string",
+    documentation: "string",
+    license: "string",
+    namespace: "string",
+    categories: "string[]",
+    deprecated: "object",
+};
+/** What a kind doc's `metadata:` may carry.
+ *
+ *  Deliberately narrower than a module's: `version`, `license` and the rest
+ *  belong to the module, and a kind restating them means nothing. `categories`
+ *  is legal and *replaces* the module's for that kind; `description` is hub
+ *  search text. Both have exactly the failure mode this file exists for — a
+ *  `descriptoin:` on a kind doc is read by nothing and reported by nothing, so
+ *  it ships silently — which is why kind docs are checked rather than exempt. */
+const KIND_METADATA_TYPES = {
+    name: "string",
+    module: "string",
+    description: "string",
+    categories: "string[]",
+    deprecated: "object",
+};
+/** Alias-qualified kind — `Self.Migrations`, `Cache.Store`, `Telo.JsonSchema`. */
+const ALIAS_KIND_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
+/** The built-in namespace, resolvable without an import — mirrors `validate-extends`. */
+const TELO_BUILTIN_ALIAS = "Telo";
+function typeOf(value) {
+    if (typeof value === "string")
+        return "string";
+    if (Array.isArray(value))
+        return value.every((v) => typeof v === "string") ? "string[]" : "other";
+    if (value !== null && typeof value === "object")
+        return "object";
+    return "other";
+}
+export function validateModuleMetadata(manifests, registry, aliases) {
+    const out = [];
+    // Docs forwarded from imported libraries carry `metadata.module` set to that
+    // library's name. Their `replacedBy` aliases — `Self`, or any alias private to
+    // that library — belong to the library's OWN scope, which the consumer's
+    // resolver knows nothing about, so re-checking them here reports a false
+    // DEPRECATION_REPLACEMENT_UNRESOLVED against a manifest the consumer does not
+    // own. They are validated when that library is analyzed as a root, which is
+    // its author's concern. Same rule, and the same reason, as `validate-extends`.
+    const importedModules = new Set();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Import")
+            continue;
+        const resolved = m.metadata
+            ?.resolvedModuleName;
+        if (resolved)
+            importedModules.add(resolved);
+    }
+    for (const manifest of manifests) {
+        const isModuleDoc = manifest.kind === "Telo.Application" || manifest.kind === "Telo.Library";
+        const isKindDoc = manifest.kind === "Telo.Definition" || manifest.kind === "Telo.Abstract";
+        if (!isModuleDoc && !isKindDoc)
+            continue;
+        const metadata = manifest.metadata;
+        if (!metadata)
+            continue;
+        const ownModule = metadata.module;
+        if (ownModule && importedModules.has(ownModule))
+            continue;
+        const name = typeof metadata.name === "string" ? metadata.name : undefined;
+        const filePath = typeof metadata.source === "string" ? metadata.source : undefined;
+        const ctx = {
+            label: `${manifest.kind}/${name ?? "(unnamed)"}`,
+            resource: { kind: manifest.kind, name },
+            filePath,
+        };
+        validateFieldTypes(metadata, isModuleDoc ? MODULE_METADATA_TYPES : KIND_METADATA_TYPES, ctx, out);
+        validateDeprecation(metadata, isModuleDoc, ctx, registry, aliases, out);
+    }
+    return out;
+}
+/** How far a key may be from a known one and still be called a typo.
+ *
+ *  Scaled, not absolute: at a flat 2, `date:` (a perfectly ordinary key an
+ *  author might carry) is two edits from `name` and gets told it is a
+ *  misspelling of it. The vocabulary is open, so a false accusation on a short
+ *  key is worse than missing a typo on one. */
+function typoThreshold(key, known) {
+    return Math.max(1, Math.floor(Math.min(key.length, known.length) / 3));
+}
+function validateFieldTypes(metadata, allowed, ctx, out) {
+    const known = Object.keys(allowed);
+    for (const [key, value] of Object.entries(metadata)) {
+        // Stamped by the loader, not authored — never a typo to report on.
+        if (key === "source")
+            continue;
+        // Listed as known so a typo still gets suggested against it, but its shape
+        // belongs to `validateDeprecation`, which can say what is actually wrong.
+        // Type-checking it here too would report one mistake twice.
+        if (key === "deprecated")
+            continue;
+        const expected = allowed[key];
+        if (expected === undefined) {
+            const near = known.find((k) => distance(key, k) <= typoThreshold(key, k));
+            if (near) {
+                out.push({
+                    severity: DiagnosticSeverity.Warning,
+                    code: "METADATA_UNKNOWN_FIELD",
+                    source: SOURCE,
+                    message: `${ctx.label}: 'metadata.${key}' is not a known field — did you mean '${near}'? ` +
+                        `Nothing reads an unrecognized key, so this declares nothing.`,
+                    data: { resource: ctx.resource, filePath: ctx.filePath, path: `metadata.${key}` },
+                });
+            }
+            continue;
+        }
+        if (typeOf(value) !== expected) {
+            out.push({
+                severity: DiagnosticSeverity.Warning,
+                code: "METADATA_INVALID_TYPE",
+                source: SOURCE,
+                message: `${ctx.label}: 'metadata.${key}' must be ${describeType(expected)}.`,
+                data: { resource: ctx.resource, filePath: ctx.filePath, path: `metadata.${key}` },
+            });
+        }
+    }
+}
+function describeType(t) {
+    if (t === "string[]")
+        return "an array of strings";
+    if (t === "object")
+        return "an object";
+    return "a string";
+}
+/**
+ * `metadata.deprecated: { reason, replacedBy? }`.
+ *
+ * `replacedBy` is deliberately resolvable rather than free text, and its form
+ * follows the level: a module doc names another **module ref** (the `imports:`
+ * source grammar), a kind doc names an **alias-qualified kind** resolved through
+ * this file's own imports — the same grammar `kind:` / `extends:` use, so the
+ * replacement is a link a consumer can follow rather than a sentence they have to
+ * interpret.
+ *
+ * A kind whose replacement lives in a module this one does not import cannot be
+ * named; that case deprecates at module level with a module ref instead. Accepted
+ * over inventing a second grammar for it.
+ */
+function validateDeprecation(metadata, isModuleDoc, ctx, registry, aliases, out) {
+    const deprecated = metadata.deprecated;
+    if (deprecated === undefined)
+        return;
+    const at = "metadata.deprecated";
+    const push = (code, message, path = at, severity = DiagnosticSeverity.Warning) => {
+        out.push({
+            severity,
+            code,
+            source: SOURCE,
+            message: `${ctx.label}: ${message}`,
+            data: { resource: ctx.resource, filePath: ctx.filePath, path },
+        });
+    };
+    if (typeOf(deprecated) !== "object") {
+        push("INVALID_DEPRECATION", `'${at}' must be an object with a 'reason' (and an optional 'replacedBy'). ` +
+            `A bare 'true' says a thing is deprecated without saying what to do instead.`);
+        return;
+    }
+    const block = deprecated;
+    const allowed = new Set(["reason", "replacedBy"]);
+    for (const key of Object.keys(block)) {
+        if (!allowed.has(key)) {
+            push("INVALID_DEPRECATION", `'${at}.${key}' is not a recognized key (reason, replacedBy).`, `${at}.${key}`);
+        }
+    }
+    if (typeof block.reason !== "string" || block.reason.trim() === "") {
+        push("INVALID_DEPRECATION", `'${at}.reason' is required and must be a non-empty string — it is what a consumer reads to know what to do instead.`, `${at}.reason`);
+    }
+    const replacedBy = block.replacedBy;
+    if (replacedBy === undefined)
+        return;
+    const path = `${at}.replacedBy`;
+    if (typeof replacedBy !== "string" || replacedBy.trim() === "") {
+        push("INVALID_DEPRECATION", `'${path}' must be a non-empty string.`, path);
+        return;
+    }
+    if (isModuleDoc) {
+        // A module is replaced by another module, addressed the way an import is.
+        // Catching alias form here is worth a dedicated message: it is the natural
+        // mistake, and it would otherwise be stored as an unresolvable ref.
+        if (ALIAS_KIND_RE.test(replacedBy)) {
+            push("INVALID_DEPRECATION", `'${path}: ${replacedBy}' looks like a kind reference, but a module doc's replacement is a ` +
+                `module ref (e.g. 'oci://ghcr.io/acme/thing'). Deprecate the kind itself to point at another kind.`, path);
+        }
+        return;
+    }
+    // Kind level: resolve through this file's imports, exactly as `extends` does.
+    if (!ALIAS_KIND_RE.test(replacedBy)) {
+        push("INVALID_DEPRECATION", `'${path}: ${replacedBy}' must be an alias-qualified kind ("<Alias>.<Kind>", ` +
+            `e.g. 'Self.Migrations'), resolved via this file's imports.`, path);
+        return;
+    }
+    const prefix = replacedBy.slice(0, replacedBy.indexOf("."));
+    if (prefix !== TELO_BUILTIN_ALIAS && !aliases.hasAlias(prefix)) {
+        push("DEPRECATION_REPLACEMENT_UNRESOLVED", `'${path}: ${replacedBy}' — alias '${prefix}' is not an import in this file's scope. ` +
+            `Declare the import or correct the alias.`, path);
+        return;
+    }
+    const canonical = aliases.resolveKind(replacedBy);
+    if (!canonical || !registry.resolve(canonical)) {
+        push("DEPRECATION_REPLACEMENT_UNRESOLVED", `'${path}: ${replacedBy}' does not resolve to a known kind. A replacement a consumer ` +
+            `cannot follow is no better than none.`, path);
+    }
+}

package/dist/validate-observed-state.d.ts

@@ -1,5 +1,6 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { type ModuleScopes } from "./alias-resolver.js";
+import type { CallGraph } from "./call-graph.js";
 /**
  * The `status:` block's own schema — a plain JSON Schema, structurally. The one
  * normative restriction (`required:` is rejected) is enforced by
@@ -45,21 +46,21 @@ export interface ObservedStateRead {
  */
 export declare function observedStateRead(chain: readonly string[]): ObservedStateRead | 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 declare function collectRunReachableNames(manifests: readonly ResourceManifest[], defs: {
-    resolve(kind: string): ResourceDefinition | undefined;
-}, aliases?: {
-    resolveKind(kind: string): string | undefined;
-}): Set<string>;
+export declare function collectRunReachableNames(graph: CallGraph): Set<string>;
 /** What a resource name resolves to for CEL purposes. `status` is present only
  *  when the kind declares one; `scoped` marks a resource declared inside an
  *  `x-telo-scope` slot, which resolves only within that scope's regions. */

package/dist/validate-observed-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-observed-state.d.ts","sourceRoot":"","sources":["../src/validate-observed-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAyBjF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;CAGjC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB3E;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC;+CAC2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,GAAG,SAAS,CAOzF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,IAAI,EAAE;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAA;CAAE,EAC/D,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,GAC1D,GAAG,CAAC,MAAM,CAAC,CAyBb;AAgDD;;4EAE4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,IAAI,EAAE;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAA;CAAE,EAC/D,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAAC,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,EAC/G,MAAM,CAAC,EAAE,YAAY,GACpB,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAsC/B;AAyDD;;;gDAGgD;AAChD,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC5C,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,IAAI,CAmBN"}
+{"version":3,"file":"validate-observed-state.d.ts","sourceRoot":"","sources":["../src/validate-observed-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAgBjD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;CAGjC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB3E;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC;+CAC2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,GAAG,SAAS,CAOzF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,CAQtE;AAGD;;4EAE4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,IAAI,EAAE;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAA;CAAE,EAC/D,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAAC,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,EAC/G,MAAM,CAAC,EAAE,YAAY,GACpB,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAsC/B;AAyDD;;;gDAGgD;AAChD,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC5C,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CASrB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,IAAI,CAmBN"}

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"}