@telorun/templating 0.7.0 → 0.8.0

package/README.md

@@ -58,8 +58,8 @@ imports:
   Http: std/http-server@0.9.0
   Sql: std/sql@0.8.0
 targets:
-  - Migrations
-  - Server
+  - !ref Migrations
+  - !ref Server
 ---
 # SQLite database — swap driver/host/database for PostgreSQL with zero YAML changes
 kind: Sql.Connection
@@ -72,9 +72,7 @@ file: ./tmp/feedback.db
 kind: Sql.Migrations
 metadata:
   name: Migrations
-connection:
-  kind: Sql.Connection
-  name: Db
+connection: !ref Db
 ---
 kind: Sql.Migration
 metadata:
@@ -101,7 +99,7 @@ openapi:
     version: 1.0.0
 mounts:
   - path: /v1
-    type: Http.Api.FeedbackRoutes
+    mount: !ref FeedbackRoutes
 ---
 kind: Http.Api
 metadata:
@@ -123,9 +121,7 @@ routes:
           required: [ text ]
     handler:
       kind: Sql.Exec
-      connection:
-        kind: Sql.Connection
-        name: Db
+      connection: !ref Db
     inputs:
       sql: "INSERT INTO feedback (text, source, score) VALUES (?, ?, ?)"
       bindings:
@@ -146,9 +142,7 @@ routes:
       method: GET
     handler:
       kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
+      connection: !ref Db
       from: feedback
       columns: [ id, text, source, score, created_at ]
       orderBy:
@@ -172,9 +166,7 @@ routes:
           required: [ id ]
     handler:
       kind: Sql.Select
-      connection:
-        kind: Sql.Connection
-        name: Db
+      connection: !ref Db
       from: feedback
       columns: [ id, text, source, score, created_at ]
       where:

package/dist/index.d.ts

@@ -12,5 +12,5 @@ export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builti
 export type { AnalyzeEnv, CompileEnv, EngineDiagnostic, TemplatingEngine, } from "./engine.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";
