transcription/docs/ver4/schema_v4.md

Database Schema (Version 4)

This document defines the selected schema direction for V4 document-person relationship expansion.

V4 goals are:

• extensible role taxonomy,
• extensible document type taxonomy,
• explicit assertion state (asserted, suggested),
• policy-driven exclusivity,
• deterministic migration from V3 links.

Scope

This specification focuses on relationship and document-type governance persistence changes. Existing Person, Source, Job, and JobSource core structures remain as in V3 unless explicitly noted.

New/Expanded Concepts

• Relationship role: semantic label such as author, recipient, mentioned.
• Assertion state: whether the link is canonical (asserted) or pending review (suggested).
• Exclusivity matrix: configurable role-pair conflicts for same (document_id, person_id).
• Suggestion provenance: evidence fields enabling review decisions.
• Document type registry: controlled taxonomy for Document classification with stable code identity.

Selected Model: Role Registry + Separate Suggestion Table

This option cleanly separates canonical links from pending suggestions and enables fully data-driven role expansion.

Tables

person_role

Column	Type	Notes
id	UUID PK	Stable key
code	TEXT UNIQUE	Canonical role code, for example author, recipient, mentioned
label	TEXT	UI label
is_active	BOOLEAN	Soft-enable/disable role
created_at	TIMESTAMPTZ	Audit timestamp
updated_at	TIMESTAMPTZ	Audit timestamp

document_person (asserted links only)

Column	Type	Notes
id	UUID PK	Stable key
document_id	UUID FK	-> document.id
person_id	UUID FK	-> person.id
role_id	UUID FK	-> person_role.id
created_at	TIMESTAMPTZ	Audit timestamp
updated_at	TIMESTAMPTZ	Audit timestamp

Constraints:

• UNIQUE(document_id, person_id, role_id)

document_person_suggestion

Column	Type	Notes
id	UUID PK	Stable key
document_id	UUID FK	-> document.id
person_id	UUID FK	-> person.id
role_id	UUID FK	-> person_role.id
status	TEXT	pending, accepted, rejected
confidence	FLOAT NULL	Optional score
source_mechanism	TEXT NULL	For example rule, llm
evidence_ref	TEXT NULL	Pointer or excerpt ID
evidence_span	JSON NULL	Optional text span payload
note	TEXT NULL	Reviewer note
created_at	TIMESTAMPTZ	Suggestion creation time
reviewed_at	TIMESTAMPTZ NULL	Decision time
reviewed_by	TEXT NULL	Operator identifier

Constraints:

• UNIQUE(document_id, person_id, role_id, status) with policy for multiple pending rows defined in service layer.
• Optional stricter rule: one active pending suggestion per (document_id, person_id, role_id).

role_exclusivity

Column	Type	Notes
id	UUID PK	Stable key
left_role_id	UUID FK	-> person_role.id
right_role_id	UUID FK	-> person_role.id
created_at	TIMESTAMPTZ	Audit timestamp

Constraints:

• Canonical ordering rule to avoid duplicate pairs (left_role_id < right_role_id enforced in service/DB).
• UNIQUE(left_role_id, right_role_id)

Initial seed:

• Exclusivity pair: (author, recipient)

Deferred Alternative (Not Selected for V4)

An enum-based shared table model was considered but is intentionally not selected for V4 because it couples canonical and provisional states in one table and increases invariant complexity.

Assertion-State Semantics

• asserted: canonical relationship used for document/person metadata and business logic.
• suggested: non-canonical proposal requiring explicit review.
• Accept action:
  • creates asserted link (or confirms existing),
  • marks suggestion accepted.
• Reject action:
  • marks suggestion rejected.

Exclusivity Enforcement

Policy target:

• For a single (document_id, person_id), disallow coexistence of role pairs configured as exclusive.

Enforcement layers:

1. Service-level pre-check for clear API errors.
2. Database-level guard where feasible (constraints/triggers or deterministic write path).

Initial configured rule:

• author and recipient are exclusive.

Enforcement semantics:

• Exclusivity is enforced for asserted links.
• Pending suggestions may exist even if they would conflict when asserted.
• Accepting a suggestion must run exclusivity checks and fail deterministically on conflict.

Migration From V3

Data Mapping

• Existing V3 document_person rows map to V4 asserted semantics.
• Existing V3 role values:
  • author -> role author
  • recipient -> role recipient

Backfill Steps

1. Seed role rows (author, recipient, mentioned) if using Option A.
2. Migrate current links into asserted table/state.
3. Run conflict scan for exclusivity violations.
4. Apply deterministic conflict policy for any violations.
5. Enable hard enforcement after data passes validation.

Indexing Guidance

Recommended indexes:

• document_person(document_id)
• document_person(person_id)
• document_person(role_id) (Option A) or document_person(role) (Option B)
• document_person_suggestion(document_id, status) (Option A)
• document_person_suggestion(person_id, status) (Option A)

Selection Rationale

V4 selects role registry plus separate suggestion storage for clearer provenance boundaries, cleaner lifecycle transitions, and long-term extensibility.

Document Type Registry Model (Selected for V4)

V4 applies the same registry governance pattern to document classification.

Tables

document_type

Column	Type	Notes
id	UUID PK	Stable key
code	TEXT UNIQUE	Canonical type code, for example letter, diary, book, postcard
label	TEXT	UI display label
is_active	BOOLEAN	Soft-enable/disable type
sort_order	INTEGER NULL	Optional UI ordering
created_at	TIMESTAMPTZ	Audit timestamp
updated_at	TIMESTAMPTZ	Audit timestamp

document update

Column	Type	Notes
document_type_id	UUID FK NULL	-> document_type.id

Constraints and Governance

• document_type.code must be stable and unique.
• document_type.label may change without changing canonical type identity.
• Inactive types remain valid for historical records but are excluded from default create/edit selectors.

Initial Seeds

• Seed baseline type codes from current V3 usage set (for example letter, diary, book, postcard, record, memo) and refine labels as needed.

Migration and Normalization (Small Corpus)

1. Seed canonical document_type rows.
2. Manually assign each existing document (10 total) to a canonical type via document_type_id.
3. Resolve any outlier values directly during this one-time pass.
4. Enforce registry-backed write validation after manual assignment is complete.

Indexing Guidance (Document Type)

• document_type(code) unique index.
• document(document_type_id) index.

Related Local References

• V4 Scope Boundary
• V4 Requirements
• V3 Schema