@telorun/analyzer 0.72.0 → 0.74.0

package/src/resolve-ref-sentinels.ts

@@ -7,6 +7,7 @@ import {
   type ReferenceFieldMap,
 } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { isForwardedDeclaration, isForwardedExport } from "./forwarded-declaration.js";
 
 /** The slice of the definition registry this pass needs: a kind's field map, from
  *  which the `x-telo-scope` slots are read. */
@@ -73,10 +74,10 @@ export function resolveRefSentinels(
 ): void {
   const moduleOf = (r: ResourceManifest): string | undefined =>
     (r.metadata as { module?: string } | undefined)?.module;
-  // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
-  // cross-module resolution targets only — never walked as local ref sources here.
-  const isForeign = (r: ResourceManifest): boolean =>
-    (r.metadata as { forwardedExport?: boolean } | undefined)?.forwardedExport === true;
+  // A dependency's code — a forwarded export, or what extraction pulled out of one — is
+  // never walked as a local ref source here and never a local name; only an EXPORT is a
+  // cross-module resolution target.
+  const isForeign = isForwardedDeclaration;
 
   // Local resources resolve a bare / `Self.`-qualified name; forwarded foreign exports
   // resolve an `Alias.`-qualified name keyed by (module, name).
@@ -86,13 +87,13 @@ export function resolveRefSentinels(
     if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind)) continue;
     const name = r.metadata.name as string;
     if (isForeign(r)) {
-      byModuleName.set(`${moduleOf(r)}\0${name}`, r);
+      if (isForwardedExport(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;
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForwardedExport(r)) continue;
     byModuleName.set(`${moduleOf(r)}\0${r.metadata.name as string}`, r);
   }
 

package/src/resolve-throws-union.ts

@@ -1,12 +1,18 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { isTaggedSentinel } from "@telorun/templating";
 import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js";
-import { resolveScopedName } from "./call-graph.js";
+import { resolveScopedName, resolveSlotUseAt } from "./call-graph.js";
 import { refSentinelTarget, type RefSentinelTarget } from "./ref-sentinel-target.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
-import { possibleUses, readRefSlot, transfersControl, type RefSlot } from "./ref-slot.js";
-import { readStepSlot } from "./step-slot.js";
+import {
+  hasDeclaredUse,
+  possibleUses,
+  transfersControl,
+  type RefSlot,
+  type RefUse,
+} from "./ref-slot.js";
 import { forEachDrivenSlot } from "./schema-walk.js";
+import type { StepSlot } from "./step-slot.js";
 
 export interface ThrowsCodeMeta {
   data?: Record<string, any>;
@@ -207,10 +213,10 @@ function codesFromDefinition(definition: ResourceDefinition): Map<string, Throws
 }
 
 /** Resolve the effective throw union for a named manifest. The result combines
- *  explicit `throws.codes`, `throws.inherit: true` dataflow (step-context
- *  traversal with try/catch subtraction), and unbounded markers for
- *  unresolvable passthrough call sites. Cycles short-circuit to an empty
- *  result so resolution always terminates. */
+ *  explicit `throws.codes`, `throws.inherit: true` dataflow (step bodies with
+ *  try/catch subtraction, plus reference slots that hand a failure back), and
+ *  unbounded markers for unresolvable passthrough call sites. Cycles
+ *  short-circuit to an empty result so resolution always terminates. */
 export function resolveThrowsUnion(
   manifest: ResourceManifest,
   ctx: ResolveCtx,
@@ -266,14 +272,42 @@ export function resolveThrowsUnion(
 }
 
 /**
- * `throws.inherit: true` — the union a composer's own STEP BODIES reach.
+ * True for a use through which a target's failure reaches the declaring
+ * resource's CALLER: `call` returns into my invocation, and `trigger.consumer`
+ * rejects the value my caller drains. `detached` and `trigger.inbound` run where
+ * no caller of mine awaits them; `dependency` and `schema` dispatch nothing.
  *
- * Deliberately steps only, and not every slot the resource drives: `inherit` is
- * a DECLARATION that a kind's union is the union of what it dispatches, and a
- * kind that does not make that claim must not have it inferred — a kind holding
- * a `call` ref it catches internally would silently gain codes it never lets
- * escape. What a CATCH SCOPE needs is a different question with a different
- * answer, and it has its own resolver below.
+ * The reduction `inherit` is read through — by the resolver and by the check
+ * that a definition declaring it has something to inherit from.
+ */
+export function handsFailureBack(use: RefUse): boolean {
+  return use === "call" || use === "trigger.consumer";
+}
+
+/**
+ * The uses a throws consumer reads off a slot. A slot that declares no use —
+ * the legacy bare-string form — reads as `call`: the throws union must assume
+ * `call` to keep an error path, the direction the call graph takes for the same
+ * slot. The zone projection reads it the opposite way, deliberately.
+ *
+ * `uses` defaults to every use the slot can take; a consumer that resolved the
+ * slot's case map for one instance passes that answer instead.
+ */
+export function throwsUses(
+  slot: RefSlot,
+  uses: readonly RefUse[] = possibleUses(slot),
+): readonly RefUse[] {
+  return hasDeclaredUse(slot) ? uses : ["call"];
+}
+
+/**
+ * `throws.inherit: true` — the union of what the resource dispatches: its step
+ * bodies (try/catch subtraction included) and every reference slot whose use,
+ * resolved for THIS instance, hands a failure back ({@link handsFailureBack}).
+ *
+ * Only on a kind that DECLARES `inherit`: it is a claim that the kind lets what
+ * it dispatches escape, and a kind catching a slot internally does not make it.
+ * What a CATCH SCOPE encloses is a different question, answered below.
  */
 function resolveInherited(
   manifest: ResourceManifest,
@@ -282,16 +316,23 @@ function resolveInherited(
   ownerModule: string | undefined,
 ): ThrowsUnion {
   const result: ThrowsUnion = { codes: new Map(), unbounded: false };
-  const props = definition.schema?.properties as Record<string, any> | undefined;
-  if (!props) return result;
-
-  for (const [fieldName, fieldSchema] of Object.entries(props)) {
-    const stepCtx = readStepSlot(fieldSchema);
-    if (!stepCtx) continue;
-    const steps = (manifest as Record<string, any>)[fieldName];
-    if (!Array.isArray(steps)) continue;
-    unionInto(result, collectStepArrayThrows(steps, stepCtx.invoke, undefined, ctx, ownerModule));
-  }
+  const schema = definition.schema as Record<string, any> | undefined;
+
+  forEachDrivenSlot(schema, manifest, (driven) => {
+    if (driven.kind === "step") {
+      unionInto(result, stepSiteThrows(driven.data, driven.slots, ctx, ownerModule));
+      return;
+    }
+    // Several slots at one site are the branches declaring it; any one that
+    // hands a failure back counts, since a branch not applying can only add codes.
+    const handsBack = driven.slots.some(({ slot, fieldPath }) =>
+      throwsUses(
+        slot,
+        resolveSlotUseAt(slot, manifest, schema, driven.path, fieldPath).use,
+      ).some(handsFailureBack),
+    );
+    if (handsBack) unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
+  });
 
   return result;
 }
@@ -327,13 +368,15 @@ export function resolveScopeUnion(
 
   forEachDrivenSlot(definition.schema, manifest, (driven) => {
     if (driven.kind === "step") {
-      unionInto(
-        result,
-        collectStepArrayThrows(driven.data, driven.slot.invoke, undefined, ctx, ownerModule),
-      );
+      unionInto(result, stepSiteThrows(driven.data, driven.slots, ctx, ownerModule));
       return;
     }
-    if (driven.slot.throwsThrough) {
+    if (
+      driven.slots.some(({ slot }) => !slot.throwsThrough && throwsUses(slot).some(transfersControl))
+    ) {
+      unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
+    }
+    if (driven.slots.some(({ slot }) => slot.throwsThrough)) {
       const target = resolveRefManifest(driven.data, ctx, ownerModule);
       const targetDef = target
         ? definitionFor(
@@ -347,15 +390,27 @@ export function resolveScopeUnion(
       // A target that cannot be resolved says nothing about what it throws, so
       // the scope's union is no longer enumerable.
       else result.unbounded = true;
-      return;
     }
-    if (!possibleUses(driven.slot).some(transfersControl)) return;
-    unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
   });
 
   return result;
 }
 
+/** The union a step-body site reaches — once per distinct invoke field, since
+ *  several branches may declare a body at one site. */
+function stepSiteThrows(
+  steps: unknown[],
+  slots: StepSlot[],
+  ctx: ResolveCtx,
+  ownerModule: string | undefined,
+): ThrowsUnion {
+  const result = emptyUnion();
+  for (const invoke of new Set(slots.map((slot) => slot.invoke))) {
+    unionInto(result, collectStepArrayThrows(steps, invoke, undefined, ctx, ownerModule));
+  }
+  return result;
+}
+
 function collectStepArrayThrows(
   steps: unknown[],
   invokeField: string,

package/src/resolve-zone-requirements.ts

@@ -32,6 +32,7 @@ import type { ModuleDocuments } from "./module-documents.js";
 import { readProvidesZone, readRequiresZone } from "./zone-slot.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 import { moduleAliasScope } from "./module-alias-scope.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 
 const SOURCE = "telo-analyzer";
 
@@ -616,7 +617,7 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
     // (with the internal graph in hand) and seeded below — deriving them here
     // against the flattened view would resolve correlation against a graph
     // that no longer holds the library's internals.
-    if (meta?.forwardedExport) continue;
+    if (isForwardedDeclaration(node.manifest)) continue;
     const def = resolveDef(node.kind, meta?.module);
     const schema = def?.schema as Record<string, any> | undefined;
     if (!def || !schema) continue;

package/src/rewrite-synthetic-origins.ts

@@ -7,9 +7,9 @@ interface XTeloOrigin {
   pathFromParent: string;
 }
 
-function readOrigin(manifest: ResourceManifest | undefined): XTeloOrigin | undefined {
-  if (!manifest) return undefined;
-  const origin = (manifest.metadata as { xTeloOrigin?: XTeloOrigin } | undefined)?.xTeloOrigin;
+function readOrigin(manifest: unknown): XTeloOrigin | undefined {
+  if (!manifest || typeof manifest !== "object") return undefined;
+  const origin = (manifest as { metadata?: { xTeloOrigin?: XTeloOrigin } }).metadata?.xTeloOrigin;
   if (
     !origin ||
     typeof origin.parentKind !== "string" ||
@@ -26,7 +26,12 @@ function readOrigin(manifest: ResourceManifest | undefined): XTeloOrigin | undef
  *  `data.resource`, which has no YAML source. Rewrite each such diagnostic
  *  back to the chain root: walk up `metadata.xTeloOrigin` until a manifest
  *  with no origin is reached, and prepend each hop's `pathFromParent` to
- *  `data.path` so position-index lookups against the root doc resolve. */
+ *  `data.path` so position-index lookups against the root doc resolve.
+ *
+ *  An extraction from a scope member lives INSIDE the scope array rather than at
+ *  the top level, so a diagnostic about it names the top-level owner and a path
+ *  through an array index the author never wrote (`with[3]`). That prefix is
+ *  unfolded the same way, into the position the declaration was written at. */
 export function rewriteSyntheticOrigins(
   diagnostics: AnalysisDiagnostic[],
   manifests: ResourceManifest[],
@@ -45,31 +50,117 @@ export function rewriteSyntheticOrigins(
 
     let current = byName.get(data.resource.name);
     let origin = readOrigin(current);
-    if (!origin) return d;
-
-    let accumPath = typeof data.path === "string" ? data.path : "";
-    let rootKind: string = origin.parentKind;
-    let rootName: string = origin.parentName;
+    const path = typeof data.path === "string" ? data.path : "";
+    let accumPath = path;
+    let root: { kind?: string; name?: string } = data.resource;
 
     while (origin) {
       accumPath = accumPath ? `${origin.pathFromParent}.${accumPath}` : origin.pathFromParent;
-      rootKind = origin.parentKind;
-      rootName = origin.parentName;
+      root = { kind: origin.parentKind, name: origin.parentName };
       current = byName.get(origin.parentName);
       origin = readOrigin(current);
     }
 
-    const rootFilePath =
-      (current?.metadata as { source?: string } | undefined)?.source ?? data.filePath;
+    const rerouted = root !== data.resource;
+    const unfolded = current ? unfoldScopedOrigins(current, accumPath) : accumPath;
+    if (!rerouted && unfolded === path) return d;
 
     return {
       ...d,
       data: {
         ...data,
-        resource: { kind: rootKind, name: rootName },
-        filePath: rootFilePath,
-        path: accumPath,
+        resource: root,
+        filePath: rerouted
+          ? ((current?.metadata as { source?: string } | undefined)?.source ?? data.filePath)
+          : data.filePath,
+        path: unfolded,
       },
     };
   });
 }
+
+type Segment = string | number;
+
+/** Replace every scope-array index that holds an extraction with the position
+ *  the extraction was written at, until none is left. */
+function unfoldScopedOrigins(root: ResourceManifest, path: string): string {
+  let segments = parseSegments(path);
+  let unfoldedAny = false;
+  // Each unfolding replaces one extraction with its parent, which is strictly
+  // closer to what the author wrote, so the chain is as long as the nesting.
+  for (let hops = 0; hops <= segments.length + 16; hops++) {
+    const next = unfoldOnce(root, segments);
+    if (!next) break;
+    segments = next;
+    unfoldedAny = true;
+  }
+  // Re-formatting is lossy (an empty segment in `entries../x` is dropped), so a
+  // path nothing unfolded is returned as written.
+  return unfoldedAny ? formatSegments(segments) : path;
+}
+
+function unfoldOnce(root: ResourceManifest, segments: Segment[]): Segment[] | undefined {
+  let node: unknown = root;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    const container = node;
+    node =
+      typeof segment === "number"
+        ? Array.isArray(container)
+          ? container[segment]
+          : undefined
+        : container && typeof container === "object" && !Array.isArray(container)
+          ? (container as Record<string, unknown>)[segment]
+          : undefined;
+    if (node === undefined || node === null) return undefined;
+    if (typeof segment !== "number" || i === 0) continue;
+    const origin = readOrigin(node);
+    if (!origin) continue;
+
+    // Its parent is either the resource holding this scope array (a slot of
+    // the resource that declares the scope) or a sibling member of the array.
+    const holderPath = segments.slice(0, i - 1);
+    let parentPath: Segment[] | undefined;
+    if (nameOf(at(root, holderPath)) === origin.parentName) {
+      parentPath = holderPath;
+    } else {
+      const sibling = (container as unknown[]).findIndex((m) => nameOf(m) === origin.parentName);
+      if (sibling >= 0) parentPath = [...segments.slice(0, i), sibling];
+    }
+    if (!parentPath) return undefined;
+    return [...parentPath, ...parseSegments(origin.pathFromParent), ...segments.slice(i + 1)];
+  }
+  return undefined;
+}
+
+function at(root: unknown, segments: Segment[]): unknown {
+  let node = root;
+  for (const segment of segments) {
+    if (!node || typeof node !== "object") return undefined;
+    node = (node as Record<string | number, unknown>)[segment];
+  }
+  return node;
+}
+
+function nameOf(value: unknown): string | undefined {
+  const name = (value as { metadata?: { name?: unknown } } | undefined)?.metadata?.name;
+  return typeof name === "string" ? name : undefined;
+}
+
+/** `with[3].steps[0].invoke` → `["with", 3, "steps", 0, "invoke"]`. */
+function parseSegments(path: string): Segment[] {
+  const out: Segment[] = [];
+  for (const match of path.matchAll(/\[(\d+)\]|([^.[\]]+)/g)) {
+    out.push(match[1] !== undefined ? Number(match[1]) : match[2]!);
+  }
+  return out;
+}
+
+function formatSegments(segments: Segment[]): string {
+  let out = "";
+  for (const segment of segments) {
+    if (typeof segment === "number") out += `[${segment}]`;
+    else out += out ? `.${segment}` : segment;
+  }
+  return out;
+}

package/src/schema-compat.ts

@@ -10,6 +10,7 @@ import {
   celTypeOfValueType,
   isCompiledValue,
   readValueTypeSlot,
+  VALUE_TYPE_BINDINGS,
   valueBrandBases,
   valueTypeOf,
   valueTypePlaceholder,
@@ -36,8 +37,9 @@ export function createAjv(): InstanceType<typeof Ajv> {
   // 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);
+  // rejected statically and at dispatch by the identical rule. This instance is
+  // static analysis alone, so it also asserts a `live` type: no literal can be one.
+  registerTeloKeywords(instance, { assertLive: true });
   instance.addSchema(ManifestRootSchema);
   return instance;
 }
@@ -508,6 +510,18 @@ function foldedConstraints(schema: Record<string, any>): Record<string, any> {
   return out;
 }
 
+/** The stand-in for a CEL leaf at a `live` slot. Static analysis asserts a live
+ *  type like any instance type (a literal can never be one), so the leaf's
+ *  stand-in has to BE one. A live binding declares no factory, and building an
+ *  instance would mean knowing its constructor's signature; an object on the
+ *  constructor's prototype satisfies `instanceof` and is never used as one. */
+function liveValuePlaceholder(schema: Record<string, any>): unknown | undefined {
+  const entry = readValueTypeSlot(schema)?.entry;
+  if (!entry?.live || entry.representation !== "instance") return undefined;
+  const binding = VALUE_TYPE_BINDINGS[entry.binding!];
+  return binding ? Object.create(binding.constructor.prototype) : undefined;
+}
+
 export function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown {
   const schema = foldedConstraints(rawSchema);
   // An instance-typed slot's placeholder must BE an instance: the same keyword
@@ -516,8 +530,8 @@ export function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown
   // 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);
+  // declares none, because nothing validates it at dispatch.
+  const placeholder = valueTypePlaceholder(schema) ?? liveValuePlaceholder(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

package/src/schema-error-report.ts

@@ -44,6 +44,13 @@ export interface SchemaIssue {
   message: string;
   /** Dotted path to the field (e.g. "config.handler"). Empty string means root. */
   path: string;
+  /** The AJV keyword that produced it, so a consumer can key on WHAT failed
+   *  rather than on how the sentence reads. Prose is the renderer's to change;
+   *  a caller matching on it breaks silently when it does, and mis-fires on any
+   *  other issue whose text happens to quote the same name. */
+  keyword?: string;
+  /** For `required`, the property that is missing. */
+  missingProperty?: string;
 }
 
 const UNION_KEYWORDS = new Set(["anyOf", "oneOf"]);
@@ -447,10 +454,15 @@ export function ajvErrorToPath(err: AjvErrorLike): string {
 
 /** Reduced, path-anchored issues — what a diagnostic list is built from. */
 export function schemaIssues(errors: AjvErrorLike[] | null | undefined): SchemaIssue[] {
-  return reduceSchemaErrors(errors).map((err) => ({
-    message: formatSingleError(err),
-    path: ajvErrorToPath(err),
-  }));
+  return reduceSchemaErrors(errors).map((err) => {
+    const missing = (err.params ?? {}).missingProperty;
+    return {
+      message: formatSingleError(err),
+      path: ajvErrorToPath(err),
+      ...(err.keyword ? { keyword: err.keyword } : {}),
+      ...(typeof missing === "string" ? { missingProperty: missing } : {}),
+    };
+  });
 }
 
 /** Reduced, rendered as one sentence — what a thrown runtime error carries. */