aeat.adapters.persistence.storage.sql._secure_object_row_codec module

Row-level codec helpers for SQL secure-object records.

This module keeps the encrypted row decode path and post-write revision metadata update close to the SQL secure-object adapter without leaving both algorithms embedded in the repository class. It derives and persists revision lineage after ciphertext is written, validates row classification and the schema-lineage ceiling before decrypting (a version above the consumer’s current version is refused; an older version decrypts under its written version and is chain-upgraded to current), and refuses rows whose revision hashes no longer match their stored metadata.

See also

SecureObjectRepository

Repository that delegates revision metadata writes and row decoding here.

derive_revision_id()

Deterministic revision-id primitive used after a row write.

verify_revision_self_consistency()

Integrity check applied before decrypting an existing row.

build_revision_ancestor_ids()

Revision-lineage helper used to persist ancestor chains.

SecureObjectRecord

Plaintext record returned after classification, schema, lineage, and AEAD checks pass.

secure_object_payload_aad()

Associated-data builder that binds ciphertext to row identity.

SensitivityClass

Expected row classification validated before a row is decoded.

Governing vault records

2026-05-22-secure-storage-production-hardening-architecture-adr and 2026-05-28-secure-storage-production-hardening-w04-p07-s30-review-audit require secure-object revision lineage and conflict-safe metadata.

write_revision_metadata(session, *, row_id, namespace, schema_version, written_at, payload, previous_revision_id, previous_revision_ancestor_ids, previous_payload_hash, write_provenance, source_event_id, conflict_policy)[source]
Return type:

None

Parameters:

  • session (Session)

  • row_id (int)

  • namespace (str)

  • schema_version (int)

  • written_at (datetime)

  • payload (bytes)

  • previous_revision_id (str | None)

  • previous_revision_ancestor_ids (tuple[str, ...])

  • previous_payload_hash (str | None)

  • write_provenance (str)

  • source_event_id (str | None)

  • conflict_policy (str)

secure_object_record_from_row(row, *, expected_class, max_supported_version, namespace_definition=None, enforce_registered_row_schema)[source]
Return type:

SecureObjectRecord

Parameters:
secure_object_list_item_from_raw_row(raw, *, namespace, expected_class, max_supported_version, namespace_definition, enforce_registered_row_schema)[source]

Decode one raw iter_records_with_failures row into a typed outcome.

Fault-isolated: every failure mode (unknown classification, classification mismatch, unreadable schema version, decrypt failure, revision-lineage inconsistency, upgrade failure) returns a SecureObjectUnreadable carrying the reason instead of raising, so a caller iterating many rows can attribute a failure to its own row and keep inspecting the rest.

Return type:

SecureObjectRecord | SecureObjectUnreadable

Parameters: