← Python SDK / recording

PYTHONPUBLIC API

fastsim.api.recording

Public Python API for fastsim.api.recording; signatures are extracted directly from FastSim source.

Public symbols 24

class

RunCompletionOutcome

L49

class RunCompletionOutcome(StrEnum)

Caller-authored terminal intent for one Run.

class

FinalizerStatus

L57

class FinalizerStatus(StrEnum)

Portable outcome reported by one data-consumer finalizer.

class

RunLifecycleContractError

L66

class RunLifecycleContractError(RuntimeError)

Stable base error for completion/finalizer protocol violations.

class

RunCompletionConflictError

L70

class RunCompletionConflictError(RunLifecycleContractError)

An idempotency key was reused with different completion content.

class

FinalizerRegistrationError

L74

class FinalizerRegistrationError(RunLifecycleContractError)

A finalizer registration is late, unauthorized, or conflicting.

class

FinalizerResultError

L78

class FinalizerResultError(RunLifecycleContractError)

A finalizer result is early, mismatched, or conflicting.

class

RunCompletionRequest

L83

class RunCompletionRequest(object)

Idempotent request to complete the current Run. Plugin identity is intentionally absent. Core replaces caller identity with the scoped identity attached to ``run.lifecycle``.

Field	Type	Default
request_id	str	—
outcome	RunCompletionOutcome \| str	—
reason_code	str	—
summary	FrozenDict[str, object] \| Mapping[str, object]	field(default_factory=FrozenDict)
schema	str	field(default='fastsim-run-completion-request/1', init=False)

class

RunCompletionReceipt

L110

class RunCompletionReceipt(object)

Admission result. It never contains another plugin's private summary.

Field	Type	Default
request_id	str	—
requester_instance	str	—
completion_sequence	int	—
won	bool	—
winning_instance	str \| None	—
winning_sequence	int \| None	—
schema	str	field(default='fastsim-run-completion-receipt/1', init=False)

class

RunCompletionWinner

L144

class RunCompletionWinner(object)

Field	Type	Default
request_id	str	—
requester_instance	str	—
completion_sequence	int	—
outcome	RunCompletionOutcome \| str	—
reason_code	str	—
summary	FrozenDict[str, object] \| Mapping[str, object]	—
schema	str	field(default='fastsim-run-completion-winner/1', init=False)

class

FinalizerRegistrationRequest

L173

class FinalizerRegistrationRequest(object)

Field	Type	Default
finalizer_id	str	—
required	bool	—
requested_timeout_s	float	—
schema	str	field(default='fastsim-plugin-finalizer-registration/1', init=False)

class

FinalizerResult

L191

class FinalizerResult(object)

Field	Type	Default
finalizer_id	str	—
status	FinalizerStatus \| str	—
reason_code	str	—
summary	FrozenDict[str, object] \| Mapping[str, object]	field(default_factory=FrozenDict)
output_commit_receipts	tuple[RunOutputCommitReceipt, ...]	()
schema	str	field(default='fastsim-plugin-finalizer-result/1', init=False)

class

FinalizerCompletionReceipt

L216

class FinalizerCompletionReceipt(object)

Field	Type	Default
finalizer_id	str	—
instance	str	—
result_sequence	int	—
accepted	bool	True
schema	str	field(default='fastsim-plugin-finalizer-completion-receipt/1', init=False)

class

FinalizerSnapshot

L234

class FinalizerSnapshot(object)

Field	Type	Default
finalizer_id	str	—
instance	str	—
required	bool	—
requested_timeout_s	float	—
effective_timeout_s	float	—
active	bool	—
result	FinalizerResult \| None	—
schema	str	field(default='fastsim-plugin-finalizer-snapshot/1', init=False)

class

TerminalSemanticCut

L267

class TerminalSemanticCut(object)

Terminal fences for each selected globally ordered source. ``observation_sequence`` identifies the active mutually exclusive observation capture lane: legacy snapshot/barrier sequence when no locked explicit demand exists, or channel/barrier ``capture_sequence`` when it does. Consumers must not assume it is always a snapshot sequence.

Field	Type	Default
run_id	str	—
record_sequence	int	—
lifecycle_sequence	int	—
control_audit_sequence	int	—
plugin_event_sequence	int	—
observation_sequence	int	—
media_sequence	int	0
fluid_audit_sequence	int	0
render_state_sequence	int	0
schema	str	field(default='fastsim-terminal-semantic-cut/1', init=False)

class

RunFinalOutcome

L305

class RunFinalOutcome(object)

Field	Type	Default
outcome	RunCompletionOutcome \| str	—
reason_code	str	—
stop_reason	str	—
degraded	bool	—
source	str	—
required_finalizer_failures	tuple[str, ...]	()
optional_finalizer_failures	tuple[str, ...]	()
schema	str	field(default='fastsim-run-final-outcome/1', init=False)

