@telorun/sdk 0.50.0 → 0.54.0

package/dist/dispatch-invoke-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-invoke-ref.d.ts","sourceRoot":"","sources":["../src/dispatch-invoke-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,OAAO,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,OAAO,EACf,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,MAAM,GACrB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAsBlF"}
+{"version":3,"file":"dispatch-invoke-ref.d.ts","sourceRoot":"","sources":["../src/dispatch-invoke-ref.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,OAAO,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,OAAO,EACf,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,MAAM,MAAM,GACrB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAgBlF"}

package/dist/dispatch-invoke-ref.js

@@ -1,3 +1,4 @@
+import { resolveRefInstance } from "./resolve-ref-instance.js";
 import { getRefIdentity } from "./resource-instance.js";
 /**
  * Resolve a decorator's `invoke:` field to a live invocable and return a thunk
@@ -11,22 +12,16 @@ import { getRefIdentity } from "./resource-instance.js";
  * invocation context applies unchanged.
  */
 export function resolveInvocableDispatcher(field, ctx, describe) {
-    if (field && typeof field.invoke === "function") {
-        const instance = field;
-        const id = getRefIdentity(field);
-        return (inputs, invokeCtx) => id
-            ? ctx.invokeResolved(id.kind, id.name, instance, inputs, invokeCtx)
-            : instance.invoke(inputs, invokeCtx);
+    const target = resolveRefInstance(field, ctx, isInvocableInstance, () => `${describe()}: 'invoke'`, "telo#Invocable");
+    // Dispatch through the traced chokepoint needs the target's kind+name: from
+    // the `!ref` identity the kernel stamped at injection, else from the raw ref.
+    const id = getRefIdentity(target) ?? field;
+    if (!id || typeof id.kind !== "string" || typeof id.name !== "string") {
+        return (inputs, invokeCtx) => target.invoke(inputs, invokeCtx);
     }
-    const ref = field;
-    if (!ref || typeof ref.name !== "string") {
-        throw new Error(`${describe()}: 'invoke' must reference an invocable.`);
-    }
-    const resolved = (ref.alias && ref.alias !== "Self"
-        ? ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name)
-        : ctx.moduleContext.getInstance(ref.name));
-    if (!resolved || typeof resolved.invoke !== "function") {
-        throw new Error(`${describe()}: 'invoke' reference '${ref.name}' did not resolve to an invocable.`);
-    }
-    return (inputs, invokeCtx) => ctx.invokeResolved(ref.kind, ref.name, resolved, inputs, invokeCtx);
+    const { kind, name } = id;
+    return (inputs, invokeCtx) => ctx.invokeResolved(kind, name, target, inputs, invokeCtx);
+}
+function isInvocableInstance(value) {
+    return typeof value?.invoke === "function";
 }

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export * from "./capabilities/provider.js";
 export * from "./capabilities/runnable.js";
 export * from "./context-provider.js";
 export * from "./duration.js";
+export * from "./json-value.js";
+export * from "./resolve-ref-instance.js";
 export * from "./controller-context.js";
 export * from "./controller-policy.js";
 export * from "./evaluation-context.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -9,6 +9,8 @@ export * from "./capabilities/provider.js";
 export * from "./capabilities/runnable.js";
 export * from "./context-provider.js";
 export * from "./duration.js";
+export * from "./json-value.js";
+export * from "./resolve-ref-instance.js";
 export * from "./controller-context.js";
 export * from "./controller-policy.js";
 export * from "./evaluation-context.js";

package/dist/json-value.d.ts

@@ -0,0 +1,20 @@
+/**
+ * JSON encoding for values that cross a persistence boundary.
+ *
+ * `JSON.stringify` THROWS on a BigInt, and CEL integers surface as BigInt in
+ * this runtime — so any controller that persists a result computed in CEL
+ * (`{ charged: 500 }` from a `Run.Sequence` output) hits it. A store that lets
+ * that throw escape is worse than one that never persisted: the caller sees an
+ * opaque TypeError, and a decorator built on the store can mistake it for the
+ * body having failed.
+ *
+ * BigInt is encoded as a tagged object rather than a plain string or a Number:
+ * a string would come back a different type than went in, and Number is lossy
+ * past 2^53. A replayed value must equal the freshly-produced one, or
+ * at-most-once execution silently changes its answer on the second call.
+ */
+/** Serialize a value to JSON text, preserving BigInt exactly. */
+export declare function encodeJsonValue(value: unknown): string;
+/** Inverse of {@link encodeJsonValue}; BigInt values are restored as BigInt. */
+export declare function decodeJsonValue(text: string): unknown;
+//# sourceMappingURL=json-value.d.ts.map

package/dist/json-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-value.d.ts","sourceRoot":"","sources":["../src/json-value.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAItD;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/json-value.js

@@ -0,0 +1,31 @@
+/**
+ * JSON encoding for values that cross a persistence boundary.
+ *
+ * `JSON.stringify` THROWS on a BigInt, and CEL integers surface as BigInt in
+ * this runtime — so any controller that persists a result computed in CEL
+ * (`{ charged: 500 }` from a `Run.Sequence` output) hits it. A store that lets
+ * that throw escape is worse than one that never persisted: the caller sees an
+ * opaque TypeError, and a decorator built on the store can mistake it for the
+ * body having failed.
+ *
+ * BigInt is encoded as a tagged object rather than a plain string or a Number:
+ * a string would come back a different type than went in, and Number is lossy
+ * past 2^53. A replayed value must equal the freshly-produced one, or
+ * at-most-once execution silently changes its answer on the second call.
+ */
+const BIGINT_TAG = "$bigint";
+function isTaggedBigInt(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value[BIGINT_TAG] === "string" &&
+        Object.keys(value).length === 1);
+}
+/** Serialize a value to JSON text, preserving BigInt exactly. */
+export function encodeJsonValue(value) {
+    return JSON.stringify(value ?? null, (_k, v) => typeof v === "bigint" ? { [BIGINT_TAG]: v.toString() } : v);
+}
+/** Inverse of {@link encodeJsonValue}; BigInt values are restored as BigInt. */
+export function decodeJsonValue(text) {
+    return JSON.parse(text, (_k, v) => (isTaggedBigInt(v) ? BigInt(v[BIGINT_TAG]) : v));
+}

