@telorun/analyzer 1.1.0 → 1.3.0

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-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAkD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA2UtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA2WtB"}

package/dist/validate-references.js

@@ -1,13 +1,9 @@
+import { isRefSentinel } from "@telorun/templating";
 import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
-/** Kinds skipped by reference validation. Telo.Application and Telo.Library
- *  are intentionally not here: Application has `targets` with x-telo-ref that
- *  must be validated, and Library has no ref-bearing fields so flows through
- *  harmlessly. Telo.Import is also not here for the same reason — its
- *  `source` field isn't x-telo-ref, so nothing gets checked. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
  * Returns an empty array when valid, or mismatch error strings when not.
@@ -122,6 +118,36 @@ export function validateReferences(resources, context) {
             for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                 if (!val)
                     continue;
+                // `!ref <name>` sentinel — bare resource name marked at parse time as a
+                // reference. Look it up against the slot's x-telo-ref constraint exactly
+                // like the legacy bare-string path; the only difference is the value's
+                // shape (a TaggedSentinel rather than a raw string), which removed the
+                // string/inline ambiguity at the source.
+                if (isRefSentinel(val)) {
+                    const refName = val.source;
+                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                    if (!target) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "UNRESOLVED_REFERENCE",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+                            data: { resource: resourceData, filePath, path: concretePath },
+                        });
+                        continue;
+                    }
+                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
+                    if (kindErrors.length > 0) {
+                        diagnostics.push({
+                            severity: DiagnosticSeverity.Error,
+                            code: "REFERENCE_KIND_MISMATCH",
+                            source: SOURCE,
+                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                            data: { resource: resourceData, filePath, path: concretePath },
+                        });
+                    }
+                    continue;
+                }
                 // Name-only reference (plain string) — look up by name to validate.
                 // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
                 // extract the resource name from the last dot segment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -29,7 +29,8 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist/**",
@@ -41,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "1.0.0"
+    "@telorun/templating": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/analyzer.ts

@@ -14,6 +14,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,
@@ -623,6 +624,22 @@ 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<string, ResourceManifest>();
     for (const m of allManifests) {
@@ -972,12 +989,17 @@ export class StaticAnalyzer {
 
   normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[] {
     const ctx = registry._context();
-    return normalizeInlineResources(
+    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(

package/src/builtins.ts

@@ -220,6 +220,20 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             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/src/dependency-graph.ts

@@ -1,7 +1,9 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
+import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
 export interface ResourceNode {
   kind: string;
@@ -17,16 +19,6 @@ export interface DependencyGraph {
   cycle?: ReadonlyArray<ResourceNode>;
 }
 
-/** 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"]);
-
 const nodeKey = (kind: string, name: string) => `${kind}\0${name}`;
 
 /**
@@ -47,12 +39,18 @@ export function buildDependencyGraph(
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
 ): DependencyGraph {
-  // --- Build node set ---
+  // --- Build node set + name index ---
   const nodes = new Map<string, ResourceNode>();
+  // 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<string, ResourceNode>();
   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 as string);
-    nodes.set(key, { kind: r.kind, name: r.metadata.name as string });
+    const node = { kind: r.kind, name: r.metadata.name as string };
+    nodes.set(nodeKey(node.kind, node.name), node);
+    nodesByName.set(node.name, node);
   }
 
   // --- Build adjacency: from → deps (from depends on dep) ---
@@ -90,7 +88,22 @@ export function buildDependencyGraph(
       if (!isRefEntry(entry)) continue;
 
       for (const val of resolveFieldValues(r, fieldPath)) {
-        if (!val || typeof val !== "object") continue;
+        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 as Record<string, unknown>;
         if (!ref.kind || !ref.name) continue;
         // Edges to scoped resources are runtime deps, not boot-time deps — exclude from DAG

package/src/manifest-loader.ts

@@ -33,6 +33,14 @@ export class Loader {
    *  get distinct entries, so neither sees the wrong manifest tree. */
   private readonly fileCache = new Map<string, LoadedFile>();
 
+  /** 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 = new Map<string, string>();
+
   protected sources: ManifestSource[];
   private readonly celEnv: Environment;
 
@@ -67,8 +75,22 @@ export class Loader {
   }
 
   async resolveEntryPoint(url: string): Promise<string> {
-    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: string): string | undefined {
+    return this.urlToSource.get(url);
   }
 
   // --- New API: returns LoadedFile / LoadedModule / LoadedGraph ----------
@@ -78,8 +100,42 @@ export class Loader {
    *  private mutable copy must call `parseLoadedFile` directly with the
    *  LoadedFile's `text`. */
   async loadFile(url: string, options?: LoadOptions): Promise<LoadedFile> {
+    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;
 
@@ -224,7 +280,16 @@ export class Loader {
     return { rootSource, entry, modules, importEdges, errors };
   }
 
-  private resolveImportUrl(fromSource: string, importSource: string): string {
+  /** 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 {
     if (importSource.startsWith(".") || importSource.startsWith("/")) {
       return this.pick(fromSource).resolveRelative(fromSource, importSource);
     }

package/src/position-metadata.ts

@@ -29,13 +29,21 @@ export function buildDocumentPositions(
 
 /** 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: string): number[] {
   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("--- ")) offsets.push(i + 1);
+    if (t === "---" || t.startsWith("--- ")) {
+      if (i === 0) continue;
+      offsets.push(i + 1);
+    }
   }
   return offsets;
 }

package/src/precompile.ts

@@ -1,6 +1,6 @@
 import type { Environment } from "@marcbachmann/cel-js";
 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
@@ -21,6 +21,13 @@ export function precompileDoc(doc: unknown, env: Environment): unknown {
   // 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) {