@fragno-dev/db 0.1.14 → 0.1.15

package/src/query/unit-of-work.ts

@@ -157,6 +157,7 @@ export type RetrievalOperation<
       indexName: string;
       options: FindOptions<TTable, SelectClause<TTable>>;
       withCursor?: boolean;
+      withSingleResult?: boolean;
     }
   | {
       type: "count";
@@ -198,6 +199,13 @@ export type MutationOperation<
       table: TTable["name"];
       id: FragnoId | string;
       checkVersion: boolean;
+    }
+  | {
+      type: "check";
+      schema: TSchema;
+      namespace?: string;
+      table: TTable["name"];
+      id: FragnoId;
     };
 
 /**
@@ -211,6 +219,12 @@ export interface CompiledMutation<TOutput> {
    * null means don't check affected rows (e.g., for create operations).
    */
   expectedAffectedRows: number | null;
+  /**
+   * Number of rows this SELECT query must return for the transaction to succeed.
+   * Used for check operations to verify version without modifying data.
+   * null means this is not a SELECT query that needs row count validation.
+   */
+  expectedReturnedRows: number | null;
 }
 
 /**
@@ -862,13 +876,14 @@ export function buildJoinIndexed<TTable extends AnyTable, TJoinOut>(
 }
 
 /**
- * Base interface for Unit of Work with schema-agnostic methods only.
- * This allows UOW instances to be passed between services that use different schemas.
+ * Full Unit of Work interface with all operations including execution.
+ * This allows UOW instances to be passed between different contexts that use different schemas.
  */
