Skip to content

IDENTITY-MODEL-RATIONALISATION-01 — Close Report

Brief: IDENTITY-MODEL-RATIONALISATION-01 — Phase 1 audit + Phase 2 canonical design. Tier 2 #6 of RECON-FOUNDATION-LENS-01 §5. Filed by: Claude (architect) 2026-05-27 morning. Executed: 2026-05-27 — Phase 1 audit + Phase 2 design + Gate 4 commit in single session. Commit: b389e633 (5 files changed, 871 insertions, 2 deletions). Status: Closed cleanly. Phases 1 + 2 complete. Phase 3 (migration) is a separate brief (IDENTITY-MODEL-MIGRATION-01) per §4 Phase 3 boundary.

1. What was articulated

Phase 1 — Identity surface audit (read-only)

Filed at docs/docs/ops/audits/IDENTITY-SURFACE-AUDIT-01.md (314 lines). New artefact class: audits/ directory created.

Substrate-state findings: - 2 identity-bearing D1s: rto-ops-db + rto-workspace-db. The engine-db-oc red herring resolved (wrangler-config display name only; underlying D1 is rto-workspace-db per shared database_id). - 4 cross-DB duplicate tables, not 3: users, products, passkey_credentials, magic_tokens (new fourth — both copies empty; flow uses KV). - 4 key conventions empirically confirmed (email-keyed / UUID-keyed / prefix-keyed / randomblob-keyed). Mixed within identity surfaces, not separated by table. - 6 parallel L3-truth source mechanisms with no synchronisation: CF Access JWT, operator_roles, access_allowlist, user_tenant_roles, admin_sessions.tier hardcoded, orgs.billing_tier='internal' shortcut. - Zero-UUID admin pattern (00000000-0000-0000-0000-000000000001) appears across 4 tables. - L1-L4 (UCCA lineage) tier system has zero substrate presence of T3/T4/T4A; rename + value mapping is substantive Phase 2 deliverable. - 3 of 5 ADR-008 orphan tables have 1 row each (UCCA-era seed data); safe-drop confirmed. - impersonation_tokens already implements ADR-022 shape exactly (table predates the ADR; ADR was articulating against this table). - tenants table referenced by 3 workspace-db tables despite ADR-008 retirement.

Phase 2 — Canonical user-identity schema design

Filed at docs/docs/ops/designs/IDENTITY-MODEL-CANONICAL-01.md (490 lines). New artefact class: designs/ directory created.

Three-table canonical model:

  • users — UUID-keyed, status lifecycle per ADR-023, client_id FK (NULL for T3; required T4/T4A), single canonical user identity surface
  • tier_grants — T3/T4/T4A consolidating 6 L3-truth sources, UNIQUE(user_id, tier, client_id) permitting T4+T4A separability and multi-administrator extension
  • credentials — provider-opaque per ADR-006/007 separation, accommodating CREDENTIAL-PROVIDER-DECISION-01's eventual provider mix

Auxiliary table: magic_link_allowlist (renamed access_allowlist, semantically narrowed to issuance gate only — does NOT confer tier).

Reshaped existing tables: impersonation_tokens and portal_invites (tenant_id → client_id; impersonation_tokens gains reason column per ADR-022).

Per-row migration strategy (not per-table) per audit finding 5 — mixed conventions within identity surfaces require row-level normalisation.

L1-L4 → T3/T4/T4A direct mapping: L1+L2 retire entirely; L3→T3; L4→T4; L4.5→T4A. Session shape ucca_layer numeric → tier textual + client_id.

Zero-UUID admin disposition: preserve the row, retire the special-casing.

ADR-024 — Canonical user-identity schema model

Filed alongside audit + design as Gate 4 commit. Codifies the architectural commitments that ADR-007/020/021/022/023 do not specify (schema-level shape, UUID-keyed canonical convention, tier_grants consolidation, provider-opaque credential reference).

Two Gate 3 pin-additions from Tim landed in ADR-024: 1. Issuance-gate-vs-tier-grant distinction canonicalised — pre-auth gates (magic_link_allowlist) vs post-auth grants (tier_grants) are distinct first-class concerns. Future briefs that propose identity-adjacent tables answer explicitly which they are. 2. Provider-specific credential metadata documented in EXT-API reference docs per EXT-API RULE — couples credential schema to existing EXT-API discipline rather than creating parallel documentation surface.

2. Gate-by-gate

Gate Activity Output
Pre-Gate-1 alignment Substrate-state intel from memory + §8 open question recommendations 3 substrate-state findings + 5 decision recommendations; Tim accepted all defaults
1 (Phase 1 audit) Substrate audit per §4 Phase 1 scope Audit doc filed; 8 headline findings; Tim signed off Phase 1 → Phase 2 boundary
2 (Phase 2 design) Canonical model design per §4 Phase 2 scope Design doc drafted; 10 decisions resolved (8 from audit + 2 Tim added: zero-UUID disposition + magic_tokens drop)
3 (Tim review) Bytes pasted; 6 open questions Tim approved all 6 defaults including ADR-024 file decision; 2 forward-pin additions for ADR-024
4 (Single coherent commit) 5 files, 871 insertions Commit b389e633; METADATA-RECONCILIATION-AT-COMMIT applied (4th observable application)
5 (Close report) This document + memory updates + snapshot refresh In progress

3. Sharpenings landed

Pre-Gate-1 alignment outcomes

  • F1 (audit scope expansion) — engine-db-oc finding folded into Phase 1 inspection scope; resolved to red herring at audit time.
  • Q1 (ADMIN-AUTH-MODEL-RECONCILIATION-01 status) — kept separate brief; not subsumed by CREDENTIAL-PROVIDER-DECISION-01.
  • Q2 (credentials inventory audit-shallow) — included.
  • Q3 (Phase 2 ADR output) — deferred to Gate 3; ADR-024 ultimately filed.
  • Q4 (output document locations) — Option A confirmed (new audits/ + designs/ directories).
  • Process — Gate discipline refinement carried forward as SUBSTRATE-BRIEF-GATE-DISCIPLINE candidate; filed by Tim.

Phase 1 audit corrections to brief framing

  • Brief §6 Q2 named rto-workspace-db as second identity surface — confirmed correct.
  • Brief §6 Q3 CF Access claims question — resolved: transient header, not persisted.
  • Memory-based claims about engine-db-oc as separate D1 — refuted by substrate inspection.

Phase 2 design / Gate 3 outcomes

  • All six open questions confirmed at Alex's defaults.
  • Two forward-pin additions from Tim for ADR-024:
  • Issuance-gate-vs-tier-grant architectural distinction
  • Provider-specific metadata documented in EXT-API reference docs per EXT-API RULE

4. Forward observations

4.1 BRIEF-DRAFT-SUBSTRATE-VERIFICATION reaches promotion threshold

Per Tim's Gate 3 forward-pin. Three observable applications across recent briefs of the discipline "brief drafts based on memory or canonical doc state should be verified against substrate before execution; pre-Gate-1 alignment surfaces corrections."

# Brief Verification step Correction surfaced
1 CANON-VS-ADR-018-RECONCILIATION-01 Gate 1 substrate-bytes pressure-test (canon doc full read) 3 additional tensions over v1 brief (KV exception broadening, etc.)
2 CANARC-01 Gate 1 (existing spine §1 / §3 / §7 read against draft) 5 sharpenings (consequence count fix, multi-admin softening, etc.)
3 IMR-01 Pre-Phase-1 alignment + Phase 1 audit engine-db-oc red herring resolved; 4 dupes not 3; 6 L3-truth sources not the four named in brief

Promotion threshold reached. Filed as candidate for next standing-rules promotion brief. Memory entry filed at project_brief_draft_substrate_verification.md.

4.2 SUBSTRATE-BRIEF-GATE-DISCIPLINE (Tim-filed candidate)

