aeat.application.repair_integrity module

Secure-object repair diagnostics, remediation decisions, and policy coverage.

The read side of this module produces metadata-only reports over encrypted secure-object rows. Integrity sweeps iterate namespaces in a SecureObjectRepository and return per-namespace SecureObjectNamespaceIntegrity counts; inventory rows expose row metadata and HMAC digests, never natural keys or payload bytes. These reports back the repair integrity surface and the quarantine dry-run path without emitting bucket events.

The write side is deliberately narrow: RepairRemediationDecision records persist non-destructive preserve / quarantine / rebuild / export-required planning outcomes as encrypted AUDIT-class rows. A decision record is evidence for a later operator workflow, not mutation authority.

The policy catalog returned by build_repair_policy_command_surface_catalog() mirrors repair, recovery, import, export, and bucket-history command surfaces against registered SecureObjectNamespaceDefinition metadata. Tests use it as a drift gate so new maintenance surfaces cannot appear without an explicit namespace policy.

See also

aeat.application.diagnostics

Builds the user-facing repair report and delegates quarantine preview / commit flows through this module’s active-bucket repair session.

SecureObjectRepository

Encrypted SQL repository whose namespace integrity probes and quarantine operation supply the repair data.

STORAGE_NAMESPACE_REGISTRY

Central registry copied into repair-policy namespace rows.

aeat.entrypoints.cli._config._repair_cli

CLI command surface that renders these reports and policy-backed repair actions.

exception RepairIntegrityError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: CoreError

Base error for secure-object integrity and repair-remediation failures.

Raised by the repair-integrity application layer when an integrity invariant or remediation contract is violated. Inherits from aeat.core.errors.CoreError so callers can catch either the specific subclass or the broad domain base without importing the full repair-integrity module.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RepairDecisionNotFoundError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: RepairIntegrityError

Raised when a repair-remediation decision lookup misses its target.

Fired by RepairRemediationDecisionRepository.load_decision() when no row exists for the requested decision_id. Distinct from a generic not-found so the CLI can produce an actionable hint (e.g. list existing decisions) without catching broad exception classes.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
class RepairIntegrityReport(**data)[source]

Bases: BaseModel

Metadata-only secure-object integrity report.

namespaces carries one SecureObjectNamespaceIntegrity per probed namespace. check is the aggregate DiagnosticCheck row used by repair renderers; failing reports carry the quarantine command as the next action.

See also

build_repair_integrity_report()

Producer that fills this report from real secure-object decryptability probes.

SecureObjectIntegrityReport

Config-repair rollup that uses the same namespace integrity shape.

Parameters:
namespaces: tuple[SecureObjectNamespaceIntegrity, ...]
readable_total: int
unreadable_total: int
check: DiagnosticCheck
class RepairListRow(**data)[source]

Bases: BaseModel

One metadata row in the secure-object repair inventory.

Rows are projected from SecureObjectDecryptabilityRow values returned by iter_namespace_decryptability(). object_key_digest is the stored HMAC digest, not the natural object key. reason is populated only for unreadable rows and must remain a diagnostic class of failure rather than decrypted payload context.

Parameters:

  • namespace (str)

  • object_key_digest (str)

  • readable (bool | None)

  • row_id (int | None)

  • classification (str | None)

  • schema_version (int | None)

  • written_at (datetime | None)

  • reason (str | None)

namespace: str
object_key_digest: str
readable: bool | None
row_id: int | None
classification: str | None
schema_version: int | None
written_at: datetime | None
reason: str | None
class RepairListReport(**data)[source]

Bases: BaseModel

Internal secure-object inventory report for one namespace.

The report combines the namespace’s SecureObjectNamespaceIntegrity counts with metadata-only RepairListRow entries. Operator-facing repair commands render aggregate integrity and quarantine previews rather than exposing a broad raw list command.

Parameters:
namespace: str
integrity: SecureObjectNamespaceIntegrity
rows: tuple[RepairListRow, ...]
rows_total: int
filter_mode: str
build_repair_integrity_report(*, namespace=None, repository=None)[source]

Probe secure-object decryptability and return a RepairIntegrityReport.

