seonghobae · Aug 12, 2026 · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026 · Aug 9, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 ### Added
 
 - Approved Temporal Event Psychometrics Platform PRD v0.4 baseline.
+- Canonical technical documentation map, TRD, UML/scientific runtime views, logical/planned ERD, scientific test strategy, operability/recovery guide, and requirements/research/evidence traceability with explicit implemented-main, active-PR, and accepted-target maturity.
 - Eight-phase delivery roadmap and Temporal/Event Foundation implementation plan.
 - Immutable evidence, six-clock temporal semantics, interval reasoning, event ontology, typed relation graph, and time-varying multiple-membership contracts.
 - Shared-latent multilingual topic measurement architecture with native lexical channels and language-profile validation.
@@ -47,4 +48,4 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 - Added known digest vectors, mutation detection, hostile multibyte Unicode, exact-coordinate, page-boundary, stable-error, and invalid-input regression tests for the first evidence slice.
 - Added strict wire round trips, unknown-field and version rejection, digest reconstruction, configured-limit, hostile JSON, and generated multilingual span tests.
 
-[Unreleased]: https://github.com/ContextualWisdomLab/TEPP/compare/HEAD...HEAD
+[Unreleased]: https://github.com/ContextualWisdomLab/TEPP/compare/HEAD...HEAD
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
@@ -0,0 +1,33 @@
+# TEPP Documentation Map
+
+TEPP's approved PRD v0.4 and implementation plan are already the primary product baseline. This index makes the remaining technical, data, quality, and operating contracts discoverable without duplicating that source material.
+
+| Area | Canonical document |
+|---|---|
+| Approved product requirements | [`docs/product/prd-v0.4-approved.md`](docs/product/prd-v0.4-approved.md) |
+| Technical requirements | [`docs/TRD.md`](docs/TRD.md) |
+| Architecture | [`ARCHITECTURE.md`](ARCHITECTURE.md) |
+| UML/runtime/scientific flows | [`docs/UML.md`](docs/UML.md) |
+| Logical/physical ERD | [`docs/ERD.md`](docs/ERD.md) |
+| Security policy | [`SECURITY.md`](SECURITY.md) |
+| Test/scientific validation strategy | [`docs/TEST_STRATEGY.md`](docs/TEST_STRATEGY.md) |
+| Operability/recovery/release | [`docs/OPERABILITY.md`](docs/OPERABILITY.md) |
+| Requirement/research/evidence traceability | [`docs/TRACEABILITY.md`](docs/TRACEABILITY.md) |
+| Architecture decisions | [`docs/adr/README.md`](docs/adr/README.md) |
+| Delivery roadmap | [`docs/roadmaps/2026-08-05-tepp-delivery-roadmap.md`](docs/roadmaps/2026-08-05-tepp-delivery-roadmap.md) |
+| Foundation implementation plan | [`docs/superpowers/plans/2026-08-05-temporal-event-foundation.md`](docs/superpowers/plans/2026-08-05-temporal-event-foundation.md) |
+| Standards and APA 7 literature | [`docs/research/standards-and-literature.md`](docs/research/standards-and-literature.md) |
+| Governance | [`GOVERNANCE.md`](GOVERNANCE.md) |
+| Agent development rules | [`AGENTS.md`](AGENTS.md) |
+| Agent context | [`CLAUDE.md`](CLAUDE.md) |
+| Change history | [`CHANGELOG.md`](CHANGELOG.md) |
+
+## Maturity vocabulary
+
+- **implemented-main** — source and tests are present on protected `main`.
+- **active-PR** — implemented only on an open PR and not yet a protected-main claim.
+- **accepted-target** — approved PRD/ADR architecture not yet implemented.
+- **conceptual** — logical entity/service/model contract; not evidence of a migration or deployment.
+- **research-only** — evaluated research direction not accepted as production behavior.
+
+At the time of this review, immutable evidence records/exact spans and the Rust workspace quality foundation are implemented-main. PR #5 typed six-clock values/uncertain intervals and PR #6 Allen interval algebra/bounded closure are active-PR. Event ontology, PostgreSQL persistence, shared-latent topic estimation, GPU kernels, TDT/CHRONOS intelligence, longitudinal ESEM/DSEM, and visual analytics remain later accepted-target work.
diff --git a/docs/ERD.md b/docs/ERD.md
@@ -0,0 +1,283 @@
+# TEPP Logical and Persistence ERD
+
+**Status:** Accepted logical target model with current implementation maturity explicitly marked.  
+**Last reviewed:** 2026-08-09
+
+Protected main currently implements storage-independent evidence domain objects only. PR #5/#6 add temporal domain behavior on active branches. PostgreSQL migrations/tables are accepted-target and are **not implemented** on protected main yet.
+
+## Current domain foundation
+
+```mermaid
+classDiagram
+    class SourceArtifact {
+      +artifact_id UUIDv7
+      +content_sha256
+      +immutable bytes
+    }
+    class DocumentRecord {
+      +document_id UUIDv7
+      +content_sha256
+      +immutable UTF-8 text
+    }
+    class SourceSpan {
+      +document_id
+      +byte_start
+      +byte_end
+      +scalar_start
+      +scalar_end
+      +page_location optional
+    }
+    SourceArtifact --> DocumentRecord
+    DocumentRecord --> SourceSpan
+```
+
+These names summarize the current `evidence_core` domain; they are not PostgreSQL table claims.
+
+## Planned PostgreSQL ERD
+
+```mermaid
+erDiagram
+    TENANT_RECORD ||--o{ DOCUMENT_RECORD : owns
+    SOURCE_ARTIFACT ||--o{ DOCUMENT_RECORD : contains
+    DOCUMENT_RECORD ||--o{ TEXT_SEGMENT : contains
+    DOCUMENT_RECORD ||--o{ TEMPORAL_ASSERTION : carries
+    TEXT_SEGMENT ||--o{ EVENT_MENTION : evidences
+    EVENT_INSTANCE ||--o{ EVENT_MENTION : realized_by
+    EVENT_INSTANCE ||--o{ EVENT_RELATION : source_event
+    EVENT_INSTANCE ||--o{ EVENT_RELATION : target_event
+    ENTITY_RECORD ||--o{ ENTITY_ROLE_ASSIGNMENT : assigned
+    EVENT_INSTANCE ||--o{ ENTITY_ROLE_ASSIGNMENT : contextualizes
+    PROJECT_RECORD ||--o{ ENTITY_ROLE_ASSIGNMENT : contextualizes
+    DOCUMENT_RECORD ||--o{ MEMBERSHIP_ASSIGNMENT : observed_unit
+    ENTITY_RECORD ||--o{ MEMBERSHIP_ASSIGNMENT : membership_target
+    MODEL_RUN ||--o{ TOPIC_DEFINITION : estimates
+    MODEL_RUN ||--o{ TOPIC_SCORE : estimates
+    MODEL_RUN ||--o{ VALIDATION_METRIC : reports
+    TOPIC_DEFINITION ||--o{ TOPIC_CORRELATION : source_topic
+    TOPIC_DEFINITION ||--o{ TOPIC_CORRELATION : target_topic
+    TOPIC_CLUSTER ||--o{ CLUSTER_MEMBERSHIP : contains
+    TOPIC_DEFINITION ||--o{ CLUSTER_MEMBERSHIP : member
+    MODEL_RUN ||--o{ FACTOR_SOLUTION : estimates
+    FACTOR_SOLUTION ||--o{ FACTOR_LOADING : contains
+    MODEL_RUN ||--o{ AUDIT_EVENT : evidenced_by
+
+    TENANT_RECORD {
+      uuid tenant_record_id PK
+      text tenant_status_code
+      timestamptz created_at
+    }
+
+    SOURCE_ARTIFACT {
+      uuid source_artifact_id PK
+      uuid tenant_record_id FK
+      text content_sha256 UK
+      bigint source_size_bytes
+      text media_type_code
+      text protected_object_ref
+      timestamptz system_time
+    }
+
+    DOCUMENT_RECORD {
+      uuid document_record_id PK
+      uuid tenant_record_id FK
+      uuid source_artifact_id FK
+      text content_sha256
+      text language_profile_code
+      timestamptz assertion_time
+      timestamptz document_time
+      timestamptz system_time
+      timestamptz available_time
+    }
+
+    TEXT_SEGMENT {
+      uuid text_segment_id PK
+      uuid document_record_id FK
+      bigint byte_start
+      bigint byte_end
+      bigint scalar_start
+      bigint scalar_end
+      text segment_type_code
+    }
+
+    TEMPORAL_ASSERTION {
+      uuid temporal_assertion_id PK
+      uuid document_record_id FK
+      text clock_type_code
+      timestamptz lower_time
+      timestamptz upper_time
+      text lower_boundary_code
+      text upper_boundary_code
+      text source_precision_code
+    }
+
+    EVENT_INSTANCE {
+      uuid event_instance_id PK
+      uuid tenant_record_id FK
+      text event_type_code
+      timestamptz valid_from
+      timestamptz valid_to
+      text lifecycle_status_code
+    }
+
+    EVENT_MENTION {
+      uuid event_mention_id PK
+      uuid event_instance_id FK
+      uuid text_segment_id FK
+      numeric confidence_score
+    }
+
+    EVENT_RELATION {
+      uuid event_relation_id PK
+      uuid source_event_id FK
+      uuid target_event_id FK
+      text relation_type_code
+      uuid evidence_segment_id FK
+      numeric confidence_score
+      boolean transition_edge
+    }
+
+    ENTITY_RECORD {
+      uuid entity_record_id PK
+      uuid tenant_record_id FK
+      text entity_type_code
+      text canonical_name
+    }
+
+    PROJECT_RECORD {
+      uuid project_record_id PK
+      uuid tenant_record_id FK
+      text project_type_code
+      text lifecycle_status_code
+    }
+
+    ENTITY_ROLE_ASSIGNMENT {
+      uuid entity_role_assignment_id PK
+      uuid entity_record_id FK
+      uuid event_instance_id FK
+      uuid project_record_id FK
+      text role_type_code
+      timestamptz valid_from
+      timestamptz valid_to
+      numeric membership_weight
+      uuid evidence_segment_id FK
+    }
+
+    MEMBERSHIP_ASSIGNMENT {
+      uuid membership_assignment_id PK
+      uuid document_record_id FK
+      uuid membership_target_id
+      text membership_type_code
+      numeric membership_weight
+      timestamptz valid_from
+      timestamptz valid_to
+    }
+
+    MODEL_RUN {
+      uuid model_run_id PK
+      uuid tenant_record_id FK
+      text corpus_hash
+      text engine_version
+      text configuration_hash
+      text compute_backend_code
+      text random_seed_manifest_hash
+      timestamptz knowledge_cutoff
+      timestamptz created_at
+    }
+
+    TOPIC_DEFINITION {
+      uuid topic_definition_id PK
+      uuid model_run_id FK
+      integer topic_number
+      text topic_status_code
+    }
+
+    TOPIC_SCORE {
+      uuid topic_score_id PK
+      uuid model_run_id FK
+      uuid document_record_id FK
+      uuid topic_definition_id FK
+      numeric posterior_mean
+      numeric posterior_sd
+    }
+
+    TOPIC_CORRELATION {
+      uuid topic_correlation_id PK
+      uuid model_run_id FK
+      uuid source_topic_id FK
+      uuid target_topic_id FK
+      numeric posterior_median
+      numeric interval_lower
+      numeric interval_upper
+      numeric selection_probability
+    }
+
+    TOPIC_CLUSTER {
+      uuid topic_cluster_id PK
+      uuid model_run_id FK
+      text cluster_status_code
+      numeric stability_score
+    }
+
+    CLUSTER_MEMBERSHIP {
+      uuid cluster_membership_id PK
+      uuid topic_cluster_id FK
+      uuid topic_definition_id FK
+      numeric assignment_probability
+    }
+
+    FACTOR_SOLUTION {
+      uuid factor_solution_id PK
+      uuid model_run_id FK
+      text model_type_code
+      text invariance_status_code
+    }
+
+    FACTOR_LOADING {
+      uuid factor_loading_id PK
+      uuid factor_solution_id FK
+      uuid topic_definition_id FK
+      text factor_code
+      numeric loading_estimate
+      numeric standard_error
+    }
+
+    VALIDATION_METRIC {
+      uuid validation_metric_id PK
+      uuid model_run_id FK
+      text metric_type_code
+      text evaluation_slice_code
+      numeric metric_value
+      numeric interval_lower
+      numeric interval_upper
+    }
+
+    AUDIT_EVENT {
+      uuid audit_event_id PK
+      uuid tenant_record_id FK
+      uuid model_run_id FK
+      text action_code
+      text outcome_code
+      text evidence_digest
+      timestamptz system_time
+    }
+```
+
+## Temporal/bitemporal invariants
+
+- Event/valid time and system/record time are distinct.
+- `available_time` gates historical inclusion through `knowledge_cutoff`.
+- Retrospective evidence may describe an earlier event while retaining its later availability/system time.
+- Transition edges never derive a reverse state transition from a backward-pointing citation/revision/retrospective edge.
+- A future physical schema must represent uncertain/open intervals without coercing them to false exact timestamps.
+
+## Multiple-membership invariant
+
+Customer/partner/competitor/author/department/project roles are contextual time-varying assignments. They are not static attributes on `entity_record`. One document/event may have multiple weighted memberships.
+
+## Provenance/reproducibility invariant
+
+Every published analytical artifact must be traceable to source hashes, evidence spans, preprocessing/concept versions, model/configuration/seed, compute backend, dependency lock, and Git commit. Audit records store bounded evidence/digests rather than copying protected source text unnecessarily.
+
+## Migration acceptance
+
+Before this planned ERD becomes as-built, migrations must include rollback, tenant/RLS policy, temporal constraints/indexes, lineage integrity, idempotency/concurrency, retention/deletion, backup/recovery, and synthetic known-truth integration tests. The documentation maturity label then changes only after protected-main integration.