CRB L4 Fill Plan — 2026-04-28

Governing thesis: The 357 MISSING-L4 flags in CRB-LINT-REPORT.md are not uniformly a documentation problem. For Category A processes — the ~120 L3s Canary owns — L4 activities already exist as working Python code in the Canary prototype (Canary/canary/services/). The L4 fill pass for Category A is a code-to-spec translation, not a documentation search. For Category B, L4s derive from the NCR/Counterpoint REST API docs. For Category C, no workflow L4s are needed — export API surface design only.

This reframes GRO-675 (L4 documentation pass) into three parallel tracks with distinct sources, sequences, and ownership.

Revised GRO-675 Framing

Impact on lint report: MISSING-L4 count stays at 357 until fill pass runs, but the resolution path and urgency changes by track. Track A (Category A) should be prioritized — these L4s are what a Go engineer needs to build Canary's core competency correctly.

Track A — Category A Python Service Map

Module T — Transaction Pipeline (Category A L3s)

The TSP pipeline is the best-documented subsystem in the codebase. Every sub-consumer has its own file with a processing sequence comment that is already L4-quality.

Key invariants from sub1_seal.py (must be preserved in Go): - BATCH_SIZE = 1 — chain integrity requires single-message processing - Advisory lock per merchant_id before chain hash computation - Hash verification (BEFORE parse) is the patent-critical ordering; never swap

Module Q — Loss Prevention (all 38 L3s)

Q is the most complete subsystem in the Python prototype. L4s can be extracted with high confidence.

Fox state machine (from VALID_STATUSES frozenset):

open → investigating → pending_review → escalated → closed
                                                  → referred_to_le

This is the L4 state machine spec for Q.3.2.

Chirp rule tiers (from rule_definitions.py): - Tier 1: Stateless — evaluate_stateless() — pure function, no I/O - Tier 2: Valkey counters — velocity-based rules - Tier 3: Full DB — cross-transaction correlation rules

Module N — LP Substrate Config (Category A L3s)

Module C — Customer Intelligence (Category A L3s)

Module D — Distribution Analytics (Category A L3s)

Module F — Finance Analytics (Category A L3s)

Module S — Space/Range Analytics (Category A L3s)

Module P — Pricing Intelligence (Category A L3s)

Module M — B2B Detection (Category A L3s)

Module L — Labor/LP Context (Category A L3s)

Module E — Execution (all 14 L3s)

Key discovery: hawk/ in the Python prototype IS the W module. cmd/hawk in CanaryGO maps to W (Execution), not an unknown package. The cmd/bull unknown is still unresolved.

Hawk-specific additions vs Fox: - generate_card() — narrative card generation (not in Fox) - get_wizard_template() — incident type wizard (not in Fox) - advance_workflow() — FSM with explicit workflow advancement (Fox uses update_case_status())

These additions are the W-over-Fox generalization — the L4 spec difference between Q.3 and E.3.

Track B — Category B Counterpoint API Source Map

L4 activities for Category B are derived from NCR Counterpoint REST API documentation and the PS_DOC schema. No Python code to translate — these are net-new integrations.

Note on T.2.1–T.2.2 (receipt stamp + dedup): These are infrastructure L3s. L4 spec comes from internal idempotency design, not Counterpoint docs.

Track C — Category C Export API Surface

No workflow L4s required. For each Category C module, specify the export API endpoint shape and the data Canary surfaces. The retailer's existing system calls Canary; Canary does not own the workflow.

Fill Sequencing

Week 1 — Track A Priority (Category A, no UX dependency)

Spec systematic Category A L4s from codebase. Priority order:

1. Q module (all 38 L3s) — fox/case_service.py + chirp/* = complete source. Highest value. Go engineer needs this first.
2. T module Category A L3s (T.2.3, T.2.4–T.2.6, T.4.1–T.4.9, T.5.1–T.5.5) — sub1_seal.py + merkle.py = precise spec available.
3. N.4.x LP substrate config — threshold_manager.py = complete source.
4. W module (all 14 L3s) — hawk/case_service.py + hawk/tools.py = complete source. Confirm cmd/hawk = W module.

Week 2 — Track B Priority (Category B systematic L3s)

Spec Category B L4s from Counterpoint API docs. Priority order:

1. T.1 Transaction ingestion (T.1.1–T.1.9) — GET /Documents is the foundation everything runs on.
2. S.1–S.4 Item catalog (17 endpoints) — needed for Q item context and LP accuracy.
3. C.1 Customer sync (C.1.1–C.1.5) — needed for investigator surface.
4. D.1–D.2 Inventory snapshot (7 endpoints) — needed for transfer-loss analytics.

Week 3+ — Remaining Track A + Track B

• Track A: C.2.x risk scoring, D.4–D.5 analytics, F.2.x LP analytics, S.5.x drift, P.2.x promo inference
• Track B: N.1–N.3 store config, F.1 PayCode/TaxCode, F.4–F.5 payment flow, O.6–O.7 receiving/RTV
• Track C: Export API specs (low urgency — needed for v1.1, not launch)

Blocked until ASSUMPTION-A-01 resolved

All 12 Module A L3s (regardless of track) remain blocked pending Jeffe's decision on Module A scope. See GRO-674.

Updated GRO-675 Issue Description

Revised scope: L4 fill pass is three parallel tracks, not one uniform documentation pass.

Track A (Category A, ~120 L3s): Code-to-spec translation from Canary Python prototype. Source files confirmed: chirp/, fox/, tsp/consumers/, tsp/merkle.py, evidence_chain.py, velocity_engine.py, impact_scoring.py, hawk/, alerts/, notification_service.py. Week 1 priority: Q module + T evidentiary L3s.

Track B (Category B, ~162 L3s): L4s from NCR Counterpoint REST API docs. Source: /Documents endpoint, IM_ITEM endpoints, PS_DOC schema, PS_STR_CFG_PS. Week 2 priority: T.1 ingestion + S.1–S.4 item catalog.

Track C (Category C, ~117 L3s): Export API surface only. No workflow L4s. Spec the endpoint shape; retailer's systems own the workflow.

Codebase Intel: Confirmed Service-to-Module Mapping

Derived from Python prototype service directory, to inform CanaryGO cmd/ package assignment:

cmd/bull remains UNKNOWN. Likely infrastructure (job queue runner, ETL runner) — etl_runner.py and period_aggregation.py in the Python prototype are the candidates. Inspect cmd/bull to confirm.

Pass: GRO-670 / GRO-675 | L4 Fill Plan v1 | A/B/C tracks confirmed | hawk/=W module discovery | cmd/bull still unknown