cadrumo.application.diagnostics module

Application-owned diagnostics, version reports, and repair probes.

build_cli_version_report() and render_cli_version_text() back the root aeat --version surface without loading the bundled registry.

build_config_repair_report() composes environment checks, WorkflowState loading, ActiveProfileHealth profile storage verdicts, WizardStatusReport readiness and secure-object decryptability into a ConfigRepairReport of DiagnosticCheck rows.

Every warn/fail DiagnosticCheck carries an application-owned precondition_verdict whose outcome is either a canonical action reference or an explicit no-recovery classification. The validator raises DiagnosticModelError if a row is silent or ambiguous. Renderers and CLI payloads can therefore treat the repair report as a typed contract, not a best-effort text scan.

Secure-object repair helpers return SecureObjectIntegrityReport instances. Dry-run preview and quarantine use the same decryptability probe so the committed mutation has the same namespace counts the operator saw before confirming it.

See also

application.workflow.profile_health supplies the redacted active-profile health verdict when secure workflow state is readable or degraded. application.wizard.status supplies semantic profile/auth readiness once the workflow state has loaded. entrypoints.cli.config._repair_cli wires these reports into aeat config repair commands.

build_cli_version_report()[source]

Return package identity for the CLI version surfaces.

Return type:

CliVersionReport

build_config_repair_report(*, ports, profile_decode_context=None)[source]

Return local diagnostics for the aeat config repair surface.

Returns a ConfigRepairReport enumerating every diagnostic check and any suggested repairs. It is restricted to actionable local configuration and secure-state health.

The secure-state branch reads WorkflowState, derives ActiveProfileHealth, and builds a WizardStatusReport. If that load fails, the report still emits profile and auth rows from the redacted health verdict so repair remains usable on a cold or degraded storage root. Each emitted warning/failure row is validated by DiagnosticCheck so the caller never receives a silent repair finding.

Return type:

ConfigRepairReport

Parameters:
render_config_repair_text(report)[source]

Render a compact human-readable repair report.

Preserves DiagnosticCheck.audience and never reconstructs command prose from an application-owned DiagnosticCheck.precondition_verdict. Typed actions are resolved by the entrypoint projection; this application renderer remains a diagnosis-only view.

Return type:

str

Parameters:

report (ConfigRepairReport)

build_profile_check(report, *, profile_health=None, state=None, profile_decode_context=None)[source]

Render semantic profile readiness from wizard status plus workflow state.

report supplies the WizardStatusReport counters and next action. profile_health can override the row when ActiveProfileHealth says the active profile bucket is unavailable. state lets the check expand missing profile keys from WorkflowState into per-key DiagnosticFinding rows.

Return type:

DiagnosticCheck

Parameters:
is_missing_active_bucket_session_failure(exc, *, ports)[source]

Classify a secure-state probe failure as a missing active bucket session.

This verdict decides whether secure_state.load warns (an expected cold start) or fails (a real fault), and whether the raw exception text reaches the operator, so it reads the typed exception chain rather than rendered text.

Scanning the rendered text for the class name could not survive this module’s own contract: a producer that stops passing an authored sentence positionally leaves str(exc) degraded to a locale key which no longer contains the class name, so the scan would quietly stop matching and every cold start would report as a hard fault. It also matched in the wrong direction, classifying any unrelated failure whose message merely mentioned the class as an expected cold start, which downgrades a genuine fault to a warning and suppresses its detail.

Both the __cause__ and __context__ edges are followed. An explicit raise ... from sets only the former and an incidental re-raise inside an except block sets only the latter, so a chain can fork across the two; the previous single-edge walk silently abandoned the __context__ branch whenever a __cause__ was present. Identity marking keeps a self- or mutually-referential chain from looping.

Return type:

bool

Parameters:
render_cli_version_text(report)[source]

Render a compact text line for human-facing version output.

Return type:

str

Parameters:

report (CliVersionReport)

secure_object_unreadable_total(*, ports)[source]

Return the count of rows the current master key cannot decrypt.

Lightweight wrapper over _probe_secure_objects_integrity() for consumers (notably aeat app overview status) that want to surface a concise “N rows unreadable” pointer towards aeat config repair without rendering the per-namespace breakdown themselves. The full breakdown remains the authority of ConfigRepairReport.

Return type:

int

Parameters:

ports (DiagnosticsPorts)

preview_quarantine_unreadable_secure_objects(*, ports)[source]

Report the rows repair quarantine would move, mutating nothing.

Backs the aeat config repair quarantine --dry-run preview. Runs the same per-namespace decryptability probe that quarantine_unreadable_secure_objects() uses to decide which rows to archive, but performs no copy and no delete: the secure_objects table is left exactly as found. The returned SecureObjectIntegrityReport carries, per namespace, the unreadable count (= rows the non-dry-run verb would quarantine) and the readable count (= rows it would retain), so the operator can confirm the blast radius before committing - the same preview shape reset-progress --dry-run already offers.

Return type:

SecureObjectIntegrityReport

Parameters:

ports (DiagnosticsPorts)

quarantine_unreadable_secure_objects(*, ports)[source]

Move every undecryptable secure-object row into the quarantine table.

Delegates to the injected secure-object diagnostic repository, whose storage implementation creates the quarantine archive table on first use, copies each undecryptable row’s metadata and (still encrypted) payload into the archive, then deletes the row from the active secure_objects table. Decryptable rows are not touched.

The user’s ciphertext is preserved in the archive; nothing is auto-deleted. If a missing master key is later recovered (e.g. restored from a recovery-key backup), the operator can manually re-import rows from the quarantine table.

Return type:

SecureObjectIntegrityReport

Returns:

A SecureObjectIntegrityReport whose namespaces report carries per-namespace unreadable counts (= rows moved to quarantine) and readable counts (= rows retained in secure_objects).

Parameters:

ports (DiagnosticsPorts)