@telorun/sql 0.10.0 → 0.12.0

package/README.md

@@ -48,7 +48,9 @@ See [examples/](./examples/) for a list of working applications.
 
 ## Status
 
-Telo is under **active development**. The core runtime, module system, and standard library are functional, but the API surface — including YAML shapes — may change without notice. Not yet recommended for production use.
+Telo is under heavy development. While it is pre-1.0, breaking changes ship in **minor** releases — manifest shapes, kind schemas, and APIs can change between versions. Pin your imports and expect to update manifests when you upgrade. The core runtime, module system, and standard library are functional, but Telo is not yet recommended for production use.
+
+**1.0 lands when the Rust kernel reaches feature parity with the Node.js implementation** — that is the milestone that freezes the manifest contract across runtimes.
 
 ## The Meaning of Telo
 

package/dist/sql-command-controller.d.ts

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnection } from "./sql-connection.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
@@ -18,7 +18,7 @@ declare class SqlCommandResource implements ResourceInstance {
     private readonly manifest;
     private readonly ctx;
     constructor(manifest: SqlCommandManifest, ctx: ResourceContext);
-    invoke(input: unknown): Promise<SqlResult>;
+    invoke(input: unknown, invokeCtx?: InvokeContext): Promise<SqlResult>;
 }
 export declare function register(): void;
 export declare function create(resource: SqlCommandManifest, ctx: ResourceContext): Promise<SqlCommandResource>;

package/dist/sql-command-controller.js

@@ -7,7 +7,7 @@ class SqlCommandResource {
         this.manifest = manifest;
         this.ctx = ctx;
     }
