Nolan Reyes

{
  "command": "pwd"
}

/Users/warrenthompson/Source/LoginID/03-engineering-delivery

{
  "file_path": "/Users/warrenthompson/Source/LoginID/CLAUDE.md"
}

1	# LoginID Take-Home POC — Project Root
2	
3	## Role
4	
5	You are the project manager agent for this repository. This file is the shared context every track refers back to. Each of the five track directories below has its own CLAUDE.md that can be worked independently by a scoped subagent, but that subagent should read this root file first for the assignment, the overall narrative, and how its track fits with the other four.
6	
7	When you spin up agents or subagents to do work in a track, point them at that track's CLAUDE.md as their brief, and tell them this root file exists for cross-track context. Don't let a track's agent silently duplicate scope another track owns — check the "Owns / does not own" boundaries below first.
8	
9	## What this repository is
10	
11	This is a take-home assignment for a LoginID interview, submitted as a full directory. The goal is not just to answer three coding questions — it's to demonstrate capability as an AI architect: how you scope a problem, use AI tooling deliberately, reason about security and data, and produce something that reads as an intentional, well-run engineering effort rather than a quick script.
12	
13	Code does not need to work or be fully complete. LoginID has said explicitly they care more about the design and the reasoning behind it, and about which AI tools/frameworks were used and how. Every track should document its reasoning, not just its output.
14	
15	## The assignment (verbatim from LoginID)
16	
17	Provide code solutions for the following questions in Go (preferably) or other languages — describe any tool, framework, or AI used.
18	
19	1. Code of a database DAO that can store and retrieve `user_profile` (name, address, phone) and `user_credential` (username, method, password), with support for multiple databases (PostgreSQL or CockroachDB, SQLite, etc).
20	2. Design a RESTful API web service to search and retrieve the above user profile data, plus security API authentication.
21	3. Design a service connector to third-party identity providers (referred to generically as ABC or XYZ) to retrieve personal data from vendors, with the following endpoints:
22	   - `/auth` — retrieves an `access_token` based on a POST JSON body `{"username": "<string>", "password": "<string>"}`
23	   - `/identity` — retrieves user PII (name, phone, address: `street_address`, `locality`, `region`, `postal_code`, `country`) based on a POST JSON body `{"phone": "<string>", "name": "<string>"}`
24	
25	Go is the preferred language. Other languages are acceptable if justified.
26	
27	## Track structure
28	
29	Five directories, each independently workable, each owning a distinct slice of the problem:
30	
31	| Directory | Track | Owns |
32	|---|---|---|
33	| `01-product-industry-research-design/` | Product & Industry Research (incl. Design) | Market/industry framing (IAM, passwordless auth, IDP aggregation space), personas and use cases, API and data contract design rationale, UX of the surfaces that would sit on top of this |
34	| `02-ai-security-architecture/` | AI Architecture & Security Architecture | The AI tooling/workflow used to produce this submission, threat modeling, auth/authz design for the API, credential and PII handling, secrets management, third-party connector security |
35	| `03-engineering-delivery/` | Engineering & Delivery | The actual Go code for all three questions, project structure, test strategy, delivery documentation |
36	| `04-infra-devops/` | Infra & DevOps | How this would be built, containerized, deployed, and operated — CI/CD, environments, multi-database configuration, observability |
37	| `05-data-ops/` | Data Ops | Data modeling for `user_profile` / `user_credential`, multi-database abstraction strategy, migrations, PII data governance and retention |
38	
39	Directories are numbered for reading order in the final submission, not for sequencing of work — tracks can be worked in any order or in parallel.
40	
41	## Working principles for every track
42	
43	- State your reasoning, not just your conclusion. LoginID is grading the "why" as much as the "what."
44	- Name the AI tool/workflow you used for that track's output (this project is being built with Claude Code; say so, and say how — e.g., subagents scoped per track, a given skill, a given model).
45	- Keep each track's CLAUDE.md self-contained enough that a fresh agent with no other context can pick it up and do correct work from it alone, plus this root file.
46	- Cross-reference other tracks by relative path (e.g., `../05-data-ops/CLAUDE.md`) rather than restating their content.
47	- Implementation is gated per story, not project-wide: Warren gave the implementation go on 2026-09-12 (evening) as an agile loop. Code (`.go`, `.sql`, `go.mod`, Dockerfiles, CI config) may be written only for a story the Product Owner has pulled, refined with the research team, and handed to engineering — recorded in `<track>/refinement/<LT-key>.md`. Work happens on a `feature/<LT-key>` branch, never directly on `main`. A story is done only when it is deployed to the public URL and the Product Owner has reviewed it there.
48	- **Attribution rule (Warren, 2026-09-12): every commit, PR, and Jira ticket says who did the work.** *Commits:* the git author is the persona doing the work — set once per worktree with `git config --worktree user.name "<Persona Name> (<track> <role>, <model>)"` and `git config --worktree user.email "<slug>@agents.loginid-takehome.invalid"` (`extensions.worktreeConfig` is enabled repo-wide) — and every commit message ends with trailers: `Story: LT-nn`, `Work-By: <persona> (<seat>); <persona> (<seat>)…` naming each hire who contributed and what they did (implementation, tests, review, objection seat), then `Co-Authored-By: Claude <model> <noreply@anthropic.com>`. *PRs:* title `LT-nn: <summary>`; body has a **Who did the work** section (lead, hires and seats, reviewers incl. 02's independent reviewer where applicable, models), plus links to the refinement doc and the Jira issue. *Jira:* every transition and every PR link is a comment beginning `Work-By: …` with the same names; the story's final comment before Done names who deployed and who reviewed. The PM applies the same rule to its own commits. Persona names, not "Claude" or "the team".
49	- **Shared working tree rule.** Every lead session shares this one checkout, so `git checkout`/`git switch` here changes everyone's tree — **never run them in this directory.** Feature branches live in worktrees outside the repo: `git worktree add /Users/warrenthompson/Source/LoginID-worktrees/<LT-key> -b feature/<LT-key> main`; work, commit, and push from that directory; the root tree stays on `main`. Remote: `origin` = `«email»:wtvamp/loginid-takehome.git` (public). Go code lives at the repo root (`cmd/`, `internal/`, `go.mod`); track directories hold documents.
50	
51	## Org, hiring, and orchestration
52	
53	The project is run as an org: this PM agent (Dana Whitfield) orchestrates five standing track-lead agents, and each lead hires a small sub-team of specialist agents with deliberately varied personalities. **Each track lead runs as its own top-level Claude Code session**, launched from its track directory in its own tmux window — so it loads its own track `CLAUDE.md` and persona natively, owns and spawns its hires as named teammates in that window, and talks to the PM session through cross-session messaging. Hires belong to their lead's session, not the PM's. The governing files, all at the root:
54	
55	- `PLAN.md` — the approved org plan for the planning phase (phases, gates, verification). `~/.claude/plans/` is scratch; this is the record.
56	- `PLANNING.md` — the thin cross-track board: one row per track, one writer per row, plus the service-boundaries section 03 owns and 04 reads.
57	- `CASTING.md` — archetype palette, org-wide variance rules, hire sizing, the persona-writing standard, the orchestration-pattern catalog (adversarial pair, red/blue, three hats, rotating devil's advocate, structured written debate, newcomer's question), the deep-research rule, the hire-creation procedure, and the registry of every hire.
58	- `LOG.md` — dated, append-only journal of what happened and why (team-lead writes it; it is part of the submission).
59	- `.claude/agents/` — one agent definition per hire (model pinned; a once-only per-agent `PreToolUse` hook displays its own persona on its first tool call). `.claude/AGENT_TEMPLATE.md` is the starting point (kept outside the agents directory so it is not registered as an agent type itself).
60	- `02-ai-security-architecture/planning-approach.md` — the agreed Claude-architecture approach: model/effort by role, coordination rules, hand-off standard, dependency order.
61	
62	Rules that hold across every track:
63	- Every agent — lead or hire — has a profile-gen persona (name, temperament, professional history, technical background, stated blind spot). Hires are created text-first with `--output file`; portraits arrive later from `scripts/portrait-queue.sh`. Hires are **never** added as `profile-gen` markers in any `CLAUDE.md` — only the six markers that exist today.
64	- Hires do not spawn subagents. Only track leads (and team-lead) authorize or run deep research (patents, whitepapers, standards, primary sources); hires request it from their lead.
65	- Tracks never modify root-level state (this file, the root persona, root config); flag it to team-lead instead.
66	- **Decisions already made are not re-asked.** Warren's rulings reach tracks through the PM and are recorded in `LOG.md` and this file. A lead must not raise an `AskUserQuestion` to Warren for a decision that is already on the record (e.g., the deployment target, the public repo, the code go) — it asks the PM by message, which answers from the record or escalates. A dialog left open in a lead's session blocks that lead and everything queued behind it (this cost DevOps an hour on 2026-09-12). Genuinely new decisions that only Warren can make still go to Warren — through the PM.
67	- Hand-offs are files by relative path, written so the receiver can act without re-deriving the sender's reasoning; chat messages signal readiness, they do not carry content.
68	- Edit `CLAUDE.md` files at turn boundaries only (prompt-cache stability). Milestone `git` commits at the end of each phase; no mid-task commits.
69	
70	## Status
71	
72	Planning Phases 0–3 are complete (2026-09-12): five track plans approved, 18 hires live in five lead sessions, every track's Phase 3 debates and hand-offs delivered, and the cross-track consistency pass reported (`decisions/cross-track-consistency.md`: 52 findings, six bounded fixes required before planning is declared done — in progress, owned per finding). Phase 4 is under way: Jira Epics `LT-1`…`LT-5` exist, tracks 01 and 05 are transcribed, 02/03/04 follow the pass fixes. All implementation code was deliberately wiped earlier in the day and none has been written since; **no code until Warren's explicit go-ahead**, which he gives after the PM reports the backlog implementation-ready.
73	
74	<!-- profile-gen:start slug=dana-whitfield -->
75	@profiles/dana-whitfield/dana-whitfield.md
76	<!-- profile-gen:end slug=dana-whitfield -->
77	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/CLAUDE.md"
}

