Interface: CheckpointableScope<THandle, TReceipt>

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

Tier-2 runtime driver contract for checkpointable isolation scopes (capabilityTier: 'checkpointable' | 'branchable').

Extends IsolationScope with uncommitted state snapshotting (serializeCheckpoint), deterministic rollback (restoreCheckpoint), and post-flight effect diffing (diffEffects).

Extends

• IsolationScope<THandle, TReceipt>

Extended by

• BranchableScope

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.

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

IsolationScope.acquireRoot

---

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.

---

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

IsolationScope.inspect

---

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

IsolationScope.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

IsolationScope.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.

---

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.

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
id	readonly	string	Unique identifier of the isolation scope driver.	IsolationScope.id	ports/isolation-scope.ts:17
receiptSchema	readonly	ZodType<TReceipt>	Zod schema validating receipts returned by inspect().	IsolationScope.receiptSchema	ports/isolation-scope.ts:19
supportsCheckpoints	readonly	true	Literal capability marker confirming checkpoint support.	-	ports/checkpointable-scope.ts:18