-export interface IUnitOfWorkBase {
+export interface IUnitOfWork {
   // Getters (schema-agnostic)
   readonly state: UOWState;
   readonly name: string | undefined;
+  readonly nonce: string;
   readonly retrievalPhase: Promise<unknown[]>;
   readonly mutationPhase: Promise<void>;
 
@@ -881,30 +896,238 @@ export interface IUnitOfWorkBase {
   getMutationOperations(): ReadonlyArray<MutationOperation<AnySchema>>;
   getCreatedIds(): FragnoId[];
 
+  // Parent-child relationships
+  restrict(): IUnitOfWork;
+
+  // Reset for retry support
+  reset(): void;
+
   // Schema-specific view (for cross-schema operations)
   forSchema<TOtherSchema extends AnySchema>(
     schema: TOtherSchema,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ): UnitOfWorkSchemaView<TOtherSchema, [], any>;
+  ): TypedUnitOfWork<TOtherSchema, [], any>;
 }
 
-export function createUnitOfWork<
-  const TSchema extends AnySchema,
-  const TRetrievalResults extends unknown[] = [],
-  const TRawInput = unknown,
->(
-  schema: TSchema,
+/**
+ * Restricted UOW interface without execute methods.
+ * Useful when you want to allow building operations but not executing them,
+ * to prevent deadlocks or enforce execution control at a higher level.
+ *
+ * Note: This is just a marker interface. Restriction is enforced by the UnitOfWork class itself.
+ */
+export interface IUnitOfWorkRestricted
+  extends Omit<IUnitOfWork, "executeRetrieve" | "executeMutations"> {}
+
+export function createUnitOfWork(
   compiler: UOWCompiler<unknown>,
-  executor: UOWExecutor<unknown, TRawInput>,
-  decoder: UOWDecoder<TRawInput>,
+  executor: UOWExecutor<unknown, unknown>,
+  decoder: UOWDecoder<unknown>,
+  schemaNamespaceMap?: WeakMap<AnySchema, string>,
   name?: string,
-): UnitOfWork<TSchema, TRetrievalResults, TRawInput> {
-  return new UnitOfWork(schema, compiler, executor, decoder, name);
+): UnitOfWork {
+  return new UnitOfWork(compiler, executor, decoder, name, undefined, schemaNamespaceMap);
 }
 
 export interface UnitOfWorkConfig {
   dryRun?: boolean;
   onQuery?: (query: unknown) => void;
+  nonce?: string;
+}
+
+/**
+ * Encapsulates a promise with its resolver/rejecter functions.
+ * Simplifies management of deferred promises with built-in error handling.
+ */
+class DeferredPromise<T> {
+  #resolve?: (value: T) => void;
+  #reject?: (error: Error) => void;
+  #promise: Promise<T>;
+
+  constructor() {
+    const { promise, resolve, reject } = Promise.withResolvers<T>();
+    this.#promise = promise;
+    this.#resolve = resolve;
+    this.#reject = reject;
+    // Attach no-op error handler to prevent unhandled rejection warnings
+    this.#promise.catch(() => {});
+  }
+
+  get promise(): Promise<T> {
+    return this.#promise;
+  }
+
+  resolve(value: T): void {
+    this.#resolve?.(value);
+  }
+
+  reject(error: Error): void {
+    this.#reject?.(error);
+  }
+
+  /**
+   * Reset to a new promise
+   */
+  reset(): void {
+    const { promise, resolve, reject } = Promise.withResolvers<T>();
+    this.#promise = promise;
+    this.#resolve = resolve;
+    this.#reject = reject;
+    // Attach no-op error handler to prevent unhandled rejection warnings
+    this.#promise.catch(() => {});
+  }
+}
+
+/**
+ * Tracks readiness signals from a group of children.
+ * Maintains a promise that resolves when all registered children have signaled.
+ */
+class ReadinessTracker {
+  #expectedCount = 0;
+  #signalCount = 0;
+  #resolve?: () => void;
+  #promise: Promise<void> = Promise.resolve();
+
+  get promise(): Promise<void> {
+    return this.#promise;
+  }
+
+  /**
+   * Register that we're expecting a signal from a child
+   */
+  registerChild(): void {
+    if (this.#expectedCount === 0) {
+      // First child - create new promise
+      const { promise, resolve } = Promise.withResolvers<void>();
+      this.#promise = promise;
+      this.#resolve = resolve;
+    }
+    this.#expectedCount++;
+  }
+
+  /**
+   * Signal that one child is ready
+   */
+  signal(): void {
+    this.#signalCount++;
+    if (this.#signalCount >= this.#expectedCount && this.#resolve) {
+      this.#resolve();
+    }
+  }
+
+  /**
+   * Reset to initial state
+   */
+  reset(): void {
+    this.#expectedCount = 0;
+    this.#signalCount = 0;
+    this.#resolve = undefined;
+    this.#promise = Promise.resolve();
+  }
+}
+
+/**
+ * Manages parent-child relationships and readiness coordination for Unit of Work instances.
+ * This allows parent UOWs to wait for all child UOWs to signal readiness before executing phases.
+ */
+class UOWChildCoordinator<TRawInput> {
+  #parent: UnitOfWork<TRawInput> | null = null;
+  #parentCoordinator: UOWChildCoordinator<TRawInput> | null = null;
+  #children: Set<UnitOfWork<TRawInput>> = new Set();
+  #isRestricted = false;
+
+  #retrievalTracker = new ReadinessTracker();
+  #mutationTracker = new ReadinessTracker();
+
+  get isRestricted(): boolean {
+    return this.#isRestricted;
+  }
+
+  get parent(): UnitOfWork<TRawInput> | null {
+    return this.#parent;
+  }
+
+  get children(): ReadonlySet<UnitOfWork<TRawInput>> {
+    return this.#children;
+  }
+
+  get retrievalReadinessPromise(): Promise<void> {
+    return this.#retrievalTracker.promise;
+  }
+
+  get mutationReadinessPromise(): Promise<void> {
+    return this.#mutationTracker.promise;
+  }
+
+  /**
+   * Mark this UOW as a restricted child of the given parent
+   */
+  setAsRestricted(
+    parent: UnitOfWork<TRawInput>,
+    parentCoordinator: UOWChildCoordinator<TRawInput>,
+  ): void {
+    this.#parent = parent;
+    this.#parentCoordinator = parentCoordinator;
+    this.#isRestricted = true;
+  }
+
+  /**
+   * Register a child UOW
+   */
+  addChild(child: UnitOfWork<TRawInput>): void {
+    this.#children.add(child);
+    this.#retrievalTracker.registerChild();
+    this.#mutationTracker.registerChild();
+  }
+
+  /**
+   * Signal that this child is ready for retrieval phase execution.
+   * Only valid for restricted (child) UOWs.
+   */
+  signalReadyForRetrieval(): void {
+    if (!this.#parentCoordinator) {
+      throw new Error("signalReadyForRetrieval() can only be called on restricted child UOWs");
+    }
+
+    this.#parentCoordinator.notifyChildReadyForRetrieval();
+  }
+
+  /**
+   * Signal that this child is ready for mutation phase execution.
+   * Only valid for restricted (child) UOWs.
+   */
+  signalReadyForMutation(): void {
+    if (!this.#parentCoordinator) {
+      throw new Error("signalReadyForMutation() can only be called on restricted child UOWs");
+    }
+
+    this.#parentCoordinator.notifyChildReadyForMutation();
+  }
+
+  /**
+   * Notify this coordinator that a child is ready for retrieval (internal use).
+   * Called by child UOWs when they signal readiness.
+   */
+  notifyChildReadyForRetrieval(): void {
+    this.#retrievalTracker.signal();
+  }
+
+  /**
+   * Notify this coordinator that a child is ready for mutation (internal use).
+   * Called by child UOWs when they signal readiness.
+   */
+  notifyChildReadyForMutation(): void {
+    this.#mutationTracker.signal();
+  }
+
+  /**
+   * Reset coordination state for retry support
+   */
+  reset(): void {
+    this.#children.clear();
+    this.#retrievalTracker.reset();
+    this.#mutationTracker.reset();
+  }
 }
 
 /**
@@ -914,19 +1137,22 @@ export interface UnitOfWorkConfig {
  * 1. Retrieval phase: Read operations to fetch entities with their versions
  * 2. Mutation phase: Write operations that check versions before committing
  *
+ * This is the untyped base storage. Use TypedUnitOfWork for type-safe operations.
+ *
  * @example
  * ```ts
  * const uow = queryEngine.createUnitOfWork("update-user-balance");
+ * const typedUow = uow.forSchema(mySchema);
  *
  * // Retrieval phase
- * uow.find("users", (b) => b.where("primary", (eb) => eb("id", "=", userId)));
+ * typedUow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId)));
  *
  * // Execute retrieval and transition to mutation phase
  * const [users] = await uow.executeRetrieve();
  *
  * // Mutation phase with version check
  * const user = users[0];
- * uow.update("users", user.id, (b) => b.set({ balance: newBalance }).check());
+ * typedUow.update("users", user.id, (b) => b.set({ balance: newBalance }).check());
  *
  * // Execute mutations
  * const { success } = await uow.executeMutations();
@@ -935,20 +1161,14 @@ export interface UnitOfWorkConfig {
  * }
  * ```
  */
-export class UnitOfWork<
-  const TSchema extends AnySchema,
-  const TRetrievalResults extends unknown[] = [],
-  const TRawInput = unknown,
-> implements IUnitOfWorkBase
-{
-  #schema: TSchema;
-
+export class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
   #name?: string;
   #config?: UnitOfWorkConfig;
+  #nonce: string;
 
   #state: UOWState = "building-retrieval";
 
-  // Operations can now come from any schema
+  // Operations can come from any schema
   #retrievalOps: RetrievalOperation<AnySchema>[] = [];
   #mutationOps: MutationOperation<AnySchema>[] = [];
 
@@ -957,17 +1177,21 @@ export class UnitOfWork<
   #decoder: UOWDecoder<TRawInput>;
   #schemaNamespaceMap?: WeakMap<AnySchema, string>;
 
-  #retrievalResults?: TRetrievalResults;
+  #retrievalResults?: unknown[];
   #createdInternalIds: (bigint | null)[] = [];
 
   // Phase coordination promises
-  #retrievalPhaseResolve?: (value: TRetrievalResults) => void;
-  #mutationPhaseResolve?: () => void;
-  #retrievalPhasePromise: Promise<TRetrievalResults>;
-  #mutationPhasePromise: Promise<void>;
+  #retrievalPhaseDeferred = new DeferredPromise<unknown[]>();
+  #mutationPhaseDeferred = new DeferredPromise<void>();
+
+  // Error tracking
+  #retrievalError: Error | null = null;
+  #mutationError: Error | null = null;
+
+  // Child coordination
+  #coordinator: UOWChildCoordinator<TRawInput> = new UOWChildCoordinator();
 
   constructor(
-    schema: TSchema,
     compiler: UOWCompiler<unknown>,
     executor: UOWExecutor<unknown, TRawInput>,
     decoder: UOWDecoder<TRawInput>,
@@ -975,381 +1199,196 @@ export class UnitOfWork<
     config?: UnitOfWorkConfig,
     schemaNamespaceMap?: WeakMap<AnySchema, string>,
   ) {
-    this.#schema = schema;
     this.#compiler = compiler;
     this.#executor = executor;
     this.#decoder = decoder;
+    this.#schemaNamespaceMap = schemaNamespaceMap;
     this.#name = name;
     this.#config = config;
-    this.#schemaNamespaceMap = schemaNamespaceMap;
-
-    // Initialize phase coordination promises
-    this.#retrievalPhasePromise = new Promise<TRetrievalResults>((resolve) => {
-      this.#retrievalPhaseResolve = resolve;
-    });
-    this.#mutationPhasePromise = new Promise<void>((resolve) => {
-      this.#mutationPhaseResolve = resolve;
-    });
-  }
-
-  get schema(): TSchema {
-    return this.#schema;
-  }
-
-  get $results(): Prettify<TRetrievalResults> {
-    throw new Error("type only");
+    this.#nonce = config?.nonce ?? crypto.randomUUID();
   }
 
   /**
-   * Get a schema-specific view of this UOW for type-safe operations
-   * Returns a wrapper that uses a different schema for operations.
+   * Get a schema-specific typed view of this UOW for type-safe operations.
+   * Returns a wrapper that provides typed operations for the given schema.
    * The namespace is automatically resolved from the schema-namespace map.
    */
