@telorun/sdk 0.65.0 → 0.68.0

package/dist/cancellation.d.ts

@@ -1,3 +1,4 @@
+import type { ResourceHandle } from "./resource-instance.js";
 /**
  * Cooperative invocation cancellation — the standard source/token split.
  *
@@ -29,6 +30,21 @@ export interface CancellationToken {
     /** Throw `ERR_INVOKE_CANCELLED` if cancelled; otherwise no-op. */
     throwIfCancelled(): void;
 }
+/**
+ * One open execution zone — see `kernel/specs/execution-zones.md`. Three
+ * identities and nothing else: no provider-private payload rides here (a
+ * provider keys its own map on the entry), so the contract stays serializable
+ * across the ABI and another module's open transaction is never readable from
+ * the ambient stack.
+ */
+export interface ZoneEntry {
+    /** Canonical `<module>.<Kind>` of the providing kind — what a requirement names. */
+    readonly kind: string;
+    readonly provider: ResourceHandle;
+    /** The instance the provider's correlation-key pointer resolved to.
+     *  Absent = uncorrelated zone. */
+    readonly key?: ResourceHandle;
+}
 /**
  * The out-of-band second argument every `invoke()` receives. Intentionally an
  * extensible object rather than a bare token so future per-invoke concerns
@@ -48,7 +64,18 @@ export interface InvokeContext {
      *  trace the way OpenTelemetry's `trace_id` does (an exporter maps it directly),
      *  independent of the parent chain. */
     readonly traceId?: string;
+    /** Zones open around this invocation, outermost first. Absent = none. */
+    readonly zones?: readonly ZoneEntry[];
 }
+/**
+ * The ONE way to build a context derived from another. A fresh object literal
+ * at a rebuild site silently drops every field it does not restate — with
+ * `zones` that means the stack survives with tracing off and vanishes under
+ * `--debug`, a safety property flipping on a debug flag. Every context-rebuild
+ * site (the kernel's tracing branches, span derivation) goes through here so a
+ * field added to {@link InvokeContext} propagates without each site opting in.
+ */
+export declare function deriveContext(base: InvokeContext, overrides: Partial<InvokeContext>): InvokeContext;
 /** Terminal status of a span — maps to OpenTelemetry span status. */
 export type SpanOutcome = "ok" | "failed" | "rejected" | "cancelled";
 /** Options for {@link ResourceContext.openSpan}. */

package/dist/cancellation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;yDACqD;IACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;2CACuC;IACvC,WAAW,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxE,kEAAkE;IAClE,gBAAgB,IAAI,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC;;4CAEwC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;mFAC+E;IAC/E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;2CAGuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAErE,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B;0DACsD;IACtD,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;kDAC8C;IAC9C,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,qEAAqE;IACrE,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC;4EACwE;IACxE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uCAAuC;IACvC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;mEAG+D;IAC/D,OAAO,IAAI,IAAI,CAAC;CACjB;AAiFD,wBAAgB,wBAAwB,IAAI,kBAAkB,CAE7D;AAMD;2EAC2E;AAC3E,eAAO,MAAM,eAAe,EAAE,iBAU7B,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,EAAE,aAAiD,CAAC;AAEtF,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMzD"}
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"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"}

package/dist/cancellation.js

@@ -16,6 +16,17 @@ import { InvokeError } from "./invoke-error.js";
  * is the primitive; `cancelAfter(ms)` is sugar over it.
  */
 export const ERR_INVOKE_CANCELLED = "ERR_INVOKE_CANCELLED";
