Interface: BranchableScope<THandle, TReceipt, TSync>

Defined in: ports/branchable-scope.ts:17

Tier-3 runtime driver contract for branchable isolation scopes (capabilityTier: 'branchable').

Extends CheckpointableScope with Copy-on-Write child forking (forkChild), crash-recovery child reattachment (reattachChild), zero-pollution 3-way child commit (commitChild), dirty-safe child rebase (syncChild), and stacked prerequisite root sync (syncRoot).

Extends

• CheckpointableScope<THandle, TReceipt>

Type Parameters

Type Parameter	Default type	Description
THandle	unknown	Runtime scope handle type.
TReceipt extends Record<string, unknown>	Record<string, unknown>	Validated scope inspection receipt shape.
TSync extends Record<string, unknown>	Record<string, unknown>	Validated scope synchronization receipt shape.

Methods

acquireRoot()

acquireRoot(runId): Promise<THandle>;

Defined in: ports/isolation-scope.ts:30

Provisions and initializes an isolated root scope handle for runId.

Executes any configured scope setup commands and pins the initial base state for the run.

Parameters

Parameter	Type	Description
runId	string	Unique identifier of the flow run.

Returns

Promise<THandle>

Newly acquired root scope handle.

Inherited from

CheckpointableScope.acquireRoot

---

commitChild()

commitChild(child, parent): Promise<ReconcileResult<TReceipt>>;

Defined in: ports/branchable-scope.ts:63

Reconciles child into parent via a zero-pollution 3-way merge.

When parent has advanced and conflicts with child, leaves parent untouched, materializes the conflict state inside child, and returns status: 'conflict'.

Parameters

Parameter	Type	Description
child	THandle	Completed child scope handle.
parent	THandle	Target parent scope handle.

Returns

Promise<ReconcileResult<TReceipt>>

Clean or conflicted reconciliation result.

---

diffEffects()

diffEffects(fromCheckpoint, handle): Promise<readonly ToolEffect[]>;

Defined in: ports/checkpointable-scope.ts:53

Synthesizes ToolEffect descriptors by deterministically diffing handle against fromCheckpoint.

Enables post-flight policy guard and quota tripwire verification for arbitrary subprocess tools.

Parameters

Parameter	Type	Description
fromCheckpoint	string	Pre-tool checkpoint token captured before execution.
handle	THandle	Scope handle after tool execution.

Returns

Promise<readonly ToolEffect[]>

Synthesized tool effects for policy guard and tripwire evaluation.

Inherited from

CheckpointableScope.diffEffects

---

forkChild()

forkChild(parent, forkId): Promise<THandle>;

Defined in: ports/branchable-scope.ts:37

Forks an isolated child scope handle cloned from parent.

Preserves uncommitted edits from parent inside the newly provisioned Copy-on-Write child handle.

Parameters

Parameter	Type	Description
parent	THandle	Parent scope handle to clone from.
forkId	string	Unique identifier of the child fork or speculative branch.

Returns

Promise<THandle>

Newly provisioned child scope handle.

---

getConflictLease()?

getConflictLease?(handle): LeaseDelta | undefined;

Defined in: ports/branchable-scope.ts:101

Returns an optional temporary capability lease unlocking conflicted resources on handle.

Granted automatically when commitChild, syncChild, or syncRoot returns status: 'conflict'.

Parameters

Parameter	Type	Description
handle	THandle	Scope handle containing unresolved conflicts.

Returns

LeaseDelta | undefined

Temporary conflict resolution lease, or undefined if none.

---

inspect()

inspect(handle): Promise<TReceipt>;

Defined in: ports/isolation-scope.ts:53

Captures a side-effect-free inspection receipt (TReceipt) for handle.

Validates the returned receipt against receiptSchema before exposing it to .inputFrom() or .evaluate().

Parameters

Parameter	Type	Description
handle	THandle	Active scope handle to inspect.

Returns

Promise<TReceipt>

Validated inspection receipt.

Inherited from

CheckpointableScope.inspect

---

reattachChild()

reattachChild(
   parent, 
   forkId, 
   checkpoint?
): Promise<THandle>;

Defined in: ports/branchable-scope.ts:50

Rebinds an existing child scope handle during process reboot crash recovery.

Restores the child worktree or isolated branch state and applies checkpoint when needed.