-  forSchema<TOtherSchema extends AnySchema>(
+  forSchema<TOtherSchema extends AnySchema, TRawInput>(
     schema: TOtherSchema,
-  ): UnitOfWorkSchemaView<TOtherSchema, [], TRawInput> {
+  ): TypedUnitOfWork<TOtherSchema, [], TRawInput> {
     // Look up namespace from map
     const resolvedNamespace = this.#schemaNamespaceMap?.get(schema);
 
-    // Safe cast: UnitOfWorkSchemaView starts with empty result types
-    // As operations are added, the types will accumulate correctly
-    return new UnitOfWorkSchemaView(
-      schema,
-      resolvedNamespace,
-      this as unknown as UnitOfWork<AnySchema, unknown[], TRawInput>,
-    );
+    return new TypedUnitOfWork(schema, resolvedNamespace, this as unknown as UnitOfWork<TRawInput>);
   }
 
-  get state(): UOWState {
-    return this.#state;
-  }
+  /**
+   * Create a restricted child UOW that cannot execute phases.
+   * The child shares the same operation storage but must signal readiness
+   * before the parent can execute each phase.
+   */
+  restrict(): UnitOfWork<TRawInput> {
+    const child = new UnitOfWork(
+      this.#compiler,
+      this.#executor,
+      this.#decoder,
+      this.#name,
+      { ...this.#config, nonce: this.#nonce },
+      this.#schemaNamespaceMap,
+    );
+    child.#coordinator.setAsRestricted(this, this.#coordinator);
 
-  get name(): string | undefined {
-    return this.#name;
+    // Share state with parent
+    child.#state = this.#state;
+    child.#retrievalOps = this.#retrievalOps;
+    child.#mutationOps = this.#mutationOps;
+    child.#retrievalResults = this.#retrievalResults;
+    child.#createdInternalIds = this.#createdInternalIds;
+    child.#retrievalPhaseDeferred = this.#retrievalPhaseDeferred;
+    child.#mutationPhaseDeferred = this.#mutationPhaseDeferred;
+    child.#retrievalError = this.#retrievalError;
+    child.#mutationError = this.#mutationError;
+
+    this.#coordinator.addChild(child);
+
+    // For synchronous usage (the common case), immediately signal readiness
+    // This allows services called directly from handlers to work without explicit signaling
+    child.signalReadyForRetrieval();
+    child.signalReadyForMutation();
+
+    return child;
   }
 
   /**
-   * Promise that resolves when the retrieval phase is executed
-   * Service methods can await this to coordinate multi-phase logic
+   * Signal that this child is ready for retrieval phase execution.
+   * Only valid for restricted (child) UOWs.
    */
-  get retrievalPhase(): Promise<TRetrievalResults> {
-    return this.#retrievalPhasePromise;
+  signalReadyForRetrieval(): void {
+    this.#coordinator.signalReadyForRetrieval();
   }
 
   /**
-   * Promise that resolves when the mutation phase is executed
-   * Service methods can await this to coordinate multi-phase logic
+   * Signal that this child is ready for mutation phase execution.
+   * Only valid for restricted (child) UOWs.
    */
-  get mutationPhase(): Promise<void> {
-    return this.#mutationPhasePromise;
+  signalReadyForMutation(): void {
+    this.#coordinator.signalReadyForMutation();
   }
 
   /**
-   * Execute the retrieval phase and transition to mutation phase
-   * Returns all results from find operations
+   * Reset the UOW to initial state for retry support.
+   * Clears operations, resets state, and resets phase promises.
    */
-  async executeRetrieve(): Promise<TRetrievalResults> {
-    if (this.#state !== "building-retrieval") {
-      throw new Error(
-        `Cannot execute retrieval from state ${this.#state}. Must be in building-retrieval state.`,
-      );
-    }
-
-    if (this.#retrievalOps.length === 0) {
-      this.#state = "building-mutation";
-      const emptyResults = [] as unknown as TRetrievalResults;
-      this.#retrievalPhaseResolve?.(emptyResults);
-      return emptyResults;
+  reset(): void {
+    if (this.#coordinator.isRestricted) {
+      throw new Error("reset() cannot be called on restricted child UOWs");
     }
 
-    // Compile retrieval operations using single compiler
-    const retrievalBatch: unknown[] = [];
-    for (const op of this.#retrievalOps) {
-      const compiled = this.#compiler.compileRetrievalOperation(op);
-      if (compiled !== null) {
-        this.#config?.onQuery?.(compiled);
-        retrievalBatch.push(compiled);
-      }
-    }
+    // Clear operations
+    this.#retrievalOps = [];
+    this.#mutationOps = [];
+    this.#retrievalResults = undefined;
+    this.#createdInternalIds = [];
 
-    if (this.#config?.dryRun) {
-      this.#state = "executed";
-      return [] as unknown as TRetrievalResults;
-    }
+    // Reset state
+    this.#state = "building-retrieval";
+    this.#retrievalError = null;
+    this.#mutationError = null;
 
-    // Execute all operations together (ideally in same transaction)
-    const rawResults = await this.#executor.executeRetrievalPhase(retrievalBatch);
+    // Reset phase promises
+    this.#retrievalPhaseDeferred.reset();
+    this.#mutationPhaseDeferred.reset();
 
-    // Decode results using single decoder
-    const results = this.#decoder(rawResults, this.#retrievalOps);
+    // Reset child coordination
+    this.#coordinator.reset();
+  }
 
-    // Store results and transition to mutation phase
-    this.#retrievalResults = results as TRetrievalResults;
-    this.#state = "building-mutation";
+  get state(): UOWState {
+    return this.#state;
+  }
 
-    // Resolve the retrieval phase promise to unblock waiting service methods
-    this.#retrievalPhaseResolve?.(this.#retrievalResults);
+  get name(): string | undefined {
+    return this.#name;
+  }
 
-    return this.#retrievalResults;
+  get nonce(): string {
+    return this.#nonce;
   }
 
   /**
-   * Add a find operation using a builder callback (retrieval phase only)
+   * Promise that resolves when the retrieval phase is executed
+   * Service methods can await this to coordinate multi-phase logic
    */
-  find<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
-    tableName: TTableName,
-    builderFn: (
-      builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
-    ) => TBuilderResult,
-  ): UnitOfWork<
-    TSchema,
-    [
-      ...TRetrievalResults,
-      SelectResult<
-        TSchema["tables"][TTableName],
-        ExtractJoinOut<TBuilderResult>,
-        Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>
-      >[],
-    ],
-    TRawInput
-  >;
-  find<TTableName extends keyof TSchema["tables"] & string>(
-    tableName: TTableName,
-  ): UnitOfWork<
-    TSchema,
-    [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], {}, true>[]],
-    TRawInput
-  >;
-  find<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
-    tableName: TTableName,
-    builderFn?: (
-      builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
-    ) => TBuilderResult,
-  ): UnitOfWork<
-    TSchema,
-    [
-      ...TRetrievalResults,
-      SelectResult<
-        TSchema["tables"][TTableName],
-        ExtractJoinOut<TBuilderResult>,
-        Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>
-      >[],
-    ],
-    TRawInput
-  > {
-    if (this.#state !== "building-retrieval") {
-      throw new Error(
-        `find() can only be called during retrieval phase. Current state: ${this.#state}`,
-      );
-    }
-
-    const table = this.#schema.tables[tableName];
-    if (!table) {
-      throw new Error(`Table ${tableName} not found in schema`);
-    }
-
-    // Create builder, pass to callback (or use default), then extract configuration
-    const builder = new FindBuilder(tableName, table as TSchema["tables"][TTableName]);
-    if (builderFn) {
-      builderFn(builder);
-    } else {
-      // Default to primary index with no filter
-      builder.whereIndex("primary");
-    }
-    const { indexName, options, type } = builder.build();
-
-    this.#retrievalOps.push({
-      type,
-      schema: this.#schema,
-      // Safe: we know the table is part of the schema from the find() method
-      table: table as TSchema["tables"][TTableName],
-      indexName,
-      // Safe: we're storing the options for later compilation
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      options: options as any,
-    });
-
-    // Safe: return type is correctly specified in the method signature
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return this as any;
+  get retrievalPhase(): Promise<unknown[]> {
+    return this.#retrievalPhaseDeferred.promise;
   }
 
   /**
-   * Add a find operation with cursor metadata (retrieval phase only)
+   * Promise that resolves when the mutation phase is executed
+   * Service methods can await this to coordinate multi-phase logic
    */
-  findWithCursor<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
-    tableName: TTableName,
-    builderFn: (
-      // We omit "build" because we don't want to expose it to the user
-      builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
-    ) => TBuilderResult,
-  ): UnitOfWork<
-    TSchema,
-    [
-      ...TRetrievalResults,
-      CursorResult<
-        SelectResult<
-          TSchema["tables"][TTableName],
-          ExtractJoinOut<TBuilderResult>,
-          Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>
-        >
-      >,
-    ],
-    TRawInput
-  > {
-    if (this.#state !== "building-retrieval") {
-      throw new Error(
-        `findWithCursor() can only be called during retrieval phase. Current state: ${this.#state}`,
-      );
-    }
-
-    const table = this.#schema.tables[tableName];
-    if (!table) {
-      throw new Error(`Table ${tableName} not found in schema`);
-    }
-
-    // Create builder and pass to callback
-    const builder = new FindBuilder(tableName, table as TSchema["tables"][TTableName]);
-    builderFn(builder);
-    const { indexName, options, type } = builder.build();
-
-    this.#retrievalOps.push({
-      type,
-      schema: this.#schema,
-      // Safe: we know the table is part of the schema from the findWithCursor() method
-      table: table as TSchema["tables"][TTableName],
-      indexName,
-      // Safe: we're storing the options for later compilation
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      options: options as any,
-      withCursor: true,
-    });
-
-    // Safe: return type is correctly specified in the method signature
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return this as any;
+  get mutationPhase(): Promise<void> {
+    return this.#mutationPhaseDeferred.promise;
   }
 
   /**
-   * Add a create operation (mutation phase only)
-   * Returns a FragnoId with the external ID that can be used immediately in subsequent operations
+   * Execute the retrieval phase and transition to mutation phase
+   * Returns all results from find operations
    */
-  create<TableName extends keyof TSchema["tables"] & string>(
-    table: TableName,
-    values: TableToInsertValues<TSchema["tables"][TableName]>,
-  ): FragnoId {
-    if (this.#state === "executed") {
-      throw new Error(`create() can only be called during mutation phase.`);
+  async executeRetrieve(): Promise<unknown[]> {
+    if (this.#coordinator.isRestricted) {
+      throw new Error("executeRetrieve() cannot be called on restricted child UOWs");
     }
 
-    const tableSchema = this.#schema.tables[table];
-    if (!tableSchema) {
-      throw new Error(`Table ${table} not found in schema`);
+    if (this.#state !== "building-retrieval") {
+      throw new Error(
+        `Cannot execute retrieval from state ${this.#state}. Must be in building-retrieval state.`,
+      );
     }
 
-    const idColumn = tableSchema.getIdColumn();
-    let externalId: string;
-    let updatedValues = values;
-
-    // Check if ID value is provided in values
-    const providedIdValue = (values as Record<string, unknown>)[idColumn.ormName];
+    try {
+      // Wait for all children to signal readiness
+      await this.#coordinator.retrievalReadinessPromise;
 
-    if (providedIdValue !== undefined) {
-      // Extract string from FragnoId or use string directly
-      if (
-        typeof providedIdValue === "object" &&
-        providedIdValue !== null &&
-        "externalId" in providedIdValue
-      ) {
-        externalId = (providedIdValue as FragnoId).externalId;
-      } else {
-        externalId = providedIdValue as string;
+      if (this.#retrievalOps.length === 0) {
+        this.#state = "building-mutation";
+        const emptyResults: unknown[] = [];
+        this.#retrievalPhaseDeferred.resolve(emptyResults);
+        return emptyResults;
       }
-    } else {
-      // Generate using the column's default configuration
-      const generated = idColumn.generateDefaultValue();
-      if (generated === undefined) {
-        throw new Error(
-          `No ID value provided and ID column ${idColumn.ormName} has no default generator`,
-        );
-      }
-      externalId = generated as string;
 
-      // Add the generated ID to values so it's used in the insert
-      updatedValues = {
-        ...values,
-        [idColumn.ormName]: externalId,
-      } as TableToInsertValues<TSchema["tables"][TableName]>;
-    }
+      // Compile retrieval operations using single compiler
+      const retrievalBatch: unknown[] = [];
+      for (const op of this.#retrievalOps) {
+        const compiled = this.#compiler.compileRetrievalOperation(op);
+        if (compiled !== null) {
+          this.#config?.onQuery?.(compiled);
+          retrievalBatch.push(compiled);
+        }
+      }
 
-    this.#mutationOps.push({
-      type: "create",
-      schema: this.#schema,
-      table,
-      values: updatedValues,
-      generatedExternalId: externalId,
-    });
+      if (this.#config?.dryRun) {
+        this.#state = "executed";
+        const emptyResults: unknown[] = [];
+        this.#retrievalPhaseDeferred.resolve(emptyResults);
+        return emptyResults;
+      }
 
-    return FragnoId.fromExternal(externalId, 0);
-  }
+      const rawResults = await this.#executor.executeRetrievalPhase(retrievalBatch);
 
-  /**
-   * Add an update operation using a builder callback (mutation phase only)
-   */
-  update<TableName extends keyof TSchema["tables"] & string>(
-    table: TableName,
-    id: FragnoId | string,
-    builderFn: (
-      // We omit "build" because we don't want to expose it to the user
-      builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">,
-    ) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build"> | void,
-  ): void {
-    if (this.#state === "executed") {
-      throw new Error(`update() can only be called during mutation phase.`);
-    }
+      const results = this.#decoder(rawResults, this.#retrievalOps);
 
-    // Create builder, pass to callback, then extract configuration
-    const builder = new UpdateBuilder<TSchema["tables"][TableName]>(table, id);
-    builderFn(builder);
-    const { id: opId, checkVersion, set } = builder.build();
+      // Store results and transition to mutation phase
+      this.#retrievalResults = results;
+      this.#state = "building-mutation";
 
-    this.#mutationOps.push({
-      type: "update",
-      schema: this.#schema,
-      table,
-      id: opId,
-      checkVersion,
-      set,
-    });
-  }
+      this.#retrievalPhaseDeferred.resolve(this.#retrievalResults);
 
-  /**
-   * Add a delete operation using a builder callback (mutation phase only)
-   */
-  delete<TableName extends keyof TSchema["tables"] & string>(
-    table: TableName,
-    id: FragnoId | string,
-    builderFn?: (
-      // We omit "build" because we don't want to expose it to the user
-      builder: Omit<DeleteBuilder, "build">,
-    ) => Omit<DeleteBuilder, "build"> | void,
-  ): void {
-    if (this.#state === "executed") {
-      throw new Error(`delete() can only be called during mutation phase.`);
+      return this.#retrievalResults;
+    } catch (error) {
+      this.#retrievalError = error instanceof Error ? error : new Error(String(error));
+      throw error;
     }
-
-    // Create builder, optionally pass to callback, then extract configuration
-    const builder = new DeleteBuilder(table, id);
-    builderFn?.(builder);
-    const { id: opId, checkVersion } = builder.build();
-
-    this.#mutationOps.push({
-      type: "delete",
-      schema: this.#schema,
-      table,
-      id: opId,
-      checkVersion,
-    });
   }
 
   /**
@@ -1357,41 +1396,54 @@ export class UnitOfWork<
    * Returns success flag indicating if mutations completed without conflicts
    */
   async executeMutations(): Promise<{ success: boolean }> {
+    if (this.#coordinator.isRestricted) {
+      throw new Error("executeMutations() cannot be called on restricted child UOWs");
+    }
+
     if (this.#state === "executed") {
       throw new Error(`Cannot execute mutations from state ${this.#state}.`);
     }
 
-    // Compile mutation operations using single compiler
-    const mutationBatch: CompiledMutation<unknown>[] = [];
-    for (const op of this.#mutationOps) {
-      const compiled = this.#compiler.compileMutationOperation(op);
-      if (compiled !== null) {
-        this.#config?.onQuery?.(compiled);
-        mutationBatch.push(compiled);
+    try {
+      // Wait for all children to signal readiness
+      await this.#coordinator.mutationReadinessPromise;
+
+      // Compile mutation operations using single compiler
+      const mutationBatch: CompiledMutation<unknown>[] = [];
+      for (const op of this.#mutationOps) {
+        const compiled = this.#compiler.compileMutationOperation(op);
+        if (compiled !== null) {
+          this.#config?.onQuery?.(compiled);
+          mutationBatch.push(compiled);
+        }
       }
-    }
 
-    if (this.#config?.dryRun) {
-      this.#state = "executed";
-      return {
-        success: true,
-      };
-    }
+      if (this.#config?.dryRun) {
+        this.#state = "executed";
+        this.#mutationPhaseDeferred.resolve();
+        return {
+          success: true,
+        };
+      }
 
-    // Execute mutation phase
-    const result = await this.#executor.executeMutationPhase(mutationBatch);
-    this.#state = "executed";
+      // Execute mutation phase
+      const result = await this.#executor.executeMutationPhase(mutationBatch);
+      this.#state = "executed";
 
-    if (result.success) {
-      this.#createdInternalIds = result.createdInternalIds;
-    }
+      if (result.success) {
+        this.#createdInternalIds = result.createdInternalIds;
+      }
 
-    // Resolve the mutation phase promise to unblock waiting service methods
-    this.#mutationPhaseResolve?.();
+      // Resolve the mutation phase promise to unblock waiting service methods
+      this.#mutationPhaseDeferred.resolve();
 
-    return {
-      success: result.success,
-    };
+      return {
+        success: result.success,
+      };
+    } catch (error) {
+      this.#mutationError = error instanceof Error ? error : new Error(String(error));
+      throw error;
+    }
   }
 
   /**
@@ -1410,18 +1462,26 @@ export class UnitOfWork<
 
   /**
    * @internal
-   * Add a retrieval operation (used by SchemaView)
+   * Add a retrieval operation (used by TypedUnitOfWork)
    */
   addRetrievalOperation(op: RetrievalOperation<AnySchema>): number {
+    if (this.#state !== "building-retrieval") {
+      throw new Error(
+        `Cannot add retrieval operation in state ${this.#state}. Must be in building-retrieval state.`,
+      );
+    }
     this.#retrievalOps.push(op);
     return this.#retrievalOps.length - 1;
   }
 
   /**
    * @internal
-   * Add a mutation operation (used by SchemaView)
+   * Add a mutation operation (used by TypedUnitOfWork)
    */
   addMutationOperation(op: MutationOperation<AnySchema>): void {
+    if (this.#state === "executed") {
+      throw new Error(`Cannot add mutation operation in executed state.`);
+    }
     this.#mutationOps.push(op);
   }
 
@@ -1494,28 +1554,26 @@ export class UnitOfWork<
 }
 
 /**
- * A lightweight wrapper around a parent UOW that provides type-safe operations for a different schema.
- * All operations are stored in the parent UOW, but this wrapper ensures the correct schema is used.
+ * A typed facade around a UnitOfWork that provides type-safe operations for a specific schema.
+ * All operations are stored in the underlying UOW, but this facade ensures type safety and
+ * filters retrieval results to only include operations added through this facade.
  */