+/**
+ * The ONE way to build a context derived from another. A fresh object literal
+ * at a rebuild site silently drops every field it does not restate — with
+ * `zones` that means the stack survives with tracing off and vanishes under
+ * `--debug`, a safety property flipping on a debug flag. Every context-rebuild
+ * site (the kernel's tracing branches, span derivation) goes through here so a
+ * field added to {@link InvokeContext} propagates without each site opting in.
+ */
+export function deriveContext(base, overrides) {
+    return { ...base, ...overrides };
+}
 class CancellationTokenSource {
     #controller = new AbortController();
     #cancelled = false;

package/dist/resource-context.d.ts

@@ -1,4 +1,5 @@
-import type { CancellationSource, InvokeContext, OpenSpan, OpenSpanOptions } from "./cancellation.js";
+import type { CancellationSource, InvokeContext, OpenSpan, OpenSpanOptions, ZoneEntry } from "./cancellation.js";
+import type { ResourceHandle } from "./resource-instance.js";
 import { ControllerContext } from "./controller-context.js";
 import type { Logger } from "./logger.js";
 import type { LoggingHost } from "./log-sink.js";
@@ -36,6 +37,20 @@ export declare class NoopValidator implements DataValidator {
 export type ParsedArgs = Partial<Record<string, string | boolean | string[]>> & {
     _: string[];
 };
+/**
+ * Per-call options for a by-name dispatch.
+ *
+ * A bag rather than a positional context parameter because this slot already
+ * carried one meaning — `retry`, consumed by the step leaf — and
+ * `ResourceContext` satisfies `InvokeStepContext` structurally, so a positional
+ * `InvokeContext` here silently receives a step's retry options instead.
+ */
+export interface InvokeByNameOptions {
+    /** Seeds the invocation context, replacing the ambient. */
+    ctx?: InvokeContext;
+    /** Retry policy, read by `executeInvokeStep`. */
+    retry?: unknown;
+}
 export interface ResourceContext extends ControllerContext {
     readonly args: ParsedArgs;
     /** The id prefix of the context this resource was created in (the creating
@@ -72,6 +87,48 @@ export interface ResourceContext extends ControllerContext {
      *  lambda budget). Pass `source.context` into `invokeResolved` to scope an
      *  invocation tree to it. */
     createCancellationSource(): CancellationSource;
+    /** This resource's own handle. Its `ref` is how a controller names itself in a
+     *  diagnostic; its id is what the kernel stamps as a zone's `provider`. */
+    readonly self: ResourceHandle;
+    /**
+     * Open the zone declared by this resource's `slot` (`x-telo-provides-zone`)
+     * around `fn`. Kind = the declaring kind; correlation key = the annotation's
+     * pointer, resolved against this resource's own manifest. Throws if `slot`
+     * carries no such annotation — a controller and its schema disagreeing is a
+     * defect, not a fallback.
+     *
+     * A scope function rather than a push/pop pair: push/pop cannot be honest
+     * across async boundaries. `fn` receives the derived context to thread into
+     * `invokeResolved` for the body — the discipline cancellation already has —
+     * and the minted entry, which a provider with private state (an open
+     * transaction, a journal) keys its own map on.
+     *
+     * `base` is the context the new zone is layered onto. Pass the
+     * {@link InvokeContext} the controller was handed, exactly as
+     * {@link requireZone} takes one: a runtime with no ambient store (the Rust
+     * kernel passes its context explicitly and has none) can only implement the
+     * provider half through this parameter, so omitting it would make the surface
+     * unportable. Defaults to the ambient context.
+     */
+    withZone<T>(slot: string, fn: (ctx: InvokeContext, entry: ZoneEntry) => Promise<T>, base?: InvokeContext): Promise<T>;
+    /** The zone required by this resource's `field` (`x-telo-requires-zone`), or
+     *  throw ERR_ZONE_REQUIRED. Reads the ambient stack unless `ctx` is given. */
+    requireZone(field: string, ctx?: InvokeContext): ZoneEntry;
+    /** Like {@link requireZone} but absence is a valid answer, not an error. */
+    findZone(field: string, ctx?: InvokeContext): ZoneEntry | undefined;
+    /** Ambient zones correlated on an instance the caller holds, innermost first —
+     *  the undeclared case (a statement with no `transaction:` still joins an open
+     *  one). No kind parameter: the provider's own per-instance map already
+     *  discriminates — a zone this instance's owner did not open simply misses. */
+    zonesFor(instance: ResourceInstance, ctx?: InvokeContext): readonly ZoneEntry[];
+    /** The root context for runtime-driven inbound work (request, timer, queue
+     *  message): inherits nothing from whatever ambient happens to be live at the
+     *  registration site — no zones, no trace parent, no caller token. An inbound
+     *  registrant dispatches with this (or a cancellation source's context, which
+     *  is one), never `undefined`. */
+    rootContext(opts?: {
+        cancellation?: CancellationSource;
+    }): InvokeContext;
     /** Run `fn` detached from the caller's cancellation/trace scope: the ambient
      *  request token + span are replaced with the uncancellable root, so request
      *  teardown cannot abort the work and it does not nest under the request's
@@ -86,7 +143,11 @@ export interface ResourceContext extends ControllerContext {
      *  (e.g. a W3C `traceparent`). A no-op (returns `base` unchanged) when tracing
      *  is off. */
     openSpan(base: InvokeContext | undefined, opts: OpenSpanOptions): Promise<OpenSpan>;
-    invoke<TInputs>(kind: string, name: string, inputs: TInputs, options?: any): Promise<any>;
+    /** Dispatch by name through the traced chokepoint. See
+     *  {@link InvokeByNameOptions} for `ctx` — an inbound registrant passes
+     *  {@link rootContext} there so the handler inherits nothing ambient
+     *  (execution-zones spec §7). */
+    invoke<TInputs>(kind: string, name: string, inputs: TInputs, options?: InvokeByNameOptions): Promise<any>;
     invokeResolved<TInputs>(kind: string, name: string, instance: ResourceInstance, inputs: TInputs, ctx?: InvokeContext): Promise<any>;
     run(kind: string, name: string): Promise<void>;
     getResourcesByName(kind: string, name: string): RuntimeResource | null;
@@ -122,6 +183,12 @@ export interface ResourceContext extends ControllerContext {
      */
     resolveRef<T>(value: unknown, guard: (candidate: unknown) => candidate is T, describe: () => string, expects?: string): T;
     validateSchema(value: any, schema: any): void;
+    /** Compile an author-written JSON Schema from a resource field into a
+     *  reusable validator, through the runtime's own engine — so its formats and
+     *  `x-telo-*` keywords apply and one process never holds two disagreeing
+     *  validators. Compile once in `create()` and validate per invocation; the
+     *  result is memoized in-process but never written to the on-disk validator
+     *  cache, which only warms kind schemas and invocation contracts. */
     createSchemaValidator(schema: any): DataValidator;
     registerSchema(name: string, schema: object): void;
     lookupSchema(name: string): object | undefined;

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/dist/resource-instance.d.ts

@@ -29,6 +29,26 @@ export interface RefIdentity {
     kind: string;
     name: string;
 }
+/**
+ * Kernel-minted, unique per LIVE instance, stable for its lifetime. Distinct
+ * from {@link RefIdentity}: a `with:`-scoped resource has one declaration and
+ * one instance per scope run, and correlation must see those as different.
+ * A string rather than an object reference so it serializes across the ABI —
+ * a second-language kernel compares the same value.
+ */
+export type ResourceInstanceId = string & {
+    readonly __brand: "ResourceInstanceId";
+};
+/**
+ * Typed identity of a live resource instance. `id` is the only thing compared;
+ * `ref` is where the instance was declared — diagnostics only, so an error can
+ * say *no transaction open on connection `appDb`* instead of printing an id.
+ */
+export interface ResourceHandle {
+    readonly id: ResourceInstanceId;
+    readonly ref: RefIdentity;
+}
+export declare const sameResource: (a: ResourceHandle, b: ResourceHandle) => boolean;
 /**
  * Non-enumerable identity tag the kernel stamps on a live instance when it
  * injects a resolved `!ref` into a slot. A consumer that holds only the bare

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

@@ -1 +1 @@
-{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChE;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEJ;;mBAEmB;AACnB,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAuC,CAAC;AAE1E;sFACsF;AACtF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASnF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAExE"}
+{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChE;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEJ;;mBAEmB;AACnB,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED,eAAO,MAAM,YAAY,GAAI,GAAG,cAAc,EAAE,GAAG,cAAc,KAAG,OAAwB,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAuC,CAAC;AAE1E;sFACsF;AACtF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASnF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAExE"}

package/dist/resource-instance.js

@@ -2,6 +2,7 @@
  *  sinks use it so anything logging during its own teardown still reaches a live
  *  destination. */
 export const TEARDOWN_LAST = 1000;
+export const sameResource = (a, b) => a.id === b.id;
 /**
  * Non-enumerable identity tag the kernel stamps on a live instance when it
  * injects a resolved `!ref` into a slot. A consumer that holds only the bare

package/package.json

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

package/src/cancellation.ts

@@ -1,4 +1,5 @@
 import { InvokeError } from "./invoke-error.js";
+import type { ResourceHandle } from "./resource-instance.js";
 
 /**
  * Cooperative invocation cancellation — the standard source/token split.
@@ -34,6 +35,22 @@ export interface CancellationToken {
   throwIfCancelled(): void;
 }
 
+/**
+ * One open execution zone — see `kernel/specs/execution-zones.md`. Three
+ * identities and nothing else: no provider-private payload rides here (a
+ * provider keys its own map on the entry), so the contract stays serializable
+ * across the ABI and another module's open transaction is never readable from
+ * the ambient stack.
+ */
+export interface ZoneEntry {
+  /** Canonical `<module>.<Kind>` of the providing kind — what a requirement names. */
+  readonly kind: string;
+  readonly provider: ResourceHandle;
+  /** The instance the provider's correlation-key pointer resolved to.
+   *  Absent = uncorrelated zone. */
+  readonly key?: ResourceHandle;
+}
+
 /**
  * The out-of-band second argument every `invoke()` receives. Intentionally an
  * extensible object rather than a bare token so future per-invoke concerns
@@ -53,6 +70,20 @@ export interface InvokeContext {
    *  trace the way OpenTelemetry's `trace_id` does (an exporter maps it directly),
    *  independent of the parent chain. */
   readonly traceId?: string;
+  /** Zones open around this invocation, outermost first. Absent = none. */
+  readonly zones?: readonly ZoneEntry[];
+}
+
+/**
+ * The ONE way to build a context derived from another. A fresh object literal
+ * at a rebuild site silently drops every field it does not restate — with
+ * `zones` that means the stack survives with tracing off and vanishes under
+ * `--debug`, a safety property flipping on a debug flag. Every context-rebuild
+ * site (the kernel's tracing branches, span derivation) goes through here so a
+ * field added to {@link InvokeContext} propagates without each site opting in.
+ */
+export function deriveContext(base: InvokeContext, overrides: Partial<InvokeContext>): InvokeContext {
+  return { ...base, ...overrides };
 }
 
 /** Terminal status of a span — maps to OpenTelemetry span status. */

package/src/resource-context.ts

@@ -1,4 +1,11 @@
-import type { CancellationSource, InvokeContext, OpenSpan, OpenSpanOptions } from "./cancellation.js";
+import type {
+  CancellationSource,
+  InvokeContext,
+  OpenSpan,
+  OpenSpanOptions,
+  ZoneEntry,
+} from "./cancellation.js";
+import type { ResourceHandle } from "./resource-instance.js";
 import { ControllerContext } from "./controller-context.js";
 import type { Logger } from "./logger.js";
 import type { LoggingHost } from "./log-sink.js";
@@ -45,6 +52,21 @@ export class NoopValidator implements DataValidator {
 
 export type ParsedArgs = Partial<Record<string, string | boolean | string[]>> & { _: string[] };
 
+/**
+ * Per-call options for a by-name dispatch.
+ *
+ * A bag rather than a positional context parameter because this slot already
+ * carried one meaning — `retry`, consumed by the step leaf — and
+ * `ResourceContext` satisfies `InvokeStepContext` structurally, so a positional
+ * `InvokeContext` here silently receives a step's retry options instead.
+ */
+export interface InvokeByNameOptions {
+  /** Seeds the invocation context, replacing the ambient. */
+  ctx?: InvokeContext;
+  /** Retry policy, read by `executeInvokeStep`. */
+  retry?: unknown;
+}
+
 export interface ResourceContext extends ControllerContext {
   readonly args: ParsedArgs;
   /** The id prefix of the context this resource was created in (the creating
@@ -81,6 +103,50 @@ export interface ResourceContext extends ControllerContext {
    *  lambda budget). Pass `source.context` into `invokeResolved` to scope an
    *  invocation tree to it. */
   createCancellationSource(): CancellationSource;
+  /** This resource's own handle. Its `ref` is how a controller names itself in a
+   *  diagnostic; its id is what the kernel stamps as a zone's `provider`. */
+  readonly self: ResourceHandle;
+  /**
+   * Open the zone declared by this resource's `slot` (`x-telo-provides-zone`)
+   * around `fn`. Kind = the declaring kind; correlation key = the annotation's
+   * pointer, resolved against this resource's own manifest. Throws if `slot`
+   * carries no such annotation — a controller and its schema disagreeing is a
+   * defect, not a fallback.
+   *
+   * A scope function rather than a push/pop pair: push/pop cannot be honest
+   * across async boundaries. `fn` receives the derived context to thread into
+   * `invokeResolved` for the body — the discipline cancellation already has —
+   * and the minted entry, which a provider with private state (an open
+   * transaction, a journal) keys its own map on.
+   *
+   * `base` is the context the new zone is layered onto. Pass the
+   * {@link InvokeContext} the controller was handed, exactly as
+   * {@link requireZone} takes one: a runtime with no ambient store (the Rust
+   * kernel passes its context explicitly and has none) can only implement the
+   * provider half through this parameter, so omitting it would make the surface
+   * unportable. Defaults to the ambient context.
+   */
+  withZone<T>(
+    slot: string,
+    fn: (ctx: InvokeContext, entry: ZoneEntry) => Promise<T>,
+    base?: InvokeContext,
+  ): Promise<T>;
+  /** The zone required by this resource's `field` (`x-telo-requires-zone`), or
+   *  throw ERR_ZONE_REQUIRED. Reads the ambient stack unless `ctx` is given. */
+  requireZone(field: string, ctx?: InvokeContext): ZoneEntry;
+  /** Like {@link requireZone} but absence is a valid answer, not an error. */
+  findZone(field: string, ctx?: InvokeContext): ZoneEntry | undefined;
+  /** Ambient zones correlated on an instance the caller holds, innermost first —
+   *  the undeclared case (a statement with no `transaction:` still joins an open
+   *  one). No kind parameter: the provider's own per-instance map already
+   *  discriminates — a zone this instance's owner did not open simply misses. */
+  zonesFor(instance: ResourceInstance, ctx?: InvokeContext): readonly ZoneEntry[];
+  /** The root context for runtime-driven inbound work (request, timer, queue
+   *  message): inherits nothing from whatever ambient happens to be live at the
+   *  registration site — no zones, no trace parent, no caller token. An inbound
+   *  registrant dispatches with this (or a cancellation source's context, which
+   *  is one), never `undefined`. */
+  rootContext(opts?: { cancellation?: CancellationSource }): InvokeContext;
   /** Run `fn` detached from the caller's cancellation/trace scope: the ambient
    *  request token + span are replaced with the uncancellable root, so request
    *  teardown cannot abort the work and it does not nest under the request's
@@ -95,7 +161,16 @@ export interface ResourceContext extends ControllerContext {
    *  (e.g. a W3C `traceparent`). A no-op (returns `base` unchanged) when tracing
    *  is off. */
   openSpan(base: InvokeContext | undefined, opts: OpenSpanOptions): Promise<OpenSpan>;
-  invoke<TInputs>(kind: string, name: string, inputs: TInputs, options?: any): Promise<any>;
+  /** Dispatch by name through the traced chokepoint. See
+   *  {@link InvokeByNameOptions} for `ctx` — an inbound registrant passes
+   *  {@link rootContext} there so the handler inherits nothing ambient
+   *  (execution-zones spec §7). */
+  invoke<TInputs>(
+    kind: string,
+    name: string,
+    inputs: TInputs,
+    options?: InvokeByNameOptions,
+  ): Promise<any>;
   invokeResolved<TInputs>(
     kind: string,
     name: string,
@@ -139,6 +214,12 @@ export interface ResourceContext extends ControllerContext {
     expects?: string,
   ): T;
   validateSchema(value: any, schema: any): void;
+  /** Compile an author-written JSON Schema from a resource field into a
+   *  reusable validator, through the runtime's own engine — so its formats and
+   *  `x-telo-*` keywords apply and one process never holds two disagreeing
+   *  validators. Compile once in `create()` and validate per invocation; the
+   *  result is memoized in-process but never written to the on-disk validator
+   *  cache, which only warms kind schemas and invocation contracts. */
   createSchemaValidator(schema: any): DataValidator;
   registerSchema(name: string, schema: object): void;
   lookupSchema(name: string): object | undefined;

package/src/resource-instance.ts

@@ -37,6 +37,27 @@ export interface RefIdentity {
   name: string;
 }
 
+/**
+ * Kernel-minted, unique per LIVE instance, stable for its lifetime. Distinct
+ * from {@link RefIdentity}: a `with:`-scoped resource has one declaration and
+ * one instance per scope run, and correlation must see those as different.
+ * A string rather than an object reference so it serializes across the ABI —
+ * a second-language kernel compares the same value.
+ */
+export type ResourceInstanceId = string & { readonly __brand: "ResourceInstanceId" };
+
+/**
+ * Typed identity of a live resource instance. `id` is the only thing compared;
+ * `ref` is where the instance was declared — diagnostics only, so an error can
+ * say *no transaction open on connection `appDb`* instead of printing an id.
+ */
+export interface ResourceHandle {
+  readonly id: ResourceInstanceId;
+  readonly ref: RefIdentity;
+}
+
+export const sameResource = (a: ResourceHandle, b: ResourceHandle): boolean => a.id === b.id;
+
 /**
  * Non-enumerable identity tag the kernel stamps on a live instance when it
  * injects a resolved `!ref` into a slot. A consumer that holds only the bare