@telorun/templating 1.0.0 → 1.1.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/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;gEAKgE;AAChE,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAA+B,CAAC;AAEtF,wBAAgB,qBAAqB,IAAI,wBAAwB,CAMhE;AAID;;;oBAGoB;AACpB,wBAAgB,eAAe,IAAI,wBAAwB,CAK1D"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;gEAKgE;AAChE,eAAO,MAAM,cAAc,EAAE,SAAS,gBAAgB,EAA0C,CAAC;AAEjG,wBAAgB,qBAAqB,IAAI,wBAAwB,CAMhE;AAID;;;oBAGoB;AACpB,wBAAgB,eAAe,IAAI,wBAAwB,CAK1D"}

package/dist/builtins.js

@@ -1,5 +1,6 @@
 import { celEngine } from "./engines/cel.js";
 import { literalEngine } from "./engines/literal.js";
+import { refEngine } from "./engines/ref.js";
 import { TemplatingEngineRegistry } from "./registry.js";
 /** Single source of truth for the built-in templating engines. Every host
  *  (kernel, analyzer, editor, vscode extension) calls `createDefaultRegistry`
@@ -7,7 +8,7 @@ import { TemplatingEngineRegistry } from "./registry.js";
  *  agree on which engines exist. Per-host à-la-carte registration would let
  *  a manifest validate clean in one host (e.g. `cel` only) and crash in
  *  another (e.g. `cel + literal`); always ship the same set. */
-export const builtinEngines = [celEngine, literalEngine];
+export const builtinEngines = [celEngine, literalEngine, refEngine];
 export function createDefaultRegistry() {
     const registry = new TemplatingEngineRegistry();
     for (const engine of builtinEngines) {

package/dist/engines/ref.d.ts

@@ -0,0 +1,12 @@
+import type { TemplatingEngine } from "../engine.js";
+/** The `!ref` engine. Marks a tagged scalar as a resource reference: the
+ *  source is the bare resource name, looked up against the slot's
+ *  `x-telo-ref` constraint by the analyzer and the kernel.
+ *
+ *  Returns the source string verbatim at compile time. The actual lookup
+ *  (sentinel → live ResourceInstance) happens at resource-context init,
+ *  not at templating-engine compile — the engine just preserves the source
+ *  through the parse/serialize round-trip. Analysis is a no-op; reference
+ *  resolution is the analyzer's responsibility via the ref-aware walker. */
+export declare const refEngine: TemplatingEngine;
+//# sourceMappingURL=ref.d.ts.map

package/dist/engines/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/engines/ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;4EAQ4E;AAC5E,eAAO,MAAM,SAAS,EAAE,gBAUvB,CAAC"}

package/dist/engines/ref.js

@@ -0,0 +1,18 @@
+/** The `!ref` engine. Marks a tagged scalar as a resource reference: the
+ *  source is the bare resource name, looked up against the slot's
+ *  `x-telo-ref` constraint by the analyzer and the kernel.
+ *
+ *  Returns the source string verbatim at compile time. The actual lookup
+ *  (sentinel → live ResourceInstance) happens at resource-context init,
+ *  not at templating-engine compile — the engine just preserves the source
+ *  through the parse/serialize round-trip. Analysis is a no-op; reference
+ *  resolution is the analyzer's responsibility via the ref-aware walker. */
+export const refEngine = {
+    name: "ref",
+    compile(source) {
+        return source;
+    },
+    analyze() {
+        return [];
+    },
+};

package/dist/index.d.ts

@@ -4,9 +4,11 @@ export { extractAccessChains, validateChainAgainstSchema } from "./cel/analyze.j
 export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";
+export { refEngine } from "./engines/ref.js";
 export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
 export type { AnalyzeEnv, CompileEnv, EngineDiagnostic, TemplatingEngine, } from "./engine.js";
-export { isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
+export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, } from "./manifest-schemas.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -4,7 +4,9 @@ export { extractAccessChains, validateChainAgainstSchema } from "./cel/analyze.j
 export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";
+export { refEngine } from "./engines/ref.js";
 export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
-export { isTaggedSentinel, makeTaggedSentinel } from "./sentinel.js";
+export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel } from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
+export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, } from "./manifest-schemas.js";

package/dist/manifest-schemas.d.ts

