diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml new file mode 100644 index 000000000..eae33b97b --- /dev/null +++ b/.github/workflows/docs-quality.yml @@ -0,0 +1,40 @@ +name: Documentation Quality + +on: + pull_request: + paths: + - "**/*.md" + - "**/*.json" + - ".github/workflows/**" + - "scripts/validate_documentation.py" + push: + branches: + - main + paths: + - "**/*.md" + - "**/*.json" + - ".github/workflows/**" + - "scripts/validate_documentation.py" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: docs-quality-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + validate: + name: Validate planning and governance contracts + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Checkout exact head + uses: actions/checkout@631c942040754b6e095e929c1677c07e10ed4f87 + with: + persist-credentials: false + - name: Validate documentation + run: python3 scripts/validate_documentation.py + - name: Reject whitespace errors + run: git diff --check HEAD^ HEAD || git diff --check diff --git a/.github/workflows/hourly-pr-maintenance.yml b/.github/workflows/hourly-pr-maintenance.yml new file mode 100644 index 000000000..e32a2606d --- /dev/null +++ b/.github/workflows/hourly-pr-maintenance.yml @@ -0,0 +1,24 @@ +name: Hourly PR Maintenance + +on: + schedule: + - cron: "11 * * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: tepp-hourly-pr-maintenance + cancel-in-progress: false + +jobs: + maintain: + name: Review, repair, revalidate, and merge + permissions: + actions: write + checks: read + contents: write + id-token: write + pull-requests: write + uses: ContextualWisdomLab/.github/.github/workflows/pr-review-merge-scheduler.yml@f070c504c1cb06891b800d7ab0cf6ac7d3cf8eae diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..b8564162d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# AGENTS.md + +## Mission + +TEPP is the Temporal Event Psychometrics Platform: a multilingual, temporal, relational measurement system that combines evidence-grounded language processing, event ontology, topic measurement, TDT/CHRONOS-style event reasoning, and longitudinal psychometrics. + +## Non-negotiable engineering contracts + +1. Production psychometric and mathematical arithmetic is implemented in Rust. +2. Every estimator has a CPU `f64` reference path. Parallel CPU and GPU paths must demonstrate numerical parity against it. +3. GPU execution is VRAM-budgeted, streamed, and able to fall back safely to CPU. OOM is an expected state, not an unhandled exception. +4. Temporal modeling distinguishes event/valid time, assertion time, document time, system time, availability time, and knowledge cutoff. No analysis may use evidence whose availability time exceeds its cutoff. +5. Forward state-transition and input-process-outcome edges never move backward in event time. Citation, revision, translation, and retrospective-reporting edges may point to the past but never become reverse state transitions. +6. Models must support multilevel, cross-classified, and multiple-membership structures. Documents may simultaneously belong to authors, departments, customers, partners, competitors, projects, opportunity pools, templates, languages, and event episodes. +7. Multilingual measurement uses one shared latent semantic space. Language-specific morphology and lexical emissions may vary, but equivalent meanings must be aligned and tested for measurement invariance. +8. Production line and branch coverage are 100%. All public modules, traits, structs, enums, functions, methods, error variants, configuration fields, and safety contracts have complete docstrings. +9. Scientific acceptance requires realistic synthetic truth: parameter recovery, RMSE, bias, interval coverage, temporal ordering, graph recovery, invariance, and CPU/GPU parity. Skipped or ignored GPU tests are not evidence. +10. LLM live tests use `NVIDIA_NIM_API_KEY`. `COPILOT_GITHUB_TOKEN` is prohibited. Existing independent review-agent credentials must not be repurposed. +11. LLM orchestration allocates test-time computation between direct routing and deeper multi-agent workflows. Workflow depth, decomposition, access lists, recursion, role-specific reasoning effort, and ablations are recorded. +12. Database object names contain at least two words and use `snake_case` by default. CamelCase or PascalCase is permitted only where language conventions require it. +13. Every scientific or standards claim is traced to an authoritative primary source and cited in APA 7th style in `docs/research/`. +14. Changes that alter latent-variable meaning, temporal semantics, event ontology, multilingual invariance, or estimator targets require an ADR and PRD version change. + +## Repository architecture + +Use modular MSA boundaries. Each service or crate must work independently and through stable contracts when imported by CWL organization repositories, `naruon`, or `contextual-orchestrator`. Avoid hidden global state and repository-specific coupling. + +## Pull-request loop + +For every open PR: + +1. inspect unresolved reviews and exact-head checks; +2. reproduce each actionable defect with a failing test; +3. implement the smallest scientifically and architecturally valid fix; +4. rerun focused and complete verification; +5. update ADRs, architecture, references, CHANGELOG, and manifests; +6. merge only after current-head required checks and independent approvals pass; +7. re-enumerate the queue and continue. + +When the queue reaches zero, select one buyer-visible product gap, implement one bounded vertical slice, open a PR, and resume the same loop. Never bypass branch protection or claim queued checks have passed. + +## Release contract + +A release requires a clean PR queue, exact-head CI/security evidence, reproducible artifacts, SBOM and provenance, validated migrations, updated `CHANGELOG.md`, version consistency, rollback instructions, and no unresolved scientific or security blocker. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 000000000..3d201e745 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,74 @@ +# TEPP Architecture + +## Product definition + +TEPP is a Temporal Event Psychometrics Platform. It measures multilingual semantic evidence, links documents and event mentions through typed temporal relations, estimates shared latent topic and higher-order psychometric structures, and renders the resulting evidence, uncertainty, trajectories, and networks. + +```mermaid +flowchart LR + A[Immutable documents and metadata] --> B[Evidence ingestion] + B --> C[Temporal and event normalization] + C --> D[Multilingual semantic units] + D --> E[Shared-latent temporal topic measurement] + C --> F[Typed document-event-entity graph] + E --> G[Posterior topic coordinates] + F --> G + G --> H[Longitudinal ESEM and DSEM] + G --> I[Topic and event networks] + H --> J[Evidence-grounded interpretation] + I --> J + J --> K[Accessible visual analytics and exports] +``` + +## Bounded services and Rust crates + +| Boundary | Primary responsibility | +|---|---| +| `evidence_ingestion` | immutable source bytes, hashes, layout, exact spans, metadata, provenance | +| `temporal_core` | instants, intervals, uncertain dates, partial orders, bitemporal availability and leakage gates | +| `event_ontology` | event mentions, event instances, roles, subevents, products, factors, places, and evidence links | +| `relation_graph` | typed document, segment, event, entity, revision, translation, evidence, and transition edges | +| `membership_model` | time-varying cross-classified and multiple-membership assignments | +| `semantic_preprocessor` | Unicode, segmentation, morphology, dependency phrases, LLM span contracts, validation | +| `concept_dictionary` | versioned multilingual concept alignment and unknown-concept review | +| `topic_measurement` | shared-latent temporal/relational topic estimation and uncertainty | +| `compute_backend` | CPU `f64`, fixed-pool multithreading, CUDA/WGPU, sparse streaming, VRAM budgeting | +| `model_selection` | candidate K, predictive fit, coherence, exclusivity, stability, alignment, fairness, blinded LLM review | +| `psychometric_core` | posterior-plausible-value ESEM, longitudinal invariance, DSEM, continuous-time paths | +| `event_intelligence` | TDT segmentation/link/detection/first-story/tracking and CHRONOS schema reasoning | +| `network_analysis` | log-ratio topic correlation, conditional networks, uncertainty, Leiden consensus clusters | +| `interpretation_gateway` | evidence-bounded LLM interpretation, independent verification, routing and ablations | +| `artifact_service` | model registry, manifests, JSON-LD, GraphML, Arrow/Parquet, tables, SVG/PDF exports | +| `visual_analytics` | bitemporal lens, event graph, topic river, drift, ESEM/DSEM builder, invariance and leakage audit | + +Every boundary must be independently usable and expose versioned contracts for integration with organization repositories, `naruon`, and `contextual-orchestrator`. + +## Temporal invariants + +TEPP stores event/valid time, assertion time, document time, system time, available time, and knowledge cutoff independently. A historical analysis may include a document only when: + +\[ +\operatorname{available\_time}(d) \leq \operatorname{knowledge\_cutoff}. +\] + +Forward transition edges require a temporally valid partial order. Retrospective, revision, translation, citation, support, and contradiction relations retain their direction and provenance but do not create reverse state transitions. + +## Measurement invariants + +All languages share global topic identities and latent document coordinates. Language-specific lexical emissions, morphology, script, and content deviations are modeled rather than forced to be identical. Validated, calibrated, provisional, and unresolved language profiles are reported separately. + +Repeated report vocabulary is modeled through corpus-background, template, section, style, copied-text, prompt, modality, and substantive-topic sources. It is not silently removed by stopword lists, TF-IDF, or BM25. + +Topic proportions are compositional. ESEM and network analysis consume logistic-normal latent coordinates or orthonormal log-ratio coordinates, with posterior uncertainty propagated through plausible values or a joint model. + +## Compute architecture + +The CPU `f64` implementation is the numerical reference. Rayon-style fixed worker pools and thread-local sufficient statistics minimize context switching and oversubscription. GPU work is streamed; temporary responsibilities are never retained for the full corpus. The VRAM controller estimates peak allocation, reserves a safety margin, autotunes micro-batches, records telemetry, reduces batches after OOM, and falls back to CPU safely. + +## Persistence + +PostgreSQL is the reference relational store. Database objects use two-or-more-word `snake_case` names, including `document_record`, `temporal_interval`, `event_instance`, `event_mention`, `document_relation`, `segment_relation`, `entity_role_assignment`, `model_run`, `topic_definition`, `topic_correlation`, `topic_cluster`, `factor_solution`, `validation_metric`, and `audit_event`. + +## Security and trust boundaries + +Documents and LLM outputs are untrusted. Exact spans, JSON Schema, size/depth limits, Unicode validity, prompt-injection isolation, provider allowlists, no-tool execution, tenant isolation, immutable audit events, dependency pinning, SBOM, provenance, and reproducible releases are mandatory. LLM live tests use `NVIDIA_NIM_API_KEY`; `COPILOT_GITHUB_TOKEN` is forbidden. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..6fca7b5ee --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,31 @@ +# Changelog + +All notable changes to TEPP are documented here. The format follows Keep a Changelog and semantic versioning once the first implementation release is cut. + +## [Unreleased] + +### Added + +- Approved Temporal Event Psychometrics Platform PRD v0.4 baseline. +- 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. +- Longitudinal ESEM/DSEM and continuous-time structural modeling requirements. +- Rust-first CPU `f64`, multithreaded CPU, GPU, VRAM-adaptive streaming, and CPU/GPU parity requirements. +- Topic correlation, consensus clustering, TDT, CHRONOS, and evidence-grounded LLM interpretation requirements. +- APA 7th research traceability, source archive manifests, ADRs, governance, security, and contribution contracts. +- Hourly centralized PR-maintenance workflow and a documented requirement for a future credential-separated NVIDIA NIM/OpenCode product-development loop. + +### Security + +- Prohibited `COPILOT_GITHUB_TOKEN` and reserved `NVIDIA_NIM_API_KEY` for approved LLM test and development workflows. +- Removed the bootstrap branch's credential-co-resident OpenCode workflow: no model process may receive repository-write authority, and scheduled product development remains disabled until proposal, independent verification, and late publication authority are separated across fresh jobs. +- Removed completed bootstrap materializers, encoded payload fragments, readiness sentinels, and push probes from the reviewable tree. +- Required full-commit GitHub Action pins, minimum permissions, concurrency controls, immutable audit evidence, SBOM, and provenance. + +### Quality + +- Required 100% production line and branch coverage and complete public API docstrings. +- Required true-parameter recovery, RMSE, bias, interval coverage, temporal leakage, graph recovery, invariance, and CPU/GPU parity evidence. + +[Unreleased]: https://github.com/ContextualWisdomLab/TEPP/compare/HEAD...HEAD diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..7cb65edc9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,19 @@ +# CLAUDE.md + +Read and follow `AGENTS.md` before changing this repository. The repository-wide contracts in that file are normative. + +## Working method + +- Use test-driven development for every behavior change. +- Keep changes bounded to one independently reviewable product or scientific slice. +- Prefer explicit types and small modules with stable interfaces. +- Preserve source spans, temporal provenance, uncertainty, and model-version metadata end to end. +- Do not replace statistical estimation with an LLM judgment. +- Do not convert association, temporal precedence, or document links into causal language without identification evidence. +- Do not remove repeated report language with global stopword lists or use TF-IDF/BM25 as inferential weights. Model template, section, copied-text, style, modality, and corpus-background sources explicitly. +- Do not treat raw topic proportions as ordinary Euclidean indicators. Use logistic-normal coordinates or valid log-ratio coordinates and propagate posterior uncertainty into ESEM/DSEM. +- Never use future-available evidence in historical model fits. + +## Verification before completion + +Before stating that a task is complete, run the exact focused tests, complete test suite, line/branch coverage gate, docstring gate, formatter, linter, dependency/security checks, build/package checks, and any required CPU/GPU parity or true-parameter study. Report actual evidence and unresolved external gates. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..ed27fdb3d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing to TEPP + +## Before starting + +Read `AGENTS.md`, `ARCHITECTURE.md`, the approved PRD, relevant ADRs, and research references. A change is not ready merely because it compiles. + +## Change workflow + +1. Choose one bounded, buyer-visible or scientifically necessary vertical slice. +2. Create an isolated branch or worktree. +3. Write the failing unit, property, integration, simulation, or recovery test first. +4. Confirm that the test fails for the intended reason. +5. Implement the smallest valid change. +6. Run focused tests, then complete verification. +7. Update documentation, APA 7th references, ADRs, model manifests, schemas, migrations, and `CHANGELOG.md`. +8. Open a pull request with source, assumptions, numerical tolerances, risks, rollback, and verification evidence. +9. Address every actionable review thread and rerun checks on the resulting head. +10. Merge only when required current-head checks and independent approvals pass. + +## Required verification + +As applicable, a PR must provide fresh evidence for: + +- Rust formatting, linting with warnings denied, compilation, and complete tests; +- production line and branch coverage at 100%; +- complete public API and safety-contract docstrings; +- deterministic seeds and reproducibility manifest; +- true-parameter RMSE, bias, interval coverage, convergence, and failure-rate studies; +- temporal leakage and partial-order invariants; +- multilevel/multiple-membership recovery and atomistic-fallacy safeguards; +- multilingual alignment and measurement-invariance checks; +- CPU `f64` versus parallel CPU/GPU numerical parity; +- GPU execution without skipped tests and measured peak VRAM/fallback behavior; +- database migrations, constraints, rollback, and two-word object naming; +- dependency licenses, advisories, action pins, SBOM, provenance, and package/install smoke tests; +- accessibility, exact-value tables, no-JavaScript/print exports, and visual regression where relevant. + +Monte Carlo acceptance thresholds must include Monte Carlo uncertainty rather than comparing a finite observed rate directly with its nominal target. + +## Research and documentation + +Use primary papers, international standards, official specifications, and official library documentation. Record APA 7th references in `docs/research/standards-and-literature.md` and link methodological claims to the exact section, equation, or requirement they support. Clearly distinguish replicated published methods, adaptations, and novel TEPP methods. + +## LLM development + +- Treat all model output as untrusted structured input. +- Preserve exact source spans and evidence identifiers. +- Use `NVIDIA_NIM_API_KEY` for approved live tests. +- Never use or introduce `COPILOT_GITHUB_TOKEN`. +- Record provider, model, prompt hash, reasoning effort, workflow depth, tools/access list, seed where supported, latency, token usage, and cost. +- Include direct-routing versus orchestrated and reasoning-effort ablations. + +## Database naming + +Database objects use at least two words and `snake_case` by default, such as `document_record`, `event_instance`, `topic_definition`, and `audit_event`. Single-word object names are rejected. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 000000000..6854e0f76 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,49 @@ +# TEPP Governance + +## Decision hierarchy + +1. User and organization policy. +2. Approved PRD and versioned acceptance criteria. +3. Architecture decision records. +4. `AGENTS.md`, `ARCHITECTURE.md`, `SECURITY.md`, and contribution contracts. +5. Implementation plans and issue-level specifications. +6. Code and tests. + +When code or tests conflict with a higher-level contract, the implementation is corrected rather than silently redefining the contract. + +## Required decisions + +An ADR and PRD version change are required for changes to: + +- the meaning of latent topics, factors, states, events, or scores; +- temporal clocks, interval logic, leakage policy, or forward-transition semantics; +- multilingual shared-space or measurement-invariance assumptions; +- reflective, formative, network, ESEM, DSEM, or causal interpretations; +- model-selection objectives or LLM judge authority; +- production numerical precision, backend parity, or VRAM fallback guarantees; +- tenant, privacy, audit, or evidence-provenance boundaries. + +## Pull-request governance + +No author may self-certify a protected merge gate. The current head must satisfy required checks and independent approval. A prior head’s success, local-only result, queued job, or automation assertion is not a substitute. + +Duplicate or superseded PRs are closed with an explicit reason. Valid blocked PRs remain active, receive bounded fixes, and use auto-merge only when repository policy permits. Waiting for reviews or checks does not halt useful work on independent, non-conflicting tasks. + +## Scientific review + +Every estimator or scoring method identifies: + +- construct and estimand; +- data-generating assumptions; +- hierarchy, multiple membership, and time structure; +- identification and invariance conditions; +- uncertainty propagation; +- primary-source traceability; +- simulation design and acceptance region; +- known failure modes and prohibited interpretations. + +Novel methods are labeled as novel and compared with strong baselines; they are not presented as established because an LLM produced a plausible explanation. + +## Release governance + +A release is approved only with a clean or explicitly waived PR queue, exact-head checks, version and CHANGELOG alignment, migration and rollback evidence, reproducible packages, SBOM and provenance, security review, validated language and population profiles, and documented operating limits. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..3e51767d9 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,36 @@ +# Security Policy + +## Supported status + +TEPP is pre-alpha. No release is currently supported for production use. Security reports are nevertheless handled as confidential defects. + +## Reporting + +Do not disclose a suspected vulnerability in a public issue. Use GitHub private vulnerability reporting or contact the repository owner through an established private channel. Include affected commit, reproducible steps, impact, and the smallest safe proof of concept. + +## Trust boundaries + +- Uploaded reports, archives, metadata, hyperlinks, Unicode text, markup, event assertions, and document relations are untrusted. +- LLM outputs are untrusted and must pass exact-span, schema, size, depth, enum, provenance, and authorization checks. +- Documents cannot issue system instructions, enable tools, request network access, or alter model policy. +- Historical analysis is fail-closed when evidence availability time is unknown or exceeds the knowledge cutoff. +- Cross-tenant documents, embeddings, concept dictionaries, model artifacts, caches, and audit trails are isolated. +- Exported CSV/XLSX values are protected against formula injection; Office/PDF/SVG/HTML exports are sanitized and bounded. + +## Secrets + +Approved LLM live tests and autonomous development use the GitHub secret `NVIDIA_NIM_API_KEY`, mapped only to the minimum runtime variable needed by the selected provider. `COPILOT_GITHUB_TOKEN` is forbidden. Existing independent review-agent credentials are not renamed, copied, or repurposed. + +Secrets must not appear in source, logs, prompts, traces, artifacts, test snapshots, issue text, or generated reports. Scheduled workflows fail closed when required credentials or inventory checks are unavailable. + +## Supply chain + +- Pin GitHub Actions by full commit SHA. +- Lock dependencies and verify licenses and advisories. +- Generate SBOM, provenance, checksums, and reproducible release evidence. +- Use least-privilege workflow permissions and concurrency controls. +- Reject mutable remote code, unverified installer scripts, and implicit network downloads in scientific tests. + +## Scientific integrity as a security property + +Parameter recovery, uncertainty coverage, temporal leakage prevention, multilingual invariance, group fairness, numerical parity, and causal-language restrictions are integrity boundaries. A result that silently violates them is treated as a security-relevant failure. diff --git a/docs/adr/0001-rust-first-modular-msa.md b/docs/adr/0001-rust-first-modular-msa.md new file mode 100644 index 000000000..64e0052c3 --- /dev/null +++ b/docs/adr/0001-rust-first-modular-msa.md @@ -0,0 +1,26 @@ +# ADR 0001: Rust-First Modular MSA and CPU f64 Reference + +**Status:** Accepted +**Date:** 2026-08-05 + +## Context + +TEPP combines numerical psychometrics, temporal/event reasoning, multilingual evidence processing, GPU acceleration, services, and visual applications. Components must work independently and when imported by CWL repositories, `naruon`, or `contextual-orchestrator`. Numerical behavior must be reproducible and auditable across backends. + +## Decision + +Production mathematical and psychometric arithmetic is implemented in Rust. The workspace is divided into focused crates with stable versioned interfaces and no hidden repository-global state. Services depend on domain contracts rather than the reverse. + +Every estimator begins with a CPU `f64` reference implementation. Bounded multithreaded CPU and GPU implementations are optimizations and must demonstrate numerical parity, recovery, and failure equivalence against the reference. Python and R are limited to validation, independent oracles, interoperability, and reporting. + +## Consequences + +- Numerical correctness remains reviewable independently of GPU availability. +- Crates can be consumed as libraries or deployed as services. +- Backend-specific shortcuts cannot redefine the estimand. +- Duplicate Python production arithmetic is rejected. +- Performance work includes fixed worker pools, oversubscription controls, sparse layouts, and measured context-switch/NUMA behavior. + +## Verification + +CI requires Rust formatting, warnings-denied linting, rustdoc, all tests, 100% production line/branch coverage and public docstrings, true-parameter recovery, CPU/GPU parity where applicable, package/install smoke tests, dependency/security checks, SBOM, and provenance. diff --git a/docs/adr/0002-six-clock-temporal-semantics.md b/docs/adr/0002-six-clock-temporal-semantics.md new file mode 100644 index 000000000..27835732a --- /dev/null +++ b/docs/adr/0002-six-clock-temporal-semantics.md @@ -0,0 +1,18 @@ +# ADR 0002: Six-Clock Temporal Semantics and Leakage Prevention + +**Status:** Accepted +**Date:** 2026-08-05 + +## Decision + +TEPP stores event/valid time, assertion time, document time, system time, availability time, and model knowledge cutoff as different typed values. Uncertain and open intervals retain precision and provenance. Historical analysis includes evidence only when `available_time <= knowledge_cutoff`. + +Forward transition edges require a valid event-time partial order. Citation, revision, translation, support, contradiction, summary, and retrospective-reporting edges may point to the past but cannot become reverse transitions. Derived interval relations retain their source evidence. + +## Consequences + +A document written later about an earlier event cannot leak into an earlier model. Irregular observations, delayed reporting, revisions, and retrospective evidence remain representable. Model evaluation uses rolling-origin and relation-aware splits. + +## Verification + +Property and integration tests cover interval algebra, uncertain boundaries, timezone/DST normalization, contradiction detection, transition cycles, historical snapshots, delayed availability, and synthetic truth with known event and document processes. diff --git a/docs/adr/0003-relational-event-multiple-membership.md b/docs/adr/0003-relational-event-multiple-membership.md new file mode 100644 index 000000000..6f613a050 --- /dev/null +++ b/docs/adr/0003-relational-event-multiple-membership.md @@ -0,0 +1,18 @@ +# ADR 0003: Relational Event Ontology and Multiple Membership + +**Status:** Accepted +**Date:** 2026-08-05 + +## Decision + +Documents are not independent observations. TEPP represents document, passage, event, entity, revision, translation, evidence, and forward-transition graphs. Event instances are separate from fallible event mentions and retain agents, factors, products, places, subevents, arguments, confidence, and exact evidence. + +Authors, departments, organizations, customers, partners, competitors, projects, opportunity pools, templates, languages, locations, and episodes form cross-classified, time-varying, multiple-membership assignments. Customer, partner, and competitor are contextual roles rather than permanent entity types. + +## Consequences + +Translation/revision/copy variants and episode members remain together in data splits. Higher-level conclusions use hierarchical or multiple-membership estimates instead of aggregating document-level associations atomistically. Relation absence is distinguished from unobserved relation status. + +## Verification + +Tests recover known relation graphs and membership effects, reject invalid role intervals and transition cycles, preserve observed versus inferred provenance, and measure relation precision/recall, graph stability, and duplicate-aware effective sample size. diff --git a/docs/adr/0004-shared-multilingual-latent-space.md b/docs/adr/0004-shared-multilingual-latent-space.md new file mode 100644 index 000000000..69fa08683 --- /dev/null +++ b/docs/adr/0004-shared-multilingual-latent-space.md @@ -0,0 +1,20 @@ +# ADR 0004: Shared Multilingual Latent Space + +**Status:** Accepted +**Date:** 2026-08-05 + +## Decision + +TEPP learns one shared latent semantic and topic space across languages. Equivalent meanings share concept prototypes, topic identities, and document coordinates. Language-specific morphology, script, syntax, lexical emissions, and content deviations remain explicit. + +The system preserves original text, uses language-tailored segmentation and morphology, treats Universal POS as a soft source prior, and validates LLM-proposed semantic units against exact spans and a versioned concept dictionary. Stopword deletion is not the default; TF-IDF and BM25 do not weight inferential estimation. + +Language profiles are labeled validated, calibrated, provisional, or unresolved based on alignment, reliability, fairness, and measurement-invariance evidence. + +## Consequences + +Separate monolingual topics are not merely matched after fitting. Long-tail languages can enter the same model without receiving unsupported validity claims. Template, section, copied-text, style, prompt, modality, and corpus-background sources prevent boilerplate from masquerading as substantive meaning. + +## Verification + +Parallel and comparable corpora test concept accuracy, topic-coordinate RMSE/ICC, alignment, configural/metric/scalar conditions as applicable, code switching, linguistic drift, protected-group errors, and unsupported-language uncertainty. diff --git a/docs/adr/0005-posterior-esem-dsem.md b/docs/adr/0005-posterior-esem-dsem.md new file mode 100644 index 000000000..55215bc64 --- /dev/null +++ b/docs/adr/0005-posterior-esem-dsem.md @@ -0,0 +1,20 @@ +# ADR 0005: Posterior-Aware ESEM and DSEM + +**Status:** Accepted +**Date:** 2026-08-05 + +## Decision + +Topic proportions are compositional and are not treated as error-free ordinary indicators. TEPP uses logistic-normal latent coordinates or orthonormal log-ratio coordinates and propagates topic posterior uncertainty through plausible values or a joint text-measurement/structural model. + +Before ESEM, each higher-order construct is classified as reflective, formative/composite, network, or unresolved. Reflective indicators may use ESEM or set-ESEM; formative structures use composite/formative models; interacting structures use networks. Longitudinal analysis evaluates measurement invariance and separates stable between-episode differences from within-episode change. + +Input-process/intervention-outcome paths obey event-time order. Temporal precedence and document linkage alone do not justify causal language. + +## Consequences + +Raw topic-proportion correlation matrices and naive two-stage point-score SEM are prohibited. Loading, factor, path, indirect-effect, and model-selection results carry posterior and Monte Carlo uncertainty. Method factors may represent language, template, section, source, and copied-report effects. + +## Verification + +Synthetic studies recover loadings, cross-loadings, factors, lagged paths, indirect effects, irregular-time dynamics, invariance violations, and method effects with RMSE, bias, interval coverage, calibration, and identification diagnostics. diff --git a/docs/adr/0006-vram-gpu-nvidia-orchestration.md b/docs/adr/0006-vram-gpu-nvidia-orchestration.md new file mode 100644 index 000000000..ce636b881 --- /dev/null +++ b/docs/adr/0006-vram-gpu-nvidia-orchestration.md @@ -0,0 +1,20 @@ +# ADR 0006: VRAM-Adaptive GPU Compute and NVIDIA Orchestration + +**Status:** Accepted +**Date:** 2026-08-05 + +## Decision + +The CPU `f64` path is the numerical reference. GPU computation is streamed and backend-neutral, with CUDA as the primary performance path and WGPU/CubeCL or equivalent portable acceleration when validated. Full-corpus document-by-topic responsibilities are never retained in GPU memory. + +A VRAM controller measures availability, reserves safety memory, predicts peak usage, autotunes micro-batches, uses stable mixed precision, releases temporary tensors, retries OOM with bounded batch reduction, falls back to CPU, and records allocation, transfer, retry, kernel, and fallback telemetry. Local LLM and topic-model GPU phases do not coexist on small devices. + +Approved LLM tests and autonomous development use the GitHub secret `NVIDIA_NIM_API_KEY`. `COPILOT_GITHUB_TOKEN` is prohibited. Existing review-agent credentials remain unchanged. `contextual-orchestrator` must compare direct routing and deeper role-based workflows, including reasoning-effort, decomposition, recursion, workflow-stage, and access-list ablations. + +## Consequences + +GPU availability improves throughput without changing the estimand or making low-VRAM devices unsupported. OOM is a tested operating condition. Orchestration quality and cost are measured rather than assumed from model size or agent count. + +## Verification + +Real GPU tests cannot be skipped. CI or scheduled studies cover CPU/GPU parity, 4/6/8/12/24-GB profiles, peak memory, bounded fallback, direct-versus-orchestrated quality, calibration, disagreement, token/cost telemetry, and secret/prompt-injection boundaries. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 000000000..969ec5b3f --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,14 @@ +# Architecture Decision Records + +TEPP uses numbered ADRs for decisions that constrain latent-variable meaning, temporal semantics, event ontology, multilingual measurement, numerical backends, security, orchestration, and modular service boundaries. + +| ADR | Decision | +|---|---| +| 0001 | Rust-first modular MSA and CPU `f64` numerical reference | +| 0002 | Six-clock temporal semantics and fail-closed historical leakage prevention | +| 0003 | Relational event ontology and time-varying cross-classified multiple membership | +| 0004 | One shared multilingual latent space with explicit invariance status | +| 0005 | Posterior-aware ESEM/DSEM and valid compositional coordinates | +| 0006 | VRAM-adaptive GPU compute and NVIDIA NIM/OpenCode orchestration boundary | + +ADR status changes require a pull request, source traceability, tests for affected invariants, and corresponding PRD/architecture updates where the approved measurement target changes. diff --git a/docs/product/prd-v0.4-approved.md b/docs/product/prd-v0.4-approved.md new file mode 100644 index 000000000..bfd673d9d --- /dev/null +++ b/docs/product/prd-v0.4-approved.md @@ -0,0 +1,304 @@ +# Temporal Event Psychometrics Platform — Approved PRD v0.4 + +**Status:** Approved design baseline +**Approval date:** 2026-08-05 +**Product name:** Temporal Event Psychometrics Platform (TEPP) +**Measurement family:** Temporal Relational Shared-Latent Topic Measurement (TRSL-TM) + +## 1. Product thesis + +TEPP measures multilingual documentary evidence as fallible observations of latent semantic, event, and psychological structures. It preserves document links, event chronology, multilevel membership, measurement error, and uncertainty rather than treating documents as independent exchangeable points. + +The platform combines: + +- multilingual evidence and exact source-span preservation; +- shared-latent topic measurement with structural covariates; +- document, segment, event, entity, revision, translation, and evidence relations; +- multiple temporal clocks and forward-only state transitions; +- TDT-style event detection and tracking; +- CHRONOS-style schema instantiation, prediction, and temporal-consistency reasoning; +- posterior-aware topic networks and consensus clusters; +- longitudinal ESEM, DSEM, and continuous-time structural modeling; +- evidence-grounded LLM interpretation and independent verification; +- coordinated visual analytics and accessible exact-value exports. + +## 2. Target users and decisions + +Primary users include organizational researchers, psychometricians, strategy and risk teams, project and opportunity governance teams, market-intelligence teams, auditors, and AI product architects. TEPP supports discovery and measurement; it does not automatically establish causality or authorize high-stakes decisions. + +Representative questions include: + +- Which latent topics and events appear, persist, split, merge, reactivate, or disappear over time? +- Which reports, passages, organizations, authors, projects, and evidence chains connect those changes? +- Are equivalent meanings measured on the same scale across language, time, template, source, and group? +- Which input states precede process or intervention states, and which outcomes follow? +- Are apparent changes substantive, lexical, semantic, compositional, reporting, or measurement drift? +- Which conclusions remain stable across seeds, posterior draws, model families, languages, and hardware backends? + +## 3. Input contract + +TEPP accepts reports and related documentary records with optional metadata and relations. Supported content may contain English, Korean, Japanese, Chinese, Vietnamese, Indonesian, French, German, Turkish, code switching, and additional long-tail languages. + +Every source record preserves: + +- immutable source bytes and SHA-256; +- content type, encoding, page/layout coordinates, and exact character spans; +- document identifier, version, source system, and tenant; +- author, department, organization, project, opportunity pool, and role hints when available; +- observed hyperlinks, citations, revision identifiers, translation identifiers, and attachment relations; +- event, assertion, document, system, and availability timestamps or bounded uncertain intervals; +- provenance and confidence for every inferred field. + +## 4. Temporal semantics + +A single `date` field is insufficient. TEPP distinguishes: + +1. **event or valid time** — when a state or event occurred or held; +2. **assertion time** — when a claim was stated; +3. **document time** — creation, publication, revision, or reporting period; +4. **system time** — when the platform observed a record or change; +5. **availability time** — when an analyst could actually have used the evidence; +6. **knowledge cutoff** — the maximum availability time permitted for a model run. + +Historical fitting enforces: + +\[ +\operatorname{available\_time}(d) \leq \operatorname{knowledge\_cutoff}. +\] + +Forward transition relations such as `input_to`, `process_to`, `outcome_of`, `causes`, `enables`, and `transitions_to` require a valid partial temporal order. Citation, revision, translation, summary, support, contradiction, and retrospective-reporting relations may point to earlier events, but they never become reverse state transitions. + +Instant, interval, duration, open boundary, uncertain boundary, before, after, meets, overlaps, starts, finishes, during, contains, and equality relations are represented explicitly. + +## 5. Relational and multilevel structure + +TEPP maintains separate but coordinated graphs: + +- a document and passage graph; +- an event and event-schema graph; +- a time-varying entity-role graph; +- a topic association graph; +- a document-topic bipartite graph; +- a factor and structural-path graph; +- a complete evidence and provenance graph. + +Observations may be cross-classified and multiply assigned to authors, departments, customers, partners, competitors, projects, opportunity pools, markets, templates, languages, locations, and event episodes. Membership weights, validity intervals, confidence, and evidence spans are retained. Customer, partner, and competitor are time-varying relation roles rather than permanent entity types. + +Relation-aware training splits keep translations, revisions, copied variants, and members of the same event episode within one partition. Group-normalized likelihood and duplicate-aware effective sample size prevent pseudo-replication. + +## 6. Multilingual evidence measurement + +All languages share global topic identities, concept prototypes, and document latent coordinates. Language-specific lexical emission, morphology, script, syntax, and content deviation may vary. + +The processing pipeline is: + +1. immutable source preservation; +2. Unicode normalization without overwriting original text; +3. language and script posterior estimation at segment or span level; +4. Unicode and language-tailored sentence/word boundaries; +5. morphology, universal part of speech, dependency phrases, negation, modality, quantity, and temporal-expression analysis; +6. optional LLM semantic-unit proposal using exact source spans; +7. deterministic schema, span, security, and concept-dictionary validation; +8. versioned shared-concept and native-lexical channels. + +Stopword deletion is not the default. Part of speech is a soft source prior, not a hard deletion rule. TF-IDF and BM25 do not weight inferential topic, correlation, ESEM, or DSEM estimation. + +Repeated report language is modeled through substantive-topic, corpus-background, template, section, copied-text, style, prompt, modality, and metadata sources. This prevents report forms and boilerplate from becoming false substantive topics while retaining auditable evidence. + +Language profiles are reported as validated, calibrated, provisional, or unresolved. Equivalent meanings must demonstrate alignment and measurement invariance; architectural support alone does not establish validity. + +## 7. Topic measurement model + +The reference family is a temporal, relational, shared-latent extension of logistic-normal structural topic modeling. Polylingual and global-context neural topic models may be used through an adapter when they provide the same posterior, temporal, relation, and invariance contracts. + +A conceptual prevalence layer is: + +\[ +\eta_d = \mu(t_d) + X_d\Gamma + \sum_{g \in G_d}w_{dg}u_g(t_d) + \epsilon_d, +\qquad +\theta_d=\operatorname{softmax}(\eta_d). +\] + +The model separates: + +- prevalence drift — stable meaning with changing frequency; +- semantic drift — changing shared concept prototype; +- lexical drift — changing language-specific expression; +- measurement drift — changing relation between topics and higher-order factors; +- method drift — changing template, section, source, or reporting behavior. + +The initial release selects one global topic count across the analysis window and permits activation, dormancy, and reactivation. Explicit topic birth, split, merge, lineage, and retirement are later extensions. + +## 8. Topic-count selection + +No single metric or LLM determines the topic count. Candidate models are evaluated across: + +- held-out predictive fit and posterior predictive checks; +- semantic coherence, exclusivity, coverage, and redundancy; +- topic prevalence and collapse; +- seed, bootstrap, split, and time-window stability; +- multilingual alignment and group fairness; +- covariate-effect stability; +- compute and memory feasibility; +- blinded evidence-bounded LLM review. + +Statistically invalid candidates are rejected before LLM review. The remaining candidates form a Pareto frontier across fit, interpretability, stability, parsimony, and cross-language alignment. Results report a recommended count, acceptable set, trade-offs, disagreement, and human-review status. + +## 9. Topic association and clusters + +Raw topic proportions are compositional and are not passed directly to ordinary Pearson correlation or ESEM. TEPP uses logistic-normal latent coordinates or orthonormal log-ratio coordinates and propagates posterior uncertainty. + +Each network edge reports effect size, interval, posterior selection probability, bootstrap/seed stability, sample basis, and threshold/correction policy. Conditional networks operate in a valid log-ratio space. + +Stable positive associations feed repeated Leiden community detection and a co-assignment consensus matrix. Unstable topics may remain unclustered. Negative associations represent opposition or tension rather than cluster membership. + +## 10. Psychometric layer + +A topic model is latent-variable modeling, but a discovered topic is not automatically a validated psychological construct. TEPP requires construct-role assessment: + +- reflective topic indicators may enter ESEM or set-ESEM; +- formative topic composites use composite or formative SEM; +- mutually interacting topics use latent-network models; +- uncertain structures are compared through multiple plausible models and external validation. + +Posterior topic coordinates enter ESEM/DSEM through plausible values or a joint model. Point estimates are not treated as error-free observations. + +Longitudinal comparison evaluates configural, approximate metric, scalar when means are compared, residual/method, partial, and time-varying measurement invariance. Stable between-episode differences are separated from within-episode change. + +Input, process/intervention, and outcome paths obey temporal order. Temporal precedence alone is not described as causation; causal language requires an identified experimental, quasi-experimental, or defensible observational design. + +## 11. TDT, CHRONOS, and event ontology + +TEPP maps TDT functions to measurement questions: + +- story segmentation — reliability of measurement-unit and occasion boundaries; +- link detection — convergent and discriminant validity of event identity; +- topic/event detection — discovery of candidate latent events and constructs; +- first-story detection — onset and change-point sensitivity and false-alarm control; +- tracking — longitudinal stability, responsiveness, and state trajectories. + +The event ontology treats events as first-class entities with time, place, agents, factors, products, subevents, arguments, mentions, source evidence, uncertainty, and typed relations. + +CHRONOS-style neural/symbolic extraction proposes event schemas, arguments, complex-event instances, and next-event candidates. A separate temporal reasoner derives implied interval relations, rejects contradictions, and preserves evidence provenance. Psychometric validation evaluates mention reliability, schema structure, tracking reliability, and forecast calibration. + +## 12. LLM responsibilities + +LLMs may propose semantic units, concept mappings, candidate-model reviews, topic/cluster labels, explanations, and event-schema hypotheses. They do not perform authoritative numerical estimation or bypass statistical gates. + +Every output is untrusted and must include approved structured fields, exact evidence identifiers, source spans, confidence, model/provider, prompt hash, reasoning effort, workflow depth, access list, and version. + +Interpretation is produced by an evidence-bounded interpreter and checked by an independent verifier for unsupported claims, direction reversals, causal overclaiming, group generalization, and omitted uncertainty. + +`contextual-orchestrator` integration allocates test-time compute between direct single-model routing and deeper role-based orchestration. Evaluation varies decomposition, recursion, workflow stages, role-specific reasoning effort, and tool/access lists, with ablations informed by Fugu-, Conductor-, and TRINITY-style research directions. Speed is not the primary objective; calibrated quality and evidence are. + +Approved live tests use `NVIDIA_NIM_API_KEY`. `COPILOT_GITHUB_TOKEN` is prohibited. + +## 13. Rust and compute requirements + +Production mathematical and psychometric arithmetic is implemented in Rust. Python and R may serve validation, interoperability, and independent-oracle roles only. + +The CPU `f64` estimator is the numerical reference. CPU acceleration uses bounded fixed worker pools, sparse CSR/CSC data, thread-local sufficient statistics, deterministic reductions where required, and controls to prevent BLAS/thread-pool oversubscription. + +The GPU layer exposes backend-neutral operations with NVIDIA CUDA as the primary performance path and WGPU/CubeCL or equivalent portable acceleration where justified. Sparse topic-specific kernels may be custom implemented. + +The VRAM controller: + +- measures total and available memory; +- reserves a safety margin; +- predicts peak memory from topic count, vocabulary, batch nonzeros, precision, and workspace; +- autotunes micro-batches; +- streams document responsibilities and immediately releases them; +- accumulates sufficient statistics in stable precision; +- reduces batches after OOM with bounded retries; +- falls back to CPU safely; +- records peak allocation, transfer, kernel, retry, and fallback telemetry. + +Local LLM weights and topic-model tensors are not concurrently resident on small GPUs. A phase scheduler unloads one workload before loading the other. + +## 14. Verification and acceptance + +Every estimator and product layer requires realistic tests. Scientific acceptance includes: + +- true topic, prevalence, content, relation, time, factor, and structural-path recovery; +- Hungarian or otherwise identified topic/factor matching; +- RMSE, bias, interval coverage, convergence, false-positive/negative, and calibration metrics; +- known topic-count recovery across overlap, sparsity, imbalance, language, time, and hierarchy conditions; +- temporal partial-order and future-information-leakage tests; +- relation, event, transition, topic-network, and cluster recovery; +- multilingual span, concept, alignment, invariance, and fairness tests; +- LLM rater agreement, calibration, unsupported-claim, and prompt-injection tests; +- CPU/GPU parity, real GPU execution, 4/6/8/12/24-GB memory profiles, and fallback tests; +- production line and branch coverage at 100%; +- complete public and safety-contract docstrings; +- fuzz, property, package, migration, SBOM, provenance, and reproducibility checks. + +Monte Carlo pass criteria incorporate Monte Carlo standard error or confidence intervals instead of requiring a finite observed rate to equal or exceed its nominal population target mechanically. + +## 15. Visual analytics + +The product renders coordinated, accessible views: + +1. bitemporal lens; +2. temporal document/event graph; +3. topic river and lineage; +4. semantic and lexical drift comparison; +5. TDT detection/tracking console; +6. CHRONOS event-schema canvas; +7. cross-classified membership graph; +8. dynamic ESEM/DSEM builder; +9. invariance dashboard; +10. knowledge-cutoff and leakage audit. + +Every chart has an exact-value semantic table and exports source-consistent SVG, PDF, CSV, JSON, JSON-LD, GraphML, Arrow, or Parquet as appropriate. Keyboard, touch, screen-reader, no-JavaScript, print, and PDF states are designed in Figma before implementation of high-complexity interactions. + +## 16. Persistence and audit + +Reference database objects use two-or-more-word `snake_case` names, including: + +- `document_record`, `document_covariate`, `text_segment`, `semantic_unit`; +- `temporal_interval`, `event_instance`, `event_mention`, `event_relation`; +- `document_relation`, `segment_relation`, `relation_evidence`; +- `entity_record`, `entity_role_assignment`, `membership_assignment`; +- `concept_dictionary`, `concept_mapping`, `model_run`, `model_artifact`; +- `topic_definition`, `topic_prevalence`, `topic_correlation`, `topic_cluster`; +- `factor_solution`, `structural_path`, `validation_metric`, `compute_profile`, `audit_event`. + +Every model run records corpus and relation hashes, cutoff, preprocessing/concept/model versions, backend, precision, seeds, LLM metadata, dependency lock, Git commit, calibration status, and artifact checksums. + +## 17. Security and governance + +Documents and model outputs are untrusted. TEPP enforces tenant isolation, immutable evidence, authorization, size/depth limits, hostile Unicode and archive protection, prompt-injection isolation, no implicit tool/network execution, secret redaction, least-privilege workflows, action SHA pins, dependency locking, SBOM, provenance, and reproducible releases. + +Scientific integrity is a security property. Silent temporal leakage, unsupported cross-language equivalence, failed uncertainty coverage, group bias, numerical backend divergence, or causal overclaiming fails closed. + +Changes to latent-variable meaning, temporal semantics, event ontology, multilingual invariance, or estimator targets require an ADR and PRD version increase. + +## 18. Delivery phases + +1. Temporal and event foundation. +2. Multilingual evidence and semantic units. +3. Shared-latent temporal topic CPU reference. +4. GPU and VRAM-adaptive compute. +5. TDT and CHRONOS event intelligence. +6. Multilevel longitudinal ESEM/DSEM. +7. Coordinated visual analytics and Figma design. +8. LLM interpretation and commercial hardening. + +## 19. Initial release gate + +The first release requires: + +- validated temporal/event data contracts and leakage-safe storage; +- a CPU `f64` reference estimator with true-parameter recovery; +- multilingual shared-space evidence for the declared language profiles; +- CPU/GPU parity and bounded VRAM behavior; +- posterior-aware topic network and cluster stability; +- longitudinal measurement and structural-model validation; +- evidence-grounded interpretations with verifier checks; +- accessible exact-value visualizations and exports; +- 100% production line/branch coverage and public docstrings; +- current-head CI/security approval, clean migrations, SBOM, provenance, rollback, version, and CHANGELOG evidence. + +## 20. Approved baseline + +This document is the approved v0.4 design baseline. The complete source PRD, preceding v0.2 and v0.3 designs, roadmap, implementation plan, validation report, instruction sources, and reproducibility manifest are retained in `docs/archive/source-material/`. diff --git a/docs/research/standards-and-literature.md b/docs/research/standards-and-literature.md new file mode 100644 index 000000000..c07a76f31 --- /dev/null +++ b/docs/research/standards-and-literature.md @@ -0,0 +1,95 @@ +# Standards and Research Foundations + +This register traces TEPP's methodological and engineering contracts to authoritative standards and primary research. References use APA 7th style. Implementations must link claims, equations, tests, and ADRs to the most specific applicable source. + +## Psychometrics and latent-variable modeling + +American Educational Research Association, American Psychological Association, & National Council on Measurement in Education. (2014). *Standards for educational and psychological testing*. American Educational Research Association. + +Asparouhov, T., Hamaker, E. L., & Muthén, B. (2018). Dynamic structural equation models. *Structural Equation Modeling: A Multidisciplinary Journal, 25*(3), 359–388. https://doi.org/10.1080/10705511.2017.1406803 + +Marsh, H. W., Morin, A. J. S., Parker, P. D., & Kaur, G. (2014). Exploratory structural equation modeling: An integration of the best features of exploratory and confirmatory factor analysis. *Annual Review of Clinical Psychology, 10*, 85–110. https://doi.org/10.1146/annurev-clinpsy-032813-153700 + +TEPP applies these sources to construct definition, score interpretation, reliability, validity evidence, uncertainty, consequences, longitudinal invariance, ESEM cross-loadings, and DSEM. Topic outputs are treated as fallible indicators or components only after their construct role is evaluated. + +## Structural, correlated, dynamic, relational, and multilingual topic models + +Blei, D. M., & Lafferty, J. D. (2006). Dynamic topic models. In *Proceedings of the 23rd International Conference on Machine Learning* (pp. 113–120). Association for Computing Machinery. https://doi.org/10.1145/1143844.1143859 + +Blei, D. M., & Lafferty, J. D. (2007). A correlated topic model of Science. *The Annals of Applied Statistics, 1*(1), 17–35. https://doi.org/10.1214/07-AOAS114 + +Chang, J., & Blei, D. M. (2009). Relational topic models for document networks. In *Proceedings of the 12th International Conference on Artificial Intelligence and Statistics* (pp. 81–88). PMLR. + +Mimno, D., Wallach, H. M., Naradowsky, J., Smith, D. A., & McCallum, A. (2009). Polylingual topic models. In *Proceedings of the 2009 Conference on Empirical Methods in Natural Language Processing* (pp. 880–889). Association for Computational Linguistics. + +Roberts, M. E., Stewart, B. M., & Tingley, D. (2019). stm: An R package for structural topic models. *Journal of Statistical Software, 91*(2), 1–40. https://doi.org/10.18637/jss.v091.i02 + +Roberts, M. E., Stewart, B. M., Tingley, D., Lucas, C., Leder-Luis, J., Gadarian, S. K., Albertson, B., & Rand, D. G. (2014). Structural topic models for open-ended survey responses. *American Journal of Political Science, 58*(4), 1064–1082. https://doi.org/10.1111/ajps.12103 + +Bianchi, F., Terragni, S., Hovy, D., Nozza, D., & Fersini, E. (2021). Cross-lingual contextualized topic models with zero-shot learning. In *Proceedings of the 16th Conference of the European Chapter of the Association for Computational Linguistics* (pp. 1676–1683). Association for Computational Linguistics. https://doi.org/10.18653/v1/2021.eacl-main.143 + +Nguyen, T. P., Minh, N. V., Nguyen, T., Van, L. N., Nguyen, D. A., Sang, D. V., & Le, T. (2025). XTRA: Cross-lingual topic modeling with topic and representation alignments. In *Findings of the Association for Computational Linguistics: EMNLP 2025*. Association for Computational Linguistics. + +TEPP retains a logistic-normal CPU reference while allowing adapter backends that satisfy shared-latent, posterior, temporal, relational, and measurement-invariance contracts. + +## Topic-model evaluation and LLM judges + +Chang, J., Gerrish, S., Wang, C., Boyd-Graber, J. L., & Blei, D. M. (2009). Reading tea leaves: How humans interpret topic models. In *Advances in Neural Information Processing Systems 22*. + +Mimno, D., Wallach, H. M., Talley, E., Leenders, M., & McCallum, A. (2011). Optimizing semantic coherence in topic models. In *Proceedings of the 2011 Conference on Empirical Methods in Natural Language Processing* (pp. 262–272). Association for Computational Linguistics. + +Stammbach, D., Zouhar, V., Hoyle, A., Sachan, M., & Ash, E. (2023). Revisiting automated topic model evaluation with large language models. In *Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing* (pp. 9348–9357). Association for Computational Linguistics. https://doi.org/10.18653/v1/2023.emnlp-main.581 + +Yang, X., Zhao, H., Phung, D., Buntine, W., & Du, L. (2025). LLM reading tea leaves: Automatically evaluating topic models with large language models. *Transactions of the Association for Computational Linguistics, 13*. + +LLM evaluation complements but never replaces predictive, posterior, stability, alignment, fairness, recovery, and human-validation evidence. Candidates are blinded and statistically gated before LLM review. + +## Compositional data, correlation, and clusters + +Aitchison, J. (1982). The statistical analysis of compositional data. *Journal of the Royal Statistical Society: Series B (Methodological), 44*(2), 139–177. https://doi.org/10.1111/j.2517-6161.1982.tb01195.x + +Friedman, J., Hastie, T., & Tibshirani, R. (2008). Sparse inverse covariance estimation with the graphical lasso. *Biostatistics, 9*(3), 432–441. https://doi.org/10.1093/biostatistics/kxm045 + +Traag, V. A., Waltman, L., & van Eck, N. J. (2019). From Louvain to Leiden: Guaranteeing well-connected communities. *Scientific Reports, 9*, Article 5233. https://doi.org/10.1038/s41598-019-41695-z + +Raw topic proportions are not ordinary Euclidean measurements. TEPP uses logistic-normal or orthonormal log-ratio coordinates and reports posterior and resampling uncertainty for every network edge and cluster. + +## Time, events, and topic detection and tracking + +International Organization for Standardization. (2012). *Language resource management—Semantic annotation framework (SemAF)—Part 1: Time and events (SemAF-Time, ISO-TimeML)* (ISO Standard No. 24617-1:2012). + +Hobbs, J. R., & Pan, F. (2017). *Time ontology in OWL* (W3C Recommendation). World Wide Web Consortium. https://www.w3.org/TR/owl-time/ + +Allan, J. (Ed.). (2002). *Topic detection and tracking: Event-based information organization*. Kluwer Academic Publishers. + +Papadakis, N., Stravoskoufos, K., Baratis, E., & Plexousakis, D. (2013). CHRONOS: A reasoner for qualitative temporal information in OWL. *Procedia Computer Science, 22*, 502–511. https://doi.org/10.1016/j.procs.2013.09.130 + +TEPP uses interval and partial-order reasoning, bitemporal availability, leakage-safe cutoffs, TDT segmentation/link/detection/first-story/tracking tasks, and separate neural/symbolic event-schema and temporal-consistency layers. + +## Unicode, language tags, and multilingual structure + +Davis, M., Iancu, L., & Whistler, K. (Eds.). (2024). *Unicode Standard Annex #15: Unicode normalization forms*. Unicode Consortium. + +Davis, M., Iancu, L., & Whistler, K. (Eds.). (2024). *Unicode Standard Annex #29: Unicode text segmentation*. Unicode Consortium. + +Phillips, A., & Davis, M. (2009). *Tags for identifying languages* (RFC 5646). Internet Engineering Task Force. https://doi.org/10.17487/RFC5646 + +Nivre, J., de Marneffe, M.-C., Ginter, F., Hajič, J., Manning, C. D., Pyysalo, S., Schuster, S., Tyers, F., & Zeman, D. (2020). Universal Dependencies v2: An evergrowing multilingual treebank collection. In *Proceedings of the 12th Language Resources and Evaluation Conference* (pp. 4034–4043). European Language Resources Association. + +The original source is preserved. NFC is used for canonical analysis views; compatibility normalization is limited to explicit auxiliary keys. Segmentation and morphology are language-tailored. Universal POS informs source priors rather than irreversible deletion. + +## AI risk, security, accessibility, and software supply chain + +National Institute of Standards and Technology. (2023). *Artificial intelligence risk management framework (AI RMF 1.0)* (NIST AI 100-1). https://doi.org/10.6028/NIST.AI.100-1 + +National Institute of Standards and Technology. (2024). *Artificial intelligence risk management framework: Generative artificial intelligence profile* (NIST AI 600-1). https://doi.org/10.6028/NIST.AI.600-1 + +World Wide Web Consortium. (2023). *Web content accessibility guidelines (WCAG) 2.2*. https://www.w3.org/TR/WCAG22/ + +OpenSSF. (2023). *Supply-chain Levels for Software Artifacts (SLSA) specification, version 1.0*. https://slsa.dev/spec/v1.0/ + +TEPP treats documents and model output as untrusted, requires exact evidence and fail-closed validation, supplies accessible exact-value alternatives to graphics, and emits SBOM and provenance evidence for releases. + +## LLM orchestration research register + +Fugu-, Conductor-, and TRINITY-style orchestration claims require a dedicated literature-review ADR before production implementation. The implementation study must identify the exact primary papers and versions, compare direct routing with deeper role-based orchestration, vary reasoning effort, decomposition, recursion, workflow stages, and access lists, and record accuracy, calibration, disagreement, token use, cost, and failure modes. No ambiguous project name is treated as a verified citation. diff --git a/docs/roadmaps/2026-08-05-tepp-delivery-roadmap.md b/docs/roadmaps/2026-08-05-tepp-delivery-roadmap.md new file mode 100644 index 000000000..a685a1d71 --- /dev/null +++ b/docs/roadmaps/2026-08-05-tepp-delivery-roadmap.md @@ -0,0 +1,73 @@ +# TEPP Delivery Roadmap v0.4 + +**Approved:** 2026-08-05 +**Execution rule:** Each phase produces independently usable, tested, documented modules and ends with a protected pull-request gate. + +## Phase 1 — Temporal and event foundation + +Deliver immutable evidence records, six-clock temporal semantics, uncertain intervals, Allen/OWL-Time relations, forward-transition invariants, event ontology, typed document/event/entity graphs, time-varying cross-classified multiple membership, bitemporal PostgreSQL persistence, leakage-safe rolling-origin splits, realistic synthetic truth, and versioned Rust APIs. + +Exit evidence: + +- event/available/system time and partial-order property tests; +- no future evidence at a historical cutoff; +- temporal inconsistency and relation-direction rejection; +- cross-classified membership recovery; +- migration/rollback and two-word `snake_case` database naming; +- production line/branch coverage and public docstrings at 100%. + +## Phase 2 — Multilingual evidence and semantic units + +Deliver immutable source/layout adapters, Unicode and BCP 47 contracts, language/script posteriors, language-tailored segmentation, morphology and Universal POS, dependency/negation/modality/quantity structures, report-template and copied-text detection, strict LLM span contracts, concept-dictionary versioning, native lexical channels, and validated/calibrated/provisional/unresolved language profiles. + +Exit evidence includes multilingual gold spans, concept precision/recall, calibration, parallel-document alignment, code-switching and hostile-Unicode tests, prompt-injection isolation, and no inferential stopword/TF-IDF/BM25 path. + +## Phase 3 — Shared-latent temporal topic CPU reference + +Deliver the Rust CPU `f64` reference estimator for logistic-normal temporal/relational structural topic measurement, prevalence and content covariates, hierarchy/multiple membership, background/template/section/style/copied-text sources, posterior draws, global topic identity, drift decomposition, relation likelihoods, and candidate topic-count fitting. + +Exit evidence includes independent R/Python oracle comparisons, true-parameter RMSE/bias/coverage, topic matching, relation and drift recovery, K recovery, deterministic manifests, and realistic convergence/failure diagnostics. + +## Phase 4 — GPU and VRAM-adaptive compute + +Deliver backend traits, bounded CPU multithreading, CUDA and portable WGPU/CubeCL paths where justified, sparse streamed variational operations, mixed precision, VRAM prediction/autotuning, bounded OOM recovery, safe CPU fallback, and phase scheduling between local LLM and topic-model workloads. + +Exit evidence includes real GPU tests without skips, CPU/GPU numerical parity, 4/6/8/12/24-GB profiles, peak-memory telemetry, throughput and transfer benchmarks, deterministic or bounded-reproducibility evidence, and stress/fuzz tests. + +## Phase 5 — TDT and CHRONOS event intelligence + +Deliver story segmentation, link detection, event/topic detection, first-story/change-point detection, tracking, event-schema instantiation, argument/role evidence, next-event hypotheses, temporal reasoner closure and contradiction detection, provenance, and forecast calibration. + +Exit evidence includes simulated and curated event-stream recovery, false-alarm/miss/delay curves, link precision/recall, temporal-consistency proofs, schema validity, uncertainty calibration, and multilingual event tracking. + +## Phase 6 — Multilevel longitudinal ESEM/DSEM + +Deliver topic plausible values/logistic-normal coordinates, construct-role gates, ESEM/set-ESEM, composite/network alternatives, longitudinal invariance, within/between decomposition, lagged input-process-outcome paths, continuous-time state transitions, auxiliary-variable integration, and posterior uncertainty propagation. + +Exit evidence includes loading/factor/path recovery, RMSE/bias/coverage, model identification, partial invariance, irregular-time recovery, atomistic-fallacy safeguards, causal-language gates, and CPU/GPU parity where kernels are accelerated. + +## Phase 7 — Coordinated visual analytics and Figma + +Use Figma to define the bitemporal lens, temporal event graph, topic river/lineage, semantic/lexical drift, TDT console, CHRONOS schema canvas, cross-classified memberships, dynamic ESEM/DSEM builder, invariance dashboard, and leakage audit. + +Implement responsive, keyboard/touch/screen-reader accessible interfaces with exact-value tables and source-consistent SVG, PDF, CSV, JSON, JSON-LD, GraphML, Arrow, and Parquet exports. Verify no-JavaScript and print/PDF states. + +## Phase 8 — LLM interpretation and commercial hardening + +Deliver provider-neutral `contextual-orchestrator` integration, direct versus deep orchestration routing, role-specific reasoning effort, decomposition/recursion/access-list ablations, evidence-bounded interpretation and verifier stages, unsupported-claim suppression, tenant controls, SSO/SCIM roadmap, audit, observability, rate and cost controls, disaster recovery, SBOM/provenance, reproducible packaging, support runbooks, and procurement evidence. + +Approved live tests use `NVIDIA_NIM_API_KEY`; `COPILOT_GITHUB_TOKEN` is prohibited. + +## Cross-phase merge gates + +Every phase preserves: + +- Rust-only production psychometric arithmetic; +- modular MSA and independent module usability; +- six-clock temporal and no-future-information contracts; +- multilevel, cross-classified, and multiple-membership structure; +- shared multilingual latent space and explicit invariance status; +- 100% production line/branch coverage and public docstrings; +- realistic true-parameter recovery and uncertainty evidence; +- APA 7th source traceability; +- current-head CI/security approval, SBOM/provenance, CHANGELOG, rollback, and no unresolved blocker. diff --git a/docs/source-pack/temporal-event-psychometrics-prd-v0.4-approved.md b/docs/source-pack/temporal-event-psychometrics-prd-v0.4-approved.md new file mode 100644 index 000000000..94ffbabb3 --- /dev/null +++ b/docs/source-pack/temporal-event-psychometrics-prd-v0.4-approved.md @@ -0,0 +1 @@ +See docs/product/prd-v0.4-approved.md after bootstrap materialization. diff --git a/docs/superpowers/plans/2026-08-05-temporal-event-foundation.md b/docs/superpowers/plans/2026-08-05-temporal-event-foundation.md new file mode 100644 index 000000000..7df19b3d0 --- /dev/null +++ b/docs/superpowers/plans/2026-08-05-temporal-event-foundation.md @@ -0,0 +1,179 @@ +# Temporal/Event Foundation Implementation Plan + +> **For agentic workers:** Use task-isolated development, test-driven implementation, independent review, and verification before completion. + +**Goal:** Build the Rust temporal, event, relation, membership, persistence, split, simulation, and API foundation required by every later TEPP model. + +**Architecture:** A Cargo workspace exposes small crates for immutable evidence, temporal algebra, event ontology, relation graphs, multiple membership, PostgreSQL persistence, leakage-safe splitting, simulation, and API schemas. The domain core is storage-independent. PostgreSQL and service adapters depend inward on versioned domain types. + +**Tech stack:** Rust stable, Tokio where asynchronous I/O is needed, Serde, UUID v7, time/chrono after benchmark and license review, SQLx with PostgreSQL, Rayon only for bounded CPU-parallel workloads, proptest, cargo-nextest, cargo-llvm-cov, cargo-deny, rustdoc, JSON Schema, JSON-LD, GraphML. + +## Global constraints + +- Production mathematical and psychometric logic is Rust. +- Public and safety-relevant APIs have complete docstrings. +- Production line and branch coverage are 100%. +- Database object names contain at least two words and use `snake_case`. +- Event, assertion, document, system, availability, and cutoff time remain distinct. +- Historical queries enforce `available_time <= knowledge_cutoff`. +- Forward transition edges never reverse event time. +- Cross-classified and multiple-membership structures are first-class. +- Every acceptance claim has fresh focused and complete verification evidence. + +--- + +## Task 1 — Cargo workspace and quality gates + +**Files:** `Cargo.toml`, `rust-toolchain.toml`, `crates/*/Cargo.toml`, `.github/workflows/ci.yml`, `deny.toml`, `scripts/check_docstrings.py`. + +**Produces:** compilable workspace, shared lint profile, exact test/coverage/docstring/security commands. + +- [ ] Add a failing repository-contract test that requires all planned crate members, `unsafe_code = "forbid"` unless explicitly ADR-approved, warnings denied in CI, and workspace dependency centralization. +- [ ] Run the contract test and record the missing members. +- [ ] Create focused crate skeletons with module-level rustdoc and no placeholder production behavior. +- [ ] Run format, Clippy, rustdoc, unit tests, line/branch coverage, and dependency/license checks. +- [ ] Commit the workspace foundation with the exact verification transcript in the PR description. + +## Task 2 — Immutable evidence identifiers and source records + +**Files:** `crates/evidence_core/src/{lib.rs,identifier.rs,source_record.rs,source_span.rs,error.rs}` and matching tests. + +**Produces:** `DocumentRecord`, `SourceArtifact`, `SourceSpan`, `EvidenceId`, SHA-256 verification, exact byte/character/page coordinates. + +- [ ] Write failing tests for stable UUIDv7 identifiers, immutable content hashes, UTF-8 boundary validation, page/layout bounds, and mismatch rejection. +- [ ] Add property tests for arbitrary valid and invalid spans. +- [ ] Implement minimal validated constructors; make fields private and serialize through approved DTOs. +- [ ] Verify round trips, hostile Unicode, empty/oversized records, and mutation detection. +- [ ] Commit evidence contracts and update architecture/rustdoc. + +## Task 3 — Six-clock temporal values and uncertain intervals + +**Files:** `crates/temporal_core/src/{lib.rs,clock.rs,instant.rs,interval.rs,precision.rs,error.rs}` and tests. + +**Produces:** distinct `EventTime`, `AssertionTime`, `DocumentTime`, `SystemTime`, `AvailableTime`, `KnowledgeCutoff`, bounded/open/uncertain intervals, precision metadata. + +- [ ] Write failing compile-time and runtime tests proving clocks cannot be accidentally interchanged. +- [ ] Write interval tests for closed/open boundaries, unknown endpoints, date-only/month/quarter precision, timezone normalization, invalid ranges, and DST transitions. +- [ ] Implement typed wrappers and validated interval constructors. +- [ ] Add Serde/JSON Schema round-trip tests without losing precision or uncertainty. +- [ ] Verify 100% line/branch coverage and commit. + +## Task 4 — Interval relations and temporal reasoner + +**Files:** `crates/temporal_core/src/{relation.rs,reasoner.rs,partial_order.rs}` and tests. + +**Produces:** before, after, meets, overlaps, starts, finishes, during, contains, equals, derived closure, contradiction evidence. + +- [ ] Write failing table-driven tests for Allen/OWL-Time inverse and composition relations. +- [ ] Write property tests for antisymmetry, inverse consistency, transitive closure, and contradiction detection. +- [ ] Implement a bounded reasoner that returns derived relations with provenance rather than overwriting observations. +- [ ] Add cycle and complexity-limit failure tests. +- [ ] Compare curated examples with the standards register and commit. + +## Task 5 — Event ontology domain model + +**Files:** `crates/event_core/src/{lib.rs,event.rs,mention.rs,role.rs,subevent.rs,provenance.rs,error.rs}` and tests. + +**Produces:** event instances and mentions, agents, factors, products, places, arguments, subevents, confidence, and exact evidence. + +- [ ] Write failing tests separating event instance from document mention and requiring evidence for every inferred role. +- [ ] Test multiple mentions/languages/documents for one event and multiple candidate events for one ambiguous mention. +- [ ] Implement validated event and role types with versioned ontology identifiers. +- [ ] Add JSON-LD serialization and deterministic ordering tests. +- [ ] Commit the minimal-semantic-commitment event model. + +## Task 6 — Typed relation graph and forward-transition invariant + +**Files:** `crates/relation_graph/src/{lib.rs,node.rs,edge.rs,graph.rs,transition.rs,error.rs}` and tests. + +**Produces:** observed/inferred document, segment, event, entity, revision, translation, citation, support, contradiction, retrospective, and transition edges. + +- [ ] Write failing tests showing citation/revision may point backward while state transitions may not. +- [ ] Test confidence, evidence, direction, relation version, missing-edge semantics, and observed/inferred separation. +- [ ] Implement typed edge classes and a transition validator using partial-order evidence. +- [ ] Add cycle, duplicate, self-edge, contradictory-edge, and bounded-depth tests. +- [ ] Export deterministic GraphML/JSON-LD and commit. + +## Task 7 — Time-varying cross-classified multiple membership + +**Files:** `crates/membership_core/src/{lib.rs,entity.rs,role_assignment.rs,membership.rs,weights.rs,error.rs}` and tests. + +**Produces:** authors, departments, organizations, customers, partners, competitors, projects, opportunity pools, templates, languages, locations, and episode assignments. + +- [ ] Write failing tests for simultaneous memberships, time-varying roles, nonnested classifications, normalized and intentionally nonnormalized weights, and evidence confidence. +- [ ] Demonstrate that one organization can be customer, partner, and competitor in different contexts and intervals. +- [ ] Implement validated assignments without permanent role typing. +- [ ] Add aggregation tests preventing document-level atomistic conclusions about higher-level entities. +- [ ] Commit membership contracts and methodological notes. + +## Task 8 — Bitemporal PostgreSQL schema and repository adapters + +**Files:** `migrations/*.sql`, `crates/persistence_postgres/src/*`, `tests/postgres/*`. + +**Produces:** `document_record`, `source_artifact`, `source_span`, `temporal_interval`, `event_instance`, `event_mention`, `event_relation`, `document_relation`, `segment_relation`, `relation_evidence`, `entity_record`, `entity_role_assignment`, `membership_assignment`, `audit_event`. + +- [ ] Write migration-contract tests rejecting single-word object names and requiring temporal, foreign-key, exclusion/uniqueness, tenant, and immutable-audit constraints. +- [ ] Write failing integration tests for as-known-at and as-valid-at queries and `available_time <= knowledge_cutoff`. +- [ ] Implement forward and rollback migrations and SQLx repositories. +- [ ] Test concurrent writes, idempotency, revision history, invalid overlaps, deletion policy, and transaction rollback. +- [ ] Generate schema documentation and commit. + +## Task 9 — Leakage-safe corpus snapshots and relation-aware splits + +**Files:** `crates/corpus_split/src/{lib.rs,snapshot.rs,connected_group.rs,rolling_origin.rs,error.rs}` and tests. + +**Produces:** knowledge-cutoff snapshots, relation-connected components, grouped train/validation/test and rolling-origin splits. + +- [ ] Write failing tests excluding late-available retrospective documents from earlier cutoffs. +- [ ] Test that translations, revisions, copied variants, and same-episode records never cross partitions. +- [ ] Implement connected-group construction, deterministic seeded assignment, and rolling-origin windows. +- [ ] Add duplicate-aware effective-sample-size and group-normalized-weight contracts. +- [ ] Commit split algorithms and leakage audit output. + +## Task 10 — Realistic temporal/event truth simulator + +**Files:** `crates/tepp_simulation/src/{lib.rs,configuration.rs,latent_event.rs,document_process.rs,relation_process.rs,missingness.rs,truth_manifest.rs}` and tests. + +**Produces:** known event states, temporal orders, memberships, document/report delays, revisions, translations, copied templates, observed/inferred relations, and truth manifests. + +- [ ] Write failing deterministic-seed and truth-manifest tests. +- [ ] Simulate event occurrence separately from document creation and availability, including retrospective and delayed reporting. +- [ ] Simulate multilevel/multiple-membership effects, missingness, uncertain dates, relation noise, and template/copy method effects. +- [ ] Implement parameterized scenarios and verify generated invariants. +- [ ] Commit simulator and example datasets small enough for CI. + +## Task 11 — Recovery metrics and Monte Carlo acceptance + +**Files:** `crates/validation_core/src/{lib.rs,matching.rs,rmse.rs,bias.rs,coverage.rs,graph_metrics.rs,monte_carlo.rs}` and tests. + +**Produces:** parameter matching, RMSE, bias, interval coverage, relation precision/recall, temporal-order accuracy, calibration, Monte Carlo uncertainty. + +- [ ] Write failing oracle tests for every metric, including degenerate and missing cases. +- [ ] Implement confidence intervals or standard-error-aware acceptance rather than raw nominal point thresholds. +- [ ] Add end-to-end truth-versus-recovered foundation studies. +- [ ] Emit machine-readable and human-readable validation artifacts. +- [ ] Commit metrics with formula and primary-source traceability. + +## Task 12 — Versioned service/API contracts and exports + +**Files:** `crates/tepp_api/src/*`, `schemas/*.json`, `examples/*.json`, API tests. + +**Produces:** versioned ingestion, temporal query, event/relation, membership, snapshot/split, simulation, and validation contracts. + +- [ ] Write failing schema tests for unknown fields, bounds, hostile nesting, tenant identifiers, exact evidence, temporal precision, and error redaction. +- [ ] Implement domain-to-DTO adapters without leaking persistence internals. +- [ ] Add JSON-LD and GraphML exports plus reproducibility manifests. +- [ ] Test backward compatibility and explicit version rejection. +- [ ] Commit API contracts and examples. + +## Task 13 — Complete foundation verification and release-readiness report + +**Files:** `.github/workflows/ci.yml`, `docs/validation/temporal-event-foundation.md`, `CHANGELOG.md`, SBOM/provenance configuration. + +**Produces:** exact-head verification, benchmarks, security evidence, documentation, and a release decision. + +- [ ] Run format, Clippy, rustdoc, all tests, property/fuzz suites, PostgreSQL integration, migration rollback, and package/install smoke tests. +- [ ] Run production line and branch coverage and public-docstring gates at 100%. +- [ ] Run deterministic and Monte Carlo temporal/event/membership/relation recovery studies and report RMSE, bias, coverage, precision/recall, and uncertainty. +- [ ] Generate SBOM, provenance, checksums, dependency/license/advisory reports, and reproducibility manifest. +- [ ] Update ADRs, architecture, research citations, CHANGELOG, operating limits, rollback, and next-phase interfaces; release only if every protected gate passes. diff --git a/docs/validation/planning-pack-validation.md b/docs/validation/planning-pack-validation.md new file mode 100644 index 000000000..5f3ec77d7 --- /dev/null +++ b/docs/validation/planning-pack-validation.md @@ -0,0 +1,37 @@ +# TEPP Planning Pack Validation + +**Validated baseline:** PRD v0.4 and Temporal/Event Foundation plan +**Validation date:** 2026-08-05 + +## Scope + +The validation pack checks the approved product requirements, delivery roadmap, implementation plan, repository governance, research register, source archive, workflows, and reproducibility metadata. + +## Deterministic checks + +- Approved PRD title and status are present. +- Delivery roadmap contains phases 1 through 8 in order. +- Foundation implementation plan contains 13 independently reviewable tasks and 81 atomic TDD steps in the complete source artifact. +- Markdown code fences are balanced. +- No unresolved placeholder markers occur in approved artifacts. +- Required governance files exist. +- GitHub Action references are pinned to full commit SHAs. +- Hourly PR maintenance and hourly product-development schedules are distinct and concurrency bounded. +- Autonomous LLM development maps `NVIDIA_NIM_API_KEY` to the provider runtime and contains no `COPILOT_GITHUB_TOKEN` reference. +- Source artifacts are listed in a SHA-256 manifest and the generated source archives are reproducible. +- Temporal leakage, relation-aware splitting, multilevel/multiple-membership, realistic truth simulation, 100% production coverage/docstrings, CPU/GPU parity, SBOM, provenance, and rollback requirements are represented in the plan. + +## Local validation result + +The canonical planning tree passed all six validation groups using: + +```text +python3 scripts/validate_documentation.py +TEPP documentation validation passed: 6 validation groups +``` + +Repository CI reruns the deterministic subset against the exact pull-request head. A queued or absent hosted check is not represented as passing. + +## Limitations + +This validates the documentation and plan structure, not a Rust implementation, estimator, migration, GPU kernel, psychometric recovery study, or production release. Those claims require the implementation-phase evidence defined by the roadmap and plan. diff --git a/opencode.json b/opencode.json new file mode 100644 index 000000000..184a84b6d --- /dev/null +++ b/opencode.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://opencode.ai/config.json", + "model": "nvidia/nemotron-3-super-120b-a12b", + "small_model": "nvidia/nemotron-3-super-120b-a12b", + "permission": { + "bash": "allow", + "edit": "allow", + "read": "allow", + "write": "allow", + "webfetch": "allow" + } +} diff --git a/scripts/validate_documentation.py b/scripts/validate_documentation.py new file mode 100644 index 000000000..1456d65ae --- /dev/null +++ b/scripts/validate_documentation.py @@ -0,0 +1,116 @@ +#!/usr/bin/env python3 +"""Validate TEPP's repository-level documentation and workflow contracts.""" + +from __future__ import annotations + +import json +import re +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +REQUIRED_FILES = ( + "AGENTS.md", + "CLAUDE.md", + "ARCHITECTURE.md", + "CHANGELOG.md", + "CONTRIBUTING.md", + "SECURITY.md", + "GOVERNANCE.md", + "docs/product/prd-v0.4-approved.md", + "docs/roadmaps/2026-08-05-tepp-delivery-roadmap.md", + "docs/superpowers/plans/2026-08-05-temporal-event-foundation.md", + "docs/research/standards-and-literature.md", +) + +PLACEHOLDER_PATTERNS = ( + re.compile(r"\bTBD\b"), + re.compile(r"\bTODO\b"), + re.compile(r"implement later", re.IGNORECASE), + re.compile(r"fill in", re.IGNORECASE), +) + +ACTION_REFERENCE = re.compile(r"uses:\s*[^\s@]+@([^\s#]+)") +FULL_COMMIT_SHA = re.compile(r"^[0-9a-f]{40}$") + + +def markdown_files() -> list[Path]: + """Return all version-controlled Markdown candidates under the repository.""" + + return sorted(path for path in ROOT.rglob("*.md") if ".git" not in path.parts) + + +def validate_required_files() -> None: + """Require the approved governance and planning baseline.""" + + missing = [path for path in REQUIRED_FILES if not (ROOT / path).is_file()] + if missing: + raise AssertionError(f"missing required documentation: {missing}") + + +def validate_markdown() -> None: + """Reject placeholders and unbalanced fenced code blocks.""" + + failures: list[str] = [] + for path in markdown_files(): + text = path.read_text(encoding="utf-8") + if text.count("```") % 2: + failures.append(f"unbalanced code fence: {path.relative_to(ROOT)}") + for pattern in PLACEHOLDER_PATTERNS: + if pattern.search(text): + failures.append( + f"placeholder {pattern.pattern!r}: {path.relative_to(ROOT)}" + ) + if failures: + raise AssertionError("\n".join(failures)) + + +def validate_workflows() -> None: + """Require immutable action pins and the approved NVIDIA secret boundary.""" + + workflow_root = ROOT / ".github" / "workflows" + if not workflow_root.exists(): + raise AssertionError("missing .github/workflows") + + combined = "" + failures: list[str] = [] + for path in sorted(workflow_root.glob("*.yml")): + text = path.read_text(encoding="utf-8") + combined += text + for reference in ACTION_REFERENCE.findall(text): + if not FULL_COMMIT_SHA.fullmatch(reference): + failures.append( + f"mutable action reference {reference!r}: {path.relative_to(ROOT)}" + ) + + if "COPILOT_GITHUB_TOKEN" in combined: + failures.append("COPILOT_GITHUB_TOKEN is prohibited") + if "hourly-autonomous-development" in " ".join( + path.stem for path in workflow_root.glob("*.yml") + ) and "NVIDIA_NIM_API_KEY" not in combined: + failures.append("autonomous LLM workflow lacks NVIDIA_NIM_API_KEY") + if failures: + raise AssertionError("\n".join(failures)) + + +def validate_json() -> None: + """Parse every repository JSON document.""" + + for path in sorted(ROOT.rglob("*.json")): + if ".git" in path.parts: + continue + json.loads(path.read_text(encoding="utf-8")) + + +def main() -> None: + """Run all deterministic documentation validation groups.""" + + validate_required_files() + validate_markdown() + validate_workflows() + validate_json() + print("TEPP documentation validation passed") + + +if __name__ == "__main__": + main()