docs(rfc): rethink database architecture for Prisma 8

[rickylabs]

Summary

Ground-up NetScript database architecture for Prisma 8 / Prisma Next. This is deliberately not a version-bump RFC: it replaces the inherited database foundation with a clean-break, contract-first system optimized for application and agent DX.

The RFC supersedes #313's compatibility-first pilot. It preserves migration safety through an explicit migration guide, conformance tests, receipts, retained rollback artifacts, and a parallel rollout branch—not runtime compatibility shims.

Locked direction

• Three progressive DX layers over the same contract: an ergonomic app preset, composable NetScript factories, and direct Prisma Next primitives plus NetScript ports.
• Prisma's current model-first TypeScript defineContract is the native authoring foundation; NetScript does not mirror Prisma's model/field/relation/query vocabulary.
• One compiled database manifest is the runtime/control authority, with distinct plan, receipt, contribution, and lock artifacts.
• Source-native app inference by default; atomic generated declarations only at proven package/artifact boundaries.
• A single plugin extension bundle contributes authoring, runtime, control, and validation facets once, with canonical space/snapshot identity.
• Fail-closed Standard Schema validation for the bounded semantics the Prisma contract and contributed metadata can prove, exposed as runtime | json; unsupported operations fail at schema construction.
• Multi-schema, multi-space, and multi-database orchestration are first-class without flattening ownership.
• PostgreSQL-first Prisma Next adapter and a no-backward-compat migration. Other engines earn support through the same conformance contract.

Scope

• Canonical RFC: rfcs/0000-database-architecture.md
• Harness evidence: .llm/runs/docs-database-architecture-rfc--prisma-8-rfc/
• Related issue: epic: migrate NetScript DB layer to Prisma Next (Postgres-first pilot, deferred) #313
• This PR specifies the architecture and implementation gates; it does not implement the new packages.

Completed slices

• S0 — activate the harness run and publish the review surface
• S1 — re-baseline NetScript, Prisma 8 RC1/source/main, related gaps, competitors, and agent/DX surfaces
• S2 — lock D-01–D-47 and pass separate-session PLAN-EVAL cycle 2
• S3 — author and consolidate the canonical RFC
• S4 — disposition Qwen 3.8 Max and Grok 4.6 reviews; close TypeScript/API, JSR, and architecture findings
• S5 — pass the owner-directed fresh Fable 5 high final review/refinement

Review record

• PLAN-EVAL cycle 2: PASS
• Opus 5 high: evidence-complete draft, consolidation, and author/editor dispositions
• Qwen 3.8 Max focused review: PASS_WITH_CHANGES; all QF-01–QF-05 dispositioned
• Grok 4.6 high whole-RFC adversarial review: PASS_WITH_REFINEMENTS; all GR-01–GR-08 dispositioned
• Root semantic closure: TypeScript/API PASS, prospective JSR PASS, architecture PASS at d28d8e779
• Final fresh Fable 5 high session 3517a6d2-b0b5-47ec-a207-b3533657a90c: PASS; one source-correct pgvector example refinement; gate cc90ead70
• Terminal harness closeout: 2e97c86e4

Validation

• deno fmt --check on the RFC, evaluator, and terminal run artifacts — PASS
• deno task docs:links — PASS (103 docs, 0 broken links, anchors, or orphans)
• git diff --check — PASS
• RFC code fences — PASS (40, balanced)
• Runtime/consumer implementation matrices are intentionally future implementation gates, not claims that the architecture has already shipped.

Owner review

This remains a draft for owner review. The harness and substantive evaluator gates are complete; no additional Claude/Fable session is planned. Do not merge until the owner accepts the final RFC.

Drift / debt

• epic: migrate NetScript DB layer to Prisma Next (Postgres-first pilot, deferred) #313's additive compatibility-first architecture is superseded by the owner-directed clean break.
• RFC length is not an acceptance criterion; clarity and complete decision coverage are.
• The final evaluator found no new, deepened, resolved, or unrecorded doctrine violation. Future implementation debt closure is not claimed by this docs-only RFC.

[rickylabs]

[PHASE: RESEARCH]

Harness run activated from current origin/main and the clean-break re-baseline is underway.

Evidence