+export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, normalizeRefSlots, } 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,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,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;AAC7C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAExF,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"}
+{"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,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,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;AAC7C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAExF,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,EACjB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -11,4 +11,4 @@ export { TemplatingEngineRegistry } from "./registry.js";
 export { builtinEngines, createDefaultRegistry, defaultRegistry } from "./builtins.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";
+export { MANIFEST_SCHEMA_URI, ManifestRootSchema, ResourceRefSchema, normalizeRefSlots, } from "./manifest-schemas.js";

package/dist/manifest-schemas.d.ts

@@ -5,35 +5,87 @@
  *  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.
+/** Schema fragment for a resource-reference slot. The only form a manifest
+ *  author writes is the `!ref <name>` (or `!ref <Alias>.<name>`) YAML tag,
+ *  which parses to a `TaggedSentinel` (engine "ref") whose `source` is the
+ *  bare resource name. In practice module schemas mark a ref slot with a bare
+ *  `x-telo-ref` annotation (plus, where the slot only ever holds a reference,
+ *  `type: object` to reject a stray scalar); the analyzer's reference walker
+ *  reads `x-telo-ref` to look the name up against that constraint, independent
+ *  of this fragment. A slot opts into `$ref:
+ *  "telo://manifest#/$defs/ResourceRef"` only when it wants this exact
+ *  two-branch shape enforced at the AJV layer too — it is not required, and
+ *  slots that also accept an inline value (e.g. `inputType` / `outputType`)
+ *  deliberately do not use it (an inline JSON Schema has no `kind`).
  *
- *  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. */
+ *  Two `anyOf` branches because the value's shape depends on the phase at
+ *  which it is validated:
+ *
+ *   1. The raw `!ref` sentinel — what survives to AJV when a cross-module
+ *      reference can't be resolved in standalone single-file analysis (the
+ *      imported module isn't loaded). `substituteCelFields` deliberately
+ *      keeps the sentinel so this branch matches.
+ *   2. A resolved reference object — `{kind, name, alias?}` substituted in
+ *      place of a sentinel (or an inline definition `{kind, ...config}`
+ *      reached through a local `$ref` that escapes extraction). Both the
+ *      kernel and the analyzer validate ref slots *after* sentinel
+ *      resolution, so this is the shape AJV usually sees.
+ *
+ *  The object-form `{kind, name}` reference a user could once type directly
+ *  is gone: a plain object at a ref slot is only ever an inline definition
+ *  or the resolver's own substitution, never an author-written reference.
+ *  That removal is enforced by the analyzer (it rejects an author-written
+ *  `{kind, name}` before normalization), not by this schema — branch 2
+ *  cannot distinguish an author's `{kind, name}` from the resolver's. */
 export declare const ResourceRefSchema: {
-    type: string;
-    required: string[];
-    properties: {
-        __tagged: {
-            const: boolean;
-        };
-        engine: {
-            const: string;
+    title: string;
+    anyOf: ({
+        type: string;
+        required: string[];
+        properties: {
+            __tagged: {
+                const: boolean;
+            };
+            engine: {
+                const: string;
+            };
+            source: {
+                type: string;
+                minLength: number;
+            };
+            kind?: undefined;
         };
-        source: {
-            type: string;
-            minLength: number;
+        additionalProperties: boolean;
+    } | {
+        type: string;
+        required: string[];
+        properties: {
+            kind: {
+                type: string;
+            };
+            __tagged?: undefined;
+            engine?: undefined;
+            source?: undefined;
         };
-    };
-    additionalProperties: boolean;
+        additionalProperties: boolean;
+    })[];
 };
+/** Deep-clone `schema`, dropping the stale scalar `type` constraint from every
+ *  reference-slot node — one carrying an `x-telo-ref` string annotation.
+ *
+ *  A reference slot's value is always a `!ref` sentinel or its resolved
+ *  `{kind, name, alias?}` object (never a bare string, post-migration). Older
+ *  published modules still pin `type: "string"` on these slots — the encoding
+ *  references took when they were written as plain strings — which now rejects
+ *  the resolved object. Removing only the scalar `type` lets the analyzer and
+ *  kernel accept references uniformly across module versions during the
+ *  migration away from `{kind, name}` / string references, without disturbing
+ *  slots that legitimately accept an inline object (e.g. `inputType` /
+ *  `outputType`, which take a Telo.Type reference *or* an inline JSON schema).
+ *  The `x-telo-ref` constraint itself (which kind the reference must satisfy) is
+ *  checked separately by the analyzer's reference walker, which reads the
+ *  original schema — not this validation-only copy. */
+export declare function normalizeRefSlots(schema: unknown): unknown;
 /** 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;
@@ -49,21 +101,37 @@ export declare const ManifestRootSchema: {
     $id: string;
     $defs: {
         ResourceRef: {
-            type: string;
-            required: string[];
-            properties: {
-                __tagged: {
-                    const: boolean;
+            title: string;
+            anyOf: ({
+                type: string;
+                required: string[];
+                properties: {
+                    __tagged: {
+                        const: boolean;
+                    };
+                    engine: {
+                        const: string;
+                    };
+                    source: {
+                        type: string;
+                        minLength: number;
+                    };
+                    kind?: undefined;
                 };
-                engine: {
-                    const: string;
+                additionalProperties: boolean;
+            } | {
+                type: string;
+                required: string[];
+                properties: {
+                    kind: {
+                        type: string;
+                    };
+                    __tagged?: undefined;
+                    engine?: undefined;
+                    source?: undefined;
                 };
-                source: {
-                    type: string;
-                    minLength: number;
-                };
-            };
-            additionalProperties: boolean;
+                additionalProperties: boolean;
+            })[];
         };
     };
 };

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

@@ -1 +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"}
+{"version":3,"file":"manifest-schemas.d.ts","sourceRoot":"","sources":["../src/manifest-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;kBAMkB;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yEA+ByE;AACzE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoB7B,CAAC;AAqCF;;;;;;;;;;;;;;uDAcuD;AACvD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CA0C1D;AAED;;;;;+BAK+B;AAC/B,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;8BAG8B;AAC9B,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK9B,CAAC"}

package/dist/manifest-schemas.js

@@ -5,28 +5,149 @@
  *  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.
+/** Schema fragment for a resource-reference slot. The only form a manifest
+ *  author writes is the `!ref <name>` (or `!ref <Alias>.<name>`) YAML tag,
+ *  which parses to a `TaggedSentinel` (engine "ref") whose `source` is the
+ *  bare resource name. In practice module schemas mark a ref slot with a bare
+ *  `x-telo-ref` annotation (plus, where the slot only ever holds a reference,
+ *  `type: object` to reject a stray scalar); the analyzer's reference walker
+ *  reads `x-telo-ref` to look the name up against that constraint, independent
+ *  of this fragment. A slot opts into `$ref:
+ *  "telo://manifest#/$defs/ResourceRef"` only when it wants this exact
+ *  two-branch shape enforced at the AJV layer too — it is not required, and
+ *  slots that also accept an inline value (e.g. `inputType` / `outputType`)
+ *  deliberately do not use it (an inline JSON Schema has no `kind`).
  *
- *  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. */
+ *  Two `anyOf` branches because the value's shape depends on the phase at
+ *  which it is validated:
+ *
+ *   1. The raw `!ref` sentinel — what survives to AJV when a cross-module
+ *      reference can't be resolved in standalone single-file analysis (the
+ *      imported module isn't loaded). `substituteCelFields` deliberately
+ *      keeps the sentinel so this branch matches.
+ *   2. A resolved reference object — `{kind, name, alias?}` substituted in
+ *      place of a sentinel (or an inline definition `{kind, ...config}`
+ *      reached through a local `$ref` that escapes extraction). Both the
+ *      kernel and the analyzer validate ref slots *after* sentinel
+ *      resolution, so this is the shape AJV usually sees.
+ *
+ *  The object-form `{kind, name}` reference a user could once type directly
+ *  is gone: a plain object at a ref slot is only ever an inline definition
+ *  or the resolver's own substitution, never an author-written reference.
+ *  That removal is enforced by the analyzer (it rejects an author-written
+ *  `{kind, name}` before normalization), not by this schema — branch 2
+ *  cannot distinguish an author's `{kind, name}` from the resolver's. */
 export const ResourceRefSchema = {
-    type: "object",
-    required: ["__tagged", "engine", "source"],
-    properties: {
-        __tagged: { const: true },
-        engine: { const: "ref" },
-        source: { type: "string", minLength: 1 },
-    },
-    additionalProperties: false,
+    title: "Resource reference",
+    anyOf: [
+        {
+            type: "object",
+            required: ["__tagged", "engine", "source"],
+            properties: {
+                __tagged: { const: true },
+                engine: { const: "ref" },
+                source: { type: "string", minLength: 1 },
+            },
+            additionalProperties: false,
+        },
+        {
+            type: "object",
+            required: ["kind"],
+            properties: { kind: { type: "string" } },
+            additionalProperties: true,
+        },
+    ],
 };
+const REF_ANNOTATION = "x-telo-ref";
+// The legacy base types a reference slot used to pin when references were
+// written as plain strings. Post-migration a reference resolves to an object
+// (the `{kind, name, alias?}` shape, or an unresolved `!ref` sentinel), so a
+// scalar `type` on a ref slot is a stale constraint that would reject the
+// resolved value. Object / array `type`s are left alone — they already admit
+// the reference object (and any inline value a slot like `inputType` accepts).
+const LEGACY_REF_SCALAR_TYPES = new Set(["string", "number", "integer", "boolean"]);
+// JSON Schema keywords whose values are themselves subschemas. Split by shape so
+// the ref-slot normalizer recurses only into schema positions — never into
+// data-bearing keywords (`default`, `const`, `enum`, `examples`), where a stray
+// `x-telo-ref` key would be data, not an annotation.
+const SUBSCHEMA_SINGLE = [
+    "additionalProperties",
+    "additionalItems",
+    "contains",
+    "not",
+    "if",
+    "then",
+    "else",
+    "propertyNames",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+];
+const SUBSCHEMA_LIST = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const SUBSCHEMA_MAP = [
+    "properties",
+    "patternProperties",
+    "$defs",
+    "definitions",
+    "dependentSchemas",
+];
+/** Deep-clone `schema`, dropping the stale scalar `type` constraint from every
+ *  reference-slot node — one carrying an `x-telo-ref` string annotation.
+ *
+ *  A reference slot's value is always a `!ref` sentinel or its resolved
+ *  `{kind, name, alias?}` object (never a bare string, post-migration). Older
+ *  published modules still pin `type: "string"` on these slots — the encoding
+ *  references took when they were written as plain strings — which now rejects
+ *  the resolved object. Removing only the scalar `type` lets the analyzer and
+ *  kernel accept references uniformly across module versions during the
+ *  migration away from `{kind, name}` / string references, without disturbing
+ *  slots that legitimately accept an inline object (e.g. `inputType` /
+ *  `outputType`, which take a Telo.Type reference *or* an inline JSON schema).
+ *  The `x-telo-ref` constraint itself (which kind the reference must satisfy) is
+ *  checked separately by the analyzer's reference walker, which reads the
+ *  original schema — not this validation-only copy. */
+export function normalizeRefSlots(schema) {
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+        return schema;
+    }
+    const node = schema;
+    const out = { ...node };
+    // Reference slot with a stale scalar `type` (legacy string-ref encoding):
+    // drop the constraint so the resolved reference object / sentinel validates.
+    if (typeof node[REF_ANNOTATION] === "string" &&
+        typeof node.type === "string" &&
+        LEGACY_REF_SCALAR_TYPES.has(node.type)) {
+        delete out.type;
+    }
+    for (const key of SUBSCHEMA_SINGLE) {
+        const value = node[key];
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            out[key] = normalizeRefSlots(value);
+        }
+    }
+    for (const key of SUBSCHEMA_LIST) {
+        const value = node[key];
+        if (Array.isArray(value))
+            out[key] = value.map(normalizeRefSlots);
+    }
+    // `items` is either a single subschema or a tuple of subschemas.
+    if (Array.isArray(node.items)) {
+        out.items = node.items.map(normalizeRefSlots);
+    }
+    else if (node.items && typeof node.items === "object") {
+        out.items = normalizeRefSlots(node.items);
+    }
+    for (const key of SUBSCHEMA_MAP) {
+        const value = node[key];
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            const mapped = {};
+            for (const [name, sub] of Object.entries(value)) {
+                mapped[name] = normalizeRefSlots(sub);
+            }
+            out[key] = mapped;
+        }
+    }
+    return out;
+}
 /** 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;

package/package.json

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

package/src/index.ts

@@ -41,4 +41,5 @@ export {
   MANIFEST_SCHEMA_URI,
   ManifestRootSchema,
   ResourceRefSchema,
+  normalizeRefSlots,
 } from "./manifest-schemas.js";

package/src/manifest-schemas.ts

@@ -6,29 +6,154 @@
  *  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.
+/** Schema fragment for a resource-reference slot. The only form a manifest
+ *  author writes is the `!ref <name>` (or `!ref <Alias>.<name>`) YAML tag,
+ *  which parses to a `TaggedSentinel` (engine "ref") whose `source` is the
+ *  bare resource name. In practice module schemas mark a ref slot with a bare
+ *  `x-telo-ref` annotation (plus, where the slot only ever holds a reference,
+ *  `type: object` to reject a stray scalar); the analyzer's reference walker
+ *  reads `x-telo-ref` to look the name up against that constraint, independent
+ *  of this fragment. A slot opts into `$ref:
+ *  "telo://manifest#/$defs/ResourceRef"` only when it wants this exact
+ *  two-branch shape enforced at the AJV layer too — it is not required, and
+ *  slots that also accept an inline value (e.g. `inputType` / `outputType`)
+ *  deliberately do not use it (an inline JSON Schema has no `kind`).
  *
- *  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. */
+ *  Two `anyOf` branches because the value's shape depends on the phase at
+ *  which it is validated:
+ *
+ *   1. The raw `!ref` sentinel — what survives to AJV when a cross-module
+ *      reference can't be resolved in standalone single-file analysis (the
+ *      imported module isn't loaded). `substituteCelFields` deliberately
+ *      keeps the sentinel so this branch matches.
+ *   2. A resolved reference object — `{kind, name, alias?}` substituted in
+ *      place of a sentinel (or an inline definition `{kind, ...config}`
+ *      reached through a local `$ref` that escapes extraction). Both the
+ *      kernel and the analyzer validate ref slots *after* sentinel
+ *      resolution, so this is the shape AJV usually sees.
+ *
+ *  The object-form `{kind, name}` reference a user could once type directly
+ *  is gone: a plain object at a ref slot is only ever an inline definition
+ *  or the resolver's own substitution, never an author-written reference.
+ *  That removal is enforced by the analyzer (it rejects an author-written
+ *  `{kind, name}` before normalization), not by this schema — branch 2
+ *  cannot distinguish an author's `{kind, name}` from the resolver's. */
 export const ResourceRefSchema = {
-  type: "object",
-  required: ["__tagged", "engine", "source"],
-  properties: {
-    __tagged: { const: true },
-    engine: { const: "ref" },
-    source: { type: "string", minLength: 1 },
-  },
-  additionalProperties: false,
+  title: "Resource reference",
+  anyOf: [
+    {
+      type: "object",
+      required: ["__tagged", "engine", "source"],
+      properties: {
+        __tagged: { const: true },
+        engine: { const: "ref" },
+        source: { type: "string", minLength: 1 },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      required: ["kind"],
+      properties: { kind: { type: "string" } },
+      additionalProperties: true,
+    },
+  ],
 };
 
+const REF_ANNOTATION = "x-telo-ref";
+
+// The legacy base types a reference slot used to pin when references were
+// written as plain strings. Post-migration a reference resolves to an object
+// (the `{kind, name, alias?}` shape, or an unresolved `!ref` sentinel), so a
+// scalar `type` on a ref slot is a stale constraint that would reject the
+// resolved value. Object / array `type`s are left alone — they already admit
+// the reference object (and any inline value a slot like `inputType` accepts).
+const LEGACY_REF_SCALAR_TYPES = new Set(["string", "number", "integer", "boolean"]);
+
+// JSON Schema keywords whose values are themselves subschemas. Split by shape so
+// the ref-slot normalizer recurses only into schema positions — never into
+// data-bearing keywords (`default`, `const`, `enum`, `examples`), where a stray
+// `x-telo-ref` key would be data, not an annotation.
+const SUBSCHEMA_SINGLE = [
+  "additionalProperties",
+  "additionalItems",
+  "contains",
+  "not",
+  "if",
+  "then",
+  "else",
+  "propertyNames",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+] as const;
+const SUBSCHEMA_LIST = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
+const SUBSCHEMA_MAP = [
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+] as const;
+
+/** Deep-clone `schema`, dropping the stale scalar `type` constraint from every
+ *  reference-slot node — one carrying an `x-telo-ref` string annotation.
+ *
+ *  A reference slot's value is always a `!ref` sentinel or its resolved
+ *  `{kind, name, alias?}` object (never a bare string, post-migration). Older
+ *  published modules still pin `type: "string"` on these slots — the encoding
+ *  references took when they were written as plain strings — which now rejects
+ *  the resolved object. Removing only the scalar `type` lets the analyzer and
+ *  kernel accept references uniformly across module versions during the
+ *  migration away from `{kind, name}` / string references, without disturbing
+ *  slots that legitimately accept an inline object (e.g. `inputType` /
+ *  `outputType`, which take a Telo.Type reference *or* an inline JSON schema).
+ *  The `x-telo-ref` constraint itself (which kind the reference must satisfy) is
+ *  checked separately by the analyzer's reference walker, which reads the
+ *  original schema — not this validation-only copy. */
+export function normalizeRefSlots(schema: unknown): unknown {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+    return schema;
+  }
+  const node = schema as Record<string, unknown>;
+  const out: Record<string, unknown> = { ...node };
+  // Reference slot with a stale scalar `type` (legacy string-ref encoding):
+  // drop the constraint so the resolved reference object / sentinel validates.
+  if (
+    typeof node[REF_ANNOTATION] === "string" &&
+    typeof node.type === "string" &&
+    LEGACY_REF_SCALAR_TYPES.has(node.type)
+  ) {
+    delete out.type;
+  }
+  for (const key of SUBSCHEMA_SINGLE) {
+    const value = node[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      out[key] = normalizeRefSlots(value);
+    }
+  }
+  for (const key of SUBSCHEMA_LIST) {
+    const value = node[key];
+    if (Array.isArray(value)) out[key] = value.map(normalizeRefSlots);
+  }
+  // `items` is either a single subschema or a tuple of subschemas.
+  if (Array.isArray(node.items)) {
+    out.items = node.items.map(normalizeRefSlots);
+  } else if (node.items && typeof node.items === "object") {
+    out.items = normalizeRefSlots(node.items);
+  }
+  for (const key of SUBSCHEMA_MAP) {
+    const value = node[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const mapped: Record<string, unknown> = {};
+      for (const [name, sub] of Object.entries(value as Record<string, unknown>)) {
+        mapped[name] = normalizeRefSlots(sub);
+      }
+      out[key] = mapped;
+    }
+  }
+  return out;
+}
+
 /** 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;