refactor(runner): Use single TransactionWrapper class and optimize Cell.sink() (commontoolsinc#2176)

refactor(runner): Use single TransactionWrapper class with configurable options

Refactors the transaction wrapper to use a single configurable class instead
of multiple wrapper classes. Also uses this to optimize Cell.sink() by
removing the duplicate validateAndTransform call - now we wrap the transaction
to capture dependencies while child cells use a separate transaction.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: seefeldb

packages/runner/src/cell.ts

@@ -69,7 +69,10 @@ import type {
   IExtendedStorageTransaction,
   IReadOptions,
 } from "./storage/interface.ts";
-import { NonReactiveTransaction } from "./storage/extended-storage-transaction.ts";
+import {
+  createChildCellTransaction,
+  createNonReactiveTransaction,
+} from "./storage/extended-storage-transaction.ts";
 import { fromURI } from "./uri-utils.ts";
 import { ContextualFlowControl } from "./cfc.ts";
 
@@ -532,11 +535,11 @@ export class CellImpl<T> implements ICell<T>, IStreamable<T> {
   sample(): Readonly<T> {
     if (!this.synced) this.sync(); // No await, just kicking this off
 
-    // Wrap the transaction with NonReactiveTransaction to make all reads
-    // non-reactive. Child cells created during validateAndTransform will
-    // use the original transaction (via getTransactionForChildCells).
+    // Wrap the transaction to make all reads non-reactive. Child cells created
+    // during validateAndTransform will use the original transaction (via
+    // getTransactionForChildCells).
     const readTx = this.runtime.readTx(this.tx);
-    const nonReactiveTx = new NonReactiveTransaction(readTx);
+    const nonReactiveTx = createNonReactiveTransaction(readTx);
 
     return validateAndTransform(
       this.runtime,
@@ -1287,17 +1290,14 @@ function subscribeToReferencedDocs<T>(
   const cancel = runtime.scheduler.subscribe((tx) => {
     if (isCancel(cleanup)) cleanup();
 
-    // Run once with tx to capture _this_ cell's read dependencies.
-    validateAndTransform(runtime, tx, link, true);
-
-    // Using a new transaction for the callback, as we're only interested in
+    // Using a new transaction for child cells, as we're only interested in
     // dependencies for the initial get, not further cells the callback might
     // read. The callback is responsible for calling sink on those cells if it
     // wants to stay updated.
-
     const extraTx = runtime.edit();
+    const wrappedTx = createChildCellTransaction(tx, extraTx);
 
-    const newValue = validateAndTransform(runtime, extraTx, link, true);
+    const newValue = validateAndTransform(runtime, wrappedTx, link, true);
     cleanup = callback(newValue);
 
     // no async await here, but that also means no retry. TODO(seefeld): Should

packages/runner/src/storage/extended-storage-transaction.ts

@@ -216,21 +216,44 @@ export class ExtendedStorageTransaction implements IExtendedStorageTransaction {
 }
 
 /**
- * A wrapper around an IExtendedStorageTransaction that adds ignoreReadForScheduling
- * meta to all read operations. This makes reads non-reactive - they won't trigger
- * re-execution of handlers when the read values change.
+ * Options for configuring a TransactionWrapper.
+ */
+export interface TransactionWrapperOptions {
+  /**
+   * If true, adds ignoreReadForScheduling meta to all reads, making them
+   * non-reactive.
+   */
+  nonReactive?: boolean;
+
+  /**
+   * Transaction to use for creating child cells. If not provided, uses the
+   * wrapped transaction.
+   */
+  childCellTx?: IExtendedStorageTransaction;
+}
+
+/**
+ * A configurable wrapper around an IExtendedStorageTransaction.
  *
- * Used by Cell.sample() to read values without subscribing to changes.
+ * Supports two modes that can be combined:
+ * - nonReactive: Adds ignoreReadForScheduling meta to all reads
+ * - childCellTx: Uses a different transaction for child cells
+ *
+ * Used by:
+ * - Cell.sample(): nonReactive=true, childCellTx=wrapped (child cells reactive)
+ * - Cell.sink(): nonReactive=false, childCellTx=extraTx (child cells on separate tx)
  */
-export class NonReactiveTransaction implements IExtendedStorageTransaction {
-  constructor(private wrapped: IExtendedStorageTransaction) {}
+export class TransactionWrapper implements IExtendedStorageTransaction {
+  constructor(
+    private wrapped: IExtendedStorageTransaction,
+    private options: TransactionWrapperOptions = {},
+  ) {}
 
   /**
    * Get the transaction to use for creating child cells.
-   * Child cells should be reactive, so this returns the unwrapped transaction.
    */
   getTransactionForChildCells(): IExtendedStorageTransaction {
-    return this.wrapped;
+    return this.options.childCellTx ?? this.wrapped;
   }
 
   get tx(): IStorageTransaction {
@@ -249,7 +272,10 @@ export class NonReactiveTransaction implements IExtendedStorageTransaction {
     return this.wrapped.reader(space);
   }
 
-  private addNonReactiveMeta(options?: IReadOptions): IReadOptions {
+  private transformReadOptions(options?: IReadOptions): IReadOptions {
+    if (!this.options.nonReactive) {
+      return options ?? {};
+    }
     return {
       ...options,
       meta: { ...options?.meta, ...ignoreReadForScheduling },
@@ -260,14 +286,17 @@ export class NonReactiveTransaction implements IExtendedStorageTransaction {
     address: IMemorySpaceAddress,
     options?: IReadOptions,
   ): Result<IAttestation, ReadError> {
-    return this.wrapped.read(address, this.addNonReactiveMeta(options));
+    return this.wrapped.read(address, this.transformReadOptions(options));
   }
 
   readOrThrow(
     address: IMemorySpaceAddress,
     options?: IReadOptions,
   ): JSONValue | undefined {
-    return this.wrapped.readOrThrow(address, this.addNonReactiveMeta(options));
+    return this.wrapped.readOrThrow(
+      address,
+      this.transformReadOptions(options),
+    );
   }
 
   readValueOrThrow(
@@ -276,7 +305,7 @@ export class NonReactiveTransaction implements IExtendedStorageTransaction {
   ): JSONValue | undefined {
     return this.wrapped.readValueOrThrow(
       address,
-      this.addNonReactiveMeta(options),
+      this.transformReadOptions(options),
     );
   }
 
@@ -318,18 +347,39 @@ export class NonReactiveTransaction implements IExtendedStorageTransaction {
   }
 }
 
+/**
+ * Create a non-reactive transaction wrapper for Cell.sample().
+ * Reads won't trigger re-execution, but child cells will be reactive.
+ */
+export function createNonReactiveTransaction(
+  tx: IExtendedStorageTransaction,
+): TransactionWrapper {
+  return new TransactionWrapper(tx, { nonReactive: true, childCellTx: tx });
+}
+
+/**
+ * Create a transaction wrapper for Cell.sink() that uses a separate transaction
+ * for child cells.
+ */
+export function createChildCellTransaction(
+  tx: IExtendedStorageTransaction,
+  childCellTx: IExtendedStorageTransaction,
+): TransactionWrapper {
+  return new TransactionWrapper(tx, { childCellTx });
+}
+
 /**
  * Helper function to get the transaction to use for creating child cells from a
- * potentially wrapped NonReactiveTransaction. If the transaction is not wrapped,
- * returns it as-is.
+ * potentially wrapped transaction. If the transaction is not wrapped, returns
+ * it as-is.
  *
- * Used when creating child cells that should be reactive even when the parent
- * read was non-reactive (e.g., in Cell.sample()).
+ * Used when creating child cells that should use a different transaction than
+ * the parent read (e.g., in Cell.sample() or Cell.sink()).
  */
 export function getTransactionForChildCells(
   tx: IExtendedStorageTransaction | undefined,
 ): IExtendedStorageTransaction | undefined {
-  if (tx instanceof NonReactiveTransaction) {
+  if (tx instanceof TransactionWrapper) {
     return tx.getTransactionForChildCells();
   }
   return tx;

packages/runner/src/storage/interface.ts

@@ -922,5 +922,9 @@ export interface IAttestation {
   readonly value?: JSONValue;
 }
 
-// Re-export NonReactiveTransaction from implementation
-export { NonReactiveTransaction } from "./extended-storage-transaction.ts";
+// Re-export transaction wrapper utilities from implementation
+export {
+  createChildCellTransaction,
+  createNonReactiveTransaction,
+  TransactionWrapper,
+} from "./extended-storage-transaction.ts";