Module T (Transaction Pipeline) — Functional Decomposition

Artifact layer. Third of three Canary module artifact layers: 1. Canonical spec (vendor-neutral) — Canary-Retail-Brain/modules/T-transaction-pipeline.md 2. Code/schema crosswalk (Canary-specific) — Brain/wiki/canary-module-t-transaction-pipeline.md (planned for Q/T/R; exists for J/P/F/C) 3. Functional decomposition (Counterpoint-substrate-aware, L2/L3 + user stories) — this card

Governing thesis

T is the inbound edge of every spine module. Every detection (Q), every customer projection (R), every device telemetry signal (N), every margin computation (P-derived), every transfer reconciliation (D), every PO match (J) — all eventually trace back to a row T wrote. If T is wrong, every downstream answer is wrong.

For a Counterpoint-shaped tenant, T's functional surface is dominated by two architectural pivots that distinguish it from the Square baseline: (1) ingress is poll-only, not webhook-driven, and (2) the inbound payload is Document-shaped omnibus — sales, returns, voids, transfers, POs, RTVs, GFC transactions all arrive through one endpoint family discriminated by DOC_TYP. The decomposition must accommodate both shapes (Square = webhook + Payment-shaped; Counterpoint = poll + Document-shaped) because the substrate-decoupling work documented in the Apr 25 delivery spec demands it.

T is ● Full direct in every Counterpoint Solution Map cell, but the cell hides real architectural difficulty: poll cadence discipline, type-routing on DOC_TYP, watermark management per (tenant, entity), multi-company-per-tenant identity, and the Document-omnibus pattern that lights up D and J modules from the same poll loop that lights up T.

Counterpoint Endpoint Substrate

Executive summary

Posture: archetype-shaped against Counterpoint specifically, with explicit accommodation for the Square baseline staying live. No real Counterpoint customer engaged. The Q card's L3s drove most of T.6 (substrate contracts to downstream); see Q's §Q.1 for the consumer-side perspective.

L1 → L2 → L3 framework

L1 (Solution Map cell)         T = ● Full direct (Counterpoint Document family)
                                 │
L2 (Process areas)               ├── T.1  Adapter ingress (poll OR webhook, per source)
                                 ├── T.2  Sealing & integrity (raw-bytes hash chain)
                                 ├── T.3  Provider-keyed parsing (Document → CanonicalEvent)
                                 ├── T.4  Canonical event publication (downstream dispatch)
                                 ├── T.5  Merkle anchoring (batch tree, anchor cadence)
                                 ├── T.6  Replay, backfill & idempotency
                                 └── T.7  Cross-module substrate contracts
                                 │
