@telorun/analyzer 0.48.0 → 0.49.1

package/src/extends-resolution.ts

@@ -29,6 +29,10 @@ interface DefinitionBody {
   base?: Record<string, unknown>;
   schema?: Record<string, any>;
   status?: Record<string, any>;
+  inputType?: unknown;
+  outputType?: unknown;
+  inputs?: unknown;
+  result?: unknown;
 }
 
 const body = (def: ResourceDefinition | undefined): DefinitionBody =>
@@ -133,6 +137,88 @@ export function effectiveAuthorSchema(
   return mergeTypeSchemas([parentSchema, own]) as Record<string, any>;
 }
 
+/** The two directions of a kind's invocation contract. `inputType` is what a
+ *  caller sends to `invoke()`; `outputType` is what `invoke()` / `provide()`
+ *  returns. */
+export type ContractDirection = "inputType" | "outputType";
+
+/**
+ * The **nearest declaration** of an invocation contract along the `extends`
+ * chain, self first — the raw type-field value, still to be resolved to a schema
+ * by the caller (which is what keeps this module free of manifest lookup).
+ *
+ * Contracts RESOLVE, they never merge. A definition that declares one fully
+ * replaces its ancestor's; one that declares none inherits its ancestor's
+ * verbatim, at any depth. This is deliberately unlike {@link
+ * effectiveAuthorSchema} and {@link effectiveStatusSchema}: construction config
+ * and observed state are additive, a call signature is not. Folding a child's
+ * required fields into its parent's yields a union no caller can satisfy, and it
+ * would reject the very remapping `base:` + `inputs:` exists for — the point of
+ * a child declaring a signature is that it accepts something *different*.
+ *
+ * Substitutability is not weakened by that, because `extends` never carried the
+ * dispatch contract: it decides which slots accept a resource. Whether a
+ * particular slot may hold a resource whose contract differs from the slot's
+ * declared kind is a wiring question, answered per slot by
+ * `validate-invocation-contract`'s wiring rule.
+ */
+export function effectiveContractField(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+  direction: ContractDirection,
+): unknown {
+  const own = body(def)[direction];
+  if (own !== undefined && own !== null) return own;
+  for (const a of ancestorChain(def, resolve)) {
+    const inherited = body(a)[direction];
+    if (inherited !== undefined && inherited !== null) return inherited;
+  }
+  return undefined;
+}
+
+/** The definition in the `extends` chain (self first) that actually DECLARES the
+ *  contract for `direction` — the one whose scope its `telo#Type` references
+ *  resolve in, and the one a diagnostic should name. Undefined when nothing in
+ *  the chain declares it. */
+export function contractDeclarer(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+  direction: ContractDirection,
+): ResourceDefinition | undefined {
+  if (!def) return undefined;
+  const own = body(def)[direction];
+  if (own !== undefined && own !== null) return def;
+  for (const a of ancestorChain(def, resolve)) {
+    const inherited = body(a)[direction];
+    if (inherited !== undefined && inherited !== null) return a;
+  }
+  return undefined;
+}
+
+/** True when this definition declares its own contract for `direction` while
+ *  inheriting the controller that will execute it — the case that REQUIRES a
+ *  bridging mapping (`inputs:` for inputs, `result:` for outputs), because the
+ *  inherited controller only understands the ancestor's shape. A definition with
+ *  its own controller or template body is exempt: its controller *is* the
+ *  implementation of whatever it declares. */
+export function needsContractMapping(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+  direction: ContractDirection,
+): boolean {
+  const own = body(def)[direction];
+  if (own === undefined || own === null) return false;
+  if (hasOwnControllerOrTemplate(def)) return false;
+  return controllerBearingAncestor(def, resolve) !== undefined;
+}
+
+/** The mapping field that bridges a replaced contract back to the inherited
+ *  controller: `inputs:` maps the child's signature onto the parent's call,
+ *  `result:` maps the parent's result back to the child's declared output. */
+export function mappingFieldFor(direction: ContractDirection): "inputs" | "result" {
+  return direction === "inputType" ? "inputs" : "result";
+}
+
 /** The observed state a kind reports (`status:`), folded through `extends`:
  *  - with `base:` present → the **parent's** effective status unchanged; the
  *    child delegates to the parent's controller and *is* a parent instance, so

package/src/index.ts

@@ -38,15 +38,27 @@ export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolve
 export type { ModuleScopes } from "./alias-resolver.js";
 export {
   ancestorChain,
+  contractDeclarer,
   controllerBearingAncestor,
   effectiveAuthorSchema,
+  effectiveContractField,
   effectiveStatusSchema,
   hasOwnControllerOrTemplate,
   inheritedCapability,
   isInheritedDelegation,
+  mappingFieldFor,
+  needsContractMapping,
   resolveParent,
 } from "./extends-resolution.js";
-export type { DefResolver } from "./extends-resolution.js";
+export type { ContractDirection, DefResolver } from "./extends-resolution.js";
+export {
+  defaultBearingPaths,
+  PERMISSIVE_CONTRACT,
+  resolveContract,
+  resolveContractSchema,
+  withStreamPropertiesSkipped,
+} from "./invocation-contract.js";
+export type { ContractOrigin, ContractScope, ResolvedContract } from "./invocation-contract.js";
 export {
   hasIntermediateWildcard,
   parseRedactionPath,

package/src/invocation-contract.ts

@@ -0,0 +1,275 @@
+import type { ResourceDefinition } from "@telorun/sdk";
+import {
+  type ContractDirection,
+  contractDeclarer,
+  type DefResolver,
+  effectiveContractField,
+} from "./extends-resolution.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+
+export type { ContractDirection };
+
+/**
+ * The one answer to "what is this target's input / output schema".
+ *
+ * Both halves of Telo consume it: `telo check` validates call sites against it,
+ * and the kernel binds it to the instance at creation. It lives here rather than
+ * in the kernel because it must be browser-safe and because a second
+ * implementation would drift — the same split already used for
+ * `buildEvalPaths` / `evalPathCovers` and the redaction path parser. Before this
+ * there were three one-hop lookups (the analysis registry's editor helpers, the
+ * template-body `inputs` typing, the step-context definition fallback) and a
+ * runtime that consulted only an explicitly-passed type ref, so static analysis
+ * and dispatch could disagree about the very contract they were both checking.
+ */
+
+/** Where a resolved contract was declared. Instance-level declarations let one
+ *  call site narrow a kind's contract (`JS.Script` does this); kind-level ones
+ *  are the kind's own signature. */
+export type ContractOrigin = "instance" | "kind";
+
+export interface ResolvedContract {
+  /** The JSON Schema a value is validated against. */
+  schema: Record<string, any>;
+  origin: ContractOrigin;
+  /** The definition that declared it, when `origin` is `"kind"` — the scope its
+   *  named type references resolved in, and what a diagnostic should name. */
+  declaredBy?: ResourceDefinition;
+}
+
+export interface ContractScope {
+  /** Resolves a kind to its definition. Must be scoped to the module that
+   *  DECLARED the definition being walked — `extends` aliases are lexical, so a
+   *  chain crossing module boundaries re-scopes at each hop. */
+  resolveDefinition: DefResolver;
+  /**
+   * Manifests a named `telo#Type` reference resolves against, given the
+   * definition that DECLARED the type field.
+   *
+   * The parameter exists for a caller that keeps types per module. The analyzer
+   * does not: it works from one flattened list where names are already unique
+   * per module, so it ignores the argument and returns that list. A caller
+   * holding several scopes uses it to avoid resolving a bare name against the
+   * wrong module's type of the same name.
+   */
+  typeManifestsFor(def: ResourceDefinition | undefined): Record<string, any>[];
+}
+
+/** The fallback for a target that declares no contract: anything goes. Not
+ *  `additionalProperties: false` — an undeclared contract is an absence of a
+ *  claim, not a claim of emptiness. */
+export const PERMISSIVE_CONTRACT: Record<string, any> = {
+  type: "object",
+  additionalProperties: true,
+};
+
+/**
+ * Resolve a dispatch target's contract, layering:
+ *   1. the **instance manifest's** own `inputType:` / `outputType:` — per-call-site
+ *      narrowing, opted into simply by the kind declaring the property;
+ *   2. the **kind's** contract, resolved to the nearest declaration along
+ *      `extends` (see {@link effectiveContractField} — nearest wins, no merge);
+ *   3. undefined — the caller decides whether that means permissive.
+ *
+ * Returns undefined rather than {@link PERMISSIVE_CONTRACT} so a caller can tell
+ * "declared nothing" from "declared anything", which the wiring rule and the
+ * `run()` guard both need.
+ */
+export function resolveContract(
+  direction: ContractDirection,
+  manifest: Record<string, any> | undefined,
+  definition: ResourceDefinition | undefined,
+  scope: ContractScope,
+): ResolvedContract | undefined {
+  const own = manifest?.[direction];
+  if (own !== undefined && own !== null) {
+    const schema = resolveTypeFieldToSchema(own, scope.typeManifestsFor(definition));
+    if (schema) return { schema, origin: "instance" };
+  }
+
+  const declared = effectiveContractField(definition, scope.resolveDefinition, direction);
+  if (declared === undefined || declared === null) return undefined;
+  const declarer = contractDeclarer(definition, scope.resolveDefinition, direction);
+  const schema = resolveTypeFieldToSchema(declared, scope.typeManifestsFor(declarer));
+  if (!schema) return undefined;
+  return { schema, origin: "kind", declaredBy: declarer };
+}
+
+/** {@link resolveContract}, falling back to {@link PERMISSIVE_CONTRACT}. For
+ *  callers that need a schema unconditionally (CEL context typing), as opposed
+ *  to needing to know whether one was declared. */
+export function resolveContractSchema(
+  direction: ContractDirection,
+  manifest: Record<string, any> | undefined,
+  definition: ResourceDefinition | undefined,
+  scope: ContractScope,
+): Record<string, any> {
+  return resolveContract(direction, manifest, definition, scope)?.schema ?? PERMISSIVE_CONTRACT;
+}
+
+/**
+ * A copy of `schema` with every `x-telo-stream`-marked property removed from
+ * `properties` and `required`, for validating a runtime value against.
+ *
+ * Streams travel in BOTH directions — `Codec.Encoder` marks `input` on its
+ * `inputType` and lists it in `required`, and `Record.Stream`, `Ai`, `Tar` and
+ * `Console` do the same — so a one-directional skip would walk a live `Stream`
+ * with AJV on the hottest path in the runtime. That is the same defect as
+ * `stripCompiledValues` walking a live `ResourceInstance` in a ref slot: a live
+ * object in a declared slot is not data to be traversed. The annotation already
+ * marks exactly the properties to leave alone.
+ *
+ * Structural (returns a new object, never mutates), and shared so the analyzer
+ * and the kernel exempt the same set.
+ */
+export function withStreamPropertiesSkipped(
+  schema: Record<string, any>,
+  /** Resolves a `$ref` to the schema it names. Required to see through the
+   *  reference form the runtime deliberately KEEPS intact for its validator: a
+   *  contract written as `{ $ref: "telo:mod/Type" }` has none of its own
+   *  properties, so a walk that cannot follow the reference exempts nothing and
+   *  the stream is traversed after all. */
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): Record<string, any> {
+  return stripStreams(schema, [], resolveRef);
+}
+
+function stripStreams(
+  node: unknown,
+  // A PATH-scoped guard, not a global memo: a schema object reached twice from
+  // different parents must be stripped twice (a global `seen` would hand the
+  // second parent the unstripped original), while a cycle must still terminate.
+  path: readonly object[],
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): any {
+  if (Array.isArray(node)) {
+    let changed = false;
+    const items = node.map((item) => {
+      const next = stripStreams(item, path, resolveRef);
+      if (next !== item) changed = true;
+      return next;
+    });
+    return changed ? items : node;
+  }
+  if (!node || typeof node !== "object") return node;
+  let schema = node as Record<string, any>;
+  if (path.includes(schema)) return schema;
+
+  // Follow a whole-document reference to SEE the annotations behind it, but
+  // return the original node when nothing behind it was stripped. Substituting
+  // the resolved target unconditionally would break schema identity — the
+  // compiled-validator cache is keyed on it — and would move the target out of
+  // the document whose `$defs` its own internal `$ref`s resolve against.
+  if (resolveRef && typeof schema.$ref === "string") {
+    const target = resolveRef(schema.$ref);
+    if (target && !path.includes(target)) {
+      const stripped = stripStreams(target, [...path, schema], resolveRef);
+      if (stripped === target) return node;
+      const { $ref: _ref, ...siblings } = schema;
+      return Object.keys(siblings).length > 0 ? { ...stripped, ...siblings } : stripped;
+    }
+  }
+  const here = [...path, schema];
+
+  let out: Record<string, any> = schema;
+  const properties = schema.properties as Record<string, any> | undefined;
+  if (properties) {
+    // A stream can be contributed by an `allOf` branch too (how type inheritance
+    // is expressed before the branches are merged), so the marked set is read
+    // from the folded view while the removal is applied here.
+    const streamed = Object.keys(properties).filter(
+      (key) => (properties[key] as Record<string, any> | undefined)?.["x-telo-stream"],
+    );
+    if (streamed.length > 0) {
+      const kept: Record<string, any> = {};
+      for (const [key, value] of Object.entries(properties)) {
+        if (!streamed.includes(key)) kept[key] = value;
+      }
+      // The key stays DECLARED but unconstrained, rather than being deleted.
+      // Deleting it would force `additionalProperties: false` open, and a closed
+      // contract would stop rejecting unknown keys the moment it grew a stream —
+      // trading one exemption for a hole across the whole shape.
+      for (const key of streamed) kept[key] = {};
+      out = { ...schema, properties: kept };
+    }
+  }
+
+  // Recurse: a stream one level down (an item, a branch, a nested object) is as
+  // live as one at the root, and walking it with AJV is the same defect.
+  //
+  // `properties` and `$defs` are MAPS of schemas, not schemas — descending into
+  // them as if they were would visit nothing, since a map has none of the
+  // keywords this walk looks for.
+  let changed = out !== schema;
+  const result: Record<string, any> = { ...out };
+  for (const key of ["properties", "$defs"] as const) {
+    const map = out[key] as Record<string, any> | undefined;
+    if (!map || typeof map !== "object") continue;
+    let mapChanged = false;
+    const next: Record<string, any> = {};
+    for (const [name, child] of Object.entries(map)) {
+      const stripped = stripStreams(child, here, resolveRef);
+      if (stripped !== child) mapChanged = true;
+      next[name] = stripped;
+    }
+    if (mapChanged) {
+      result[key] = next;
+      changed = true;
+    }
+  }
+  for (const key of ["items", "allOf", "anyOf", "oneOf"] as const) {
+    const child = out[key];
+    if (child === undefined) continue;
+    const next = stripStreams(child, here, resolveRef);
+    if (next !== child) {
+      result[key] = next;
+      changed = true;
+    }
+  }
+  return changed ? result : schema;
+}
+
+/** Every property path in `schema` that can receive a `default:` — the paths a
+ *  defaults pass may write to, and therefore exactly how far the caller's inputs
+ *  must be copied before AJV's `useDefaults` runs. A flat shallow copy would not
+ *  do: `useDefaults` writes at every level it finds a default, so a nested
+ *  default would mutate the structure the caller still holds. Bounded by the
+ *  schema's defaults rather than by the size of the payload. */
+export function defaultBearingPaths(
+  schema: Record<string, any>,
+  /** See {@link withStreamPropertiesSkipped} — a contract kept in `$ref` form
+   *  declares its defaults behind the reference, and a walk that cannot follow
+   *  it would report none, leaving the caller's data shared where a fill lands. */
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): string[][] {
+  const out: string[][] = [];
+
+  // Path-scoped, for the same reason as the stream walk: a shared subschema
+  // reached from two parents contributes a path under each.
+  const walk = (node: unknown, path: string[], chain: readonly object[]): void => {
+    if (!node || typeof node !== "object") return;
+    let s = node as Record<string, any>;
+    if (chain.includes(s)) return;
+    if (resolveRef && typeof s.$ref === "string") {
+      const target = resolveRef(s.$ref);
+      if (!target || chain.includes(target)) return;
+      s = { ...target, ...s, $ref: undefined };
+    }
+    const here = [...chain, node as object];
+
+    if ("default" in s && path.length > 0) out.push(path);
+
+    const properties = s.properties as Record<string, any> | undefined;
+    if (properties) {
+      for (const [key, child] of Object.entries(properties)) walk(child, [...path, key], here);
+    }
+    for (const branch of ["allOf", "anyOf", "oneOf"] as const) {
+      const list = s[branch];
+      if (Array.isArray(list)) for (const child of list) walk(child, path, here);
+    }
+    if (s.items) walk(s.items, [...path, "[]"], here);
+  };
+
+  walk(schema, [], []);
+  return out;
+}

package/src/manifest-loader.ts

@@ -117,6 +117,26 @@ export class Loader {
     return this.urlToSource.get(url);
   }
 
+  /** Drop every memo for `url` so the next `loadFile` reads it from the source
+   *  chain again — the parsed file in each variant, plus every request URL that
+   *  canonicalised to it (a module reached under several refs must not stay
+   *  reachable through one of them).
+   *
+   *  `loadFile`'s fast path assumes a file's contents do not change under a
+   *  single Loader, which holds until something invalidates one deliberately:
+   *  `telo check` dropping a manifest whose upstream tag has moved, and watch
+   *  mode when it returns. Without this the only way to un-cache one file is to
+   *  discard the whole Loader, taking every unrelated file's memo with it. */
+  forget(url: string): void {
+    const source = this.urlToSource.get(url) ?? url;
+    for (const [requestUrl, canonical] of this.urlToSource) {
+      if (canonical === source) this.urlToSource.delete(requestUrl);
+    }
+    for (const variant of CACHE_VARIANTS) {
+      this.fileCache.delete(`${variant}:${source}`);
+    }
+  }
+
   // --- New API: returns LoadedFile / LoadedModule / LoadedGraph ----------
 
   /** Read one file via the source chain and parse it into a LoadedFile.