@@ -0,0 +1,70 @@
+/** Shared JSON-Schema fragments referenced from every module's `telo.yaml`
+ *  via `$ref: "telo://manifest#/$defs/<Name>"`. Lives in the templating
+ *  package (alongside the YAML tag mechanism) because the analyzer cannot
+ *  depend on the kernel — both consume this package, so this is the only
+ *  layer where a single source of truth can sit. The kernel re-exports
+ *  these symbols from its own `manifest-schemas` surface for downstream
+ *  ergonomics. */
+/** Schema fragment for a resource reference produced by the `!ref` YAML
+ *  tag. After parsing, the value is a `TaggedSentinel` (engine "ref")
+ *  whose `source` is the bare resource name. Module schemas declare a
+ *  ref slot as `$ref: "telo://manifest#/$defs/ResourceRef"`; the
+ *  analyzer's reference walker is what looks the name up against the
+ *  slot's `x-telo-ref` constraint.
+ *
+ *  Migration note: while the legacy bare-name string and `{kind, name}`
+ *  object forms are still accepted by the analyzer/kernel walkers (in an
+ *  additive transitional state), those shapes are *not* part of this
+ *  schema. Slots that need to accept legacy forms during migration keep
+ *  their hand-rolled `oneOf` until the cutover lands. */
+export declare const ResourceRefSchema: {
+    type: string;
+    required: string[];
+    properties: {
+        __tagged: {
+            const: boolean;
+        };
+        engine: {
+            const: string;
+        };
+        source: {
+            type: string;
+            minLength: number;
+        };
+    };
+    additionalProperties: boolean;
+};
+/** Stable URI under which the shared manifest root schema is registered
+ *  with module-side AJV instances. Module YAMLs reach the fragments via
+ *  `$ref: "telo://manifest#/$defs/<Name>"`. The URI is the contract;
+ *  the symbol names intentionally omit a host-specific prefix since the
+ *  fragments live in `@telorun/templating` (the only layer both kernel
+ *  and analyzer depend on). */
+export declare const MANIFEST_SCHEMA_URI = "telo://manifest";
+/** Root schema registered with AJV under `MANIFEST_SCHEMA_URI`. Carries
+ *  `$defs` only — it isn't validated against directly. Adding a new
+ *  shared fragment means putting it under `$defs` here and `$ref`-ing
+ *  it from module schemas. */
+export declare const ManifestRootSchema: {
+    $id: string;
+    $defs: {
+        ResourceRef: {
+            type: string;
+            required: string[];
+            properties: {
+                __tagged: {
+                    const: boolean;
+                };
+                engine: {
+                    const: string;
+                };
+                source: {
+                    type: string;
+                    minLength: number;
+                };
+            };
+            additionalProperties: boolean;
+        };
+    };
+};
+//# sourceMappingURL=manifest-schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-schemas.d.ts","sourceRoot":"","sources":["../src/manifest-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;kBAMkB;AAElB;;;;;;;;;;;yDAWyD;AACzD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;CAS7B,CAAC;AAEF;;;;;+BAK+B;AAC/B,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;8BAG8B;AAC9B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;CAK9B,CAAC"}

package/dist/manifest-schemas.js

@@ -0,0 +1,46 @@
+/** Shared JSON-Schema fragments referenced from every module's `telo.yaml`
+ *  via `$ref: "telo://manifest#/$defs/<Name>"`. Lives in the templating
+ *  package (alongside the YAML tag mechanism) because the analyzer cannot
+ *  depend on the kernel — both consume this package, so this is the only
+ *  layer where a single source of truth can sit. The kernel re-exports
+ *  these symbols from its own `manifest-schemas` surface for downstream
+ *  ergonomics. */
+/** Schema fragment for a resource reference produced by the `!ref` YAML
+ *  tag. After parsing, the value is a `TaggedSentinel` (engine "ref")
+ *  whose `source` is the bare resource name. Module schemas declare a
+ *  ref slot as `$ref: "telo://manifest#/$defs/ResourceRef"`; the
+ *  analyzer's reference walker is what looks the name up against the
+ *  slot's `x-telo-ref` constraint.
+ *
+ *  Migration note: while the legacy bare-name string and `{kind, name}`
+ *  object forms are still accepted by the analyzer/kernel walkers (in an
+ *  additive transitional state), those shapes are *not* part of this
+ *  schema. Slots that need to accept legacy forms during migration keep
+ *  their hand-rolled `oneOf` until the cutover lands. */
+export const ResourceRefSchema = {
+    type: "object",
+    required: ["__tagged", "engine", "source"],
+    properties: {
+        __tagged: { const: true },
+        engine: { const: "ref" },
+        source: { type: "string", minLength: 1 },
+    },
+    additionalProperties: false,
+};
+/** Stable URI under which the shared manifest root schema is registered
+ *  with module-side AJV instances. Module YAMLs reach the fragments via
+ *  `$ref: "telo://manifest#/$defs/<Name>"`. The URI is the contract;
+ *  the symbol names intentionally omit a host-specific prefix since the
+ *  fragments live in `@telorun/templating` (the only layer both kernel
+ *  and analyzer depend on). */
+export const MANIFEST_SCHEMA_URI = "telo://manifest";
+/** Root schema registered with AJV under `MANIFEST_SCHEMA_URI`. Carries
+ *  `$defs` only — it isn't validated against directly. Adding a new
+ *  shared fragment means putting it under `$defs` here and `$ref`-ing
+ *  it from module schemas. */
+export const ManifestRootSchema = {
+    $id: MANIFEST_SCHEMA_URI,
+    $defs: {
+        ResourceRef: ResourceRefSchema,
+    },
+};

