@telorun/analyzer 0.57.0 → 0.59.0

package/dist/resolve-schema-type-refs.js

@@ -2,28 +2,51 @@ import { canonicalTypeSchemaId, parseTeloTypeRef } from "@telorun/sdk";
 /** Schema-bearing fields on a Telo.Definition / Telo.Type resource. */
 const SCHEMA_FIELDS = ["schema", "inputType", "outputType"];
 /**
- * Rewrites import-scoped schema references in place. A `$ref` of the form
- * `telo://<authority>/<typeName>` names a `Type.JsonSchema` (or any `Telo.Type`)
- * reached through an import: `telo://Self/<type>` for the declaring module's own
- * type, `telo://<Alias>/<type>` for an imported module's. Each authority is
- * resolved to the owning module's name and the ref is rewritten to the canonical
- * `telo://<module>/<type>` the type registered its schema under.
+ * Rewrites schema references to their canonical, module-scoped form, in place.
  *
- * The version lives on the `imports:` entry, never the URI — only the pinned
- * version is loaded, so the canonical id is version-free.
+ * A named shape is written with the reference tag — `!ref File` for the declaring
+ * module's own, `!ref <Alias>.<File>` for one an imported library exports — which
+ * is Telo's ONE reference grammar, and `use: schema` has been in the `x-telo-ref`
+ * vocabulary for exactly this relation all along (*names a shape; no runtime
+ * instance, no edge*). Phase 2.5 has already turned the tag into `{kind, name,
+ * alias?}`; this pass turns that into `{ $ref: "telo:<module>/<type>" }`, the id
+ * the type registered its schema under.
  *
- * Already-canonical refs (authority is a real module name, not an alias) and
- * fragment-bearing built-ins (`telo://manifest#/$defs/ResourceRef`) are left
- * untouched: the former because the authority resolves to nothing, the latter
- * because they don't match the `authority/type` grammar.
+ * WHY NORMALIZE RATHER THAN RESOLVE. Substituting the shape itself would inline
+ * it, which changes schema identity — the compiled-validator cache is keyed on it
+ * — and would make a self-recursive shape inexpressible. Keeping a REFERENCE is
+ * what every validator wants, and it is not an AJV concern: a Rust validator
+ * wants a registered id just as much. So the tag is the authoring surface and the
+ * canonical `$ref` is the internal form, exactly as `resolveRefSentinels` and
+ * `resolveSchemaRefKinds` already split authoring sugar from canonical form.
+ *
+ * ALIAS SCOPE IS WHAT THE CANONICAL FORM CARRIES. The authority is resolved in
+ * the DECLARING module's scope, so the id names the owning module and two
+ * libraries declaring a shape of the same name stay distinct. A downstream
+ * resolver reads the module off the id instead of matching a bare name, which is
+ * how an alias used to get silently dropped.
+ *
+ * The legacy authoring spelling `$ref: "telo://<authority>/<type>"` is resolved
+ * the same way, since a published artifact carries it. The version lives on the
+ * `imports:` entry, never the URI — only the pinned version is loaded, so the
+ * canonical id is version-free. Already-canonical refs and fragment-bearing
+ * built-ins (`telo://manifest#/$defs/ResourceRef`) are left untouched: the former
+ * because the authority resolves to nothing, the latter because they do not match
+ * the `authority/type` grammar.
  */
 export function resolveSchemaTypeRefs(resources, aliases, aliasesByModule) {
-    const walk = (value, resolveAuthority) => {
+    const walk = (value, resolveAuthority, ownModule, 
+    // The type field's OWN value is a declared reference slot (`x-telo-ref:
+    // Telo.Type`), with its own reference validation and its own editor picker.
+    // Only what sits INSIDE it is schema, and only schema is this pass's to
+    // canonicalize — rewriting the slot itself would hand the reference checker
+    // a shape it is right to reject.
+    isSlotRoot) => {
         if (value === null || typeof value !== "object")
             return;
         if (Array.isArray(value)) {
             for (const item of value)
-                walk(item, resolveAuthority);
+                walk(item, resolveAuthority, ownModule, false);
             return;
         }
         const obj = value;
@@ -33,15 +56,65 @@ export function resolveSchemaTypeRefs(resources, aliases, aliasesByModule) {
             if (module)
                 obj.$ref = canonicalTypeSchemaId(module, parsed.typeName);
         }
+        // A reference the tag left behind. Rewritten in place rather than replaced,
+        // so a node that carried siblings (a `title`, a `description`) keeps them —
+        // a `$ref` beside other keywords is ordinary JSON Schema.
+        const named = resolvedRefInSchema(obj);
+        if (named) {
+            const module = named.alias === undefined ? ownModule : resolveAuthority(named.alias);
+            // An unresolvable alias is left exactly as written: `validateReferences`
+            // is what reports a reference that names nothing, and guessing a module
+            // here would turn a typo into a `$ref` that resolves to the wrong shape.
+            if (module) {
+                const canonical = canonicalTypeSchemaId(module, named.name);
+                if (isSlotRoot) {
+                    // At the slot root the reference STAYS a reference — the canonical id
+                    // is stamped beside it. That is what makes the resolver alias-aware
+                    // here: it reads the module off the id instead of matching a bare
+                    // `metadata.name` across a flattened list, where two libraries
+                    // declaring a shape of the same name collide silently.
+                    obj.$ref = canonical;
+                }
+                else {
+                    delete obj.kind;
+                    delete obj.name;
+                    delete obj.alias;
+                    obj.$ref = canonical;
+                }
+            }
+        }
         for (const key of Object.keys(obj))
-            walk(obj[key], resolveAuthority);
+            walk(obj[key], resolveAuthority, ownModule, false);
     };
     for (const r of resources) {
         const ownModule = r.metadata?.module;
         const resolver = (ownModule ? aliasesByModule?.get(ownModule) : undefined) ?? aliases;
         const resolveAuthority = (authority) => authority === "Self" ? ownModule : resolver?.moduleForAlias(authority);
         for (const field of SCHEMA_FIELDS) {
-            walk(r[field], resolveAuthority);
+            walk(r[field], resolveAuthority, ownModule, true);
         }
     }
 }
+/**
+ * A resolved `!ref` sitting where a schema belongs, or null.
+ *
+ * Recognised structurally: Phase 2.5 writes `{kind, name, alias?}` and nothing
+ * else, and a node carrying JSON Schema keywords is a schema that happens to be
+ * beside one rather than a reference. Being conservative here is the safe
+ * direction — a node this declines to rewrite stays a reference for
+ * `validateReferences` to judge, while one it rewrote wrongly would silently
+ * become a different shape.
+ */
+function resolvedRefInSchema(obj) {
+    if (typeof obj.kind !== "string" || typeof obj.name !== "string")
+        return null;
+    for (const key of Object.keys(obj)) {
+        // `$ref` is allowed so the pass is idempotent at a slot root, where the id
+        // is stamped BESIDE the reference rather than replacing it.
+        if (key !== "kind" && key !== "name" && key !== "alias" && key !== "$ref")
+            return null;
+    }
+    return typeof obj.alias === "string"
+        ? { name: obj.name, alias: obj.alias }
+        : { name: obj.name };
+}

package/dist/schema-compat.d.ts

@@ -12,10 +12,29 @@ export interface CompatibilityResult {
     compatible: boolean;
     issues: string[];
 }
-/** Conservative structural JSON Schema compatibility check.
- *  Only flags definite mismatches: missing required fields and primitive type conflicts.
- *  Ambiguous cases (anyOf/oneOf/etc.) are treated as compatible. */
-export declare function checkSchemaCompatibility(source: Record<string, any>, target: Record<string, any>): CompatibilityResult;
+/**
+ * Conservative structural JSON Schema compatibility check — is a value shaped
+ * like `source` acceptable where `target` is declared?
+ *
+ * COVARIANT, because the values this compares are consumed by reading: a
+ * narrower element satisfies a slot declaring a wider one. Only DEFINITE
+ * mismatches are flagged — a missing required field, a primitive type conflict,
+ * a disagreeing type argument. Anything ambiguous (`anyOf` / `oneOf` / `allOf`,
+ * an absent `type`, an undeclared argument) is treated as compatible, so an
+ * unmigrated producer and consumer keep checking exactly as they did.
+ *
+ * The traversal is written here rather than reused: the function this replaced
+ * compared only `type` for the names in `target.required` and descended only
+ * into objects, so a stream of arrays of strings and a stream of arrays of
+ * integers both read as `array` and passed — leaving argument checking inert on
+ * exactly the nested shapes it exists for. What survives from it is its posture.
+ *
+ * `resolveRef` sees through a named shape. Declaring a shape once and
+ * referencing it is the sanctioned way to reuse one, so without it two such
+ * arguments present as opaque nodes carrying no information — the same reason
+ * {@link withLiveValuesSkipped} takes one.
+ */
+export declare function checkSchemaCompatibility(source: Record<string, any>, target: Record<string, any>, resolveRef?: (ref: string) => Record<string, any> | undefined): CompatibilityResult;
 export declare function formatSingleError(err: any): string;
 export declare function formatAjvErrors(errors: any[] | null | undefined): string;
 /** A schema validation issue with a dotted-path pointer to the offending field. */
@@ -36,14 +55,21 @@ export declare function navigateJsonPointer(schema: unknown, pointer: string): u
  *  Returns `undefined` if any segment cannot be resolved. */
 export declare function navigateSchemaToExprPath(schema: Record<string, any>, path: string): Record<string, any> | undefined;
 /**
- * Recognized `x-telo-type` value brands and the CEL primitive each refines.
+ * Every `json`-represented value type's CEL brand → the primitive it refines.
+ *
  * A brand is a nominal type the analyzer registers (see cel-environment.ts) so
- * structurally-identical values (a `TcpPort` and a `UdpPort` are both integers)
- * stay distinct for static wiring checks. Brands carry no runtime effect — the
- * value flows as its base type. Add new brands here (e.g. `Url: "string"`).
+ * structurally-identical values (a `Telo.TcpPort` and a `Telo.UdpPort` are both
+ * integers) stay distinct for static wiring checks. Brands carry no runtime
+ * effect — the value flows as its base type.
+ *
+ * DERIVED from the value-type vocabulary, never hand-written: a new brand is a
+ * new entry file, and a table here would be a second place to edit that could
+ * silently disagree with the one the runtime reads.
  */
 export declare const VALUE_BRAND_BASE: Record<string, string>;
-/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+/** Read a `json`-represented value type's brand off a schema, or undefined.
+ *  An `instance` type is not a brand — it replaces the JSON layer rather than
+ *  refining it, so it carries its binding's CEL type instead. */
 export declare function brandOfSchema(schema: Record<string, any> | undefined): string | undefined;
 /** Map a JSON Schema type annotation to a CEL type string. */
 export declare function jsonSchemaToCelType(schema: Record<string, any> | undefined): string;
@@ -52,6 +78,24 @@ export declare function celTypeSatisfiesJsonSchema(celType: string, schema: Reco
 export declare function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown;
 /** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
 export declare function resolveRef(schema: Record<string, any>, root: Record<string, any>): Record<string, any>;
+/** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
+/**
+ * The `oneOf` / `anyOf` branch a value is written against, when exactly one fits.
+ *
+ * A union carries no `type` / `properties` / `items` of its own, so a walker that
+ * ignores it descends with an empty schema and hands every CEL leaf underneath a
+ * `null` placeholder — which then fails every branch and reports a pile of
+ * violations against a value that is perfectly valid. Picking the branch first
+ * is what lets the leaves be typed.
+ *
+ * Selection is structural and conservative: a branch must agree with the data's
+ * kind, and for an object every `required` key must be present (which is what
+ * separates a `{type, text}` part from a `{type, data, mediaType}` one). If that
+ * leaves anything other than exactly one branch, the union is returned unchanged
+ * — an ambiguous union is one the analyzer should not resolve on the author's
+ * behalf.
+ */
+export declare function selectUnionBranch(schema: Record<string, any>, data: unknown, root: Record<string, any>): Record<string, any>;
 export declare function collectProperties(schema: Record<string, any>): Record<string, any>;
 /** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
  *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */

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

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAYA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAWpD;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;AAaD,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CA2B/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;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAyBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiChG;AAkED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CA0C/E;AAqBD,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAyDD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAwBlF;AAED;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;AAChC;;;;;;;;6DAQ6D;AAC7D,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EACrC,IAAI,SAAK,GACR,OAAO,CA2DT"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"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"}

package/dist/schema-compat.js

@@ -1,7 +1,8 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { INCLUDE_BYTES_ENGINE, INCLUDE_ENGINE_NAMES, isRefSentinel, isTaggedSentinel, ManifestRootSchema, normalizeRefSlots, } from "@telorun/templating";
-import { binaryKeyword, isBinarySlot } from "./binary-slot.js";
+import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, producedTypeOf, } from "@telorun/templating";
+import { celBaseOfValueType, celTypeOfValueType, readValueTypeSlot, valueBrandBases, valueTypeOf, valueTypePlaceholder, } from "@telorun/sdk";
+import { registerTeloKeywords } from "./value-type-keyword.js";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
  *  Also registers the kernel manifest root schema under `telo://manifest` so
@@ -16,53 +17,181 @@ export function createAjv() {
     addFormats.default
         ? addFormats.default(instance)
         : addFormats(instance);
-    // Bytes have no JSON Schema type, so the annotation carries the check. Registered
-    // here and in the kernel's validators from one definition, so a literal at a byte
-    // slot is rejected statically and at dispatch by the identical rule.
-    instance.addKeyword(binaryKeyword());
+    // One registration site for every Telo keyword — the annotations as no-ops and
+    // `x-telo-type` as the one that checks. Registered here and in the kernel's
+    // validators from one definition, so a literal at an instance-typed slot is
+    // rejected statically and at dispatch by the identical rule.
+    registerTeloKeywords(instance);
     instance.addSchema(ManifestRootSchema);
     return instance;
 }
 const ajv = createAjv();
 const compiledSchemaValidators = new WeakMap();
-/** Conservative structural JSON Schema compatibility check.
- *  Only flags definite mismatches: missing required fields and primitive type conflicts.
- *  Ambiguous cases (anyOf/oneOf/etc.) are treated as compatible. */
-export function checkSchemaCompatibility(source, target) {
+/** The alternatives a union node declares, or undefined when it is not one.
+ *  `anyOf` and `oneOf` are one question here — which branches could accept this
+ *  value — and their difference (exactly-one vs at-least-one) is a validation
+ *  rule, not a compatibility one. */
+function unionBranches(schema) {
+    const branches = schema.anyOf ?? schema.oneOf;
+    if (!Array.isArray(branches) || branches.length === 0)
+        return undefined;
+    return branches.filter((b) => b && typeof b === "object");
+}
+/**
+ * Conservative structural JSON Schema compatibility check — is a value shaped
+ * like `source` acceptable where `target` is declared?
+ *
+ * COVARIANT, because the values this compares are consumed by reading: a
+ * narrower element satisfies a slot declaring a wider one. Only DEFINITE
+ * mismatches are flagged — a missing required field, a primitive type conflict,
+ * a disagreeing type argument. Anything ambiguous (`anyOf` / `oneOf` / `allOf`,
+ * an absent `type`, an undeclared argument) is treated as compatible, so an
+ * unmigrated producer and consumer keep checking exactly as they did.
+ *
+ * The traversal is written here rather than reused: the function this replaced
+ * compared only `type` for the names in `target.required` and descended only
+ * into objects, so a stream of arrays of strings and a stream of arrays of
+ * integers both read as `array` and passed — leaving argument checking inert on
+ * exactly the nested shapes it exists for. What survives from it is its posture.
+ *
+ * `resolveRef` sees through a named shape. Declaring a shape once and
+ * referencing it is the sanctioned way to reuse one, so without it two such
+ * arguments present as opaque nodes carrying no information — the same reason
+ * {@link withLiveValuesSkipped} takes one.
+ */
+export function checkSchemaCompatibility(source, target, resolveRef) {
     const issues = [];
-    checkObject(source, target, "", issues);
+    compare(source, target, "", issues, resolveRef, new Set());
     return { compatible: issues.length === 0, issues };
 }
-function checkObject(source, target, path, issues) {
-    const targetRequired = target.required ?? [];
+function deref(schema, resolveRef) {
+    if (!resolveRef || typeof schema.$ref !== "string")
+        return schema;
+    return resolveRef(schema.$ref) ?? schema;
+}
+function compare(rawSource, rawTarget, path, issues, resolveRef, seen) {
+    if (!rawSource || !rawTarget || typeof rawSource !== "object" || typeof rawTarget !== "object") {
+        return;
+    }
+    // A recursive shape reached through the same pair of references twice is the
+    // same question again; answering it once terminates and loses nothing.
+    //
+    // The key is the REFERENCE PAIR and deliberately not the path. A path grows on
+    // every descent, so a key containing it is new every time and the guard never
+    // fires — which is a stack overflow on the first self-referential shape, taking
+    // every other diagnostic in the file with it. It also has to be this way to be
+    // correct rather than merely terminating: comparing two schemas gives the same
+    // answer wherever they are reached from, so the second visit has nothing to add.
+    if (typeof rawSource.$ref === "string" && typeof rawTarget.$ref === "string") {
+        const key = `${rawSource.$ref}|${rawTarget.$ref}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+    }
+    const source = deref(rawSource, resolveRef);
+    const target = deref(rawTarget, resolveRef);
+    // A union is ALTERNATIVES, so it is compared by distributing over branches on
+    // both sides: a definite conflict is one where no source-branch/target-branch
+    // pair agrees. Returning silently the moment either side was a union — which
+    // is what this did — switched the whole comparison off for any slot that
+    // accepts more than one shape, and those are exactly the slots where a value
+    // type carries the only information distinguishing the branches.
+    //
+    // `allOf` is a conjunction rather than a choice, so it keeps the old posture:
+    // it says too little to judge and stays compatible.
+    if (source.allOf || target.allOf)
+        return;
+    const sourceBranches = unionBranches(source);
+    const targetBranches = unionBranches(target);
+    if (sourceBranches || targetBranches) {
+        const lefts = sourceBranches ?? [source];
+        const rights = targetBranches ?? [target];
+        const reasons = [];
+        for (const left of lefts) {
+            for (const right of rights) {
+                const probe = [];
+                // A fresh `seen` per probe: a pair rejected on one branch must not mark
+                // a reference pair visited for the next, which would silently pass it.
+                compare(left, right, path, probe, resolveRef, new Set(seen));
+                if (probe.length === 0)
+                    return;
+                reasons.push(...probe);
+            }
+        }
+        issues.push(`${path || "/"}: no alternative matches — ${[...new Set(reasons)].join("; ")}`);
+        return;
+    }
+    // Value types first: an `instance` representation has no JSON `type` to
+    // compare, so its identity IS the comparison — and its arguments are where the
+    // real information lives.
+    const sourceType = readValueTypeSlot(source);
+    const targetType = readValueTypeSlot(target);
+    if (sourceType && targetType) {
+        if (sourceType.name !== targetType.name) {
+            issues.push(`${path || "/"}: value type mismatch — source is '${sourceType.name}', target expects '${targetType.name}'`);
+            return;
+        }
+        for (const [argument, targetArg] of Object.entries(targetType.args)) {
+            const sourceArg = sourceType.args[argument];
+            // An omitted argument is *any*, in BOTH directions. That is what keeps a
+            // bare `Telo.Stream` flowing into a typed slot and vice versa, so nothing
+            // that does not declare its element is forced to.
+            if (sourceArg === undefined)
+                continue;
+            compare(sourceArg, targetArg, `${path}<${argument}>`, issues, resolveRef, seen);
+        }
+        return;
+    }
+    // One side declares a value type and the other does not. A `json`
+    // representation refines a base type, so it is compared through that base — a
+    // `Telo.TcpPort` into a plain `integer` slot is gradual typing working. An
+    // `instance` is not JSON at all, so ANY declared JSON type on the other side is
+    // a definite conflict; a side declaring no type at all is still saying nothing
+    // and stays compatible.
+    if (Boolean(sourceType) !== Boolean(targetType)) {
+        const declared = (sourceType ?? targetType);
+        const other = sourceType ? target : source;
+        if (declared.entry && typeof other.type === "string") {
+            const base = celBaseOfValueType(declared.entry);
+            const asJson = base === undefined ? undefined : declared.entry.base;
+            if (asJson !== other.type) {
+                issues.push(`${path || "/"}: value type mismatch — ${sourceType ? "source is" : "target expects"} '${declared.name}', ${sourceType ? "target expects" : "source is"} '${other.type}'`);
+                return;
+            }
+        }
+    }
+    // Only flag definite primitive type clashes; an absent or union `type` says
+    // too little to judge.
+    if (typeof source.type === "string" &&
+        typeof target.type === "string" &&
+        source.type !== target.type) {
+        issues.push(`${path || "/"}: type mismatch — source is '${source.type}', target expects '${target.type}'`);
+        return;
+    }
+    // An array's element, which the old comparison never looked at — so every
+    // nested shape passed regardless of what it contained.
+    if (target.items && source.items) {
+        compare(source.items, target.items, `${path}[]`, issues, resolveRef, seen);
+    }
+    const targetRequired = Array.isArray(target.required) ? target.required : [];
     const sourceProps = source.properties ?? {};
     const targetProps = target.properties ?? {};
     for (const field of targetRequired) {
         if (!(field in sourceProps)) {
+            // Only when the source describes an object at all: a schema with no
+            // `properties` is saying nothing about its shape, not saying it is empty.
+            if (source.properties === undefined)
+                continue;
             issues.push(`${path}/${field}: required by target but missing from source`);
             continue;
         }
         const srcProp = sourceProps[field];
         const tgtProp = targetProps[field];
         if (tgtProp && srcProp) {
-            checkProperty(srcProp, tgtProp, `${path}/${field}`, issues);
+            compare(srcProp, tgtProp, `${path}/${field}`, issues, resolveRef, seen);
         }
     }
 }
-function checkProperty(source, target, path, issues) {
-    // Only flag definite primitive type clashes; skip anyOf/oneOf/allOf
-    if (source.type &&
-        target.type &&
-        typeof source.type === "string" &&
-        typeof target.type === "string" &&
-        source.type !== target.type) {
-        issues.push(`${path}: type mismatch — source is '${source.type}', target expects '${target.type}'`);
-        return;
-    }
-    if (target.type === "object" && source.type === "object") {
-        checkObject(source, target, path, issues);
-    }
-}
 export function formatSingleError(err) {
     const p = err.instancePath || "/";
     const params = err.params ?? {};
@@ -120,13 +249,8 @@ function schemaCompiles(schema) {
 export function validateAgainstSchema(data, schema) {
     let validate = compiledSchemaValidators.get(schema);
     if (!validate) {
-        // Normalize outside the try: a fault in our own ref-slot normalization must
-        // surface, never be mistaken for the module author's schema being malformed.
-        // Drop the legacy scalar `type` an older published module may still pin on
-        // its `x-telo-ref` slots so a resolved reference object validates.
-        const normalized = normalizeRefSlots(schema);
         try {
-            validate = ajv.compile(normalized);
+            validate = ajv.compile(schema);
         }
         catch (err) {
             // The normalized schema didn't compile. If the original schema is itself
@@ -198,28 +322,36 @@ export function navigateSchemaToExprPath(schema, path) {
     return current;
 }
 /**
- * Recognized `x-telo-type` value brands and the CEL primitive each refines.
+ * Every `json`-represented value type's CEL brand → the primitive it refines.
+ *
  * A brand is a nominal type the analyzer registers (see cel-environment.ts) so
- * structurally-identical values (a `TcpPort` and a `UdpPort` are both integers)
- * stay distinct for static wiring checks. Brands carry no runtime effect — the
- * value flows as its base type. Add new brands here (e.g. `Url: "string"`).
+ * structurally-identical values (a `Telo.TcpPort` and a `Telo.UdpPort` are both
+ * integers) stay distinct for static wiring checks. Brands carry no runtime
+ * effect — the value flows as its base type.
+ *
+ * DERIVED from the value-type vocabulary, never hand-written: a new brand is a
+ * new entry file, and a table here would be a second place to edit that could
+ * silently disagree with the one the runtime reads.
  */
-export const VALUE_BRAND_BASE = {
-    TcpPort: "int",
-    UdpPort: "int",
-};
-/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+export const VALUE_BRAND_BASE = valueBrandBases();
+/** Read a `json`-represented value type's brand off a schema, or undefined.
+ *  An `instance` type is not a brand — it replaces the JSON layer rather than
+ *  refining it, so it carries its binding's CEL type instead. */
 export function brandOfSchema(schema) {
-    const brand = schema?.["x-telo-type"];
-    return typeof brand === "string" && brand in VALUE_BRAND_BASE ? brand : undefined;
+    const entry = valueTypeOf(schema);
+    return entry && entry.representation === "json" ? entry.name : undefined;
 }
 /** Map a JSON Schema type annotation to a CEL type string. */
 export function jsonSchemaToCelType(schema) {
     if (!schema || typeof schema !== "object")
         return "dyn";
-    const brand = brandOfSchema(schema);
-    if (brand)
-        return brand;
+    // A declared value type IS the type — for an `instance` representation it is
+    // the only thing that says so, since bytes and streams have no JSON Schema
+    // type at all. Before the three annotations were unified, a byte slot's
+    // expression typed as `dyn` because nothing here consulted `x-telo-binary`.
+    const entry = valueTypeOf(schema);
+    if (entry)
+        return celTypeOfValueType(entry);
     if (schema.anyOf || schema.oneOf || schema.allOf)
         return "dyn";
     if (Array.isArray(schema.type))
@@ -263,10 +395,28 @@ export function celTypeSatisfiesJsonSchema(celType, schema) {
             return fieldBrand === celType;
         celType = sourceBase;
     }
+    // An `instance` representation has no JSON Schema type to compare against, so
+    // an expression carrying its binding's CEL type is accepted on that ground
+    // alone. This ADDS a case and never removes one: a mismatch falls through to
+    // the rules below rather than being rejected here, so nothing that checks
+    // today stops checking, and the `bytes` row still accepts a byte expression at
+    // a plain `type: string` slot.
+    const slotEntry = valueTypeOf(schema);
+    if (slotEntry?.representation === "instance" && celTypeOfValueType(slotEntry) === celType) {
+        return true;
+    }
     if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf)
         return true;
-    if (schema.anyOf || schema.oneOf || schema.allOf)
+    // `allOf` is a conjunction and says too little to judge from a single CEL
+    // type. A union is a CHOICE, so it is satisfied by satisfying any branch —
+    // distributed for the same reason `compare` does it: accepting every union
+    // outright turns the check off for exactly the slots that admit more than one
+    // shape, and those are the ones where the branches carry the information.
+    if (schema.allOf)
         return true;
+    const branches = unionBranches(schema);
+    if (branches)
+        return branches.some((branch) => celTypeSatisfiesJsonSchema(celType, branch));
     const schemaTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
     const accepted = {
         int: ["integer", "number"],
@@ -357,12 +507,16 @@ function foldedConstraints(schema) {
 }
 export function celPlaceholderForSchema(rawSchema) {
     const schema = foldedConstraints(rawSchema);
-    // A byte slot's placeholder must BE bytes: the same keyword validates statically
-    // and at dispatch, so a CEL leaf standing in for a runtime buffer has to satisfy
-    // it. This is what keeps the rule single — a literal is rejected because no YAML
-    // literal is a Uint8Array, while a value arriving by reference passes.
-    if (isBinarySlot(schema))
-        return new Uint8Array();
+    // An instance-typed slot's placeholder must BE an instance: the same keyword
+    // validates statically and at dispatch, so a CEL leaf standing in for a runtime
+    // value has to satisfy it. This is what keeps the rule single — a literal is
+    // rejected because no YAML literal is a byte buffer, while a value arriving by
+    // reference passes. The stand-in comes from the binding table, so a new
+    // instance type brings its own rather than adding a branch here; a `live` type
+    // declares none, because nothing validates it.
+    const placeholder = valueTypePlaceholder(schema);
+    if (placeholder !== undefined)
+        return placeholder;
     if (schema.default !== undefined)
         return schema.default;
     // An enum-constrained field needs a placeholder drawn from the enum: the
@@ -373,6 +527,24 @@ export function celPlaceholderForSchema(rawSchema) {
     // the real value is checked at runtime once the expression resolves.
     if (Array.isArray(schema.enum) && schema.enum.length > 0)
         return schema.enum[0];
+    // A UNION with no `type` of its own. Without this, a whole-field CEL leaf at
+    // such a slot gets `null`, which every branch then rejects — so a field
+    // declared `anyOf: [array, boolean]` could not be written as an expression at
+    // all, while one whose union happens to contain a `live` branch escaped by
+    // accident (nothing validates a live value, so `null` passed). The first
+    // branch that yields a placeholder wins: the same conservative posture
+    // `selectUnionBranch` takes, and enough for AJV, whose question is only
+    // whether SOME branch accepts the stand-in.
+    if (schema.type === undefined) {
+        const branches = unionBranches(schema);
+        if (branches) {
+            for (const branch of branches) {
+                const candidate = celPlaceholderForSchema(branch);
+                if (candidate !== null)
+                    return candidate;
+            }
+        }
+    }
     switch (schema.type) {
         case "integer":
         case "number":
@@ -444,7 +616,7 @@ export function resolveRef(schema, root) {
  * — an ambiguous union is one the analyzer should not resolve on the author's
  * behalf.
  */
-function selectUnionBranch(schema, data, root) {
+export function selectUnionBranch(schema, data, root) {
     const branches = (schema.oneOf ?? schema.anyOf);
     if (!Array.isArray(branches) || branches.length === 0)
         return schema;
@@ -537,16 +709,23 @@ onSubstitute, path = "") {
     if (isRefSentinel(data)) {
         return data;
     }
-    // A file embed's type is a CONSTANT of the tag, not a function of the slot:
-    // `!include-text` always produces a string and `!include-bytes` always
-    // produces bytes. Collapsing them to a slot-shaped placeholder like a CEL
-    // expression would make every slot accept both, so a byte embed at a
-    // `type: string` field passed `telo check` and failed at resource creation —
-    // and the reverse (text at an `x-telo-binary` slot) did too. Substituting the
-    // real type lets AJV and the `x-telo-binary` keyword reject both directions
-    // statically, with no new diagnostic code.
-    if (isTaggedSentinel(data) && INCLUDE_ENGINE_NAMES.has(data.engine)) {
-        return data.engine === INCLUDE_BYTES_ENGINE ? new Uint8Array() : "";
+    // A tag whose produced type is a CONSTANT of the tag rather than a function of
+    // the slot substitutes a placeholder of THAT type: `!include-text` always
+    // produces a string and `!include-bytes` always produces bytes. Collapsing
+    // them to a slot-shaped placeholder like a CEL expression would make every
+    // slot accept both, so a byte embed at a `type: string` field passed
+    // `telo check` and failed at resource creation — and the reverse did too.
+    // Substituting the real type lets AJV and the `x-telo-type` keyword reject
+    // both directions statically, with no new diagnostic code.
+    //
+    // The engine is what says so. This used to branch on two tag names, which was
+    // the only place a tag's produced type was written down and it was written in
+    // the consumer — so a future tag producing bytes had to be added to a set here
+    // rather than declaring it.
+    if (isTaggedSentinel(data)) {
+        const produced = producedTypeOf(data.engine);
+        if (produced)
+            return celPlaceholderForSchema(produced);
     }
     if (isTaggedSentinel(data)) {
         mark();