@telorun/analyzer 0.48.0 → 0.49.1

package/dist/builtins.js

@@ -206,6 +206,64 @@ export const KERNEL_BUILTINS = [
             additionalProperties: false,
         },
     },
+    {
+        // Telo.JsonSchema — the concrete data-shape kind, in the kernel rather than
+        // in an installable module for the same reason the mandatory sinks are:
+        // declaring a shape is not optional. Every kind with an invocation contract
+        // needs one, so requiring an import to write `inputType:` would put a tax on
+        // the one thing the contract wants authors to do more of — and a library
+        // declaring a contract would have to import a module purely to describe
+        // itself. `type.JsonSchema` remains as a deprecated alias of this kind.
+        kind: "Telo.Definition",
+        metadata: { name: "JsonSchema", module: "Telo" },
+        capability: "Telo.Type",
+        // Declared so the kind reads as controller-BEARING, which is what lets
+        // another definition inherit it by delegation (`extends: Telo.JsonSchema`
+        // with no controller of its own). The entry is never loaded from — the
+        // kernel registers this controller directly at boot, before any lazy
+        // resolution — it states truthfully who provides it.
+        controllers: [{ runtime: "kernel", entry: "Telo.JsonSchema" }],
+        schema: {
+            type: "object",
+            properties: {
+                schema: {
+                    title: "Schema",
+                    description: "JSON Schema definition for the declared data type.",
+                    type: "object",
+                },
+                extends: {
+                    title: "Extends",
+                    description: "Parent type name or list of parent type names to inherit from.",
+                    oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+                },
+                rules: {
+                    title: "Rules",
+                    description: "CEL-based business invariant rules. Each rule's condition must return true for valid data.",
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            condition: {
+                                type: "string",
+                                description: "CEL expression evaluated with 'this' bound to the data. Must return true for valid data.",
+                            },
+                            code: {
+                                type: "string",
+                                description: "Machine-readable error code surfaced on validation failure.",
+                            },
+                            message: {
+                                type: "string",
+                                description: "Optional human-readable hint for the validation failure.",
+                            },
+                        },
+                        required: ["condition", "code"],
+                    },
+                },
+            },
+            required: ["schema"],
+            additionalProperties: false,
+        },
+    },
     {
         kind: "Telo.Definition",
         metadata: { name: "Abstract", module: "Telo" },
@@ -479,6 +537,11 @@ export const KERNEL_BUILTINS = [
                     default: "shared",
                 },
                 targets: {
+                    // Boot targets form a step list: a later target reads an earlier one's
+                    // result as `steps.<name>.result`, exactly as a sequence step does, so
+                    // the same annotation types that context and drives the call-site
+                    // contract check.
+                    "x-telo-step-context": { invoke: "invoke", outputType: "outputType" },
                     type: "array",
                     items: {
                         anyOf: [
@@ -552,7 +615,15 @@ export const KERNEL_BUILTINS = [
                                             { "x-telo-ref": "Telo.Runnable" },
                                         ],
                                     },
-                                    inputs: { type: "object", additionalProperties: true },
+                                    inputs: {
+                                        // Same annotation Run.Sequence steps carry: it is what makes
+                                        // a boot target's inputs visible to the call-site contract
+                                        // check and to the wiring rule. Without it the kernel would
+                                        // validate these at dispatch and nothing before it.
+                                        "x-telo-topology-role": "inputs",
+                                        type: "object",
+                                        additionalProperties: true,
+                                    },
                                     when: { type: "string" },
                                 },
                                 additionalProperties: false,

package/dist/extends-resolution.d.ts

@@ -36,6 +36,47 @@ export declare function inheritedCapability(def: ResourceDefinition | undefined,
  *    `mergeTypeSchemas` that `Type.JsonSchema.extends` uses.
  *  - no `extends` → the own schema unchanged. */
 export declare function effectiveAuthorSchema(def: ResourceDefinition | undefined, resolve: DefResolver): 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 declare function effectiveContractField(def: ResourceDefinition | undefined, resolve: DefResolver, direction: ContractDirection): unknown;
+/** 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 declare function contractDeclarer(def: ResourceDefinition | undefined, resolve: DefResolver, direction: ContractDirection): ResourceDefinition | 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 declare function needsContractMapping(def: ResourceDefinition | undefined, resolve: DefResolver, direction: ContractDirection): boolean;
+/** 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 declare function mappingFieldFor(direction: ContractDirection): "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/dist/extends-resolution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extends-resolution.d.ts","sourceRoot":"","sources":["../src/extends-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD;;;;;;;2DAO2D;AAC3D,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,kBAAkB,KACtB,kBAAkB,GAAG,SAAS,CAAC;AAsBpC;sDACsD;AACtD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAIhC;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,EAAE,CAUtB;AAED;iFACiF;AACjF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAUvF;AAED;;mFAEmF;AACnF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAMhC;AAED;;sCAEsC;AACtC,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,OAAO,CAGT;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOrB;AAED;;;;;;;;;gDASgD;AAChD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CASjC"}
+{"version":3,"file":"extends-resolution.d.ts","sourceRoot":"","sources":["../src/extends-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD;;;;;;;2DAO2D;AAC3D,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,kBAAkB,KACtB,kBAAkB,GAAG,SAAS,CAAC;AA0BpC;sDACsD;AACtD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAIhC;AAED;6EAC6E;AAC7E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,EAAE,CAUtB;AAED;iFACiF;AACjF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAUvF;AAED;;mFAEmF;AACnF,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,kBAAkB,GAAG,SAAS,CAMhC;AAED;;sCAEsC;AACtC,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,OAAO,CAGT;AAED;2EAC2E;AAC3E,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,GAAG,SAAS,CAMpB;AAED;;;;;;iDAMiD;AACjD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOrB;AAED;;eAEe;AACf,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,iBAAiB,GAC3B,OAAO,CAQT;AAED;;;6BAG6B;AAC7B,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,iBAAiB,GAC3B,kBAAkB,GAAG,SAAS,CAShC;AAED;;;;;8CAK8C;AAC9C,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,iBAAiB,GAC3B,OAAO,CAKT;AAED;;8EAE8E;AAC9E,wBAAgB,eAAe,CAAC,SAAS,EAAE,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,CAEjF;AAED;;;;;;;;;gDASgD;AAChD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,kBAAkB,GAAG,SAAS,EACnC,OAAO,EAAE,WAAW,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CASjC"}

package/dist/extends-resolution.js

@@ -80,6 +80,74 @@ export function effectiveAuthorSchema(def, resolve) {
     const parentSchema = effectiveAuthorSchema(parent, resolve);
     return mergeTypeSchemas([parentSchema, own]);
 }
+/**
+ * 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, resolve, direction) {
+    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, resolve, direction) {
+    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, resolve, direction) {
+    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) {
+    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/dist/index.d.ts

@@ -9,8 +9,10 @@ export { applyObservedStateNode, buildObservedStateIndex, buildObservedStateReso
 export type { AnalyzedResource, ObservedStateRead } from "./validate-observed-state.js";
 export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
 export type { ModuleScopes } from "./alias-resolver.js";
-export { ancestorChain, controllerBearingAncestor, effectiveAuthorSchema, effectiveStatusSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, resolveParent, } from "./extends-resolution.js";
-export type { DefResolver } from "./extends-resolution.js";
+export { ancestorChain, contractDeclarer, controllerBearingAncestor, effectiveAuthorSchema, effectiveContractField, effectiveStatusSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, mappingFieldFor, needsContractMapping, resolveParent, } 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, RedactionPathError, } from "./redaction-path.js";
 export type { RedactionSegment } from "./redaction-path.js";
 export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-field-map.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -5,7 +5,8 @@ export { flattenForAnalyzer, flattenLoadedModule, forwardReExportManifests, pars
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
 export { applyObservedStateNode, buildObservedStateIndex, buildObservedStateResourcesSchema, collectRunReachableNames, observedStateRead, validateObservedStateDeclarations, OBSERVED_STATE_SCHEMA, } from "./validate-observed-state.js";
 export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
-export { ancestorChain, controllerBearingAncestor, effectiveAuthorSchema, effectiveStatusSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, resolveParent, } from "./extends-resolution.js";
+export { ancestorChain, contractDeclarer, controllerBearingAncestor, effectiveAuthorSchema, effectiveContractField, effectiveStatusSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, mappingFieldFor, needsContractMapping, resolveParent, } from "./extends-resolution.js";
+export { defaultBearingPaths, PERMISSIVE_CONTRACT, resolveContract, resolveContractSchema, withStreamPropertiesSkipped, } from "./invocation-contract.js";
 export { hasIntermediateWildcard, parseRedactionPath, RedactionPathError, } from "./redaction-path.js";
 export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-field-map.js";
 export { visitManifest } from "./manifest-visitor.js";

package/dist/invocation-contract.d.ts

@@ -0,0 +1,100 @@
+import type { ResourceDefinition } from "@telorun/sdk";
+import { type ContractDirection, type DefResolver } from "./extends-resolution.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 declare const PERMISSIVE_CONTRACT: Record<string, any>;
+/**
+ * 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 declare function resolveContract(direction: ContractDirection, manifest: Record<string, any> | undefined, definition: ResourceDefinition | undefined, scope: ContractScope): ResolvedContract | undefined;
+/** {@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 declare function resolveContractSchema(direction: ContractDirection, manifest: Record<string, any> | undefined, definition: ResourceDefinition | undefined, scope: ContractScope): Record<string, any>;
+/**
+ * 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 declare 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>;
+/** 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 declare 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[][];
+//# sourceMappingURL=invocation-contract.d.ts.map

package/dist/invocation-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-contract.d.ts","sourceRoot":"","sources":["../src/invocation-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,WAAW,EAEjB,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;;;;;;;;;GAYG;AAEH;;oCAEoC;AACpC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB;gFAC4E;IAC5E,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;;kEAE8D;IAC9D,iBAAiB,EAAE,WAAW,CAAC;IAC/B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CAC9E;AAED;;uCAEuC;AACvC,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAGnD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EACzC,UAAU,EAAE,kBAAkB,GAAG,SAAS,EAC1C,KAAK,EAAE,aAAa,GACnB,gBAAgB,GAAG,SAAS,CAa9B;AAED;;mDAEmD;AACnD,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EACzC,UAAU,EAAE,kBAAkB,GAAG,SAAS,EAC1C,KAAK,EAAE,aAAa,GACnB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAErB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;AAC3B;;;;yCAIyC;AACzC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAC5D,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAErB;AAiGD;;;;;gEAKgE;AAChE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;AAC3B;;iFAEiF;AACjF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAC5D,MAAM,EAAE,EAAE,CA+BZ"}

package/dist/invocation-contract.js

@@ -0,0 +1,208 @@
+import { contractDeclarer, effectiveContractField, } from "./extends-resolution.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
+/** 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 = {
+    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, manifest, definition, scope) {
+    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, manifest, definition, scope) {
+    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, 
+/** 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) {
+    return stripStreams(schema, [], resolveRef);
+}
+function stripStreams(node, 
+// 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, resolveRef) {
+    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;
+    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 = schema;
+    const properties = schema.properties;
+    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]?.["x-telo-stream"]);
+        if (streamed.length > 0) {
+            const kept = {};
+            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 = { ...out };
+    for (const key of ["properties", "$defs"]) {
+        const map = out[key];
+        if (!map || typeof map !== "object")
+            continue;
+        let mapChanged = false;
+        const next = {};
+        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"]) {
+        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, 
+/** 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) {
+    const out = [];
+    // 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, path, chain) => {
+        if (!node || typeof node !== "object")
+            return;
+        let s = node;
+        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];
+        if ("default" in s && path.length > 0)
+            out.push(path);
+        const properties = s.properties;
+        if (properties) {
+            for (const [key, child] of Object.entries(properties))
+                walk(child, [...path, key], here);
+        }
+        for (const branch of ["allOf", "anyOf", "oneOf"]) {
+            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/dist/manifest-loader.d.ts

@@ -30,6 +30,17 @@ export declare class Loader {
      *  set-membership against a previous graph walk's modules without
      *  triggering an extra source read. */
     canonicalize(url: string): string | undefined;
+    /** 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;
     /** Read one file via the source chain and parse it into a LoadedFile.
      *  The result is shared with `Loader.fileCache`. Callers that want a
      *  private mutable copy must call `parseLoadedFile` directly with the

package/dist/manifest-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAwCpB,qBAAa,MAAM;IACjB;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D;;;;;8BAK0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;mBAIe;gBACH,OAAO,GAAE,cAAc,EAAO,EAAE,OAAO,GAAE,iBAAsB;IAK3E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUrD;;;;2CAIuC;IACvC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM7C;;;+BAG2B;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAyCvE;;;;gEAI4D;IAC5D,OAAO,CAAC,oBAAoB;IAa5B;gFAC4E;IAC5E,OAAO,CAAC,cAAc;IAQtB;;wEAEoE;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAsB3E;;;qCAGiC;IAC3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAiI9E;;;;;;;;sBAQkB;IAClB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAOlE,OAAO,CAAC,6BAA6B;IAarC,OAAO,CAAC,mCAAmC;IAc3C,OAAO,CAAC,2BAA2B;YAkCrB,eAAe;IAmB7B;;;0CAGsC;IAChC,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA0B5D"}
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../src/manifest-loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAwCpB,qBAAa,MAAM;IACjB;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D;;;;;8BAK0B;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC;;;;mBAIe;gBACH,OAAO,GAAE,cAAc,EAAO,EAAE,OAAO,GAAE,iBAAsB;IAK3E,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAKtC,OAAO,CAAC,IAAI;IAMN,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUrD;;;;2CAIuC;IACvC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;;;gFAS4E;IAC5E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAYzB;;;+BAG2B;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAyCvE;;;;gEAI4D;IAC5D,OAAO,CAAC,oBAAoB;IAa5B;gFAC4E;IAC5E,OAAO,CAAC,cAAc;IAQtB;;wEAEoE;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAsB3E;;;qCAGiC;IAC3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAiI9E;;;;;;;;sBAQkB;IAClB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAOlE,OAAO,CAAC,6BAA6B;IAarC,OAAO,CAAC,mCAAmC;IAc3C,OAAO,CAAC,2BAA2B;YAkCrB,eAAe;IAmB7B;;;0CAGsC;IAChC,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CA0B5D"}

package/dist/manifest-loader.js

@@ -88,6 +88,26 @@ export class Loader {
     canonicalize(url) {
         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) {
+        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.
      *  The result is shared with `Loader.fileCache`. Callers that want a