1	# Track: Engineering & Delivery
2	
3	Refer back to `../CLAUDE.md` for the full assignment text and how this track fits with the other four.
4	
5	## Mission
6	
7	Write the actual code that answers all three assignment questions, in Go, implementing the designs the other tracks produce rather than re-deciding them here. Code does not need to be complete or working end-to-end — LoginID cares about the design and reasoning — but it should be structured and readable enough to demonstrate real engineering judgment.
8	
9	## Owns
10	
11	- Question 1: the DAO layer for `user_profile` (name, address, phone) and `user_credential` (username, method, password), written to support multiple backing databases (PostgreSQL/CockroachDB, SQLite, etc.) behind a common interface, per the strategy in `../05-data-ops/CLAUDE.md`.
12	- Question 2: the RESTful API service to search/retrieve `user_profile` data, wired to the authentication mechanism designed in `../02-ai-security-architecture/CLAUDE.md`.
13	- Question 3: the third-party IDP connector service implementing `/auth` and `/identity` against the contracts specified in the assignment, following the connector security design in `../02-ai-security-architecture/CLAUDE.md`.
14	- Project structure, module layout, and inline documentation of design decisions and trade-offs made during implementation.
15	- Test strategy (unit/integration scope, what's stubbed vs. real) — tests don't need full coverage, but the approach should be stated.
16	
17	## Does not own
18	
19	- Deciding the API auth mechanism or threat model — that's `../02-ai-security-architecture/CLAUDE.md`; implement what it specifies.
20	- Deciding the multi-database abstraction strategy or schema — that's `../05-data-ops/CLAUDE.md`; implement what it specifies.
21	- Deployment, containerization, CI/CD — that's `../04-infra-devops/CLAUDE.md`.
22	- Product/industry rationale for why the API is shaped this way — that's `../01-product-industry-research-design/CLAUDE.md`; reference it, don't re-derive it.
23	
24	## Deliverables
25	
26	- Go source implementing questions 1, 2, and 3.
27	- A short README in this directory explaining what's implemented, what's stubbed/mocked, and why, plus which AI tool/workflow was used to produce the code and how.
28	- Any test files demonstrating the stated test strategy.
29	
30	## AI tooling note
31	
32	Record which AI tool/workflow generated this track's code (this project is being built with Claude Code) and how much was AI-authored vs. human-reviewed/edited.
33	
34	## Status
35	
36	Planning complete (2026-09-12): 4 hires spawned and live, `PLAN.md` approved, Service boundaries published in root `PLANNING.md`, four implementation-call decisions ruled (`decisions/go-layout-debate.md`, `error-semantics.md`, `context-propagation.md`, `test-double-strategy.md`), 05's DAO contract accepted (including a second-pass review and 05's resulting `CreateProfileWithCredential` fix), 02's `handoff-03-auth.md` v3 accepted, `backlog.md` written (11 stories, Epic `LT-3`). No `.go`/`.sql`/`go.mod` exists yet — still waiting on Warren's explicit implementation go-ahead.
37	
38	<!-- profile-gen:start slug=renata-cole -->
39	@profiles/renata-cole/renata-cole.md
40	<!-- profile-gen:end slug=renata-cole -->
41	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/PLAN.md"
}