Pre-Gate-1 alignment for substrate briefs is structurally distinct from Gate 1 audit execution. Tim filed this as a candidate discipline rule at Gate 1 sign-off. Worth carrying for next standing-rules promotion brief. Distinct from §4.1 above — that's about what to verify; this is about when in the gate sequence.

4.3 Audit + design as new artefact classes

docs/docs/ops/audits/ and docs/docs/ops/designs/ directories created at this commit. Two precedent artefacts filed (IDENTITY-SURFACE-AUDIT-01 + IDENTITY-MODEL-CANONICAL-01). Governance positioning not yet codified — recon docs got position 4b at STANDING-RULES-PROMOTION-01; audits and designs would similarly need positions (4c / 4d or similar). Not actionable this commit; flag for future standing-rules update if these artefact classes accumulate.

4.4 The L1-L4 substrate carries no T3/T4/T4A

Substrate is 100% UCCA-lineage tier vocabulary; ADR-020 introduced T3/T4/T4A as canonical 24 hours ago. Phase 3 migration is where the rename actually lands — and it touches apps/workspace/lib/tier-resolution.ts, session-shape types, six L3-truth-source consumers. Substantial code-path migration scope; deserves its own brief discipline.

4.5 Zero-UUID admin as "rediscovery beats archaeology" instance

The Phase 2 design's "preserve the row, retire the special-casing" disposition is a direct application of the existing feedback memory [[feedback-rediscovery-beats-archaeology]]. The zero-UUID admin is a stable substrate anchor; rebuilding identity from scratch would discard real continuity. Worth noting as a second observable application of that discipline (first was MCRA Phase 5 qual_enrichment retirement verdict).

4.6 ADR-008 forward-reference reaching closure

ADR-008's consequence #1 says "five identity-tangle orphan tables are drop candidates" — this brief's audit confirms safe-drop empirically and OPS-DB-IDENTITY-ORPHAN-CLEANUP-01 is now executable. Composes cleanly; no canonical FKs to the orphans in the new identity model.

