IDENTITY-MODEL-PLACEMENT-DECISION-01 — Close Report¶

Brief: IDENTITY-MODEL-PLACEMENT-DECISION-01 (renamed from OPS-DB-SPLIT-SHAPE-DECISION-01 at pre-Gate-1 per F1 sharpening). Tier 2 #8 of RECON-FOUNDATION-LENS-01 §5 (scope narrowed to identity placement only). Filed by: Claude (architect) 2026-05-27. Executed: 2026-05-27 — single session, pre-Gate-1 + Phase 1 + Phase 2 decision + Gate 3 ADR draft + Gate 4 commit. Commit: 4dabb86b (4 files, 401 insertions, 2 deletions). Status: Closed cleanly. Identity placement decided: Option C — new rto-identity-db.

1. What was decided¶

Identity tables live in a new dedicated database: rto-identity-db (with rto-identity-db-staging twin per Peel taxonomy).

The three ADR-024 core tables (users, tier_grants, credentials), plus auxiliary magic_link_allowlist, plus reshaped impersonation_tokens + portal_invites, all live in the new identity-db. internal-api gains IDENTITY_DB binding and hosts identity-read endpoints; customer-facing workers route reads via the existing INTERNAL_API service-binding (MANDARIN-compliant).

Reasoning (Tim's Phase 2 decision)¶

Marginal cost over Option B is ~1 hour against asymmetric reversibility (C→B later costs DB bloat only; B→C later costs full re-migration ~3-4 days)
Name-matches-shape principle fully honoured (D1 names immutable; shortcuts compound)
Composes cleanly with future broader ops-db split regardless of shape
Forward-positions for InstaLearn credential issuance, federation per spine §7, eventual RTO SSO — all argue for identity-as-first-class-subsystem

Codified at ADR-025¶

Full ADR text at docs/docs/ops/architecture-decisions.md (lines added at this commit). Two additions folded in at Gate 3 review per Tim's verdict: CF Access posture pinned explicitly; methodology observations paragraph capturing BRIEF-DRAFT-SUBSTRATE-VERIFICATION's fourth application + MIGRATION-COMPLETION-DISCIPLINE making retirement explicit.

2. Gate-by-gate¶

Gate	Activity	Output
Pre-Gate-1 alignment	Substrate-bytes pressure-test on brief draft	6 findings: F1 rename brief; F2 MANDARIN reframing; F3 cross-product matrix; F4-F6 clarifications; 5 §9 question recommendations
1 (Phase 1 audit + option analysis)	3-option analysis against substrate state	Decision analysis doc filed at `ops/decisions/IDENTITY-MODEL-PLACEMENT-ANALYSIS-01.md` (353 lines); new `decisions/` artefact class created
Pre-Phase-2 substrate scan (Tim-requested)	Concrete numbers for B-vs-C: code-paths, latency, LOC, provisioning effort	Substrate scan corrected initial Option C cost framing: "~1 hour marginal" vs initial "substantially heavier"
2 (Decision)	Tim picks Option C	Decision lands with explicit reasoning
3 (ADR-025 draft + review)	ADR drafted; Tim approves with 2 additions	CF Access posture + methodology observations folded in
4 (Single coherent commit)	4 files; METADATA-RECONCILIATION-AT-COMMIT 5th application	Commit `4dabb86b`
5 (Close report)	This document	+ memory updates + snapshot refresh

3. Sharpenings landed¶

Pre-Gate-1 outcomes (per F1-F6)¶

F1 — Brief renamed from OPS-DB-SPLIT-SHAPE-DECISION-01 to IDENTITY-MODEL-PLACEMENT-DECISION-01. Scope honesty: brief delivers identity placement, not broader ops-db split. The broader split decision remains future-queued.
F2 — MANDARIN DATA TAXONOMY (not HARD SEPARATION RULE) is the load-bearing constraint. Customer-facing workers cannot read ops-db; this surfaces Option B's true code-path cost.
F3 — Cross-product matrix against OPS-DB-CONTENT-AUDIT-01's three shapes (A 4-cluster / B 2-DB / C 3-DB-narrative). Identified which combinations are coherent vs which force re-work.
F4 — Option A reframed as substrate-state-direction preservation (not "introducing operator identity to customer-facing DB").
F5 — Option C's federation advantage reduced to "slightly cleaner integration boundary" — ADR-024's opaque provider column handles federation at schema level regardless.
F6 — Option C code-path cost surfaced as substantial (~12-15 worker files + new D1 + service-binding + observability) before substrate scan corrected this.

Substrate scan corrections (mid-Phase-1, pre-Phase-2)¶

18 identity-read sites across 10 distinct route files in customer-facing workers (concrete count via grep, not estimate)
INTERNAL_API service binding already configured in apps/site and apps/workspace wrangler configs (existing infrastructure)
internal-api has dispatch-by-pathname routing already; identity endpoints fit naturally
internal-api has identity-adjacent surface today (passkey.ts WebAuthn handling)
Service binding overhead is sub-millisecond (CF same-isolate-region)
Net Option C marginal cost over Option B: ~1 hour additional substrate work (D1 provisioning + schema), not "substantially heavier"

Gate 3 additions (Tim's Gate 3 verdict)¶

CF Access posture pinned explicitly in ADR-025 Consequences: no new policy needed per ADR-019 (enforcement at worker-domain layer, not D1 layer).
Methodology observations paragraph added to ADR-025: BRIEF-DRAFT-SUBSTRATE-VERIFICATION fourth application + MIGRATION-COMPLETION-DISCIPLINE making retirement explicit.

4. Forward observations¶

4.1 BRIEF-DRAFT-SUBSTRATE-VERIFICATION — fourth application within 36-hour window¶

Per Tim's pin. The substrate scan during pre-Phase-2 corrected initial architect-intuition on Option C's cost from "substantially heavier" to "~1 hour marginal." Without the discipline, this decision would likely have landed on Option B against an incorrect cost framing — paying ~3-4 days re-migration cost down the line if Shape C broader split eventually wanted.

Four observable applications within 36 hours: CANON-VS-ADR-018-RECONCILIATION-01, CANARC-01, IDENTITY-MODEL-RATIONALISATION-01, IDENTITY-MODEL-PLACEMENT-DECISION-01. Promotion threshold already reached at IMR-01 (third application); this fourth application strengthens the case. Substrate-scan beats architect-intuition on cost estimation — durable observation worth carrying into future briefs.

4.2 SUBSTRATE-NAME-MATCHES-SHAPE — candidate discipline filed¶

Surfaced during ADR-025 drafting; canonicalised by Tim. Substrate names should reflect substrate shape; shortcuts that defer name-alignment compound across migrations.

Two observable applications: 1. ADR-024 — schema canonicalisation via T3/T4/T4A tier vocabulary (L1-L4 UCCA-lineage retires; new tier names match the new tier model) 2. ADR-025 — placement decision via dedicated rto-identity-db (name matches the subsystem identity holds, instead of placing identity inside a workspace-named DB)

One application short of promotion threshold (3 applications). Carry forward in memory for accumulation. Filed at project_substrate_name_matches_shape.md.

4.3 MIGRATION-COMPLETION-DISCIPLINE — referenced in ADR-025¶

Per Tim's pre-Phase-2 pin. The IDENTITY-MODEL-MIGRATION-01 brief (next-brief recommendation) will include explicit Phase 4 retirement of superseded substrate per this discipline. Migration is not done when new substrate is in place; migration is done when old substrate is retired.

4.4 METADATA-RECONCILIATION-AT-COMMIT — fifth application post-codification¶

Continued discipline application. This commit's header pin reconciliation (architecture-decisions.md 24 → 25 ADRs; client-spine.md closing line 24 → 25) landed in the same commit as the ADR addition. Mkdocs nav extended (new Operations → Decisions subsection); new docs/docs/ops/decisions/ directory created.

4.5 The cross-product matrix surfaced unexpected forward-coupling¶

The Phase 1 analysis cross-product matrix (this brief's 3 options × OPS-DB-CONTENT-AUDIT-01's 3 shapes) surfaced that this brief's placement decision partially constrains the broader split shape. The brief's original framing didn't capture this; the cross-product made it explicit. Worth carrying as analysis-pattern observation — when a decision-only brief operates against a queued downstream decision, surface the constraint cross-product up-front.

5. Recommended next brief drip¶

Primary: IDENTITY-MODEL-MIGRATION-01¶

Phase 3 of IDENTITY-MODEL-RATIONALISATION-01. Unblocked by this commit. Target: rto-identity-db.

Migration brief structure (per MIGRATION-COMPLETION-DISCIPLINE):

Phase 1: Schema creation + binding wiring — provision rto-identity-db + -staging twin; apply ADR-024 schema; add IDENTITY_DB binding to internal-api; add staging binding
Phase 2: Per-row migration with id_migration_map — consolidate users + tier_grants assembly + credentials migration; preserve zero-UUID admin per ADR-024 disposition
Phase 3: Code-path update — 18 caller-side conversions (apps/site + apps/workspace + workers/prelaunch); ~6-10 new internal-api endpoints; session-shape update (ucca_layer → tier + client_id)
Phase 4: Explicit retirement — drop 8+ superseded tables in dependency order (operator_roles, user_tenant_roles, admin_sessions, tenants, ops-db users + workspace-db users vestigial sides, both magic_tokens, both passkey_credentials originals)
Phase 5: Verification — confirm zero remaining references via grep + schema inspection + worker config audit; close report includes "all superseded substrate retired" attestation

Substantial brief. Likely earns its own phased structure with gate discipline per phase. Tim's call on scope and timing.

Parallel candidates (Tier 2 alternatives if migration is held)¶

OPS-DB-IDENTITY-ORPHAN-CLEANUP-01 — 5 orphan table drops; can run independently or fold into IDENTITY-MODEL-MIGRATION-01 Phase 4
CROSS-DB-DUPLICATE-PRODUCTS-01 — out of identity scope; drop ops-db.products; standalone tiny brief
CROSS-DB-DUPLICATE-MAGIC-TOKENS-01 — drop both copies; standalone tiny brief OR fold into migration Phase 4

The orphan + cross-DB-duplicate work can drip as small fast-follow-on briefs after migration lands.

Standing-rules promotion brief¶

Three candidate disciplines now accumulated for next promotion: - BRIEF-DRAFT-SUBSTRATE-VERIFICATION (4 applications, well past threshold) - SUBSTRATE-BRIEF-GATE-DISCIPLINE (Tim-filed at IMR-01 sign-off) - MIGRATION-COMPLETION-DISCIPLINE (Tim-filed during IMPD-01) - SUBSTRATE-NAME-MATCHES-SHAPE (candidate, 2 applications — carry for accumulation)

When standing-rules promotion-02 brief drips, all four can land in one commit. Could compose with sub-rule formalising the four substrate-work artefact classes (audits / designs / recons / decisions — decisions/ was created at this commit).

6. Canonical doc state at close¶

Doc	Lines added	Lines removed	Net	Notes
`architecture-decisions.md`	46	1	+45	ADR-025 added; header pin (24 → 25 ADRs); methodology observations paragraph
`client-spine.md`	1	1	0	Closing-line pin (24 → 25 ADRs)
`decisions/IDENTITY-MODEL-PLACEMENT-ANALYSIS-01.md`	353	0	+353	New file; new `decisions/` directory
`mkdocs.yml`	2	0	+2	New Operations → Decisions subsection
Total	402	2	+400	Single coherent commit `4dabb86b`

ADRs total: 25 (was 24 at start of this brief).

Snapshot refresh follows per CANONICAL-PROJECT-FILES-CURRENCY (third authoritative application of the rule post-codification).

7. Process notes¶

7.1 Decision-only briefs compose with the five-gate pattern¶

IMPD-01 was the first decision-only Tier 2 brief in the methodology (prior Tier 2 brief IMR-01 was audit+design). The gate discipline composed cleanly with one variation: Phase 1 produced a decision-analysis document instead of a design document; Phase 2 was Tim's decision (not a drafting activity); Phase 3 was the ADR draft. Same five-gate shape, different artefact mix.

7.2 Substrate scan as mid-phase pivot¶

Tim's mid-Phase-1 pivot — requesting concrete numbers before Phase 2 — was load-bearing for the decision quality. Without it, the decision likely lands on Option B against an inflated Option C cost framing. The methodology should explicitly support mid-phase substrate scans as a Tim-pivot option, not just structured Gate 1 substrate-bytes pressure-tests. Worth observing.

7.3 Cross-product matrix as standard Phase 1 deliverable for decision briefs¶

The cross-product matrix (this brief's options × queued downstream decisions) surfaced forward-coupling that wasn't visible in the brief's option-by-option framing. Worth adopting as standard Phase 1 deliverable for decision briefs that operate against queued downstream decisions.

7.4 Brief drip discipline held¶

IMPD-01 was in flight from drip until Gate 5 close. Next brief drips on Tim instruction. One brief at a time held cleanly across the day's Tier 2 work.

End of close report. Brief drip moves to next brief on Tim instruction. Recommended: drip IDENTITY-MODEL-MIGRATION-01 (Phase 3 of IMR-01, now unblocked against rto-identity-db target).