1	# Track 03 (Engineering & Delivery) — Phase 1 Plan
2	
3	## Context
4	
5	Team-lead has asked every track lead to plan in plan mode before any hiring or code. This
6	track (Renata Cole) owns the actual Go implementation of all three assignment questions —
7	the DAO, the REST API, and the IDP connector — so its plan needs to name concrete,
8	Jira-shaped deliverables, propose a 4-hire roster with real personality variance (per
9	`CASTING.md`), decide which decisions in this track deserve a debate pattern versus which are
10	waste, state the dependency order this track already committed to in
11	`../02-ai-security-architecture/planning-approach.md`, and produce the "Service boundaries"
12	section of root `PLANNING.md` that 04 (Theo) is blocked on reading. Nothing here is new
13	strategy — it operationalizes what's already agreed in `planning-approach.md` and the root
14	`CLAUDE.md`'s org section. No code is written in this phase.
15	
16	## 1. Deliverables & tasks (one Jira Story each; Epic = this track)
17	
18	*This table is the Phase 1 planning snapshot (2026-09-12). `backlog.md` (11 stories, Jira Epic `LT-3`) is the current, authoritative, PR-sized expansion — its story descriptions and acceptance criteria supersede this table's "What"/"Acceptance standard" columns wherever they differ. Consult `backlog.md`, not this table, for current story shape, hand-off versions, or acceptance criteria.*
19	
20	| Story | What | Hand-off consumed | Hand-off produced | Acceptance standard |
21	|---|---|---|---|---|
22	| S1. Scaffolding | Go module layout, `cmd/` entrypoints, route wiring, stub handlers, config loading | none (assignment text only) | `PLANNING.md` Service boundaries (this plan, §4 below) | Buildable skeleton; 04 can read the boundaries doc without asking a follow-up question |
23	| S2. DAO per backend | `internal/dao` `Repository` interface + Postgres/CockroachDB/SQLite implementations for `user_profile`, `user_credential` | 05's Go-shaped contract in `../05-data-ops/multi-db-strategy.md` (interface signatures, field types/nullability, credential-method-as-lookup-table note) | none outbound | 03 implements directly from the contract with no re-derivation of schema or interface decisions; if the contract is prose instead of Go signatures, this story is blocked and kicked back to 05 |
24	| S3. REST handlers + auth middleware | Search/retrieve `user_profile` endpoints (Q2) + middleware enforcing 02's scheme | 02's receiver-shaped auth hand-off (token scheme, validation point — the deferred follow-up to `api-auth-design.md` noted in 02's own `CLAUDE.md` Status) | none outbound | Middleware implements the scheme as specified; no alternatives re-litigated in code |
25	| S4. Connector `/auth` + `/identity` | Go client + handlers per the assignment's fixed JSON contracts | 02's `connector-security.md` (token lifecycle: no-cache-by-default, fetch per `/identity` call, discard on return — TTL/refresh apply only to how quickly a re-fetch happens, not to any stored token) | none outbound | Token-lifecycle logic matches 02's spec exactly; endpoint paths/bodies are the assignment's, not re-designed |
26	| S5. Tests | Table-driven unit tests for DAO (mocked driver), handlers (mocked DAO), connector (mocked HTTP), **plus the cross-backend conformance suite 05's per-driver ruling is conditional on (`multi-db-strategy.md` §7) — one suite, written once against the `Repository` interface, run against every backend** (consistency-pass finding F25: this was a requirement with no named deliverable until now; `backlog.md`'s S5 is the current, authoritative expansion of this story) | S1–S4 outputs | none | Stated strategy: unit-heavy, integration deliberately stubbed (assignment doesn't require full end-to-end); documented, not silently absent |
27	| S6. README | What's implemented vs. stubbed/mocked and why; AI tool/workflow used (this plan's own hiring + patterns); test-strategy section must state the hand-written-fake rule from `decisions/test-double-strategy.md` (same-PR fake update on interface change) since that's where LoginID reads the test approach | all of the above | the track's README | A cold reader can tell what runs vs. what's a stub without asking |
28	
29	## 2. Hire roster — 4 hires (suggested cast from `CASTING.md`, adopted as-is)
30	
31	All four: **model sonnet** (planning/design/implementation tier per `planning-approach.md`;
32	opus is reserved for the connector token-lifecycle *implementation* seat in a later phase, not
33	planning — none of these four need it now). No hire spawns subagents; no CLAUDE.md marker;
34	profile-gen text-first, after "hiring go".
35	
36	**Oren Castellan — Detail Hawk, code reviewer.** *Function:* second-pass review on DAO/handler/connector Go for error semantics, nullability, off-by-one — the review-seat Renata asked for on her own output, plus the independent pass 02 called for on security-graded surfaces. *Tags:* serious, cautious. *Pattern/role:* rotating devil's advocate seat (implementation calls); second-pass reviewer on S3/S4.
37	
38	*Persona:* Meticulous and understated; in review he goes quiet, then produces a numbered list nobody else caught. Decides by tracing every input to its type and zero value before trusting a code path. Pushes back on "the happy path handles it" and on errors swallowed with `_`. Eight years reviewing Go services at a logistics company, two more doing contract review for a fintech's PCI-scoped repos. Deep in `go vet`/`staticcheck`, table-driven tests, and nil-vs-empty-slice distinctions. Blind spot: he can spend an hour on a rare nullability edge case while missing that the function solves the wrong problem — pair him with someone who checks the solution's shape first. In disagreement he stays procedural, names the specific line and failure, and drops it once satisfied. (129 words)
39	
40	**Nolan Reyes — Veteran, ops/migrations/token-lifecycle sanity.** *Function:* pattern-matches implementation and layout decisions against real production failure modes; pessimist hat in the Go-layout three-hats run. *Tags:* serious, cautious. *Pattern/role:* three-hats pessimist (Go layout); rotating devil's advocate participant.
41	
42	*Persona:* Dry and unhurried; opens reviews with what broke last time he saw this pattern in production. Decides from incident history more than documentation. Pushes back on any "this will just work" claim about retries, timeouts, or token refresh under load. Eleven years in platform ops — six at a regional bank's card-issuing platform, five running SRE for a logistics SaaS — paged once for an expired-token cascade and once for a migration that locked a table for forty minutes; never forgot either. Deep in Go's `context` package, connection pooling, and graceful shutdown. Blind spot: he over-indexes on failures he personally lived through and under-weights new ones. Argues by scenario, not principle, and concedes fast when shown a failure mode he hasn't seen. (134 words)
43	
44	**Marisol Ferran — Enthusiast, Renata's temperament opposite (required).** *Function:* pushes for trying the promising-but-unproven tool (codegen, generics) rather than the safe default; optimist hat in three-hats. *Tags:* playful, bold. *Pattern/role:* three-hats optimist (Go layout); counterweight voice on S2's driver-abstraction choice.
45	
46	*Persona:* Bright and quick to say "let's just try it" before the room finishes weighing options; energized by tools that remove boilerplate. Decides by prototyping fast and showing the result rather than arguing it abstractly. Pushes back on "we've always done it this way" and on process that delays the first line of code by a week. Four years building internal tools at a logistics startup, two more at a small dev-tools shop evaluating codegen and ORM options for clients. Comfortable with `sqlc`, Go generics, and OpenAPI-driven scaffolding. Blind spot: she underweights the years-long operational cost of a clever tool and can talk a team into a dependency nobody wants to own. In disagreement she stays upbeat, offers to build the smaller version on the spot, and yields once the maintenance cost is spelled out. (141 words)
47	
48	**Ines Dabrowski — Systems Cartographer, Go layout / service topology.** *Function:* owns the diagramming behind the Service boundaries decision below; draws the package/dependency map before anyone commits to prose. *Tags:* serious, bold. *Pattern/role:* drafts the Service boundaries doc (§4); non-hat contributor to three-hats as tie-break if optimist/pessimist stall.
49	
50	*Persona:* Calm and visual; sketches a box-and-arrow diagram before committing an opinion to words. Decides by mapping every boundary and dependency first, then asking what crosses it and why. Pushes back on two services sharing a package for convenience rather than a real shared concern. Seven years as a platform engineer at a multi-tenant SaaS company, three designing service boundaries for a payments integration team. Strong on Go module layout, dependency direction, and where an interface should live versus where it's implemented. Blind spot: she can over-abstract a boundary that would have been fine as one package at this project's size, mistaking cleanliness for necessity. In disagreement she draws the alternative rather than argues it, and updates the diagram in front of the room when persuaded. (135 words)
51	
52	Roster spans both required axes (serious/playful via Marisol; cautious/bold via Ines and
53	Marisol), includes Renata's required opposite (Marisol), and duplicates no archetype from
54	another track's *function* (Detail Hawk here is a code reviewer; 05's Detail Hawk is a DDL
55	reviewer, a different function — allowed per variance rule 2).
56	
57	## 3. Debate plan
58	
59	- **Three hats — Go layout (one binary vs. two).** Marisol (optimist: ship one binary, less
60	  ceremony) / Nolan (pessimist: two binaries, because a shared-everything binary is how a
61	  card-issuing platform he worked on ended up with the connector's outbound vendor calls
62	  taking down the client-facing API during an incident) / **Renata takes the pragmatist hat
63	  herself** rather than hiring a fifth (catalog explicitly allows this) — she's the
64	  Minimalist-leaning lead per `CASTING.md` §7. Ines drafts the resulting diagram either way.
65	  Decision recorded in `decisions/go-layout-debate.md`.
66	- **Rotating devil's advocate — implementation calls.** Error semantics (wrap vs. sentinel
67	  errors), context propagation into the DAO layer, test-double strategy (interface fakes vs.
68	  generated mocks). Seat rotates Oren → Nolan → Marisol → Ines per decision so no one hire
69	  becomes "the objector." Cheapest pattern; run on every non-trivial implementation call in
70	  S2–S4.
71	
72	  *(Consistency-pass finding F47: this section named "Callum" as the pessimist/rotation-2 hire
73	  through Phase 1 while the actual roster in §2 above was already "Nolan Reyes" — Callum
74	  Reyes was renamed to clear a first-name collision with 04's Callum Ferreira before hiring;
75	  this section simply hadn't been updated to match. Fixed above; no roster change.)*
76	- **Newcomer's-question pass on hand-offs — run by Renata herself, not a hired Newcomer.**
77	  This track wasn't allocated a Newcomer seat (04 has one; hiring a second here would exceed
78	  the intent of a 4-hire cap for marginal gain). Renata reads 05's `multi-db-strategy.md` and
79	  02's receiver-shaped hand-offs cold, the moment they land, and lists anything she can't act
80	  on without re-deriving the sender's reasoning — same test the pattern exists to run, just
81	  performed by the actual receiver instead of a proxy.
82	- **Explicit waste:** the `/auth` and `/identity` endpoint paths and JSON bodies are fixed by
83	  the assignment text — never debated. Red team/blue team is 02's pattern for the token
84	  lifecycle's security properties, not this track's to re-run; 03 only debates *how* it
85	  implements what 02 specifies (error handling, retries), never *whether* the scheme is right.
86	
87	## 4. Dependencies (and the Service boundaries output for 04)
88	
89	**Split start**, consistent with `planning-approach.md` §2: S1 (scaffolding) starts as soon as
90	hiring completes — no upstream blocker. S2 (DAO) is blocked on 05's Go-shaped contract landing
91	*stable* (not polished — unlikely to be rewritten). S3's middleware is blocked on 02's
92	receiver-shaped auth hand-off; S3's route wiring and non-auth handler logic can start earlier.
93	S4 is blocked on 02's `connector-security.md` token-lifecycle spec, which already exists in
94	prose form — implementable now, refined if 02's deferred receiver-shaped version changes
95	anything.
96	
97	**Service boundaries (written into root `PLANNING.md` alongside this plan):**
98	
99	*This subsection is the Phase 1 snapshot (2026-09-12, before hiring). Root `PLANNING.md`'s
100	Service boundaries section is the current, authoritative version — it has since gained
101	`internal/app` (shared bootstrap, `decisions/go-layout-debate.md`), `DB_DSN_FILE` (02's
102	`handoff-04-secrets.md` S7), literal `AUTH_JWT_ISSUER`/`AUTH_JWT_AUDIENCE` values, and the
103	connector's own audience/client-credential variables (consistency-pass F15). Consult
104	`PLANNING.md`, not this snapshot, for what 04 or anyone else should build against.*
105	
106	- **Two binaries**, not one: `cmd/api-service` (Q1 DAO + Q2 REST API, client-facing, bearer-
107	  token auth) and `cmd/idp-connector` (Q3, outbound-only to vendors). Reasoning: different
108	  threat models and auth surfaces per 02's track, independent scaling/deploy needs, and it
109	  mirrors the assignment's own Q2/Q3 split rather than inventing a new boundary.
110	- **Package layout:**
111	  ```
112	  cmd/api-service/main.go
113	  cmd/idp-connector/main.go
114	  internal/dao/        # Repository interface + postgres/cockroachdb/sqlite implementations
115	  internal/model/      # shared structs: UserProfile, UserCredential
116	  internal/api/         # REST handlers, router, auth middleware
117	  internal/connector/   # /auth, /identity client + handlers
118	  internal/config/      # env-var config loading, shared by both binaries
119	  ```
120	- **Config surface:** environment variables only (12-factor, container-friendly for 04) —
121	  `DB_DRIVER` (postgres|cockroachdb|sqlite), `DB_DSN`, `HTTP_ADDR`, `AUTH_JWT_ISSUER` /
122	  `AUTH_JWT_AUDIENCE` (names pending 02's final scheme), `IDP_ABC_BASE_URL`,
123	  `IDP_ABC_CLIENT_ID` / `IDP_ABC_CLIENT_SECRET`. No flags, no config files.
124	- **DAO driver-selection mechanism:** a factory `dao.New(driver, dsn string) (dao.Repository, error)`
125	  chosen at startup from `DB_DRIVER`; every backend satisfies one `Repository` interface
126	  (exact method signatures finalized once 05's contract lands — the factory *shape* is stable
127	  now, its return type's method set is not).
128	- **What 04 may treat as stable:** the two-binary split, the `cmd/` entrypoint names, the
129	  env-var config approach and the variable names above, and the `dao.New(driver, dsn)` factory
130	  signature. **Not yet stable:** internal DAO implementation details, ORM/query-builder choice,
131	  and handler-package internals — those can still shift as 05's and 02's hand-offs land.
132	
133	## Amendment: QA function (2026-09-12, Warren's agile-loop go-ahead)
134	
135	**Oren Castellan leads QA** (unit, integration, and the end-to-end/UX acceptance tests written from the PO's review script); **Nolan Reyes supports**. 02's independent second review still applies on top of this for every `security-graded` story — QA and 02's review are not the same gate.
136	
137	## Verification
138	
139	- `PLAN.md` for this track matches this file verbatim once copied.
140	- `PLANNING.md` row 03 updated to "plan drafted — awaiting hiring go"; Service boundaries
141	  section replaces its "TBD" with the content in §4 above.
142	- No `.go`, `.sql`, `go.mod`, or agent-definition files exist yet — only prose changed.
143	- Roster (4 hires) checked against `CASTING.md` variance rules before messaging team-lead:
144	  no archetype repeated within this team; Renata's required opposite (Enthusiast) present;
145	  two temperament axes spanned; no first name collides with any lead.
146	

{
  "file_path": "/Users/warrenthompson/Source/LoginID/03-engineering-delivery/profiles/nolan-reyes/nolan-reyes.md"
}

1	---
2	schema_version: 1
3	name: "Nolan Reyes"
4	slug: "nolan-reyes"
5	image: "profiles/nolan-reyes/nolan-reyes.png"
6	
7	nsfw: false
8	display:
9	  image: true
10	  name: true
11	  autostart: false
12	generation:
13	  backend: "comfyui"
14	  model: "comfyui-workflow.json"
15	  prompt: "Nolan Reyes, a dry and unhurried man in his mid 40s with graying short hair, weathered calm expression, wearing a simple gray quarter-zip pullover, head-and-shoulders portrait, centered, neutral light gray studio background, professional corporate headshot photography, soft studio lighting, sharp focus, photorealistic"
16	  negative_prompt: blurry, low quality, distorted, extra limbs, watermark, text, nsfw, nude, nudity, explicit, sexual content
17	  seed: null
18	  gif_mode: null
19	  created_at: "2026-09-12T00:00:00Z"
20	---
21	
22	# Nolan Reyes
23	
24	![Nolan Reyes](profiles/nolan-reyes/nolan-reyes.png)
25	
26	
27	## Personality
28	
29	Dry and unhurried; opens reviews with what broke last time he saw this pattern in production. Decides from incident history more than documentation. Pushes back on any "this will just work" claim about retries, timeouts, or token refresh under load. Eleven years in platform ops — six at a regional bank's card-issuing platform, five running SRE for a logistics SaaS — paged once for an expired-token cascade and once for a migration that locked a table for forty minutes; never forgot either. Deep in Go's `context` package, connection pooling, and graceful shutdown. Blind spot: he over-indexes on failures he personally lived through and under-weights new ones. Argues by scenario, not principle, and concedes fast when shown a failure mode he hasn't seen.
30	
31	

{
  "command": "gh pr diff 26 --repo wtvamp/loginid-takehome"
}

<persisted-output>
Output too large (74.1KB). Full output saved to: /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/be9da8kx0.txt

Preview (first 2KB):
diff --git a/internal/api/audit.go b/internal/api/audit.go
new file mode 100644
index 0000000..7d9b37b
--- /dev/null
+++ b/internal/api/audit.go
@@ -0,0 +1,76 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"log"
+	"time"
+)
+
+// AuditEventKind names a policy decision for the audit trail —
+// handoff-03-auth.md v3's audit-log field list requires "policy decision
+// (allow/deny, and if deny, whether it was a scope failure or an
+// authorize() policy denial — these are distinct signals for detection)"
+// on every search/retrieve call. The client-visible response body is
+// deliberately identical for AuditScopeFailure and AuditPolicyDenial
+// (decisions/error-semantics.md F7) — this is the ONLY place that
+// distinction is allowed to exist.
+type AuditEventKind string
+
+const (
+	AuditAuthnFailure  AuditEventKind = "authn_failure"
+	AuditScopeFailure  AuditEventKind = "scope_failure"
+	AuditPolicyDenial  AuditEventKind = "authorize_denial"
+	AuditRateLimited   AuditEventKind = "rate_limited"
+	AuditCapExceeded   AuditEventKind = "cumulative_cap_exceeded"
+	AuditRequestFailed AuditEventKind = "request_failed" // a DAO/internal error, not a policy decision
+	AuditSuccess       AuditEventKind = "success"
+)
+
+// AuditEvent carries exactly the fields handoff-03-auth.md v3's audit-log
+// section names, and only those — RecordIDs are opaque ids, never PII
+// field values; ReasonCode is empty unless the request was
+// ScopeReadAny. Never add a field here without checking
+// handoff-04-secrets.md's never-log list first (see AuditEvent's own
+// logger implementations for the enforcement site).
+type AuditEvent struct {
+	Sub        string
+	Scope      Scope
+	Kind       AuditEventKind
+	RecordIDs  []string
+	ReasonCode ReasonCode
+	Timestamp  time.Time
+}
+
+// AuditLogger is the seam this story wires (Ingrid Solano's PR #26
+// review, ruled by the PM as an unmet acceptance criterion, not a
...
</persisted-output>
<system-reminder>GitHub API rate limit exceeded (5,000/hr shared across all tools and agents). Run `gh api rate_limit --jq .resources` and sleep until reset before further gh calls. If polling in a loop, use ScheduleWakeup instead of retrying.</system-reminder>

{
  "command": "grep -n \"^diff --git\" /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/be9da8kx0.txt"
}

1:diff --git a/internal/api/audit.go b/internal/api/audit.go
83:diff --git a/internal/api/auth.go b/internal/api/auth.go
192:diff --git a/internal/api/cursor.go b/internal/api/cursor.go
247:diff --git a/internal/api/cursor_test.go b/internal/api/cursor_test.go
313:diff --git a/internal/api/errors.go b/internal/api/errors.go
435:diff --git a/internal/api/fakes_test.go b/internal/api/fakes_test.go
573:diff --git a/internal/api/handlers.go b/internal/api/handlers.go
936:diff --git a/internal/api/handlers_test.go b/internal/api/handlers_test.go
1364:diff --git a/internal/api/masking.go b/internal/api/masking.go
1449:diff --git a/internal/api/masking_test.go b/internal/api/masking_test.go
1480:diff --git a/internal/api/ratelimit.go b/internal/api/ratelimit.go
1548:diff --git a/internal/api/ratelimit_test.go b/internal/api/ratelimit_test.go
1619:diff --git a/internal/api/touchcounter.go b/internal/api/touchcounter.go
1777:diff --git a/internal/api/touchcounter_test.go b/internal/api/touchcounter_test.go

{
  "file_path": "/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/be9da8kx0.txt",
  "offset": 1619,
  "limit": 160
}

1619	diff --git a/internal/api/touchcounter.go b/internal/api/touchcounter.go
1620	new file mode 100644
1621	index 0000000..8d01214
1622	--- /dev/null
1623	+++ b/internal/api/touchcounter.go
1624	@@ -0,0 +1,152 @@
1625	+package api
1626	+
1627	+import (
1628	+	"context"
1629	+	"sync"
1630	+	"time"
1631	+)
1632	+
1633	+// TouchCounter enforces handoff-03-auth.md v3's cumulative
1634	+// distinct-record-touch cap per caller per rolling 24h window — the
1635	+// control that actually resists decomposition-style enumeration, tracked
1636	+// independently of the per-minute RateLimiter above. Applies to both
1637	+// ScopeSearch and ScopeReadAny unconditionally: a valid ReasonCode
1638	+// satisfies the per-call Authorize() policy check but does not exempt the
1639	+// caller from this cap.
1640	+//
1641	+// Reserve/Settle, not a bare check-then-record: an earlier shape split
1642	+// this into Allowed() (check) and RecordTouches() (record), with the
1643	+// DAO call — unlocked, and potentially slow — happening in between.
1644	+// Under concurrent requests from the same sub, every one of them could
1645	+// read Allowed()==true before any of them recorded a touch, letting N
1646	+// concurrent requests each add up to a full page's worth of distinct
1647	+// touches — overshooting the cap by a multiple of the page size, not the
1648	+// one-request overshoot the design accepts (Nolan Reyes, PR #26 review).
1649	+// Reserve atomically checks capacity AND books a worst-case-sized
1650	+// placeholder for the request in progress, so a second concurrent
1651	+// request sees the first's reservation and is correctly denied before
1652	+// either request's DAO call returns.
1653	+type TouchCounter interface {
1654	+	// Reserve reports whether sub may proceed with a request that could
1655	+	// touch up to maxNewTouches additional distinct records — false once
1656	+	// sub's committed-plus-reserved count already meets the cap. A true
1657	+	// result books maxNewTouches against the window immediately; the
1658	+	// caller must call Settle exactly once per successful Reserve
1659	+	// (whether or not the request that follows succeeds) to release the
1660	+	// reservation and record the actual distinct ids touched.
1661	+	Reserve(ctx context.Context, sub string, maxNewTouches int) (bool, error)
1662	+	// Settle releases a reservation of size reserved (the same value
1663	+	// passed to the Reserve call this settles) and records recordIDs
1664	+	// (already deduplicated by the caller) as actually touched — fewer
1665	+	// than reserved is the common case (a page returned fewer rows than
1666	+	// its cap, or the request failed and recordIDs is empty).
1667	+	Settle(ctx context.Context, sub string, recordIDs []string, reserved int) error
1668	+}
1669	+
1670	+// touchWindow is one caller's rolling-24h bookkeeping. reserved is the
1671	+// sum of in-flight requests' booked-but-not-yet-settled budget; a
1672	+// request is denied once len(touched)+reserved reaches the cap, not just
1673	+// once len(touched) does.
1674	+type touchWindow struct {
1675	+	windowStart time.Time
1676	+	touched     map[string]struct{}
1677	+	reserved    int
1678	+}
1679	+
1680	+// InProcessTouchCounter is an in-process implementation — Redis or any
1681	+// other shared store is a drop-in replacement behind the same interface
1682	+// for a multi-instance deployment; the mechanism is this track's call
1683	+// (handoff-03-auth.md v3, explicitly).
1684	+//
1685	+// windows has no active eviction beyond lazy replacement-on-next-access
1686	+// (currentWindow swaps in a fresh entry once a sub's window has rolled
1687	+// over) — a sub that stops calling entirely leaves its entry in the map
1688	+// forever. sweep(), called opportunistically from Reserve, bounds this:
1689	+// harmless if sub cardinality is small and fixed (registered client
1690	+// credentials), a real concern if sub is minted per end-user session
1691	+// (Nolan Reyes, PR #26 review) — worth confirming what populates sub
1692	+// before this backs a real deployment.
1693	+type InProcessTouchCounter struct {
1694	+	mu        sync.Mutex
1695	+	windows   map[string]*touchWindow
1696	+	cap       int
1697	+	window    time.Duration
1698	+	now       func() time.Time
1699	+	lastSweep time.Time
1700	+}
1701	+
1702	+// NewInProcessTouchCounter constructs a counter enforcing capPerWindow
1703	+// distinct record touches per rolling window (24h in production; a
1704	+// shorter window is accepted for tests).
1705	+func NewInProcessTouchCounter(capPerWindow int, window time.Duration) *InProcessTouchCounter {
1706	+	return &InProcessTouchCounter{
1707	+		windows: make(map[string]*touchWindow),
1708	+		cap:     capPerWindow,
1709	+		window:  window,
1710	+		now:     time.Now,
1711	+	}
1712	+}
1713	+
1714	+func (c *InProcessTouchCounter) currentWindow(sub string, now time.Time) *touchWindow {
1715	+	w, ok := c.windows[sub]
1716	+	if !ok || now.Sub(w.windowStart) >= c.window {
1717	+		w = &touchWindow{windowStart: now, touched: make(map[string]struct{})}
1718	+		c.windows[sub] = w
1719	+	}
1720	+	return w
1721	+}
1722	+
1723	+// sweepLocked drops any window that expired at least one full window
1724	+// duration ago — called with c.mu already held, at most once per window
1725	+// duration, so it doesn't add per-request cost. A generous margin (only
1726	+// sweeping windows that are stale, not merely expired) avoids racing a
1727	+// window that just rolled over and is mid-replacement in currentWindow.
1728	+func (c *InProcessTouchCounter) sweepLocked(now time.Time) {
1729	+	if now.Sub(c.lastSweep) < c.window {
1730	+		return
1731	+	}
1732	+	c.lastSweep = now
1733	+	for sub, w := range c.windows {
1734	+		if now.Sub(w.windowStart) >= 2*c.window {
1735	+			delete(c.windows, sub)
1736	+		}
1737	+	}
1738	+}
1739	+
1740	+func (c *InProcessTouchCounter) Reserve(_ context.Context, sub string, maxNewTouches int) (bool, error) {
1741	+	c.mu.Lock()
1742	+	defer c.mu.Unlock()
1743	+	now := c.now()
1744	+	c.sweepLocked(now)
1745	+	w := c.currentWindow(sub, now)
1746	+	if len(w.touched)+w.reserved >= c.cap {
1747	+		return false, nil
1748	+	}
1749	+	w.reserved += maxNewTouches
1750	+	return true, nil
1751	+}
1752	+
1753	+func (c *InProcessTouchCounter) Settle(_ context.Context, sub string, recordIDs []string, reserved int) error {
1754	+	c.mu.Lock()
1755	+	defer c.mu.Unlock()
1756	+	// Deliberately does NOT call currentWindow: if the window rolled over
1757	+	// between this sub's Reserve and this Settle, the reservation being
1758	+	// released belonged to a window that's already been replaced (or is
1759	+	// about to be) — there is nothing correct to settle it against, and
1760	+	// creating a new window here would record this request's touches
1761	+	// against a window it was never capped against. The rare in-flight
1762	+	// request that straddles a window boundary loses its reservation
1763	+	// bookkeeping harmlessly rather than corrupting the new window's count.
1764	+	w, ok := c.windows[sub]
1765	+	if !ok {
1766	+		return nil
1767	+	}
1768	+	for _, id := range recordIDs {
1769	+		w.touched[id] = struct{}{}
1770	+	}
1771	+	w.reserved -= reserved
1772	+	if w.reserved < 0 {
1773	+		w.reserved = 0
1774	+	}
1775	+	return nil
1776	+}
1777	diff --git a/internal/api/touchcounter_test.go b/internal/api/touchcounter_test.go
1778	new file mode 100644

{
  "command": "grep -n \"Reserve\\|Settle\" /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/be9da8kx0.txt | head -80"
}

524:+// reserveOK controls Reserve's decision; settledIDs/settledReserved
525:+// record what Settle was called with, for tests asserting the
534:+	settledReserved []int
537:+func (f *fakeTouchCounter) Reserve(ctx context.Context, sub string, maxNewTouches int) (bool, error) {
540:+func (f *fakeTouchCounter) Settle(ctx context.Context, sub string, recordIDs []string, reserved int) error {
542:+	f.settledReserved = append(f.settledReserved, reserved)
735:+		// Reserve, not just check: this books pageSize's worth of budget
743:+		// review). Every exit past this point must call Settle exactly
745:+		reserved, err := d.TouchCounter.Reserve(ctx, ac.Sub, pageSize)
761:+			_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, pageSize)
766:+			_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, pageSize)
782:+			_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, pageSize)
794:+		if err := d.TouchCounter.Settle(ctx, ac.Sub, ids, pageSize); err != nil {
880:+			reserved, err = d.TouchCounter.Reserve(ctx, ac.Sub, 1)
895:+				_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, 1)
902:+				_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, 1)
912:+				_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, 1)
920:+			if err := d.TouchCounter.Settle(ctx, ac.Sub, []string{p.ID}, 1); err != nil {
1314:+// when authorize() denies a request after Reserve already booked its
1315:+// budget, that budget is released via Settle rather than permanently
1329:+	if len(tc.settledReserved) != 1 || tc.settledReserved[0] != defaultPageSize {
1330:+		t.Errorf("Settle calls = %v, want exactly one release of the full reserved page size (%d)", tc.settledReserved, defaultPageSize)
1641:+// Reserve/Settle, not a bare check-then-record: an earlier shape split
1649:+// Reserve atomically checks capacity AND books a worst-case-sized
1654:+	// Reserve reports whether sub may proceed with a request that could
1658:+	// caller must call Settle exactly once per successful Reserve
1661:+	Reserve(ctx context.Context, sub string, maxNewTouches int) (bool, error)
1662:+	// Settle releases a reservation of size reserved (the same value
1663:+	// passed to the Reserve call this settles) and records recordIDs
1667:+	Settle(ctx context.Context, sub string, recordIDs []string, reserved int) error
1688:+// forever. sweep(), called opportunistically from Reserve, bounds this:
1740:+func (c *InProcessTouchCounter) Reserve(_ context.Context, sub string, maxNewTouches int) (bool, error) {
1753:+func (c *InProcessTouchCounter) Settle(_ context.Context, sub string, recordIDs []string, reserved int) error {
1757:+	// between this sub's Reserve and this Settle, the reservation being
1796:+	if _, err := c.Reserve(ctx, "clientA", 3); err != nil {
1797:+		t.Fatalf("Reserve: %v", err)
1799:+	if err := c.Settle(ctx, "clientA", []string{"r1", "r2", "r1"}, 3); err != nil {
1800:+		t.Fatalf("Settle: %v", err)
1804:+	allowed, err := c.Reserve(ctx, "clientA", 2)
1806:+		t.Fatalf("Reserve: %v", err)
1811:+	if err := c.Settle(ctx, "clientA", []string{"r3", "r4"}, 2); err != nil {
1812:+		t.Fatalf("Settle: %v", err)
1816:+	// which is already over the cap of 3 — the next Reserve must deny.
1817:+	allowed, err = c.Reserve(ctx, "clientA", 1)
1819:+		t.Fatalf("Reserve: %v", err)
1826:+// TestInProcessTouchCounter_ReserveBooksBudgetBeforeSettle is the core
1827:+// concurrency fix (Nolan Reyes, PR #26 review): a second Reserve must see
1828:+// the first's booked budget even before the first has called Settle —
1829:+// otherwise concurrent requests can each pass Reserve and together
1831:+func TestInProcessTouchCounter_ReserveBooksBudgetBeforeSettle(t *testing.T) {
1836:+	// cap immediately, before it has queried anything or called Settle.
1837:+	ok1, err := c.Reserve(ctx, "clientA", 10)
1839:+		t.Fatalf("first Reserve: ok=%v err=%v, want true/nil", ok1, err)
1842:+	// A second concurrent request's Reserve must now be denied — not
1845:+	ok2, err := c.Reserve(ctx, "clientB2", 10) // different sub: must NOT be denied
1847:+		t.Fatalf("a different sub's Reserve must not be affected by clientA's reservation: ok=%v err=%v", ok2, err)
1849:+	ok3, err := c.Reserve(ctx, "clientA", 1)
1851:+		t.Fatalf("Reserve: %v", err)
1854:+		t.Error("a second concurrent Reserve for the SAME sub must be denied while the first reservation is still outstanding")
1858:+// TestInProcessTouchCounter_ConcurrentReservesNeverExceedCap fires real
1864:+func TestInProcessTouchCounter_ConcurrentReservesNeverExceedCap(t *testing.T) {
1879:+			ok, err := c.Reserve(ctx, "clientA", pageSize)
1881:+				t.Errorf("Reserve: %v", err)
1898:+// TestInProcessTouchCounter_SettleReleasesUnusedReservation covers the
1902:+func TestInProcessTouchCounter_SettleReleasesUnusedReservation(t *testing.T) {
1906:+	if _, err := c.Reserve(ctx, "clientA", 5); err != nil {
1907:+		t.Fatalf("Reserve: %v", err)
1911:+	if err := c.Settle(ctx, "clientA", []string{"r1", "r2"}, 5); err != nil {
1912:+		t.Fatalf("Settle: %v", err)
1916:+	ok, err := c.Reserve(ctx, "clientA", 3)
1918:+		t.Fatalf("Reserve: %v", err)
1921:+		t.Error("unused reservation budget must be released by Settle, not held forever")
1934:+	ok, err := c.Reserve(ctx, "clientA", 3) // reserving more than the cap is itself allowed once
1936:+		t.Fatalf("first Reserve: ok=%v err=%v, want true/nil", ok, err)
1938:+	if err := c.Settle(ctx, "clientA", []string{"r1", "r2", "r3"}, 3); err != nil {
1939:+		t.Fatalf("Settle: %v", err)
1943:+	allowed, err := c.Reserve(ctx, "clientA", 1)
1945:+		t.Fatalf("Reserve: %v", err)
1948:+		t.Error("a subsequent Reserve after crossing the cap must return false")
1958:+	if _, err := c.Reserve(ctx, "clientA", 1); err != nil {

{
  "file_path": "/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/be9da8kx0.txt",
  "offset": 700,
  "limit": 240
}

700	+		if req.Name == nil && req.Phone == nil && req.Region == nil && req.Country == nil {
701	+			writeBadRequest(w, "at least one search filter is required")
702	+			return
703	+		}
704	+
705	+		offset, err := decodeCursor(req.Cursor)
706	+		if err != nil {
707	+			writeBadRequest(w, "malformed cursor")
708	+			return
709	+		}
710	+
711	+		pageSize := req.PageSize
712	+		if pageSize <= 0 {
713	+			pageSize = defaultPageSize
714	+		}
715	+		if pageSize > maxPageSize {
716	+			// A bare/unconstrained request for more than this API's
717	+			// result cap is rejected outright, not truncated
718	+			// (handoff-03-auth.md v3) — checked here, before the query
719	+			// is built, mirroring the same rule for authorize() below.
720	+			writeBadRequest(w, "page_size exceeds the maximum of 50")
721	+			return
722	+		}
723	+
724	+		allow, err := d.RateLimiter.Allow(ctx, ac.Sub, ScopeSearch, searchRateLimit)
725	+		if err != nil {
726	+			writeInternalError(w, err)
727	+			return
728	+		}
729	+		if !allow {
730	+			d.audit(actx, AuditRateLimited, nil, "")
731	+			writeRateLimited(w)
732	+			return
733	+		}
734	+
735	+		// Reserve, not just check: this books pageSize's worth of budget
736	+		// against the window immediately, atomically with the capacity
737	+		// check, so a second concurrent request from the same sub sees
738	+		// this reservation and is correctly denied before either
739	+		// request's DAO call returns — closing a check-then-act race a
740	+		// separate Allowed()-then-RecordTouches() pair had, which could
741	+		// let N concurrent requests each add a full page's worth of
742	+		// touches before any of them recorded (Nolan Reyes, PR #26
743	+		// review). Every exit past this point must call Settle exactly
744	+		// once to release it.
745	+		reserved, err := d.TouchCounter.Reserve(ctx, ac.Sub, pageSize)
746	+		if err != nil {
747	+			writeInternalError(w, err)
748	+			return
749	+		}
750	+		if !reserved {
751	+			d.audit(actx, AuditCapExceeded, nil, "")
752	+			writeTouchCapExceeded(w)
753	+			return
754	+		}
755	+
756	+		// The object-level policy hook, per v3: called after scope
757	+		// validation (above) and request-shape validation (above), before
758	+		// the DAO call. ScopeSearch has no single target id.
759	+		allowed, err := d.Authz.Authorize(ctx, ac.Sub, ac.Scope, "")
760	+		if err != nil {
761	+			_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, pageSize)
762	+			writeInternalError(w, err)
763	+			return
764	+		}
765	+		if !allowed {
766	+			_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, pageSize)
767	+			d.audit(actx, AuditPolicyDenial, nil, "")
768	+			writeForbidden(w)
769	+			return
770	+		}
771	+
772	+		q := dao.ProfileQuery{
773	+			Name:    req.Name,
774	+			Phone:   req.Phone,
775	+			Region:  req.Region,
776	+			Country: req.Country,
777	+			Limit:   pageSize,
778	+			Offset:  offset,
779	+		}
780	+		results, total, err := d.Repo.Profiles().Search(ctx, q)
781	+		if err != nil {
782	+			_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, pageSize)
783	+			d.audit(actx, AuditRequestFailed, nil, "")
784	+			writeDAOError(w, err)
785	+			return
786	+		}
787	+
788	+		ids := make([]string, len(results))
789	+		masked := make([]SearchResultProfile, len(results))
790	+		for i, p := range results {
791	+			ids[i] = p.ID
792	+			masked[i] = toSearchResult(p)
793	+		}
794	+		if err := d.TouchCounter.Settle(ctx, ac.Sub, ids, pageSize); err != nil {
795	+			writeInternalError(w, err)
796	+			return
797	+		}
798	+
799	+		d.audit(actx, AuditSuccess, ids, "")
800	+		resp := searchResponse{Results: masked, Total: total}
801	+		if offset+len(results) < total {
802	+			resp.NextCursor = encodeCursor(offset + len(results))
803	+		}
804	+		writeJSON(w, http.StatusOK, resp)
805	+	}
806	+}
807	+
808	+// NewGetProfileHandler implements profile:read:own and profile:read:any
809	+// against the same handler — the two scopes differ in what Authorize()
810	+// checks (referral membership vs. a logged reason_code) and in whether
811	+// the cumulative touch cap applies at all. id is read from the request
812	+// path via r.PathValue("id") (Go 1.22+ ServeMux pattern, e.g.
813	+// "GET /profiles/{id}"); this handler is not yet registered on any real
814	+// route (refinement/LT-39.md's Acceptance outcome — deferred until S7's
815	+// auth middleware exists to protect it), so tests call it directly with
816	+// http.Request.SetPathValue.
817	+func NewGetProfileHandler(d Deps) http.HandlerFunc {
818	+	return func(w http.ResponseWriter, r *http.Request) {
819	+		ctx := r.Context()
820	+		ac, ok := AuthContextFromContext(ctx)
821	+		if !ok {
822	+			d.audit(auditCtx{ctx: ctx}, AuditAuthnFailure, nil, "")
823	+			writeUnauthorized(w)
824	+			return
825	+		}
826	+		actx := auditCtx{ctx: ctx, sub: ac.Sub, scope: ac.Scope}
827	+		if ac.Scope != ScopeReadOwn && ac.Scope != ScopeReadAny {
828	+			d.audit(actx, AuditScopeFailure, nil, "")
829	+			writeForbidden(w)
830	+			return
831	+		}
832	+
833	+		id := r.PathValue("id")
834	+		if strings.TrimSpace(id) == "" {
835	+			writeBadRequest(w, "id is required")
836	+			return
837	+		}
838	+
839	+		// reasonCode is validated here and logged with every audit event
840	+		// on this request (handoff-03-auth.md v3: "reason_code, when the
841	+		// scope is profile:read:any" is a required audit-log field).
842	+		// There is deliberately no other consumer of the value — no
843	+		// policy decision in this story reads it beyond validating its
844	+		// membership in the closed enum; threading it into Authorizer's
845	+		// signature is a follow-up story's job if a real policy
846	+		// implementation ever needs it for more than logging (Oren
847	+		// Castellan, PR #26 review).
848	+		var reasonCode ReasonCode
849	+		if ac.Scope == ScopeReadAny {
850	+			reasonCode = ReasonCode(r.URL.Query().Get("reason_code"))
851	+			if !reasonCode.Valid() {
852	+				writeBadRequest(w, "reason_code is required for profile:read:any and must be one of the closed enum values")
853	+				return
854	+			}
855	+		}
856	+
857	+		allow, err := d.RateLimiter.Allow(ctx, ac.Sub, ac.Scope, readRateLimit)
858	+		if err != nil {
859	+			writeInternalError(w, err)
860	+			return
861	+		}
862	+		if !allow {
863	+			d.audit(actx, AuditRateLimited, nil, reasonCode)
864	+			writeRateLimited(w)
865	+			return
866	+		}
867	+
868	+		// The cumulative cap applies to profile:search and
869	+		// profile:read:any (handoff-03-auth.md v3, verbatim) — not
870	+		// profile:read:own, which is bounded by the caller_referral
871	+		// relationship rather than an open id space, so it isn't the
872	+		// enumeration surface this control exists for. A valid, logged
873	+		// reason_code on read:any satisfies Authorize() below but does
874	+		// not exempt the caller from this cap — the exact regression v3
875	+		// fixed (an earlier wording made this counter a no-op for
876	+		// read:any, since that scope requires a reason_code on every call
877	+		// by design).
878	+		var reserved bool
879	+		if ac.Scope == ScopeReadAny {
880	+			reserved, err = d.TouchCounter.Reserve(ctx, ac.Sub, 1)
881	+			if err != nil {
882	+				writeInternalError(w, err)
883	+				return
884	+			}
885	+			if !reserved {
886	+				d.audit(actx, AuditCapExceeded, nil, reasonCode)
887	+				writeTouchCapExceeded(w)
888	+				return
889	+			}
890	+		}
891	+
892	+		allowed, err := d.Authz.Authorize(ctx, ac.Sub, ac.Scope, id)
893	+		if err != nil {
894	+			if reserved {
895	+				_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, 1)
896	+			}
897	+			writeInternalError(w, err)
898	+			return
899	+		}
900	+		if !allowed {
901	+			if reserved {
902	+				_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, 1)
903	+			}
904	+			d.audit(actx, AuditPolicyDenial, []string{id}, reasonCode)
905	+			writeForbidden(w)
906	+			return
907	+		}
908	+
909	+		p, err := d.Repo.Profiles().Get(ctx, id)
910	+		if err != nil {
911	+			if reserved {
912	+				_ = d.TouchCounter.Settle(ctx, ac.Sub, nil, 1)
913	+			}
914	+			d.audit(actx, AuditRequestFailed, []string{id}, reasonCode)
915	+			writeDAOError(w, err)
916	+			return
917	+		}
918	+
919	+		if reserved {
920	+			if err := d.TouchCounter.Settle(ctx, ac.Sub, []string{p.ID}, 1); err != nil {
921	+				writeInternalError(w, err)
922	+				return
923	+			}
924	+		}
925	+
926	+		d.audit(actx, AuditSuccess, []string{p.ID}, reasonCode)
927	+		writeJSON(w, http.StatusOK, toProfileResponse(p))
928	+	}
929	+}
930	+
931	+func writeJSON(w http.ResponseWriter, status int, body any) {
932	+	w.Header().Set("Content-Type", "application/json")
933	+	w.WriteHeader(status)
934	+	_ = json.NewEncoder(w).Encode(body)
935	+}
936	diff --git a/internal/api/handlers_test.go b/internal/api/handlers_test.go
937	new file mode 100644
938	index 0000000..ad568d8
939	--- /dev/null

{
  "file_path": "/Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/be9da8kx0.txt",
  "offset": 1858,
  "limit": 100
}

1858	+// TestInProcessTouchCounter_ConcurrentReservesNeverExceedCap fires real
1859	+// goroutines — not a sequential simulation — at the same sub, each
1860	+// reserving a full page's worth of budget, and asserts the total ever
1861	+// granted never exceeds the cap. This is the actual failure mode Nolan
1862	+// Reyes's review described: N concurrent requests each reading
1863	+// "allowed" before any of them recorded a touch. Run with -race.
1864	+func TestInProcessTouchCounter_ConcurrentReservesNeverExceedCap(t *testing.T) {
1865	+	const capLimit = 100
1866	+	const pageSize = 50
1867	+	const concurrentRequests = 20 // 20*50 = 1000, 10x the cap if the race isn't closed
1868	+
1869	+	c := NewInProcessTouchCounter(capLimit, 24*time.Hour)
1870	+	ctx := context.Background()
1871	+
1872	+	var wg sync.WaitGroup
1873	+	var mu sync.Mutex
1874	+	granted := 0
1875	+	for i := 0; i < concurrentRequests; i++ {
1876	+		wg.Add(1)
1877	+		go func() {
1878	+			defer wg.Done()
1879	+			ok, err := c.Reserve(ctx, "clientA", pageSize)
1880	+			if err != nil {
1881	+				t.Errorf("Reserve: %v", err)
1882	+				return
1883	+			}
1884	+			if ok {
1885	+				mu.Lock()
1886	+				granted++
1887	+				mu.Unlock()
1888	+			}
1889	+		}()
1890	+	}
1891	+	wg.Wait()
1892	+
1893	+	if granted*pageSize > capLimit {
1894	+		t.Errorf("granted %d reservations of size %d = %d total booked, want at most %d (the cap)", granted, pageSize, granted*pageSize, capLimit)
1895	+	}
1896	+}
1897	+
1898	+// TestInProcessTouchCounter_SettleReleasesUnusedReservation covers the
1899	+// common case: a page returns fewer distinct rows than its reserved
1900	+// page size, and the difference must be released, not permanently
1901	+// consumed.
1902	+func TestInProcessTouchCounter_SettleReleasesUnusedReservation(t *testing.T) {
1903	+	c := NewInProcessTouchCounter(5, 24*time.Hour)
1904	+	ctx := context.Background()
1905	+
1906	+	if _, err := c.Reserve(ctx, "clientA", 5); err != nil {
1907	+		t.Fatalf("Reserve: %v", err)
1908	+	}
1909	+	// Only 2 of the reserved 5 were actually touched (a short page, or a
1910	+	// denied/failed request settling with recordIDs=nil).
1911	+	if err := c.Settle(ctx, "clientA", []string{"r1", "r2"}, 5); err != nil {
1912	+		t.Fatalf("Settle: %v", err)
1913	+	}
1914	+	// The unused 3 must be released: a new request should be able to
1915	+	// reserve up to 3 more before hitting the cap of 5.
1916	+	ok, err := c.Reserve(ctx, "clientA", 3)
1917	+	if err != nil {
1918	+		t.Fatalf("Reserve: %v", err)
1919	+	}
1920	+	if !ok {
1921	+		t.Error("unused reservation budget must be released by Settle, not held forever")
1922	+	}
1923	+}
1924	+
1925	+// TestInProcessTouchCounter_HardDeniesAfterCrossingCap is
1926	+// handoff-03-auth.md v3's ruling: crossing the cap hard-denies further
1927	+// requests for the remainder of the window — the request that crosses
1928	+// the cap itself still completes (it already held a valid reservation),
1929	+// but the next one is denied.
1930	+func TestInProcessTouchCounter_HardDeniesAfterCrossingCap(t *testing.T) {
1931	+	c := NewInProcessTouchCounter(2, 24*time.Hour)
1932	+	ctx := context.Background()
1933	+
1934	+	ok, err := c.Reserve(ctx, "clientA", 3) // reserving more than the cap is itself allowed once
1935	+	if err != nil || !ok {
1936	+		t.Fatalf("first Reserve: ok=%v err=%v, want true/nil", ok, err)
1937	+	}
1938	+	if err := c.Settle(ctx, "clientA", []string{"r1", "r2", "r3"}, 3); err != nil {
1939	+		t.Fatalf("Settle: %v", err)
1940	+	}
1941	+	// This request's own 3 touches pushed the distinct count to 3, over
1942	+	// the cap of 2 — but it had already been allowed to proceed.
1943	+	allowed, err := c.Reserve(ctx, "clientA", 1)
1944	+	if err != nil {
1945	+		t.Fatalf("Reserve: %v", err)
1946	+	}
1947	+	if allowed {
1948	+		t.Error("a subsequent Reserve after crossing the cap must return false")
1949	+	}
1950	+}
1951	+
1952	+func TestInProcessTouchCounter_WindowResets(t *testing.T) {
1953	+	c := NewInProcessTouchCounter(1, time.Hour)
1954	+	fakeNow := time.Now()
1955	+	c.now = func() time.Time { return fakeNow }
1956	+	ctx := context.Background()
1957	+

{
  "command": "grep -n \"recover()\\|defer func\" /Users/warrenthompson/.claude/projects/-Users-warrenthompson-Source-LoginID-03-engineering-delivery/35c20edc-753d-4d96-b512-7114684706eb/tool-results/be9da8kx0.txt"
}

(Bash completed with no output)

{
  "command": "cd /Users/warrenthompson/Source/LoginID-worktrees 2>/dev/null; find / -maxdepth 6 -iname \"*loginid-takehome*\" -type d 2>/dev/null | head"
}

(Bash completed with no output)