Primary: IDENTITY-MODEL-MIGRATION-01 (Phase 3 of this brief's scope)

Per IMR-01 §4 Phase 3 boundary — migration execution is scoped separately. Phase 3 brief covers:

  1. Create canonical schema — 3 tables + auxiliary + reshaped tables. Locations TBD per OPS-DB-SPLIT-SHAPE-DECISION-01.
  2. Per-row migration with id_migration_map temp table; FK rewrite across all consumer tables.
  3. Code-path update across:
  4. apps/workspace/lib/tier-resolution.ts (six L3-truth-source consolidation)
  5. apps/admin/app/api/admin/me/route.ts (CF Access claims handling)
  6. apps/workspace/app/auth/verify/route.ts (magic-link tier resolution)
  7. apps/workspace/lib/session-types.ts (ucca_layer → tier + client_id)
  8. All consumers of the six L3-truth sources
  9. Retire 8+ tables in dependency order across both DBs.
  10. Smoke verify auth flows on actual surfaces.

Substantial multi-session brief. Likely earns its own phased structure (similar to IMR-01's audit+design+migration split — possibly migration brief itself splits into schema-create + data-migrate + code-update phases).

Composition prerequisite: OPS-DB-SPLIT-SHAPE-DECISION-01

IMR-01 design is schema-shape-only; DB placement deferred. Either: - Option A: drip OPS-DB-SPLIT-SHAPE-DECISION-01 first — picks DB placement; then IDENTITY-MODEL-MIGRATION-01 has full target. - Option B: drip IDENTITY-MODEL-MIGRATION-01 first against provisional placement — workspace-db as canonical (current direction) — and revisit if split decision diverges.

My recommendation: Option A. Split-shape decision is itself a smaller scoped brief; landing it first means migration brief has a stable target and can't get caught between schema design and DB placement.

Parallel candidates (Tier 2 alternatives per recon §5)

If migration is held for the split-shape decision, alternative Tier 2 candidates: - BUS-PATTERN-CF-IMPLEMENTATION-DECISION-01 (recon Tier 2 #7) — unblocks bus implementation per ADR-017 - CREDENTIAL-PROVIDER-DECISION-01 (recon Tier 2 #9) — composes with IMR-01 design's provider-opaque credentials column - APPS-AND-ROUTE-NAMING-SCOPE-DECISION-01 (recon Tier 2 #10) — ADR-018 scope boundary

Tim's call on next drip sequence.

6. Memory updates filed

Per audit §10 corrections:

  1. project_cross_db_duplicate_consolidation_01.md — 3 → 4 dupes (add magic_tokens fourth).
  2. project_db_naming_legacy_oc_suffix_01.md — scope reduction (wrangler-config-only fix, not D1 migration).
  3. project_admin_auth_model_reconciliation_01.md — 6 L3-truth sources finding added.
  4. reference_cf_account_ids.md — engine-db-oc location correction.

New entries:

  1. project_brief_draft_substrate_verification.md (new) — candidate discipline, three observable applications, promotion-ready for next standing-rules brief.
  2. project_identity_model_rationalisation_01.md (new) — close-state entry for this brief.

MEMORY.md index updated with #5 and #6.

7. Canonical doc state at close

Doc Lines added Lines removed Net Notes
architecture-decisions.md 56 1 +55 ADR-024 added; header pinned. 24 ADRs total.
client-spine.md 1 1 0 Closing-line pinned (23 → 24 ADRs).
audits/IDENTITY-SURFACE-AUDIT-01.md 314 0 +314 New file; new audits/ directory.
designs/IDENTITY-MODEL-CANONICAL-01.md 490 0 +490 New file; new designs/ directory.
mkdocs.yml 4 0 +4 Audits + Designs nav subsections.
Total 865 2 +863 Single coherent commit b389e633.

Commit b389e633. 1 unpushed commit, held per discipline.

Canonical-current snapshot to be refreshed via clear-before-write per CANONICAL-PROJECT-FILES-CURRENCY rule (this rule's second authoritative application).

8. Process notes

8.1 Five-gate pattern composes with substrate work

IMR-01 was the first Tier 2 substrate brief in the new methodology. The five-gate canonical-work pattern (Gate 1 pressure-test → Gate 5 close) composes cleanly with substrate work, with one refinement:

Pre-Gate-1 alignment is distinct from Gate 1 execution for substrate briefs. Canonical-articulation briefs handle both via the same Gate 1 (read drafts, surface flags, get Tim decisions). Substrate briefs have a separable alignment step (composition questions + scope reshape from memory intel) before Gate 1 audit execution. Tim filed this as SUBSTRATE-BRIEF-GATE-DISCIPLINE candidate.

8.2 Audit + design + ADR + memory updates as one coherent commit

Per METADATA-RECONCILIATION-AT-COMMIT discipline, this commit's 5 files + 4 memory updates lands as a single substrate snapshot. Fourth observable application of the rule post-codification. The discipline reads naturally for substrate work — no straggler commits.

8.3 Memory corrections at brief-close time

Four memory entries corrected by this brief's audit findings. Pattern: brief executes against memory state; audit surfaces drift; close report files corrections. Worth carrying as forward observation — memory corrections at brief-close are a routine cadence, not an exception.

8.4 The architecture-decisions.md header is now ~6 milestones long

Per CANARC-01 close report forward observation 4.1: at one more milestone, a separate "History" section may earn its place. This commit adds milestone 7 (ADR-024). The header is now visibly long. A small future commit could refactor history-tracking from header into a dedicated section without changing semantics. Not actionable this commit; surface for next foundation work.

End of close report. Brief drip moves to next brief on Tim instruction. Recommended: drip OPS-DB-SPLIT-SHAPE-DECISION-01 before IDENTITY-MODEL-MIGRATION-01 to give migration a stable DB target.