cayu.memory.execution

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`CayuMemoryInterventionRuntimeRunner`

from cayu.memory import CayuMemoryInterventionRuntimeRunner

Run a fixed intervention through Cayu’s ordinary runtime pipeline.

Bases: MemoryInterventionRuntimeRunner.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`execution_profile_fingerprint`	`str`	`required`
`provider_configuration_fingerprint`	`str \| None`	`None`
`provider_execution_mode`	`MemoryInterventionProviderExecutionMode \| None`	`None`

durable_state_paths (method)

CayuMemoryInterventionRuntimeRunner.durable_state_paths() -> tuple[Path, ...]

Return the exact canonical runtime store’s local state files.

durable_budget_ledger_paths (method)

CayuMemoryInterventionRuntimeRunner.durable_budget_ledger_paths() -> tuple[Path, ...]

Return local files used by the canonical runtime’s reservation ledger.

current_provider_configuration_fingerprint (method)

CayuMemoryInterventionRuntimeRunner.current_provider_configuration_fingerprint() -> str

Verify and return the factory’s live provider configuration identity.

current_provider_execution_mode (method)

CayuMemoryInterventionRuntimeRunner.current_provider_execution_mode() -> MemoryInterventionProviderExecutionMode

Verify and return the factory’s provider dispatch classification.

required_execution_profile_fingerprint (method)

CayuMemoryInterventionRuntimeRunner.required_execution_profile_fingerprint(spec: MemoryInterventionSpec) -> str

accounting_sessions_belong_to_trial (method)

async CayuMemoryInterventionRuntimeRunner.accounting_sessions_belong_to_trial(execution: MemoryInterventionExecutionRecord, session_ids: Sequence[str]) -> bool

run (method)

async CayuMemoryInterventionRuntimeRunner.run(*, request: MemoryInterventionTrialRequest, execution: MemoryInterventionExecutionRecord, starting_execution_profile: AgentSnapshotExecutionProfileRef, trial: AgentSnapshotTrialBinding, operation: MemoryInterventionOperation, view: MemoryInterventionRuntimeView, reference_key: RuntimeSessionCreateClaimReferenceKey) -> MemoryInterventionRuntimeResult

recover (method)

async CayuMemoryInterventionRuntimeRunner.recover(*, request: MemoryInterventionTrialRequest, execution: MemoryInterventionExecutionRecord, starting_execution_profile: AgentSnapshotExecutionProfileRef, trial: AgentSnapshotTrialBinding, operation: MemoryInterventionOperation, view: MemoryInterventionRuntimeView, reference_key: RuntimeSessionCreateClaimReferenceKey) -> MemoryInterventionRuntimeResult

init (method)

CayuMemoryInterventionRuntimeRunner.__init__(factory: MemoryInterventionRuntimeApplicationFactory, *, attribution_bounds: MemoryAttributionBounds | None=None) -> None

Release source · Runtime guarantees · Capability guides

`InMemoryMemoryInterventionExecutionStore`

from cayu.memory import InMemoryMemoryInterventionExecutionStore

Bases: MemoryInterventionExecutionStore.

durable_state_paths (method)

InMemoryMemoryInterventionExecutionStore.durable_state_paths() -> tuple[Path, ...]

Return local files that own this store’s durable state.

begin (method)

async InMemoryMemoryInterventionExecutionStore.begin(record: MemoryInterventionExecutionRecord) -> MemoryInterventionExecutionRecord

load (method)

async InMemoryMemoryInterventionExecutionStore.load(execution_id: str) -> MemoryInterventionExecutionRecord | None

compare_and_set (method)

async InMemoryMemoryInterventionExecutionStore.compare_and_set(expected: MemoryInterventionExecutionRecord, desired: MemoryInterventionExecutionRecord) -> MemoryInterventionExecutionRecord

transition_runtime_dispatch_ownership (method)

async InMemoryMemoryInterventionExecutionStore.transition_runtime_dispatch_ownership(execution_id: str, request: DurableOperationOwnershipTransition) -> MemoryInterventionRuntimeOwnershipResult

init (method)

InMemoryMemoryInterventionExecutionStore.__init__(*, ownership_clock: Callable[[], datetime] | None=None) -> None

Release source · Runtime guarantees · Capability guides