package/dist/resolve-ref-instance.d.ts

@@ -0,0 +1,39 @@
+import type { ModuleContext } from "./module-context.js";
+/** The slice of `ResourceContext` needed to resolve a reference. */
+export interface RefResolveContext {
+    readonly moduleContext: ModuleContext;
+}
+/**
+ * Resolve a `!ref` config field to a live instance of `T`. Controllers reach
+ * this as `ctx.resolveRef(value, guard, describe, expects)`; the standalone form
+ * is for callers holding only a `{ moduleContext }` slice rather than a full
+ * `ResourceContext`.
+ *
+ * Phase 5 injection normally replaces the slot with the live `ResourceInstance`
+ * before `init()` — local and cross-module refs alike, since injection resolves
+ * an aliased ref through the import's export table (and defers, rather than
+ * leaving a raw ref, when the import hasn't published its exports yet). So the
+ * common path here is the guard short-circuit.
+ *
+ * A raw {@link KindRef} still reaches a controller where injection does not
+ * reach the slot: a kind whose definition yields no field map, or a ref the
+ * controller obtained itself via `ctx.ensureKindRef`. Both are gaps worth
+ * closing in the kernel — until they are, both shapes must be accepted here, and
+ * an aliased ref routes through the import's exported scope because a bare local
+ * lookup would miss it.
+ *
+ * `guard` decides what counts as the right kind of instance — a duck-type check
+ * on the methods the caller will actually invoke, so a mis-wired ref fails with a
+ * clear message here rather than as `undefined is not a function` later.
+ * `describe` labels the owning resource and slot; `expects` names the contract
+ * the slot wants — the slot's own `x-telo-ref` string (`std/cache#Store`) — so
+ * the message says what was missing, not just that something was.
+ *
+ * @example
+ * const store = resolveRefInstance(
+ *   this.resource.store, this.ctx, isKvStore,
+ *   () => `Idempotency.Once "${name}": 'store'`, "std/kv-store#Store",
+ * );
+ */
+export declare function resolveRefInstance<T>(value: unknown, ctx: RefResolveContext, guard: (candidate: unknown) => candidate is T, describe: () => string, expects?: string): T;
+//# sourceMappingURL=resolve-ref-instance.d.ts.map

