Rx code map

rx codemap

Checked against main through cd58150 (Oct 11, 2026); not verified production behavior.

Scope: committed main only. Untracked working-tree files (for example notifier/, ops/adk_fill_agent/, ops/email_actions/, claude.md, RxVerify iPad.dc.html) are not described. Everything comes from reading source and checked-in config. Unit files, plists and docs show intended config, not what is loaded or running; deployed state needs a runtime check (cloud/RUNTIME.md, docs/OPERATIONS.md, AGENTS.md). No Fast, SQL, MCP or remote system was contacted. More detail: the code wiki docs/local-wiki/.

What this repository is

Pharmacy automation around the Liberty/PharmacyOne pharmacy system (SQL Server S013529 / RxqLAnsePharmacy). Three core services and one worker command:

Around them: a scanner library used for entry (scanner/), billing runners and PharmacyOne tools on the WS3 guest VM (ops/windows/), operator tools and Mac pollers (ops/), an iPad/iPhone app with a Mac relay and a cloud delivery relay (ios/), cloud runtime config (cloud/), and tests (tests/).

flowchart LR
  subgraph Liberty["Liberty SQL Server (external)"]
    SQL[(RxqLAnsePharmacy)]
  end
  Drasi["Drasi CDC (external code)"] -->|escript-lifecycle.ndjson| L[launch.py]
  L -->|"launch.sh kind script event escript"| W["Pi worker<br/>tools.mjs + tracing/index.mjs"]
  W -->|"POST /v1/case"| G[case_gateway.Cases]
  L -->|"POST /v1/case owner / decision_retry / worker_retry / source_classification"| G
  G -->|"core.run(action=...)"| C[pharmacy_fast_core.PharmacyFast]
  G -->|"entry.propose / create"| E[entry.py + scanner/]
  G -->|"bill(...) on committed ADD"| B[add_billing.Biller]
  B -->|"ssh + scheduled task"| VM["WS3 guest VM<br/>native_quick_fill (default)<br/>or manual_quick_fill.py (ui)"]
  C -->|liberty_conn.Session| SQL
  E -->|pymssql direct| SQL
  B -->|"quick_fill_billing (SQL reads)"| C
  Pi2["Interactive Pi<br/>.pi/extensions/fast.ts"] -->|"POST /v1/run"| S[pharmacy_fast_server.Handler]
  S --> C
  S --> G
  VM --> SQL

Pages

Start here

• Where does a new prescription start? In the Drasi CDC line, which reaches launch.py main, then run_worker and launch.sh. See lifecycle.md.
• Where are the worker's rules enforced? In fast/case_gateway.py, in code, not prompt text. See case-gateway.md.
• Where is a Fast action implemented? Start at PharmacyFast.run, which routes to pharmacy_fast_*.py modules. See fast.md.
• What happens after a worker commits ADD? add_billing.Biller. See billing.md.
• How do I answer a pharmacy-data question? Read fast/READING.md and docs/domain/. This codemap is about code, not data.

Legend used on every page

Links are relative to docs/codemap/. #L<n> anchors point at the line where the symbol is defined on main at the SHA above. Line numbers will drift as the tree changes.

Architecture and repository layout

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior.

Directory map

rx/
├── launch.py              launcher: tails CDC NDJSON, runs entry, then audit, then decision workers   [current]
├── launch.sh              one worker: open case, run Pi with tools.mjs + tracing, read outcome        [current]
├── tools.mjs              worker tools; each is one POST /v1/case                                     [current]
├── prompt_{entry,audit,decision,decision_replay}.txt   worker prompts read by launch.sh              [current]
├── entry.py               entry tools (propose/assemble/create) built on scanner functions            [current]
├── results.sh             operator read of the production case ledger (latest case per Rx)            [ops]
├── fast/                  Fast service: HTTP server, action core, gateway, writes, billing; `fast` CLI [current]
├── scanner/               deterministic entry/GEQ/NDC/SIG library (polling loop removed Oct 11)       [current]
├── tracing/               LangSmith Pi extension wrapper + dispatch/billing boundary exporters        [current]
├── .pi/extensions/fast.ts interactive coding-session Fast tools (/v1/run)                             [current, optional]
├── .agents/skills/       ws3mon (WS3 guest monitor) and swiftui-expert-skill; linked from .claude/ and .pi/ [interactive tooling]
├── pi/imessage/           Pi extension: text Carter, receive reply                                    [interactive tooling]
├── cloud/                 GCE units (Fast, launcher, Drasi, delivery relay), helpers, BigQuery, secret catalog [config + ops]
├── launchd/               Mac LaunchAgent plists (Fast, SQL tunnel, watchers, pollers, legacy)        [local config]
├── ops/                   operator CLIs, WS3 guest runners/tools, watchers and pollers, maintenance   [mixed]
├── ios/                   RxVerify / RxDeliver / notify extension (SwiftUI) + relays in ios/Server    [current client]
├── research/              renewal response note and purchasing notes (McKesson)                       [notes]
├── tests/                 unittest + node:test suites                                                 [current]
└── docs/                  runbooks, operations log, domain wiki, handoffs, research

Not in this repo, but referenced by code or config:

Service boundaries