-    async invoke(input) {
+    async invoke(input, invokeCtx) {
         const m = this.manifest;
         const ctx = this.ctx;
         const connection = resolveSqlConnection(m.connection, ctx, () => `Sql.Command "${m.metadata.name}": 'connection'`) ??
@@ -15,7 +15,12 @@ class SqlCommandResource {
         if (!connection) {
             throw new Error("Sql: either 'connection' or 'transaction' must be set");
         }
-        const result = await runSql(connection, m.transaction, input, ctx);
+        // ERR_ZONE_REQUIRED when no sql.Transaction zone is open on THIS statement's
+        // connection — a transaction on another connection no longer answers. The
+        // kernel supplies the zone kind and the correlation key (including the
+        // `/transaction/connection` fallback) from the `transaction` annotation.
+        const zone = m.transaction ? ctx.requireZone("transaction", invokeCtx) : undefined;
+        const result = await runSql(connection, zone, input, ctx, invokeCtx);
         return { rows: result.rows, rowCount: connection.toRowCount(result) };
     }
 }

package/dist/sql-connection-base.d.ts

@@ -1,6 +1,6 @@
+import { type InvokeContext, type ResourceContext, type ZoneEntry } from "@telorun/sdk";
 import { type Kysely, type QueryResult } from "kysely";
 import type { SqlConnection, SqlDialect } from "./sql-connection.js";
-import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 /**
  * The dialect-neutral half of a connection: statement execution, transaction
  * scoping, template binding and row-count normalization over a kysely instance.
@@ -10,15 +10,18 @@ import type { SqlTransactionResource } from "./sql-transaction-controller.js";
  * where the driver has a native multi-statement path.
  */
 export declare abstract class SqlConnectionBase implements SqlConnection {
+    #private;
     readonly dialect: SqlDialect;
+    protected readonly ctx: ResourceContext;
     protected readonly db: Kysely<any>;
-    constructor(db: Kysely<any>, dialect: SqlDialect);
+    constructor(db: Kysely<any>, dialect: SqlDialect, ctx: ResourceContext);
     get kysely(): Kysely<any>;
     init(): Promise<void>;
     teardown(): Promise<void>;
-    transaction<T>(cb: () => Promise<T>): Promise<T>;
-    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
-    executeTemplate<T>(fragments: string[], values: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    runInTransaction<T>(body: (bind: (entry: ZoneEntry) => void) => Promise<T>): Promise<T>;
+    hasOpenTransaction(ctx?: InvokeContext): boolean;
+    execute<T>(sql: string, params?: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
+    executeTemplate<T>(fragments: string[], values: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
     /** Hand the whole script to the driver as one statement. Backends whose driver
      *  needs a dedicated multi-statement entry point override this. */
     executeScript(sql: string): Promise<void>;

package/dist/sql-connection-base.js

@@ -1,6 +1,5 @@
-import { randomUUID } from "crypto";
+import { InvokeError, } from "@telorun/sdk";
 import { CompiledQuery } from "kysely";
-import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-store.js";
 /**
  * The dialect-neutral half of a connection: statement execution, transaction
  * scoping, template binding and row-count normalization over a kysely instance.
@@ -11,9 +10,17 @@ import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-st
  */
 export class SqlConnectionBase {
     dialect;
+    ctx;
     db;
-    constructor(db, dialect) {
+    /** Executors for transaction zones open on THIS connection. An instance
+     *  field, never a module global: the transaction controller and this base are
+     *  delivered as different bundles, each inlining its own copy of a shared
+     *  source file, so module scope would be one map per bundle and every lookup
+     *  a miss (the payload rule, kernel/specs/execution-zones.md §8). */
+    #executors = new WeakMap();
+    constructor(db, dialect, ctx) {
         this.dialect = dialect;
+        this.ctx = ctx;
         this.db = db;
     }
     get kysely() {
@@ -27,28 +34,24 @@ export class SqlConnectionBase {
     async teardown() {
         await this.db.destroy();
     }
-    async transaction(cb) {
-        const txId = randomUUID();
-        return this.db.transaction().execute(async (trx) => {
-            setTx(txId, { executor: trx });
-            try {
-                return await txStorage.run(txId, cb);
-            }
-            finally {
-                deleteTx(txId);
-            }
-        });
+    async runInTransaction(body) {
+        return this.db
+            .transaction()
+            .execute((trx) => body((entry) => this.#executors.set(entry, trx)));
+    }
+    hasOpenTransaction(ctx) {
+        return this.ctx.zonesFor(this, ctx).some((entry) => this.#executors.has(entry));
     }
-    async execute(sql, params = [], transaction) {
-        const executor = this.resolveExecutor(transaction);
+    async execute(sql, params = [], zone, ctx) {
+        const executor = this.resolveExecutor(zone, ctx);
         return executor.executeQuery(CompiledQuery.raw(sql, params));
     }
-    async executeTemplate(fragments, values, transaction) {
+    async executeTemplate(fragments, values, zone, ctx) {
         let sql = fragments[0] ?? "";
         for (let i = 1; i < fragments.length; i++) {
             sql += this.placeholder(i) + fragments[i];
         }
-        return this.execute(sql, values, transaction);
+        return this.execute(sql, values, zone, ctx);
     }
     /** Hand the whole script to the driver as one statement. Backends whose driver
      *  needs a dedicated multi-statement entry point override this. */
@@ -67,17 +70,16 @@ export class SqlConnectionBase {
     placeholder(index) {
         return this.dialect.placeholderStyle === "numbered" ? `$${index}` : "?";
     }
-    resolveExecutor(transaction) {
-        if (transaction) {
-            transaction.assertActive();
+    resolveExecutor(zone, ctx) {
+        if (zone && !this.#executors.has(zone)) {
+            // A zone this connection did not open cannot be silently ignored: the
+            // caller declared a requirement, and `?? this.db` here would execute it
+            // outside the transaction it asked for — silent non-transactional writes
+            // instead of a loud failure.
+            throw new InvokeError("ERR_SQL_ZONE_FOREIGN", `Sql: the ${zone.kind} zone provided by '${zone.provider.ref.name}' was not opened on ` +
+                `this connection — the statement would execute outside the transaction it names`);
         }
-        const txId = currentTxId();
-        if (txId) {
-            const entry = getTx(txId);
-            if (entry) {
-                return entry.executor;
-            }
-        }
-        return this.db;
+        const entry = zone ?? this.ctx.zonesFor(this, ctx).find((e) => this.#executors.has(e));
+        return (entry && this.#executors.get(entry)) ?? this.db;
     }
 }

package/dist/sql-connection.d.ts

@@ -1,6 +1,5 @@
-import type { ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceInstance, ZoneEntry } from "@telorun/sdk";
 import type { Kysely, QueryResult } from "kysely";
-import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 /** Native bind-placeholder syntax: SQLite binds anonymous `?`, PostgreSQL binds
  *  numbered `$1`, `$2`, … */
 export type PlaceholderStyle = "qmark" | "numbered";
@@ -25,6 +24,12 @@ export declare function quoteAnsiIdentifier(name: string): string;
  * against. Backends (`sql-postgres`, `sql-sqlite`) own their own implementation
  * — usually by extending {@link SqlConnectionBase} — so nothing in this module
  * knows which databases exist.
+ *
+ * Transaction membership is ambient, carried by the kernel's execution-zone
+ * stack (kernel/specs/execution-zones.md) and keyed per connection: a statement
+ * executes on an open transaction's executor when a transaction zone
+ * correlated on THIS connection is ambient, or when the caller passes the
+ * zone entry explicitly.
  */
 export interface SqlConnection extends ResourceInstance {
     readonly dialect: SqlDialect;
@@ -33,13 +38,19 @@ export interface SqlConnection extends ResourceInstance {
      *  must stay implementable by a driver kysely does not support; a consumer
      *  that needs it (`Sql.Migrations`) checks and fails with a clear message. */
     readonly kysely?: Kysely<any>;
-    execute<T>(sql: string, params?: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    execute<T>(sql: string, params?: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
     /** Assemble SQL from literal fragments by interleaving dialect-native
      *  placeholders, then bind `values` positionally. */
-    executeTemplate<T>(fragments: string[], values: unknown[], transaction?: SqlTransactionResource): Promise<QueryResult<T>>;
+    executeTemplate<T>(fragments: string[], values: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
     /** Run a multi-statement script. */
     executeScript(sql: string): Promise<void>;
-    transaction<T>(cb: () => Promise<T>): Promise<T>;
+    /** Open a database transaction and hand the caller a `bind` that keys the
+     *  open executor on the zone entry the caller mints (via `ctx.withZone`).
+     *  The executor stays private to this connection — the payload rule. */
+    runInTransaction<T>(body: (bind: (entry: ZoneEntry) => void) => Promise<T>, ctx?: InvokeContext): Promise<T>;
+    /** True when an ambient transaction zone correlated on this connection has an
+     *  open executor here — the flat-nesting check `Sql.Transaction` reuses. */
+    hasOpenTransaction(ctx?: InvokeContext): boolean;
     /** Rows affected by a write, normalized across drivers. */
     toRowCount(result: QueryResult<unknown>): number;
 }

package/dist/sql-query-controller.d.ts

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnection } from "./sql-connection.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 interface SqlQueryManifest {
@@ -21,7 +21,7 @@ declare class SqlQueryResource implements ResourceInstance {
     private readonly manifest;
     private readonly ctx;
     constructor(manifest: SqlQueryManifest, ctx: ResourceContext);
-    invoke(input: unknown): Promise<SqlResult>;
+    invoke(input: unknown, invokeCtx?: InvokeContext): Promise<SqlResult>;
 }
 export declare function register(): void;
 export declare function create(resource: SqlQueryManifest, ctx: ResourceContext): Promise<SqlQueryResource>;

package/dist/sql-query-controller.js

@@ -7,11 +7,14 @@ class SqlQueryResource {
         this.manifest = manifest;
         this.ctx = ctx;
     }
-    async invoke(input) {
+    async invoke(input, invokeCtx) {
         const m = this.manifest;
         const ctx = this.ctx;
         const connection = resolveConnection(m.connection, m.transaction, ctx, () => `Sql.Query "${m.metadata.name}": 'connection'`);
-        const result = await runSql(connection, m.transaction, input, ctx);
+        // ERR_ZONE_REQUIRED when no sql.Transaction zone is open on THIS query's
+        // connection — a transaction on another connection no longer answers.
+        const zone = m.transaction ? ctx.requireZone("transaction", invokeCtx) : undefined;
+        const result = await runSql(connection, zone, input, ctx, invokeCtx);
         return { rows: result.rows, rowCount: result.rows.length };
     }
 }

package/dist/sql-run.d.ts

@@ -1,7 +1,6 @@
-import { type ResourceContext } from "@telorun/sdk";
+import { type InvokeContext, type ResourceContext, type ZoneEntry } from "@telorun/sdk";
 import type { QueryResult } from "kysely";
 import type { SqlConnection } from "./sql-connection.js";
-import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 /** Execute the `sql` input of a Query/Exec resource against `connection`.
  *
  *  Two modes:
@@ -13,4 +12,4 @@ import type { SqlTransactionResource } from "./sql-transaction-controller.js";
  *
  *  Mixing a `!sql` template with `bindings` is rejected. A plain string `sql`
  *  with neither is executed verbatim. */
-export declare function runSql(connection: SqlConnection, transaction: SqlTransactionResource | undefined, input: unknown, ctx: ResourceContext): Promise<QueryResult<Record<string, unknown>>>;
+export declare function runSql(connection: SqlConnection, zone: ZoneEntry | undefined, input: unknown, ctx: ResourceContext, invokeCtx?: InvokeContext): Promise<QueryResult<Record<string, unknown>>>;

package/dist/sql-run.js

@@ -1,4 +1,4 @@
-import { InvokeError, isParameterizedSql } from "@telorun/sdk";
+import { InvokeError, isParameterizedSql, } from "@telorun/sdk";
 /** Execute the `sql` input of a Query/Exec resource against `connection`.
  *
  *  Two modes:
@@ -10,7 +10,7 @@ import { InvokeError, isParameterizedSql } from "@telorun/sdk";
  *
  *  Mixing a `!sql` template with `bindings` is rejected. A plain string `sql`
  *  with neither is executed verbatim. */
-export async function runSql(connection, transaction, input, ctx) {
+export async function runSql(connection, zone, input, ctx, invokeCtx) {
     const expanded = ctx.expandValue(input, {});
     const sql = expanded.sql;
     const bindings = expanded.bindings;
@@ -21,7 +21,7 @@ export async function runSql(connection, transaction, input, ctx) {
                 "Use one or the other — `!sql` binds each inline value automatically; " +
                 "`bindings` is for hand-written ? / $n placeholders.");
         }
-        return connection.executeTemplate(sql.fragments, sql.values, transaction);
+        return connection.executeTemplate(sql.fragments, sql.values, zone, invokeCtx);
     }
-    return connection.execute(sql, hasBindings ? bindings : [], transaction);
+    return connection.execute(sql, hasBindings ? bindings : [], zone, invokeCtx);
 }

package/dist/sql-selection-controller.d.ts

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnection } from "./sql-connection.js";
 import type { SqlResult } from "./sql-query-controller.js";
 import type { SqlTransactionResource } from "./sql-transaction-controller.js";
@@ -62,7 +62,7 @@ declare class SqlSelectionResource implements ResourceInstance {
     private readonly manifest;
     private readonly ctx;
     constructor(manifest: SelectManifest, ctx: ResourceContext);
-    invoke(input: unknown): Promise<SqlResult>;
+    invoke(input: unknown, invokeCtx?: InvokeContext): Promise<SqlResult>;
 }
 export declare function register(): void;
 export declare function create(resource: SelectManifest, ctx: ResourceContext): Promise<SqlSelectionResource>;

package/dist/sql-selection-controller.js

@@ -7,7 +7,7 @@ class SqlSelectionResource {
         this.manifest = manifest;
         this.ctx = ctx;
     }
-    async invoke(input) {
+    async invoke(input, invokeCtx) {
         const m = this.manifest;
         const ctx = this.ctx;
         const inputs = {
@@ -24,8 +24,11 @@ class SqlSelectionResource {
         if (!connection) {
             throw new Error("Sql.Selection: either 'connection' or 'transaction' must be set");
         }
+        // ERR_ZONE_REQUIRED when no sql.Transaction zone is open on THIS selection's
+        // connection — a transaction on another connection no longer answers.
+        const zone = m.transaction ? ctx.requireZone("transaction", invokeCtx) : undefined;
         const { sql, params } = buildSelect(m, where, having, limit, offset, connection.dialect);
-        const result = await connection.execute(sql, params, m.transaction);
+        const result = await connection.execute(sql, params, zone, invokeCtx);
         return { rows: result.rows, rowCount: result.rows.length };
     }
 }

package/dist/sql-transaction-controller.d.ts

@@ -1,4 +1,4 @@
-import type { Invocable, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { type InvokeContext, type ResourceContext, type ResourceInstance } from "@telorun/sdk";
 import type { SqlConnection } from "./sql-connection.js";
 interface SqlTransactionManifest {
     metadata: {
@@ -6,7 +6,7 @@ interface SqlTransactionManifest {
         module: string;
     };
     connection: SqlConnection;
-    steps: Invocable;
+    steps: ResourceInstance;
     inputs?: Record<string, unknown>;
 }
 export declare class SqlTransactionResource implements ResourceInstance {
@@ -14,8 +14,8 @@ export declare class SqlTransactionResource implements ResourceInstance {
     private readonly ctx;
     constructor(manifest: SqlTransactionManifest, ctx: ResourceContext);
     getConnection(): SqlConnection;
-    assertActive(): void;
-    invoke(input: unknown): Promise<unknown>;
+    invoke(input: unknown, invokeCtx?: InvokeContext): Promise<unknown>;
+    private dispatchSteps;
 }
 export declare function register(): void;
 export declare function create(resource: SqlTransactionManifest, ctx: ResourceContext): Promise<SqlTransactionResource>;

package/dist/sql-transaction-controller.js

@@ -1,5 +1,10 @@
+import { InvokeError, getRefIdentity, } from "@telorun/sdk";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
-import { currentTxId } from "./transaction-store.js";
+/** The steps slot is `Telo.Executable`: an instance with either entry point. */
+function isExecutable(value) {
+    const v = value;
+    return typeof v?.invoke === "function" || typeof v?.run === "function";
+}
 export class SqlTransactionResource {
     manifest;
     ctx;
@@ -10,22 +15,49 @@ export class SqlTransactionResource {
     getConnection() {
         return (resolveSqlConnection(this.manifest.connection, this.ctx, () => `Sql.Transaction "${this.manifest.metadata.name}": 'connection'`) ?? failMissingConnection(this.manifest.metadata.name));
     }
-    assertActive() {
-        if (!currentTxId()) {
-            throw new Error(`Sql.Transaction '${this.manifest.metadata.name}': used outside an active transaction`);
+    async invoke(input, invokeCtx) {
+        const m = this.manifest;
+        const ctx = this.ctx;
+        // The declared `inputs:` map's CEL reads the caller's invocation input as
+        // `inputs.<field>` — the same variable name a Run.Sequence step's inputs
+        // read, and what the slot's `inputs: /inputs` pointer names.
+        const celScope = { inputs: input ?? {} };
+        const expandedInputs = ctx.expandValue(m.inputs ?? {}, celScope);
+        // `invokeCtx` is threaded rather than left to the ambient throughout: the
+        // caller's context is the authority on which zones are open, and a runtime
+        // with no ambient store has nothing else to read.
+        //
+        // Flat nesting: an ambient transaction on the SAME connection is joined; a
+        // different connection's transaction is not ours and we open our own.
+        const conn = this.getConnection();
+        if (conn.hasOpenTransaction(invokeCtx)) {
+            return this.dispatchSteps(expandedInputs, invokeCtx);
         }
+        return conn.runInTransaction((bind) => 
+        // "steps" is this kind's own slot; the kernel reads `x-telo-provides-zone`
+        // there for the zone kind (this kind) and the correlation key
+        // (`/connection`). The entry is handed to the connection's own map —
+        // across the bundle/npm delivery split — and the derived context is
+        // threaded into the body dispatch, the discipline cancellation has.
+        ctx.withZone("steps", (zoneCtx, entry) => {
+            bind(entry);
+            return this.dispatchSteps(expandedInputs, zoneCtx);
+        }, invokeCtx));
     }
-    async invoke(input) {
+    dispatchSteps(inputs, zoneCtx) {
         const m = this.manifest;
-        const ctx = this.ctx;
-        // Flat nesting: if already inside a transaction, reuse it
-        if (currentTxId()) {
-            const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
-            return m.steps.invoke(expandedInputs);
+        const target = this.ctx.resolveRef(m.steps, isExecutable, () => `Sql.Transaction "${m.metadata.name}": 'steps'`, "Telo.Executable");
+        // The kernel stamps `!ref` identity at Phase-5 injection, and `resolveRef`
+        // rescues the sentinel form, so a resolved target always carries one.
+        // Guessing a label instead would emit malformed dispatch events (`.Invoked`
+        // with no kind) — a silent wrong answer where a missing identity means the
+        // resolution path changed under us.
+        const id = getRefIdentity(target);
+        if (!id) {
+            throw new InvokeError("ERR_SQL_STEPS_UNIDENTIFIED", `Sql.Transaction '${m.metadata.name}': the resolved 'steps' target carries no reference ` +
+                `identity, so its dispatch cannot be traced or named`);
         }
-        const conn = this.getConnection();
-        const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
-        return conn.transaction(() => m.steps.invoke(expandedInputs));
+        return this.ctx.invokeResolved(id.kind, id.name, target, inputs, zoneCtx);
     }
 }
 function failMissingConnection(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Telo SQL module - SQL database resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -26,33 +26,10 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "bun": "./src/index.ts",
       "import": "./dist/index.js"
-    },
-    "./sql-query": {
-      "bun": "./src/sql-query-controller.ts",
-      "import": "./dist/sql-query-controller.js"
-    },
-    "./sql-selection": {
-      "bun": "./src/sql-selection-controller.ts",
-      "import": "./dist/sql-selection-controller.js"
-    },
-    "./sql-command": {
-      "bun": "./src/sql-command-controller.ts",
-      "import": "./dist/sql-command-controller.js"
-    },
-    "./sql-transaction": {
-      "bun": "./src/sql-transaction-controller.ts",
-      "import": "./dist/sql-transaction-controller.js"
-    },
-    "./sql-migration": {
-      "bun": "./src/sql-migration-controller.ts",
-      "import": "./dist/sql-migration-controller.js"
-    },
-    "./sql-migrations": {
-      "bun": "./src/sql-migrations-controller.ts",
-      "import": "./dist/sql-migrations-controller.js"
     }
   },
   "files": [
@@ -64,13 +41,14 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "esbuild": "^0.25.12",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.58.0"
+    "@telorun/sdk": "0.67.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.lib.json"
+    "build": "tsc -p tsconfig.lib.json && esbuild src/sql-command-controller.ts src/sql-migration-controller.ts src/sql-migrations-controller.ts src/sql-query-controller.ts src/sql-selection-controller.ts src/sql-transaction-controller.ts --bundle --format=esm --platform=node --target=node20 --external:@telorun/sdk --conditions=source --outdir=. --banner:js='import { createRequire as __teloCreateRequire } from \"node:module\";const require = __teloCreateRequire(import.meta.url);' --out-extension:.js=.mjs"
   }
 }

package/src/sql-command-controller.ts

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnection } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import type { SqlResult } from "./sql-query-controller.js";
@@ -21,7 +21,7 @@ class SqlCommandResource implements ResourceInstance {
     private readonly ctx: ResourceContext,
   ) {}
 
-  async invoke(input: unknown): Promise<SqlResult> {
+  async invoke(input: unknown, invokeCtx?: InvokeContext): Promise<SqlResult> {
     const m = this.manifest;
     const ctx = this.ctx;
 
@@ -32,7 +32,12 @@ class SqlCommandResource implements ResourceInstance {
       throw new Error("Sql: either 'connection' or 'transaction' must be set");
     }
 
-    const result = await runSql(connection, m.transaction, input, ctx);
+    // ERR_ZONE_REQUIRED when no sql.Transaction zone is open on THIS statement's
+    // connection — a transaction on another connection no longer answers. The
+    // kernel supplies the zone kind and the correlation key (including the
+    // `/transaction/connection` fallback) from the `transaction` annotation.
+    const zone = m.transaction ? ctx.requireZone("transaction", invokeCtx) : undefined;
+    const result = await runSql(connection, zone, input, ctx, invokeCtx);
     return { rows: result.rows, rowCount: connection.toRowCount(result) };
   }
 }

package/src/sql-connection-base.ts

@@ -1,8 +1,11 @@
-import { randomUUID } from "crypto";
+import {
+  InvokeError,
+  type InvokeContext,
+  type ResourceContext,
+  type ZoneEntry,
+} from "@telorun/sdk";
 import { CompiledQuery, type Kysely, type QueryResult, type Transaction } from "kysely";
 import type { SqlConnection, SqlDialect } from "./sql-connection.js";
-import type { SqlTransactionResource } from "./sql-transaction-controller.js";
-import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-store.js";
 
 /**
  * The dialect-neutral half of a connection: statement execution, transaction
@@ -15,9 +18,17 @@ import { currentTxId, deleteTx, getTx, setTx, txStorage } from "./transaction-st
 export abstract class SqlConnectionBase implements SqlConnection {
   protected readonly db: Kysely<any>;
 
+  /** Executors for transaction zones open on THIS connection. An instance
+   *  field, never a module global: the transaction controller and this base are
+   *  delivered as different bundles, each inlining its own copy of a shared
+   *  source file, so module scope would be one map per bundle and every lookup
+   *  a miss (the payload rule, kernel/specs/execution-zones.md §8). */
+  readonly #executors = new WeakMap<ZoneEntry, Kysely<any>>();
+
   constructor(
     db: Kysely<any>,
     readonly dialect: SqlDialect,
+    protected readonly ctx: ResourceContext,
   ) {
     this.db = db;
   }
@@ -36,38 +47,39 @@ export abstract class SqlConnectionBase implements SqlConnection {
     await this.db.destroy();
   }
 
-  async transaction<T>(cb: () => Promise<T>): Promise<T> {
-    const txId = randomUUID();
+  async runInTransaction<T>(
+    body: (bind: (entry: ZoneEntry) => void) => Promise<T>,
+  ): Promise<T> {
+    return this.db
+      .transaction()
+      .execute((trx: Transaction<any>) => body((entry) => this.#executors.set(entry, trx)));
+  }
 
-    return this.db.transaction().execute(async (trx: Transaction<any>) => {
-      setTx(txId, { executor: trx });
-      try {
-        return await txStorage.run(txId, cb);
-      } finally {
-        deleteTx(txId);
-      }
-    });
+  hasOpenTransaction(ctx?: InvokeContext): boolean {
+    return this.ctx.zonesFor(this, ctx).some((entry) => this.#executors.has(entry));
   }
 
   async execute<T>(
     sql: string,
     params: unknown[] = [],
-    transaction?: SqlTransactionResource,
+    zone?: ZoneEntry,
+    ctx?: InvokeContext,
   ): Promise<QueryResult<T>> {
-    const executor = this.resolveExecutor(transaction);
+    const executor = this.resolveExecutor(zone, ctx);
     return executor.executeQuery<T>(CompiledQuery.raw(sql, params));
   }
 
   async executeTemplate<T>(
     fragments: string[],
     values: unknown[],
-    transaction?: SqlTransactionResource,
+    zone?: ZoneEntry,
+    ctx?: InvokeContext,
   ): Promise<QueryResult<T>> {
     let sql = fragments[0] ?? "";
     for (let i = 1; i < fragments.length; i++) {
       sql += this.placeholder(i) + fragments[i];
     }
-    return this.execute<T>(sql, values, transaction);
+    return this.execute<T>(sql, values, zone, ctx);
   }
 
   /** Hand the whole script to the driver as one statement. Backends whose driver
@@ -92,19 +104,19 @@ export abstract class SqlConnectionBase implements SqlConnection {
     return this.dialect.placeholderStyle === "numbered" ? `$${index}` : "?";
   }
 
-  private resolveExecutor(transaction?: SqlTransactionResource): Kysely<any> {
-    if (transaction) {
-      transaction.assertActive();
+  private resolveExecutor(zone?: ZoneEntry, ctx?: InvokeContext): Kysely<any> {
+    if (zone && !this.#executors.has(zone)) {
+      // A zone this connection did not open cannot be silently ignored: the
+      // caller declared a requirement, and `?? this.db` here would execute it
+      // outside the transaction it asked for — silent non-transactional writes
+      // instead of a loud failure.
+      throw new InvokeError(
+        "ERR_SQL_ZONE_FOREIGN",
+        `Sql: the ${zone.kind} zone provided by '${zone.provider.ref.name}' was not opened on ` +
+          `this connection — the statement would execute outside the transaction it names`,
+      );
     }
-
-    const txId = currentTxId();
-    if (txId) {
-      const entry = getTx(txId);
-      if (entry) {
-        return entry.executor as Kysely<any>;
-      }
-    }
-
-    return this.db;
+    const entry = zone ?? this.ctx.zonesFor(this, ctx).find((e) => this.#executors.has(e));
+    return (entry && this.#executors.get(entry)) ?? this.db;
   }
 }

package/src/sql-connection.ts

@@ -1,6 +1,5 @@
-import type { ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceInstance, ZoneEntry } from "@telorun/sdk";
 import type { Kysely, QueryResult } from "kysely";
-import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 
 /** Native bind-placeholder syntax: SQLite binds anonymous `?`, PostgreSQL binds
  *  numbered `$1`, `$2`, … */
@@ -37,6 +36,12 @@ export function quoteAnsiIdentifier(name: string): string {
  * against. Backends (`sql-postgres`, `sql-sqlite`) own their own implementation
  * — usually by extending {@link SqlConnectionBase} — so nothing in this module
  * knows which databases exist.
+ *
+ * Transaction membership is ambient, carried by the kernel's execution-zone
+ * stack (kernel/specs/execution-zones.md) and keyed per connection: a statement
+ * executes on an open transaction's executor when a transaction zone
+ * correlated on THIS connection is ambient, or when the caller passes the
+ * zone entry explicitly.
  */
 export interface SqlConnection extends ResourceInstance {
   readonly dialect: SqlDialect;
@@ -50,7 +55,8 @@ export interface SqlConnection extends ResourceInstance {
   execute<T>(
     sql: string,
     params?: unknown[],
-    transaction?: SqlTransactionResource,
+    zone?: ZoneEntry,
+    ctx?: InvokeContext,
   ): Promise<QueryResult<T>>;
 
   /** Assemble SQL from literal fragments by interleaving dialect-native
@@ -58,13 +64,24 @@ export interface SqlConnection extends ResourceInstance {
   executeTemplate<T>(
     fragments: string[],
     values: unknown[],
-    transaction?: SqlTransactionResource,
+    zone?: ZoneEntry,
+    ctx?: InvokeContext,
   ): Promise<QueryResult<T>>;
 
   /** Run a multi-statement script. */
   executeScript(sql: string): Promise<void>;
 
-  transaction<T>(cb: () => Promise<T>): Promise<T>;
+  /** Open a database transaction and hand the caller a `bind` that keys the
+   *  open executor on the zone entry the caller mints (via `ctx.withZone`).
+   *  The executor stays private to this connection — the payload rule. */
+  runInTransaction<T>(
+    body: (bind: (entry: ZoneEntry) => void) => Promise<T>,
+    ctx?: InvokeContext,
+  ): Promise<T>;
+
+  /** True when an ambient transaction zone correlated on this connection has an
+   *  open executor here — the flat-nesting check `Sql.Transaction` reuses. */
+  hasOpenTransaction(ctx?: InvokeContext): boolean;
 
   /** Rows affected by a write, normalized across drivers. */
   toRowCount(result: QueryResult<unknown>): number;

package/src/sql-query-controller.ts

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnection } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import { runSql } from "./sql-run.js";
@@ -25,7 +25,7 @@ class SqlQueryResource implements ResourceInstance {
     private readonly ctx: ResourceContext,
   ) {}
 
-  async invoke(input: unknown): Promise<SqlResult> {
+  async invoke(input: unknown, invokeCtx?: InvokeContext): Promise<SqlResult> {
     const m = this.manifest;
     const ctx = this.ctx;
     const connection = resolveConnection(
@@ -34,7 +34,10 @@ class SqlQueryResource implements ResourceInstance {
       ctx,
       () => `Sql.Query "${m.metadata.name}": 'connection'`,
     );
-    const result = await runSql(connection, m.transaction, input, ctx);
+    // ERR_ZONE_REQUIRED when no sql.Transaction zone is open on THIS query's
+    // connection — a transaction on another connection no longer answers.
+    const zone = m.transaction ? ctx.requireZone("transaction", invokeCtx) : undefined;
+    const result = await runSql(connection, zone, input, ctx, invokeCtx);
     return { rows: result.rows, rowCount: result.rows.length };
   }
 }

package/src/sql-run.ts

@@ -1,7 +1,12 @@
-import { InvokeError, isParameterizedSql, type ResourceContext } from "@telorun/sdk";
+import {
+  InvokeError,
+  isParameterizedSql,
+  type InvokeContext,
+  type ResourceContext,
+  type ZoneEntry,
+} from "@telorun/sdk";
 import type { QueryResult } from "kysely";
 import type { SqlConnection } from "./sql-connection.js";
-import type { SqlTransactionResource } from "./sql-transaction-controller.js";
 
 /** Execute the `sql` input of a Query/Exec resource against `connection`.
  *
@@ -16,9 +21,10 @@ import type { SqlTransactionResource } from "./sql-transaction-controller.js";
  *  with neither is executed verbatim. */
 export async function runSql(
   connection: SqlConnection,
-  transaction: SqlTransactionResource | undefined,
+  zone: ZoneEntry | undefined,
   input: unknown,
   ctx: ResourceContext,
+  invokeCtx?: InvokeContext,
 ): Promise<QueryResult<Record<string, unknown>>> {
   const expanded = ctx.expandValue(input, {}) as { sql: unknown; bindings?: unknown[] };
   const sql = expanded.sql;
@@ -37,13 +43,15 @@ export async function runSql(
     return connection.executeTemplate<Record<string, unknown>>(
       sql.fragments,
       sql.values,
-      transaction,
+      zone,
+      invokeCtx,
     );
   }
 
   return connection.execute<Record<string, unknown>>(
     sql as string,
     hasBindings ? (bindings as unknown[]) : [],
-    transaction,
+    zone,
+    invokeCtx,
   );
 }

package/src/sql-selection-controller.ts

@@ -1,4 +1,4 @@
-import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import type { InvokeContext, ResourceContext, ResourceInstance } from "@telorun/sdk";
 import type { SqlConnection, SqlDialect } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
 import type { SqlResult } from "./sql-query-controller.js";
@@ -82,7 +82,7 @@ class SqlSelectionResource implements ResourceInstance {
     private readonly ctx: ResourceContext,
   ) {}
 
-  async invoke(input: unknown): Promise<SqlResult> {
+  async invoke(input: unknown, invokeCtx?: InvokeContext): Promise<SqlResult> {
     const m = this.manifest;
     const ctx = this.ctx;
     const inputs = {
@@ -103,8 +103,11 @@ class SqlSelectionResource implements ResourceInstance {
       throw new Error("Sql.Selection: either 'connection' or 'transaction' must be set");
     }
 
+    // ERR_ZONE_REQUIRED when no sql.Transaction zone is open on THIS selection's
+    // connection — a transaction on another connection no longer answers.
+    const zone = m.transaction ? ctx.requireZone("transaction", invokeCtx) : undefined;
     const { sql, params } = buildSelect(m, where, having, limit, offset, connection.dialect);
-    const result = await connection.execute<Record<string, unknown>>(sql, params, m.transaction);
+    const result = await connection.execute<Record<string, unknown>>(sql, params, zone, invokeCtx);
     return { rows: result.rows, rowCount: result.rows.length };
   }
 }

package/src/sql-transaction-controller.ts

@@ -1,15 +1,26 @@
-import type { Invocable, ResourceContext, ResourceInstance } from "@telorun/sdk";
+import {
+  InvokeError,
+  getRefIdentity,
+  type InvokeContext,
+  type ResourceContext,
+  type ResourceInstance,
+} from "@telorun/sdk";
 import type { SqlConnection } from "./sql-connection.js";
 import { resolveSqlConnection } from "./sql-connection-ref.js";
-import { currentTxId } from "./transaction-store.js";
 
 interface SqlTransactionManifest {
   metadata: { name: string; module: string };
   connection: SqlConnection;
-  steps: Invocable;
+  steps: ResourceInstance;
   inputs?: Record<string, unknown>;
 }
 
+/** The steps slot is `Telo.Executable`: an instance with either entry point. */
+function isExecutable(value: unknown): value is ResourceInstance {
+  const v = value as ResourceInstance | undefined;
+  return typeof v?.invoke === "function" || typeof v?.run === "function";
+}
+
 export class SqlTransactionResource implements ResourceInstance {
   constructor(
     private readonly manifest: SqlTransactionManifest,
@@ -26,28 +37,66 @@ export class SqlTransactionResource implements ResourceInstance {
     );
   }
 
-  assertActive(): void {
-    if (!currentTxId()) {
-      throw new Error(
-        `Sql.Transaction '${this.manifest.metadata.name}': used outside an active transaction`,
-      );
-    }
-  }
-
-  async invoke(input: unknown): Promise<unknown> {
+  async invoke(input: unknown, invokeCtx?: InvokeContext): Promise<unknown> {
     const m = this.manifest;
     const ctx = this.ctx;
 
-    // Flat nesting: if already inside a transaction, reuse it
-    if (currentTxId()) {
-      const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
-      return m.steps.invoke(expandedInputs);
-    }
+    // The declared `inputs:` map's CEL reads the caller's invocation input as
+    // `inputs.<field>` — the same variable name a Run.Sequence step's inputs
+    // read, and what the slot's `inputs: /inputs` pointer names.
+    const celScope = { inputs: input ?? {} };
+    const expandedInputs = ctx.expandValue(m.inputs ?? {}, celScope) as Record<string, unknown>;
 
+    // `invokeCtx` is threaded rather than left to the ambient throughout: the
+    // caller's context is the authority on which zones are open, and a runtime
+    // with no ambient store has nothing else to read.
+    //
+    // Flat nesting: an ambient transaction on the SAME connection is joined; a
+    // different connection's transaction is not ours and we open our own.
     const conn = this.getConnection();
-    const expandedInputs = ctx.expandValue(m.inputs ?? {}, input ?? {});
+    if (conn.hasOpenTransaction(invokeCtx)) {
+      return this.dispatchSteps(expandedInputs, invokeCtx);
+    }
 
-    return conn.transaction(() => m.steps.invoke(expandedInputs));
+    return conn.runInTransaction((bind) =>
+      // "steps" is this kind's own slot; the kernel reads `x-telo-provides-zone`
+      // there for the zone kind (this kind) and the correlation key
+      // (`/connection`). The entry is handed to the connection's own map —
+      // across the bundle/npm delivery split — and the derived context is
+      // threaded into the body dispatch, the discipline cancellation has.
+      ctx.withZone(
+        "steps",
+        (zoneCtx, entry) => {
+          bind(entry);
+          return this.dispatchSteps(expandedInputs, zoneCtx);
+        },
+        invokeCtx,
+      ),
+    );
+  }
+
+  private dispatchSteps(inputs: Record<string, unknown>, zoneCtx?: InvokeContext): Promise<unknown> {
+    const m = this.manifest;
+    const target = this.ctx.resolveRef(
+      m.steps,
+      isExecutable,
+      () => `Sql.Transaction "${m.metadata.name}": 'steps'`,
+      "Telo.Executable",
+    );
+    // The kernel stamps `!ref` identity at Phase-5 injection, and `resolveRef`
+    // rescues the sentinel form, so a resolved target always carries one.
+    // Guessing a label instead would emit malformed dispatch events (`.Invoked`
+    // with no kind) — a silent wrong answer where a missing identity means the
+    // resolution path changed under us.
+    const id = getRefIdentity(target as object);
+    if (!id) {
+      throw new InvokeError(
+        "ERR_SQL_STEPS_UNIDENTIFIED",
+        `Sql.Transaction '${m.metadata.name}': the resolved 'steps' target carries no reference ` +
+          `identity, so its dispatch cannot be traced or named`,
+      );
+    }
+    return this.ctx.invokeResolved(id.kind, id.name, target, inputs, zoneCtx);
   }
 }
 

package/dist/transaction-store.d.ts

@@ -1,9 +0,0 @@
-import { AsyncLocalStorage } from "async_hooks";
-export interface TxEntry {
-    executor: unknown;
-}
-export declare const txStorage: AsyncLocalStorage<string>;
-export declare const setTx: (id: string, entry: TxEntry) => void;
-export declare const getTx: (id: string) => TxEntry | undefined;
-export declare const deleteTx: (id: string) => void;
-export declare const currentTxId: () => string | undefined;

package/dist/transaction-store.js

@@ -1,11 +0,0 @@
-import { AsyncLocalStorage } from "async_hooks";
-const txMap = new Map();
-export const txStorage = new AsyncLocalStorage();
-export const setTx = (id, entry) => {
-    txMap.set(id, entry);
-};
-export const getTx = (id) => txMap.get(id);
-export const deleteTx = (id) => {
-    txMap.delete(id);
-};
-export const currentTxId = () => txStorage.getStore();

package/src/transaction-store.ts

@@ -1,20 +0,0 @@
-import { AsyncLocalStorage } from "async_hooks";
-
-export interface TxEntry {
-  executor: unknown;
-}
-
-const txMap = new Map<string, TxEntry>();
-export const txStorage = new AsyncLocalStorage<string>();
-
-export const setTx = (id: string, entry: TxEntry): void => {
-  txMap.set(id, entry);
-};
-
-export const getTx = (id: string): TxEntry | undefined => txMap.get(id);
-
-export const deleteTx = (id: string): void => {
-  txMap.delete(id);
-};
-
-export const currentTxId = (): string | undefined => txStorage.getStore();