Skip to content

Retained acquisition-attempt reports

The optional report journal retains immutable, caller-supplied canonical JSON against an exact retained request. Different command keys append reports; exact replay returns the original metadata. Report claims do not select current outcomes or establish provider, factual, remote-ID, evidence, eligibility or publication authority.

This offline slice has passed local memory/SQLite verification. Native five-profile acceptance, independent review and complete gates remain pending. It enables no browser task or live price collection.

Explicit setup and values

open_acquisition_attempt_report_store(identity, limits, grants, *, handle, owns_handle=False, initialize=False) returns the optional AcquisitionAttemptReportStore. It uses the existing explicit connection, initialization, ownership, limits and supported-profile rules. Existing factories and protocol methods keep their signatures and defaults.

CurrentAcquisitionAttemptReportGrants extends the request-grant interface with authorize_attempt_report_write(request_identity) and authorize_attempt_report_read(request_identity). Each receives the full original retained-request command identity. Decisions bind the current actor, scope and exact native-integer authority generation. Report write/read also requires current frozen-input read permission; metadata inspection remains a separate permission. Coordinated authority advancement fences stale grants.

The four frozen validated values are:

  • RetainAttemptReport(key, request, body_json): original command, exact AttemptRequestRef and canonical UTF-8 JSON-object bytes.
  • AttemptReportRef(command, request): full fingerprinted report identity and original parent reference.
  • AttemptReportReceipt(report, body_digest, body_length, charged_payload_bytes): inspectable metadata without the supplied body.
  • AttemptReportRecord(receipt, body_json): the exact supplied bytes returned under current report/input read authority.

Given an already retained request and a valid caller-known next command key:

from pycharter.acquisition_store import (
    AttemptReportRef,
    RetainAttemptReport,
    identify_command,
    open_acquisition_attempt_report_store,
)

command = RetainAttemptReport(
    report_key, retained_request_ref, b'{"claim":"unverified"}'
)
report_ref = AttemptReportRef(identify_command(command), retained_request_ref)
with open_acquisition_attempt_report_store(
    identity, limits, grants, handle=handle
) as reports:
    metadata = reports.retain_attempt_report(command)
    content = reports.get_attempt_report(report_ref)

The example assumes trusted setup, verified original references and a valid sequence; supplied identifiers confer no permission. Retention and read results must be checked for refusal. No report status vocabulary is inferred from JSON.

Atomic admission and bounded history

New admission verifies the exact actual retained request, applied intent and original frozen target/requirements. One existing native transaction checks current permissions and accounting, then performs one bounded history pass. It preserves each report by its own command ordinal and complete parent reference, including conflicting references appearing before or after valid ones. Existing one-body-per-intent uniqueness still applies. An allocated missing or corrupt record cannot be treated as a fresh opportunity to write.

History work retains the existing command/control limits and 16MiB aggregate ceiling. The sum of retained inline request/report charges must not exceed the stored retained counter. This is a lower-bound consistency check, rather than reconstruction of every frozen envelope or certification of physical storage. Exact selected reads/replay do not scan unrelated history or re-observe current heads and freshness.

One applied command holds a private report_payload field. A body of n bytes charges q = 4 * ceil(n / 3) retained payload bytes and advances commands and next sequence by one. Its whole serialized record must also fit the existing control bound. No new slot, reservation, table, migration, counter, refund, retirement, TTL or quota default is introduced. Full-capacity replay/read and existing reserved cleanup retain their contracts.

Raw body size is checked before snapshot/parsing. The full packed request, actual encoding, canonical JSON, digest and exact parent linkage are validated. Malformed known content refuses safely; actual native failures remain fixed persistence errors. Metadata recovery validates the retained fingerprint and returns no body. Current content reads validate the selected report and actual parent request/intent under explicit current permissions.

Compatibility and limits

identify_command accepts the additional report request. Updated recovery annotations include report metadata; existing generic invariance remains unchanged. Older executables cannot decode this new command kind and must refuse safely. Existing request fingerprints, factory bodies, operation aliases, authority algorithms, backend schema and initialization behavior are unchanged.

The implementation targets all existing profiles: explicit memory, SQLite, PostgreSQL, an unsharded transaction-capable Mongo replica set, and standalone Redis with no replicas and noeviction. Local checks establish only their executed profiles; deployment durability is separate.

Trusted preparation must decide what supplied content may be retained. The journal does not certify secret freedom, provider completeness, remote effects, chronology or factual truth. It does not enforce the pilot's live attempt/cost limits or approved evidence-retention period. Those obligations and full AGPIPE-4 remain open in BACKLOG.md.