`memory_intervention_eval_result_revision`

from cayu.memory import memory_intervention_eval_result_revision

Compatibility name for the canonical eval trial-result identity.

memory_intervention_eval_result_revision(result: EvalTrialResult) -> str

Release source · Runtime guarantees · Capability guides

`MEMORY_INTERVENTION_EXECUTION_MAX_RECORD_BYTES`

from cayu.memory import MEMORY_INTERVENTION_EXECUTION_MAX_RECORD_BYTES

MEMORY_INTERVENTION_EXECUTION_MAX_RECORD_BYTES = 1 << 20

Release source · Runtime guarantees · Capability guides

`MEMORY_INTERVENTION_EXECUTION_MAX_TIMEOUT_SECONDS`

from cayu.memory import MEMORY_INTERVENTION_EXECUTION_MAX_TIMEOUT_SECONDS

MEMORY_INTERVENTION_EXECUTION_MAX_TIMEOUT_SECONDS = 3600

Release source · Runtime guarantees · Capability guides

`MEMORY_INTERVENTION_EXECUTION_RECORD_SCHEMA_VERSION`

from cayu.memory import MEMORY_INTERVENTION_EXECUTION_RECORD_SCHEMA_VERSION

MEMORY_INTERVENTION_EXECUTION_RECORD_SCHEMA_VERSION = 2

Release source · Runtime guarantees · Capability guides

`MEMORY_INTERVENTION_EXECUTION_SCHEMA_VERSION`

from cayu.memory import MEMORY_INTERVENTION_EXECUTION_SCHEMA_VERSION

MEMORY_INTERVENTION_EXECUTION_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`memory_intervention_request_key`

from cayu.memory import memory_intervention_request_key

memory_intervention_request_key(keys: Mapping[str, MemoryInterventionRequestFingerprintKey], key_id: str) -> MemoryInterventionRequestFingerprintKey

Release source · Runtime guarantees · Capability guides

`memory_intervention_runtime_result_fingerprint`

from cayu.memory import memory_intervention_runtime_result_fingerprint

memory_intervention_runtime_result_fingerprint(result: MemoryInterventionRuntimeResult) -> str

Release source · Runtime guarantees · Capability guides

`MemoryInterventionEvaluator`

from cayu.memory import MemoryInterventionEvaluator

Thin adapter over an application-owned existing evaluator identity.

Bases: ABC.

Fields and attributes

Name	Type	Default
`evaluator_fingerprint`	`str`	`required`

evaluate (method)

async MemoryInterventionEvaluator.evaluate(*, operation_id: str, case: EvalCaseContractV1, runtime: MemoryInterventionRuntimeResult) -> EvalTrialResult

recover (method)

async MemoryInterventionEvaluator.recover(*, operation_id: str, case: EvalCaseContractV1, runtime: MemoryInterventionRuntimeResult) -> EvalTrialResult

Complete or reconcile evaluation for the exact operation identity.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutionConflict`

from cayu.memory import MemoryInterventionExecutionConflict

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutionPhase`

