ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain

• Status: Accepted (plan entity-kernel, 2026-10-23).
• Refines: ADR 0003, ADR 0011, ADR 0013
• Code: packages/ddx-contracts/src/{kernel,kernel-fields,kernel-access,attachments}.ts, packages/ddx-contracts/src/descriptors/*, ddx-api/src/kernel/**, ddx-web/src/lib/kernel/**, ddx-web/src/components/entity/**, scripts/check-entity-kernel.mjs
• Guide: entity-kernel.md

Context

• Project and Task each carried a hand-written controller, DTO, role list and web service. A new entity meant a copy of all of them.
• A list route could return a raw Prisma row, so a personal field (e-mail, tax id) could reach a role that must not see it.
• Access was ad-hoc role checks; a record grant (a patient reading one project) had no home.
• Audit rows were plain inserts. Nothing showed that a row had been removed or reordered.
• The MediaKind enum drift (task 006) showed the cost of a value that lives in two places: the watcher kept the old build, /health stayed 200, and the next restart failed typecheck.

Decision

• One descriptor per entity, written with defineEntity in @ddx/contracts/descriptors/<name>. It holds fields (18 kinds), lifecycle enums, projections, access (rbac, grants, owner, aclParent), capability flags and attachment types. ddx-api and ddx-web import it as a value at runtime (Node type stripping on the API side). A mirror is forbidden (EK6).
• One access seam. AccessPolicy decides every op. EntityAccessGuard runs after RolesGuard for RBAC. Record checks and list scope run before rows are read; an unreadable row answers 404.
• One projection seam. ProjectionService.project() is the only path from a stored row to a response. A pii field never appears in summary or public.
• One proof chain per stream. ProofChainService.append is the only writer of chained audit rows. Each row stores seq, prevHash, hash (sha256 over canonical JSON). The head moves under a compare-and-set on audit_stream_head; a lost race rolls back and retries, a stuck chain answers 503, never an unchained row. GET :id/audit/verify re-walks the stream.
• Descriptor-driven routes. EntityRouterModule.forEntities([{ descriptor, mapper }]) builds the CRUD, acl, audit, audit/verify and attachments routes with one controller factory. A descriptor entity has no hand-written controller or DTO.
• Events by name. Every mutation emits <entity>.created|updated|deleted|acl-changed|attached as an entity.changed SSE frame (ids only, no body). ddx-web invalidates by descriptor name.
• Attachments through ddx-api only. One registry (ATTACHMENT_TYPES) names source store, stored kind and bucket role; size and MIME come from MEDIA_LIMITS. The browser streams through the BFF (ADR 0011).
• One gate. ./ddx-manage.sh kernel (scripts/check-entity-kernel.mjs, codes EK0-EK8) runs inside ./ddx-manage.sh lint and in CI.

Consequences

• A new entity is a descriptor, a Prisma model, a mapper, a seed, kernel.json labels (4 locales) and registry lines (SSE_ENTITY_NAMES, forEntities(), WEB_DESCRIPTORS). Nothing else.
• Every descriptor edit reaches api and web in one change; drift is a typecheck or gate failure, not a runtime surprise.
• ddx-web still holds some per-entity code (route union in portal-registry.ts, legacy-key list in lib/kernel/registry.ts, project wizard). Task 029 lists them; they are follow-ups, not part of the decision.
• A chained stream serialises writers per record. Contention is bounded by the in-process queue plus the CAS; a second process may see a 503 retry.

Alternatives rejected

• Per-entity mirrors (a descriptor copy in api and web, as unified settings did with satisfies). Rejected: a mirror drifts; EK6 fails the build instead.
• Presigned media URLs for attachments. Rejected by ADR 0011: MinIO stays behind ddx-api, so the access check runs on every byte.
• Advisory locks (pg_advisory_xact_lock) for the audit chain. Rejected: a lock needs a connection pinned across the transaction, and a stale lock hides a forked chain. The unique (stream, seq) index plus the head CAS fails loudly instead.

Last reconciled: 2026-10-23 · working tree on 8ef2dc6

• ddx-documentation — dudoxx-web-boot

adr/

• ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides
• ADR 0002 — Auth: better-auth 1.7 in ddx-api
• ADR 0003 — Route shape: org slug, role, [entity]/[id], ?view=
• ADR 0004 — Database split: one Postgres 18 instance, six databases
• ADR 0005 — Frameworks and the approved dependency table
• ADR 0006 — API clients come from one factory
• ADR 0007 — Typed service container (DI / IoC)
• ADR 0008 — Singleton scope: what may live at module level
• ADR 0009 — One variant API for every inventory component
• ADR 0010 — Media path: presigned URLs from ddx-api after the org check
• ADR 0011 — Media proxy: MinIO only through ddx-api
• ADR 0012 — Density names: compact | cosy | large
• ADR 0013 — Platform super-admin acts as org-admin of the target org
• ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api
• ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain
• ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue
• ADR 0017 — Layered BFF: one route table, route classes, read models
• ADR 0018 — Cluster node registry, node identity, hot plug
• ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read
• Debug overlay

deploy/

• Deploy runbook — dudoxx-web-boot
• Entity kernel — guide
• Feature map — what each role can do
• Component inventory
• Naming constitution — dudoxx-web-boot
• Observability — one log layout, one key set
• Pattern reference — P1-P23 and groups A-K
• Port map — dudoxx-web-boot

research/

• RQ1 — Which release is "latest", and does it differ from the canon?
• RQ10 — SSE through the Next.js BFF route handler (desk half)
• RQ11 — Dev latency baseline: cold compile per route + next-server RSS
• RQ2 — Route group or dynamic org slug?
• RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix
• RQ4 — Separate databases or separate schemas?
• RQ5 — Which frameworks beyond shadcn earn a place?
• RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?
• RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?
• RQ8 — Media path: presigned URLs vs streaming through the BFF
• Template triage — create-nextjs code in ddx-web
• Settings — guide
• Local setup — dudoxx-web-boot
• Shell tree — SiteShell and PortalShell
• SSE event catalog
• Version pins — dudoxx-web-boot