@telorun/analyzer 0.12.1 → 0.14.0

package/dist/resolve-ref-sentinels.js

@@ -1,38 +1,99 @@
 import { isRefSentinel } from "@telorun/templating";
+import { isModuleKind } from "./module-kinds.js";
 import { isRefEntry } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 /**
  * Walks every `x-telo-ref` slot in every non-system resource and rewrites
- * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ * `!ref <name>` sentinels in-place to `{kind, name}` (local) or
+ * `{kind, name, alias}` (cross-module).
  *
- * The downstream pipeline (inline normalization, dependency graph, kernel
- * controllers) expects every ref-slot value to be either a `{kind, name}`
- * object, an inline-definition object, or a legacy bare string — resolving
- * sentinels here keeps that contract intact so each consumer doesn't need
- * its own sentinel branch.
+ * Reference grammar — the tag's source string is split on the FIRST dot:
+ *   - `!ref writeLine`          → local resource `writeLine`
+ *   - `!ref Self.writeLine`     → local resource `writeLine` (explicit self-qualifier)
+ *   - `!ref Console.writeLine`  → instance `writeLine` exported by the import aliased
+ *                                 `Console`, resolved against the forwarded foreign set
  *
- * The walker assigns `kind` by name lookup (resource names are unique
- * within a manifest scope). When the name doesn't resolve in the local
- * `byName` map, the sentinel is left in place so `validateReferences`
- * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ * Aliases are PascalCase identifiers without dots and resource names carry no dots
+ * (enforced as a hard diagnostic), so the first-dot split is unambiguous. When the
+ * name doesn't resolve, the sentinel is left in place so `validateReferences` emits the
+ * `UNRESOLVED_REFERENCE` diagnostic with full context.
  *
- * Mutation strategy: the field-path walker descends the resource tree
- * directly and replaces the sentinel on its parent container. Re-parsing
- * a string-encoded concrete path (the earlier shape) coupled the writer
- * to the path-encoding rules of `resolveFieldEntries` — any new path
- * marker would silently break this writer. Descending directly avoids
- * that coupling.
+ * Forwarded foreign resources (an imported library's exported instances, carrying a
+ * `metadata.module` that isn't a root module) are resolution TARGETS only — they are not
+ * re-walked as sources here, since their own ref slots belong to their own module scope.
  */
-export function resolveRefSentinels(resources, registry, aliases, aliasesByModule) {
+export function resolveRefSentinels(resources, registry, aliases, aliasesByModule, 
+// Extra foreign resources used only as cross-module resolution TARGETS (not mutated, not
+// walked as sources). The kernel passes the analyzer-flattened set here so the runtime
+// pass — which loads the entry module only — can still resolve `!ref Alias.name` against
+// imported libraries' exported instances.
+crossModuleTargets = []) {
+    const rootModules = new Set();
+    for (const r of resources) {
+        if (isModuleKind(r.kind) && typeof r.metadata?.name === "string") {
+            rootModules.add(r.metadata.name);
+        }
+    }
+    const moduleOf = (r) => r.metadata?.module;
+    const isForeign = (r) => {
+        const mod = moduleOf(r);
+        return typeof mod === "string" && !rootModules.has(mod);
+    };
+    // Local resources resolve a bare / `Self.`-qualified name; forwarded foreign exports
+    // resolve an `Alias.`-qualified name keyed by (module, name).
     const byName = new Map();
+    const byModuleName = new Map();
     for (const r of resources) {
-        if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
-            byName.set(r.metadata.name, r);
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind))
+            continue;
+        const name = r.metadata.name;
+        if (isForeign(r)) {
+            byModuleName.set(`${moduleOf(r)}\0${name}`, r);
         }
+        else {
+            byName.set(name, r);
+        }
+    }
+    for (const r of crossModuleTargets) {
+        if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
+            continue;
+        byModuleName.set(`${moduleOf(r)}\0${r.metadata.name}`, r);
     }
