R&D documentation

Entity kernel — guide

Source: ddx-documentation/entity-kernel.md

Previous: Deploy runbook — dudoxx-web-boot Next: Feature map — what each role can do Inventory gallery

One descriptor per entity drives the API routes, the access check, the response shape, the audit chain, the events, the attachments and the web views. Decision record: [ADR 0015](/en/docs/adr/0015-entity-kernel). Path-scoped rules: `.claude/rules/entity-kernel.md`. Binding rows: `context/_invariants.md` 27-30. Shipped descriptors (5): `user`, `organization`, `member`, `project`, `task` in `packages/ddx-contracts/src/descriptors/`. `MedicalVisit` and its children are **not** in the code; the recipe at the end is the worked plan for the next entity. ## Where the kernel lives | Layer | Path | Role | |---|---|---| | Contracts | `packages/ddx-contracts/src/{kernel,kernel-fields,kernel-access,attachments}.ts` | `defineEntity`, field catalog, access model, attachment registry | | Descriptors | `packages/ddx-contracts/src/descriptors/<name>.ts` | the one source per entity (subpath import, no barrel) | | API | `ddx-api/src/kernel/{access,projection,audit,events,attachments,router}/` | `AccessPolicyService`, `EntityAccessGuard`, `ProjectionService`, `ProofChainService`, `EntityRouterModule` | | Web | `ddx-web/src/lib/kernel/*`, `ddx-web/src/components/entity/*` | entity service, form spec, view modes, `EntityView`, `Entity*Panel` | | Gate | `scripts/check-entity-kernel.mjs`, `scripts/entity-kernel-exempt.json` | EK0-EK8 | ## Field catalog `FIELD_KINDS` (18). Every field carries `name`, optional `labelKey`, and the flags `required`, `readOnly`, `sortable`, `filterable`, `searchable`, `pii: true`, `writableBy`. | Kind | Value | Notes | |---|---|---| | `text`, `richText` | string · tiptap JSON | `max` on text; `format: 'tiptap-json'` on richText | | `number`, `money` | number · minor-unit integer | money names a `currencyField` | | `date`, `datetime`, `dateRange` | ISO string · `{start, end}` | dateRange names `startField` / `endField` columns | | `enum` | one of `values` | optional `lifecycle`: `initial` + `transitions` (from → to[]) | | `boolean`, `email`, `phone`, `url`, `address` | as named | `address` is the fixed `AddressSchema` | | `image`, `file`, `signature` | media id | never a URL; `attachmentType` names the registry row | | `relation` | id or id[] | `target`, `cardinality`, `inverse`, `through`, `readOnly` | | `computed` | read-only | `type` from `COMPUTED_TYPES`, `dependsOn` | `writableBy` takes `FIELD_WRITERS` = org roles, `super-admin`, `owner`. Reserved field names: `id`, `version`, `page`, `limit`, `sort`, `q`. List page size: default 20, max 100 (`LIST_LIMIT_*` in `kernel.ts`). ## Projections `BASE_PROJECTIONS` = `summary`, `detail`, `owner`, `admin`, `public`, plus `service:<name>` (for example `service:ai`). `summary` and `detail` are required. Each projection lists fields and an `audience` (`roles`, `owner`, `grantOps`). - A `pii` field is allowed only in `owner`, `admin` and `service:*` (`projectionAllowsPii`). EK2 enforces it. - `ProjectionService.project()` picks the projection by the caller's audience and answers `meta.projection`. The client never names a projection its audience lacks. - A patient with a read grant on a project gets `detail` (the project holds no pii field). ## Access model - **Ops** (`OPS`): `read`, `list`, `create`, `update`, `delete`, `share`, `attach`, `audit`. - **RBAC**: `access.rbac[role]` per `RBAC_ROLES` (org roles + `super-admin`). Enforced by `EntityAccessGuard` after `RolesGuard`. - **Owner**: `access.ownerField` names the owner column; `ownerOps` lists the ops the owner holds. - **Grants** (`acl`): `acl.enabled`, `grantable` ops, `principalTypes` (`user`, `role`, `service`). Stored as `access_grant` rows. - **Parent inheritance**: `access.aclParent = '<relation field>'`; a grant on the parent opens the child (`task` → `project`). - **Decision**: `resolveOps()` is pure and shared; `AccessPolicyService.assert` applies it to one record, `listScope` applies it to a list **before** rows are read. An unreadable row is 404, not 403. Rules decided in task 033 (security review): - `share` on project and task: org-admin and super-admin by RBAC, plus the project owner. The doctor role does **not** hold `share`. - `PUT :id/acl` stays **replace-all**. A `user` principal must be an active member of the org; a `role` principal must be in `ORG_ROLES`; otherwise 400. - The `acl` audit row stores `before` / `after` as `{grants: [{principalType, principalId, ops}]}`, sorted, ids only. - `task.assignee` and `task.project` are `writableBy` org-admin, super-admin, doctor. A `relation → user` value must be an active org member (400), on create and patch. `writableBy` also holds on POST. ## Capability flags `CAPABILITY_KEYS`: `audit`, `proofChain`, `acl`, `attachments`, `events`, `softDelete`, `search`. All default to `true`; a descriptor turns one off with `capabilities: { acl: false }`. Today `organization` and `member` set `acl: false`; `user` sets `acl: false` and keeps `proofChain`. EK7 warns when a flag is not boolean. ## Audit and proof chain `EntityAuditService` writes one audit row per mutation. With `proofChain` on, it goes through `ProofChainService.append` on stream `<orgId|platform>:<entity>:<recordId>` (the `user` entity uses `platform`). Row = `seq`, `prevHash`, `hash` = sha256 over canonical JSON; first `prevHash` is `GENESIS`. Head `audit_stream_head` moves by compare-and-set; `(stream, seq)` is unique. `GET :id/audit` lists rows; `GET :id/audit/verify` re-walks the chain and answers `ok` or `brokenAt`. ## Event catalog `ENTITY_EVENT_SUFFIXES`: `created`, `updated`, `deleted`, `acl-changed`, `attached`. Name = `<entity>.<suffix>`. The wire frame is `entity.changed` with `entity`, `entityId`, `change`, `version`, `orgId`, `ts` — ids only, no body, no audience. The entity name must be in `SSE_ENTITY_NAMES` (EK3). ddx-web invalidates the entity's query keys; server-rendered `EntityView` modes refresh through `EntityLiveRefresh`. ## Attachment registry `ATTACHMENT_TYPES` in `@ddx/contracts/attachments`. Size and MIME come from `MEDIA_LIMITS[storedKind]`; the registry never restates them. | Type | Source store | Stored kind | Bucket role | |---|---|---|---| | `avatar` | `auth.user_media` | `avatar` | `avatars` | | `signature` | `auth.user_media` | `signature` | `avatars` | | `logo` | `main.media_object` | `logo` | `images` | | `cover` | `main.media_object` | `image` | `images` | | `document` | `main.media_object` | `document` (reads `attachment`) | `images` | | `recording` | `main.media_object` | `audio` | `images` | A descriptor lists the types it accepts (`attachmentTypesOf(desc)`); the router serves `GET|POST :id/attachments` and `GET :id/attachments/:attachmentId/content` (Range → 206). A new store = one more `ATTACHMENT_SOURCES` value in the kernel plus one registry row. A Prisma `MediaKind` value lands in `MEDIA_KINDS` and `MEDIA_LIMITS` in the same change (EK8). ## Routes (per descriptor) `GET /orgs/{orgSlug}/<plural>` · `POST` · `GET|PATCH|DELETE …/{id}` · `GET …/{id}/audit` · `GET …/{id}/audit/verify` · `GET|PUT …/{id}/acl` · `GET|POST …/{id}/attachments` · `GET …/{id}/attachments/{attachmentId}/content` · child lists `GET|POST …/{id}/<child plural>`. Identity routes outside the factory: `/me/profile`, `/me/avatar`, `/me/signature`, `/orgs`, `/orgs/{orgSlug}/profile`, `/orgs/{orgSlug}/logo`, `/orgs/{orgSlug}/members`. Reference: [api/openapi.json](./api/openapi.json) (generated). ## View modes `ENTITY_VIEW_MODES` (`ddx-web/src/lib/kernel/view-modes.ts`): `table`, `cards`, `list`, `kanban`, `calendar`, `detail`, `form`, `wizard`, `print`, `export`. The mode lives in `?view=`. `kanban` is offered when the descriptor has a lifecycle enum; `calendar` when it has a date field; a value the descriptor does not offer falls back to the first offered mode. Components: `EntityView` plus `EntityAccessPanel`, `EntityAttachmentsPanel`, `EntityAuditPanel` (inventory family `@/inventory/entity`). Pattern: [P23](/en/docs/patterns). ## Conformance gate (EK0-EK8) `./ddx-manage.sh kernel` runs `node scripts/check-entity-kernel.mjs` (`--quiet-ok` hides clean output and EK7 warnings). It also runs inside `./ddx-manage.sh lint` and in `.github/workflows/entity-kernel.yml`. | Code | Check | |---|---| | EK0 | each descriptor module loads and exports exactly one descriptor | | EK1 | every Prisma model has a descriptor (`descriptorModels`) or an exemption row with a reason; stale or double rows fail | | EK2 | `summary` and `detail` exist; no `pii` field in `summary` or `public` | | EK3 | the descriptor name is in `SSE_ENTITY_NAMES` | | EK4 | every `labelKey` exists in `ddx-web/messages/{en,fr,de,es}/kernel.json` | | EK5 | registered in ddx-api (`forEntities` / `registry.register`) and in `WEB_DESCRIPTORS` | | EK6 | no descriptor mirror (`defineEntity(`, `satisfies EntityInput\|EntityDescriptor`) outside contracts; no re-declared lifecycle tuple, drifted `z.enum`, hand union of entity names or per-entity map | | EK7 | capability flags are booleans (warning only) | | EK8 | Prisma enum ↔ contract tuple parity (`enumParity` rows + the `<Entity><Field>` naming rule) | ## Add an entity — recipe (worked: MedicalVisit) The steps for any entity are exactly these: **descriptor · Prisma model · mapper · seed · `kernel.json` labels · registry lines** (`SSE_ENTITY_NAMES`, `forEntities()`, `WEB_DESCRIPTORS`). No controller, no DTO, no web service. Run `./ddx-manage.sh kernel` after. Proposed layout (design, not shipped). Databases follow [ADR 0004](/en/docs/adr/0004-database-split). | Entity | DB | `aclParent` | Attachment types | Notes | |---|---|---|---|---| | `MedicalVisit` | `main` | — | `document` | root; owner = treating doctor | | `MedicalVisitRecord` | `main` | `visit` | `document` | clinical notes; pii fields | | `MedicalVisitAppointment` | `main` | `visit` | — | `dateRange` field → calendar view | | `MedicalVisitGeneratedReport` | `main` | `visit` | `document` | report file; owner = generating user | | `MedicalVisitAiAssistantSession` | `ai` | `visit` | `recording` | needs one more `ATTACHMENT_SOURCES` value (the `ai` store) and one registry row | | `MedicalVisitOnlineRoom` | `communication` | `visit` | — | live room; `service:` projection not needed | Projections per audience (child entities repeat the pattern; `pii` fields only where marked): | Audience | Projection | Content | |---|---|---| | staff (doctor, nurse, receptionist) | `summary` | status, dates, patient display name | | doctor, owner | `detail` | adds record text, report link | | org-admin, super-admin | `admin` | every field | | patient with a read grant | `detail` | own visit; clinical `pii` fields only if the descriptor lists them for `owner` | | `service:ai` | `service:ai` | the minimal fields the AI session needs, set by `audience.roles`/service principal; the only non-human projection that may hold `pii` | Steps: 1. Descriptor `descriptors/medical-visit.ts` with `defineEntity`; children set `access.aclParent` to the relation field (see `descriptors/task.ts`). Export it from the contracts package `exports` map. 2. Prisma model in the DB named above; add a `descriptorModels` row in `scripts/entity-kernel-exempt.json` and `enumParity` rows for every enum (EK1, EK8). 3. Mapper (row ↔ record bag) and `forEntities([{ descriptor, mapper }])`. 4. Seed rows in `ddx-api/prisma/seed/`. 5. `kernel.json` labels in en, fr, de, es (`entity.<name>.fields.<field>`, enum `values`, `views.entities.<name>`). 6. Registry lines: `SSE_ENTITY_NAMES`, `WEB_DESCRIPTORS`. 7. Route tree under `portal/[orgSlug]/[role]/<plural>/**` composing `EntityView` (expected per entity; see the code review for the web sites that still need per-entity code). Last reconciled: 2026-10-23 · working tree on 8ef2dc6

