@telorun/analyzer 1.1.0 → 1.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 # SUSTAINABLE USE LICENSE (Fair-code)
 
-Copyright (c) 2026 DiglyAI
+Copyright (c) 2026 CodeNet Sp. z o.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
 
@@ -14,4 +14,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
 
-For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact DiglyAI.
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAc9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA+c/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA6cvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAUxF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAe9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA+c/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA6dvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -7,6 +7,7 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import { celTypeSatisfiesJsonSchema, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
@@ -492,6 +493,20 @@ export class StaticAnalyzer {
         }
         // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
         const allManifests = normalizeInlineResources(manifests, defs, aliases, aliasesByModule);
+        // Phase 2.5: resolve `!ref <name>` sentinels at every ref slot to canonical
+        // {kind, name} objects so downstream phases (validation, dependency graph,
+        // kernel controllers) see a uniform shape. Runs after normalize so both
+        // original and inline-extracted manifests have their sentinels resolved.
+        resolveRefSentinels(allManifests, defs, aliases, aliasesByModule);
+        // Trusted-input fast path: when the caller has already attested that
+        // this exact manifest set passes analysis (e.g. via the kernel's
+        // hash-stamped `.validated.json` cache), skip the validation walk.
+        // Registration of identities / aliases / definitions and inline-resource
+        // normalisation have already run above; that's all downstream
+        // consumers (prepare, init loop) require.
+        if (options?.skipValidation) {
+            return diagnostics;
+        }
         // Build a name→manifest map for looking up referenced resources
         const byName = new Map();
         for (const m of allManifests) {
@@ -779,7 +794,12 @@ export class StaticAnalyzer {
     }
     normalize(manifests, registry) {
         const ctx = registry._context();
-        return normalizeInlineResources(manifests, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        const normalized = normalizeInlineResources(manifests, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        // Resolve !ref sentinels after normalize so both the original and
+        // inline-extracted manifests get their refs canonicalized to
+        // {kind, name} for the kernel that consumes this output.
+        resolveRefSentinels(normalized, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        return normalized;
     }
     prepare(manifests, registry) {
         const ctx = registry._context();

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAmT/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAiU/C,CAAC"}

package/dist/builtins.js

@@ -218,6 +218,20 @@ export const KERNEL_BUILTINS = [
                         anyOf: [
                             { type: "string", "x-telo-ref": "telo#Runnable" },
                             { type: "string", "x-telo-ref": "telo#Service" },
+                            // Post-resolution shape that `resolveRefSentinels`
+                            // substitutes a `!ref <name>` sentinel into. The
+                            // adjacent `x-telo-ref` constraints govern the kind
+                            // check; this branch only admits the structural form so
+                            // AJV doesn't reject a resolved ref.
+                            {
+                                type: "object",
+                                required: ["kind", "name"],
+                                properties: {
+                                    kind: { type: "string" },
+                                    name: { type: "string" },
+                                },
+                                additionalProperties: true,
+                            },
                         ],
                     },
                 },

package/dist/dependency-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGnE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CA6FjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.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,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CAkHjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}

package/dist/dependency-graph.js

@@ -1,13 +1,6 @@
+import { isRefSentinel } from "@telorun/templating";
 import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
-/** System resource kinds that are not runtime nodes in the dependency graph.
- *  Module-identity docs (Telo.Application, Telo.Library) are intentionally
- *  not in this set: an Application's `targets` use `x-telo-ref` to real
- *  Runnable/Service resources, so the Application legitimately depends on
- *  them in boot order — modeling that as a graph edge is correct. A Library
- *  has no `targets`, so it becomes a zero-edge node, which is harmless.
- *  If the graph is ever consumed as "things to init", skip these kinds at
- *  the consumer site; the controller already runs them separately. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Import"]);
+import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 const nodeKey = (kind, name) => `${kind}\0${name}`;
 /**
  * Builds a directed acyclic graph (DAG) of runtime resource dependencies and
@@ -22,13 +15,19 @@ const nodeKey = (kind, name) => `${kind}\0${name}`;
  * not pre-compute or pass field maps separately.
  */
 export function buildDependencyGraph(resources, registry, aliases, aliasesByModule) {
-    // --- Build node set ---
+    // --- Build node set + name index ---
     const nodes = new Map();
+    // Sentinel lookup (`!ref <name>`) needs to resolve a bare name to its
+    // declared kind. Names are unique within a manifest scope, so a flat
+    // map suffices and lets the sentinel branch below avoid a full
+    // O(N) scan of the node set on every reference.
+    const nodesByName = new Map();
     for (const r of resources) {
         if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
             continue;
-        const key = nodeKey(r.kind, r.metadata.name);
-        nodes.set(key, { kind: r.kind, name: r.metadata.name });
+        const node = { kind: r.kind, name: r.metadata.name };
+        nodes.set(nodeKey(node.kind, node.name), node);
+        nodesByName.set(node.name, node);
     }
     // --- Build adjacency: from → deps (from depends on dep) ---
     const deps = new Map();
@@ -66,7 +65,22 @@ export function buildDependencyGraph(resources, registry, aliases, aliasesByModu
             if (!isRefEntry(entry))
                 continue;
             for (const val of resolveFieldValues(r, fieldPath)) {
-                if (!val || typeof val !== "object")
+                if (!val)
+                    continue;
+                // `!ref <name>` sentinel — look up the target's kind from the
+                // name (resources are unique by name) so the edge carries the
+                // concrete kind, matching the {kind, name} edge shape below.
+                if (isRefSentinel(val)) {
+                    const refName = val.source;
+                    if (scopedNames.has(refName))
+                        continue;
+                    const node = nodesByName.get(refName);
+                    if (node) {
+                        deps.get(sourceKey).add(nodeKey(node.kind, node.name));
+                    }
+                    continue;
+                }
+                if (typeof val !== "object")
                     continue;
                 const ref = val;
                 if (!ref.kind || !ref.name)

package/dist/manifest-loader.d.ts

@@ -6,12 +6,25 @@ export declare class Loader {
      *  caller (kernel) and a raw-mode caller (analyzer/editor) on the same file
      *  get distinct entries, so neither sees the wrong manifest tree. */
     private readonly fileCache;
+    /** requestUrl → canonical `source`. Lets `loadFile` skip the source read
+     *  when a URL it has already canonicalised is requested again — kernel
+     *  load → boot and the import-controller each ask the loader for the same
+     *  modules. Without this fast path every duplicate request re-runs the
+     *  source's `read()` (a `fetch` for `RegistrySource`, a disk read for
+     *  `LocalFileSource`). */
+    private readonly urlToSource;
     protected sources: ManifestSource[];
     private readonly celEnv;
     constructor(extraSourcesOrOptions?: ManifestSource[] | LoaderInitOptions);
     register(source: ManifestSource): this;
     private pick;
     resolveEntryPoint(url: string): Promise<string>;
+    /** Returns the canonical source URL the loader has already mapped `url`
+     *  to during a prior `loadFile`/`loadModule`/`loadGraph` call, or
+     *  `undefined` when the URL has not been seen. Callers use it to test
+     *  set-membership against a previous graph walk's modules without
+     *  triggering an extra source read. */
+    canonicalize(url: string): string | undefined;
     /** Read one file via the source chain and parse it into a LoadedFile.
      *  The result is shared with `Loader.fileCache`. Callers that want a
      *  private mutable copy must call `parseLoadedFile` directly with the
@@ -26,7 +39,16 @@ export declare class Loader {
      *  `importEdges` mapping each importing file's PascalCase aliases to their
      *  target's canonical source. */
     loadGraph(entryUrl: string, options?: LoadOptions): Promise<LoadedGraph>;
-    private resolveImportUrl;
+    /** Resolve an `import` URL against the file it appears in. Relative /
+     *  absolute-path forms run through the owning `ManifestSource`'s
+     *  `resolveRelative`; registry refs and full URLs pass through
+     *  unchanged. Exposed so the import-controller (and any other
+     *  caller-side resolver) lands on the *exact same* canonical URL the
+     *  loader used when walking the entry graph — divergent resolution
+     *  would silently break optimizations like `canonicalize()`-keyed
+     *  cache hits whenever a non-trivial `ManifestSource.resolveRelative`
+     *  is in play. */
+    resolveImportUrl(fromSource: string, importSource: string): string;
     private assertSingleModuleDeclaration;
     private assertNoSystemKindsInPartialContext;
     private assertImportTargetIsLibrary;

package/dist/manifest-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,qBAAqB,GAAE,cAAc,EAAE,GAAG,iBAAsB;IAmB5E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOrD;;;+BAG2B;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAcvE;;wEAEoE;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAsB3E;;;qCAGiC;IAC3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAwG9E,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,6BAA6B;IAarC,OAAO,CAAC,mCAAmC;IAc3C,OAAO,CAAC,2BAA2B;YAkCrB,eAAe;IAmB7B;;;0CAGsC;IAChC,gBAAgB,CACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA0B5D"}
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AASpB,qBAAa,MAAM;IACjB;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D;;;;;8BAK0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,qBAAqB,GAAE,cAAc,EAAE,GAAG,iBAAsB;IAmB5E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUrD;;;;2CAIuC;IACvC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM7C;;;+BAG2B;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAgDvE;;wEAEoE;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAsB3E;;;qCAGiC;IAC3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAwG9E;;;;;;;;sBAQkB;IAClB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAOlE,OAAO,CAAC,6BAA6B;IAarC,OAAO,CAAC,mCAAmC;IAc3C,OAAO,CAAC,2BAA2B;YAkCrB,eAAe;IAmB7B;;;0CAGsC;IAChC,gBAAgB,CACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA0B5D"}

package/dist/manifest-loader.js

@@ -16,6 +16,13 @@ export class Loader {
      *  caller (kernel) and a raw-mode caller (analyzer/editor) on the same file
      *  get distinct entries, so neither sees the wrong manifest tree. */
     fileCache = new Map();
+    /** requestUrl → canonical `source`. Lets `loadFile` skip the source read
+     *  when a URL it has already canonicalised is requested again — kernel
+     *  load → boot and the import-controller each ask the loader for the same
+     *  modules. Without this fast path every duplicate request re-runs the
+     *  source's `read()` (a `fetch` for `RegistrySource`, a disk read for
+     *  `LocalFileSource`). */
+    urlToSource = new Map();
     sources;
     celEnv;
     constructor(extraSourcesOrOptions = []) {
@@ -45,8 +52,21 @@ export class Loader {
         return s;
     }
     async resolveEntryPoint(url) {
-        const { source } = await this.pick(url).read(url);
-        return source;
+        // Route through `loadFile` so the resolved source URL and parsed
+        // entry are populated in `urlToSource` + `fileCache` in one read.
+        // Callers (kernel.load) immediately call `loadGraph(entryUrl)`
+        // afterwards — without this priming, the entry file would be read
+        // twice (twice over the network for `RegistrySource`).
+        const file = await this.loadFile(url);
+        return file.source;
+    }
+    /** Returns the canonical source URL the loader has already mapped `url`
+     *  to during a prior `loadFile`/`loadModule`/`loadGraph` call, or
+     *  `undefined` when the URL has not been seen. Callers use it to test
+     *  set-membership against a previous graph walk's modules without
+     *  triggering an extra source read. */
+    canonicalize(url) {
+        return this.urlToSource.get(url);
     }
     // --- New API: returns LoadedFile / LoadedModule / LoadedGraph ----------
     /** Read one file via the source chain and parse it into a LoadedFile.
@@ -54,8 +74,42 @@ export class Loader {
      *  private mutable copy must call `parseLoadedFile` directly with the
      *  LoadedFile's `text`. */
     async loadFile(url, options) {
+        const compileKey = options?.compile ? "compiled" : "raw";
+        const knownSource = this.urlToSource.get(url);
+        if (knownSource) {
+            const cached = this.fileCache.get(`${compileKey}:${knownSource}`);
+            if (cached)
+                return cached;
+            // The other compile-mode entry is cached — reparse from its text
+            // instead of re-reading the source.
+            //
+            // NOTE for watch-mode reactivation (cli/nodejs/src/commands/run.ts
+            // currently has `setupWatchMode` commented out): this branch
+            // assumes file contents don't change underneath a single Loader.
+            // Reviving watch mode will need a public `invalidate(url)` (or
+            // similar) that drops both `urlToSource[url]` and the cached
+            // entries for its canonical source before the loader serves the
+            // file again.
+            const altKey = `${compileKey === "compiled" ? "raw" : "compiled"}:${knownSource}`;
+            const alt = this.fileCache.get(altKey);
+            if (alt) {
+                const reparsed = parseLoadedFile(knownSource, url, alt.text, {
+                    compile: options?.compile,
+                    celEnv: this.celEnv,
+                });
+                this.fileCache.set(`${compileKey}:${knownSource}`, reparsed);
+                return reparsed;
+            }
+        }
         const { text, source } = await this.pick(url).read(url);
-        const cacheKey = `${options?.compile ? "compiled" : "raw"}:${source}`;
+        this.urlToSource.set(url, source);
+        // Also map the canonical source to itself so subsequent `loadFile`
+        // calls that already received a canonical URL — `kernel.load` passes
+        // the result of `resolveEntryPoint` to `loadGraph`, which then asks
+        // for that exact URL — hit the urlToSource fast path instead of
+        // falling through to a redundant `pick(url).read(url)`.
+        this.urlToSource.set(source, source);
+        const cacheKey = `${compileKey}:${source}`;
         const cached = this.fileCache.get(cacheKey);
         if (cached && cached.text === text)
             return cached;
@@ -190,6 +244,15 @@ export class Loader {
         }
         return { rootSource, entry, modules, importEdges, errors };
     }
+    /** Resolve an `import` URL against the file it appears in. Relative /
+     *  absolute-path forms run through the owning `ManifestSource`'s
+     *  `resolveRelative`; registry refs and full URLs pass through
+     *  unchanged. Exposed so the import-controller (and any other
+     *  caller-side resolver) lands on the *exact same* canonical URL the
+     *  loader used when walking the entry graph — divergent resolution
+     *  would silently break optimizations like `canonicalize()`-keyed
+     *  cache hits whenever a non-trivial `ManifestSource.resolveRelative`
+     *  is in play. */
     resolveImportUrl(fromSource, importSource) {
         if (importSource.startsWith(".") || importSource.startsWith("/")) {
             return this.pick(fromSource).resolveRelative(fromSource, importSource);

package/dist/position-metadata.d.ts

@@ -15,7 +15,12 @@ export interface DocumentPosition {
 export declare function buildDocumentPositions(text: string, parsedDocs: Document[]): DocumentPosition[];
 /** Line numbers (0-indexed) where each YAML document in a multi-doc file
  *  starts. The first document is always at line 0; subsequent entries point
- *  to the line after each `---` directive. */
+ *  to the line after each `---` separator.
+ *
+ *  A `---` at line 0 is the doc-start marker for doc 0 (the parser still
+ *  emits a single document), not a separator before an empty doc — skipping
+ *  it keeps `offsets.length === parsedDocs.length` so diagnostics for doc N
+ *  don't land inside doc N-1's text. */
 export declare function documentLineOffsets(text: string): number[];
 /** Byte-offset → start-of-line lookup table. Index `i` is the byte offset of
  *  the first character on line `i`. Used with `offsetToPosition` to turn a

package/dist/position-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position-metadata.d.ts","sourceRoot":"","sources":["../src/position-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;oBAKoB;AAEpB,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,QAAQ,EAAE,GACrB,gBAAgB,EAAE,CAOpB;AAED;;8CAE8C;AAC9C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAaD;;;;;+CAK+C;AAC/C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,aAAa,CA0CtF"}
+{"version":3,"file":"position-metadata.d.ts","sourceRoot":"","sources":["../src/position-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;oBAKoB;AAEpB,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,QAAQ,EAAE,GACrB,gBAAgB,EAAE,CAOpB;AAED;;;;;;;wCAOwC;AACxC,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAW1D;AAED;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAaD;;;;;+CAK+C;AAC/C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,aAAa,CA0CtF"}

package/dist/position-metadata.js

@@ -10,14 +10,22 @@ export function buildDocumentPositions(text, parsedDocs) {
 }
 /** Line numbers (0-indexed) where each YAML document in a multi-doc file
  *  starts. The first document is always at line 0; subsequent entries point
- *  to the line after each `---` directive. */
+ *  to the line after each `---` separator.
+ *
+ *  A `---` at line 0 is the doc-start marker for doc 0 (the parser still
+ *  emits a single document), not a separator before an empty doc — skipping
+ *  it keeps `offsets.length === parsedDocs.length` so diagnostics for doc N
+ *  don't land inside doc N-1's text. */
 export function documentLineOffsets(text) {
     const offsets = [0];
     const lines = text.split("\n");
     for (let i = 0; i < lines.length; i++) {
         const t = lines[i].trimEnd();
-        if (t === "---" || t.startsWith("--- "))
+        if (t === "---" || t.startsWith("--- ")) {
+            if (i === 0)
+                continue;
             offsets.push(i + 1);
+        }
     }
     return offsets;
 }

package/dist/precompile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"precompile.d.ts","sourceRoot":"","sources":["../src/precompile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAmCrE"}
+{"version":3,"file":"precompile.d.ts","sourceRoot":"","sources":["../src/precompile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIxD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CA0CrE"}

package/dist/precompile.js

@@ -1,5 +1,5 @@
 import { isCompiledValue } from "@telorun/sdk";
-import { compileString, defaultRegistry, isTaggedSentinel } from "@telorun/templating";
+import { compileString, defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 /**
  * Walks a raw YAML document and replaces all `${{ expr }}` strings (and
  * `!cel`-tagged sentinels) with CompiledValue wrappers. Throws on CEL syntax
@@ -19,6 +19,14 @@ export function precompileDoc(doc, env) {
     // analyzer's diagnostic walk can identify it on compiled trees too;
     // engines returning plain values (e.g. `literal` → a string) pass through
     // verbatim — the runtime contract is "any scalar value is fine."
+    // `!ref` sentinels are identity markers, not templating values. They must
+    // survive precompile intact so the analyzer's `resolveRefSentinels` pass
+    // can substitute them with `{kind, name}` objects against the resolved
+    // resource manifest. Running the engine's `compile` here would prematurely
+    // collapse the sentinel into its source string and the ref slot would
+    // arrive at the controller as a bare name with no kind.
+    if (isRefSentinel(doc))
+        return doc;
     if (isTaggedSentinel(doc)) {
         const engine = defaultRegistry().get(doc.engine);
         if (!engine) {

package/dist/reference-field-map.js

@@ -98,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;
@@ -123,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"] });
@@ -148,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
@@ -162,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/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);
+        }
+    }
+}