+    const resolveTarget = (source) => {
+        const dot = source.indexOf(".");
+        if (dot === -1) {
+            const t = byName.get(source);
+            return t ? { kind: t.kind, name: source } : undefined;
+        }
+        const alias = source.slice(0, dot);
+        const name = source.slice(dot + 1);
+        if (alias === "Self") {
+            const t = byName.get(name);
+            return t ? { kind: t.kind, name } : undefined;
+        }
+        const module = aliases?.moduleForAlias(alias);
+        if (module) {
+            const t = byModuleName.get(`${module}\0${name}`);
+            if (t) {
+                // The foreign instance's `kind` is authored in ITS module's scope (e.g.
+                // `Self.WriteLine`); canonicalize to a scope-independent `<module>.<Kind>` for the
+                // consumer's kind check. `Self.` maps to the owning module directly — the forwarded
+                // library's Library doc (hence its `Self` alias) isn't in the consumer's manifest
+                // set — while other alias prefixes resolve via that module's forwarded import scope.
+                const rawKind = t.kind;
+                const foreignKind = rawKind.startsWith("Self.")
+                    ? `${module}.${rawKind.slice("Self.".length)}`
+                    : aliasesByModule?.get(module)?.resolveKind(rawKind) ?? rawKind;
+                return { kind: foreignKind, name, alias };
+            }
+        }
+        return undefined;
+    };
     for (const r of resources) {
         if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
             continue;
+        if (isForeign(r))
+            continue;
         const fieldMap = aliases && aliasesByModule
             ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
             : registry.getFieldMapForKind(r.kind, aliases);
@@ -41,37 +102,30 @@ export function resolveRefSentinels(resources, registry, aliases, aliasesByModul
         for (const [fieldPath, entry] of fieldMap) {
             if (!isRefEntry(entry))
                 continue;
-            replaceSentinelsAtPath(r, fieldPath, byName);
+            descend(r, fieldPath.split("."), resolveTarget);
         }
     }
 }
-/** Walks `obj` along `fieldPath` (dot notation with `[]` for arrays and
- *  `{}` for additionalProperties-typed maps) and replaces any `!ref`
- *  sentinel value at the terminal slot with `{kind, name}` looked up
- *  via `byName`. Mutates the parent container in place; no string-path
- *  round-trip. */
-function replaceSentinelsAtPath(obj, fieldPath, byName) {
-    const parts = fieldPath.split(".");
-    descend(obj, parts, byName);
-}
-function descend(obj, parts, byName) {
+/** Walks `obj` along `fieldPath` parts (dot notation with `[]` for arrays and `{}` for
+ *  additionalProperties-typed maps) and replaces any `!ref` sentinel at the terminal slot
+ *  with its resolved `{kind, name, alias?}`. Mutates the parent container in place. */
+function descend(obj, parts, resolve) {
     if (obj == null || typeof obj !== "object" || parts.length === 0)
         return;
     const [head, ...rest] = parts;
-    // Map iteration: descend into every value of the current object.
     if (head === "{}") {
         const container = obj;
         for (const key of Object.keys(container)) {
             const child = container[key];
             if (rest.length === 0) {
                 if (isRefSentinel(child)) {
-                    const target = byName.get(child.source);
+                    const target = resolve(child.source);
                     if (target)
-                        container[key] = { kind: target.kind, name: child.source };
+                        container[key] = target;
                 }
             }
             else {
-                descend(child, rest, byName);
+                descend(child, rest, resolve);
             }
         }
         return;
@@ -89,26 +143,26 @@ function descend(obj, parts, byName) {
             if (rest.length === 0) {
                 const elem = val[i];
                 if (isRefSentinel(elem)) {
-                    const target = byName.get(elem.source);
+                    const target = resolve(elem.source);
                     if (target)
-                        val[i] = { kind: target.kind, name: elem.source };
+                        val[i] = target;
                 }
             }
             else {
-                descend(val[i], rest, byName);
+                descend(val[i], rest, resolve);
             }
         }
     }
     else {
         if (rest.length === 0) {
             if (isRefSentinel(val)) {
-                const target = byName.get(val.source);
+                const target = resolve(val.source);
                 if (target)
-                    container[key] = { kind: target.kind, name: val.source };
+                    container[key] = target;
             }
         }
         else {
-            descend(val, rest, byName);
+            descend(val, rest, resolve);
         }
     }
 }

package/dist/resolve-throws-union.d.ts

@@ -4,6 +4,10 @@ import type { DefinitionRegistry } from "./definition-registry.js";
 export interface ThrowsCodeMeta {
     data?: Record<string, any>;
 }
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export declare const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
 export interface ThrowsUnion {
     /** Code → per-code metadata (data schema, etc). Keys are the declared codes. */
     codes: Map<string, ThrowsCodeMeta>;
@@ -12,6 +16,12 @@ export interface ThrowsUnion {
      *  an unknown kind was encountered, or a cycle short-circuited resolution.
      *  Callers must treat unbounded unions as requiring a catch-all entry. */
     unbounded: boolean;
+    /** True when the block can fail with a non-`InvokeError` (any `invoke:` step).
+     *  Such a failure surfaces inside an enclosing `catch` as `PLAIN_ERROR_CODE`,
+     *  so a `throw: { code: "${{ error.code }}" }` rethrow can propagate it. Not
+     *  injected into `codes` — only seeds `enclosingTryCodes` at a try/catch site,
+     *  leaving non-rethrow unions untouched. */
+    canThrowPlain?: boolean;
 }
 export interface ResolveCtx {
     allManifests: ResourceManifest[];

package/dist/resolve-throws-union.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,GACrB,UAAU,CAQZ;AA+BD;;;;8CAI8C;AAC9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CA+Cb"}
+{"version":3,"file":"resolve-throws-union.d.ts","sourceRoot":"","sources":["../src/resolve-throws-union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;gFAEgF;AAChF,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACnC;;;8EAG0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;gDAI4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC/B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,gBAAgB,EAAE,EAChC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,GACrB,UAAU,CAQZ;AAgCD;;;;8CAI8C;AAC9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,UAAU,GACd,WAAW,CA+Cb"}

package/dist/resolve-throws-union.js

@@ -1,3 +1,8 @@
+import { isTaggedSentinel } from "@telorun/templating";
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
 export function createResolveCtx(allManifests, defs, aliases) {
     return {
         allManifests,
@@ -17,6 +22,8 @@ function unionInto(target, src) {
     }
     if (src.unbounded)
         target.unbounded = true;
+    if (src.canThrowPlain)
+        target.canThrowPlain = true;
 }
 function definitionFor(kind, defs, aliases) {
     const resolved = aliases.resolveKind(kind);
@@ -115,7 +122,11 @@ function collectStepArrayThrows(steps, invokeField, enclosingTryCodes, ctx) {
  *  composers that reuse those shape conventions work without changes here. */
 function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
     if (step[invokeField]) {
-        return resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx);
+        // Any invoked resource can throw a non-InvokeError at runtime, which an
+        // enclosing catch surfaces as PLAIN_ERROR_CODE — record that possibility.
+        const u = cloneUnion(resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx));
+        u.canThrowPlain = true;
+        return u;
     }
     if (step.throw && typeof step.throw === "object") {
         return resolveThrowStepCode(step.throw, enclosingTryCodes);
@@ -128,6 +139,11 @@ function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
             // out instead. Sequence-specific subtraction — the plan explicitly
             // anchors this to Run.Sequence's try/catch schema shape.
             const tryCodes = new Set(tryUnion.codes.keys());
+            // A plain (non-InvokeError) failure in the try block reaches the catch as
+            // `error.code === PLAIN_ERROR_CODE`, so a `throw: { code: error.code }`
+            // rethrow can propagate it — seed the set the catch resolves against.
+            if (tryUnion.canThrowPlain)
+                tryCodes.add(PLAIN_ERROR_CODE);
             propagated = collectStepArrayThrows(step.catch, invokeField, tryCodes, ctx);
             // Unbounded in the try block still signals the caller to expect
             // arbitrary codes to flow through the catch (e.g. via passthrough).
@@ -179,6 +195,8 @@ function cloneUnion(u) {
     for (const [c, m] of u.codes)
         out.codes.set(c, m);
     out.unbounded = u.unbounded;
+    if (u.canThrowPlain)
+        out.canThrowPlain = true;
     return out;
 }
 function resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx) {
@@ -226,14 +244,24 @@ function resolveThrowStepCode(throwSpec, enclosingTryCodes) {
     return resolveCodeExpression(throwSpec.code, enclosingTryCodes);
 }
 function resolveCodeExpression(codeInput, enclosingTryCodes) {
-    if (typeof codeInput !== "string" || codeInput.length === 0) {
-        return { codes: new Map(), unbounded: true };
+    // A `!cel`-tagged sentinel and a `${{ … }}` string must resolve identically —
+    // normalize both to the inner CEL expression (or a bare literal code).
+    let expr;
+    if (isTaggedSentinel(codeInput)) {
+        if (codeInput.engine !== "cel")
+            return { codes: new Map(), unbounded: true };
+        expr = codeInput.source.trim();
     }
-    const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
-    if (!match) {
-        return { codes: new Map([[codeInput, {}]]), unbounded: false };
+    else if (typeof codeInput === "string" && codeInput.length > 0) {
+        const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
+        if (!match) {
+            return { codes: new Map([[codeInput, {}]]), unbounded: false };
+        }
+        expr = match[1].trim();
+    }
+    else {
+        return { codes: new Map(), unbounded: true };
     }
-    const expr = match[1].trim();
     const litMatch = expr.match(/^'([^']+)'$|^"([^"]+)"$/);
     if (litMatch) {
         const code = litMatch[1] ?? litMatch[2];

package/dist/schema-compat.d.ts

@@ -35,6 +35,16 @@ export declare function navigateJsonPointer(schema: unknown, pointer: string): u
  *  Stops and returns the current node when a union type (`anyOf`/`oneOf`) is reached.
  *  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.
+ * 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"`).
+ */
+export declare const VALUE_BRAND_BASE: Record<string, string>;
+/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+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;
 /** Check whether a CEL return type is compatible with a JSON Schema type constraint. */

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;;;;;;;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,CAmB/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;AAID,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;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUlF;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,GAC/B,OAAO,CAqCT"}
+{"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,CAmB/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;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AAID,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;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUlF;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,GAC/B,OAAO,CAqCT"}

package/dist/schema-compat.js

@@ -172,10 +172,29 @@ export function navigateSchemaToExprPath(schema, path) {
     }
     return current;
 }
+/**
+ * Recognized `x-telo-type` value brands and the CEL primitive each 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"`).
+ */
+export const VALUE_BRAND_BASE = {
+    TcpPort: "int",
+    UdpPort: "int",
+};
+/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+export function brandOfSchema(schema) {
+    const brand = schema?.["x-telo-type"];
+    return typeof brand === "string" && brand in VALUE_BRAND_BASE ? brand : 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;
     if (schema.anyOf || schema.oneOf || schema.allOf)
         return "dyn";
     if (Array.isArray(schema.type))
@@ -206,6 +225,19 @@ export function jsonSchemaToCelType(schema) {
 export function celTypeSatisfiesJsonSchema(celType, schema) {
     if (celType === "dyn")
         return true;
+    // Nominal value brands: when the expression's type is a recognized brand,
+    // a branded consuming field must match exactly (a UdpPort wired into a
+    // TcpPort-branded field is the error we want). An unbranded field accepts
+    // the brand as its base type — gradual typing, so a TcpPort flows freely
+    // into a plain integer field. (A plain integer into a branded field is also
+    // allowed: only a *conflicting* brand is rejected.)
+    const sourceBase = VALUE_BRAND_BASE[celType];
+    if (sourceBase) {
+        const fieldBrand = brandOfSchema(schema);
+        if (fieldBrand)
+            return fieldBrand === celType;
+        celType = sourceBase;
+    }
     if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf)
         return true;
     if (schema.anyOf || schema.oneOf || schema.allOf)

package/dist/validate-cel-context.d.ts

@@ -83,4 +83,18 @@ export declare function resolveContextAnnotations(schema: Record<string, any>, m
  * e.g. exprPath="routes[0].inputs.q", scope="$.routes[*].inputs" → manifest.routes[0]
  */
 export declare function getManifestItem(exprPath: string, scope: string, manifest: Record<string, any>): Record<string, any>;
+/**
+ * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
+ * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
+ * the same format the analyzer uses for CEL context validation.
+ *
+ * Result is sorted by scope specificity (longer scope first) so that the
+ * per-expression resolver's first-match-wins logic picks the most-specific
+ * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
+ * could shadow a narrower descendant scope whose activation differs.
+ */
+export declare function extractContextsFromSchema(schema: Record<string, any>, path?: string): Array<{
+    scope: string;
+    schema: Record<string, any>;
+}>;
 //# sourceMappingURL=validate-cel-context.d.ts.map

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD"}

package/dist/validate-cel-context.js

@@ -219,3 +219,41 @@ function navigatePath(obj, segments) {
     }
     return cur;
 }
+/**
+ * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
+ * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
+ * the same format the analyzer uses for CEL context validation.
+ *
+ * Result is sorted by scope specificity (longer scope first) so that the
+ * per-expression resolver's first-match-wins logic picks the most-specific
+ * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
+ * could shadow a narrower descendant scope whose activation differs.
+ */
+export function extractContextsFromSchema(schema, path = "$") {
+    const all = collectContexts(schema, path);
+    return all.sort((a, b) => b.scope.length - a.scope.length);
+}
+function collectContexts(schema, path) {
+    if (!schema || typeof schema !== "object")
+        return [];
+    const results = [];
+    if (schema["x-telo-context"]) {
+        results.push({ scope: path, schema: schema["x-telo-context"] });
+    }
+    if (schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+            results.push(...collectContexts(value, `${path}.${key}`));
+        }
+    }
+    if (schema.items && typeof schema.items === "object") {
+        results.push(...collectContexts(schema.items, `${path}[*]`));
+    }
+    for (const key of ["oneOf", "anyOf", "allOf"]) {
+        if (Array.isArray(schema[key])) {
+            for (const subschema of schema[key]) {
+                results.push(...collectContexts(subschema, path));
+            }
+        }
+    }
+    return results;
+}

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;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,CAsbtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA6C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA2etB"}