@telorun/analyzer 0.47.0 → 0.49.0

package/src/artifact-layer-index.ts

@@ -0,0 +1,162 @@
+/**
+ * The **layer index** of `kernel/specs/module-artifact.md` — the `layers:` block
+ * a published `telo.yaml` carries, listing every layer of the module artifact
+ * except the manifest layer itself.
+ *
+ * Why it lives in `telo.yaml` rather than in the OCI manifest, which has layers
+ * natively: a Telo import is pinned to a hash of `telo.yaml` and nothing else.
+ * The OCI manifest sits one level up, is fetched by a reference that is usually
+ * a mutable tag, and is never hashed by Telo — so digests held only there would
+ * leave the pin proving nothing about the payload. Pinning the OCI manifest
+ * instead is circular: `telo.yaml` is one of its layers.
+ *
+ * The manifest layer therefore has no entry — a hash of `telo.yaml` cannot sit
+ * inside `telo.yaml`. It is pinned by the importer's `#sha256-...` instead, so
+ * the chain reads `import pin -> telo.yaml -> blob digest -> layer contents`.
+ *
+ * Each entry carries two digests, answering different questions:
+ *  - `blob` — the OCI blob digest over the pushed bytes. It *addresses* the
+ *    layer, so a client pulls by digest and never reads the OCI layer list, and
+ *    it verifies the transfer. Publish pushes payload blobs first and injects
+ *    their digests here, then pushes the manifest blob, so nothing is circular.
+ *  - `integrity` — the content digest (`computeFilesIntegrity`) over that
+ *    layer's own files, independent of tar/gzip framing. It verifies what is
+ *    already extracted on disk and can be re-derived from it without re-tarring,
+ *    which is what makes a per-layer cache marker checkable.
+ *
+ * Browser-safe: `telo check`, the editor and the hub validate an index through
+ * this module; only the kernel fetches and extracts.
+ */
+
+import {
+  isLayerRole,
+  normalizeSelector,
+  selectorKey,
+  selectorMatches,
+  type ArtifactSelector,
+  type LayerRole,
+  type PlatformTarget,
+} from "./artifact-selector.js";
+
+/** OCI content digest: `sha256:` + 64 lowercase hex. */
+const BLOB_DIGEST = /^sha256:[0-9a-f]{64}$/;
+
+/** Telo content digest: `sha256-` + unpadded base64url of 32 bytes. */
+const CONTENT_DIGEST = /^sha256-[A-Za-z0-9_-]{43}$/;
+
+export interface ArtifactLayer {
+  role: LayerRole;
+  /** Present on `controller` layers only. */
+  selector?: ArtifactSelector;
+  /** OCI blob digest — addresses the layer and verifies the transfer. */
+  blob: string;
+  /** Content digest over the layer's files — verifies what is on disk. */
+  integrity: string;
+}
+
+export class LayerIndexError extends Error {
+  readonly code = "INVALID_LAYER_INDEX";
+
+  constructor(detail: string) {
+    super(detail);
+    this.name = "LayerIndexError";
+  }
+}
+
+function digest(field: "blob" | "integrity", raw: unknown, describe: string): string {
+  if (typeof raw !== "string" || raw === "") {
+    throw new LayerIndexError(`${describe}: ${field} is required and must be a string.`);
+  }
+  const pattern = field === "blob" ? BLOB_DIGEST : CONTENT_DIGEST;
+  if (!pattern.test(raw)) {
+    throw new LayerIndexError(
+      field === "blob"
+        ? `${describe}: blob '${raw}' is not an OCI digest (expected 'sha256:' + 64 hex characters).`
+        : `${describe}: integrity '${raw}' is not a content digest (expected 'sha256-' + 43 base64url characters).`,
+    );
+  }
+  return raw;
+}
+
+/**
+ * Parse and validate a `layers:` value off an owner document. Order is
+ * preserved — when several controller layers match a target, precedence is
+ * declaration order, so the author controls it.
+ */
+export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLayer[] {
+  if (!Array.isArray(value)) {
+    throw new LayerIndexError(`${describe}: expected an array of layer entries.`);
+  }
+  const layers: ArtifactLayer[] = [];
+  const seenSelectors = new Set<string>();
+  const seenSingletons = new Set<LayerRole>();
+
+  value.forEach((raw, index) => {
+    const where = `${describe}[${index}]`;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      throw new LayerIndexError(`${where}: expected an object.`);
+    }
+    const entry = raw as Record<string, unknown>;
+    if (!isLayerRole(entry.role)) {
+      throw new LayerIndexError(
+        `${where}: role must be one of 'controller', 'assets', 'common'; got ` +
+          `${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
+      );
+    }
+    const role = entry.role;
+
+    let selector: ArtifactSelector | undefined;
+    if (role === "controller") {
+      if (entry.selector === undefined) {
+        throw new LayerIndexError(`${where}: a controller layer must declare a selector.`);
+      }
+      selector = normalizeSelector(entry.selector, where);
+      const key = selectorKey(selector);
+      if (seenSelectors.has(key)) {
+        throw new LayerIndexError(
+          `${where}: a second controller layer claims the selector ${key}. ` +
+            `Each selector addresses exactly one layer.`,
+        );
+      }
+      seenSelectors.add(key);
+    } else {
+      if (entry.selector !== undefined) {
+        throw new LayerIndexError(
+          `${where}: a '${role}' layer must not declare a selector — it is a singleton.`,
+        );
+      }
+      if (seenSingletons.has(role)) {
+        throw new LayerIndexError(`${where}: a second '${role}' layer is declared.`);
+      }
+      seenSingletons.add(role);
+    }
+
+    layers.push({
+      role,
+      ...(selector ? { selector } : {}),
+      blob: digest("blob", entry.blob, where),
+      integrity: digest("integrity", entry.integrity, where),
+    });
+  });
+
+  return layers;
+}
+
+/** The singleton layer for a role, or undefined when the artifact has none. */
+export function singletonLayer(
+  layers: readonly ArtifactLayer[],
+  role: Exclude<LayerRole, "controller">,
+): ArtifactLayer | undefined {
+  return layers.find((l) => l.role === role);
+}
+
+/** Every controller layer matching `target`, in declaration order. Used by
+ *  `telo install` to warm a cache for one platform. */
+export function matchControllerLayers(
+  layers: readonly ArtifactLayer[],
+  target: PlatformTarget,
+): ArtifactLayer[] {
+  return layers.filter(
+    (l) => l.role === "controller" && l.selector !== undefined && selectorMatches(l.selector, target),
+  );
+}

package/src/artifact-selector.ts

@@ -0,0 +1,171 @@
+/**
+ * The **selector** of `kernel/specs/module-artifact.md` — the tuple a bundled
+ * controller candidate is chosen by, and the key a controller layer of a module
+ * artifact is stored under.
+ *
+ * A selector is `format` plus the optional platform axes `os` / `arch` / `libc`.
+ * Matching is one rule, applied per axis: an axis the selector omits accepts
+ * anything, an axis it states must be equal. That is what lets a `js` controller
+ * be platform-neutral and a `napi` controller be pinned to one triple, with no
+ * special case for either.
+ *
+ * Browser-safe and dependency-free by construction. Three consumers must agree
+ * on this grammar or a published artifact stops loading: `telo publish`
+ * (partitioning files into layers), `telo install --platform` (deciding which
+ * layers to pre-fetch), and the kernel's bundle controller loader (matching a
+ * candidate against the host). Keeping it here — beside the redaction path
+ * parser, for the same reason — means one implementation rather than three that
+ * drift.
+ *
+ * PURL *syntax* is deliberately not parsed here. Callers hand in the format and
+ * an already-decoded qualifier map, so this module owns selector semantics while
+ * the caller owns its own package-URL library. The Node vocabulary is likewise
+ * not known here: `process.platform` / `process.arch` are mapped to the
+ * canonical OCI/GOOS names at the kernel boundary, since these values are
+ * published into OCI descriptors.
+ */
+
+/** The role a layer plays in a module artifact. `controller` layers carry a
+ *  selector; `assets` and `common` are singletons and carry none. */
+export type LayerRole = "controller" | "assets" | "common";
+
+export const LAYER_ROLES: readonly LayerRole[] = ["controller", "assets", "common"];
+
+export function isLayerRole(value: unknown): value is LayerRole {
+  return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
+}
+
+/** The platform axes, in canonical order. Not a closed vocabulary of *values* —
+ *  new architectures appear without a Telo release — only of axis names. */
+export const PLATFORM_AXES = ["os", "arch", "libc"] as const;
+
+export type PlatformAxis = (typeof PLATFORM_AXES)[number];
+
+export interface ArtifactSelector {
+  /** Bundled controller format: the PURL name segment (`js`, `napi`, `wasm`, …). */
+  format: string;
+  os?: string;
+  arch?: string;
+  libc?: string;
+}
+
+/** What a selector is matched against: the host the kernel runs on, or the
+ *  target `telo install --platform` is warming a cache for. An axis left
+ *  undetermined (a host whose libc cannot be detected) matches no selector that
+ *  constrains it — refusing to load is the safe direction for a native binary. */
+export interface PlatformTarget {
+  format?: string;
+  os?: string;
+  arch?: string;
+  libc?: string;
+}
+
+export class ArtifactSelectorError extends Error {
+  readonly code = "INVALID_ARTIFACT_SELECTOR";
+
+  constructor(detail: string) {
+    super(detail);
+    this.name = "ArtifactSelectorError";
+  }
+}
+
+/** Canonical token shape for every selector value. Lowercase, so the same
+ *  platform written two ways is one layer rather than two. */
+const TOKEN = /^[a-z0-9][a-z0-9_.-]*$/;
+
+function normalizeToken(axis: string, raw: unknown, describe: string): string {
+  if (typeof raw !== "string") {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} must be a string, got ${raw === null ? "null" : typeof raw}.`,
+    );
+  }
+  const value = raw.trim().toLowerCase();
+  if (!TOKEN.test(value)) {
+    throw new ArtifactSelectorError(
+      `${describe}: ${axis} value '${raw}' is not a canonical token. ` +
+        `Use lowercase letters, digits, '.', '-' or '_', starting with a letter or digit.`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Build a selector from a controller candidate's format and qualifier map.
+ * Qualifier keys other than the platform axes are ignored — `path` and the
+ * sibling list live in the same map and are not part of the selector.
+ */
+export function selectorFromQualifiers(
+  format: unknown,
+  qualifiers: Readonly<Record<string, unknown>> | undefined,
+  describe = "controller selector",
+): ArtifactSelector {
+  const selector: ArtifactSelector = {
+    format: normalizeToken("format", format, describe),
+  };
+  for (const axis of PLATFORM_AXES) {
+    const raw = qualifiers?.[axis];
+    if (raw === undefined || raw === "") continue;
+    selector[axis] = normalizeToken(axis, raw, describe);
+  }
+  return selector;
+}
+
+/** Validate and normalize a selector read off a published layer index. */
+export function normalizeSelector(
+  value: unknown,
+  describe = "layer selector",
+): ArtifactSelector {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ArtifactSelectorError(`${describe}: expected an object of selector axes.`);
+  }
+  const record = value as Record<string, unknown>;
+  const unknown = Object.keys(record).filter(
+    (k) => k !== "format" && !(PLATFORM_AXES as readonly string[]).includes(k),
+  );
+  if (unknown.length > 0) {
+    throw new ArtifactSelectorError(
+      `${describe}: unknown selector ${unknown.length === 1 ? "axis" : "axes"} ` +
+        `${unknown.map((k) => `'${k}'`).join(", ")}. Known axes: format, ${PLATFORM_AXES.join(", ")}.`,
+    );
+  }
+  return selectorFromQualifiers(record.format, record, describe);
+}
+
+/**
+ * The canonical stable key for a selector: sorted `axis=value` pairs joined by
+ * `;`. Used to group entry points into layers at publish time and to detect two
+ * layers claiming the same selector. Sorted and fully qualified so no two
+ * distinct selectors can collide and no one selector has two spellings.
+ */
+export function selectorKey(selector: ArtifactSelector): string {
+  const pairs: string[] = [`format=${selector.format}`];
+  for (const axis of PLATFORM_AXES) {
+    const value = selector[axis];
+    if (value !== undefined) pairs.push(`${axis}=${value}`);
+  }
+  return pairs.sort().join(";");
+}
+
+/** Human-facing rendering for diagnostics and the publish partition printout. */
+export function describeSelector(selector: ArtifactSelector): string {
+  const platform = PLATFORM_AXES.map((axis) => selector[axis]).filter(
+    (v): v is string => v !== undefined,
+  );
+  return platform.length === 0 ? selector.format : `${selector.format} (${platform.join("/")})`;
+}
+
+/**
+ * The matching rule: every axis the selector states must equal the target's;
+ * every axis it omits accepts anything. A target axis left undetermined matches
+ * only a selector that does not constrain it — a host whose libc is unknown must
+ * not be handed a `libc=gnu` binary on the assumption it will run.
+ */
+export function selectorMatches(selector: ArtifactSelector, target: PlatformTarget): boolean {
+  if (target.format !== undefined && selector.format !== target.format) return false;
+  for (const axis of PLATFORM_AXES) {
+    const constraint = selector[axis];
+    if (constraint === undefined) continue;
+    if (target[axis] !== constraint) return false;
+  }
+  return true;
+}

package/src/builtins.ts

@@ -23,6 +23,53 @@ const PROVENANCE_METADATA = {
   documentation: { type: "string" },
 };
 
+/** Author-declared subset of `files:` that ships in the artifact's lazily
+ *  materialized `assets` layer. Optional: an unclaimed file joins the `common`
+ *  layer, which is pulled alongside any controller layer, so omitting this costs
+ *  laziness rather than correctness. See kernel/specs/module-artifact.md. */
+const ASSETS_FILES_SCHEMA = {
+  type: "array",
+  items: { type: "string" },
+};
+
+/** The published layer index, written by `telo publish` (never hand-authored).
+ *  One entry per layer except the manifest layer, which cannot list its own hash
+ *  inside itself and is pinned by the importer's `#sha256-...` instead. Shape and
+ *  matching rules are normative in kernel/specs/module-artifact.md; the parser
+ *  that enforces them is `artifact-layer-index.ts`. */
+const LAYER_INDEX_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["role", "blob", "integrity"],
+    properties: {
+      role: { type: "string", enum: ["controller", "assets", "common"] },
+      selector: {
+        type: "object",
+        required: ["format"],
+        properties: {
+          format: { type: "string" },
+          os: { type: "string" },
+          arch: { type: "string" },
+          libc: { type: "string" },
+        },
+        additionalProperties: false,
+      },
+      blob: { type: "string", pattern: "^sha256:[0-9a-f]{64}$" },
+      integrity: { type: "string", pattern: "^sha256-[A-Za-z0-9_-]{43}$" },
+    },
+    additionalProperties: false,
+  },
+};
+
+/** The pre-layers payload digest, superseded by the per-layer `integrity` values
+ *  in `layers:`. Accepted and ignored, for one reason only: a module published in
+ *  the old single-blob shape must reach the *actionable* failure — the controller
+ *  loader's "republish the module" error — instead of dying earlier on
+ *  `must NOT have additional properties`, which tells an author nothing. Nothing
+ *  reads this field. */
+const LEGACY_FILES_INTEGRITY_SCHEMA = { type: "string" };
+
 /** The six named levels of `kernel/specs/logging.md` §5.1. The full 1–24 OTel
  *  range stays valid on the wire; only these are nameable in a manifest. */
 const LOG_LEVEL_ENUM = ["trace", "debug", "info", "warn", "error", "fatal"];
@@ -171,6 +218,66 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
       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" },
@@ -444,6 +551,11 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           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: [
@@ -517,7 +629,15 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                       { "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,
@@ -529,21 +649,18 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
-        // Files bundled alongside `telo.yaml` into the module's registry
-        // artifact (`module.tar.gz`) — static assets served by Http.Static,
-        // templates, etc. Ordered `.gitignore`-style patterns resolved against
-        // the manifest dir at publish time. Analyzer-only role: accept the
-        // field (the schema is additionalProperties:false); the analyzer never
-        // reads the assets. See kernel/nodejs/plans/bundle-controllers.md.
+        // Files bundled alongside `telo.yaml` into the module's artifact —
+        // controller bundles, static assets served by Http.Static, templates,
+        // etc. Ordered `.gitignore`-style patterns resolved against the manifest
+        // dir at publish time. Analyzer-only role: accept the field (the schema
+        // is additionalProperties:false); the analyzer never reads the payload.
         files: {
           type: "array",
           items: { type: "string" },
         },
-        // Integrity hash of the decompressed payload tar (`module.tar.gz`,
-        // telo.yaml excluded), written by `telo publish`. Pinned transitively
-        // by the importer's `#sha256-...` hash over this telo.yaml; verified at
-        // extract time. See plans/federated-registries.md.
-        filesIntegrity: { type: "string" },
+        assets: ASSETS_FILES_SCHEMA,
+        layers: LAYER_INDEX_SCHEMA,
+        filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — name-keyed map sugar for separate `Telo.Import`
         // documents. The key is the PascalCase alias (the import's
         // `metadata.name`). Each value is either a bare source string
@@ -680,18 +797,16 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
-        // Files bundled into the module's registry artifact — same semantics as
-        // the Telo.Application `files` field above (a library may ship bundled
-        // templates, migrations, seed data).
+        // Files bundled into the module's artifact — same semantics as the
+        // Telo.Application `files` field above (a library may ship bundled
+        // controllers, templates, migrations, seed data).
         files: {
           type: "array",
           items: { type: "string" },
         },
-        // Integrity hash of the decompressed payload tar (`module.tar.gz`,
-        // telo.yaml excluded), written by `telo publish`. Pinned transitively
-        // by the importer's `#sha256-...` hash over this telo.yaml; verified at
-        // extract time. See plans/federated-registries.md.
-        filesIntegrity: { type: "string" },
+        assets: ASSETS_FILES_SCHEMA,
+        layers: LAYER_INDEX_SCHEMA,
+        filesIntegrity: LEGACY_FILES_INTEGRITY_SCHEMA,
         // Inline imports — same name-keyed map sugar as Telo.Application; the
         // loader desugars each entry into a synthetic Telo.Import. See the
         // Application schema above and analyzer/nodejs/src/inline-imports.ts.

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