When namespace is set, only that namespace is probed; otherwise every namespace currently present in the repository is scanned. Without an injected repository, the probe opens the active bucket repair session before resolving the runtime-bound SecureObjectRepository.

Return type:

RepairIntegrityReport

Parameters:

  • namespace (str | None)

  • repository (_SecureObjectRepositoryProtocol | None)

active_bucket_repair_session()[source]

Best-effort session opener for active-bucket repair diagnostics.

Repair integrity and quarantine previews need to test decryptability under the active bucket key, but they are bootstrap-adjacent diagnostics rather than profile enrollment flows. If a session is already active it is reused; otherwise the configured master-key provider is entered for the span. A provider failure is logged and the caller still observes the normal repository/runtime readiness result.

See also

preview_quarantine_unreadable_secure_objects()

Dry-run repair flow that uses this context before probing decryptability.

quarantine_unreadable_secure_objects()

Commit flow that uses this context before calling quarantine_unreadable_rows().

Return type:

Generator[None]

build_repair_list_report(*, namespace, include_all=False, only_unreadable=False, repository=None)[source]

List secure-object metadata stored under namespace.

--all returns every key; --unreadable filters to only the rows whose payload cannot be decrypted under the current master key. Default behaviour (both flags False) returns the full key set but caps the inventory at the integrity-readable count for bandwidth control on large namespaces — same as --all for namespaces with no integrity issues.

Returns a RepairListReport enumerating matching HMAC digests and their decryptability status. The report never exposes natural object keys or payload bytes. Without an injected repository, the list path enters active_bucket_repair_session() before resolving the active SecureObjectRepository.

Return type:

RepairListReport

Parameters:

  • namespace (str)

  • include_all (bool)

  • only_unreadable (bool)

  • repository (_SecureObjectRepositoryProtocol | None)

class RepairRemediationDecision(**data)[source]

Bases: BaseModel

Non-destructive planning record for a repair-remediation outcome.

Decision records persist preserve / quarantine / rebuild / export-required planning outcomes without authorising mutation. mutation_authorized is hard-typed to False so a decision record can never be mistaken for an execute order. The policy catalog keeps these records visible through RepairPolicyCommandSurface decision-trail anchors.

The decision_id is content-bound via repair_remediation_decision_id() to every other field, so persisting an arbitrary sha-shaped key for a different remediation target or evidence requirement set is rejected at load time by the re-derivation guard.

See also

RepairRemediationDecisionRepository

Profile-local encrypted persistence for these decision records.

REPAIR_INTEGRITY_DECISION_NAMESPACE

Secure-object namespace used to store the decisions.

Parameters:

  • decision_id (str)

  • target_namespace (str)

  • target_object_key_digest (str | None)

  • outcome (Literal['preserve', 'quarantine', 'rebuild', 'export-required'])

  • decided_at (datetime)

  • decided_by (str)

  • reason (str)

  • likely_origin (str)

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

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

  • mutation_authorized (Literal[False])

  • schema_version (str)

decision_id: str
target_namespace: str
target_object_key_digest: str | None
outcome: _RepairDecisionOutcome
decided_at: datetime
decided_by: str
reason: str
likely_origin: str
replacement_evidence_requirements: tuple[str, ...]
verified_replacement_evidence_refs: tuple[str, ...]
mutation_authorized: Literal[False]
schema_version: str
repair_remediation_decision_id(*, target_namespace, target_object_key_digest, outcome, decided_at, decided_by, reason, likely_origin, replacement_evidence_requirements, verified_replacement_evidence_refs)[source]

Return the deterministic SHA-256 id for a repair-remediation decision.

Content-bound to every payload field including decided_at so two structurally identical re-runs at the same instant produce the same id; differing payloads produce different ids. The hash domain matches the RepairRemediationDecision field set exactly so the load-time re-derivation guard catches any payload mutation that bypassed the constructor.

Return type:

str

Parameters:

  • target_namespace (str)

  • target_object_key_digest (str | None)

  • outcome (Literal['preserve', 'quarantine', 'rebuild', 'export-required'])

  • decided_at (datetime)

  • decided_by (str)

  • reason (str)

  • likely_origin (str)

  • replacement_evidence_requirements (Sequence[str])

  • verified_replacement_evidence_refs (Sequence[str])

