recon_gen.common.l2.probe

Probe fetcher — BT.2’s observed-row side.

fetch_probe_rows queries <prefix>_transactions filtered to one L2 slice (rail / template / chain parent) within an operator-selected date window. Returns a ProbeResult with up to limit rows ordered by posting DESC + the total matching row count so the page can render “Showing 10 of 1,247”.

Three slice kinds:

  • rail — narrows on rail_name = <name>. The most common case; every transaction carries a rail_name.

  • transfer_template — narrows on template_name = <name>. Only template-bundled transfers carry a non-NULL template_name; standalone rail firings have NULL there.

  • chain — narrows on rows whose rail_name OR template_name matches the chain’s parent. Picks up parent firings on either side (parents can be either a Rail or a TransferTemplate per SPEC).

The fetcher is pure SQL — no contract evaluation, no per-cell ✓/✗ decoration. The companion evaluate_predicate helper applies a single ColumnPredicate to a ProbeRow so the render layer can paint each cell; both directions stay decoupled so a CLI / Triage surface can reuse the same primitives.

Severability: imports the SQL dialect + the async pool protocol + the BT.5 contract types. No html/render dependency.

Functions

evaluate_predicate(predicate, row)

Apply one ColumnPredicate to a ProbeRow.

fetch_probe_rows(pool, prefix, *, kind, ...)

Fetch observed transactions matching the slice + window.

Classes

ProbeResult(rows, total_count)

Probe page payload: up to limit rows + total matching count.

ProbeRow(transaction_id, rail_name, ...)

One observed transaction row.
class recon_gen.common.l2.probe.ProbeResult(rows, total_count)[source]

Bases: object

Probe page payload: up to limit rows + total matching count.

rows is ordered by posting DESC so the most recent activity is visible first (matches the operator’s mental model when debugging “did the ETL just run”). total_count is the pre-limit COUNT(*) so the page can render “Showing N of M” without a second round-trip.

Parameters:

  • rows (tuple[ProbeRow, ...])

  • total_count (int)

rows: tuple[ProbeRow, ...]
total_count: int
class recon_gen.common.l2.probe.ProbeRow(transaction_id, rail_name, template_name, account_role, amount_direction, transfer_parent_id, posting, metadata)[source]

Bases: object

One observed transaction row.

Columns mirror <prefix>_transactions’s contract-relevant subset (the columns BT.5’s predicates reference). metadata is the raw JSON text — predicate evaluation does the per-key extraction.

Parameters:

  • transaction_id (str)

  • rail_name (str | None)

  • template_name (str | None)

  • account_role (str | None)

  • amount_direction (str)

  • transfer_parent_id (str | None)

  • posting (datetime)

  • metadata (str | None)

account_role: str | None
amount_direction: str
metadata: str | None
posting: datetime
rail_name: str | None
template_name: str | None
transaction_id: str
transfer_parent_id: str | None
recon_gen.common.l2.probe.evaluate_predicate(predicate, row)[source]

Apply one ColumnPredicate to a ProbeRow.

Return type:

bool | None

Returns:

  • True if the predicate holds on the row.

  • False if the predicate is contradicted.

  • None if the predicate’s column has no value to evaluate against (e.g. a NULL account_role on a row whose contract expects an account_role IN {…} membership — not a violation per se, but also not a confirmation; render with “—“).

Parameters:

Metadata keys (column = "metadata.<key>") are evaluated by a naive JSON-text search for the key — the same shape SPEC §F4’s SQL/JSON path expressions use. Robust enough for the probe surface; Triage (BT.4) does proper JSON_VALUE extraction via SQL.

async recon_gen.common.l2.probe.fetch_probe_rows(pool, prefix, *, kind, name, date_from, date_to, dialect, limit=25)[source]

Fetch observed transactions matching the slice + window.

Parameters:

  • pool (AsyncConnectionPool) – AsyncConnectionPool against the demo DB.

  • prefix (str) – L2 instance prefix.

  • kind (Literal['rail', 'transfer_template', 'chain']) – Slice discriminator.

  • name (str) – The L2-declared identifier (rail name / template name / chain parent name).

  • date_from (date) – Inclusive window start (posting >= date_from 00:00).

  • date_to (date) – Inclusive window end (posting < date_to 23:59:59.999…). Passed as posting <= <date_to> 23:59:59 to dodge timezone / sub-second-precision footguns on Oracle.

  • dialect (Dialect) – SQL dialect; drives column-name case folding.

  • limit (int) – Row cap; default 25 (the page table size).

Return type:

ProbeResult

Returns:

ProbeResult with rows ordered by posting DESC + the pre-limit total count.