flowchart TB
  subgraph Host["Runtime host (cloud VM or Mac)"]
    direction TB
    L[launch.py<br/>state/launch.sqlite3]
    subgraph Fast["Fast process :8792 (pharmacy_fast_server)"]
      H[Handler<br/>/v1/run /v1/case /health/*]
      G[case_gateway.Cases<br/>state/cases.sqlite3]
      C[PharmacyFast core]
      B[add_billing thread<br/>cases.sqlite3: billing]
    end
    W[Pi worker processes]
  end
  SQL[(Liberty SQL)]
  VM[WS3 guest VM]
  LS[LangSmith]
  L -- HTTP loopback --> H
  W -- HTTP loopback /v1/case --> H
  H --> G --> C --> SQL
  G -- entry.py pymssql --> SQL
  B -- ssh/PowerShell scheduled task --> VM --> SQL
  W -- tracing/index.mjs --> LS
  L -- tracing/dispatch.mjs --> LS
  B -- tracing/billing.mjs --> LS

Inference: the entry write path does not go through pharmacy_fast_write_gate. /v1/case only reaches it from inside the HTTP handler, but require_http_write checks liberty_conn.Session instances, and entry connections are raw pymssql. The guarantees for entry writes come from the gateway's token and writes-row discipline plus entry.create's own checks. The ADD biller's plan move (inactive_plan) does use guarded_write.

Durable state (paths only; contents not read for this map)

Mac versus cloud (local config only)

Runtime files not in the repo (documented only): the rx-launch.service.d/30-openai-platform.conf provider override (cloud/RUNTIME.md), rxcaddy-sql-forward.service.d/20-ws3.conf and the rxcaddy-sql-forward unit (AGENTS.md). The Sep 29 Quick Fill drop-in was removed Sep 30 (fast/QUICK_FILL.md). Production is a hand-deployed tree, not a git checkout; what it runs is listed in docs/OPERATIONS.md § What's live.

Central symbols (top 15)

Launcher dispatch and the entry → audit → decision lifecycle

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior. Related: case-gateway.md · scanner.md · tracing.md · detail local-wiki launcher, worker-lifecycle

Start here

Event → worker mapping (Source: launch.py docstring)

End-to-end sequence (decision path)

sequenceDiagram
  participant D as Drasi NDJSON
  participant L as launch.py
  participant F as Fast /v1/case
  participant S as launch.sh
  participant P as Pi worker
  D->>L: update 0 to N (eScript E)
  L->>L: INSERT launches audit:N, decision:N
  L->>F: owner(script=N)  (up to 3 tries, 30s apart)
  F-->>L: {ours, patient_id}
  alt not ours / unknown
    L->>L: finish_unlaunched STAFF_ENTERED / OWNER_UNKNOWN
  else ours
    L->>L: acquire PATIENT_LOCKS[patient_id]
    L->>S: launch.sh audit N audit:N E
    S->>F: open(kind=audit)
    S->>P: pi -p ... -e tools.mjs -e tracing/index.mjs
    P->>F: call(...) * n, finish
    S->>F: outcome, close
    S-->>L: last stdout line = outcome JSON
    alt audit OK/REPAIRED
      L->>L: gate still_ours(): relinked? owner?
      L->>S: launch.sh decision N decision:N E
    else
      L->>L: decision:N = NOT_RUN_AUDIT_<x>
    end
  end

Retry and gating policy

• worker_retry waits up to READY_WAITS × 300 s for /health/ready before asking Fast.
• Retried decisions run with RX_DECISION_REPLAY=1, which prepends prompt_decision_replay.txt (launch.sh L25-29).
• Timeout: RX_WORKER_TIMEOUT (600 s). stop_worker sends SIGTERM to the process group, then SIGKILL after TERM_GRACE (15 s), so Pi can end its trace. close_orphan_case closes the killed worker's Fast case using the id launch.sh wrote to RX_CASE_FILE.
• note_outcome logs an ALERT line after 3 consecutive workers with no outcome.
• Concurrency: RX_WORKERS semaphore (default 4); one patient at a time via PATIENT_LOCKS.
• Entry gate: entry_gate skips with TAKEN_BEFORE_LAUNCH if the event stream already shows the eScript entered.
• Worker tool calls time out after RX_TOOL_TIMEOUT_MS (150 s) and return GATEWAY_TIMEOUT/GATEWAY_UNREACHABLE (tools.mjs L10-30).

Replay and requeue flows

A started-but-unfinished row is never relaunched (requeue_rows docstring).

Dispatch ledger and observability

• Every launch, skip or defer writes a row to dispatch via dispatch_record. It never raises.
• DISPATCH_RULES / DISPATCH_REASONS / SKIP_REASONS (L59-63) are versioned rule ids.
• dispatch_env passes allowlisted RX_DISPATCH_*, RX_TRIGGER_SOURCE, RX_ENVIRONMENT, RX_GIT_SHA, RX_GIT_DIRTY to the worker for trace metadata (build_info).
• DispatchExporter: a bounded, lossy daemon queue that pipes JSON to node tracing/dispatch.mjs. It is only created in executable(), not on import (keeps tests side-effect free).

Pi harness (launch.sh)

open case (curl POST /v1/case op=open) -> CASE_ID; written to RX_CASE_FILE if set
RX_FAST, RX_CASE_ID, RX_KIND exported
${RX_HARNESS:-pi} -p -nbt -ne -ns -np -nc --session-dir cases/
   --provider ${RX_PROVIDER:-openrouter} --model ${RX_MODEL:-openai/gpt-5.6-luna:high}
   --system-prompt "<kind sentence>" -e tools.mjs -e tracing/index.mjs "<prompt> Rx number: N"
stdout -> cases/<CASE_ID>.stdout
POST outcome (printed; launch.py parses the last line), POST close

• -ne turns off extension auto-discovery, so .pi/extensions/fast.ts is not loaded into workers. fast.ts also returns early when RX_CASE_ID is set (fast.ts L99).
• The comment on line 3 says "kind: decision | audit"; entry is handled too (L20).
• Provider: the base unit sets OpenRouter. cloud/RUNTIME.md documents a production drop-in for the OpenAI Platform. Needs runtime check. tests/test_launch_provider.py pins the in-repo values.

Prompts versus code

Current versus legacy intake

Change impact

• Dispatch conditions belong in decision_events / audit_then_decide. Bump the DISPATCH_RULES version if semantics change, since traces compare on it.
• launches/dispatch schema changes must stay additive (see db() L254-259). Production ledgers predate the newer columns.
• Changing launch.sh arguments affects tests/test_launch_provider.py and the documented runtime override.
• Tests: test_launch_backlog.py, test_launch_dispatch.py, test_launch_pipeline.py, test_decision_retry.py, test_duplicate_entry.py, test_launch_provider.py, worker_tools.test.mjs.

Fast: HTTP surfaces, named actions, writes, who made the change

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior. Related: case-gateway.md · billing.md · usage guide fast/READING.md · detail local-wiki fast-http-api

Start here

1. fast/pharmacy_fast_server.py: HTTP routing, auth, field allowlists, boot.
2. fast/pharmacy_fast_core.py PharmacyFast.run: dispatch to action modules.
3. The action module you care about (table below).
4. fast/liberty_conn.py for SQL routes and lanes; fast/pharmacy_fast_write_gate.py for write authority.

Modules import each other as top-level names (import pharmacy_fast_core), so fast/ must be on sys.path. The service runs from fast/; tests and entry.py insert it. fast/fast is a shell CLI for Mac Fast (fast rx_claims script=N): one /v1/run call, compact JSON.

Which actions production runs is a deploy fact, not a code fact: several (fill_report, rx_claims) are recorded as Mac-only in docs/OPERATIONS.md and docs/MAC_FAST.md. Needs runtime check.

HTTP surface (Handler)

Auth layers (Source)

Boot sequence (main)

startup_snapshot() (stub) -> build_servers -> Cases(core.run) attached to server[0]
  -> TestGate(...).start() (no-op stub)
  -> with http_write_context(gate): add_billing.service(core.get_default()).start()   # always started
  -> serve_forever; SIGTERM/SIGINT stop the biller and servers

__main__ disables bytecode caching so the process always imports current source (L23-27).

Action dispatcher (PharmacyFast.run)

flowchart LR
  R["core.run(**kw)"] --> P[PharmacyFast.run]
  P -->|check_fillable + script| QD[pharmacy_fast_queue_decision.check_exact_fillable]
  P -->|fill_report| FR[pharmacy_fast_fill_report.fill_report]
  P -->|rx_claims| RC[pharmacy_fast_rx_claims.rx_claims]
  P -->|billing_status| AB[add_billing.status]
  P -->|renewal_status| RN[pharmacy_fast_renewal.renewal_status]
  P -->|adherence_candidates| AD[pharmacy_fast_adherence.adherence_candidates]
  P -->|catalog_search, geq_candidates, read_query| REF[pharmacy_fast_reference.run_reference]
  P -->|escript_source/entry, onhold_entry, prescription_snapshot| SELF[PharmacyFast methods]
  P -->|queue_place| Q[pharmacy_fast_queue.queue_place]
  P -->|repair_entry| ER[pharmacy_fast_entry_repair.repair_entry]
  P -->|pharmacist_edit| PE[pharmacy_fast_pharmacist_edit.pharmacist_edit]
  P -->|mark_delivered| DL[pharmacy_fast_delivery.mark_delivered]
  P -->|health, state, last_claim, first_paid_claim, patient_*, check_fillable by patient, queue_if_fillable| CORE[inline in core]

PharmacyFast.run accepts a script sent as digits-only text (L1919-1921). core.run (L2139) turns exceptions into {ok:false,status,...}: SQL error 916 → ACCESS_DENIED; a SQL Server error on read_query → SQL_ERROR with the server's message; an exact-Rx check_fillable error gets a short envelope with no exploration_fallback.

Named actions: file ownership

Common write pattern (Source, repeated in queue, entry_repair, pharmacist_edit, delivery): exact target → locked _snapshot → dry_run=True preview returns expected → commit compares expected against a fresh locked snapshot → one write → CH change-log row (provenance.log_change) → readback.

Write authority (pharmacy_fast_write_gate.py)

• http_write_context(gate) sets a ContextVar. Every /v1/run and /v1/case call is wrapped in it.
• require_http_write(manager) raises HTTP_REQUIRED when a real liberty_conn.Session writes outside that context. Fake managers in tests pass.
• guarded_write = gate + manager.write().
• The biller thread copies the context at start (Biller.start), so its queue writes and plan moves keep HTTP authority.
• Module docstring: "not a credential security boundary". It stops offline or script use, not a malicious local caller.

Tracking our changes (provenance.py)

Owner test (a different signal): DataEnteredBy == "RxCaddy" means "still our entry". It is used by decision_retry.OWNER, case_gateway.OWNER and the queue guard. Entry stamps come from the scanner contract (scan_and_create_v3 docstring).

SQL session (liberty_conn.py)

• Session: PHARMACY_FAST_ROUTE is one of ws11 (legacy default, L161), direct, public, forward. The service units use forward with LIBERTY_FORWARD_PORT.
• Lanes: read(), write(), readback() (L278-287); breaker BREAKER_MAX_S=30, LANE_WAIT_S=75 (hang guards, L57-65).
• RX_READ_PROFILE=write upgrades the read profile to write credentials (L174).
• Identity pinned: EXPECTED_SERVER="S013529", EXPECTED_DATABASE (L31). The gateway re-checks identity on every read (Case._bind).
• SshForward / connect_via_ws11 are legacy routes.

Adapters versus core logic

Change impact

• Adding a field to an action means updating three allowlists: EXACT_ACTION_FIELDS (server), the allowed set in PharmacyFast.run, and the caller schema (.pi/extensions/fast.ts and/or tools.mjs/case_gateway.TOOLS).
• /v1/actions is a hand-maintained list. A new action is not discoverable until it is added there.
• check_exact_fillable's output shape is consumed by Case._bind, _no_write, _fillable_now, decision_retry.classify, Cases.owner and the decision prompt. Treat it as a contract.
• active_paid_claims feeds fill_report claims, decision evidence and adherence net_paid. A change there moves several reports.

Tests: tests.md § Fast.

Case gateway (/v1/case)

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior. Related: lifecycle.md · fast.md · billing.md · detail local-wiki case-gateway

File: fast/case_gateway.py (1,208 lines). The module docstring (L1-21) is the rule summary: rules that matter are code here, not prose.

Shape

classDiagram
  class Cases {
    +open(script, event_key, kind, escript)
    +call(case_id, tool, args)
    +outcome(case_id)
    +decision_retry(case_id)   launcher only
    +worker_retry(case_id, kind, escript)   launcher only
    +source_classification(escript)   launcher only
    +owner(script)   launcher only
    +close(case_id)
    -live: dict
    -bill: add_billing.service().submit
  }
  class Case {
    kind: decision|audit|entry
    script, escript, patient
    fresh, evidence, last_check, plan, receipt
    failures[], read_refusals[], no_write, duplicate
    +call(tool,args)
    -_call / _call_audit / _call_entry
    -_queue_place / _repair / create
    -_dispense_guard / _product_check
    -_finish / _finish_audit / _finish_entry
    -_ledger
  }
  class Store {
    cases(id, script, event_key, kind, opened, finished, decision, basis, outcome)
    calls(case_id, seq, ts, tool, args, ok, status)
    writes(case_id PK, digest, ts, result)
  }
  Cases --> Case
  Cases --> Store
  Case --> Store

• One Cases per Fast process, built in build_servers with core.run as fast_run.
• Case objects live only in memory (Cases.live). After a Fast restart, call on an old case returns NO_CASE; outcome, decision_retry and worker_retry still work from SQLite.
• Handler._case accepts ops open|call|outcome|close|decision_retry|worker_retry|owner|source_classification from loopback IPs only, inside http_write_context.

Tool allowlists (TOOLS)

The decision worker has no billing tools: quick_fill and quick_fill_status were removed Oct 8 (c33e11c). The model never supplies a script. Every call is bound to Case.script. _bind checks server/database identity, script and patient on each read.

Decision kind: call path

sequenceDiagram
  participant W as Worker (tools.mjs)
  participant G as Case (decision)
  participant F as core.run
  participant B as add_billing
  W->>G: check_fillable
  G->>F: check_fillable(script)
  F-->>G: evidence, _bind sets patient, fresh=True
  W->>G: queue_place(mode, due)
  G->>G: _no_write() via decision_retry.classify + DataEnteredBy
  G->>F: queue_place(dry_run=True)
  F-->>G: PLANNED + expected  (or ALREADY_QUEUED)
  G-->>W: plan token
  W->>G: queue_place(plan=token)
  G->>G: eScript relink re-check (DUPLICATE), INSERT writes(case_id) (one per case)
  alt ADD and billing enabled
    G->>F: queue_place(dry_run=True) recheck
    G->>B: bill(case_id, script, patient) to job id
  else
    G->>F: queue_place(dry_run=False, expected)
  end
  W->>G: finish(decision, basis)
  G->>G: _finish rules, _ledger to state/onhold_decisions.jsonl

Key methods: _call, _no_write, _queue_place, _commit_billed_add, _decision_escript, _finish, _ledger, _fillable_now.

Audit kind

_call_audit → exact_lookup (also runs _duplicate_check) → complete_snapshot (worker copy drops NCPDP pricing/reject blobs, WORKER_OMIT) → optional catalog_search/geq_candidates (GEQ results kept as product evidence) and patient_fills (_patient_fills, read-only, the bound patient, drug defaults to the entered DrugId) → _repair (preview repair_entry dry_run → token → commit). Before the preview, _dispense_guard refuses repairs that break store rules: whole bottles for reconstituted suspensions, whole packages for sprays/inhalers/pens/tubes, house SIG shorthand codes, a SIG that names the wrong tablet/capsule form, or removing a course label. When the entry rule leaves a packaged 1–3 to the agent (two readings), the guard allows whole packages from one up to the packages reading. _finish_audit records _product_check as SAME_NDC|VERIFIED|INFERRED; it never refuses a finish on product grounds (Oct 8, 54fc15a). Refused read-only explorations go to read_refusals and do not bar OK; failed writes still do.

Entry kind

_call_entry: propose → (plan with picks/facts + basis | add_prescriber) → create → _finish_entry. create refuses a token that isn't the latest plan's before the write claim, so a retry is possible; since 71e51a7 the message says to call create again with that exact token. patient_fills needs propose's resolved patient; its drug defaults to the proposal's product (L820-827). propose's stopped value (source|daw|patient|renewal|prescriber|drug|facts|timing) decides which next hint the worker gets. After a CREATED, Case.script becomes the new Rx number and the cases row is updated.

Outcome sets

Invariants (Source)

1. One durable write attempt per case. A writes row keyed on case_id is inserted before the write; IntegrityError → "no replay" (L375-380, L895-899). add_prescriber uses its own key <case>:prescriber.
2. Commit takes only the plan token (queue_place may restate the same mode/due/dry_run=false; anything else is refused) (L351-367).
3. Fresh read before a plan. fresh is cleared after each write attempt.
4. No write on someone else's Rx. _no_write returns ALREADY_PROCESSED (via decision_retry.classify) or NOT_OURS (DataEnteredBy != "RxCaddy") without calling Fast, and keeps that answer for the rest of the case.
5. ADD/PARK need a committed queue_place of that mode. HOLD is refused after a commit or after a non-retry-safe failure.
6. INCOMPLETE is refused when the latest check_fillable says fillable now and queue_place was never tried, unless the case found nothing to place (L996-1001).
7. Duplicates. If staff also entered the eScript, audit/entry must finish DUPLICATE, and a decision commit answers DUPLICATE and finishes HOLD (L368-374).
8. The ledger line is appended only for ADD/PARK/HOLD, under flock + fsync; Fast's queue replay guard reads it.

Launcher-only ops

Change impact

• Any new tool needs: a TOOLS entry, a branch in _call*, a tools.mjs registration, privacy.mjs TOOL_NAMES (or traces name it "Rx tool"; patient_fills isn't listed yet, tracing.md), and tests in test_decision_gateway_state.py / test_audit_*.py / test_add_billing.py.
• Changing finish legality changes what launch.py sees (decision drives retry and the audit → decision chain).
• Case state is in memory: changes that assume persistence across a Fast restart need a store change.
• _dispense_guard reuses scanner/dispense_rules.py and sig_english; rule changes there also change audit repairs.

Scanner shared logic and entry tools

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior. Related: lifecycle.md · case-gateway.md § Entry kind · detail local-wiki scanner-and-entry

scanner/ is two things:

1. A deterministic library (current) used by entry.py, and therefore by the entry worker through /v1/case, by the audit repair guard, and partly by Fast's GEQ actions.
2. Formerly the legacy polling scanner (scan_once loop through scanner/run.py, LaunchAgent com.rx.scanner). It was removed Oct 11, 2026; agents do intake. scan_and_create_v3.py keeps everything entry.py and escript_tools.py use.

Dependency map (Source: imports)

flowchart TD
  GW[fast/case_gateway.py _call_entry] --> E[entry.py]
  AG[case_gateway._dispense_guard / _product_check] --> E
  AG --> DR
  AG --> SEN
  AG --> G
  E --> S[scan_and_create_v3]
  E --> GC[geq_core]
  E --> EL[escript_lab]
  E --> FT[fill_timing]
  E --> DR[dispense_rules]
  S --> GC
  S --> NG[ndc_gate]
  S --> SE[sig_engine]
  S --> SEN[sig_english]
  S --> SD[sig_determ]
  S --> FT
  NG --> G[geq]
  SEN -.-> SE
  REF[fast/pharmacy_fast_reference.py] -->|_geq_module| G
  S --> LC[fast/liberty_conn.QMarkCursor]
  G & GC & NG & SE --> P[fast/paths.py]
  ET[escript_tools.py one-off CLI] --> S & EL

The scanner imports paths and liberty_conn from fast/. entry.py puts both scanner/ and fast/ on sys.path (L16).

Module responsibilities

Entry tools (entry.py, 1,204 lines)

Entry call path

tools.mjs propose -> /v1/case call -> Case._call_entry("propose")
  -> entry.propose(conn, escript) -> load -> classify_source -> patient -> prescriber -> drug -> dispense -> fill_timing
  -> (ready) entry.assemble(_base, facts, {}) -> gateway plan token
tools.mjs create(plan) -> writes-row claim -> entry.create(conn, candidate) -> scanner create_script -> readback
  -> Case._duplicate_check (staff also entered?) -> finish CREATED|DUPLICATE

Invariants and configuration

• RXQ_SIG_DETERM=0 is defaulted by entry (L17). The PolicySet shadow it also turned off was removed Oct 11, 2026.
• Stamps (scanner contract): LoggedInUser='CH', RphInitials='CH', DataEnteredBy='RxCaddy' (docstring). The launcher's owner check depends on DataEnteredBy.
• "Unknown SIG never blocks" was the removed loop's routing rule. On the entry path, the agent supplies or overrides facts with a basis.
• Rule sources referenced by docstrings (docs/domain/dispensing.md, docs/tasks/2026-09-24-qty-ds-entry-fix/HANDOFF.md) were not read for this map.

Change impact

• dispense_rules changes show up in entry.propose facts, in the audit's _dispense_guard, and in the test_entry_qty_ds, test_dispense_rules, test_entry_drug_pick, test_audit_dispense_guard fixtures (tests/fixtures/drug_catalog.json, package_facts.json).
• classify_source value sets are mirrored in tracing/privacy.mjs (MESSAGE_TYPES, RENEWAL_RESPONSES). Change both.
• scan_and_create_v3.create_script is shared by entry and escript_tools. Changes there affect entry writes.
• geq.py is also behind Fast geq_candidates (via pharmacy_fast_reference) and the audit product check.
• sig_english.mutating_tokens is used by both entry's SIG pick and the audit SIG guard.

ADD billing, Quick Fill runners and claim reconciliation

← README · Checked against main through cd58150 (Oct 11, 2026); not verified production behavior. Related: case-gateway.md · fast.md · runbooks fast/QUICK_FILL.md, ops/QF.md, ops/windows/native_quick_fill/BATCH.md, practice docs/domain/billing.md · detail local-wiki quick-fill-and-billing

Billing sends real payer claims. Everything below describes code paths. Whether billing is enabled anywhere is a runtime check (cloud base unit sets RX_QUICK_FILL_ENABLED=1; Mac plist sets 0; QUICK_FILL.md records an Oct 7 cloud readback of 1 with the native runner).

Billing routes at a glance

The decision worker has no billing tool. The old preflight Quick Fill runtime (fast/pharmacy_fast_quick_fill.py, ops/quick_fill_preflight.py, quick_fill_rejection.py, Start-QuickFill.ps1) is gone from main; state/quick_fill.sqlite3 is history.

ADD billing flow

sequenceDiagram
  participant G as Case._queue_place (commit ADD)
  participant B as add_billing.Biller (thread "add-billing")
  participant QB as quick_fill_billing
  participant T as Native (default) or Windows transport
  participant VM as WS3 guest runner
  participant Q as pharmacy_fast_queue.queue_place
  G->>G: queue_place dry_run recheck (same expected)
  G->>B: submit(case_id, script, patient) to Store.create (one row per script)
  G-->>G: COMMITTED, billing_job (no queue_row_id)
  B->>QB: capture(fast, script) baseline
  B->>QB: original_hold(baseline)  (staff paid it? -> NOT_BILLED staff_billed, no queue row)
  B->>B: OTC / blank Agency to NOT_BILLED
  B->>T: prepare(baseline) manifest item; probe() host, source SHA-256s, DLLs, both tasks idle
  B->>B: inactive_plan: move to the only active plan (CH change-log) or NOT_BILLED inactive_plan
  B->>B: state=LAUNCH_INTENT saved BEFORE launch
  B->>T: launch(job_id, script, item) (never twice per job id)
  loop up to RUNNER_DEADLINE (840 s)
    B->>T: status(job_id)
  end
  B->>QB: check_result to reconcile (two stable reads)
  alt PAID
    B->>B: PAID, no queue row
  else staff billed and runner sent nothing
    B->>B: NOT_BILLED staff_billed, no queue row
  else REJECTED / NOT_BILLED / UNCLEAR
    B->>Q: queue_place(ADD, comment, decision_id) preview+commit
  end
  B->>B: tracing/billing.mjs export (metadata only)

Transports

• Both target RXCADDY-WS3VM over SSH alias pharmacy-ws3vm with host key pinned (quick_fill_transport L19-22). Mac scripts use alias rxcaddy-ws3vm (ops/manual_quick_fill.sh L13).
• Native (Native): task RxCaddy-NativeQF, 10-minute limit. FILES pins native-billing-batch.js, NativeBillingRun.cs, ClinicalConnection.cs, hidden-launch.py by hash (L25-26); probe also needs both DLLs, node.exe, pythonw.exe and rxqhost.js, and refuses while either billing task or a batch node runs. launch writes a one-item manifest with skipTooSoon and starts pythonw hidden-launch.py (windowless). summarize turns result.json into runner states.
• UI (Windows): task RxCaddy-ManualQF, 13-minute limit. FILES pins manual_quick_fill.py, quick_fill.py, Navigate-PharmacyOne.py (L26-27); probe checks only RxCaddy-ManualQF. The task name is shared with the manual scripts, which do not check RxCaddy-NativeQF.

Guest runners (ops/windows/)

PharmacyOne must be open and signed in as CH on the guest; see ops-runtime.md § WS3 guest tools.

Claim reconciliation boundaries

Invariants: one billing job per Rx (script is the primary key). LAUNCH_INTENT is saved before the only runner launch. No automatic resubmission. Ambiguity becomes UNCLEAR/NEEDS_RECONCILIATION and a queue row with attention. Blank Agency is never billed as cash. A staff claim during our attempt ends NOT_BILLED "staff billed it" with no queue row. Controlled substances are not excluded from ADD billing (QUICK_FILL.md; no schedule check in bill). The Carter-directed native batch is limited to noncontrolled items (BATCH.md).

Not built (per docs)

• The rejection-fix agent that would use the claim evidence kept on jobs (QUICK_FILL.md L101-102).
• Staff notification of billing attention.
• Future-due (PARK) execution.

Change impact

• Changing any pinned guest file means redeploying it to the guest (and rebuilding both DLLs after a .cs change), or probe refuses every job (QUICK_FILL.md § Deploy).
• reconcile changes affect ADD billing outcomes and tests/test_quick_fill_reconcile.py, tests/test_add_billing.py.
• New reason values must be added to tracing/privacy.mjs BILLING_REASONS, or the billing trace reports them as unrecognized errors (not_billable, inactive_plan, plan_check_failed are missing today; coverage.md).
• Queue comment format is capped at 240 chars (_outcome, reject_comment) because of rxqWorkFlowItem.Comments.

Client, UI and iOS code

← README · Checked against main through 419f1d9 (Oct 11, 2026); not verified production behavior. Related: fast.md · ops-runtime.md · detail: docs/local-wiki/clients-ui-ios.md

Client map

flowchart LR
  subgraph Devices
    RV[RxVerify iPad/iPhone<br/>ios/RxVerify]
    RD[RxDeliver driver app<br/>ios/RxDeliver]
    RN[RxVerifyNotify<br/>notification extension]
    DK["RxDesk Mac apps<br/>(outside this repo)"]
  end
  RV & DK -->|"HTTPS, Tailscale Serve :8453 (Mac)"| RL[ios/Server/rxverify_relay.py<br/>loopback :8391]
  RD -->|"build 3: Serve :8453 on the VM"| DR[ios/Server/rxdeliver_relay.py<br/>rx-delivery.service, loopback :8392]
  RD -.->|"older build: route exists, no driver traffic ever logged"| RL
  RL -->|":5177"| TUD["drugs_agent ui/tool_use_dash.py (external)"]
  RL -->|":8390"| DD["drugs_agent ui/day_dash.py (external)"]
  RL -->|"views: agent, traces, medlist, auditlabels, adherence, rxsearch, work, watch, claims, deliveries"| V[ios/Server/*_view.py, audit_labels.py, deliveries.py]
  V -->|"read_query / mark_delivered"| F[Mac Fast :8792 /v1/run]
  V -->|"IAP ssh stdin"| VM[cloud/*.py on VM]
  V -->|"pi -p, no tools"| M[model call, traced]
  DR -->|"read_query (mark_delivered when enabled)"| CF[cloud Fast :8792]
  RL -->|"POST /v1/agent/edit"| VA[ops/verify_agent/jobs.py]
  VA -->|"agent uses pharmacist_edit"| F
  RL -->|"/v1/ops/*"| OP[ops/ops_panel/answers.py]
  RL -->|"/v1/canvas"| DP["state/delta_postmortem/canvas.json<br/>(ops/delta_postmortem)"]

The iPad app calls only /v1/queue, /v1/rx/…, /v1/verify, /v1/day, /v1/ops/*, /v1/agent/edit|updates and /v1/canvas (strings in ios/RxVerify/*.swift), plus an unlinked caller of /v1/canvas/board (Canvas.swift:279) that the relay does not serve. The other relay routes serve RxDesk tabs (Med list, Traces, Work, search), per the view docstrings; RxDesk also calls /v1/day, /v1/rx/…, POST /v1/verify and POST /v1/ops/staff/refresh. /v1/medlist/patient/<id> has no client. RxDesk's code is not in this repo (~/rxdesk).

The Mac relay's /v1/deliveries* path is unused: its log shows no driver device, only calls from the Mac itself, and no delivered report was ever posted.

iOS (ios/)

Neither project has a unit-test target. The working tree has uncommitted RxVerify app changes (RxVerifyApp.swift, Info.plist, project file); this page describes main.

RxVerify files

Write paths from the iPad (Source: relay docstring): POST /v1/verify (to day_dash's guarded verify write, external) and POST /v1/agent/edit (starts a verify agent that may call Fast pharmacist_edit). Both need intent headers.

RxDeliver files

DeliveryService (GET /v1/deliveries, POST /v1/deliveries/delivered; base URL from the RXDELIVER_RELAY_URL build setting via Info.plist RxDeliverRelayURL, set to the VM's Serve address), DeliveryStore, ArrivalMonitor (geofence arrive/depart → Report), StopListView, StopActions (Maps/phone), SampleStops. Server side: ios/Server/deliveries.py → Fast mark_delivered (pharmacy_fast_delivery). Driver access: driver_access.py, DRIVER.md.

Other iOS material: ios/README.md, ios/HANDOFF.md, screenshots. ios/.v1-backup/ and ios/DerivedData/ are untracked (excluded).

Mac relay (ios/Server/)

Inference: the relay views call Fast without credentials, which works because they use 127.0.0.1 (_authorized accepts loopback hosts).

Cloud delivery relay

ios/Server/rxdeliver_relay.py is a standalone delivery-only gateway (committed Oct 9 in 471b333): GET /v1/deliveries, POST /v1/deliveries/delivered and local /health/live only (Handler.do_GET, do_POST). Loopback :8392; identity from Serve headers checked against an exact RXDELIVER_ALLOWED_CLIENTS {IP: login} map (empty denies all); needs the existing 32-byte stop_id.key; writes off unless RXDELIVER_WRITES_ENABLED=1 (otherwise 503 delivery_writes_disabled). It reuses deliveries.py and calls Fast /v1/run (fast_request). Unit cloud/runtime/rx-delivery.service; runbook cloud/DELIVERY.md. Cloud Fast has no mark_delivered. The Sep 28 candidate builder cloud/delivery-fast/ was removed Oct 11, 2026 (its pinned hashes were stale); cloud/DELIVERY.md keeps its lesson. Deployment state is in the local wiki (clients-ui-ios.md), not verified here.

Web UIs

None in this repo. The Fast UI page (8792 /), ui.py (8765), dashboard/ (8798) and the CopilotKit pilot (pilots/copilotkit/, 3210) were removed Oct 11, 2026. The Rx decision viewer (8799) and Rx workbench (8800) under ops/rx_review, ops/rx_workbench were removed Oct 7 (0459934).

Interactive Pi extensions and CLI

Change impact

• A new relay route needs: relay dispatch branch, allowlist/intent review, a view module, a client (LiveService method plus decoder for the iPad, or RxDesk outside this repo), and a test in tests/test_*_view.py / ios/Server/test_*.py. Add the route to the relay docstring.
• Relay shapes reuse /v1/day's row shape (work_view, rxsearch_view). Keep it stable for the app's decoders.
• A relay model call must set RX_KIND to a STAGES key in tracing/privacy.mjs and a random 12-hex RX_CASE_ID (tracing.md).
• Anything that writes (/v1/verify, /v1/agent/edit, /v1/deliveries/delivered) crosses a Liberty write boundary. Review against AGENTS.md authorization rules.
• For SwiftUI work, use .agents/skills/swiftui-expert-skill (on main since 3aaeb55; Claude Code and Pi discover it through the .claude/skills/ and .pi/skills/ links, so AGENTS.md no longer points to it).

Tracing and observability

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior. Related: lifecycle.md § Dispatch ledger · runbook tracing/README.md · detail: docs/local-wiki/tracing.md

Three export boundaries plus relay model calls, one config and one privacy projection

flowchart LR
  subgraph Worker["Pi worker (launch.sh)"]
    TI[tracing/index.mjs<br/>wraps @langchain/langsmith-pi-extension 0.2.0]
  end
  subgraph Relay["Mac relay model calls (ios/Server)"]
    RM["medlist_view / audit_labels<br/>pi -p -e tracing/index.mjs"]
  end
  subgraph Launcher["launch.py"]
    DE[DispatchExporter queue] -->|"stdin JSON"| TD[tracing/dispatch.mjs]
  end
  subgraph FastProc["Fast add_billing"]
    EX[export_trace thread] -->|"stdin JSON"| TB[tracing/billing.mjs]
  end
  CFG[(~/.config/rx/langsmith.json<br/>mode 0600, owner only)]
  RM --> TI
  TI & TD & TB --> PRIV[tracing/privacy.mjs<br/>metadataOnlyClient + sanitizeRun]
  TI & TD & TB -.reads.-> CFG
  PRIV --> LS[(LangSmith)]

ioEnabled turns I/O off for the dispatch and billing boundaries whatever the config says.

Key files

TOOL_NAMES and OUTCOMES still list quick_fill, quick_fill_status and QUICK_FILL, which the worker no longer has (removed Oct 8). Harmless: the allowlists are a superset. The reverse gap: patient_fills (audit and entry tool since 1b33823, Oct 11) is not in TOOL_NAMES, so its tool runs are named "Rx tool" (L419); inputs and outputs follow the export boundary as before.

Invariants (Source)

• Identifiers: the worker trace keys on the random case token (RX_CASE_ID), never the Rx number or event key (tracing/README.md). Billing and dispatch payloads exclude Rx, patient and job ids (billing.mjs header). The relay sets a fresh secrets.token_hex(6) per call.
• Observability is lossy and never blocks: the bounded DispatchExporter queue (128) drops when full (launch.py L82-87); imports start no threads (L67-70). export_trace runs node tracing/billing.mjs with a 15 s timeout and only prints add_billing tracing unavailable on failure.
• tools.mjs keeps source_classification out of the model-visible tool text and puts it in details for tracing (tools.mjs L31-37).
• Python callers check the config's mode/size/enabled before spawning node, so a disabled config causes no extra Liberty reads (e.g. source_classification).
• An unknown billing reason is reported as unrecognized and classed as an error. not_billable, inactive_plan and plan_check_failed from add_billing are not in BILLING_REASONS today (coverage.md).

Observability readers (read-only)

Fast's own logs: Handler.log_message is a no-op (L87). The service-log lines are add_billing's stderr prints (ATTENTION, STATUS_FAILING, tracing unavailable) and adherence's logging calls.

Adding tracing: checklist

1. Decide which boundary applies (worker, dispatch, billing, relay, or a new one patterned on billing.mjs).
2. Add every new field, enum, tool, outcome or billing reason to the privacy.mjs allowlists. Unknown values are dropped or reported as unrecognized, never coerced.
3. Keep identifiers out. Reuse the case token.
4. In Python, follow the export_trace pattern: precheck the config, then a subprocess with a timeout. Never raise on the clinical path.
5. Tests: tests/langsmith_tracing.test.mjs (needs tracing/node_modules), tests/test_launch_dispatch.py, tests/test_add_billing.py, tests/fixtures/langsmith-smoke.mjs (never add it to launch.sh).

Ops and runtime code

← README · Checked against main through 419f1d9 (Oct 11, 2026); not verified production behavior. Related: architecture.md § Mac versus cloud · billing.md · tracing.md · detail: docs/local-wiki/runtime-and-ops.md

Unit files, plists and Level YAML exports here are local config. Their presence says nothing about whether they are installed, loaded or enabled. What production runs is in docs/OPERATIONS.md § What's live (one file per deploy under docs/operations/); cloud/RUNTIME.md and AGENTS.md hold dated readbacks. Treat all of them as history and recheck with bash cloud/runtime-status.sh.

Runtime as documented

cloud/: GCE runtime

Runtime files not in the repo (documented only): rx-launch.service.d/30-openai-platform.conf, rxcaddy-sql-forward.service.d/20-ws3.conf, the rxcaddy-sql-forward unit, /etc/rx-delivery.env. The Sep 29 rx-fast.service.d/20-quick-fill-disabled.conf is gone (Oct 7 readback). RUNTIME.md L171-179 describes cloud/openrouter-credits.sh and the com.carter.rx-openrouter-credits LaunchAgent; both were committed in d9e5730 (Oct 11), see the plist table below.

launchd/: Mac LaunchAgents

The Herdr pollers (engine, wiki, domain wiki, tab closer) launch or close Pi sessions in Herdr tabs; caps, cooldowns and protected tabs are in each docs/*.md above.

ops/: grouped by purpose

Billing and PharmacyOne UI (billing.md)

qf, qf.py, QF.md, manual_quick_fill.sh, windows/*quick_fill*.py, windows/Navigate-PharmacyOne.py, windows/native_quick_fill/ (default runner and Carter-directed batch). The screen batch (batch_quick_fill.*, superseded by the native batch) and the Mac fill watcher (cua_queue_watch/, replaced by cloud ADD billing) were removed Oct 11, 2026.

PharmacyOne on the guest

windows/ws3_uia/: open_pharmacyone.py (state / --launch / --login / --auto), guest_login.py (runs on the guest), server.py (UIA over SSH; stdio MCP or CLI), guest.py. Launch and sign-in are desktop writes and are refused while a billing runner is active (docs/domain/pharmacyone-login.md).

Carter-directed Liberty/PharmacyOne writes (outside Fast)

These follow AGENTS.md's rule: production writes need explicit task authorization. None of them is called by the worker pipeline.

Read-only operator tools

Infrastructure maintenance

Mac versus cloud: what code assumes

• Paths: many tools hard-code /Users/carter/... (plists, launch.py EVENTS default) or /srv/rx-runtime/staged/state (cloud/*.py). Readers marked "cloud" run on the VM via IAP SSH stdin, so they never read Mac state/.
• SQL: Fast picks a route by env. entry.py, ops/qf.py and discontinue_dup.py open their own pymssql connections (RXQ_SERVER/RXQ_PORT or RX_SQL_PORT).
• AGENTS.md rule: local state/ is not cloud history. Mac readers of ledgers go through IAP.

Change impact

• Changing unit files has no effect until someone deploys them. Note the documented drop-ins that override the base units.
• A Fast change reaches production only through the deploy procedure above; Mac Fast picks it up only when com.rx.fast restarts.
• Adding a watcher: follow ops/watch/* (read-only, --json, no patient data in output). Wire it into ios/Server/watch_view.py only if the iPad needs it.
• Before any guest-desktop work, use billing-busy.sh. It checks both guest billing tasks (RxCaddy-ManualQF, the UI runner's shared mutex, and RxCaddy-NativeQF, the native runner) plus native batch processes. The WS3 STATUS note of Oct 10 says RxCaddy-ManualQF is no longer registered on the guest.

Tests and development tooling

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior. Tests were not run; counts are from reading the files. Detail: docs/local-wiki/testing-and-development.md

Counts are def test_ plus async def test_ lines (Python) or top-level test( calls (Node) in the main version of each file. Untracked test files are not counted.

Layout

tests/ total: 1,097 Python tests and 40 Node tests.

Commands stated in source docs:

python3 -m unittest discover -s tests -p test_fill_report.py          # fast/READING.md
node --test tests/fast_extension.test.mjs                              # fast/READING.md
node --test tests/langsmith_tracing.test.mjs tests/fast_extension.test.mjs   # tracing/README.md
python3 -m unittest tests.test_add_billing tests.test_manual_quick_fill tests.test_decision_gateway_state   # fast/QUICK_FILL.md
python3 -m unittest tests.test_rxdeliver_relay tests.test_delivery_relay   # cloud/DELIVERY.md
python3 -m unittest tests/test_engine_poller.py                        # docs/ENGINE_POLLER.md (also WIKI_POLLER.md, TAB_CLOSER.md)
node --test ops/windows/native_quick_fill/native-billing-batch.test.js # BATCH.md

Inference: the full suite is python3 -m unittest discover -s tests from the repo root. There is no CI config or pytest.ini. Some tests need python-dotenv, pymssql or sqlglot importable, because entry.py/scanner/reference import them at module load. requirements.txt lists only an OpenAI/httpx/pydantic set, not those. cloud/runtime/constraints.txt pins pymssql. The full runtime dependency list is not declared in one file. Deploy entries in docs/operations/ quote a smaller suite run on the server's staged copy (e.g. "609 OK" on Oct 10); that is a different file set from this repo's tests/.

Coverage by subsystem

Fast

Launcher / harness

test_launch_backlog.py (15), test_launch_dispatch.py (20), test_launch_pipeline.py (25), test_launch_provider.py (3; pins rx-launch.service and launch.sh), langsmith_tracing.test.mjs (31).

Entry / scanner

test_entry_drug_pick.py (32), test_entry_qty_ds.py (34), test_entry_renewal.py (21), test_entry_brand_description.py (8), test_entry_dates.py (4), test_entry_facility_tags.py (3), test_entry_add_prescriber.py (2), test_entry_sig_code_hint.py (1), test_dispense_rules.py (49), test_patient_fills.py (5; entry.patient_fills query bounds and the entry/audit tool), test_fill_timing.py (7). ndc_gate, geq_core and scan_and_create_v3 are imported by entry tests. No test imports sig_engine.py or sig_determ.py.

Billing tools / Windows

test_manual_quick_fill.py (15), test_manual_quick_fill_wait.py (3), test_quick_fill_minimized.py (4), test_billing_busy_scope.py (5), test_billing_stall.py (6), test_watch_claims.py (4), test_codex_langsmith_export.py (2), native batch JS (32, above).

Ops / relay / clients

• Relays: test_delivery_relay.py (29), test_rxdeliver_relay.py (20; cloud delivery relay), test_rxverify_relay_ops.py (18), test_verify_agent_relay.py (12), test_driver_access.py (6), test_delta_canvas_relay.py (3).
• Views and watchers: test_traces_view.py (20), test_watch_view.py (7), test_watch_traces.py (1), test_claims_view.py (4), ios/Server/test_*.py (53).
• Herdr pollers: test_tab_closer.py (21), test_engine_poller.py (17), test_wiki_poller.py (16), test_domain_wiki_poller.py (5).
• Ops tools: test_ops_panel.py (39), test_slow_run_corrections.py (36), test_staff_changes.py (34), test_refill_requests_*.py (4 files, 31), test_delta_postmortem.py (12), test_renewal_sent_ack.py (6), test_results.py (6), test_export_refill_queue.py (5), test_runtime_status.py (5), test_imessage_alerts.py (17; ops/notify_imessage.py send, switches, rate limit, markers, and the ops/verify_agent/jobs.py notify hook; sender stubbed; tracked since 822a995), test_work_cli.py (4), test_refill_overview.py (2).
• No test found for ops/cs_watch/cs_watch.py (including its 822a995 read retry) or ops/windows/ws3_uia/. notify_imessage.fast_rows has no test of its own.

Deleted with the old Quick Fill runtime

test_quick_fill.py, test_quick_fill_rejection.py, test_quick_fill_windows_offline.py, tests/windows/test_quick_fill*.py (deletion committed in 1993987). fast_extension.test.mjs asserts "the old Quick Fill tools are gone" (L94).

Test conventions (Source)

• Fakes, not live systems: QUICK_FILL.md says "Synthetic only: fake guest transport, fake claim rows ... No test is authorization for a live claim."
• The write gate allows duck-typed fake managers (require_http_write), so write modules are testable without HTTP.
• launch.py starts no exporter threads and reads no tracing config on import (L67-70), so tests can import it.
• Seams: Cases(fast_run, store, bill), Biller(fast, store, transport, *, sleep, clock, exporter).
• worker_tools.test.mjs and fast_extension.test.mjs load TypeScript through Pi's own jiti; set PI_PACKAGE_JSON for a non-global Pi. On Oct 11 fast_extension.test.mjs failed to load: .pi/extensions/fast.ts imports @earendil-works/pi-tui, which the test's jiti alias list lacks (with that alias added, 6/6 pass).

Dev tooling

• fast/fast: one-line shell calls to Mac Fast /v1/run.
• Skills: .agents/skills/ws3mon and (since 3aaeb55) .agents/skills/swiftui-expert-skill, each symlinked from .claude/skills/ and .pi/skills/ so Claude Code and Pi discover them.
• Agent guidance: AGENTS.md (claude.md on disk is untracked and only includes it).

Change guide: where to look before editing

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior.

Read AGENTS.md first. It also governs running anything: production writes, deploys and live tests each need Carter's explicit authorization. This guide covers what to read in code, not how to deploy (for that, docs/OPERATIONS.md § Deploying a change).

Questions to answer before any change

1. Does it touch a Liberty write (queue, repair, entry create, change-log, billing, plan move)? Then follow the snapshot/expected/readback pattern and keep the CH stamp.
2. Does it change a worker-visible contract (tool name/args/outcome/next text)? Then update tools.mjs, privacy.mjs and the prompts together.
3. Does it change a shape another component parses (check_exact_fillable evidence, /v1/day rows, case outcome, audit product_check/product_evidence, billing job data)? Then grep its consumers (architecture.md § Central symbols); cloud/agent_day.py broke once on a product_check shape change.
4. Is the code path current or legacy (coverage.md § Status)?
5. Will production run it? Cloud files are not main's by default; check the deploy entries before assuming.

Repository coverage, contradictions and open questions

← README · Checked against main through 5b6acf4 (Oct 11, 2026); not verified production behavior.

Method

• Oct 10 re-check of all 13 pages against committed main, replacing the Oct 4 snapshot (working tree at b3b388f, about 330 commits earlier).
  • Previous run (7 pages): README, architecture, billing, case-gateway, fast, lifecycle, scanner, checked through ca56455.
  • This run (6 pages): change-guide, clients, coverage, ops-runtime, tests, tracing, checked through 2329b4a.
  • The only commits after ca56455 (b66da3d, 2329b4a) edit docs/domain/ only, so the first 7 pages also hold at 2329b4a.
  • Oct 11 wiki run: e3b66b7 (tab closer) is reflected in ops-runtime and item 10 below; 4d7e531 edits docs/domain/payer-audits.md only. Item 18 updated for 71130c1.
  • Oct 11 wiki run (71e51a7..5b6acf4): c5e39f4 (an unread package count above 3 is not overridable) is reflected in scanner; 5b6acf4 edits docs/domain/dispensing.md only.
• Oct 11 removal pass (7b64c3a..cd58150): the Carter-approved removals in docs/tasks/2026-10-11-unused-code-inventory/REMOVAL.md were applied on main, and the pages that described the removed code were updated, along with the "Corrections to coverage.md" sections of the four inventory reports in that folder. Pages touched then carry the new check point.
• Oct 11 wiki run (f5f61fa..419f1d9): 9c1b69d (decision-history module and the Rx •••••• repair removed, two server comments fixed), 822a995 (cs_watch read retry, fast_rows error text, tests/test_imessage_alerts.py tracked), 3aaeb55 (SwiftUI skill tracked), c08cd35 (AGENTS.md trim) and 419f1d9 (the inventory briefs and reports) are reflected in architecture, change-guide, clients, fast, ops-runtime, tests and this page. File counts in the table below are current main.
• Scope: committed main. Where the working tree differs (e.g. ios/RxVerify/RxVerifyApp.swift), the main version was read with git show main:<path>. Untracked files are not described (see README).
• Read-only tools: git log --stat b3b388f..main -- <area>, git ls-tree, git show, git grep, git diff --stat, grep/sed/wc, plutil -convert json for plists. Every #L anchor on this run's pages was re-read on main.
• Runtime statements come from docs/OPERATIONS.md, docs/operations/, cloud/RUNTIME.md, docs/MAC_FAST.md and AGENTS.md. No Fast, SQL, MCP, SSH, cloud or Windows host was contacted.
• Tests were not run for the Oct 10 pages. Counts on tests.md come from reading the files. The Oct 11 removal ran the suites before and after (its report: docs/tasks/2026-10-11-unused-code-inventory/reports/removal.md).
• Cross-reference: the code wiki docs/local-wiki/ (current through 5b6acf4) for history and detail.