All pages (45)

- [ddx-documentation — dudoxx-web-boot](/en/docs) **adr/** - [ADR 0001 — Scaffold route: dudoxx-sandbox-creator with 163XX overrides](/en/docs/adr/0001-scaffold-route) - [ADR 0002 — Auth: better-auth 1.7 in ddx-api](/en/docs/adr/0002-auth-better-auth) - [ADR 0003 — Route shape: org slug, role, `[entity]/[id]`, `?view=`](/en/docs/adr/0003-route-shape) - [ADR 0004 — Database split: one Postgres 18 instance, six databases](/en/docs/adr/0004-database-split) - [ADR 0005 — Frameworks and the approved dependency table](/en/docs/adr/0005-frameworks) - [ADR 0006 — API clients come from one factory](/en/docs/adr/0006-factory) - [ADR 0007 — Typed service container (DI / IoC)](/en/docs/adr/0007-di-container) - [ADR 0008 — Singleton scope: what may live at module level](/en/docs/adr/0008-singleton-scope) - [ADR 0009 — One variant API for every inventory component](/en/docs/adr/0009-variant-api) - [ADR 0010 — Media path: presigned URLs from ddx-api after the org check](/en/docs/adr/0010-media-path) - [ADR 0011 — Media proxy: MinIO only through ddx-api](/en/docs/adr/0011-media-proxy) - [ADR 0012 — Density names: compact | cosy | large](/en/docs/adr/0012-density-names) - [ADR 0013 — Platform super-admin acts as org-admin of the target org](/en/docs/adr/0013-super-admin-platform-role) - [ADR 0014 — Unified settings: one registry, three tiers, one resolve in ddx-api](/en/docs/adr/0014-unified-settings) - [ADR 0015 — Entity kernel: one descriptor, one access seam, one projection, one proof chain](/en/docs/adr/0015-entity-kernel) - [ADR 0016 — SSE Bus: Redis Streams log, Redis pub/sub fan-out, BullMQ outbound queue](/en/docs/adr/0016-sse-bus) - [ADR 0017 — Layered BFF: one route table, route classes, read models](/en/docs/adr/0017-bff-layered) - [ADR 0018 — Cluster node registry, node identity, hot plug](/en/docs/adr/0018-cluster-node-registry) - [ADR 0019 — Tenant branding: settings keys, vendored palettes, public platform read](/en/docs/adr/0019-tenant-branding) - [Debug overlay](/en/docs/debug-overlay) **deploy/** - [Deploy runbook — dudoxx-web-boot](/en/docs/deploy/README) - [**Entity kernel — guide**](/en/docs/entity-kernel) - [Feature map — what each role can do](/en/docs/features) - [Component inventory](/en/docs/inventory) - [Naming constitution — dudoxx-web-boot](/en/docs/naming-constitution) - [Observability — one log layout, one key set](/en/docs/observability) - [Pattern reference — P1-P23 and groups A-K](/en/docs/patterns) - [Port map — dudoxx-web-boot](/en/docs/ports) **research/** - [RQ1 — Which release is "latest", and does it differ from the canon?](/en/docs/research/rq1-versions) - [RQ10 — SSE through the Next.js BFF route handler (desk half)](/en/docs/research/rq10-sse-through-bff) - [RQ11 — Dev latency baseline: cold compile per route + next-server RSS](/en/docs/research/rq11-dev-latency) - [RQ2 — Route group or dynamic org slug?](/en/docs/research/rq2-route-shape) - [RQ3 — better-auth 1.7 vs Auth.js v5: feature matrix](/en/docs/research/rq3-auth-matrix) - [RQ4 — Separate databases or separate schemas?](/en/docs/research/rq4-db-split) - [RQ5 — Which frameworks beyond shadcn earn a place?](/en/docs/research/rq5-frameworks) - [RQ6 — How do DI, IoC and Singleton behave across RSC, client bundles and NestJS?](/en/docs/research/rq6-di-scope) - [RQ7 — Which data uses the server cache, which uses TanStack Query, how is each invalidated?](/en/docs/research/rq7-cache-classes) - [RQ8 — Media path: presigned URLs vs streaming through the BFF](/en/docs/research/rq8-media-path) - [Template triage — create-nextjs code in ddx-web](/en/docs/research/template-triage) - [Settings — guide](/en/docs/settings) - [Local setup — dudoxx-web-boot](/en/docs/setup) - [Shell tree — SiteShell and PortalShell](/en/docs/shell-tree) - [SSE event catalog](/en/docs/sse-events) - [Version pins — dudoxx-web-boot](/en/docs/versions)

Entity kernel — guide · R&D documentation | Dudoxx Web Boot

R&D documentation

Entity kernel — guide

Source: ddx-documentation/entity-kernel.md

Previous: Deploy runbook — dudoxx-web-boot Next: Feature map — what each role can do Inventory gallery

One descriptor per entity drives the API routes, the access check, the response shape, the audit chain, the events, the attachments and the web views. Decision record: . Path-scoped rules: .claude/rules/entity-kernel.md. Binding rows: context/_invariants.md 27-30.

Shipped descriptors (5): user, organization, member, project, task in packages/ddx-contracts/src/descriptors/. MedicalVisit and its children are not in the code; the recipe at the end is the worked plan for the next entity.

Where the kernel lives

Layer	Path	Role
Contracts	`packages/ddx-contracts/src/{kernel,kernel-fields,kernel-access,attachments}.ts`	`defineEntity`, field catalog, access model, attachment registry
Descriptors	`packages/ddx-contracts/src/descriptors/<name>.ts`	the one source per entity (subpath import, no barrel)
API	`ddx-api/src/kernel/{access,projection,audit,events,attachments,router}/`	`AccessPolicyService`, `EntityAccessGuard`, `ProjectionService`, `ProofChainService`, `EntityRouterModule`
Web	`ddx-web/src/lib/kernel/`, `ddx-web/src/components/entity/`	entity service, form spec, view modes, `EntityView`, `Entity*Panel`
Gate	`scripts/check-entity-kernel.mjs`, `scripts/entity-kernel-exempt.json`	EK0-EK8

Field catalog

FIELD_KINDS (18). Every field carries name, optional labelKey, and the flags required, readOnly, sortable, filterable, searchable, pii: true, writableBy.

Kind	Value	Notes
`text`, `richText`	string · tiptap JSON	`max` on text; `format: 'tiptap-json'` on richText
`number`, `money`	number · minor-unit integer	money names a `currencyField`
`date`, `datetime`, `dateRange`	ISO string · `{start, end}`	dateRange names `startField` / `endField` columns
`enum`	one of `values`	optional `lifecycle`: `initial` + `transitions` (from → to[])
`boolean`, `email`, `phone`, `url`, `address`	as named	`address` is the fixed `AddressSchema`
`image`, `file`, `signature`	media id	never a URL; `attachmentType` names the registry row
`relation`	id or id[]	`target`, `cardinality`, `inverse`, `through`, `readOnly`
`computed`	read-only	`type` from `COMPUTED_TYPES`, `dependsOn`

writableBy takes FIELD_WRITERS = org roles, super-admin, owner. Reserved field names: id, version, page, limit, sort, q. List page size: default 20, max 100 (LIST_LIMIT_* in kernel.ts).

Projections

BASE_PROJECTIONS = summary, detail, owner, admin, public, plus service:<name> (for example service:ai). summary and detail are required. Each projection lists fields and an audience (roles, owner, grantOps).

A pii field is allowed only in owner, admin and service:* (projectionAllowsPii). EK2 enforces it.
ProjectionService.project() picks the projection by the caller's audience and answers meta.projection. The client never names a projection its audience lacks.
A patient with a read grant on a project gets detail (the project holds no pii field).

Access model

Ops (OPS): read, list, create, update, delete, share, attach, audit.
RBAC: access.rbac[role] per RBAC_ROLES (org roles + super-admin). Enforced by EntityAccessGuard after RolesGuard.
Owner: access.ownerField names the owner column; ownerOps lists the ops the owner holds.
Grants (acl): acl.enabled, grantable ops, principalTypes (user, role, service). Stored as access_grant rows.
Parent inheritance: access.aclParent = '<relation field>'; a grant on the parent opens the child (task → project).
Decision: resolveOps() is pure and shared; AccessPolicyService.assert applies it to one record, listScope applies it to a list before rows are read. An unreadable row is 404, not 403.

Rules decided in task 033 (security review):

share on project and task: org-admin and super-admin by RBAC, plus the project owner. The doctor role does not hold share.
PUT :id/acl stays replace-all. A user principal must be an active member of the org; a role principal must be in ORG_ROLES; otherwise 400.
The acl audit row stores before / after as {grants: [{principalType, principalId, ops}]}, sorted, ids only.
task.assignee and task.project are writableBy org-admin, super-admin, doctor. A relation → user value must be an active org member (400), on create and patch. writableBy also holds on POST.

Capability flags

CAPABILITY_KEYS: audit, proofChain, acl, attachments, events, softDelete, search. All default to true; a descriptor turns one off with capabilities: { acl: false }. Today organization and member set acl: false; user sets acl: false and keeps proofChain. EK7 warns when a flag is not boolean.

Audit and proof chain

EntityAuditService writes one audit row per mutation. With proofChain on, it goes through ProofChainService.append on stream <orgId|platform>:<entity>:<recordId> (the user entity uses platform). Row = seq, prevHash, hash = sha256 over canonical JSON; first prevHash is GENESIS. Head audit_stream_head moves by compare-and-set; (stream, seq) is unique. GET :id/audit lists rows; GET :id/audit/verify re-walks the chain and answers ok or brokenAt.

Event catalog

ENTITY_EVENT_SUFFIXES: created, updated, deleted, acl-changed, attached. Name = <entity>.<suffix>. The wire frame is entity.changed with entity, entityId, change, version, orgId, ts — ids only, no body, no audience. The entity name must be in SSE_ENTITY_NAMES (EK3). ddx-web invalidates the entity's query keys; server-rendered EntityView modes refresh through EntityLiveRefresh.

Attachment registry

ATTACHMENT_TYPES in @ddx/contracts/attachments. Size and MIME come from MEDIA_LIMITS[storedKind]; the registry never restates them.

Type	Source store	Stored kind	Bucket role
`avatar`	`auth.user_media`	`avatar`	`avatars`
`signature`	`auth.user_media`	`signature`	`avatars`
`logo`	`main.media_object`	`logo`	`images`
`cover`	`main.media_object`	`image`	`images`
`document`	`main.media_object`	`document` (reads `attachment`)	`images`
`recording`	`main.media_object`	`audio`	`images`

A descriptor lists the types it accepts (attachmentTypesOf(desc)); the router serves GET|POST :id/attachments and GET :id/attachments/:attachmentId/content (Range → 206). A new store = one more ATTACHMENT_SOURCES value in the kernel plus one registry row. A Prisma MediaKind value lands in MEDIA_KINDS and MEDIA_LIMITS in the same change (EK8).

Routes (per descriptor)

GET /orgs/{orgSlug}/<plural> · POST · GET|PATCH|DELETE …/{id} · GET …/{id}/audit · GET …/{id}/audit/verify · GET|PUT …/{id}/acl · GET|POST …/{id}/attachments · GET …/{id}/attachments/{attachmentId}/content · child lists GET|POST …/{id}/<child plural>. Identity routes outside the factory: /me/profile, /me/avatar, /me/signature, /orgs, /orgs/{orgSlug}/profile, /orgs/{orgSlug}/logo, /orgs/{orgSlug}/members. Reference: (generated).

View modes

ENTITY_VIEW_MODES (ddx-web/src/lib/kernel/view-modes.ts): table, cards, list, kanban, calendar, detail, form, wizard, print, export. The mode lives in ?view=. kanban is offered when the descriptor has a lifecycle enum; calendar when it has a date field; a value the descriptor does not offer falls back to the first offered mode. Components: EntityView plus EntityAccessPanel, EntityAttachmentsPanel, EntityAuditPanel (inventory family @/inventory/entity). Pattern: .

Conformance gate (EK0-EK8)

./ddx-manage.sh kernel runs node scripts/check-entity-kernel.mjs (--quiet-ok hides clean output and EK7 warnings). It also runs inside ./ddx-manage.sh lint and in .github/workflows/entity-kernel.yml.

Code	Check
EK0	each descriptor module loads and exports exactly one descriptor
EK1	every Prisma model has a descriptor (`descriptorModels`) or an exemption row with a reason; stale or double rows fail
EK2	`summary` and `detail` exist; no `pii` field in `summary` or `public`
EK3	the descriptor name is in `SSE_ENTITY_NAMES`
EK4	every `labelKey` exists in `ddx-web/messages/{en,fr,de,es}/kernel.json`
EK5	registered in ddx-api (`forEntities` / `registry.register`) and in `WEB_DESCRIPTORS`
EK6	no descriptor mirror (`defineEntity(`, `satisfies EntityInput\|EntityDescriptor`) outside contracts; no re-declared lifecycle tuple, drifted `z.enum`, hand union of entity names or per-entity map
EK7	capability flags are booleans (warning only)
EK8	Prisma enum ↔ contract tuple parity (`enumParity` rows + the `<Entity><Field>` naming rule)

Add an entity — recipe (worked: MedicalVisit)

The steps for any entity are exactly these: descriptor · Prisma model · mapper · seed · kernel.json labels · registry lines (SSE_ENTITY_NAMES, forEntities(), WEB_DESCRIPTORS). No controller, no DTO, no web service. Run ./ddx-manage.sh kernel after.

Proposed layout (design, not shipped). Databases follow .

Entity	DB	`aclParent`	Attachment types	Notes
`MedicalVisit`	`main`	—	`document`	root; owner = treating doctor
`MedicalVisitRecord`	`main`	`visit`	`document`	clinical notes; pii fields
`MedicalVisitAppointment`	`main`	`visit`	—	`dateRange` field → calendar view
`MedicalVisitGeneratedReport`	`main`	`visit`	`document`	report file; owner = generating user
`MedicalVisitAiAssistantSession`	`ai`	`visit`	`recording`	needs one more `ATTACHMENT_SOURCES` value (the `ai` store) and one registry row
`MedicalVisitOnlineRoom`	`communication`	`visit`	—	live room; `service:` projection not needed

Projections per audience (child entities repeat the pattern; pii fields only where marked):

Audience	Projection	Content
staff (doctor, nurse, receptionist)	`summary`	status, dates, patient display name
doctor, owner	`detail`	adds record text, report link
org-admin, super-admin	`admin`	every field
patient with a read grant	`detail`	own visit; clinical `pii` fields only if the descriptor lists them for `owner`
`service:ai`	`service:ai`	the minimal fields the AI session needs, set by `audience.roles`/service principal; the only non-human projection that may hold `pii`

Steps:

Descriptor descriptors/medical-visit.ts with defineEntity; children set access.aclParent to the relation field (see descriptors/task.ts). Export it from the contracts package exports map.
Prisma model in the DB named above; add a descriptorModels row in scripts/entity-kernel-exempt.json and enumParity rows for every enum (EK1, EK8).
Mapper (row ↔ record bag) and forEntities([{ descriptor, mapper }]).
Seed rows in ddx-api/prisma/seed/.
kernel.json labels in en, fr, de, es (entity.<name>.fields.<field>, enum values, views.entities.<name>).
Registry lines: SSE_ENTITY_NAMES, WEB_DESCRIPTORS.
Route tree under portal/[orgSlug]/[role]/<plural>/** composing EntityView (expected per entity; see the code review for the web sites that still need per-entity code).

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