class RepairRemediationDecisionRepository(repository=None)[source]

Bases: object

Profile-local persistence for RepairRemediationDecision records.

Decisions are persisted through SecureObjectRepository as encrypted AUDIT-class secure-object rows under the active profile’s bucket. The object key is the decision’s content-addressed decision_id; the payload is the decision’s JSON model dump. Listing returns rows in decision-time descending order.

The repository accepts an optional SecureObjectRepository injection for tests; the no-arg constructor resolves the active bucket’s secure-object repository via the standard runtime path.

Parameters:

repository (SecureObjectRepository | None)

save_decision(decision)[source]

Persist one decision as an encrypted AUDIT-class secure-object row.

Return type:

None

Parameters:

decision (RepairRemediationDecision)

load_decision(decision_id)[source]

Load one decision by its content-addressed id; re-derives + checks the id.

Returns the RepairRemediationDecision matching decision_id after verifying its content-addressed identity.

Return type:

RepairRemediationDecision

Parameters:

decision_id (str)

list_decisions()[source]

Return every persisted RepairRemediationDecision in decision-time descending order.

Return type:

tuple[RepairRemediationDecision, ...]

class RepairPolicyNamespaceClassification(**data)[source]

Bases: BaseModel

Minimal namespace classification attached to a repair-policy surface.

Embedded in RepairPolicyNamespacePolicy so command catalog rows can describe non-registered bundle / filing / ledger surfaces and registered secure-object namespace scopes with the same shape.

Parameters:

role (str)

role: str
class RepairPolicyNamespacePolicy(**data)[source]

Bases: BaseModel

Policy metadata for one namespace governed by a command surface.

Registered secure-object namespaces copy owner, sensitivity, schema version, and scope from SecureObjectNamespaceDefinition so repair and recovery surfaces stay tied to the namespace registry instead of parallel role markers. RepairPolicyCommandSurface attaches these rows to every CLI surface that can inspect, repair, import, export, or recover namespace-owned data.

Parameters:

  • namespace_classification (RepairPolicyNamespaceClassification)

  • owner_domain (str)

  • repair_policy (str)

  • recovery_policy (str)

  • mutation_authority (str)

  • registered_namespace_key (str | None)

  • registered_namespace (str | None)

  • registered_owner (str | None)

  • registered_sensitivity (str | None)

  • registered_schema_version (int | None)

  • registered_scope (str | None)

namespace_classification: RepairPolicyNamespaceClassification
owner_domain: str
repair_policy: str
recovery_policy: str
mutation_authority: str
registered_namespace_key: str | None
registered_namespace: str | None
registered_owner: str | None
registered_sensitivity: str | None
registered_schema_version: int | None
registered_scope: str | None
class RepairPolicyCommandSurface(**data)[source]

Bases: BaseModel

One catalogued repair-policy CLI command surface.

Each row links a command path to its owner domains, decision-trail anchors, and the namespace policies that constrain any repair or recovery behavior reachable from that command family.

See also

RepairPolicyNamespacePolicy

Per-namespace policy rows attached to a command surface.

build_repair_policy_command_surface_catalog()

Executable catalog that mirrors the repair and recovery CLI surface.

Parameters:
command_path: str

The canonical CLI command path (e.g. config repair integrity objects).

command_family: str
owner_domains: tuple[str, ...]
namespace_policies: tuple[RepairPolicyNamespacePolicy, ...]
build_repair_policy_command_surface_catalog()[source]

Return the RepairPolicyCommandSurface catalog for repair-policy CLI surfaces.

The catalog mirrors the Typer command registry for repair, recovery, import, export, and bucket-history surfaces. It is used as an executable drift gate: adding a new command in those families requires a policy row here, and secure-object rows must derive their metadata from the central namespace registry. Each row also carries decision links for RepairRemediationDecision governance.

See also

STORAGE_NAMESPACE_REGISTRY

Source of secure-object namespace metadata copied into catalog policies.

SecureObjectNamespaceDefinition

Registered namespace declaration projected into policy rows.

Return type:

tuple[RepairPolicyCommandSurface, ...]