Parameters

Parameter	Type	Description
parent	THandle	Parent scope handle.
forkId	string	Unique identifier of the child fork.
checkpoint?	string	Optional persisted childScopeCheckpoint fallback.

Returns

Promise<THandle>

Reattached child scope handle.

---

reattachRoot()

reattachRoot(runId, checkpoint?): Promise<THandle>;

Defined in: ports/isolation-scope.ts:42

Rebinds an existing root scope handle during process reboot crash recovery.

Restores the handle from persistent disk or remote state and falls back to checkpoint when needed.

Parameters

Parameter	Type	Description
runId	string	Unique identifier of the recovering flow run.
checkpoint?	string	Optional persisted baseScopeCheckpoint fallback.

Returns

Promise<THandle>

Reattached root scope handle.

Inherited from

CheckpointableScope.reattachRoot

---

release()

release(handle): Promise<void>;

Defined in: ports/isolation-scope.ts:64

Releases and cleans up an ephemeral root or child scope handle.

Invoked inside finally blocks when a branch, tournament loser, or completed flow run terminates.

Parameters

Parameter	Type	Description
handle	THandle	Scope handle to release.

Returns

Promise<void>

Resolves once all resources for handle are released.

Inherited from

CheckpointableScope.release

---

restoreCheckpoint()

restoreCheckpoint(handle, checkpoint): Promise<void>;

Defined in: ports/checkpointable-scope.ts:41

Restores handle to the exact state captured by checkpoint.

Discards any uncommitted mutations made since checkpoint was serialized without losing prior turns.

Parameters

Parameter	Type	Description
handle	THandle	Active scope handle to roll back.
checkpoint	string	Previously serialized checkpoint token.

Returns

Promise<void>

Resolves once handle matches checkpoint.

Inherited from

CheckpointableScope.restoreCheckpoint

---

serializeCheckpoint()

serializeCheckpoint(handle): Promise<string>;

Defined in: ports/checkpointable-scope.ts:29

Captures the uncommitted state of handle into a serializable checkpoint token.

Used before post-flight-guarded subprocess tools and prior to child fork or step suspension.

Parameters

Parameter	Type	Description
handle	THandle	Active scope handle to snapshot.

Returns

Promise<string>

Serialized checkpoint identifier or payload.

Inherited from

CheckpointableScope.serializeCheckpoint

---

syncChild()

syncChild(parent, pausedChild): Promise<ReconcileResult<TSync>>;

Defined in: ports/branchable-scope.ts:75

Rebases/merges uncommitted changes in pausedChild onto an updated parent handle.

Preserves dirty working-tree edits in pausedChild across the 3-way rebase onto parent.

Parameters

Parameter	Type	Description
parent	THandle	Updated parent scope handle.
pausedChild	THandle	Suspended child scope handle being resumed.

Returns

Promise<ReconcileResult<TSync>>

Clean or conflicted synchronization result.

---

syncRoot()

syncRoot(rootHandle, prerequisiteReceipts): Promise<ReconcileResult<TSync>>;

Defined in: ports/branchable-scope.ts:87

Synchronizes rootHandle onto completed prerequisite run receipts.

Rebases or merges the task root scope onto the terminal commits of its prerequisite runs upon wakeup.

Parameters

Parameter	Type	Description
rootHandle	THandle	Task root scope handle.
prerequisiteReceipts	readonly TReceipt[]	Terminal scope receipts of completed prerequisites.

Returns

Promise<ReconcileResult<TSync>>

Clean or conflicted synchronization result.

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
id	readonly	string	Unique identifier of the isolation scope driver.	CheckpointableScope.id	ports/isolation-scope.ts:17
receiptSchema	readonly	ZodType<TReceipt>	Zod schema validating receipts returned by inspect().	CheckpointableScope.receiptSchema	ports/isolation-scope.ts:19
supportsBranching	readonly	true	Literal capability marker confirming child branching support.	-	ports/branchable-scope.ts:23
supportsCheckpoints	readonly	true	Literal capability marker confirming checkpoint support.	CheckpointableScope.supportsCheckpoints	ports/checkpointable-scope.ts:18
syncSchema	readonly	ZodType<TSync>	Zod schema validating synchronization receipts returned by syncChild() and syncRoot().	-	ports/branchable-scope.ts:25