from cayu.memory import MemoryInterventionExecutionPhase

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`PREPARED`	`class attribute`	`'prepared'`
`TRIAL_BOUND`	`class attribute`	`'trial_bound'`
`EFFECT_RESOLVED`	`class attribute`	`'effect_resolved'`
`SESSION_BOUND`	`class attribute`	`'session_bound'`
`RUNTIME_TERMINAL`	`class attribute`	`'runtime_terminal'`
`EVALUATED`	`class attribute`	`'evaluated'`
`FINALIZED`	`class attribute`	`'finalized'`

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutionRecord`

from cayu.memory import MemoryInterventionExecutionRecord

One CAS-owned durable execution journal row.

Bases: _ExecutionModel.

Fields and attributes

Name	Type	Default
`record_type`	`Literal['cayu.memory-intervention-execution']`	`'cayu.memory-intervention-execution'`
`schema_version`	`Literal[2]`	`MEMORY_INTERVENTION_EXECUTION_RECORD_SCHEMA_VERSION`
`execution_id`	`StrictStr`	`required`
`request_key_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`request_fingerprint`	`StrictStr`	`required`
`spec_fingerprint`	`StrictStr`	`required`
`candidate_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`trial_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`case_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`case_revision`	`StrictStr`	`required`
`required_execution_profile_fingerprint`	`StrictStr`	`required`
`runtime_execution_profile_fingerprint`	`StrictStr`	`required`
`overlay_provider_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`overlay_provider_fingerprint`	`StrictStr`	`required`
`runtime_runner_fingerprint`	`StrictStr`	`required`
`evaluator_fingerprint`	`StrictStr`	`required`
`session_id`	`StrictStr`	`Field(max_length=512)`
`causal_budget_id`	`StrictStr`	`Field(max_length=512)`
`phase`	`MemoryInterventionExecutionPhase`	`required`
`status`	`MemoryInterventionExecutionStatus`	`MemoryInterventionExecutionStatus.ACTIVE`
`revision`	`StrictInt`	`Field(ge=0)`
`runtime_cancellation_observed`	`bool`	`False`
`runtime_timeout_observed`	`bool`	`False`
`runtime_session_create_claim`	`RuntimeSessionCreateClaimReference \| None`	`None`
`runtime_deadline_at`	`datetime \| None`	`None`
`runtime_dispatch_ownership`	`DurableOperationOwnership \| None`	`None`
`created_at`	`datetime`	`required`
`updated_at`	`datetime`	`required`
`materialization_fingerprint`	`StrictStr \| None`	`None`
`trial_binding_fingerprint`	`StrictStr \| None`	`None`
`operation_fingerprint`	`StrictStr \| None`	`None`
`receipt_fingerprint`	`StrictStr \| None`	`None`
`runtime_evidence_fingerprint`	`StrictStr \| None`	`None`
`runtime_result_fingerprint`	`StrictStr \| None`	`None`
`runtime_result_payload`	`dict[str, Any] \| None`	`None`
`eval_result_revision`	`StrictStr \| None`	`None`
`snapshot_result_fingerprint`	`StrictStr \| None`	`None`
`final_binding_fingerprint`	`StrictStr \| None`	`None`
`failure_code`	`Literal['intervention_conflicting', 'intervention_indeterminate', 'runtime_cancelled', 'runtime_failed', 'runtime_outcome_unknown', 'runtime_timed_out'] \| None`	`None`

validate_integer_literals (method)

MemoryInterventionExecutionRecord.validate_integer_literals(value: object, info) -> object

validate_runtime_control_observed (method)

MemoryInterventionExecutionRecord.validate_runtime_control_observed(value: object, info) -> object

validate_fingerprints (method)

MemoryInterventionExecutionRecord.validate_fingerprints(value: str | None, info) -> str | None

validate_case_revision (method)

MemoryInterventionExecutionRecord.validate_case_revision(value: str, info) -> str

copy_runtime_result_payload (method)

MemoryInterventionExecutionRecord.copy_runtime_result_payload(value: object) -> object

validate_text (method)

MemoryInterventionExecutionRecord.validate_text(value: str | None, info) -> str | None

copy_runtime_dispatch_ownership (method)

MemoryInterventionExecutionRecord.copy_runtime_dispatch_ownership(value: object) -> object

copy_runtime_session_create_claim (method)

MemoryInterventionExecutionRecord.copy_runtime_session_create_claim(value: object) -> object

validate_timestamps (method)

MemoryInterventionExecutionRecord.validate_timestamps(value: datetime | None, info) -> datetime | None

validate_phase (method)

MemoryInterventionExecutionRecord.validate_phase() -> Self

prepare (method)

MemoryInterventionExecutionRecord.prepare(request: MemoryInterventionTrialRequest, *, key: MemoryInterventionRequestFingerprintKey, overlay_provider_fingerprint: str, overlay_provider_id: str, runtime_runner_fingerprint: str, runtime_execution_profile_fingerprint: str, evaluator_fingerprint: str, created_at: datetime) -> MemoryInterventionExecutionRecord

replay_identity (method)

MemoryInterventionExecutionRecord.replay_identity() -> tuple[object, ...]

immutable_identity (method)