-export class UnitOfWorkSchemaView<
+export class TypedUnitOfWork<
   const TSchema extends AnySchema,
   const TRetrievalResults extends unknown[] = [],
   const TRawInput = unknown,
-> implements IUnitOfWorkBase
+> implements IUnitOfWork
 {
   #schema: TSchema;
   #namespace?: string;
-  #parent: UnitOfWork<AnySchema, unknown[], TRawInput>;
+  #uow: UnitOfWork<TRawInput>;
   #operationIndices: number[] = [];
+  #cachedRetrievalPhase?: Promise<TRetrievalResults>;
 
-  constructor(
-    schema: TSchema,
-    namespace: string | undefined,
-    parent: UnitOfWork<AnySchema, unknown[], TRawInput>,
-  ) {
+  constructor(schema: TSchema, namespace: string | undefined, uow: UnitOfWork<TRawInput>) {
     this.#schema = schema;
     this.#namespace = namespace;
-    this.#parent = parent;
+    this.#uow = uow;
   }
 
   get $results(): Prettify<TRetrievalResults> {
@@ -1527,43 +1585,81 @@ export class UnitOfWorkSchemaView<
   }
 
   get name(): string | undefined {
-    return this.#parent.name;
+    return this.#uow.name;
+  }
+
+  get nonce(): string {
+    return this.#uow.nonce;
   }
 
   get state() {
-    return this.#parent.state;
+    return this.#uow.state;
   }
 
   get retrievalPhase(): Promise<TRetrievalResults> {
-    // Filter parent's results to only include operations from this view
-    return this.#parent.retrievalPhase.then((allResults) => {
-      const filteredResults = this.#operationIndices.map((index) => allResults[index]);
-      return filteredResults as TRetrievalResults;
-    });
+    // Cache the filtered promise to avoid recreating it on every access
+    if (!this.#cachedRetrievalPhase) {
+      this.#cachedRetrievalPhase = this.#uow.retrievalPhase.then((allResults) => {
+        const allOperations = this.#uow.getRetrievalOperations();
+        const filteredResults = this.#operationIndices.map((opIndex) => {
+          const result = allResults[opIndex];
+          const operation = allOperations[opIndex];
+          // Transform array to single item for findFirst operations
+          if (operation?.type === "find" && operation.withSingleResult) {
+            return Array.isArray(result) ? (result[0] ?? null) : result;
+          }
+          return result;
+        });
+        return filteredResults as TRetrievalResults;
+      });
+    }
+    return this.#cachedRetrievalPhase;
   }
 
   get mutationPhase(): Promise<void> {
-    return this.#parent.mutationPhase;
+    return this.#uow.mutationPhase;
   }
 
   getRetrievalOperations() {
-    return this.#parent.getRetrievalOperations();
+    return this.#uow.getRetrievalOperations();
   }
 
   getMutationOperations() {
-    return this.#parent.getMutationOperations();
+    return this.#uow.getMutationOperations();
   }
 
   getCreatedIds() {
-    return this.#parent.getCreatedIds();
+    return this.#uow.getCreatedIds();
   }
 
-  async executeRetrieve(): Promise<unknown[]> {
-    return this.#parent.executeRetrieve();
+  async executeRetrieve(): Promise<TRetrievalResults> {
+    return this.#uow.executeRetrieve() as Promise<TRetrievalResults>;
   }
 
   async executeMutations(): Promise<{ success: boolean }> {
-    return this.#parent.executeMutations();
+    return this.#uow.executeMutations();
+  }
+
+  restrict(): IUnitOfWork {
+    return this.#uow.restrict();
+  }
+
+  reset(): void {
+    return this.#uow.reset();
+  }
+
+  forSchema<TOtherSchema extends AnySchema>(
+    schema: TOtherSchema,
+  ): TypedUnitOfWork<TOtherSchema, [], TRawInput> {
+    return this.#uow.forSchema(schema);
+  }
+
+  compile<TOutput>(compiler: UOWCompiler<TOutput>): {
+    name?: string;
+    retrievalBatch: TOutput[];
+    mutationBatch: CompiledMutation<TOutput>[];
+  } {
+    return this.#uow.compile(compiler);
   }
 
   find<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
@@ -1571,7 +1667,7 @@ export class UnitOfWorkSchemaView<
     builderFn: (
       builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
     ) => TBuilderResult,
-  ): UnitOfWorkSchemaView<
+  ): TypedUnitOfWork<
     TSchema,
     [
       ...TRetrievalResults,
@@ -1585,7 +1681,7 @@ export class UnitOfWorkSchemaView<
   >;
   find<TTableName extends keyof TSchema["tables"] & string>(
     tableName: TTableName,
-  ): UnitOfWorkSchemaView<
+  ): TypedUnitOfWork<
     TSchema,
     [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], {}, true>[]],
     TRawInput
