Phase 2 core infrastructure API guard feature system complete

Milestone: The architectural backbone is live. withApiGuard is implemented and tested. The feature registry exists. You could add any feature safely from here.

Learning payoff: Middleware patterns, centralized auth, feature flags, the "why" behind the architecture.

Completed: October 2026 — walkthrough in Phase 2 walkthrough

Gate: ✅ Met — Pre 2 foundation hardening complete was required before beginning the original Phase 2 tasks.

Phase 2 Exit Criteria: ✅ All met, re-proven on main in lesson 8. withApiGuard is implemented and the /api/health route correctly returns 401/403 in the right conditions. The feature system can enable/disable features per user.

• withApiGuard is implemented and tested: 14 unit tests and 5 integration tests in packages/core.
• /api/health returns 401 without a session and 200 with one, checked with curl -i and a signed-in browser.
• The 403 for a disabled feature is pinned by packages/core/tests/integration/guard.test.ts (responds 403 to a user who is not entitled to the feature). /api/health belongs to no feature, so it can't return 403 by design.
• pnpm ops:entitlements:grant --email <you> --all enables features per user. Disabling is a DELETE with the privileged role. ALL_FEATURES is still empty, so nothing is granted until Phase 4 registers Taxila.

Lessons

Phase 2 is built piece by piece, with Pratik learning as it goes (how we build). By default the coach hands over one small, explained piece at a time, and the two discuss it before it's final. Pratik writes the steps they call core themselves, and can ask the coach to code work with no learning payoff. Lessons run one at a time, in this order, each in its own thread. A lesson starts only after the previous lesson's PR is merged. The order starts with the smallest, self-contained work and builds up to the guard.

To start a lesson, open a new thread and paste this, changing the lesson number:

Coach me through Phase 2 lesson 1, piece by piece as contracts.md describes:
hand me one explained piece at a time, and I'll say which ones I write myself. Read AGENTS.md,
docs/04-plans/phase-2-core-infrastructure-api-guard-feature-system/contracts.md
and that lesson's brief (the plan's Lessons table links each one) before we start.

Every brief has the same parts: what gets built, the concepts, what the coach reads first, numbered steps, which steps are good to write yourself, questions to check understanding, and when the lesson is done. The coach builds from the target design in Phase 2 build rules and target design, which changes when Pratik's own design wins.

Close-out (lesson 8): the coach wrote Phase 2 walkthrough, marked this plan complete the way Pre-2 was closed, replaced the sketch in With API guard with the shipped behaviour, updated "Where things stand" in the agent guide, and recorded the phase's learnings in 09-notes/ (publish: false). The brief is Lesson 8: Phase 2 close-out.

Design decisions made while planning (details in Phase 2 build rules and target design; each can be revisited in its lesson):

• Bearer API keys resolve to no caller (401) until Phase 9 adds api_keys.
• getEnabledFeatures takes the guard's RLS transaction and returns feature keys, so packages/core stays feature-agnostic.
• Users can read their own entitlements but can't write any. Only the privileged role writes them.
• The guard checks scope before opening the transaction and checks the feature inside it.
• Lesson 1: features are identified by key (not slug), object shapes are interfaces, and rollout gating stays out of the registry (post-MVP, B5).
• Lesson 2: the caller variants are named interfaces with kind: 'key', and any Authorization header resolves to no caller, even alongside a valid session.
• Lesson 3: entitlements use a composite primary key (user_id, feature_key) with no surrogate id, user_id references profiles, and app_runtime can only SELECT them.
• After lesson 3: resolveApiCaller returns undefined, not null, for no caller (coding standard: prefer undefined).
• Lesson 4: handlers read caller.userId (no separate userId), feature stays optional and skips the entitlements query when unset, and the shared test helpers live in packages/core/tests/helpers/.
• Lesson 5: one place logs (withApiGuard); the checks live in authorizeAndHandle, which returns a response or a denial. api.denied logs the client's code, every event carries userId (null without a caller), and error logs drop Drizzle's query parameters.
• /api/health requires a session but no feature. The 403 path is proven by lesson 4's integration test.
• Lesson 6: /api/health returns { status: 'ok' }, and the database client is created on first use (getUnsafeDb()), because next build imports every route module and CI's build has no DATABASE_URL.
• Lesson 7: the seed is entitlements grant in a dedicated packages/ops package for privileged scripts, which nothing may import. It runs under tsx with dotenv-cli, writes only with --apply, and --apply is one INSERT … ON CONFLICT DO NOTHING RETURNING.

Implementation notes:

• Task 2.10 shipped as a package, not a registry script. packages/ops holds privileged scripts (dev seeds, provisioning, break-glass), runs them as the postgres role through withPrivilegedDb, and nothing may import it. The dependency direction gained a side branch, ops → registry, foundation (contracts).
• The guard's order changed from the planning sketch. The scope check runs before the transaction and the feature check inside it, so a rejected key never takes a pooled connection and entitlements are read under RLS. With API guard now describes the shipped order.
• Tasks 2.4 and 2.5 already cover Phase 10's 10.1 and 10.2 (request and auth-failure logging inside withApiGuard), and the guard's errors already use 10.5's { error, code } shape. Phase 10 still owns the shape for handler errors.
• Late fixes landed as post notes in earlier walkthroughs: the Data API roles (Phase 1.1 and Pre-2, sidekick#17), the lazy database client (Pre-2, sidekick#21), the ops boundaries element (Pre-2, sidekick#23) and pnpm build approvals (Phase 0, sidekick#14). The walkthrough lists them.
• Added beyond the original list: a startup check for required variables (apps/web/src/instrumentation.ts, sidekick#22), shared test helpers in packages/core/tests/helpers/ (sidekick#18), and the interface lint rule (sidekick#10).

Carried forward, not built in Phase 2:

• ops follow-ups: a revoke command, a pnpm ops <noun> <verb> dispatcher with the second command, and a --target check once a second environment exists (B6).
• CLI design belongs to Phase 9's apps/cli, which calls the API with a key. ops logic moves into admin endpoints when a command is retired; only its interface carries over (Phase 9 API keys CLI).
• A public liveness probe would be a recorded exception to require-api-guard, decided by Pratik (B7).
• getClaims() instead of getUser() is the known latency lever, at the cost of revoked sessions working until their token expires (B8).