MemoryInterventionExecutionRecord.immutable_identity() -> tuple[object, ...]

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutionStatus`

from cayu.memory import MemoryInterventionExecutionStatus

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`ACTIVE`	`class attribute`	`'active'`
`COMPLETED`	`class attribute`	`'completed'`
`FAILED`	`class attribute`	`'failed'`
`CANCELLED`	`class attribute`	`'cancelled'`
`TIMED_OUT`	`class attribute`	`'timed_out'`
`OUTCOME_UNKNOWN`	`class attribute`	`'outcome_unknown'`
`CONFLICTING`	`class attribute`	`'conflicting'`
`INDETERMINATE`	`class attribute`	`'indeterminate'`

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutionStore`

from cayu.memory import MemoryInterventionExecutionStore

Bases: ABC.

durable_state_paths (method)

MemoryInterventionExecutionStore.durable_state_paths() -> tuple[Path, ...]

Return local files that own this store’s durable state.

begin (method)

async MemoryInterventionExecutionStore.begin(record: MemoryInterventionExecutionRecord) -> MemoryInterventionExecutionRecord

Create one execution identity or return its exact replay.

load (method)

async MemoryInterventionExecutionStore.load(execution_id: str) -> MemoryInterventionExecutionRecord | None

compare_and_set (method)

async MemoryInterventionExecutionStore.compare_and_set(expected: MemoryInterventionExecutionRecord, desired: MemoryInterventionExecutionRecord) -> MemoryInterventionExecutionRecord

Advance one exact execution revision atomically.

A session-bound control or runtime-result publication must also verify that the embedded dispatch ownership is live using time sampled inside this same write boundary.

transition_runtime_dispatch_ownership (method)

async MemoryInterventionExecutionStore.transition_runtime_dispatch_ownership(execution_id: str, request: DurableOperationOwnershipTransition) -> MemoryInterventionRuntimeOwnershipResult

Apply one ownership transition using time sampled by this store.

Custom stores must compare and persist the embedded ownership in the same transaction that samples store_now. There is deliberately no lossy compare-and-set fallback: an unported store fails before runtime dispatch while remaining constructible for an orderly upgrade.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutor`

from cayu.memory import MemoryInterventionExecutor

Execute one fixed intervention through durable, exact phase boundaries.

The injected overlay provider owns idempotent candidate-local effects. The runtime runner owns the real Cayu session and must not return from timeout, cancellation, or interruption until any dispatched mutation is settled or durably recoverable. The evaluator is an adapter over the evaluator already frozen in the starting AgentSnapshot.

init (method)

MemoryInterventionExecutor.__init__(*, snapshots: AgentSnapshotCoordinator, executions: MemoryInterventionExecutionStore, overlay_provider: MemoryInterventionOverlayProvider, runtime_runner: MemoryInterventionRuntimeRunner, evaluator: MemoryInterventionEvaluator, request_keys: Mapping[str, MemoryInterventionRequestFingerprintKey], current_request_key_id: str, clock=None) -> None

snapshots (property)

MemoryInterventionExecutor.snapshots() -> AgentSnapshotCoordinator

Return the immutable snapshot capability bound at construction.

executions (property)

MemoryInterventionExecutor.executions() -> MemoryInterventionExecutionStore

Return the immutable execution journal bound at construction.

overlay_provider (property)

MemoryInterventionExecutor.overlay_provider() -> MemoryInterventionOverlayProvider

Return the immutable overlay capability bound at construction.

runtime_runner (property)

MemoryInterventionExecutor.runtime_runner() -> MemoryInterventionRuntimeRunner

Return the immutable runtime capability bound at construction.

evaluator (property)

MemoryInterventionExecutor.evaluator() -> MemoryInterventionEvaluator

Return the immutable evaluator capability bound at construction.

execution_authority (property)

MemoryInterventionExecutor.execution_authority() -> MemoryInterventionExecutorAuthority

Return the current detached identity of every execution component.

durable_state_paths (method)

MemoryInterventionExecutor.durable_state_paths() -> MemoryInterventionExecutorStatePaths

Return local state files from the exact stores used by this executor.

execute_trial (method)

async MemoryInterventionExecutor.execute_trial(request: MemoryInterventionTrialRequest, *, admission_check: Callable[[], None] | None=None) -> MemoryInterventionTrialOutcome

Execute or exactly recover one deterministic candidate trial.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutorAuthority`

from cayu.memory import MemoryInterventionExecutorAuthority

Detached identity of the components that may execute one intervention.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`1`
`overlay_provider_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`overlay_provider_fingerprint`	`StrictStr`	`required`
`runtime_runner_fingerprint`	`StrictStr`	`required`
`evaluator_fingerprint`	`StrictStr`	`required`
`provider_configuration_fingerprint`	`StrictStr \| None`	`None`
`provider_execution_mode`	`MemoryInterventionProviderExecutionMode \| None`	`None`

validate_schema_version (method)

MemoryInterventionExecutorAuthority.validate_schema_version(value: object) -> object

validate_provider_id (method)

MemoryInterventionExecutorAuthority.validate_provider_id(value: str, info) -> str

validate_fingerprints (method)

MemoryInterventionExecutorAuthority.validate_fingerprints(value: str | None, info) -> str | None

fingerprint (property)

MemoryInterventionExecutorAuthority.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

`MemoryInterventionExecutorStatePaths`

from cayu.memory import MemoryInterventionExecutorStatePaths

Local durable state files used by one intervention executor.

Decorators: @dataclass(frozen=True, slots=True, repr=False).

Fields and attributes

Name	Type	Default
`snapshot_store`	`tuple[Path, ...]`	`required`
`execution_store`	`tuple[Path, ...]`	`required`
`runtime_session_store`	`tuple[Path, ...]`	`required`
`runtime_budget_ledger`	`tuple[Path, ...]`	`required`

Release source · Runtime guarantees · Capability guides

`MemoryInterventionIsolationAuthority`

from cayu.memory import MemoryInterventionIsolationAuthority

Positive authority that one store is an intervention-only overlay.

The application-owned overlay provider creates this record only after it has opened a store that cannot write through to the production knowledge store. Runtime adapters validate the complete materialization authority before exposing the store to Cayu.

Bases: _ExecutionModel.

Fields and attributes

Name	Type	Default
`materialization_fingerprint`	`StrictStr`	`required`
`memory_overlay_fingerprint`	`StrictStr`	`required`
`state_scope_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`

validate_fingerprints (method)

MemoryInterventionIsolationAuthority.validate_fingerprints(value: str, info) -> str

validate_scope (method)

MemoryInterventionIsolationAuthority.validate_scope(value: str, info) -> str

Release source · Runtime guarantees · Capability guides

`MemoryInterventionOverlayProvider`

from cayu.memory import MemoryInterventionOverlayProvider

Application-owned opener and effect authority for one memory overlay.

Bases: ABC.

Fields and attributes

Name	Type	Default
`provider_id`	`str`	`required`
`execution_profile_fingerprint`	`str`	`required`

apply (method)

async MemoryInterventionOverlayProvider.apply(*, spec: MemoryInterventionSpec, operation: MemoryInterventionOperation, materialization: AgentSnapshotMaterialization, trial: AgentSnapshotTrialBinding) -> MemoryInterventionRuntimeView

Apply one precommitted effect exactly once and open its runtime view.

recover (method)

async MemoryInterventionOverlayProvider.recover(*, spec: MemoryInterventionSpec, operation: MemoryInterventionOperation, materialization: AgentSnapshotMaterialization, trial: AgentSnapshotTrialBinding) -> MemoryInterventionRuntimeView

Complete or reconcile the exact precommitted effect operation.

Recovery can begin after the durable operation claim but before the first application call. Implementations must therefore use the operation identity as their idempotency authority: apply the effect if no receipt exists, otherwise return the exact prior receipt, without repeating a candidate effect.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionProviderExecutionMode`

from cayu.memory import MemoryInterventionProviderExecutionMode

Whether an intervention runtime may dispatch external provider work.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`HERMETIC`	`class attribute`	`'hermetic'`
`LIVE`	`class attribute`	`'live'`

Release source · Runtime guarantees · Capability guides

`MemoryInterventionRequestFingerprintKey`

from cayu.memory import MemoryInterventionRequestFingerprintKey

Detached restart-stable key for secret-safe exact request identity.

Decorators: @dataclass(frozen=True, slots=True, repr=False).

Fields and attributes

Name	Type	Default
`key_id`	`str`	`required`
`secret`	`bytes`	`required`

fingerprint (method)

MemoryInterventionRequestFingerprintKey.fingerprint(request: MemoryInterventionTrialRequest) -> str

