recon_gen.common.drill

Typed cross-sheet drill helpers.

K.2 spike caught a sneaky bug class: a drill action bound a DATETIME source column (exception_date) to a SINGLE_VALUED string parameter (pArActivityDate), and QuickSight silently coerced it to a full timestamp text "2026-04-07 00:00:00.000" that never matched the destination’s TO_CHAR-formatted posted_date column. Both ends were “STRING” at the AWS coarse-type level, but the textual encodings differed and the destination filter quietly produced zero rows. Bugs like this look like missing data, not broken wiring — corrosive to user trust.

Per the user’s “encode invariants in the type system” preference, the fix isn’t a validation test that walks the generated output; it’s a typed constructor that refuses to wire incompatible shapes at all. The typed wrappers here let any wrong wiring fail at the call site with a TypeError that names both sides of the mismatch.

Usage:

from recon_gen.common.drill import (
    DrillParam, DrillResetSentinel, cross_sheet_drill, field_source,
)

P_AR_ACCOUNT = DrillParam("pArAccountId", ColumnShape.ACCOUNT_ID)

cross_sheet_drill(
    action_id="...",
    name="View Transactions for Account-Day",
    target_sheet=SHEET_AR_TRANSACTIONS,
    writes=[
        (P_AR_ACCOUNT, field_source("ar-todays-exc-account",
                                    DS_AR_UNIFIED_EXCEPTIONS, "account_id")),
        (P_AR_ACTIVITY_DATE, field_source(...)),
        (P_AR_TRANSFER, DrillResetSentinel()),
    ],
    trigger="DATA_POINT_MENU",
)

Functions

`cross_sheet_drill`(action_id, name, ...[, ...])	Build a NavigationOperation + SetParametersOperation drill.
`field_source`(field_id, dataset_id, column_name)	Resolve `column_name`'s shape from its registered dataset contract.
`set_drill_parameters`(*writes)	Construct a `CustomActionSetParametersOperation` from typed writes.

Classes

`DrillParam`(name, shape)	Destination parameter on a drill action — name + expected shape.
`DrillResetSentinel`([value])	Marker that a drill should reset a parameter to the sentinel value.
`DrillSourceField`(field_id, shape)	Source field on a drill action — visual field id + resolved shape.
`DrillStaticDateTime`(value)	Marker that a drill should write a fixed ISO-8601 datetime literal to a `DateTimeParam` destination.

class recon_gen.common.drill.DrillParam(name, shape)[source]

Bases: object

Destination parameter on a drill action — name + expected shape.

The shape captures the parameter’s value semantics; set_drill_parameters refuses to write a source field whose shape differs.

Parameters:

name (ParameterName)
shape (ColumnShape)

name: ParameterName

shape: ColumnShape

class recon_gen.common.drill.DrillResetSentinel(value='__ALL__')[source]

Bases: object

Marker that a drill should reset a parameter to the sentinel value.

The destination calc-field filter recognizes the sentinel as PASS, so writing this clears the filter without needing an empty-string or null-value path that QuickSight’s drill-action code path won’t deliver to calc fields cleanly.

Parameters:: value (str)

value: str = '__ALL__'

class recon_gen.common.drill.DrillSourceField(field_id, shape)[source]

Bases: object

Source field on a drill action — visual field id + resolved shape.

Build via field_source(field_id, dataset_id, column_name) so the shape is read from the dataset contract, not duplicated by hand.

Parameters:

field_id (str)
shape (ColumnShape)

field_id: str

shape: ColumnShape

class recon_gen.common.drill.DrillStaticDateTime(value)[source]

Bases: object

Marker that a drill should write a fixed ISO-8601 datetime literal to a DateTimeParam destination.

Use case: cross-sheet drills where the destination sheet has a universal date-range filter the source sheet doesn’t share — e.g. L1’s Pending Aging → Transactions. The aging sheet is a current-state view (rows can be arbitrarily old); the Transactions sheet’s universal-filter window defaults to last 7 days. Without a date write the drill-target leg falls outside the destination’s window and the table renders empty. Writing DrillStaticDateTime("1990-01-01T00:00:00.000Z") to the destination’s date-start param widens the window so the drill- target row is always visible.

QuickSight has no “now” or “rolling” expression you can write via SetParametersOperation — the only options are SourceField (column ref) or static CustomValues. Pick the static value carefully so the picker-shown date isn’t misleading; the L1 app uses "1990-01-01T..." for start and "2099-12-31T..." for end, framing the explicit “all time” intent.

Format: ISO-8601 with millisecond precision and the trailing Z, matching what the L2FT app already uses for its static StaticValues defaults.

Parameters:: value (str)

value: str

recon_gen.common.drill.cross_sheet_drill(action_id, name, target_sheet, writes, trigger='DATA_POINT_CLICK')[source]

Build a NavigationOperation + SetParametersOperation drill.

QuickSight requires a NavigationOperation before a SetParametersOperation, even when the target is the current sheet (used for same-sheet ledger→subledger filtering). This helper wraps both operations in the canonical order so callers don’t re-derive the shape.

Per K.2 cleanup: the typed writes list passes through set_drill_parameters so any shape mismatch fails here, at the wiring site, with both sides named.

Return type:

VisualCustomAction

Parameters:

action_id (str)
name (str)
target_sheet (SheetId)
writes (list[tuple[DrillParam, DrillSourceField | DrillResetSentinel | DrillStaticDateTime]])
trigger (Literal['DATA_POINT_CLICK', 'DATA_POINT_MENU'])

recon_gen.common.drill.field_source(field_id, dataset_id, column_name)[source]

Resolve column_name’s shape from its registered dataset contract.

Raises TypeError if the column has no shape tag (it isn’t drill- eligible), pointing at the call site so the developer can either tag the column in the contract or pick a different source column. Raises KeyError if the dataset_id isn’t registered (usually means the dataset hasn’t been built in this process yet — ensure build_all_datasets runs before visuals).

Return type:

DrillSourceField

Parameters:

field_id (str)
dataset_id (str)
column_name (str)

recon_gen.common.drill.set_drill_parameters(*writes)[source]

Construct a CustomActionSetParametersOperation from typed writes.

Validates shape compatibility at construction time: writing a DrillSourceField whose shape doesn’t match the DrillParam raises TypeError at the call site. DrillResetSentinel is always shape-compatible (it writes a literal sentinel string that the destination calc-field interprets, regardless of param shape).

Refuses an empty writes list — a no-op SetParametersOperation is almost certainly a wiring bug.

Return type:: CustomActionSetParametersOperation
Parameters:: writes (tuple[DrillParam, DrillSourceField | DrillResetSentinel | DrillStaticDateTime])