package/dist/resolve-ref-instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-ref-instance.d.ts","sourceRoot":"","sources":["../src/resolve-ref-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,SAAS,IAAI,CAAC,EAC7C,QAAQ,EAAE,MAAM,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAiCH"}

package/dist/resolve-ref-instance.js

@@ -0,0 +1,57 @@
+import { RuntimeError } from "./types.js";
+/**
+ * Resolve a `!ref` config field to a live instance of `T`. Controllers reach
+ * this as `ctx.resolveRef(value, guard, describe, expects)`; the standalone form
+ * is for callers holding only a `{ moduleContext }` slice rather than a full
+ * `ResourceContext`.
+ *
+ * Phase 5 injection normally replaces the slot with the live `ResourceInstance`
+ * before `init()` — local and cross-module refs alike, since injection resolves
+ * an aliased ref through the import's export table (and defers, rather than
+ * leaving a raw ref, when the import hasn't published its exports yet). So the
+ * common path here is the guard short-circuit.
+ *
+ * A raw {@link KindRef} still reaches a controller where injection does not
+ * reach the slot: a kind whose definition yields no field map, or a ref the
+ * controller obtained itself via `ctx.ensureKindRef`. Both are gaps worth
+ * closing in the kernel — until they are, both shapes must be accepted here, and
+ * an aliased ref routes through the import's exported scope because a bare local
+ * lookup would miss it.
+ *
+ * `guard` decides what counts as the right kind of instance — a duck-type check
+ * on the methods the caller will actually invoke, so a mis-wired ref fails with a
+ * clear message here rather than as `undefined is not a function` later.
+ * `describe` labels the owning resource and slot; `expects` names the contract
+ * the slot wants — the slot's own `x-telo-ref` string (`std/cache#Store`) — so
+ * the message says what was missing, not just that something was.
+ *
+ * @example
+ * const store = resolveRefInstance(
+ *   this.resource.store, this.ctx, isKvStore,
+ *   () => `Idempotency.Once "${name}": 'store'`, "std/kv-store#Store",
+ * );
+ */
+export function resolveRefInstance(value, ctx, guard, describe, expects) {
+    // Phase-5-injected: already the instance.
+    if (guard(value))
+        return value;
+    const target = expects ? `resource satisfying \`${expects}\`` : "resource";
+    if (value === undefined || value === null) {
+        throw new RuntimeError("ERR_REF_REQUIRED", `${describe()} is required — reference a ${target}.`);
+    }
+    const ref = value;
+    if (typeof ref.name !== "string") {
+        throw new RuntimeError("ERR_REF_UNRESOLVED", `${describe()} must be a \`!ref\` to a ${target}.`);
+    }
+    // `Self` names the declaring library's own scope, so it resolves locally —
+    // it is an alias that crosses no import boundary.
+    const instance = ref.alias && ref.alias !== "Self"
+        ? ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name)
+        : ctx.moduleContext.getInstance(ref.name);
+    if (!guard(instance)) {
+        const label = ref.alias ? `${ref.alias}.${ref.name}` : ref.name;
+        throw new RuntimeError("ERR_REF_UNRESOLVED", `${describe()} reference '${label}' did not resolve to a ${target}` +
+            `${instance === undefined ? " (nothing is registered under that name)" : ""}.`);
+    }
+    return instance;
+}

package/dist/resource-context.d.ts

@@ -5,6 +5,7 @@ import type { LoggingHost } from "./log-sink.js";
 import { ControllerPolicy } from "./controller-policy.js";
 import { EvaluationContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
+import type { KindRef } from "./ref.js";
 import { ResourceInstance } from "./resource-instance.js";
 import { ResourceManifest } from "./resource-manifest.js";
 import { RuntimeResource } from "./runtime-resource.js";
@@ -71,10 +72,33 @@ export interface ResourceContext extends ControllerContext {
     spawnChildContext(): EvaluationContext;
     transientChild(context: Record<string, any>): EvaluationContext;
     withManifests<T>(manifests: any[], fn: () => T): T;
+    /**
+     * Normalize a nested slot value to a {@link KindRef}. The value is an inline
+     * definition (`{ kind, …config }`), an already-normalized `{ kind, name }`
+     * ref, or a `!ref` sentinel. An inline definition is *registered* into this
+     * module's scope first — minting `resourceName` (or a generated one) as its
+     * name — so the returned ref always points at a resource the kernel knows.
+     *
+     * The inverse of {@link resolveRef}: this goes slot value → ref, that goes
+     * ref → live instance. Controllers that dispatch through
+     * `invokeResolved(kind, name, …)` want the ref, so the invocation keeps its
+     * identity for tracing and error wrapping.
+     */
+    ensureKindRef(value: any, resourceName?: string): KindRef;
+    /** @deprecated Renamed to {@link ensureKindRef} — it produces a reference
+     *  (registering an inline definition on the way), it does not resolve one. */
     resolveChildren(resource: any, resourceName?: string): {
         kind: string;
         name: string;
     };
+    /**
+     * Resolve a `!ref` config field to a live instance of `T`. See
+     * {@link resolveRefInstance} — this is the same resolution, reached through
+     * the context a controller already holds. `expects` names the contract the
+     * slot wants — its `x-telo-ref` string (`std/cache#Store`) — so a mis-wire
+     * says what was missing.
+     */
+    resolveRef<T>(value: unknown, guard: (candidate: unknown) => candidate is T, describe: () => string, expects?: string): T;
     validateSchema(value: any, schema: any): void;
     createSchemaValidator(schema: any): DataValidator;
     registerSchema(name: string, schema: object): void;

package/dist/resource-context.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.50.0",
+  "version": "0.54.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/dispatch-invoke-ref.ts

@@ -1,6 +1,8 @@
 import type { InvokeContext } from "./cancellation.js";
 import type { Invocable } from "./capabilities/invokable.js";
 import type { ModuleContext } from "./module-context.js";
+import type { KindRef } from "./ref.js";
+import { resolveRefInstance } from "./resolve-ref-instance.js";
 import { getRefIdentity, type ResourceInstance } from "./resource-instance.js";
 
 /** The context a decorator kind composes to dispatch its wrapped target. */
@@ -31,25 +33,23 @@ export function resolveInvocableDispatcher(
   ctx: DispatchContext,
   describe: () => string,
 ): (inputs: Record<string, unknown>, invokeCtx?: InvokeContext) => Promise<unknown> {
-  if (field && typeof (field as Invocable).invoke === "function") {
-    const instance = field as ResourceInstance & Invocable;
-    const id = getRefIdentity(field as object);
-    return (inputs, invokeCtx) =>
-      id
-        ? ctx.invokeResolved(id.kind, id.name, instance, inputs, invokeCtx)
-        : instance.invoke(inputs, invokeCtx);
+  const target = resolveRefInstance(
+    field,
+    ctx,
+    isInvocableInstance,
+    () => `${describe()}: 'invoke'`,
+    "telo#Invocable",
+  );
+  // Dispatch through the traced chokepoint needs the target's kind+name: from
+  // the `!ref` identity the kernel stamped at injection, else from the raw ref.
+  const id = getRefIdentity(target as object) ?? (field as Partial<KindRef> | undefined);
+  if (!id || typeof id.kind !== "string" || typeof id.name !== "string") {
+    return (inputs, invokeCtx) => target.invoke(inputs, invokeCtx);
   }
-  const ref = field as { kind: string; name: string; alias?: string } | undefined;
-  if (!ref || typeof ref.name !== "string") {
-    throw new Error(`${describe()}: 'invoke' must reference an invocable.`);
-  }
-  const resolved = (
-    ref.alias && ref.alias !== "Self"
-      ? ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name)
-      : ctx.moduleContext.getInstance(ref.name)
-  ) as ResourceInstance | undefined;
-  if (!resolved || typeof resolved.invoke !== "function") {
-    throw new Error(`${describe()}: 'invoke' reference '${ref.name}' did not resolve to an invocable.`);
-  }
-  return (inputs, invokeCtx) => ctx.invokeResolved(ref.kind, ref.name, resolved, inputs, invokeCtx);
+  const { kind, name } = id;
+  return (inputs, invokeCtx) => ctx.invokeResolved(kind, name, target, inputs, invokeCtx);
+}
+
+function isInvocableInstance(value: unknown): value is ResourceInstance & Invocable {
+  return typeof (value as Invocable | undefined)?.invoke === "function";
 }

package/src/index.ts

@@ -9,6 +9,8 @@ export * from "./capabilities/provider.js";
 export * from "./capabilities/runnable.js";
 export * from "./context-provider.js";
 export * from "./duration.js";
+export * from "./json-value.js";
+export * from "./resolve-ref-instance.js";
 export * from "./controller-context.js";
 export * from "./controller-policy.js";
 export * from "./evaluation-context.js";

package/src/json-value.ts

@@ -0,0 +1,43 @@
+/**
+ * JSON encoding for values that cross a persistence boundary.
+ *
+ * `JSON.stringify` THROWS on a BigInt, and CEL integers surface as BigInt in
+ * this runtime — so any controller that persists a result computed in CEL
+ * (`{ charged: 500 }` from a `Run.Sequence` output) hits it. A store that lets
+ * that throw escape is worse than one that never persisted: the caller sees an
+ * opaque TypeError, and a decorator built on the store can mistake it for the
+ * body having failed.
+ *
+ * BigInt is encoded as a tagged object rather than a plain string or a Number:
+ * a string would come back a different type than went in, and Number is lossy
+ * past 2^53. A replayed value must equal the freshly-produced one, or
+ * at-most-once execution silently changes its answer on the second call.
+ */
+
+const BIGINT_TAG = "$bigint";
+
+interface TaggedBigInt {
+  [BIGINT_TAG]: string;
+}
+
+function isTaggedBigInt(value: unknown): value is TaggedBigInt {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    typeof (value as TaggedBigInt)[BIGINT_TAG] === "string" &&
+    Object.keys(value).length === 1
+  );
+}
+
+/** Serialize a value to JSON text, preserving BigInt exactly. */
+export function encodeJsonValue(value: unknown): string {
+  return JSON.stringify(value ?? null, (_k, v) =>
+    typeof v === "bigint" ? { [BIGINT_TAG]: v.toString() } : v,
+  );
+}
+
+/** Inverse of {@link encodeJsonValue}; BigInt values are restored as BigInt. */
+export function decodeJsonValue(text: string): unknown {
+  return JSON.parse(text, (_k, v) => (isTaggedBigInt(v) ? BigInt(v[BIGINT_TAG]) : v));
+}

package/src/resolve-ref-instance.ts

@@ -0,0 +1,81 @@
+import type { ModuleContext } from "./module-context.js";
+import type { KindRef } from "./ref.js";
+import { RuntimeError } from "./types.js";
+
+/** The slice of `ResourceContext` needed to resolve a reference. */
+export interface RefResolveContext {
+  readonly moduleContext: ModuleContext;
+}
+
+/**
+ * Resolve a `!ref` config field to a live instance of `T`. Controllers reach
+ * this as `ctx.resolveRef(value, guard, describe, expects)`; the standalone form
+ * is for callers holding only a `{ moduleContext }` slice rather than a full
+ * `ResourceContext`.
+ *
+ * Phase 5 injection normally replaces the slot with the live `ResourceInstance`
+ * before `init()` — local and cross-module refs alike, since injection resolves
+ * an aliased ref through the import's export table (and defers, rather than
+ * leaving a raw ref, when the import hasn't published its exports yet). So the
+ * common path here is the guard short-circuit.
+ *
+ * A raw {@link KindRef} still reaches a controller where injection does not
+ * reach the slot: a kind whose definition yields no field map, or a ref the
+ * controller obtained itself via `ctx.ensureKindRef`. Both are gaps worth
+ * closing in the kernel — until they are, both shapes must be accepted here, and
+ * an aliased ref routes through the import's exported scope because a bare local
+ * lookup would miss it.
+ *
+ * `guard` decides what counts as the right kind of instance — a duck-type check
+ * on the methods the caller will actually invoke, so a mis-wired ref fails with a
+ * clear message here rather than as `undefined is not a function` later.
+ * `describe` labels the owning resource and slot; `expects` names the contract
+ * the slot wants — the slot's own `x-telo-ref` string (`std/cache#Store`) — so
+ * the message says what was missing, not just that something was.
+ *
+ * @example
+ * const store = resolveRefInstance(
+ *   this.resource.store, this.ctx, isKvStore,
+ *   () => `Idempotency.Once "${name}": 'store'`, "std/kv-store#Store",
+ * );
+ */
+export function resolveRefInstance<T>(
+  value: unknown,
+  ctx: RefResolveContext,
+  guard: (candidate: unknown) => candidate is T,
+  describe: () => string,
+  expects?: string,
+): T {
+  // Phase-5-injected: already the instance.
+  if (guard(value)) return value;
+
+  const target = expects ? `resource satisfying \`${expects}\`` : "resource";
+  if (value === undefined || value === null) {
+    throw new RuntimeError("ERR_REF_REQUIRED", `${describe()} is required — reference a ${target}.`);
+  }
+
+  const ref = value as Partial<KindRef<T>>;
+  if (typeof ref.name !== "string") {
+    throw new RuntimeError(
+      "ERR_REF_UNRESOLVED",
+      `${describe()} must be a \`!ref\` to a ${target}.`,
+    );
+  }
+
+  // `Self` names the declaring library's own scope, so it resolves locally —
+  // it is an alias that crosses no import boundary.
+  const instance =
+    ref.alias && ref.alias !== "Self"
+      ? ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name)
+      : ctx.moduleContext.getInstance(ref.name);
+
+  if (!guard(instance)) {
+    const label = ref.alias ? `${ref.alias}.${ref.name}` : ref.name;
+    throw new RuntimeError(
+      "ERR_REF_UNRESOLVED",
+      `${describe()} reference '${label}' did not resolve to a ${target}` +
+        `${instance === undefined ? " (nothing is registered under that name)" : ""}.`,
+    );
+  }
+  return instance;
+}