runtime_session_create_reference_key (method)

MemoryInterventionRequestFingerprintKey.runtime_session_create_reference_key() -> RuntimeSessionCreateClaimReferenceKey

Derive a restricted runtime-reference key from this rotated root key.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionRuntimeApplicationFactory`

from cayu.memory import MemoryInterventionRuntimeApplicationFactory

Application-owned constructor for one isolated canonical Cayu runtime.

Implementations register the frozen agent/provider/evaluation authority and must install view.knowledge_store as the selected environment’s exact knowledge store. The concrete runner validates those facts and the full runtime execution profile before dispatch.

Bases: ABC.

Fields and attributes

Name	Type	Default
`factory_id`	`str`	`required`
`execution_profile_fingerprint`	`str`	`required`

provider_configuration_fingerprint (property)

MemoryInterventionRuntimeApplicationFactory.provider_configuration_fingerprint() -> str

Return the exact provider configuration installed by this factory.

provider_execution_mode (property)

MemoryInterventionRuntimeApplicationFactory.provider_execution_mode() -> MemoryInterventionProviderExecutionMode

Return whether created applications may dispatch external provider work.

runtime_session_store (property)

MemoryInterventionRuntimeApplicationFactory.runtime_session_store() -> SessionStore

Return the exact store installed in every application this factory creates.

runtime_budget_ledger (property)

MemoryInterventionRuntimeApplicationFactory.runtime_budget_ledger() -> BudgetLedger

Return the exact reservation ledger installed in every created application.

expected_execution_profile_fingerprint (method)

MemoryInterventionRuntimeApplicationFactory.expected_execution_profile_fingerprint(spec: MemoryInterventionSpec) -> str

Return the app-owned exact profile for this authorized recall policy.

Unchanged recall uses the verified snapshot profile. Applications that support automatic_recall_off or another policy-changing fixed variant must override this method and bind that mapping into execution_profile_fingerprint.

create (method)

async MemoryInterventionRuntimeApplicationFactory.create(*, request: MemoryInterventionTrialRequest, execution: MemoryInterventionExecutionRecord, trial: AgentSnapshotTrialBinding, operation: MemoryInterventionOperation, view: MemoryInterventionRuntimeView) -> object

Return a newly configured CayuApp for the exact runtime view.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionRuntimeResult`

from cayu.memory import MemoryInterventionRuntimeResult

Bases: _ExecutionModel.

Fields and attributes

Name	Type	Default
`session_id`	`StrictStr`	`Field(max_length=512)`
`terminal_disposition`	`AgentSnapshotTerminalDisposition`	`required`
`runtime_evidence_fingerprint`	`StrictStr`	`required`
`terminal_evidence_available`	`StrictBool`	`required`
`terminal_evidence_limitation`	`EvalMemoryEvidenceLimitation \| None`	`None`
`expected_receipt_count`	`StrictInt \| None`	`Field(default=None, ge=0)`
`expected_exposure_count`	`StrictInt \| None`	`Field(default=None, ge=0)`
`effective_attribution_bounds`	`MemoryAttributionBounds`	`required`
`source_alias`	`EvalMemorySourceAliasV1 \| None`	`None`
`attribution`	`MemoryAttribution`	`required`
`usage_fingerprint`	`StrictStr \| None`	`None`
`cost_fingerprint`	`StrictStr \| None`	`None`

validate_session_id (method)

MemoryInterventionRuntimeResult.validate_session_id(value: str, info) -> str

validate_evidence (method)

MemoryInterventionRuntimeResult.validate_evidence(value: str | None, info) -> str | None

copy_attribution (method)

MemoryInterventionRuntimeResult.copy_attribution(value: object) -> object

copy_effective_attribution_bounds (method)

MemoryInterventionRuntimeResult.copy_effective_attribution_bounds(value: object) -> object

copy_source_alias (method)

MemoryInterventionRuntimeResult.copy_source_alias(value: object) -> object

validate_terminal_memory_authority (method)

MemoryInterventionRuntimeResult.validate_terminal_memory_authority() -> Self

Release source · Runtime guarantees · Capability guides

`MemoryInterventionRuntimeRunner`

from cayu.memory import MemoryInterventionRuntimeRunner

