# Data Custody Contract — Pointer and Consent Schema (D14) Status: DRAFT — awaiting ratification (webui-audit S2, contract 7 of 9). Authority: PRD D14/D6 (Part I §7) — sensitive profile categories live in the **user's own brain ONLY**; PostgreSQL holds structural data, consent records, and pointers — never the content; "user data does not leak" is enforced by architecture, not policy. The Standalone split is a MAY with a recommended-default (kept for conversion forward-compatibility, D3). PRD D4 (Part I §6) — profile answers feed `USER.md` and/or the user's data store subject to the custody rule; connectors carry granular agentic-access consent. PRD D6 — estate brains hold operational records; only product-relevant material migrates into repository docs. Revision 2 (sol r1 findings F1–F6): the registry is now a full profile classifier that can represent non-sensitive rows, with an exact row shape, versioning, refusal semantics for unknown keys, and transition rules (F1); the consent model gains a concrete grantee reference model, an active-row uniqueness constraint, append-only re-grant semantics, and explicit mutation authority (F2); the pointer schema names its exact column set, binds the one-pointer rule to a database constraint, defines the `brain_ref` grammar and owner-bound resolution, replaces the unkeyed hash with a keyed construction, and bounds orphan repair (F3); the witnesses import the hierarchy contract's §6.2 column allowlist and §6.3-style closed route inventories, add negative controls and a column-type allowlist, and cover every binding rule (F4); the Standalone physical split, both valid layouts, the election record, and v1 phase timing are defined consistently with the wizard and mode-conversion contracts (F5); drafting additions are disclosed in §8 and the ruling request is one sentence with one decision (F6). This contract binds the profile-category registry (§2), the custody placement rule (§3), the pointer schema (§4), the consent schema and its evaluation (§5), mode application (§6), witnesses (§7), and disclosed drafting additions (§8). It defines schemas and placement; wizard step flow stays with contract 3 (`onboarding-wizard.md`), mode and conversion with contract 6 (`mode-conversion.md`), identity with `identity-lifecycle.md`, tool mapping with `tool-gateway-mapping.md`. ## 1. Definitions 1. **User brain**: the git-tracked per-user data store. Its two valid Standalone layouts are defined in §6.2; in Enterprise it is the user's own brain repository. 2. **Sensitive content**: any profile answer or derived text in a §2 category classified `sensitive`. 3. **Pointer**: a database record referencing sensitive content that lives in a user brain, carrying no content (§4). 4. **Grantee**: a non-subject principal that may be granted access to a user's sensitive content: an enrolled agent, a connector, or a platform feature (§5.2). 5. **Consent record**: a database record granting one grantee access to one category of one user's data (§5). 6. **Registry version**: the monotonically increasing integer identifying the active state of the §2 registry. 7. **Physical split** (Standalone): sensitive user content living in a per-user brain repository separate from the estate mosaic-brain, as opposed to the unsplit layout where it lives in a dedicated user-files subtree of the single mosaic-brain (§6.2). ## 2. Profile-category registry 1. **Model.** The registry is the single classifier for every profile category, closed and versioned, in the platform database. Table `profile_category_registry`, columns exactly: | Column | Type | Constraints | | ---------------- | ----------- | ---------------------------------------------------- | | `category_key` | text | primary key | | `classification` | text | NOT NULL, CHECK in (`sensitive`, `non-sensitive`) | | `since_version` | integer | NOT NULL (registry version that introduced this row) | | `created_at` | timestamptz | NOT NULL | The current registry version is a single integer held in `custody_config` (§6.3). Rows are added or reclassified ONLY by amendment to this contract shipped as a migration that bumps the registry version; no runtime write path may insert, update, or delete registry rows. 2. **Initial registry (version 1).** Drawn from the D4 profile step and D14's "disabilities, family, communication style, and similar": | Category key | Classification | Covers | | ------------------------- | -------------------------- | ------------------------------------------------------------------- | | `disabilities` | sensitive | disabilities including ADHD/autism/PDA/vision | | `family-social` | sensitive | family, pets, friends | | `communication-style` | sensitive | desired agent communication style, voice-matching interview product | | `personal-interests` | sensitive | hobbies, likes/dislikes | | `connector-content` | sensitive | email and drive content reached through user connectors | | `professional-background` | non-sensitive (per ruling) | professional background summary used for agent configuration | | `education` | non-sensitive (per ruling) | education summary used for agent configuration | The `Covers` column is contract documentation, not a database column. Account identity fields (email, name, credentials) are identity-contract data, not profile custody data, and have no registry row. 3. **Unknown category — refusal.** A profile write naming a `category_key` with no registry row is REFUSED with an explicit error. Nothing is stored anywhere, no registry row is auto-added (§2.1), and no pointer is created (so the §4.1 foreign key is never asked to reference a missing row). Fail-closed means refusal, not silent routing. 4. **Reclassification transitions.** A reclassification ships as a contract amendment plus migration that bumps the registry version. Non-sensitive → sensitive: the same migration moves every existing relational value for that category into its owning user's brain, creates the pointers, and deletes the relational values, all before the new version activates. Sensitive → non-sensitive: existing brain content and pointers remain valid and are never automatically materialized into the database; only writes evaluated after the new version activates route relationally. 5. **Unreadable registry — refusal.** If the registry or its version cannot be read at decision time, every routing and consent decision that depends on it is refused. There is no cached-default or assume-sensitive fallback that performs a write. ## 3. Custody placement rule 1. Sensitive content is written to the owning user's brain ONLY. PostgreSQL tables MUST NOT store sensitive content in any column — not as text, not as excerpts or previews, not as encodings, and not as embeddings or other derived representations that reconstruct content. 2. The database MAY hold, about sensitive content: the pointer records of §4, the consent records of §5, the registry of §2, and the custody configuration of §6.3. Nothing else. 3. Every write path for profile answers routes by the registry: `sensitive` → brain write + pointer upsert; `non-sensitive` → its declared platform table; unknown → refusal (§2.3). The routing decision is made server-side from the registry at its current version; a client-supplied classification or routing override is ignored. 4. D6 boundary: operational records stay in estate brains and are linked, not migrated. This contract governs user-profile custody only and creates no new obligation on estate brains. ## 4. Pointer schema 1. **Exact columns.** Table `profile_pointers`, columns exactly: | Column | Type | Constraints | | ---------------- | ----------- | ----------------------------------------------------------- | | `id` | uuid | primary key | | `user_id` | uuid | NOT NULL, FK → users(id) ON DELETE CASCADE | | `category_key` | text | NOT NULL, FK → profile_category_registry(category_key) | | `brain_ref` | text | NOT NULL, CHECK against the §4.3 grammar | | `content_hash` | text | NOT NULL (§4.4 construction) | | `created_at` | timestamptz | NOT NULL | | `updated_at` | timestamptz | NOT NULL | | `audit_event_id` | uuid | NOT NULL, FK → the platform audit log table (audit linkage) | plus the database constraint UNIQUE (`user_id`, `category_key`, `brain_ref`) — the one-pointer rule is a constraint, not a convention. 2. **Opacity.** `brain_ref` and every other pointer column MUST NOT embed content or content-derived text (no titles, snippets, or free-text descriptions). A locator is structural, not descriptive. 3. **`brain_ref` grammar and owner binding.** `brain_ref` is a normalized repository-relative POSIX path: one or more segments matching `[A-Za-z0-9][A-Za-z0-9._-]*`, joined by `/`, with no leading `/`, no empty segment, and no `.` or `..` segment; the stored form matches `^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$`. Resolution ALWAYS roots at the brain owned by the row's `user_id` (the resolver takes the owner from the row, never from the locator); the locator carries no repository, host, or user component, so a cross-user or traversal reference is unrepresentable, not merely forbidden. 4. **`content_hash` construction.** `content_hash` is `hmac-sha256:` — HMAC-SHA-256 over the canonical content bytes, keyed with a platform integrity key held in the secrets backend and never stored in the database or any repository. Because the key is external, the stored value is not an offline dictionary oracle for low-entropy answers. On read, a hash mismatch refuses the read and flags the pointer for §4.5 reconciliation. 5. **Bounded orphan repair.** Pointers are deleted when their content is deleted; dangling pointers are repaired toward deletion, never toward re-creating content in the database. Reconciliation for a user's pointers runs on two triggers: every profile write for that user, and a periodic sweep whose interval the implementing PR declares (at most daily). A pointer whose content is absent is deleted by the next triggered reconciliation — an orphan survives at most one cycle, and repair performs no database content write. ## 5. Consent schema and evaluation 1. **Exact columns.** Table `profile_consents`, columns exactly: | Column | Type | Constraints | | ---------------- | ----------- | --------------------------------------------------------------- | | `id` | uuid | primary key | | `user_id` | uuid | NOT NULL, FK → users(id) ON DELETE CASCADE (the data subject) | | `grantee_type` | text | NOT NULL, CHECK in (`agent`, `connector`, `feature`) | | `grantee_id` | text | NOT NULL (§5.2 per-type referential integrity) | | `category_key` | text | NOT NULL, FK → profile_category_registry(category_key) | | `state` | text | NOT NULL, CHECK in (`granted`, `revoked`) | | `granted_at` | timestamptz | NOT NULL | | `revoked_at` | timestamptz | CHECK ((state = 'granted') = (revoked_at IS NULL)) | | `actor` | text | NOT NULL (the authenticated principal that recorded the change) | | `audit_event_id` | uuid | NOT NULL, FK → the platform audit log table | plus the partial unique index UNIQUE (`user_id`, `grantee_type`, `grantee_id`, `category_key`) WHERE `state = 'granted'` — at most one active grant per (user, concrete grantee, category), as a database constraint. 2. **Grantee reference model.** A grantee is identified by the pair (`grantee_type`, `grantee_id`); its canonical display form is `:` (e.g. `agent:`). The discriminant set is closed at the three CHECK values. Referential integrity is per type: `agent` ids reference the enrolled-agent registry of `identity-lifecycle.md`; `connector` ids reference the platform connector registry; `feature` ids reference a closed feature-key list owned by amendments to this contract, and that list is EMPTY at version 1 (no feature grantee exists until an amendment names one). A grant to one agent confers nothing on another agent of the same type; the constraint key includes `grantee_id`, so two same-type grantees are distinct rows. 3. **Default deny.** Absence of an active `granted` row for (user, grantee, category) means no access. There are no implicit grants, no platform-admin bypass, and no mode in which default-deny is suspended. 4. **Mutation authority.** Only the authenticated data subject may create, grant, or revoke consent rows for their own data: the server enforces that `actor` is the subject's principal and equals the row's `user_id` before any consent mutation commits. A platform admin has no consent-mutation capability over another user's rows — an admin self-grant is refused at write time, closing the write-side route around §5.3. One system exception (disclosed, §8): when a grantee ceases to exist (e.g. agent retirement under `identity-lifecycle.md`), the platform auto-revokes its active rows, recording a system principal as `actor`. 5. **Revocation and re-grant.** Revocation flips exactly one active row to `revoked` and stamps `revoked_at`; it is effective for every access evaluated after the revoking write commits. Revoked rows are retained as history and never mutated again. A re-grant after revocation inserts a NEW row (append-only history) — repeated grant/revoke cycles are represented as successive rows, and the §5.1 partial unique index guarantees the old revoked rows cannot keep access live. 6. **Evaluation placement.** Access to sensitive content is mediated by the platform (Gateway/tooling) evaluating consent before any brain read on behalf of a grantee; the evaluation fails closed (`rbac-grant-model.md` §3.5 pattern), including when the consent state cannot be read (§2.5 pattern). The user reading their own data is not a grantee and needs no consent row. 7. Consent records govern agentic/feature access to user data. They are distinct from hierarchy grants (contract 2) and confer no platform authorization. ## 6. Mode application 1. The §2–§5 schemas are mode-independent: Standalone and Enterprise use the same tables and the same routing rule. 2. **Standalone layouts.** The D14 physical split remains a MAY. Its two valid layouts are: **split** — sensitive user content in a per-user brain repository separate from the estate mosaic-brain (the recommended default); **unsplit** — sensitive user content in the dedicated user-files subtree `users//` of the single mosaic-brain. §3 binds the logical user-brain region identically in both layouts; the layout election changes where the region lives, never whether routing applies. 3. **Election record.** The election lives in this contract's own one-row table `custody_config`, columns exactly: `id` (uuid, primary key), `standalone_layout` (text, NOT NULL, CHECK in (`split`, `unsplit`), default `split`), `registry_version` (integer, NOT NULL, §2.1), `elected_at` (timestamptz, NOT NULL), `actor` (text, NOT NULL), `audit_event_id` (uuid, NOT NULL, FK → the platform audit log table). It is written at bootstrap and amended only by an explicit operator action; contract 6's exact, immutable mode record is not touched or extended by this contract. 4. **Phase timing.** v1 ships the §2–§6 schemas and the D14 database boundary, and the wizard collects no sensitive category in v1 (contract 3 §3), so v1 contains no sensitive write surface. §3 binds every sensitive write path from the moment one exists — the first profile surface that accepts a sensitive category (P2/P3) activates routing, consistent with contract 6 §5's v1 slice (D14 database boundary only, custody mechanics outside v1). 5. **Conversion precondition.** An operator electing `unsplit` accepts conversion-time partitioning: `mode-conversion.md` §4.2 requires the per-user partition to exist before the Enterprise flip, so conversion from an unsplit install performs the partitioning first. 6. In Enterprise, the split is mandatory (D3 table); no-leakage between users is enforced by §3 placement plus §5 default-deny — there is no cross-user read path to sensitive content through the database, because the database has no content to serve. ## 7. Verification requirements Binding on the implementing PRs. Every witness below MUST name, in its implementation, the exact tables, columns, commands, and source roots it scans; "the custody tables" means `profile_category_registry`, `profile_pointers`, `profile_consents`, and `custody_config`. 1. **Column-allowlist witness** (hierarchy contract §6.2 style): the custody tables' live column sets are exactly §2.1/§4.1/§5.1/§6.3, and no platform table outside the declared non-sensitive profile tables carries profile answer content. 2. **Column-type allowlist witness:** the custody tables use only the column types named in §2.1/§4.1/§5.1/§6.3 (uuid, text, integer, timestamptz) — no bytea, json/jsonb, array, vector, or tsvector column exists in them, closing the encoded/derived-representation routes by type rather than by probe alone. 3. **Closed write-route witness** (hierarchy contract §6.3 style): a static, re-export-aware inventory over `apps/` and `packages/` (production code, tests excluded) enumerates every module that writes the custody tables or writes profile answers, and every enumerated route implements §3.3 registry routing; a route outside the enumeration fails the assertion. 4. **Closed brain-read witness** (same style): the inventory enumerates every production route that reads user-brain content on behalf of a grantee, and every enumerated route calls the §5.6 consent evaluation; a brain-read route outside the enumeration fails. 5. **Routing witness:** a sensitive-category answer submitted through the profile surface results in a brain write plus a pointer row and zero content bytes in the database; a non-sensitive answer lands in its declared table. The no-content probe is a negative control: the witness first plants the fixture text in a scratch column of a throwaway table to prove the probe detects it, then asserts its absence — as plaintext, base64, hex, and JSON-string encodings — across every column of the custody tables and declared profile tables. 6. **Registry witnesses:** (a) the version-1 registry state is exactly the seven §2.2 rows with their classifications; (b) a `professional-background` answer routes relationally (or per the ruling's alternative); (c) an unknown `category_key` is refused with nothing stored (§2.3); (d) with the registry unreadable, the write is refused (§2.5); (e) a runtime insert/update/delete against `profile_category_registry` outside a migration is refused (§2.1); (f) a reclassification migration (non-sensitive → sensitive) on seeded data moves the values to brains, creates pointers, and leaves zero relational values (§2.4). 7. **Server-side classification witness:** a client-supplied classification or routing override on a profile write is ignored; the registry decision is applied (§3.3). 8. **Pointer-constraint witnesses:** inserting a second pointer for the same (user, category, brain_ref) violates the §4.1 unique constraint; a `brain_ref` failing the §4.3 grammar (leading `/`, `..` segment, empty segment) is rejected by the CHECK; resolution of a valid `brain_ref` under user A's row never reads user B's brain (owner binding, §4.3). 9. **Hash witnesses:** `content_hash` verifies via the keyed §4.4 construction; a mismatch refuses the read and flags the pointer; the database value alone, without the external key, does not equal any unkeyed digest of the fixture content (oracle control). 10. **Orphan witnesses:** starting from a PRE-EXISTING orphan (content already absent, pointer present), the next triggered reconciliation deletes the pointer and writes no content anywhere in the database (§4.5); a managed deletion removes its pointer in the same transaction. 11. **Default-deny and granularity witnesses:** an agent grantee with no active row is refused; with a `granted` row for category A only, category B is refused; with agent X granted, agent Y of the same type is refused for the same (user, category); each of the three grantee types is exercised — `feature` via its refusal path, since the version-1 feature list is empty (§5.2). 12. **Mutation-authority witnesses:** a platform admin attempting to create a grant on another user's data is refused at write time; a hierarchy owner or manager likewise; the data subject succeeds; `actor` equals the subject's principal on every committed row (§5.4). 13. **Revocation/re-grant witnesses:** after revocation commits, the next evaluation refuses and the revoked row persists unmutated; a full grant → revoke → re-grant cycle yields two rows (one revoked, one active) and access follows only the active row; a second concurrent grant attempt for the same key violates the §5.1 partial unique index (§5.5). 14. **Self-access witness:** the data subject reads their own content without consent rows (§5.6). 15. **Mode witnesses:** the custody-table schemas are byte-identical under Standalone and Enterprise migrations (§6.1); a fresh Standalone bootstrap records `standalone_layout = 'split'` by default, and an explicit opt-out records `unsplit` with actor and audit linkage (§6.3); conversion from an `unsplit` install refuses the mode flip until partitioning has produced the per-user region (§6.5, with contract 6 §4.2); in an Enterprise fixture with two users, user A's grantee with a grant on user A cannot reach any of user B's content (§6.6). ## 8. Drafting additions (PRD §12.1 disclosure) The following are proposed drafting additions, visible here for ratification; none is claimed as a PRD mandate, and each is severable: 1. The `feature` grantee type, with a closed feature-key list that is empty at version 1 (§5.2). 2. Append-only consent history: re-grants insert new rows; revoked rows are retained unmutated (§5.5). 3. System-actor auto-revocation when a grantee ceases to exist (§5.4). 4. The `custody_config` election record for the Standalone layout (§6.3). 5. The keyed `content_hash` construction and its mismatch handling (§4.4). 6. The bounded dangling-pointer reconciliation policy (§4.5). 7. The column-type allowlist verification requirement (§7.2). The revision-1 "reporting" rationale for relational background/education storage is withdrawn; the traced rationale is agent configuration (PRD D4). ## Ruling request Ruling requested (one decision): classify `professional-background` and `education` as **non-sensitive** in the version-1 registry (stored relationally, used for agent configuration) — or, as the alternative, classify both **sensitive** (user-brain custody with pointers), accepting that agent-configuration reads then go through pointer indirection and consent evaluation?