package/src/resource-context.ts

@@ -5,6 +5,7 @@ import type { LoggingHost } from "./log-sink.js";
 import { ControllerPolicy } from "./controller-policy.js";
 import { EvaluationContext } from "./evaluation-context.js";
 import { ModuleContext } from "./module-context.js";
+import type { KindRef } from "./ref.js";
 import { ResourceInstance } from "./resource-instance.js";
 import { ResourceManifest } from "./resource-manifest.js";
 import { RuntimeResource } from "./runtime-resource.js";
@@ -86,7 +87,35 @@ export interface ResourceContext extends ControllerContext {
   spawnChildContext(): EvaluationContext;
   transientChild(context: Record<string, any>): EvaluationContext;
   withManifests<T>(manifests: any[], fn: () => T): T;
+  /**
+   * Normalize a nested slot value to a {@link KindRef}. The value is an inline
+   * definition (`{ kind, …config }`), an already-normalized `{ kind, name }`
+   * ref, or a `!ref` sentinel. An inline definition is *registered* into this
+   * module's scope first — minting `resourceName` (or a generated one) as its
+   * name — so the returned ref always points at a resource the kernel knows.
+   *
+   * The inverse of {@link resolveRef}: this goes slot value → ref, that goes
+   * ref → live instance. Controllers that dispatch through
+   * `invokeResolved(kind, name, …)` want the ref, so the invocation keeps its
+   * identity for tracing and error wrapping.
+   */
+  ensureKindRef(value: any, resourceName?: string): KindRef;
+  /** @deprecated Renamed to {@link ensureKindRef} — it produces a reference
+   *  (registering an inline definition on the way), it does not resolve one. */
   resolveChildren(resource: any, resourceName?: string): { kind: string; name: string };
+  /**
+   * Resolve a `!ref` config field to a live instance of `T`. See
+   * {@link resolveRefInstance} — this is the same resolution, reached through
+   * the context a controller already holds. `expects` names the contract the
+   * slot wants — its `x-telo-ref` string (`std/cache#Store`) — so a mis-wire
+   * says what was missing.
+   */
+  resolveRef<T>(
+    value: unknown,
+    guard: (candidate: unknown) => candidate is T,
+    describe: () => string,
+    expects?: string,
+  ): T;
   validateSchema(value: any, schema: any): void;
   createSchemaValidator(schema: any): DataValidator;
   registerSchema(name: string, schema: object): void;