Typed internal runtime entrance; caller metadata cannot construct it.

The executor supplies only a domain-derived session-reference key. A runner never receives the root key that authenticates the durable trial request.

Bases: ABC.

Fields and attributes

Name	Type	Default
`execution_profile_fingerprint`	`str`	`required`
`provider_configuration_fingerprint`	`str \| None`	`None`
`provider_execution_mode`	`MemoryInterventionProviderExecutionMode \| None`	`None`

durable_state_paths (method)

MemoryInterventionRuntimeRunner.durable_state_paths() -> tuple[Path, ...]

Return local files used by this runner’s canonical runtime.

durable_budget_ledger_paths (method)

MemoryInterventionRuntimeRunner.durable_budget_ledger_paths() -> tuple[Path, ...]

Return local files used by this runner’s reservation ledger.

current_provider_configuration_fingerprint (method)

MemoryInterventionRuntimeRunner.current_provider_configuration_fingerprint() -> str | None

Return the live provider configuration identity, when available.

current_provider_execution_mode (method)

MemoryInterventionRuntimeRunner.current_provider_execution_mode() -> MemoryInterventionProviderExecutionMode | None

Return whether the current provider authority is hermetic or live.

required_execution_profile_fingerprint (method)

MemoryInterventionRuntimeRunner.required_execution_profile_fingerprint(spec: MemoryInterventionSpec) -> str

accounting_sessions_belong_to_trial (method)

async MemoryInterventionRuntimeRunner.accounting_sessions_belong_to_trial(execution: MemoryInterventionExecutionRecord, session_ids: Sequence[str]) -> bool

Return whether every accounting session is attributable to this trial.

Generic runners can prove only the root session. Runtime integrations that support child sessions must override this boundary with durable lineage validation.

run (method)

async MemoryInterventionRuntimeRunner.run(*, request: MemoryInterventionTrialRequest, execution: MemoryInterventionExecutionRecord, starting_execution_profile: AgentSnapshotExecutionProfileRef, trial: AgentSnapshotTrialBinding, operation: MemoryInterventionOperation, view: MemoryInterventionRuntimeView, reference_key: RuntimeSessionCreateClaimReferenceKey) -> MemoryInterventionRuntimeResult

recover (method)

async MemoryInterventionRuntimeRunner.recover(*, request: MemoryInterventionTrialRequest, execution: MemoryInterventionExecutionRecord, starting_execution_profile: AgentSnapshotExecutionProfileRef, trial: AgentSnapshotTrialBinding, operation: MemoryInterventionOperation, view: MemoryInterventionRuntimeView, reference_key: RuntimeSessionCreateClaimReferenceKey) -> MemoryInterventionRuntimeResult

Complete or reconcile the exact precommitted runtime session.

The session claim is durable before run is entered, so recovery must safely start an undispatched session or reconnect an already dispatched one using the runtime-owned session identity.

Release source · Runtime guarantees · Capability guides

`MemoryInterventionRuntimeView`

from cayu.memory import MemoryInterventionRuntimeView

Ephemeral executable view authenticated by one durable materialization.

Decorators: @dataclass(frozen=True, slots=True).

Fields and attributes

Name	Type	Default
`materialization_fingerprint`	`str`	`required`
`memory_overlay_fingerprint`	`str`	`required`
`state_scope_id`	`str`	`required`
`knowledge_store`	`KnowledgeStore`	`required`
`knowledge_access_scope`	`KnowledgeAccessScope`	`required`
`isolation_authority`	`MemoryInterventionIsolationAuthority`	`required`
`trial_recall_policy`	`AutomaticRecallPolicy`	`required`
`receipt`	`MemoryInterventionReceipt`	`required`

Release source · Runtime guarantees · Capability guides

`MemoryInterventionTrialOutcome`

from cayu.memory import MemoryInterventionTrialOutcome

Bounded executor result assembled from existing evidence contracts.

Bases: _ExecutionModel.

Fields and attributes

Name	Type	Default
`execution`	`MemoryInterventionExecutionRecord`	`required`
`receipt`	`MemoryInterventionReceipt \| None`	`None`
`eval_result`	`EvalTrialResult \| None`	`None`
`snapshot_result`	`AgentSnapshotResultBinding \| None`	`None`
`binding`	`MemoryInterventionTrialBinding \| None`	`None`