class

RunCompletionSnapshot

L364

class RunCompletionSnapshot(object)

Field	Type	Default
state	str	—
winner	RunCompletionWinner \| None	—
finalizers	tuple[FinalizerSnapshot, ...]	—
terminal_cut	TerminalSemanticCut \| None	—
final_outcome	RunFinalOutcome \| None	—
schema	str	field(default='fastsim-run-completion-snapshot/1', init=False)

class

RunTerminalPolicy

L397

class RunTerminalPolicy(object)

Trusted launch policy; never compiled from scenario or plugin config.

Field	Type	Default
global_deadline_s	float	120.0
per_consumer_cap_s	float	60.0
cleanup_reserve_s	float	10.0

class

ScopedFinalizerHandle

L412

class ScopedFinalizerHandle(Protocol)

Process-local finalizer completion capability.

finalizer_id

ScopedFinalizerHandle.finalizer_id(self) -> str

effective_timeout_s

ScopedFinalizerHandle.effective_timeout_s(self) -> float

complete

ScopedFinalizerHandle.complete(self, result: FinalizerResult) -> FinalizerCompletionReceipt

class

ScopedControlAuditSubscription

L425

class ScopedControlAuditSubscription(Protocol)

Bounded, revocable subscription to the portable control audit stream.

closed

ScopedControlAuditSubscription.closed(self) -> bool

queued_items

ScopedControlAuditSubscription.queued_items(self) -> int

queued_bytes

ScopedControlAuditSubscription.queued_bytes(self) -> int

dropped_items

ScopedControlAuditSubscription.dropped_items(self) -> int

dropped_bytes

ScopedControlAuditSubscription.dropped_bytes(self) -> int

get

ScopedControlAuditSubscription.get(self, timeout: float | None=None) -> ControlAuditStreamItem

get_async

async ScopedControlAuditSubscription.get_async(self, timeout: float | None=None) -> ControlAuditStreamItem

ScopedControlAuditSubscription.close(self) -> None

class

ControlAuditService

L451

class ControlAuditService(Protocol)

Capability-scoped access to authored and applied control evidence.

service_id

ControlAuditService.service_id(self) -> str

ControlAuditService.subscribe(self, capacity: int=1024, max_item_bytes: int=1048576, overload: ControlAuditOverloadPolicy | str=ControlAuditOverloadPolicy.FAIL_RUN) -> ScopedControlAuditSubscription

class

RunLifecycleSubscription

L466

class RunLifecycleSubscription(Protocol)

Bounded, revocable stream of portable run-lifecycle envelopes.

closed

RunLifecycleSubscription.closed(self) -> bool

dropped

RunLifecycleSubscription.dropped(self) -> int

get

RunLifecycleSubscription.get(self, timeout: float | None=None) -> object

get_async

async RunLifecycleSubscription.get_async(self, timeout: float | None=None) -> object

RunLifecycleSubscription.close(self) -> None

class

RunLifecycleService

L483

class RunLifecycleService(Protocol)

Scoped lifecycle view plus completion/finalizer admission.

service_id

RunLifecycleService.service_id(self) -> str

snapshot

RunLifecycleService.snapshot(self) -> object

request_completion

RunLifecycleService.request_completion(self, request: RunCompletionRequest) -> RunCompletionReceipt

register_finalizer

RunLifecycleService.register_finalizer(self, request: FinalizerRegistrationRequest) -> ScopedFinalizerHandle

RunLifecycleService.subscribe(self, capacity: int=64, max_item_bytes: int=1048576, *, replay_history: bool=False, from_record_sequence: int | None=None) -> RunLifecycleSubscription

class

PluginEventSubscriptionService

L564

class PluginEventSubscriptionService(Protocol)

Bounded, revocable stream of portable plugin-event envelopes.

closed

PluginEventSubscriptionService.closed(self) -> bool

dropped

PluginEventSubscriptionService.dropped(self) -> int

get

PluginEventSubscriptionService.get(self, timeout: float | None=None) -> object

get_async

async PluginEventSubscriptionService.get_async(self, timeout: float | None=None) -> object

PluginEventSubscriptionService.close(self) -> None

class

EventSubscribeService

L581

class EventSubscribeService(Protocol)

Topic-filtered event view with optional ordered-history bootstrap.

service_id

EventSubscribeService.service_id(self) -> str

EventSubscribeService.subscribe(self, capacity: int=64, max_item_bytes: int=1048576, overload: str='drop_oldest', topics: tuple[str, ...]=(), *, replay_history: bool=False, from_record_sequence: int | None=None) -> PluginEventSubscriptionService