L3 (Functional processes)       (41 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Lives in SDDs + module specs
                                  (Canary-Retail-Brain/modules/T-transaction-pipeline.md,
                                   docs/sdds/canary/ncr-counterpoint-retail-spine-integration.md,
                                   2026-04-25-canary-for-rapidpos-delivery-spec.md cycles 7-8)

T.1 — Adapter ingress

Purpose. Receive vendor-shaped transactional events. Two ingress shapes must coexist on the same downstream pipeline: webhook push (Square — works today) and poll pull (Counterpoint — to be built). The substrate-decoupling pass defined in the delivery spec ensures the downstream consumers (T.2 onward) can't tell them apart.

Provider key. Every event entering T.1 carries (provider, tenant_id) from the moment it enters. Provider is derived from request signature (webhook) or known at construction time (poll loop). No event reaches T.2 without provider attribution.

L3 processes

User stories

• As the Counterpoint poll worker, I want a watermark per (tenant, company_alias, entity_type) so I never re-fetch already-consumed Documents and never miss a Document committed during my last cycle.
• As the Counterpoint poll worker, I want to know my per-tenant rate budget so a busy tenant doesn't starve a sibling tenant on the same Canary node.
• As an Operator in Owl, I want to ask "is the Counterpoint poll loop healthy for tenant X" and get last-successful-poll timestamps per entity type with explicit drift warnings.
• As an Operator, I want to force a one-shot ServerCache: no-cache poll on demand when I suspect cache staleness, without blowing up downstream.
• As an Operator onboarding a Counterpoint tenant, I want connection-test feedback (auth ok / APIKey ok / company alias resolves / sample entity returns) before I commit the credentials.

T.2 — Sealing & integrity

Purpose. Hash every received event over its raw bytes before any business logic runs, then chain those hashes per tenant to produce an append-only evidence ledger. The chain survives every downstream operation including parser changes — because the hash is over bytes-as-arrived, not over a parsed shape.

Stage ordering is patent-critical. Hash before parse. Parse is fallible; hash is not. Every later integrity claim depends on this ordering.

L3 processes

User stories

• As Canary's compliance posture, I want every byte of every received event sealed before any parser touches it, so a parser bug tomorrow cannot retroactively alter the integrity record.
• As an Auditor, I want to walk the evidence chain for a tenant from epoch to current and verify every link, without depending on any parsed shape.
• As Replay-tool, I want to re-run the parser against sealed bytes without re-sealing, so parser bugfixes reprocess history without breaking the chain.

T.3 — Provider-keyed parsing

Purpose. Convert vendor-shaped sealed bytes into CanonicalEvent rows. This is the L2 where the Document-omnibus pattern lives. For Counterpoint, one polled Document fans out into multiple CanonicalEvents — transaction header, lines flattened, payments flattened, taxes flattened, audit log entries flattened, pricing decisions flattened, original-doc references resolved.

Dispatch shape. Parser registry keyed by (provider, event_type) for webhooks, (provider, entity_type) for poll. Adding a third provider requires no edits to dispatch — just registry entry.

L3 processes

User stories

• As the Counterpoint parser, I want to type-route on DOC_TYP cleanly so a single polled Document produces transaction events, transfer events, or PO events — without the call site needing to know which.
• As the Counterpoint parser, I want PII-sensitive fields (SIG_IMG) redacted before any row reaches the database, so signature images literally never enter Canary's storage.
• As Q (Q.1.5 in the Q card), I want PS_DOC_AUDIT_LOG.ACTIV and LOG_ENTRY preserved verbatim — Q's rules pattern-match on these strings and any normalization breaks them.
• As Replay-tool, I want to re-run parsing against sealed bytes for a date range without re-emitting downstream events, so I can validate parser bugfixes against history.
• As an Operator, I want parse failures visible in a quarantine queue with the sealed bytes preserved, so I can diagnose without the parser blocking ingestion.

T.4 — Canonical event publication

Purpose. Hand sealed-and-parsed CanonicalEvents to downstream consumers. Every consumer reads from the same canonical surface; none reach into provider-specific shapes. This L2 owns the publication contract and the per-consumer dispatch.

L3 processes

User stories

• As Q's Chirp engine, I want every parsed transaction to arrive on canary:detection within seconds of the Document being polled, with the substrate snapshot inline (not as FK references).
• As R, I want every new CUST_NO reference in a transaction to trigger an upsert into the customer registry, even if the Customer record itself hasn't been polled yet (R catches up async).
• As D, I want only DOC_TYP=XFER events on my subscription — not every transaction; type-routing is T.3's job, not mine.
• As an Operator, I want per-consumer lag visible (Q at 2s, R at 8s, D at 15s) so a slow consumer doesn't silently fall behind.

T.5 — Merkle anchoring

Purpose. Batch sealed event hashes into a Merkle tree, anchor the root, expose per-event inclusion proofs. Today the anchor is mocked; v2 anchors as a Bitcoin ordinal inscription. This L2 is least urgent for Counterpoint cutover but most differentiating for the platform pitch.

L3 processes

User stories

• As Canary's Compliance Story, I want every sealed event to carry a verifiable inclusion proof that anchors back to a public commitment, so "the data wasn't tampered with after the fact" is provable, not asserted.
• As an Operator, I want to fetch any event's inclusion proof and walk it manually to the anchor, without depending on Canary's own systems.
• As Canary's Product Owner, I want the anchor cadence published as an SLA before tenants depend on it for compliance attestation.

T.6 — Replay, backfill & idempotency

Purpose. Operational discipline. Three concerns intersect: replay (re-process sealed bytes through a fixed parser), backfill (initial historical pull at tenant install), idempotency (same input produces same output every time). All three converge on the principle: the seal is the source of truth, not the parsed rows.

L3 processes

User stories

• As Replay-tool, I want to take a date range, re-parse every sealed event in it, and dry-run the new canonical rows against the existing rows so I can see exactly what changed before committing.
• As an Operator onboarding a Counterpoint tenant with 3 years of history, I want a published backfill SLA per entity type so I can set tenant-side expectations without guessing.
• As Canary's Product Owner, I want a documented policy for parser-change reclassification so when PAID_OUT semantically becomes POST_VOID, Q doesn't double-fire detections on the historical events.

T.7 — Cross-module substrate contracts

Purpose. T owes downstream modules specific guarantees about the canonical surface. This L2 is the contract registry: which fields, which preservation rules, which freshness commitments. Q's §Q.1 is the consumer view of these contracts; T.7 is the producer view.

Why it matters. A downstream module's L3 process can quietly fail if T silently changes a field's preservation. Naming the contracts here makes silent breakage impossible without explicit T-side change.

L3 contracts (registry)

User stories

• As Q, I want to assert at boot that all 12 T.7 contracts hold against the current T deployment, so a silent contract break shows up at startup, not at first detection-miss.
• As R, I want T's contract to upsert a Customer reference before the transaction event publishes — even if the upsert is "shell row, more data coming" — so my projections never reference unknown customers.
• As Canary's Product Owner, I want a contract-test suite (per Cycle 7 §7.3 in the delivery spec) that runs every contract in T.7 against every registered provider's adapter — Square, Counterpoint, future Aloha.

Canary Detection Hooks

Additional User Stories

• As a store manager, I need Canary to correctly ingest and classify transactions captured in offline mode (when the Counterpoint station was disconnected) so that my LP and sales reports are not understated for offline periods.

Assumptions requiring real-customer validation

These markers exist because the answer requires either a Counterpoint sandbox database, a real customer's Document corpus, or both.

Highest-leverage gaps: T-01 / T-02 (full DOC_TYP + void semantics) — these are the load-bearing structural assumptions for type-routing. Sandbox access (T-06) unblocks all of T-01 / T-02 / T-03 / T-04 / T-05 in one move.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
Counterpoint deployment shape: <on-prem | hosted | hybrid>
API hosting: <self-hosted Windows port 52000 | other>
Multi-company: <yes — N companies | no — single company>
Company aliases: [<alias1>, <alias2>, ...]
Backfill window: <epoch | <date> | <N years>>
Per-tenant poll budget: <reqs/min cap>
On-prem reachability path: <direct | customer-agent | tunnel>
Rapid POS extensions in scope: <yes — extension list | no>
Disabled DOC_TYPs (with reason):
  <type>: <reason>
  ...
ASSUMPTION resolutions:
  ASSUMPTION-T-NN: resolved as <answer>; source: <evidence>
  ...

Operating notes

• T and Q are the most coupled module pair. T.7 substrate contracts are largely driven by Q's §Q.1 consumer needs. Drift between T.7 (this card) and Q.1 (the Q card) means a contract was silently broken.
• The poll-only ingress for Counterpoint is the architectural pivot from the Square baseline. Cycle 7 in the delivery spec scaffolds the substrate to accept poll-shaped ingress; Cycle 8 builds the actual poller. This card describes the steady-state shape; the build sequencing lives in the delivery spec.
• Document is omnibus. A single GET /Document poll cycle produces fan-out into T (transactions), D (transfers), J (POs/RTVs), F (gift card transactions), and Q substrate (audit log). The L3 type-routing in T.3.2 is what makes this work; the L2 publication in T.4 is what fans it out cleanly.
• The Square baseline stays live unchanged through every cycle (Apr 25 spec § "Park Square" decision). T.3.9 is the only L3 that touches Square; everything else in T.3 is provider-keyed dispatch.

Related

• Canary-Retail-Brain/modules/T-transaction-pipeline.md — module-level architectural spec (CRDM, BSTs, schema, agent surface, security posture); referenced by every T.x section
• canary-module-q-functional-decomposition.md — sister card; T.7 contracts ↔ Q.1 consumer needs
• ncr-counterpoint-document-model.md — Document substrate detail (DOC_TYP, audit log, pricing, taxes, original-doc refs); referenced throughout T.3 and T.7
• ncr-counterpoint-api-reference.md — full API surface, auth, caching, error codes; referenced by T.1
• ncr-counterpoint-endpoint-spine-map.md — per-endpoint × CRDM × spine map; referenced by T.1 and T.4
• 2026-04-25-canary-for-rapidpos-delivery-spec.md — Cycles 7-8 build sequencing for the substrate decoupling and Counterpoint adapter
• docs/sdds/canary/ncr-counterpoint-retail-spine-integration.md — primary SDD; T.4 architecture comes from this
• garden-center-operating-reality.md — vertical-specific data noise patterns (manual entry errors, item-code drift); referenced by T.6 (parse-failure tolerance posture)
• (CATz) proof-cases/specialty-smb-counterpoint-solution-map.md — T row = ● Full direct; this card is the L2/L3 expansion of that cell
• (CATz, proposed) method/artifacts/module-functional-decomposition.md — the artifact template this card proves out alongside Q