@telorun/kernel 0.78.0 → 0.80.0

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

@@ -10,6 +10,7 @@ export {
   writeManifestCache,
 } from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
+export { WORKSPACE_FILENAME, findWorkspaceRoot, realPath } from "./workspace-marker.js";
 export type { Transport } from "./transports/transport.js";
 export { RegistryTransport } from "./transports/registry-transport.js";
 export { OciTransport } from "./transports/oci/oci-transport.js";
@@ -35,6 +36,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