@telorun/analyzer 0.64.0 → 0.66.0

package/src/definition-registry.ts

@@ -8,10 +8,19 @@ import {
   isSchemaFromEntry,
   type ReferenceFieldMap,
 } from "./reference-field-map.js";
-import { createAjv, formatSingleError, navigateJsonPointer } from "./schema-compat.js";
+import { createAjv, navigateJsonPointer } from "./schema-compat.js";
+import {
+  formatSingleError,
+  reduceSchemaErrors,
+  schemaIssues,
+  type SchemaIssue,
+} from "./schema-error-report.js";
 import { effectiveAuthorSchema } from "./extends-resolution.js";
 
 /** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
+/** What `ajv.compile` hands back: a predicate carrying its own `errors`. */
+type CompiledValidator = ((data: unknown) => boolean) & { errors?: any[] | null };
+
 export class DefinitionRegistry {
   constructor() {
     for (const def of KERNEL_BUILTINS) this.register(def);
@@ -22,6 +31,7 @@ export class DefinitionRegistry {
    *  across analyze() calls and no unbounded growth across the process lifetime. */
   private readonly ajv = createAjv();
   private readonly registeredSchemaIds = new Set<string>();
+  private readonly compiledValidators = new WeakMap<Record<string, any>, CompiledValidator>();
   /** The subset of `registeredSchemaIds` claimed by a kind's schema. Kinds and
    *  named `Telo.Type`s share one `telo://<module>/<Name>` id space, so this is
    *  what lets a colliding type name be reported instead of silently dropped. */
@@ -31,6 +41,9 @@ export class DefinitionRegistry {
   private readonly fieldMaps = new Map<string, ReferenceFieldMap>();
   /** Reverse inheritance index: parent kind → direct child kinds. */
   private readonly extendedBy = new Map<string, string[]>();
+  /** Memoized inheritance-resolved schemas. `null` records "resolved to
+   *  nothing", so a kind with no schema is not re-walked on every resource. */
+  private readonly effectiveSchemas = new Map<string, Record<string, unknown> | null>();
   /** DEPRECATED module identity table: identity string → canonical module name
    *  ("std/pipeline" → "pipeline"). Serves only the legacy
    *  `<namespace>/<module>#<Kind>` form of `x-telo-ref`, kept resolvable for
@@ -47,6 +60,7 @@ export class DefinitionRegistry {
     // so any already-computed map recomputes against the now-larger def set; the
     // maps rebuild lazily on first `getFieldMap` (after all defs are registered).
     this.fieldMaps.clear();
+    this.effectiveSchemas.clear();
     // `capability` populates extendedBy for backward-compat with the legacy pattern where
     // a concrete definition overloaded `capability: <AbstractKind>` to mean "implements
     // this abstract." The canonical pattern is `extends` (below). Both populate the index,
@@ -162,20 +176,47 @@ export class DefinitionRegistry {
     return schema && typeof schema === "object" ? (schema as Record<string, any>) : undefined;
   }
 
-  /** Validates data against a schema using this registry's AJV instance, which has all
-   *  registered definition schemas loaded — enabling cross-module $ref resolution.
-   *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
-   *  owning definition) by `schemaCompileError` via the analyzer's
-   *  definition-schema compile check, so resources are never silently skipped. */
+  /**
+   * Validates a resource's configuration against its kind's schema, with the
+   * offending field's path — what a `SCHEMA_VIOLATION` diagnostic is built from.
+   *
+   * On THIS registry's AJV, which is the point: it holds every registered
+   * definition schema and every named `Telo.Type`, so a kind whose schema
+   * references a shape declared elsewhere is checked rather than skipped. The
+   * module-level instance this used to run on had none of them registered, so
+   * such a schema failed to compile and the failure was swallowed — a resource
+   * could be arbitrarily wrong and `telo check` reported nothing, while the
+   * kernel (whose validator does resolve the reference) rejected it at boot.
+   * Two AJVs answering one question is what made that possible; there is now
+   * one, and it is the same one `schemaCompileError` reports through.
+   */
   validateWithRefs(data: unknown, schema: Record<string, any>): string[] {
-    let validate: ReturnType<typeof this.ajv.compile>;
+    const validate = this.compiledFor(schema);
+    if (!validate || validate(data)) return [];
+    return reduceSchemaErrors(validate.errors).map(formatSingleError);
+  }
+
+  /** {@link validateWithRefs}, with the path each issue is anchored at. */
+  validateResourceConfig(data: unknown, schema: Record<string, any>): SchemaIssue[] {
+    const validate = this.compiledFor(schema);
+    if (!validate || validate(data)) return [];
+    return schemaIssues(validate.errors);
+  }
+
+  /** Memoized per schema OBJECT — the analyzer validates every resource of a
+   *  kind against the same one, and this runs at keystroke time in an editor.
+   *  A schema AJV refuses compiles to `undefined`; that is reported once,
+   *  anchored on the owning definition, by `schemaCompileError`. */
+  private compiledFor(schema: Record<string, any>): CompiledValidator | undefined {
+    const cached = this.compiledValidators.get(schema);
+    if (cached) return cached;
     try {
-      validate = this.ajv.compile(schema);
+      const validate = this.ajv.compile(schema);
+      this.compiledValidators.set(schema, validate);
+      return validate;
     } catch {
-      return [];
+      return undefined;
     }
-    if (validate(data)) return [];
-    return (validate.errors ?? []).map(formatSingleError);
   }
 
   /** Returns the AJV compile error for `schema`, or `undefined` when it compiles.
@@ -248,6 +289,44 @@ export class DefinitionRegistry {
     return this.defs.get(kind);
   }
 
+  /**
+   * The kind's AUTHOR-FACING schema — its own merged with everything it
+   * inherits along `extends` — memoized per kind.
+   *
+   * This is what every consumer reading a kind's schema to interpret an
+   * INSTANCE must use, because that is the schema the instance was authored
+   * against and the one the kernel stamps at definition registration. Reading
+   * `resolve(kind).schema` instead sees only what the leaf declared, so an
+   * annotation on a parent — a CEL context region, a step body, an error
+   * context — is invisible on every child, silently and per consumer. Sharing
+   * one memo is what keeps those consumers from drifting apart.
+   *
+   * Lazy for the same reason `getFieldMap` is: a child registered before its
+   * parent still sees the inherited half once both are present.
+   */
+  effectiveSchema(kind: string): Record<string, unknown> | undefined {
+    const cached = this.effectiveSchemas.get(kind);
+    if (cached !== undefined) return cached ?? undefined;
+    const def = this.defs.get(kind);
+    if (!def) return undefined;
+    const schema = effectiveAuthorSchema(def, (k) => this.resolve(k)) as
+      | Record<string, unknown>
+      | undefined;
+    this.effectiveSchemas.set(kind, schema ?? null);
+    return schema;
+  }
+
+  /** The effective schema for a definition, by the kind it is registered under.
+   *  Falls back to the definition's own schema when it is not in this registry
+   *  (a synthesized or not-yet-registered kind), which is the pre-inheritance
+   *  behaviour and the safe direction: it types less, never wrongly. */
+  effectiveSchemaOf(definition: ResourceDefinition | undefined): Record<string, unknown> | undefined {
+    if (!definition) return undefined;
+    const { name, module: mod } = definition.metadata;
+    const resolved = this.effectiveSchema(mod ? `${mod}.${name}` : name);
+    return resolved ?? (definition.schema as Record<string, unknown> | undefined);
+  }
+
   /** Returns the reference field map for the given kind, computed lazily from the
    *  kind's AUTHOR-FACING (inheritance-resolved) schema and memoized. Lazy so a
    *  child registered before its parent still sees the parent's inherited ref

package/src/eval-paths.ts

@@ -1,3 +1,27 @@
+/**
+ * WHERE IS CEL EVALUATED — the one reader, and the one decision built on it.
+ *
+ * Two independent ways a value is evaluated, and every consumer needs both:
+ * `x-telo-eval` names a field directly, while a REGION annotation
+ * (`x-telo-context` / `x-telo-step-context` / `x-telo-error-context`, or a step
+ * body) covers everything beneath it — which is how `Run.Choice`'s rows and an
+ * `Http.Api` route's `returns:` entries hold expressions while declaring no
+ * annotation of their own.
+ *
+ * The consumers are on both sides of the runtime: `telo check` decides whether a
+ * `!cel` here is live (`CEL_IN_NON_EVAL_FIELD`) or resolved at startup
+ * (`OBSERVED_STATE_IN_STARTUP_FIELD`), the kernel decides what to expand, and
+ * the editor decides whether to offer an expression at all. The editor's answer
+ * is a CLAIM that `telo check` will accept what it writes, so a second
+ * implementation there is a promise nothing keeps — it read `x-telo-eval` alone
+ * and left every predicate inside a region as a bare checkbox, with no way to
+ * write the expression the field exists to hold.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+
+import { isStepSlot } from "./step-slot.js";
+
 /**
  * The single containment rule for `x-telo-eval` paths, shared by every matcher so
  * the analyzer's coverage decision and the kernel's expansion/exclusion can't
@@ -66,3 +90,131 @@ function collectEvalPathsNode(
     }
   }
 }
+
+/** Schema keys that declare a CEL-bearing region: a field carrying any of these
+ *  is evaluated at runtime, so a `!cel` inside it (or a descendant) is live. A
+ *  STEP BODY is one too, and says so through the grammar its items point at
+ *  rather than through a key — {@link isStepSlot} reads either spelling. */
+const CEL_REGION_KEYS = [
+  "x-telo-context",
+  "x-telo-step-context",
+  "x-telo-error-context",
+] as const;
+
+/** True when this schema node declares a CEL-bearing region. Node-level, so a
+ *  consumer holding one schema (an editor rendering one field) asks it directly
+ *  rather than deriving scopes it would then have to match against. */
+export function declaresCelRegion(schema: unknown): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  const node = schema as Record<string, unknown>;
+  return CEL_REGION_KEYS.some((key) => node[key] !== undefined) || isStepSlot(node);
+}
+
+/**
+ * Walk a JSON Schema tree and collect the JSONPath scopes of every field that
+ * declares a CEL-bearing region (`x-telo-context` / `x-telo-step-context` /
+ * `x-telo-error-context`). Used — alongside `x-telo-eval` paths — to decide
+ * whether a `!cel` expression sits in a slot the runtime actually evaluates.
+ * Scopes use the same `$.a.b[*]` form as `extractContextsFromSchema`, matched
+ * against expression paths with `pathMatchesScope`.
+ */
+export function extractCelRegionScopes(schema: Record<string, any>, path = "$"): string[] {
+  if (!schema || typeof schema !== "object") return [];
+  const out: string[] = [];
+
+  if (declaresCelRegion(schema)) out.push(path);
+
+  if (schema.properties) {
+    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
+      out.push(...extractCelRegionScopes(value, `${path}.${key}`));
+    }
+  }
+  if (schema.items && typeof schema.items === "object") {
+    out.push(...extractCelRegionScopes(schema.items, `${path}[*]`));
+  }
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(schema[key])) {
+      for (const subschema of schema[key]) out.push(...extractCelRegionScopes(subschema, path));
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
+ * falls within the scope of a context (e.g. "$.routes[*].inputs").
+ *
+ * The scope is matched directly (no sibling sharing): a context at "$.routes[*].inputs" only
+ * applies to expressions whose path starts with "routes[N].inputs", not to other sibling fields.
+ */
+export function pathMatchesScope(exprPath: string, scope: string): boolean {
+  const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+  if (!stripped) return false;
+
+  // Split on wildcard array segments; each [*] must match a concrete [N] in exprPath
+  const parts = stripped.split("[*]");
+  let remaining = exprPath;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    if (!remaining.startsWith(part)) return false;
+    remaining = remaining.slice(part.length);
+    if (i < parts.length - 1) {
+      // Expect a concrete array index like [0], [12], ...
+      const m = remaining.match(/^\[\d+\]/);
+      if (!m) return false;
+      remaining = remaining.slice(m[0].length);
+    }
+  }
+  // Expression must end here or continue into a child path
+  return remaining === "" || remaining[0] === "." || remaining[0] === "[";
+}
+
+/** Every place a schema says its values are evaluated: the `x-telo-eval` paths,
+ *  by mode, plus the scopes of the regions that cover their contents. */
+export interface CelEvalSites {
+  compile: readonly string[];
+  runtime: readonly string[];
+  regions: readonly string[];
+}
+
+export const NO_CEL_EVAL_SITES: CelEvalSites = { compile: [], runtime: [], regions: [] };
+
+export function celEvalSites(schema: Record<string, any> | undefined): CelEvalSites {
+  if (!schema) return NO_CEL_EVAL_SITES;
+  const { compile, runtime } = buildEvalPaths(schema);
+  return { compile, runtime, regions: extractCelRegionScopes(schema) };
+}
+
+/** The union of several schemas' sites — a kind's own and its capability
+ *  abstract's, which is how a `Telo.Provider`'s implicit compile-eval reaches
+ *  fields the provider never annotated. */
+export function mergeCelEvalSites(...sites: CelEvalSites[]): CelEvalSites {
+  return {
+    compile: sites.flatMap((s) => s.compile),
+    runtime: sites.flatMap((s) => s.runtime),
+    regions: sites.flatMap((s) => s.regions),
+  };
+}
+
+/**
+ * Whether the value at `path` is evaluated, and when — null for a field whose
+ * value is read as a literal.
+ *
+ * `compile` wins over `runtime`, and both win over a region: a field's own
+ * annotation is more specific than the region it sits in, which is the same
+ * precedence a nested annotation has over an enclosing one. A region resolves to
+ * `runtime` because that is what a region IS — a per-invocation scope naming
+ * what its expressions can read.
+ *
+ * `path` is the `walkCelExpressions` spelling (`routes[0].returns[1].when`).
+ */
+export function celEvalModeAt(
+  sites: CelEvalSites,
+  path: string,
+): "compile" | "runtime" | null {
+  if (evalPathsCover(sites.compile, path)) return "compile";
+  if (evalPathsCover(sites.runtime, path)) return "runtime";
+  if (sites.regions.some((scope) => pathMatchesScope(path, scope))) return "runtime";
+  return null;
+}

package/src/flatten-for-analyzer.ts

@@ -23,7 +23,7 @@ export function parseExportEntry(entry: string): ParsedExportEntry {
 }
 
 /** The import-boundary forwarding rule, shared by `flattenForAnalyzer` (the
- *  CLI / kernel loader path) and the telo-editor's workspace projection so the
+ *  CLI / kernel loader path) and telo studio's workspace projection so the
  *  two cannot drift. Given one module's stamped manifests and whether that
  *  module is the analysis entry (root), returns the manifests that cross into
  *  the consumer's flat analysis list:

package/src/import-resolution-diagnostics.ts

@@ -46,7 +46,7 @@ function messageFor(e: GraphLoadError, code: ReturnType<typeof classify>): strin
 /**
  * Convert a graph's import failures (`graph.errors`) into structured, coded
  * diagnostics. This is the single source of truth for surfacing a broken
- * import — every host (CLI, VS Code, telo-editor) routes these instead of each
+ * import — every host (CLI, VS Code, telo studio) routes these instead of each
  * re-deriving the channel and drifting (the VS Code extension used to drop it
  * entirely, showing nothing for a broken import).
  *

package/src/index.ts

@@ -24,7 +24,16 @@ export {
     type ParsedExportEntry,
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
-export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export {
+  buildEvalPaths,
+  celEvalModeAt,
+  celEvalSites,
+  declaresCelRegion,
+  evalPathCovers,
+  mergeCelEvalSites,
+  NO_CEL_EVAL_SITES,
+} from "./eval-paths.js";
+export type { CelEvalSites } from "./eval-paths.js";
 export {
   BINDINGS_ANNOTATION,
   bindingContextProperties,
@@ -96,8 +105,17 @@ export type {
   ResourceGraphNode,
   StepGraphNode,
 } from "./call-graph.js";
-export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-field-map.js";
-export type { ReferenceFieldMap, RefFieldEntry } from "./reference-field-map.js";
+export {
+  buildReferenceFieldMap,
+  isRefEntry,
+  isScopeEntry,
+  satisfiesValueBranch,
+} from "./reference-field-map.js";
+export type {
+  ReferenceFieldMap,
+  RefFieldEntry,
+  ValueBranchValidator,
+} from "./reference-field-map.js";
 export {
   hasDeclaredUse,
   isRefSlot,
@@ -181,6 +199,8 @@ export {
   readRawResourceRules,
   resolveRuleSubjects,
   findDynamicLeaf,
+  dynamicNode,
+  type DynamicLeaf,
   type ResourceRule,
   type ResourceRuleSeverity,
   type RuleSubject,
@@ -211,11 +231,32 @@ export {
   type ReferrerRuleIssue,
   type ReferrerRuleFinding,
   type ReferrerRuleDiagnostic,
+  type ReferrerRuleContext,
+  type ReferrerRuleDeclarationContext,
 } from "./validate-referrer-rules.js";
-export { RULE_BUDGET_MS } from "./rule-condition.js";
+export {
+  PeerBinder,
+  analyzerPeerBinder,
+  analyzerPeersTarget,
+  entryBoundary,
+  navigatePath,
+  referenceValueOf,
+  shapeMatches,
+  type DeclarationLookup,
+  type PeerAliasScope,
+  type PeerBinderEnv,
+  type PeerBinderRegistry,
+  type PeerBinding,
+  type PeerBindingFailure,
+  type PeerBindingResult,
+  type PeersTarget,
+} from "./peer-binding.js";
+export { RULE_BUDGET_MS, UNTAGGED_CONDITION } from "./rule-condition.js";
 export {
   readSchemaProjection,
+  type ProjectionReference,
   readSchemaMap,
+  schemaMapBranch,
   readProjectionFrom,
   readProjectionRef,
   manifestListScope,
@@ -247,8 +288,16 @@ export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validat
 export type { RefSlotIssue } from "./validate-ref-slots.js";
 export { validateValueTypeSlots } from "./validate-value-type-slots.js";
 export type { ValueTypeSlotIssue } from "./validate-value-type-slots.js";
-export { checkSchemaCompatibility, selectUnionBranch } from "./schema-compat.js";
-export type { CompatibilityResult } from "./schema-compat.js";
+export { checkSchemaCompatibility, resolveRefIn, selectUnionBranch } from "./schema-compat.js";
+export type { CompatibilityResult, ExternalSchemaResolver } from "./schema-compat.js";
+export {
+  ajvErrorToPath,
+  formatAjvErrors,
+  formatSingleError,
+  reduceSchemaErrors,
+  schemaIssues,
+} from "./schema-error-report.js";
+export type { AjvErrorLike, SchemaIssue } from "./schema-error-report.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {
     CelSiteEvent,

package/src/manifest-visitor.ts

@@ -359,7 +359,14 @@ export function visitManifest(
     }
 
     if (wantsCel) {
-      const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
+      // The INHERITANCE-RESOLVED schema: an `extends` child is authored against
+      // merge(parent, own), so a context region the parent declares is in force
+      // on the child. Reading the child's own schema typed the region on
+      // whichever kind happened to declare it and left every descendant's
+      // expressions unchecked — silently, which for a typing rule means the
+      // check simply stops existing.
+      const authorSchema = registry.effectiveSchemaOf(definition);
+      const contexts = authorSchema ? extractContextsFromSchema(authorSchema) : [];
       walkCelExpressions(r, "", (expr, path, engineName, surface) => {
         let contextSchema: Record<string, any> | undefined;
         let matchedScope: string | undefined;

package/src/migrations/entries/index.ts

@@ -2,9 +2,11 @@
 // Source: analyzer/migrations/*.json (lexically ordered).
 import e0 from "./normalize-value-types.json" with { type: "json" };
 import e1 from "./ref-slot-scalar-type.json" with { type: "json" };
+import e2 from "./schema-prepare-bucket.json" with { type: "json" };
 
 /** Every entry file, in the order the driver applies them. */
 export const MIGRATION_ENTRY_FILES: ReadonlyArray<readonly [file: string, data: unknown]> = [
   ["normalize-value-types.json", e0],
   ["ref-slot-scalar-type.json", e1],
+  ["schema-prepare-bucket.json", e2],
 ];

package/src/migrations/entries/schema-prepare-bucket.json

@@ -0,0 +1,27 @@
+{
+  "$comment": "`inKind` names the two backend schema kinds by their canonical `<module>.<Kind>` spelling, which is what a document's `kind:` carries after alias resolution. `under` is the key itself: the bucket is a top-level field of the resource, so the region and the match are the same node \u2014 the tightest containment this vocabulary can state. NAMING A MODULE'S KIND FROM A CORE ENTRY IS A DEBT, not a pattern: it is the one place the analyzer knows a standard-library kind by name. It is contained because `inKind` is a filter \u2014 an entry naming an absent kind matches nothing \u2014 and it MOVES into `modules/postgres` and `modules/sqlite` when the module-migration surface lands. Do not add another; see analyzer/migrations/README.md.",
+  "id": "schema-prepare-bucket",
+  "code": "SQL_BEFORE_MIGRATIONS_RENAMED",
+  "severity": "warning",
+  "reason": "`beforeMigrations:` is now `prepare:`. Every documented use of it was data preparation for a narrowing the reconciliation pass is about to attempt \u2014 backfill before NOT NULL, make values fit before a length reduction, convert before a non-widening type change \u2014 and each is what a refusal already tells the author to write. The old name said where it ran relative to the OTHER bucket; the new one says what it is for, which is what those refusals need to name. Nothing re-runs: the ledger stores the migration key alone, so moving an entry between the two maps changes no history.",
+  "rules": [
+    {
+      "match": {
+        "key": "beforeMigrations",
+        "inKind": [
+          "Postgres.Schema",
+          "SQLite.Schema"
+        ],
+        "under": [
+          "beforeMigrations"
+        ]
+      },
+      "patch": [
+        {
+          "op": "rename-key",
+          "to": "prepare"
+        }
+      ]
+    }
+  ]
+}