recon_gen.common.l2.triage

BT.4 — Exception triage gap detector.

detect_gaps diffs derive_column_contracts(L2Instance) against the observed runtime in <prefix>_transactions and surfaces typed Gap records the triage page renders as decision cards. Each gap carries:

  • kind — discriminator (unmatched rail / template / missing LimitSchedule / missing metadata key).

  • diagnosis — operator-readable English (the card’s headline).

  • evidence — observed row count + (sometimes) a sample transaction id + extras like “L2 declares these rails: …”.

  • link_target — deep link to the relevant L2 editor list page (per BT.0 lock 5 — link-only v1; pre-fill of the create form is deferred until cold-read flags friction).

Severability: imports the L2 model + ColumnContracts + the async pool protocol. No html/render dependency — the triage page consumes typed Gap tuples and renders them.

Functions

detect_gaps(pool, prefix, instance, ...)

Run all four gap checks against the demo DB.

Classes

Gap(kind, diagnosis, observed_value, ...)

One gap card.

GapEvidence(row_count[, ...])

Row-side context for a Gap card.
class recon_gen.common.l2.triage.Gap(kind, diagnosis, observed_value, evidence, link_target)[source]

Bases: object

One gap card.

observed_value is the offending string for unmatched-name kinds (the rail_name / template_name that doesn’t resolve); None for kinds where the gap is structural (e.g. missing_limit_schedule is a missing TUPLE, not a single bad value).

Parameters:

  • kind (Literal['unmatched_rail', 'unmatched_template', 'missing_limit_schedule', 'missing_metadata_key'])

  • diagnosis (str)

  • observed_value (str | None)

  • evidence (GapEvidence)

  • link_target (str)

diagnosis: str
evidence: GapEvidence
kind: Literal['unmatched_rail', 'unmatched_template', 'missing_limit_schedule', 'missing_metadata_key']
observed_value: str | None
class recon_gen.common.l2.triage.GapEvidence(row_count, sample_transaction_id=None, extras=<factory>)[source]

Bases: object

Row-side context for a Gap card.

row_count is the absolute number of rows exhibiting the gap. sample_transaction_id (when set) is one offending row’s id so the operator can grep the source ETL log. extras carries free-form key-value pairs the card renders (“existing_rails”: “ach_credit, ach_debit, …”) — separate from the diagnosis prose so the render layer can format them as a sub-list rather than inline.

Parameters:

  • row_count (int)

  • sample_transaction_id (str | None)

  • extras (Mapping[str, str])

extras: Mapping[str, str]
row_count: int
sample_transaction_id: str | None
async recon_gen.common.l2.triage.detect_gaps(pool, prefix, instance, contracts, *, dialect)[source]

Run all four gap checks against the demo DB. Returns gaps in a stable order (kind, then offending value).

Return type:

tuple[Gap, ...]

Parameters: