@telorun/kernel 0.77.0 → 0.79.0

package/src/controller-loaders/npm-loader.ts

@@ -1,4 +1,5 @@
 import { ControllerInstance, NOOP_LOGGER, type Logger } from "@telorun/sdk";
+import type { ControllerWorkReporter } from "../controller-loader.js";
 import { execFile } from "child_process";
 import * as crypto from "crypto";
 import * as fs from "fs/promises";
@@ -188,6 +189,7 @@ export class NpmControllerLoader {
   async resolve(
     purl: string,
     baseUri: string,
+    report?: ControllerWorkReporter,
   ): Promise<{ source: NpmResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     const parsed = PackageURL.fromString(purl);
     if (!parsed.name) {
@@ -199,7 +201,7 @@ export class NpmControllerLoader {
     // versions can coexist in one flat node_modules (see installAlias).
     const alias = installAlias(packageName, version);
 
-    const installRoot = await this.ensureInstallRoot();
+    const installRoot = await this.ensureInstallRoot(report);
     const resolved = await resolveInstallSpec(parsed, packageName, baseUri);
     const source = await this.installPackage(
       installRoot,
@@ -207,6 +209,7 @@ export class NpmControllerLoader {
       resolved.spec,
       resolved.kind,
       version,
+      report,
     );
     const subpath = parsed.subpath ?? null;
     return {
@@ -221,9 +224,9 @@ export class NpmControllerLoader {
    * `npm install` once, and return the absolute root path. Memoized for the
    * lifetime of this loader instance.
    */
-  private ensureInstallRoot(): Promise<string> {
+  private ensureInstallRoot(report?: ControllerWorkReporter): Promise<string> {
     if (this.rootReady) return this.rootReady;
-    this.rootReady = this.materializeInstallRoot().catch((err) => {
+    this.rootReady = this.materializeInstallRoot(report).catch((err) => {
       // Reset on failure so a follow-up call retries rather than caches the rejection.
       this.rootReady = undefined;
       throw err;
@@ -231,7 +234,7 @@ export class NpmControllerLoader {
     return this.rootReady;
   }
 
-  private async materializeInstallRoot(): Promise<string> {
+  private async materializeInstallRoot(report?: ControllerWorkReporter): Promise<string> {
     if (!this.entryUrl) {
       // Throw the env-missing variant so a mixed candidate list (e.g.
       // `pkg:npm/... + pkg:cargo/...`) still falls back to the next
@@ -325,6 +328,9 @@ export class NpmControllerLoader {
           2,
         ) + "\n",
       );
+      // Announced here rather than at the top of the resolve: everything above
+      // this line is a fast path that reuses the existing tree.
+      await report?.("npm-install");
       await runPackageManager(installRoot, [
         "install",
         "--no-audit",
@@ -383,6 +389,7 @@ export class NpmControllerLoader {
     spec: string,
     kind: SpecKind,
     requestedVersion: string | null,
+    report?: ControllerWorkReporter,
   ): Promise<NpmResolveSource> {
     const cacheKey = alias;
     if (this.installedSpecs.has(cacheKey)) return "cache";
@@ -466,6 +473,9 @@ export class NpmControllerLoader {
           }
         }
 
+        // Past every re-check: the package manager is about to run for real,
+        // which is the wait a caller wants reported.
+        await report?.("npm-install");
         await runPackageManager(installRoot, [
           "install",
           "--no-audit",

package/src/controller-loaders/source-bundle-builder.ts

@@ -4,6 +4,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+// Type-only, so this builder stays free of a runtime edge to the dispatcher.
+import type { ControllerWorkReporter } from "../controller-loader.js";
 
 import { readOwnerManifest } from "../bundle/module-manifest.js";
 import { ControllerEnvMissingError } from "./napi-loader.js";
@@ -295,6 +297,7 @@ export async function buildControllerFromSource(
   entryFile: string,
   cacheRoot: string,
   libraries: readonly SiblingLibrary[] = [],
+  report?: ControllerWorkReporter,
 ): Promise<string> {
   const cacheDir = path.join(cacheRoot, CACHE_DIR);
   const externals = externalSpecifiers(libraries);
@@ -309,6 +312,9 @@ export async function buildControllerFromSource(
 
   const inFlight = buildsInFlight.get(entryFile);
   if (inFlight) return inFlight;
+  // Below the content-addressed cache and the in-flight gate: from here esbuild
+  // really runs, which is the only branch worth reporting as a wait.
+  await report?.("source-build");
   const work = build(entryFile, cacheDir, libraries).finally(() =>
     buildsInFlight.delete(entryFile),
   );

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -161,6 +161,11 @@ class ResourceDefinition implements ResourceInstance {
       installRoot: ctx.getInstallRoot(),
       cacheRoot: host.getCacheRoot?.(),
       log: ctx.log,
+      // What resolution reports on its own: the work branches it enters, and
+      // the candidates it skipped. Routed through `ctx.emit` so they carry the
+      // same `<kind>.` namespace as the load events emitted below — a consumer
+      // pairs a wait with its outcome by that namespace.
+      emit: (event) => ctx.emit(event.name, event.payload as Record<string, unknown>),
     });
     // The artifact of the module that DECLARED this kind — a bundled controller
     // ships in its own module's payload, not the consumer's. It owns the pinned
@@ -199,8 +204,7 @@ class ResourceDefinition implements ResourceInstance {
             }
             throw err;
           });
-        await ctx.emit("ControllerLoading", { purl: resolved.purl });
-        const startedAt = Date.now();
+        await ctx.emit("ControllerLoading", { purl: resolved.purl, source: resolved.source });
         const instance = await resolved.importInstance().catch(async (err) => {
           await ctx.emit("ControllerLoadFailed", {
             purl: resolved.purl,
@@ -212,7 +216,7 @@ class ResourceDefinition implements ResourceInstance {
         await ctx.emit("ControllerLoaded", {
           purl: resolved.purl,
           source: resolved.source,
-          durationMs: Date.now() - startedAt,
+          durationMs: resolved.waitedMs(),
         });
       },
     );

package/src/controllers/resource-definition/resource-template-controller.ts

@@ -7,6 +7,7 @@ import type {
 } from "@telorun/sdk";
 import { isCompiledValue } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
+import { celSelfView } from "../../evaluation-context.js";
 
 /** CEL variables that are only bound at call time (request handling, step
  *  chaining, error branches) — never at a template's init(). A persistent
@@ -168,7 +169,13 @@ export function createTemplateController(definition: {
             for (const key of path[1].split(".").slice(1)) cur = cur?.[key];
             return cur;
           }
-          return definingContext.expandWith(value, { self: getSelf() });
+          // CEL cannot read a member off a live instance, and a ref slot holds
+          // one after Phase-5 injection. `celSelfView` replaces each with its
+          // published reading, so `self.<ref>.<field>` answers exactly as
+          // `resources.<name>.<field>` does. The pure-`self.<path>` form above
+          // is navigated directly and still yields the instance itself, which is
+          // what a ref slot passed straight through (`connection:`) needs.
+          return definingContext.expandWith(value, { self: celSelfView(getSelf()) });
         }
         if (isRefSentinel(value)) {
           const source = value.source;
@@ -215,10 +222,10 @@ export function createTemplateController(definition: {
               throw capabilityError(entry, invokeTarget, "invoke", "Telo.Invocable");
             }
             const invokeInputs =
-              definition.inputs != null ? expand(definition.inputs, { self: getSelf(), inputs }) : inputs;
+              definition.inputs != null ? expand(definition.inputs, { self: celSelfView(getSelf()), inputs }) : inputs;
             const raw = await entry.instance.invoke(invokeInputs);
             if (definition.result == null) return raw;
-            return expand(definition.result, { self: getSelf(), result: raw });
+            return expand(definition.result, { self: celSelfView(getSelf()), result: raw });
           },
         }),
 
@@ -239,10 +246,10 @@ export function createTemplateController(definition: {
               throw capabilityError(entry, provideTarget, "provide", "Telo.Invocable");
             }
             const provideInputs: any =
-              definition.inputs != null ? expand(definition.inputs, { self: getSelf() }) : {};
+              definition.inputs != null ? expand(definition.inputs, { self: celSelfView(getSelf()) }) : {};
             const raw = await entry.instance.invoke(provideInputs);
             if (definition.result == null) return raw;
-            return expand(definition.result, { self: getSelf(), result: raw });
+            return expand(definition.result, { self: celSelfView(getSelf()), result: raw });
           },
         }),
 

package/src/dependency-injection.ts

@@ -1,4 +1,4 @@
-import { ResourceInstance, ResourceManifest, RuntimeError, stampRefIdentity } from "@telorun/sdk";
+import { ResourceInstance, ResourceManifest, RuntimeError } from "@telorun/sdk";
 
 /**
  * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal,
@@ -41,12 +41,12 @@ export function injectAtPath(
         `Local reference '${String(ref.name)}' is registered but not initialized yet (deferring to a later init pass)`,
       );
     }
-    // Tag the instance with the kind+name it resolved from, so a consumer that
-    // holds only the bare instance (an invoke-step target) can dispatch it
-    // through the traced chokepoint rather than calling `.invoke()` directly.
-    if (instance && typeof ref.kind === "string" && typeof ref.name === "string") {
-      stampRefIdentity(instance, ref.kind, ref.name);
-    }
+    // The identity is NOT stamped here. It is stamped at `create()`, the single
+    // instance-production site, which is also the only point where an instance
+    // and the context that DECLARED it are both in hand — here the context is
+    // the CONSUMER's, so a declaration site derived at this point would name
+    // whoever referenced the resource. A second write-once stamp competing for
+    // the same property would silently decide that by init order.
     return instance;
   }
 

package/src/evaluation-context.ts

@@ -6,9 +6,11 @@ import {
   isCompiledValue,
   isInvokeError,
   isCancellationError,
+  isSuspension,
   resourceKey,
   UNCANCELLABLE_CONTEXT,
   type EvaluationContext as IEvaluationContext,
+  type SpanOutcome,
   type EmitEvent,
   type InstanceFactory,
   type InvokeContext,
@@ -230,6 +232,121 @@ const completedInstances = new WeakSet<object>();
  * `kind` is already canonical (`<module>.<Kind>`) on that path, so the resolver
  * needs no alias table.
  */
+/**
+ * The last published reading for an instance, by identity.
+ *
+ * CEL reads a resource through its PUBLISHED STATE — that is what
+ * `resources.<name>.<field>` has always meant — and a resource reached through a
+ * ref slot is no different: `self.table.table` and `resources.users.table` name
+ * the same fact and must answer the same way. A ref slot holds the live
+ * instance, which CEL cannot read a member off at all, so this is the table that
+ * makes the two agree.
+ *
+ * Keyed by instance rather than by name because a ref slot carries no name, and
+ * a `with:`-scoped resource has one published reading per scope run. Weak, so
+ * nothing here extends an instance's lifetime, and deliberately one-directional
+ * — an entry is a reading OF an instance, never a way to obtain one.
+ */
+const publishedByInstance = new WeakMap<object, Record<string, unknown>>();
+
+/** The published reading for an instance, or undefined if it has never
+ *  published — a resource that has not been created yet, or a foreign object. */
+export function publishedPropsForInstance(
+  instance: unknown,
+): Record<string, unknown> | undefined {
+  return instance && typeof instance === "object"
+    ? publishedByInstance.get(instance as object)
+    : undefined;
+}
+
+/**
+ * The CEL-facing view of a template's `self`.
+ *
+ * Ref slots hold live instances after Phase-5 injection; each is replaced by its
+ * published reading so a template body can read a scalar off a resource it
+ * references. A slot whose instance has never published is left as it is — a
+ * value CEL will reject on member access, which is the honest outcome rather
+ * than an invented empty object that would make a typo evaluate to null.
+ */
+/**
+ * A memoized `self` view, beside the exact readings it substituted.
+ *
+ * Invalidation is per view, checked against the reading each substituted
+ * instance currently has — `publishedPropsOf` publishes a NEW props object every
+ * time, so identity IS the version. A process-global counter was wrong twice
+ * over: every `invoke()` republishes, so under any concurrency the memo was
+ * defeated and the walk was back on the per-request path it was added for; and
+ * the counter is shared across in-process kernels, so one app's traffic
+ * invalidated another app's views.
+ *
+ * The check is O(substituted slots) — the refs, not the fields — and a view that
+ * substituted nothing has an empty source list and is therefore always valid,
+ * which is the common case.
+ */
+interface SelfView {
+  readonly view: Record<string, unknown>;
+  readonly sources: readonly [object, Record<string, unknown>][];
+}
+
+const selfViews = new WeakMap<object, SelfView>();
+
+function viewIsCurrent(cached: SelfView): boolean {
+  for (const [instance, props] of cached.sources) {
+    if (publishedByInstance.get(instance) !== props) return false;
+  }
+  return true;
+}
+
+export function celSelfView(self: Record<string, unknown>): Record<string, unknown> {
+  // A template's `invoke` expands its body on EVERY dispatch, so this sits on
+  // the per-request path: without the memo a repository rebuilt the whole view
+  // per call.
+  const cached = selfViews.get(self);
+  if (cached && viewIsCurrent(cached)) return cached.view;
+
+  const sources: [object, Record<string, unknown>][] = [];
+  let view: Record<string, unknown> | undefined;
+  for (const [key, value] of Object.entries(self)) {
+    const substituted = celValueView(value, sources);
+    if (substituted === value) continue;
+    view ??= { ...self };
+    view[key] = substituted;
+  }
+  const resolved = view ?? self;
+  selfViews.set(self, { view: resolved, sources });
+  return resolved;
+}
+
+/**
+ * A ref slot holds one instance or a LIST of them (`tables: [!ref a, !ref b]`),
+ * and both are ref slots — so converting only the first would make
+ * `self.tables[0].name` mean something different from `self.table.name`, which
+ * is the inconsistency this rule exists to remove.
+ *
+ * Arrays only: the walk stops at any other object, because a nested plain object
+ * in a manifest is the author's own data and a resource's published reading is
+ * not something to graft into the middle of it.
+ */
+function celValueView(
+  value: unknown,
+  sources: [object, Record<string, unknown>][],
+): unknown {
+  const published = publishedPropsForInstance(value);
+  if (published) {
+    sources.push([value as object, published]);
+    return published;
+  }
+  if (!Array.isArray(value)) return value;
+  let copy: unknown[] | undefined;
+  for (let i = 0; i < value.length; i++) {
+    const substituted = celValueView(value[i], sources);
+    if (substituted === value[i]) continue;
+    copy ??= [...value];
+    copy[i] = substituted;
+  }
+  return copy ?? value;
+}
+
 export async function publishedPropsOf(
   kind: string,
   name: string,
@@ -240,7 +357,7 @@ export async function publishedPropsOf(
     typeof instance.snapshot === "function"
       ? ((await Promise.resolve(instance.snapshot())) as Record<string, unknown> | undefined)
       : undefined;
-  return buildPublishedProps(snap, {
+  const props = buildPublishedProps(snap, {
     kind,
     name,
     module: kind.split(".")[0],
@@ -249,6 +366,8 @@ export async function publishedPropsOf(
     started: startedInstances.has(instance),
     completed: completedInstances.has(instance),
   });
+  publishedByInstance.set(instance, props);
+  return props;
 }
 
 /**
@@ -381,6 +500,19 @@ export class EvaluationContext implements IEvaluationContext {
   /** Resources queued for initialization on this context node. */
   private pendingResources: ResourceManifest[] = [];
 
+  /**
+   * Every manifest ever registered on this node, by name — kept after the
+   * resource has been created, unlike `pendingResources`, which drains.
+   *
+   * A DECLARATION-derived contract (`x-telo-schema-projection-from`) is resolved
+   * when the kernel binds a contract, which happens during create — so the
+   * pending queue has already given the target up by then. The declaration is
+   * what the projection reads (a table's `columns:`), not the instance, so this
+   * is the record it needs. Manifests only, one direction: nothing here yields
+   * an instance, and nothing here extends one's lifetime.
+   */
+  protected readonly declaredManifests = new Map<string, ResourceManifest>();
+
   /** Per-resource dependency names, captured at create() time — BEFORE Phase-5
    *  injection swaps refs for live instances, so the walk sees plain objects and
    *  cannot wander into a controller's (possibly cyclic) object graph. Read only
@@ -523,18 +655,17 @@ export class EvaluationContext implements IEvaluationContext {
       | Record<string, unknown>
       | undefined;
     const kind = entry.resource.kind as string;
-    this.onResourceSnapshotted(
+    const props = buildPublishedProps(snap, {
+      kind,
       name,
-      buildPublishedProps(snap, {
-        kind,
-        name,
-        module: entry.resource.metadata?.module as string | undefined,
-        statusSchema: this.statusSchemaOf(kind),
-        status: reportedStatus.get(entry.instance),
-        started: startedInstances.has(entry.instance),
-        completed: completedInstances.has(entry.instance),
-      }),
-    );
+      module: entry.resource.metadata?.module as string | undefined,
+      statusSchema: this.statusSchemaOf(kind),
+      status: reportedStatus.get(entry.instance),
+      started: startedInstances.has(entry.instance),
+      completed: completedInstances.has(entry.instance),
+    });
+    publishedByInstance.set(entry.instance, props);
+    this.onResourceSnapshotted(name, props);
   }
 
   get context(): Record<string, unknown> {
@@ -580,6 +711,35 @@ export class EvaluationContext implements IEvaluationContext {
       throw new RuntimeError("ERR_DUPLICATE_RESOURCE", `Resource '${name}' is already registered`);
     }
     this.pendingResources.push(resource);
+    this.declaredManifests.set(name, resource);
+  }
+
+  /**
+   * The manifest a name was DECLARED with, resolved scope-local first and then
+   * up the enclosing chain — the order `getInstance` and the CEL `resources`
+   * layering already use, so a declaration lookup and an instance lookup agree
+   * about what a name means inside a scope.
+   *
+   * `alias` routes into an import's exported instances, the one shape a bare
+   * name cannot reach. Returns undefined rather than throwing: a caller here is
+   * typing a contract, and a name that resolves to nothing is reported by the
+   * check that owns that failure, not by a lookup.
+   */
+  resolveDeclaredManifest(name: string, alias?: string): ResourceManifest | undefined {
+    if (alias && alias !== "Self") return this.resolveImportedManifest(alias, name);
+    let node: EvaluationContext | undefined = this;
+    while (node) {
+      const found = node.declaredManifests.get(name);
+      if (found) return found;
+      node = node.parent as EvaluationContext | undefined;
+    }
+    return undefined;
+  }
+
+  /** The manifest half of {@link resolveImportedInstance}. Overridden by
+   *  `ModuleContext`, which is the only node that has imports. */
+  resolveImportedManifest(alias: string, name: string): ResourceManifest | undefined {
+    return undefined;
   }
 
   /**
@@ -625,6 +785,7 @@ export class EvaluationContext implements IEvaluationContext {
       this.emit,
     );
     child.resolveImportedInstance = (alias, name) => this.resolveImportedInstance(alias, name);
+    child.resolveImportedManifest = (alias, name) => this.resolveImportedManifest(alias, name);
     child.kindResolver = (kind) => this.resolveKindSafe(kind);
     return this.spawnChild(child);
   }
@@ -1138,7 +1299,7 @@ export class EvaluationContext implements IEvaluationContext {
     traceId: string | undefined,
     capability: "invoke" | "run" | "provide" | "request",
     phase: "start" | "end",
-    outcome: "ok" | "failed" | "rejected" | "cancelled" | undefined,
+    outcome: SpanOutcome | undefined,
     detail: Record<string, unknown>,
   ): Record<string, unknown> {
     return {
@@ -1192,7 +1353,7 @@ export class EvaluationContext implements IEvaluationContext {
     const rootScope = tracing && parentInvocationId === undefined ? this.traceRootScope() : undefined;
     const span = (
       phase: "start" | "end",
-      outcome: "ok" | "failed" | "rejected" | "cancelled" | undefined,
+      outcome: SpanOutcome | undefined,
       detail: Record<string, unknown>,
     ) =>
       this.tracePayload(
@@ -1259,6 +1420,25 @@ export class EvaluationContext implements IEvaluationContext {
         await this.emit(`${name}.InvokeCancelled`, span("end", "cancelled", { inputs, reason }));
         throw err;
       }
+      // A SUSPENSION passes through untouched, exactly as a cancellation does,
+      // and for a sharper reason. It is not a failure — it is the run leaving —
+      // and the chokepoint is the one swallower that cannot be worked around:
+      // EVERY dispatch between a parking kind and the workflow that owns the run
+      // goes through here, so wrapping it once converts a park into an
+      // `ERR_EXECUTION_FAILED` at every hop. The latch would then catch the
+      // corruption at the boundary, which is a loud failure where nothing was
+      // wrong.
+      //
+      // Reported as its own outcome rather than as a rejection: a parked
+      // invocation neither succeeded nor failed, and a trace that recorded it
+      // as failed would say the run broke every time it waited.
+      if (isSuspension(err)) {
+        await this.emit(
+          `${name}.InvokeParked`,
+          span("end", "parked", { inputs, path: err.path, resource: err.resource }),
+        );
+        throw err;
+      }
       if (isInvokeError(err)) {
         const detail = { inputs, code: err.code, message: err.message, data: err.data };
         await this.emit(`${name}.InvokeRejected`, span("end", "rejected", detail));
@@ -1394,7 +1574,7 @@ export class EvaluationContext implements IEvaluationContext {
     };
     const payload = (
       phase: "start" | "end",
-      outcome: "ok" | "failed" | "rejected" | "cancelled" | undefined,
+      outcome: SpanOutcome | undefined,
       extra: Record<string, unknown> = {},
     ) =>
       this.tracePayload(

package/src/index.ts

@@ -35,6 +35,12 @@ export {
   type ResolvedControllerLayer,
 } from "./bundle/module-artifact.js";
 export { readOwnerManifest, type OwnerManifest } from "./bundle/module-manifest.js";
+export {
+  buildSiblingLibraries,
+  NO_SIBLING_LIBRARIES,
+  type SiblingLibraryMap,
+  type ResolvedSiblingLibrary,
+} from "./controller-loaders/sibling-libraries.js";
 export {
   buildControllerBundle,
   canBuildFromSource,

package/src/instance-declaration.ts

@@ -0,0 +1,36 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+/**
+ * Instance → the manifest it was DECLARED with, recorded at `create()` — the
+ * kernel's single instance-production site, beside where the handle is minted
+ * and the contract is bound.
+ *
+ * A contract typed from a referenced declaration
+ * (`x-telo-schema-projection-from`) is bound AFTER Phase-5 injection has already
+ * replaced the reference in the slot with the live instance, so the reference is
+ * gone by the time the contract needs it. This is what recovers the declaration
+ * behind it — and recovering it is what lets the kernel enforce exactly the
+ * schema the analyzer checked, rather than a reopened one.
+ *
+ * Its own module rather than a second table in `resource-handle.ts`, which
+ * guards an exact export list precisely so a new direction gets looked at: the
+ * rule there is that a HANDLE must never become someone else's live instance,
+ * and this is the unrelated instance→declaration direction. Weak and one-way —
+ * a manifest is obtainable FROM an instance, never an instance from a manifest —
+ * so nothing here extends a lifetime or hands out a reference to live state.
+ */
+const declarations = new WeakMap<object, ResourceManifest>();
+
+/** Record what a live instance was declared with. First record wins, matching
+ *  the handle rule: a `base:` child IS its parent instance, and the parent's
+ *  declaration is the one that produced it. */
+export function recordInstanceDeclaration(instance: object, manifest: ResourceManifest): void {
+  if (!declarations.has(instance)) declarations.set(instance, manifest);
+}
+
+/** The manifest a live instance was declared with, if it is one of ours. */
+export function declarationOfInstance(instance: unknown): ResourceManifest | undefined {
+  return instance && typeof instance === "object"
+    ? declarations.get(instance as object)
+    : undefined;
+}

package/src/invocation-contract-binding.ts

@@ -1,10 +1,14 @@
 import {
   type ContractDirection,
+  type ProjectionScope,
   declaredScalarPaths,
   type DeclaredScalarForm,
   type DeclaredScalarPath,
   defaultBearingPaths,
   effectiveContractField,
+  describeProjectionFailure,
+  resolveSchemaProjections,
+  type ProjectionFailure,
   type DefResolver,
   withLiveValuesSkipped,
 } from "@telorun/analyzer";
@@ -13,6 +17,7 @@ import {
   ERR_CONTRACT_UNRESOLVABLE,
   ERR_INPUT_INVALID,
   ERR_OUTPUT_INVALID,
+  ERR_SCHEMA_PROJECTION_UNRESOLVED,
   InvokeError,
 } from "@telorun/sdk";
 
@@ -120,6 +125,19 @@ export function resolveBoundContract(
   definition: ResourceDefinition | undefined,
   resolveDef: DefResolver,
   factory: ContractValidatorFactory,
+  /**
+   * Resolves a DECLARATION-derived slot (`x-telo-schema-projection-from`) to the
+   * shape the referenced declaration projects to.
+   *
+   * The kernel resolves it for the same reason the analyzer does, and it must be
+   * the SAME resolution: a projected contract enforced statically and not at
+   * dispatch is a contract with a hole exactly where a value is computed rather
+   * than written — `telo check` rejects a misspelled column in a literal and the
+   * identical key arriving from a CEL expression reaches the database. Omitted
+   * only by callers with no scope to resolve against, where the annotated node
+   * stays as it was.
+   */
+  projections?: ProjectionScope,
 ): BoundContract | undefined {
   const own = (manifest as unknown as Record<string, unknown>)[direction];
   const declared =
@@ -146,13 +164,43 @@ export function resolveBoundContract(
           `The type is not registered, so the contract cannot be enforced.`,
       );
     }
-    const stripped = withLiveValuesSkipped(schema, factory.resolveRef);
+    let projected = schema;
+    if (projections) {
+      const failures: ProjectionFailure[] = [];
+      projected = resolveSchemaProjections(
+        schema,
+        manifest as unknown as Record<string, any>,
+        projections,
+        failures,
+      ) as Record<string, any>;
+      if (failures.length > 0) {
+        // A slot that opted into a projection and got none is a DEFECT, not a
+        // default: leaving it means the contract silently reopens to the slot's
+        // own schema, which for a projected slot constrains nothing — the exact
+        // reopening this mechanism exists to prevent. The analyzer reports the
+        // same set, but only for the entry's own modules, so a dependency's
+        // consumer slot would otherwise be unreported at BOTH ends. Same rule as
+        // `ERR_CONTRACT_UNRESOLVABLE` above, for the same reason.
+        throw new InvokeError(
+          ERR_SCHEMA_PROJECTION_UNRESOLVED,
+          `declared \`${direction}\` could not be projected: ` +
+            failures.map(describeProjectionFailure).join(" ") +
+            ` The slot declares 'x-telo-schema-projection-from', so leaving it unresolved ` +
+            `would enforce nothing where it promises a declared shape.`,
+        );
+      }
+    }
+    const stripped = withLiveValuesSkipped(projected, factory.resolveRef);
     paths = defaultBearingPaths(stripped, factory.resolveRef);
     scalars = declaredScalarPaths(stripped, factory.resolveRef);
     // Compile by NAME whenever the declaration is one, so the type's CEL
     // `rules:` are composed in — including when a stream had to be stripped, in
     // which case the stream-bearing properties are dropped from the schema the
     // named validator sees rather than the reference being abandoned.
+    // A named type compiles BY NAME so its CEL `rules:` compose in — but only
+    // while the schema is untouched. Stripping a stream or resolving a
+    // projection both produce a different schema, so both take the
+    // rules-preserving path rather than the bare name.
     compiled = !isNamedTypeReference(declared)
       ? factory(stripped)
       : stripped === schema