copy_execution (method)

MemoryInterventionTrialOutcome.copy_execution(value: object) -> object

copy_receipt (method)

MemoryInterventionTrialOutcome.copy_receipt(value: object) -> object

copy_eval_result (method)

MemoryInterventionTrialOutcome.copy_eval_result(value: object) -> object

copy_snapshot_result (method)

MemoryInterventionTrialOutcome.copy_snapshot_result(value: object) -> object

copy_binding (method)

MemoryInterventionTrialOutcome.copy_binding(value: object) -> object

validate_outcome (method)

MemoryInterventionTrialOutcome.validate_outcome() -> Self

Release source · Runtime guarantees · Capability guides

`MemoryInterventionTrialRequest`

from cayu.memory import MemoryInterventionTrialRequest

One bounded fixed-candidate execution request.

Session, task, parent, and causal-budget identities are runtime-owned for this API. Rejecting caller values prevents a candidate trial from joining unrelated durable ownership or accounting scopes.

Bases: _ExecutionModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`MEMORY_INTERVENTION_EXECUTION_SCHEMA_VERSION`
`spec`	`MemoryInterventionSpec`	`required`
`candidate_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`trial_id`	`StrictStr`	`Field(max_length=_MAX_ID_CHARS)`
`case`	`EvalCaseContractV1`	`required`
`run_request`	`RunRequest`	`required`
`context_preparation`	`Literal['none', 'compact_then_resume']`	`Field(default='none', exclude_if=lambda value: value == 'none')`
`timeout_seconds`	`StrictInt`	`Field(default=300, ge=1, le=MEMORY_INTERVENTION_EXECUTION_MAX_TIMEOUT_SECONDS)`

validate_integer_literals (method)

MemoryInterventionTrialRequest.validate_integer_literals(value: object, info) -> object

copy_spec (method)

MemoryInterventionTrialRequest.copy_spec(value: object) -> object

copy_case (method)

MemoryInterventionTrialRequest.copy_case(value: object) -> object

copy_request (method)

MemoryInterventionTrialRequest.copy_request(value: RunRequest) -> RunRequest

validate_ids (method)

MemoryInterventionTrialRequest.validate_ids(value: str, info) -> str

validate_isolated_request (method)

MemoryInterventionTrialRequest.validate_isolated_request() -> Self

identity_material (method)

MemoryInterventionTrialRequest.identity_material() -> dict[str, Any]

execution_id (property)

MemoryInterventionTrialRequest.execution_id() -> str

session_id (property)

MemoryInterventionTrialRequest.session_id() -> str

causal_budget_id (property)

MemoryInterventionTrialRequest.causal_budget_id() -> str

Release source · Runtime guarantees · Capability guides

`SQLiteMemoryInterventionExecutionStore`

from cayu.memory import SQLiteMemoryInterventionExecutionStore

SQLite execution journal using one exact JSON document per CAS revision.

Bases: MemoryInterventionExecutionStore.

durable_state_paths (method)

SQLiteMemoryInterventionExecutionStore.durable_state_paths() -> tuple[Path, ...]

Return the primary SQLite file for state-boundary validation.

begin (method)

async SQLiteMemoryInterventionExecutionStore.begin(record: MemoryInterventionExecutionRecord) -> MemoryInterventionExecutionRecord

load (method)

async SQLiteMemoryInterventionExecutionStore.load(execution_id: str) -> MemoryInterventionExecutionRecord | None

compare_and_set (method)

async SQLiteMemoryInterventionExecutionStore.compare_and_set(expected: MemoryInterventionExecutionRecord, desired: MemoryInterventionExecutionRecord) -> MemoryInterventionExecutionRecord

transition_runtime_dispatch_ownership (method)

async SQLiteMemoryInterventionExecutionStore.transition_runtime_dispatch_ownership(execution_id: str, request: DurableOperationOwnershipTransition) -> MemoryInterventionRuntimeOwnershipResult

init (method)

SQLiteMemoryInterventionExecutionStore.__init__(path: str | Path, *, ownership_clock: Callable[[], datetime] | None=None) -> None

Release source · Runtime guarantees · Capability guides