• Bootstrap commit: 553290606450c9e4e5c3b566f975d1ad18cb9a02
• Run dir: .llm/runs/docs-database-architecture-rfc--prisma-8-rfc/
• Baseline: cd720529333328bcba5e1a308ce7632f4350efdf
• git diff --check — PASS
• targeted deno fmt --check over all six bootstrap artifacts — PASS
• epic: migrate NetScript DB layer to Prisma Next (Postgres-first pilot, deferred) #313 moved back to status:research, marked breaking, and linked to this re-architecture.

Research contract

The run will re-derive current NetScript DB reality and all Prisma-gap history; inspect Prisma 8 release/docs/source/open PRs/issues and agent surfaces; compare market architectures; then lock the NetScript contracts, DSL, ports/adapters, capability/contribution model, automation, multi-schema/multi-database semantics, tests, CI, migration, and rollout. The canonical RFC file remains blocked until separate-session PLAN-EVAL returns PASS.

Next

Complete the evidence corpus and Design checkpoint, then move the PR to status:plan-eval.

[rickylabs]

Research slice 9f1d0244a is now published.

Completed evidence packets:

• current NetScript database topology, generated pipeline, plugin contribution model, incident/history audit;
• Prisma 8 RC1 source/scorecard/control/runtime/contract-space/agent-surface audit, including current-main churn and open issue/PR ledger;
• eleven-product market analysis focused on ownership, multi-database composition, adapters, migrations, policy, CI, and agent DX.

Per owner direction, a fresh native Claude Code Opus 5 · high architecture lane is active (3f8a9a69-5589-4b91-9a32-91f7770fe7c2). It has an independent implementation-grade API/package/failure-mode brief and may use Claude Workflows/subagents. Its report is an input to plan lock, not the formal PLAN-EVAL. The canonical RFC remains intentionally unwritten until the independent report is incorporated and PLAN-EVAL passes.

[rickylabs]

[PHASE: IMPL]

Root RFC review checkpoint landed at ffd654fb0.

Scope

• Classified the 28,194-word canonical document as an evidence-complete raw draft, not the reader-facing RFC.
• Recorded REVISE_CONSOLIDATE with an 8,000–10,000-word target and 12,000-word hard ceiling.
• Locked ten must-fix API/correctness findings covering namespace capability, target inference, pure control boundaries, bindings, Standard Schema DX, plugin contribution, recovery, and adoption.
• Added the single-file Opus 5 high consolidation brief.

Validation

• Targeted deno fmt --check — PASS
• Full git diff --check — PASS
• Commit pushed to docs/database-architecture-rfc

Next

Fresh Opus 5 high consolidation → root sign-off → Qwen 3.8 Max focused review → Grok 4.6 high whole-RFC review → dispositions → final Fable 5 high refinement.

[rickylabs]

RFC review checkpoint — Qwen focused pass

Pushed be83301c6 (docs(rfc): record focused Qwen review). The canonical RFC remains frozen at 5dfc4e8eb / 11,205 words during review.

Qwen 3.8 Max (qwen/qwen3.8-max, effort max) returned PASS_WITH_CHANGES after reading the RFC, plan, root review, priority audits, and pinned Prisma RC1 source. It found five bounded issues:

• QF-01 high: the generated-binding example declares ambient symbols but consumes them as runtime values.
• QF-02 medium: extension-bundle authoring needs a precise home/import law so Prisma runtime/control facets do not leak past the adapter boundary.
• QF-03–QF-05 low: executable-example elisions, Prisma source-path attribution, and codec-parameter-versus-conversion-channel wording.

No D-01–D-47 decision, artifact/control invariant, validation boundary, migration/plugin safety rule, or upstream/market conclusion was rejected. Qwen also supplied an ≈1,240-word deletion ledger that projects ≈9,965 words while explicitly protecting the load-bearing API and safety contracts.

Next: Grok 4.6 high whole-RFC adversarial review, still read-only; then Opus author/editor dispositions and consolidation; then the single final Fable 5 high substantive refinement.

[rickylabs]

RFC review checkpoint — Grok whole-architecture pass

Pushed 84ff5f788 (docs(rfc): record Grok adversarial review). Grok 4.6 high (x-ai/grok-4.6, OpenRouter/OpenCode, variant high) reviewed the byte-identical RFC at 5dfc4e8eb, the plan, root review, and Qwen review in one read-only parent session.

Verdict: PASS_WITH_REFINEMENTS — 0 blockers, 8 refinements. Beyond confirming QF-01/QF-02, the most useful additions are:

• generated query/validator typing must remain per space; Prisma’s aggregate must never be presented as one merged AppContract;
• pure definition compilation must remain distinct from control execution;
• detach-and-retain needs a verify-only tombstone state, distinct from active adopted manage-forward ownership;
• space outcomes need an explicit target rollup before run-level partial-success;
• provider configuration and executable examples need one coherent symbol/value story.

Grok’s edit economics project a net reduction of roughly 1,040–1,200 words. The RFC remains frozen at 11,205 words pending the author/editor disposition pass.

Owner review has also raised a higher-level DX correction now being audited against NetScript’s existing Hono and frontend DAL/page-builder patterns: a three-level adoption surface (golden-path seam DSL → reusable factories → unrestricted native Prisma + NetScript primitives), without recreating Prisma’s schema/query DSL. The audit is also testing whether generated type bindings can be eliminated through source-native app-local inference; if not, emission must be automatic and invisible in the normal dev loop.

[rickylabs]

Database RFC semantic closure

The reviewed RFC and its resumable run state are now pushed:

• ad8effff9 — author/editor review dispositions and layered DX corrections.
• d28d8e779 — root semantic closure: executable extension value flow, canonical space/snapshot binding evidence, build-before-runtime loading, single compile/emit authority, branded field types, honest selection validation, static plugin aggregate transport, and durable retained rollback.
• 2510ab7d5 — closure receipt and final run-state bookkeeping.

Final read-only checks by the existing non-Claude TypeScript/API, prospective JSR, and architecture lanes all returned PASS. Per the latest owner direction, no further Claude/Fable route was launched and RFC length is not an acceptance gate.

Local verification passed: targeted deno fmt --check, deno task docs:links (103 docs; no broken links/anchors), git diff --check, and balanced Markdown fences. PR remains a draft for owner review; future package/runtime claims remain gated by the RFC implementation matrices.

[rickylabs]

IMPL-EVAL — final Fable 5 high evaluator/refinement gate

Field	Value
Route	Native Claude Code · claude-fable-5 · high · fresh one-shot session (owner-reinstated 2026-08-14; supersedes the earlier Claude/Fable freeze for exactly this gate)
Starting commit	a7a6887c2 (verified equal to the fetched remote tip before evaluation)
Gate commit	cc90ead70
Verdict	PASS — .llm/runs/docs-database-architecture-rfc--prisma-8-rfc/evaluate.md

What was checked

• Complete read of rfcs/0000-database-architecture.md at the starting commit, plus plan.md, plan-eval.md, worklog.md, context-pack.md, drift.md, the root/Qwen/Grok review receipts, and the three research audits (layered DX, TypeScript/oRPC, runtime validation).
• Independent re-verification of the load-bearing pinned RC1 claims against the local v8.0.0-rc.1 checkout (a76a6c5): exactly 138 export keys in @prisma/orm-postgres/package.json; TypeMapsPhantomKey at packages/2-sql/1-core/contract/src/types.ts:207; the namespace-flattening comment at contract-types.ts:644+; and every Step 1 helper spelling against examples/prisma-8-demo/prisma/contract.ts (field.id.uuidv4String(), field.temporal.createdAt(), type.pgvector.Vector(1536), rel.hasMany/rel.belongsTo coordinates — all exact).
• Eight-criteria evaluation (layered L1/L2/L3 DX, native Prisma authority, end-to-end type flow, single-registration plugin/extension fan-out, fail-closed bounded validation, manifest→plan→receipt authority, clean break with adoption safety, example completeness) — all PASS; details in evaluate.md.
• Spot-audit that QF-01–QF-05 and GR-01–GR-08 are genuinely closed in the current text.

Refinement applied (evaluator-owned, within D-01–D-47 / OWNER-DX-01)

Step 1's pgvector({ dimensions: 1536 }) implied an extension-level dimension option that pgvector cannot honor — dimension is a per-column type modifier, and the pinned demo registers the pack with no configuration. The call is now pgvector() (dimensions remain only in type.pgvector.Vector(1536)), and the Step 6 declaration takes options?. The Step 1 → Step 6 → validation-codec flow was reread after the edit; no cross-section contradiction.

Command evidence

• deno fmt --check over the RFC and all mutated run Markdown — PASS (post-edit)
• deno task docs:links — PASS (103 docs, 0 broken links/anchors)
• git diff --check — PASS; fence count 40, balanced
• git status clean; local HEAD cc90ead70 equals the pushed remote branch

Per the gate contract this PR stays draft; owner review decides RFC acceptance (W0). Package/runtime E2E is N/A for this docs-only gate and no implementation gate is claimed.