Immutable target-attempt intents¶

Offline Store foundation. Agent execution, live qualification and complete acquisition/publication remain unavailable.

An attempt intent records the intention to attempt one target from one retained frozen run. The caller knows its command key and complete request fingerprint before dispatch. The Store verifies the target and requirements inside the same native transaction that checks current authority and records the intent.

The record contains bounded references and digests. Original target and requirements bytes remain in the immutable frozen run. It contains no provider request body, remote run ID, attempt outcome, lease, timestamp, evidence, eligibility or publication state.

Explicit extension and trusted setup¶

open_acquisition_attempt_intent_store accepts the same explicit identity, operator limits, native handle and ownership/initialization options as open_acquisition_store. Its defaults remain owns_handle=False and initialize=False; handle remains keyword-only. It creates one client on the supplied backend; it performs no database resolution or fallback.

Existing AcquisitionStore, CurrentAcquisitionGrants, their method signatures, grant operation/resource aliases and the original factory remain available. The optional AcquisitionAttemptIntentStore extends that Store protocol with create_attempt_intent and get_attempt_intent. Its CurrentAcquisitionAttemptGrants adapter extends the existing grants protocol with authorize_attempt_intent(run: FrozenRunRef) -> GrantDecision. The new factory rejects a missing extension before backend initialization.

The added permission authorizes recording an intent for the exact frozen run. New admission also requires the existing current read_inputs permission for that run. Both decisions must agree on principal, scope and authority generation; the generation is checked against the locked Store guard. Namespace, digest and command identity convey no access. Grant adapters are trusted outer setup; structural protocol checks cannot certify their truthfulness.

Logical identity and frozen target pins¶

CreateAttemptIntent contains a caller-known CommandKey, exact FrozenRunRef, expected frozen manifest and requirements digests, and an AttemptTargetPin. The pin contains a zero-based target position plus key and content digests.

Validated operational value	Fields
`AttemptTargetPin`	`position`, `key_digest`, `content_digest`
`CreateAttemptIntent`	`key`, `run`, `frozen_manifest_digest`, `requirements_digest`, `target`
`AttemptIntentReceipt`	`intent`, `run`, `frozen_manifest_digest`, `requirements_digest`, `target`

These values are frozen, slotted and strictly validated. Digests contain 64 lowercase SHA256 hexadecimal characters; position is a nonnegative integer, with booleans refused. receipt.intent repeats the complete original CommandIdentity, also present as Completed.command.

Use the target array and key fields retained in the frozen run. Target content is hashed as canonical JSON for the complete selected record. The key digest hashes a canonical JSON array of values in retained key-field order. Fields are literal top-level names, including a literal dot when authored. There is no JSONata evaluation, nested-path interpretation, coercion or normalization.

Canonical JSON uses sorted object keys, comma/colon separators, UTF-8, ensure_ascii=False and allow_nan=False, matching the existing input Store. Hashes use SHA256. The Store checks the caller's expected pins against its verified original frozen bytes; it never reconstructs from the current head, an alias, an authoring file or a mutable definition.

For example, after trusted setup and retained-content preparation:

from pycharter.acquisition_store import AcquisitionPersistenceError, identify_command

# request is the complete immutable CreateAttemptIntent, prepared before I/O.
command = identify_command(request)
try:
    outcome = store.create_attempt_intent(request)
except AcquisitionPersistenceError:
    outcome = store.recover_command(command)
# Inspect outcome; retain this original request/key on absence or uncertainty.
# Recovery never authorizes a provider submission or automatic retry.

identify_command hashes the complete original request and identifies its kind as create_attempt_intent. Existing write-kind fingerprints remain unchanged. The acknowledgement and receipt repeat this identity; no ID needs to be learned after dispatch. A different command key intentionally denotes a different logical intent, even for the same target. This is not provider deduplication.

Atomic admission and exact recovery¶