@@ -1595,7 +1691,7 @@ export class UnitOfWorkSchemaView<
     builderFn?: (
       builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
     ) => TBuilderResult,
-  ): UnitOfWorkSchemaView<
+  ): TypedUnitOfWork<
     TSchema,
     [
       ...TRetrievalResults,
@@ -1620,7 +1716,81 @@ export class UnitOfWorkSchemaView<
     }
     const { indexName, options, type } = builder.build();
 
-    const operationIndex = this.#parent.addRetrievalOperation({
+    const operationIndex = this.#uow.addRetrievalOperation({
+      type,
+      schema: this.#schema,
+      namespace: this.#namespace,
+      table: table as TSchema["tables"][TTableName],
+      indexName,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      options: options as any,
+    });
+
+    // Track which operation index belongs to this view
+    this.#operationIndices.push(operationIndex);
+
+    // Safe: return type is correctly specified in the method signature
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return this as any;
+  }
+
+  findFirst<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
+    tableName: TTableName,
+    builderFn: (
+      builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
+    ) => TBuilderResult,
+  ): TypedUnitOfWork<
+    TSchema,
+    [
+      ...TRetrievalResults,
+      SelectResult<
+        TSchema["tables"][TTableName],
+        ExtractJoinOut<TBuilderResult>,
+        Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>
+      > | null,
+    ],
+    TRawInput
+  >;
+  findFirst<TTableName extends keyof TSchema["tables"] & string>(
+    tableName: TTableName,
+  ): TypedUnitOfWork<
+    TSchema,
+    [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], {}, true> | null],
+    TRawInput
+  >;
+  findFirst<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(
+    tableName: TTableName,
+    builderFn?: (
+      builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
+    ) => TBuilderResult,
+  ): TypedUnitOfWork<
+    TSchema,
+    [
+      ...TRetrievalResults,
+      SelectResult<
+        TSchema["tables"][TTableName],
+        ExtractJoinOut<TBuilderResult>,
+        Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>
+      > | null,
+    ],
+    TRawInput
+  > {
+    const table = this.#schema.tables[tableName];
+    if (!table) {
+      throw new Error(`Table ${tableName} not found in schema`);
+    }
+
+    const builder = new FindBuilder(tableName, table as TSchema["tables"][TTableName]);
+    if (builderFn) {
+      builderFn(builder);
+    } else {
+      builder.whereIndex("primary");
+    }
+    // Automatically set pageSize to 1 for findFirst
+    builder.pageSize(1);
+    const { indexName, options, type } = builder.build();
+
+    const operationIndex = this.#uow.addRetrievalOperation({
       type,
       schema: this.#schema,
       namespace: this.#namespace,
@@ -1628,6 +1798,7 @@ export class UnitOfWorkSchemaView<
       indexName,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       options: options as any,
+      withSingleResult: true,
     });
 
     // Track which operation index belongs to this view
