@telorun/analyzer 0.11.0 → 0.12.0

package/dist/reference-field-map.js

@@ -26,25 +26,30 @@ export function isInlineResource(val) {
         return false;
     return true;
 }
-/** Resolves all values at a field map path in a resource config.
- *  Path-segment markers:
- *   - `[]`  iterate array values at this key
+/** Resolves all `{value, path}` entries at a field map path in a resource
+ *  config. The returned `path` is the concrete dotted path produced by the
+ *  substitutions below, matching the format `buildPositionIndex` keys on.
+ *  Path-segment markers accepted in the input `path`:
+ *   - `[]`  iterate array values at this key, substituting `[N]` per item
+ *           (e.g. `routes[]` → `routes[0]`, `routes[1]`, …).
  *   - `{}`  iterate map values (every value in an `additionalProperties`-typed
  *           object — used for fields like `content[mime]` whose schema declares
- *           a key-as-MIME map). The path is `<key>.{}.<rest>`. */
-export function resolveFieldValues(obj, path) {
+ *           a key-as-MIME map). Substituted with the literal map key joined by
+ *           a dot, so the input `content.{}.encoder` yields concrete paths
+ *           like `content.application/json.encoder`. */
+export function resolveFieldEntries(obj, path) {
     const parts = path.split(".");
-    let current = [obj];
+    let current = [{ value: obj, path: "" }];
     for (const part of parts) {
         if (part === "{}") {
-            // Iterate the values of every map currently in `current`.
             const next = [];
-            for (const item of current) {
-                if (!item || typeof item !== "object")
+            for (const entry of current) {
+                if (!entry.value || typeof entry.value !== "object")
                     continue;
-                for (const v of Object.values(item)) {
-                    if (v != null)
-                        next.push(v);
+                for (const [k, v] of Object.entries(entry.value)) {
+                    if (v != null) {
+                        next.push({ value: v, path: entry.path ? `${entry.path}.${k}` : k });
+                    }
                 }
             }
             current = next;
@@ -53,21 +58,32 @@ export function resolveFieldValues(obj, path) {
         const isArray = part.endsWith("[]");
         const key = isArray ? part.slice(0, -2) : part;
         const next = [];
-        for (const item of current) {
-            if (!item || typeof item !== "object")
+        for (const entry of current) {
+            if (!entry.value || typeof entry.value !== "object")
                 continue;
-            const val = item[key];
+            const val = entry.value[key];
             if (val == null)
                 continue;
-            if (isArray && Array.isArray(val))
-                next.push(...val);
-            else if (!isArray)
-                next.push(val);
+            const basePath = entry.path ? `${entry.path}.${key}` : key;
+            if (isArray && Array.isArray(val)) {
+                for (let i = 0; i < val.length; i++) {
+                    if (val[i] != null)
+                        next.push({ value: val[i], path: `${basePath}[${i}]` });
+                }
+            }
+            else if (!isArray) {
+                next.push({ value: val, path: basePath });
+            }
         }
         current = next;
     }
     return current;
 }
+/** Backwards-compat wrapper that drops the concrete path. Prefer
+ *  `resolveFieldEntries` for new code that wants positions. */
+export function resolveFieldValues(obj, path) {
+    return resolveFieldEntries(obj, path).map((e) => e.value);
+}
 /**
  * Traverses a definition's JSON Schema once and returns a field map recording every
  * x-telo-ref slot and every x-telo-scope slot.
@@ -82,7 +98,7 @@ export function buildReferenceFieldMap(schema) {
     const map = new Map();
     if (schema.properties) {
         for (const [key, propSchema] of Object.entries(schema.properties)) {
-            traverseNode(propSchema, key, map);
+            traverseNode(propSchema, key, map, schema);
         }
     }
     return map;
@@ -107,10 +123,23 @@ function collectRefs(node) {
  *  hid behind the schema-from indirection. */
 export function buildFieldMapAtPath(schema, pathPrefix) {
     const map = new Map();
-    traverseNode(schema, pathPrefix, map);
+    traverseNode(schema, pathPrefix, map, schema);
     return map;
 }
-function traverseNode(node, path, map) {
+function traverseNode(node, path, map, root, visitedRefs = new Set()) {
+    // Local `$ref` is intentionally NOT followed. Descending into shared
+    // `$defs` (notably `Run.Sequence`'s `step` definition) would surface
+    // ref slots like `steps[].invoke` that Phase 5 then injects live
+    // instances into; today's `Run.Sequence` controller calls
+    // `instance.invoke()` directly when handed an instance, bypassing
+    // the kernel's `runInvoke` emit-Invoked path. The walker fix and the
+    // dispatcher fix need to land together — see the follow-up in
+    // [kernel/nodejs/plans/reference-syntax-unification.md] and the
+    // stopgap in `resource-context.ts:resolveChildren`. `visitedRefs`
+    // stays as a parameter so the recursive calls below thread the right
+    // signature; turning the descent back on is a single-branch change.
+    if (typeof node?.$ref === "string")
+        return;
     // Scope slot — record and stop; do not recurse into scope contents
     if ("x-telo-scope" in node) {
         map.set(path, { scope: node["x-telo-scope"] });
@@ -132,12 +161,32 @@ function traverseNode(node, path, map) {
     }
     // Array — recurse into items
     if (node.type === "array" && node.items) {
-        traverseNode(node.items, path + "[]", map);
+        traverseNode(node.items, path + "[]", map, root, visitedRefs);
     }
     // Object — recurse into properties
     if (node.properties) {
         for (const [key, propSchema] of Object.entries(node.properties)) {
-            traverseNode(propSchema, `${path}.${key}`, map);
+            traverseNode(propSchema, `${path}.${key}`, map, root, visitedRefs);
+        }
+    }
+    // Variant branches — descend into every alternative's properties / items.
+    // Schemas that discriminate on shape (Run.Sequence's step kinds:
+    // `oneOf: [{properties: {invoke}}, {properties: {try}}, ...]`) hide ref
+    // slots inside the branch. Walking each branch surfaces those slots into
+    // the field map so downstream passes (ref validation, sentinel
+    // resolution, dependency graph) cover them without a runtime fallback.
+    // The same field path may be added by multiple branches; the later
+    // assignment wins, which is fine — branches with the same field path
+    // share the same ref/context configuration (any divergence is already
+    // a schema bug).
+    for (const variantKey of ["oneOf", "anyOf", "allOf"]) {
+        const variants = node[variantKey];
+        if (!Array.isArray(variants))
+            continue;
+        for (const variant of variants) {
+            if (!variant || typeof variant !== "object")
+                continue;
+            traverseVariant(variant, path, map, root, visitedRefs);
         }
     }
     // Map — `additionalProperties: { ... }` describes every value in an
@@ -146,6 +195,25 @@ function traverseNode(node, path, map) {
     if (node.additionalProperties &&
         typeof node.additionalProperties === "object" &&
         !Array.isArray(node.additionalProperties)) {
-        traverseNode(node.additionalProperties, `${path}.{}`, map);
+        traverseNode(node.additionalProperties, `${path}.{}`, map, root, visitedRefs);
+    }
+}
+/** Walk a single variant of a `oneOf` / `anyOf` / `allOf` branch. Only
+ *  the properties / items / map slots are followed — collectRefs at the
+ *  variant root is handled by the parent's `collectRefs(node)` already
+ *  (anyOf of x-telo-ref branches is the canonical multi-ref shape). */
+function traverseVariant(variant, path, map, root, visitedRefs = new Set()) {
+    if (variant.properties) {
+        for (const [key, propSchema] of Object.entries(variant.properties)) {
+            traverseNode(propSchema, `${path}.${key}`, map, root, visitedRefs);
+        }
+    }
+    if (variant.type === "array" && variant.items) {
+        traverseNode(variant.items, path + "[]", map, root, visitedRefs);
+    }
+    if (variant.additionalProperties &&
+        typeof variant.additionalProperties === "object" &&
+        !Array.isArray(variant.additionalProperties)) {
+        traverseNode(variant.additionalProperties, `${path}.{}`, map, root, visitedRefs);
     }
 }

package/dist/residual-schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build the residual JSON Schema for a `variables` / `secrets` entry.
+ *
+ * For Telo.Application env-binding entries (those with an `env:` key), strips
+ * the kernel-specific wrapper keys `env` and `default` — `default` here is
+ * the *fallback host value* the kernel coerces when the env var is unset, not
+ * a JSON Schema annotation, so it must not leak into the validator.
+ *
+ * For Telo.Library entries (no `env:`), passes the entry through unchanged.
+ * Library `default:` is a standard JSON Schema annotation and stays.
+ *
+ * Single source of truth for "residual schema" referenced by both the
+ * analyzer's CEL globals normalization and the kernel's runtime env-var
+ * resolver — keeping them aligned prevents the two surfaces from drifting.
+ */
+export declare function residualEntrySchema(entry: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Apply `residualEntrySchema` to every entry in a `variables` / `secrets` map.
+ * Returns a property-map suitable for use as the inner schema of CEL's
+ * `variables` / `secrets` namespaces.
+ */
+export declare function residualEntrySchemaMap(entries: Record<string, unknown> | null | undefined): Record<string, Record<string, unknown>>;
+//# sourceMappingURL=residual-schema.d.ts.map

package/dist/residual-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"residual-schema.d.ts","sourceRoot":"","sources":["../src/residual-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAClD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAWzC"}

package/dist/residual-schema.js

@@ -0,0 +1,45 @@
+/**
+ * Build the residual JSON Schema for a `variables` / `secrets` entry.
+ *
+ * For Telo.Application env-binding entries (those with an `env:` key), strips
+ * the kernel-specific wrapper keys `env` and `default` — `default` here is
+ * the *fallback host value* the kernel coerces when the env var is unset, not
+ * a JSON Schema annotation, so it must not leak into the validator.
+ *
+ * For Telo.Library entries (no `env:`), passes the entry through unchanged.
+ * Library `default:` is a standard JSON Schema annotation and stays.
+ *
+ * Single source of truth for "residual schema" referenced by both the
+ * analyzer's CEL globals normalization and the kernel's runtime env-var
+ * resolver — keeping them aligned prevents the two surfaces from drifting.
+ */
+export function residualEntrySchema(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return { type: "object", additionalProperties: true };
+    }
+    const isAppEnvBinding = "env" in entry;
+    const out = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (isAppEnvBinding && (key === "env" || key === "default"))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Apply `residualEntrySchema` to every entry in a `variables` / `secrets` map.
+ * Returns a property-map suitable for use as the inner schema of CEL's
+ * `variables` / `secrets` namespaces.
+ */
+export function residualEntrySchemaMap(entries) {
+    const out = {};
+    if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+        return out;
+    }
+    for (const [name, value] of Object.entries(entries)) {
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            out[name] = residualEntrySchema(value);
+        }
+    }
+    return out;
+}

package/dist/resolve-ref-sentinels.d.ts

@@ -0,0 +1,27 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+/**
+ * Walks every `x-telo-ref` slot in every non-system resource and rewrites
+ * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ *
+ * The downstream pipeline (inline normalization, dependency graph, kernel
+ * controllers) expects every ref-slot value to be either a `{kind, name}`
+ * object, an inline-definition object, or a legacy bare string — resolving
+ * sentinels here keeps that contract intact so each consumer doesn't need
+ * its own sentinel branch.
+ *
+ * The walker assigns `kind` by name lookup (resource names are unique
+ * within a manifest scope). When the name doesn't resolve in the local
+ * `byName` map, the sentinel is left in place so `validateReferences`
+ * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ *
+ * Mutation strategy: the field-path walker descends the resource tree
+ * directly and replaces the sentinel on its parent container. Re-parsing
+ * a string-encoded concrete path (the earlier shape) coupled the writer
+ * to the path-encoding rules of `resolveFieldEntries` — any new path
+ * marker would silently break this writer. Descending directly avoids
+ * that coupling.
+ */
+export declare function resolveRefSentinels(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): void;
+//# sourceMappingURL=resolve-ref-sentinels.d.ts.map

package/dist/resolve-ref-sentinels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-ref-sentinels.d.ts","sourceRoot":"","sources":["../src/resolve-ref-sentinels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,IAAI,CAsBN"}

package/dist/resolve-ref-sentinels.js

@@ -0,0 +1,114 @@
+import { isRefSentinel } from "@telorun/templating";
+import { isRefEntry } from "./reference-field-map.js";
+import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+/**
+ * Walks every `x-telo-ref` slot in every non-system resource and rewrites
+ * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ *
+ * The downstream pipeline (inline normalization, dependency graph, kernel
+ * controllers) expects every ref-slot value to be either a `{kind, name}`
+ * object, an inline-definition object, or a legacy bare string — resolving
+ * sentinels here keeps that contract intact so each consumer doesn't need
+ * its own sentinel branch.
+ *
+ * The walker assigns `kind` by name lookup (resource names are unique
+ * within a manifest scope). When the name doesn't resolve in the local
+ * `byName` map, the sentinel is left in place so `validateReferences`
+ * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ *
+ * Mutation strategy: the field-path walker descends the resource tree
+ * directly and replaces the sentinel on its parent container. Re-parsing
+ * a string-encoded concrete path (the earlier shape) coupled the writer
+ * to the path-encoding rules of `resolveFieldEntries` — any new path
+ * marker would silently break this writer. Descending directly avoids
+ * that coupling.
+ */
+export function resolveRefSentinels(resources, registry, aliases, aliasesByModule) {
+    const byName = new Map();
+    for (const r of resources) {
+        if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
+            byName.set(r.metadata.name, r);
+        }
+    }
+    for (const r of resources) {
+        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
+            continue;
+        const fieldMap = aliases && aliasesByModule
+            ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
+            : registry.getFieldMapForKind(r.kind, aliases);
+        if (!fieldMap)
+            continue;
+        for (const [fieldPath, entry] of fieldMap) {
+            if (!isRefEntry(entry))
+                continue;
+            replaceSentinelsAtPath(r, fieldPath, byName);
+        }
+    }
+}
+/** Walks `obj` along `fieldPath` (dot notation with `[]` for arrays and
+ *  `{}` for additionalProperties-typed maps) and replaces any `!ref`
+ *  sentinel value at the terminal slot with `{kind, name}` looked up
+ *  via `byName`. Mutates the parent container in place; no string-path
+ *  round-trip. */
+function replaceSentinelsAtPath(obj, fieldPath, byName) {
+    const parts = fieldPath.split(".");
+    descend(obj, parts, byName);
+}
+function descend(obj, parts, byName) {
+    if (obj == null || typeof obj !== "object" || parts.length === 0)
+        return;
+    const [head, ...rest] = parts;
+    // Map iteration: descend into every value of the current object.
+    if (head === "{}") {
+        const container = obj;
+        for (const key of Object.keys(container)) {
+            const child = container[key];
+            if (rest.length === 0) {
+                if (isRefSentinel(child)) {
+                    const target = byName.get(child.source);
+                    if (target)
+                        container[key] = { kind: target.kind, name: child.source };
+                }
+            }
+            else {
+                descend(child, rest, byName);
+            }
+        }
+        return;
+    }
+    const isArr = head.endsWith("[]");
+    const key = isArr ? head.slice(0, -2) : head;
+    const container = obj;
+    const val = container[key];
+    if (val == null)
+        return;
+    if (isArr) {
+        if (!Array.isArray(val))
+            return;
+        for (let i = 0; i < val.length; i++) {
+            if (rest.length === 0) {
+                const elem = val[i];
+                if (isRefSentinel(elem)) {
+                    const target = byName.get(elem.source);
+                    if (target)
+                        val[i] = { kind: target.kind, name: elem.source };
+                }
+            }
+            else {
+                descend(val[i], rest, byName);
+            }
+        }
+    }
+    else {
+        if (rest.length === 0) {
+            if (isRefSentinel(val)) {
+                const target = byName.get(val.source);
+                if (target)
+                    container[key] = { kind: target.kind, name: val.source };
+            }
+        }
+        else {
+            descend(val, rest, byName);
+        }
+    }
+}

package/dist/rewrite-synthetic-origins.d.ts

@@ -0,0 +1,10 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AnalysisDiagnostic } from "./types.js";
+/** Diagnostics emitted on synthetic manifests (resources extracted by
+ *  `normalizeInlineResources`) carry the synthetic's identity in
+ *  `data.resource`, which has no YAML source. Rewrite each such diagnostic
+ *  back to the chain root: walk up `metadata.xTeloOrigin` until a manifest
+ *  with no origin is reached, and prepend each hop's `pathFromParent` to
+ *  `data.path` so position-index lookups against the root doc resolve. */
+export declare function rewriteSyntheticOrigins(diagnostics: AnalysisDiagnostic[], manifests: ResourceManifest[]): AnalysisDiagnostic[];
+//# sourceMappingURL=rewrite-synthetic-origins.d.ts.map

package/dist/rewrite-synthetic-origins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite-synthetic-origins.d.ts","sourceRoot":"","sources":["../src/rewrite-synthetic-origins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAsBrD;;;;;0EAK0E;AAC1E,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,kBAAkB,EAAE,EACjC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,kBAAkB,EAAE,CA0CtB"}

package/dist/rewrite-synthetic-origins.js

@@ -0,0 +1,55 @@
+function readOrigin(manifest) {
+    if (!manifest)
+        return undefined;
+    const origin = manifest.metadata?.xTeloOrigin;
+    if (!origin ||
+        typeof origin.parentKind !== "string" ||
+        typeof origin.parentName !== "string" ||
+        typeof origin.pathFromParent !== "string") {
+        return undefined;
+    }
+    return origin;
+}
+/** Diagnostics emitted on synthetic manifests (resources extracted by
+ *  `normalizeInlineResources`) carry the synthetic's identity in
+ *  `data.resource`, which has no YAML source. Rewrite each such diagnostic
+ *  back to the chain root: walk up `metadata.xTeloOrigin` until a manifest
+ *  with no origin is reached, and prepend each hop's `pathFromParent` to
+ *  `data.path` so position-index lookups against the root doc resolve. */
+export function rewriteSyntheticOrigins(diagnostics, manifests) {
+    const byName = new Map();
+    for (const m of manifests) {
+        const name = m.metadata?.name;
+        if (typeof name === "string")
+            byName.set(name, m);
+    }
+    return diagnostics.map((d) => {
+        const data = d.data;
+        if (!data?.resource?.name)
+            return d;
+        let current = byName.get(data.resource.name);
+        let origin = readOrigin(current);
+        if (!origin)
+            return d;
+        let accumPath = typeof data.path === "string" ? data.path : "";
+        let rootKind = origin.parentKind;
+        let rootName = origin.parentName;
+        while (origin) {
+            accumPath = accumPath ? `${origin.pathFromParent}.${accumPath}` : origin.pathFromParent;
+            rootKind = origin.parentKind;
+            rootName = origin.parentName;
+            current = byName.get(origin.parentName);
+            origin = readOrigin(current);
+        }
+        const rootFilePath = current?.metadata?.source ?? data.filePath;
+        return {
+            ...d,
+            data: {
+                ...data,
+                resource: { kind: rootKind, name: rootName },
+                filePath: rootFilePath,
+                path: accumPath,
+            },
+        };
+    });
+}

package/dist/schema-compat.d.ts

@@ -1,6 +1,12 @@
 declare const Ajv: any;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
- *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+ *  Also registers the kernel manifest root schema under `telo://manifest` so
+ *  module YAMLs can `$ref` into the shared `$defs/ResourceRef` (and any future
+ *  shared fragments) from this analyzer's AJV without each module having to
+ *  bundle its own copy.
+ *
+ *  Called once for the module-level instance and once per
+ *  DefinitionRegistry instance. */
 export declare function createAjv(): InstanceType<typeof Ajv>;
 export interface CompatibilityResult {
     compatible: boolean;

package/dist/schema-compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;0FAC0F;AAC1F,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAMpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAe/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AA2BD;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CA2BT"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAOpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAe/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AA2BD;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAqCT"}

package/dist/schema-compat.js

@@ -1,14 +1,21 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isTaggedSentinel } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema } from "@telorun/templating";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
- *  Called once for the module-level instance and once per DefinitionRegistry instance. */
+ *  Also registers the kernel manifest root schema under `telo://manifest` so
+ *  module YAMLs can `$ref` into the shared `$defs/ResourceRef` (and any future
+ *  shared fragments) from this analyzer's AJV without each module having to
+ *  bundle its own copy.
+ *
+ *  Called once for the module-level instance and once per
+ *  DefinitionRegistry instance. */
 export function createAjv() {
     const instance = new Ajv({ allErrors: true, strict: false });
     addFormats.default
         ? addFormats.default(instance)
         : addFormats(instance);
+    instance.addSchema(ManifestRootSchema);
     return instance;
 }
 const ajv = createAjv();
@@ -270,6 +277,16 @@ export function substituteCelFields(data, schema, rootSchema) {
     if (typeof data === "string" && CEL_PURE_RE.test(data)) {
         return celPlaceholderForSchema(resolved);
     }
+    // `!ref <name>` sentinels are identity markers, not runtime values —
+    // schemas that opt into `$ref: "telo://manifest#/$defs/ResourceRef"`
+    // (or `anyOf` it alongside other shapes) need the actual sentinel
+    // object so AJV validates it against ResourceRefSchema. Collapsing it
+    // to a CEL placeholder would either fail the schema (when the slot
+    // expects the ResourceRef shape) or mask validation errors (when the
+    // slot expects something else entirely).
+    if (isRefSentinel(data)) {
+        return data;
+    }
     if (isTaggedSentinel(data)) {
         return celPlaceholderForSchema(resolved);
     }

package/dist/system-kinds.d.ts

@@ -0,0 +1,25 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export declare const REF_VALIDATION_SKIP_KINDS: ReadonlySet<string>;
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export declare const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string>;
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export declare const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string>;
+//# sourceMappingURL=system-kinds.d.ts.map

package/dist/system-kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-kinds.d.ts","sourceRoot":"","sources":["../src/system-kinds.ts"],"names":[],"mappings":"AAAA;;;;sEAIsE;AAEtE;;;;;;0CAM0C;AAC1C,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAGxD,CAAC;AAEH;;;4CAG4C;AAC5C,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAG1D,CAAC;AAEH;;;;0EAI0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAIxD,CAAC"}

package/dist/system-kinds.js

@@ -0,0 +1,34 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export const REF_VALIDATION_SKIP_KINDS = new Set([
+    "Telo.Definition",
+    "Telo.Abstract",
+]);
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export const DEPENDENCY_GRAPH_SKIP_KINDS = new Set([
+    "Telo.Definition",
+    "Telo.Import",
+]);
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export const REF_RESOLUTION_SKIP_KINDS = new Set([
+    "Telo.Definition",
+    "Telo.Abstract",
+    "Telo.Import",
+]);

package/dist/types.d.ts

@@ -73,6 +73,18 @@ export interface LoaderInitOptions {
 }
 export interface AnalysisOptions {
     strictContexts?: boolean;
+    /** When true, `analyze()` runs the state-mutating setup (module identity /
+     *  alias / definition registration plus `normalizeInlineResources`) but
+     *  skips every diagnostic-producing pass — per-resource validation, the
+     *  Library `env:` check, `validateExtends`, `validateProviderCoherence`,
+     *  and `validateThrowsCoverage`. Used by the kernel when a previous load
+     *  has already stamped the manifest set as valid (by content hash), so
+     *  the registry still gets populated without paying the validation walk
+     *  on every cold start. The caller takes responsibility for the
+     *  correctness guarantee — pass this only when something durable
+     *  (on-disk stamp) attests that the manifests passed a real analyze
+     *  pass at the same analyzer / kernel version. */
+    skipValidation?: boolean;
 }
 /** Pre-seeded state for incremental analysis. Passed to StaticAnalyzer.analyze() so it does
  *  not rebuild from scratch on every call. The provided instances are mutated — new definitions

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;qEAEiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjE;;qEAEiE;IACjE,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;6FACyF;IACzF,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;IACpE;;;;+EAI2E;IAC3E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAAC;CAC5E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;qEAEiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjE;;qEAEiE;IACjE,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;6FACyF;IACzF,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;sDAUkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;IACpE;;;;+EAI2E;IAC3E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAAC;CAC5E"}

package/dist/validate-cel-context.d.ts

@@ -63,6 +63,11 @@ export declare function pathMatchesScope(exprPath: string, scope: string): boole
  *   `manifestRoot.provide.kind` as a kind name, looks up the kind's Telo.Definition,
  *   and returns the `outputType` schema.
  *
+ *   Accepts either a single string or an array of strings. With an array, paths
+ *   are tried in order and the first one that resolves to a usable schema wins —
+ *   used by `result:` to find its dispatch target under whichever entry-point
+ *   field (`provide:` or `invoke:`) the definition declares.
+ *
  * - `x-telo-context-ref-from`: existing form — reads `{kind, name}` object from
  *   `manifestItem.<path>`, looks up the named manifest, returns its `<subpath>` field.
  *