package/dist/sentinel.d.ts

@@ -11,4 +11,12 @@ export interface TaggedSentinel {
 }
 export declare function isTaggedSentinel(v: unknown): v is TaggedSentinel;
 export declare function makeTaggedSentinel(engine: string, source: string): TaggedSentinel;
+/** True when `v` is a `!ref <name>` sentinel — i.e. a resource reference
+ *  marked at parse time. Downstream walkers (analyzer ref validation,
+ *  inline normalization, dependency graph, kernel resource resolution)
+ *  use this to tell a reference from an inline definition without
+ *  inferring intent from field presence. */
+export declare function isRefSentinel(v: unknown): v is TaggedSentinel & {
+    engine: "ref";
+};
 //# sourceMappingURL=sentinel.d.ts.map

package/dist/sentinel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../src/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;YAKY;AACZ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAQhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAEjF"}
+{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../src/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;YAKY;AACZ,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAQhE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAEjF;AAED;;;;4CAI4C;AAC5C,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,GAAG;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,CAEjF"}

package/dist/sentinel.js

@@ -8,3 +8,11 @@ export function isTaggedSentinel(v) {
 export function makeTaggedSentinel(engine, source) {
     return { __tagged: true, engine, source };
 }
+/** True when `v` is a `!ref <name>` sentinel — i.e. a resource reference
+ *  marked at parse time. Downstream walkers (analyzer ref validation,
+ *  inline normalization, dependency graph, kernel resource resolution)
+ *  use this to tell a reference from an inline definition without
+ *  inferring intent from field presence. */
+export function isRefSentinel(v) {
+    return isTaggedSentinel(v) && v.engine === "ref";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/templating",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Telo Templating - Engine registry and shared CEL core for Telo manifests.",
   "keywords": [
     "telo",

package/src/builtins.ts

@@ -1,5 +1,6 @@
 import { celEngine } from "./engines/cel.js";
 import { literalEngine } from "./engines/literal.js";
+import { refEngine } from "./engines/ref.js";
 import { TemplatingEngineRegistry } from "./registry.js";
 import type { TemplatingEngine } from "./engine.js";
 
@@ -9,7 +10,7 @@ import type { TemplatingEngine } from "./engine.js";
  *  agree on which engines exist. Per-host à-la-carte registration would let
  *  a manifest validate clean in one host (e.g. `cel` only) and crash in
  *  another (e.g. `cel + literal`); always ship the same set. */
-export const builtinEngines: readonly TemplatingEngine[] = [celEngine, literalEngine];
+export const builtinEngines: readonly TemplatingEngine[] = [celEngine, literalEngine, refEngine];
 
 export function createDefaultRegistry(): TemplatingEngineRegistry {
   const registry = new TemplatingEngineRegistry();

package/src/engines/ref.ts

@@ -0,0 +1,22 @@
+import type { TemplatingEngine } from "../engine.js";
+
+/** The `!ref` engine. Marks a tagged scalar as a resource reference: the
+ *  source is the bare resource name, looked up against the slot's
+ *  `x-telo-ref` constraint by the analyzer and the kernel.
+ *
+ *  Returns the source string verbatim at compile time. The actual lookup
+ *  (sentinel → live ResourceInstance) happens at resource-context init,
+ *  not at templating-engine compile — the engine just preserves the source
+ *  through the parse/serialize round-trip. Analysis is a no-op; reference
+ *  resolution is the analyzer's responsibility via the ref-aware walker. */
+export const refEngine: TemplatingEngine = {
+  name: "ref",
+
+  compile(source) {
+    return source;
+  },
+
+  analyze() {
+    return [];
+  },
+};

package/src/index.ts

@@ -10,6 +10,7 @@ export { walkCelExpressions } from "./cel/walk.js";
 
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";
+export { refEngine } from "./engines/ref.js";
 
 export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.js";
@@ -20,5 +21,10 @@ export type {
   TemplatingEngine,
 } from "./engine.js";
 
-export { isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
+export { isRefSentinel, isTaggedSentinel, makeTaggedSentinel, type TaggedSentinel } from "./sentinel.js";
 export { buildCustomTags, defaultCustomTags } from "./yaml-tags.js";
+export {
+  MANIFEST_SCHEMA_URI,
+  ManifestRootSchema,
+  ResourceRefSchema,
+} from "./manifest-schemas.js";

package/src/manifest-schemas.ts

@@ -0,0 +1,49 @@
+/** Shared JSON-Schema fragments referenced from every module's `telo.yaml`
+ *  via `$ref: "telo://manifest#/$defs/<Name>"`. Lives in the templating
+ *  package (alongside the YAML tag mechanism) because the analyzer cannot
+ *  depend on the kernel — both consume this package, so this is the only
+ *  layer where a single source of truth can sit. The kernel re-exports
+ *  these symbols from its own `manifest-schemas` surface for downstream
+ *  ergonomics. */
+
+/** Schema fragment for a resource reference produced by the `!ref` YAML
+ *  tag. After parsing, the value is a `TaggedSentinel` (engine "ref")
+ *  whose `source` is the bare resource name. Module schemas declare a
+ *  ref slot as `$ref: "telo://manifest#/$defs/ResourceRef"`; the
+ *  analyzer's reference walker is what looks the name up against the
+ *  slot's `x-telo-ref` constraint.
+ *
+ *  Migration note: while the legacy bare-name string and `{kind, name}`
+ *  object forms are still accepted by the analyzer/kernel walkers (in an
+ *  additive transitional state), those shapes are *not* part of this
+ *  schema. Slots that need to accept legacy forms during migration keep
+ *  their hand-rolled `oneOf` until the cutover lands. */
+export const ResourceRefSchema = {
+  type: "object",
+  required: ["__tagged", "engine", "source"],
+  properties: {
+    __tagged: { const: true },
+    engine: { const: "ref" },
+    source: { type: "string", minLength: 1 },
+  },
+  additionalProperties: false,
+};
+
+/** Stable URI under which the shared manifest root schema is registered
+ *  with module-side AJV instances. Module YAMLs reach the fragments via
+ *  `$ref: "telo://manifest#/$defs/<Name>"`. The URI is the contract;
+ *  the symbol names intentionally omit a host-specific prefix since the
+ *  fragments live in `@telorun/templating` (the only layer both kernel
+ *  and analyzer depend on). */
+export const MANIFEST_SCHEMA_URI = "telo://manifest";
+
+/** Root schema registered with AJV under `MANIFEST_SCHEMA_URI`. Carries
+ *  `$defs` only — it isn't validated against directly. Adding a new
+ *  shared fragment means putting it under `$defs` here and `$ref`-ing
+ *  it from module schemas. */
+export const ManifestRootSchema = {
+  $id: MANIFEST_SCHEMA_URI,
+  $defs: {
+    ResourceRef: ResourceRefSchema,
+  },
+};

package/src/sentinel.ts

@@ -23,3 +23,12 @@ export function isTaggedSentinel(v: unknown): v is TaggedSentinel {
 export function makeTaggedSentinel(engine: string, source: string): TaggedSentinel {
   return { __tagged: true, engine, source };
 }
+
+/** True when `v` is a `!ref <name>` sentinel — i.e. a resource reference
+ *  marked at parse time. Downstream walkers (analyzer ref validation,
+ *  inline normalization, dependency graph, kernel resource resolution)
+ *  use this to tell a reference from an inline definition without
+ *  inferring intent from field presence. */
+export function isRefSentinel(v: unknown): v is TaggedSentinel & { engine: "ref" } {
+  return isTaggedSentinel(v) && v.engine === "ref";
+}