@@ -1643,7 +1814,7 @@ export class UnitOfWorkSchemaView<
     builderFn: (
       builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">,
     ) => TBuilderResult,
-  ): UnitOfWorkSchemaView<
+  ): TypedUnitOfWork<
     TSchema,
     [
       ...TRetrievalResults,
@@ -1666,7 +1837,7 @@ export class UnitOfWorkSchemaView<
     builderFn(builder);
     const { indexName, options, type } = builder.build();
 
-    const operationIndex = this.#parent.addRetrievalOperation({
+    const operationIndex = this.#uow.addRetrievalOperation({
       type,
       schema: this.#schema,
       namespace: this.#namespace,
@@ -1729,7 +1900,7 @@ export class UnitOfWorkSchemaView<
       } as TableToInsertValues<TSchema["tables"][TableName]>;
     }
 
-    this.#parent.addMutationOperation({
+    this.#uow.addMutationOperation({
       type: "create",
       schema: this.#schema,
       namespace: this.#namespace,
@@ -1752,7 +1923,7 @@ export class UnitOfWorkSchemaView<
     builderFn(builder);
     const { id: opId, checkVersion, set } = builder.build();
 
-    this.#parent.addMutationOperation({
+    this.#uow.addMutationOperation({
       type: "update",
       schema: this.#schema,
       namespace: this.#namespace,