A new command must use the current expected sequence, belong to the same Store incarnation and scope, and reference an earlier committed frozen run. The Store verifies the original freeze command, header, manifest and owned payload envelopes; recomputes the requirements and selected target digests; and checks target count, position and retained key fields. A no-work run cannot admit a target intent. No provider or grant-adapter call occurs inside this transaction; verification and mutation use the existing native Store transaction.

Admission writes one applied command record and advances the existing command count and sequence once. An exact retry returns the original receipt. Reusing the key with a different kind or fingerprint conflicts. Native transaction or uncertain acknowledgement failures raise the existing safe persistence error. They cannot become a successful result or a known absence.

After acknowledgement loss, recover the same original identity. An absent observation is only the state observed by that transaction: an outstanding original call may still commit. It proves neither remote absence nor permission to allocate another key and submit again.

Receipt inspection and content access¶

Operation	Required current authority	Result
New `create_attempt_intent`	Explicit attempt-intent grant and `read_inputs` for the frozen run	`Completed(status="applied", value=receipt)` or `Refused`
Exact completed create replay	`inspect` for the original command	`Completed(status="replayed", value=receipt)`
`get_attempt_intent`	`inspect` for the exact command	`ReadFound(status="found", value=receipt)` or `Refused`; missing is `not_found/missing`
`recover_command`	Existing `inspect` for the exact command	`Completed(status="replayed", ...)`, `RecoveryAbsent(status="absent", ...)` or `Refused`
`get_frozen_run`	Existing `read_inputs` for the frozen run	Verified retained target and requirements bytes

Receipt decoding verifies the command kind, exact identity, scope, bounded typed fields and the fingerprint reconstructed from the complete receipt. It never returns arbitrary unpacked backing data or raw target content. Finding or replaying a historical receipt does not establish current content availability, factual truth, freshness, execution permission or eligibility.

Store entrypoints reject malformed or over-limit supplied input and unsupported setup with fixed AcquisitionInputError (ErrorCode.CONFIG). Direct validated DTO construction can raise Pydantic ValidationError. Known access, conflict, capacity and backing-corruption outcomes return Refused, including corrupt/bad_content. Command recovery validates bounded backing data before using its identity. Actual native persistence and uncertain acknowledgement failures raise fixed AcquisitionPersistenceError (ErrorCode.ACQUISITION_PERSISTENCE_FAILED); they cannot become a known refusal or absence. Recovery itself can also raise that persistence error.

Store authority advances fence stale permission decisions. Revocation in an external grant source requires its coordinated Store authority advance to establish that same atomic ordering; the Store does not invent distributed revocation guarantees.

Stored authority generations must be native integers. Boolean or numeric-equality aliases cannot authorize reads, writes, inspection or replay. Authority maintenance also validates this before comparing or replaying its retained receipt; malformed backing state raises the existing fixed persistence error without applying a transition. This adds no new generation range, permission, public method or policy default.

Capacity and declared profiles¶

Each intent consumes one existing command slot and one bounded control record. The existing setup already reserves that control capacity. It consumes no new payload slot, pending reservation, generation or frozen-run admission. No new quota default, table, index, SQL migration, format upgrade or staging-cleanup algorithm is introduced.

At full command capacity, new intents refuse without advancing the sequence. Historical reads, exact replay/recovery, previously reserved staging cleanup and the reserved authority-maintenance slot remain available. There is no new intent TTL, retirement, key reuse or refund policy. Command capacity includes other input operations; it does not enforce the approved live 20-attempt or US$20 trial limits.

All five existing acquisition profiles implement the same interface: in-memory, SQLite, PostgreSQL, supported unsharded transaction-capable Mongo replica sets, and supported standalone Redis primary/no-replica/noeviction deployments. Existing profile restrictions and ownership behavior remain. Redis admission does not certify AOF durability; in-memory storage is process-local. Existing explicit destructive downgrade semantics are unchanged.

The complete provider request journal, remote lifecycle, worker fencing composition, current outcomes, evidence retention, factual checks, complete publication and live qualification remain open under AGPIPE-1 through AGPIPE-9.