@@ -1772,7 +1943,7 @@ export class UnitOfWorkSchemaView<
     builderFn?.(builder);
     const { id: opId, checkVersion } = builder.build();
 
-    this.#parent.addMutationOperation({
+    this.#uow.addMutationOperation({
       type: "delete",
       schema: this.#schema,
       namespace: this.#namespace,
@@ -1782,10 +1953,32 @@ export class UnitOfWorkSchemaView<
     });
   }
 
-  forSchema<TOtherSchema extends AnySchema>(
-    schema: TOtherSchema,
-  ): UnitOfWorkSchemaView<TOtherSchema, [], TRawInput> {
-    // Delegate to the parent's forSchema to create a new view
-    return this.#parent.forSchema(schema);
+  /**
+   * Check that a record's version hasn't changed since retrieval.
+   * This is useful for ensuring related records remain unchanged during a transaction.
+   *
+   * @param tableName - The table name
+   * @param id - The FragnoId with version information (string IDs are not allowed)
+   * @throws Error if the ID is a string without version information
+   *
+   * @example
+   * ```ts
+   * // Ensure both accounts haven't changed before creating a transfer
+   * uow.check("accounts", fromAccount.id);
+   * uow.check("accounts", toAccount.id);
+   * uow.create("transactions", { fromAccountId, toAccountId, amount });
+   * ```
+   */
+  check<TableName extends keyof TSchema["tables"] & string>(
+    tableName: TableName,
+    id: FragnoId,
+  ): void {
+    this.#uow.addMutationOperation({
+      type: "check",
+      schema: this.#schema,
+      namespace: this.#namespace,
+      table: tableName,
+      id,
+    });
   }
 }