diff --git a/README.es.md b/README.es.md index 3c7d89318..8d182e85e 100644 --- a/README.es.md +++ b/README.es.md @@ -245,3 +245,5 @@ Estas ventajas se combinan en dominios donde **la reproducibilidad**, **la infer ## Licencia Licencia Apache 2.0. + +> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md). diff --git a/README.md b/README.md index c0725abf5..df5c15e80 100644 --- a/README.md +++ b/README.md @@ -239,3 +239,5 @@ Apache 2.0 Thanks for checking it out. Early feedback, issues, and contributors are very welcome. + +> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md). diff --git a/README.pt-BR.md b/README.pt-BR.md index 7d5d9bfbb..26264e2e8 100644 --- a/README.pt-BR.md +++ b/README.pt-BR.md @@ -245,3 +245,5 @@ Essas vantagens se combinam em domínios em que **reprodutibilidade**, **inferê ## Licença Licença Apache 2.0. + +> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md). diff --git a/README.ru.md b/README.ru.md index d47bf54a7..9c945651e 100644 --- a/README.ru.md +++ b/README.ru.md @@ -245,3 +245,5 @@ ctest --test-dir build --output-on-failure ## Лицензия Лицензия Apache 2.0. + +> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md). diff --git a/README.zh-CN.md b/README.zh-CN.md index 05eb282e4..f0ab3b12d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -245,3 +245,5 @@ IEEE 754 浮点数存在破坏可重复性的平台特定舍入模式、结合 ## 许可证 Apache 许可证 2.0。 + +> All determinism claims in this README are bounded by the [Determinism Surface Registry](docs/governance/DETERMINISM_SURFACE_REGISTRY.md). diff --git a/docs/BUILDABLE_NEXT_STEPS.md b/docs/BUILDABLE_NEXT_STEPS.md index cd7503fe7..14848ad73 100644 --- a/docs/BUILDABLE_NEXT_STEPS.md +++ b/docs/BUILDABLE_NEXT_STEPS.md @@ -198,7 +198,7 @@ Key files: - [README.md](../README.md) - [docs/README.md](README.md) - [docs/HANDOFF.md](HANDOFF.md) -- [docs/ROADMAP.md](ROADMAP.md) +- [docs/status/ROADMAP.md](status/ROADMAP.md) Definition of done: diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 8cc5b522f..6c928d0b1 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -65,7 +65,7 @@ When in doubt, prefer these in order: - Documentation index: [docs/README.md](README.md) - Contributing guide: [CONTRIBUTING.md](../CONTRIBUTING.md) - Buildable next tasks: [docs/BUILDABLE_NEXT_STEPS.md](BUILDABLE_NEXT_STEPS.md) -- Contributor-facing roadmap: [docs/ROADMAP.md](ROADMAP.md) +- Contributor-facing roadmap: [docs/status/ROADMAP.md](status/ROADMAP.md) - AI CLI reality check: [docs/status/AI_CLI_IMPLEMENTATION_MATRIX.md](status/AI_CLI_IMPLEMENTATION_MATRIX.md) The short version: diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 220cd368e..38bd9810e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,100 +1,3 @@ # T81 Contributor Roadmap -This is the short roadmap for someone trying to build T81 forward without first absorbing the entire historical planning corpus. - -## Roadmap goal - -Move T81 from "ambitious and credible" toward "pick-up-able and extensible by new contributors" without weakening its determinism, governance, or provenance posture. - -## Phase 1: Make the current value obvious - -Primary goal: make the runtime story clearer than the long-horizon OS story. - -Success looks like: - -- a newcomer can tell what T81 is in under a minute -- the runtime path feels complete enough to try and explain -- the docs clearly distinguish: - - usable now - - experimental but demoable - - draft architectural direction - -Recommended work: - -- continue tightening README and docs entry points -- reduce duplicated roadmap/status material -- keep handoff documents current - -## Phase 2: Harden the CanonFS interchange lane - -Primary goal: turn RFC-00D1 from a good seed into a contributor-friendly subsystem. - -Success looks like: - -- import/export semantics are stable enough for non-authors to build against -- policy and provenance are real, not placeholder-shaped -- interchange behavior is documented in a small number of obvious files -- the stable seed contract is named explicitly so examples, tests, and tooling - can depend on it without pretending the whole RFC is finished - -Recommended work: - -- deepen policy-profile semantics -- add more negative/edge-case tests -- clarify which RFC-00D1 surfaces are draft vs implementation detail -- keep the current stable seed explicit: - `canonfs import` / `canonfs export`, - `t81.canonfs-import.v1`, - `t81.canonfs-export.v1`, - provenance/manifest schemas, - `host-file` / `host-directory`, - and current policy-profile names -- consider promoting more of RFC-00D1 only after the deferred v1 questions stop - moving - -## Phase 3: Pick one narrow new subsystem and keep it narrow - -Primary goal: avoid broad new architectural spread. - -Best candidate today: - -- RFC-00D0 service descriptor and resolution prototype before full TCP/IP breadth - -Success looks like: - -- a small base-81-aware resolver exists -- CanonFS-backed descriptor loading works -- API and evidence behavior are testable without pretending the full stack is done - -## Phase 4: Keep the repo boring to operate - -Primary goal: portability, CI, and docs should not become the bottleneck. - -Success looks like: - -- CI failures are mostly meaningful, not housekeeping -- formatting and portability regressions are fixed quickly -- Windows/macOS/Linux lanes stay trustworthy - -Recommended work: - -- keep workflow drift low -- keep portable helper patterns centralized -- avoid reintroducing ad hoc platform-specific builtins or checkout gaps - -## What not to do next - -- do not expand scope across many draft subsystems at once -- do not rewrite stable accepted surfaces just because the repo is large -- do not make the OS/bare-metal lane the only public story -- do not let planning docs multiply faster than buildable work - -## Decision rule - -Prefer work that does one of these: - -- makes a current surface easier to adopt -- turns draft work into something another engineer can finish -- removes project dependence on one maintainer’s memory - -De-prioritize work that mainly adds conceptual breadth without making the existing system easier to use or extend. +> **Note:** This document has been superseded. Please see the authoritative roadmap at [`docs/status/ROADMAP.md`](status/ROADMAP.md) for current planning, strategy, and subsystem execution details. diff --git a/docs/architecture/OVERVIEW.md b/docs/architecture/OVERVIEW.md index fde9f33e7..b1a2c73a2 100644 --- a/docs/architecture/OVERVIEW.md +++ b/docs/architecture/OVERVIEW.md @@ -5,7 +5,7 @@ Last Verified (UTC): 2026-02-26 Maturity: Mixed (`Frozen` core, `Experimental` periphery) > **Architecture File Style Guide** -> - Terminology mapping: "TISC ISA" -> `core/isa/`; "VM Interpreter" -> `vm/vm.cpp`; "Axion Governance Engine" -> `kernel/axion/`; "CanonFS" -> `fs/` + `include/t81/canonfs/`; "Experimental tiers" -> `experimental/`. +> - Terminology mapping: "TISC ISA" -> `isa/`; "VM Interpreter" -> `vm/`; "Axion Governance Engine" -> `kernel/axion/`; "CanonFS" -> `fs/` + `include/t81/canonfs/`; "Experimental tiers" -> `experimental/`. > - Link style: repo-relative markdown links to concrete files only. > - Diagram conventions: GitHub-renderable Mermaid only. > - Maturity labels: `Frozen`, `Stable`, `Experimental`, `Stubbed`. @@ -37,11 +37,11 @@ Diagram source: [`diagrams/overview-layer-cake.mmd`](./diagrams/overview-layer-c | Layer | Primary code | Primary spec | Maturity | Notes | | :--- | :--- | :--- | :--- | :--- | -| Data types | `core/types/` | [`spec/t81-data-types.md`](../../spec/t81-data-types.md) | Frozen | Deterministic-core surface. | -| TISC ISA | `core/isa/` + VM decode/dispatch | [`spec/tisc-spec.md`](../../spec/tisc-spec.md) | Frozen | Opcode semantics/freeze governed. | -| VM interpreter | `core/vm/` | [`spec/t81vm-spec.md`](../../spec/t81vm-spec.md) | Stable | DCP includes interpreter path, not JIT. | +| Data types | `include/t81/types/` | [`spec/t81-data-types.md`](../../spec/t81-data-types.md) | Frozen | Deterministic-core surface. | +| TISC ISA | `isa/` + VM decode/dispatch | [`spec/tisc-spec.md`](../../spec/tisc-spec.md) | Frozen | Opcode semantics/freeze governed. | +| VM interpreter | `vm/` | [`spec/t81vm-spec.md`](../../spec/t81vm-spec.md) | Stable | DCP includes interpreter path, not JIT. | | Axion governance | `kernel/axion/` | [`spec/axion-kernel.md`](../../spec/axion-kernel.md) | Stable (bounded) | Policy verdicts integrated in VM step path. | -| CanonFS | `src/canonfs/` + `include/t81/canonfs/` | [`spec/supplemental/canonfs-spec.md`](../../spec/supplemental/canonfs-spec.md) | Stable (bounded) | Integrity controls implemented; claims remain bounded. | +| CanonFS | `fs/` + `include/t81/canonfs/` | [`spec/supplemental/canonfs-spec.md`](../../spec/supplemental/canonfs-spec.md) | Stable (bounded) | Integrity controls implemented; claims remain bounded. | | Experimental tiers/kernel concepts | `experimental/` | [`spec/cognitive-tiers.md`](../../spec/cognitive-tiers.md), [`spec/supplemental/hanoi-kernel-spec.md`](../../spec/supplemental/hanoi-kernel-spec.md) | Experimental / Stubbed | Not part of DCP guarantees. | ## Binary Host Execution Boundary diff --git a/docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md b/docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md index 9a6c9dcd8..a5e21c9d5 100644 --- a/docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md +++ b/docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md @@ -170,7 +170,7 @@ For someone discovering the project, the best reading order is: 1. `README.md` for the current public story and first-run paths, 2. `docs/HANDOFF.md` for what is mature, what is draft, and how to approach the codebase, -3. `docs/ROADMAP.md` for the current sequencing of work, +3. `docs/status/ROADMAP.md` for the current sequencing of work, 4. `docs/BUILDABLE_NEXT_STEPS.md` for bounded contributor lanes, 5. RFC-00D1 for the best current example of a draft architecture turning into code, 6. RFC-00D0 for the networking direction that remains design-led. diff --git a/docs/records/audits/2026-03_documentation_refresh/OUTPUT_A_EXECUTIVE_SUMMARY.md b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_A_EXECUTIVE_SUMMARY.md new file mode 100644 index 000000000..ce0324dfe --- /dev/null +++ b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_A_EXECUTIVE_SUMMARY.md @@ -0,0 +1,26 @@ +# Executive Summary + +## Total Documents Reviewed +810 Markdown files were identified across the repository. The review focused on root documentation, architecture references, RFCs, governance policies, and status/roadmap trackers. + +## Major Stale Areas +- **Architecture Overview (`docs/architecture/OVERVIEW.md`)**: References to `core/isa/`, `core/vm/`, and `core/types/` are stale. The repository structure is actually `isa/`, `vm/`, `fs/`, `include/t81/types/`, etc., at the root level. +- **Status/Roadmap (`docs/status/ROADMAP.md` vs `docs/ROADMAP.md`)**: Duplication exists for roadmap documents. +- **Governance script mismatch (`scripts/governance/check_docs_structure.py`)**: Book directory checks pointed to `book/book-en` instead of `docs/book/book-en`. + +## Major Contradictions +- **Layer Mapping**: The `docs/architecture/OVERVIEW.md` layer mapping contradicts the physical repository layout (`isa`, `vm`, `fs`, `include` are top-level directories, not nested under a `core/` directory). +- **Status Reporting**: Multiple files in `docs/` (like `ROADMAP.md` vs `docs/status/ROADMAP.md`) report redundant or potentially diverging information. + +## Highest-Risk Docs +- `README.md` and translated equivalents +- `docs/architecture/OVERVIEW.md` +- `docs/ROADMAP.md` vs `docs/status/ROADMAP.md` +- `docs/HANDOFF.md` + +## Systemic Doc Hygiene Problems +- The repository was restructured (likely flattening `core/` to root), but architectural documentation was not updated to reflect this. +- Link staleness due to directory structural changes. + +## Overall Documentation Health Assessment +The documentation is largely excellent in intent, precision, and tone. However, it suffers from structural staleness due to a recent directory refactoring (e.g., flattening `core/`). The authoritative specifications (`spec/`) and governance documents are high quality, but the explanatory layer (`docs/architecture/`) needs immediate alignment with repository reality to prevent onboarding friction. diff --git a/docs/records/audits/2026-03_documentation_refresh/OUTPUT_B_DOCUMENT_INVENTORY_TABLE.md b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_B_DOCUMENT_INVENTORY_TABLE.md new file mode 100644 index 000000000..6a18ce65d --- /dev/null +++ b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_B_DOCUMENT_INVENTORY_TABLE.md @@ -0,0 +1,12 @@ +# Document Inventory Table + +| Path | Type | Authority | Freshness | Risk | Recommended Action | +|---|---|---|---|---|---| +| `README.md` | root overview | canonical | VERIFIED | CRITICAL | KEEP | +| `docs/architecture/OVERVIEW.md` | architecture reference | high-authority | STALE | HIGH | REVISE | +| `docs/ROADMAP.md` | roadmap summary | operational | CONTRADICTED | HIGH | REPLACE | +| `docs/status/ROADMAP.md` | roadmap | operational | VERIFIED | MEDIUM | KEEP | +| `docs/HANDOFF.md` | onboarding doc | explanatory | PARTIALLY VERIFIED | HIGH | REVISE | +| `docs/BUILDABLE_NEXT_STEPS.md` | roadmap/tasks | explanatory | PARTIALLY VERIFIED | MEDIUM | REVISE | +| `docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md` | explanatory | explanatory | PARTIALLY VERIFIED | LOW | REVISE | +| `scripts/governance/check_docs_structure.py` | script | operational | STALE | HIGH | REVISE | diff --git a/docs/records/audits/2026-03_documentation_refresh/OUTPUT_C_STALE_CLAIMS_REGISTER.md b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_C_STALE_CLAIMS_REGISTER.md new file mode 100644 index 000000000..721b1e6bb --- /dev/null +++ b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_C_STALE_CLAIMS_REGISTER.md @@ -0,0 +1,9 @@ +# Stale Claims Register + +| Document Path | Quoted or Summarized Claim | Classification | Evidence | Recommended Correction | +|---|---|---|---|---| +| `docs/architecture/OVERVIEW.md` | `"TISC ISA" -> core/isa/; "VM Interpreter" -> core/vm/` | CONTRADICTED | `ls -d isa vm` shows these are at repo root, not under `core/`. | Update mapping instructions and paths in the table to use `isa/`, `vm/`, `include/t81/types/` etc. | +| `docs/architecture/OVERVIEW.md` | `Data types -> core/types/` | CONTRADICTED | No `core/` or `types/` at root. Types are likely in `include/t81/types/` or `include/t81/data_types/` or `lang/`. | Check `include/` and adjust path to `include/t81/types/`. | +| `docs/architecture/OVERVIEW.md` | `VM interpreter -> core/vm/` | CONTRADICTED | Actual path is `vm/`. | Change to `vm/`. | +| `docs/architecture/OVERVIEW.md` | `CanonFS -> src/canonfs/ + include/t81/canonfs/` | CONTRADICTED | Actual path is `fs/` + `include/t81/canonfs/` | Change `src/canonfs/` to `fs/`. | +| `scripts/governance/check_docs_structure.py` | `book/book-en` in BOOK_DIRS | STALE | Directory `book` is actually inside `docs/book` | Prefix with `docs/` | diff --git a/docs/records/audits/2026-03_documentation_refresh/OUTPUT_D_CROSS_DOCUMENT_CONFLICT_REGISTER.md b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_D_CROSS_DOCUMENT_CONFLICT_REGISTER.md new file mode 100644 index 000000000..67f87cd53 --- /dev/null +++ b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_D_CROSS_DOCUMENT_CONFLICT_REGISTER.md @@ -0,0 +1,8 @@ +# Cross-Document Conflict Register + +| Documents Involved | Nature of Contradiction | Probable Authoritative Source | Recommended Resolution | +|---|---|---|---| +| `docs/architecture/OVERVIEW.md` vs Repo Directory Root (`isa/`, `vm/`, `fs/`) | The overview maps sub-systems to `core/isa/`, `core/vm/`, `src/canonfs/`, but the actual directory structure is flattened (`isa/`, `vm/`, `fs/`). | Repo Directory Root | Update `docs/architecture/OVERVIEW.md` to reflect flattened repository structure (`isa/`, `vm/`, `fs/`, `include/t81/types/`). | +| `docs/ROADMAP.md` vs `docs/status/ROADMAP.md` | Duplicate roadmap documents. The `docs/status/` version is ~7x larger and likely the canonical tracking document, whereas `docs/ROADMAP.md` is shorter and likely an outdated summary or symlink that drifted. | `docs/status/ROADMAP.md` | Replace `docs/ROADMAP.md` with a direct relative link (markdown link or single-line redirect text) to `docs/status/ROADMAP.md`, or delete it completely if link hygiene allows. | +| `docs/HANDOFF.md` vs Directory Structure | Mentions architecture subsystems but doesn't explicitly misname paths like `OVERVIEW.md`, but relies on `OVERVIEW.md` for exact paths. It also links to `docs/ROADMAP.md`. | Directory Structure | Fix `OVERVIEW.md` first. Update `docs/ROADMAP.md` links to `docs/status/ROADMAP.md`. | +| `docs/BUILDABLE_NEXT_STEPS.md`, `docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md` | Outdated roadmap link. | Directory Structure | Update `docs/ROADMAP.md` links to `docs/status/ROADMAP.md`. | diff --git a/docs/records/audits/2026-03_documentation_refresh/OUTPUT_E_PRIORITIZED_REMEDIATION_PLAN.md b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_E_PRIORITIZED_REMEDIATION_PLAN.md new file mode 100644 index 000000000..26aca2055 --- /dev/null +++ b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_E_PRIORITIZED_REMEDIATION_PLAN.md @@ -0,0 +1,24 @@ +# Prioritized Remediation Plan + +## Priority 0: Critical Corrections Required Immediately + +1. **Target**: `docs/architecture/OVERVIEW.md` + - **Why**: Directly misleads contributors on codebase structure, breaking onboarding. + - **Action**: Update the "Architecture File Style Guide", "Current State by Layer", and "Evidence" sections. Change paths from `core/isa/` to `isa/`, `core/vm/` to `vm/`, `core/types/` to `include/t81/types/`, and `src/canonfs/` to `fs/`. + - **Evidence Required**: `ls -l isa/ vm/ fs/ include/t81/types/` confirms these directories exist at the root level. + +2. **Target**: `docs/ROADMAP.md` + - **Why**: Duplicate document causing split-brain confusion. The authoritative status roadmap is `docs/status/ROADMAP.md` (~21KB vs ~3KB). + - **Action**: Replace `docs/ROADMAP.md` with a stub pointing to `docs/status/ROADMAP.md` (or delete if link hygiene allows, but a stub prevents broken links). + - **Evidence Required**: `ls -l docs/ROADMAP.md docs/status/ROADMAP.md` + +3. **Target**: `scripts/governance/check_docs_structure.py` + - **Why**: Broken script causing CI/governance failures. + - **Action**: Fix the `BOOK_DIRS` array to point to `docs/book/book-*`. + +## Priority 1: Root Docs and Onboarding + +1. **Target**: `docs/HANDOFF.md`, `docs/BUILDABLE_NEXT_STEPS.md`, `docs/explanation/T81_FOUNDATION_PROJECT_PROFILE.md` + - **Why**: The entry points for serious contributors. Make sure they point to the correct paths and status documents. + - **Action**: Review references to architecture and status docs, ensure they align with the corrected paths from Priority 0 (`docs/status/ROADMAP.md`). + - **Evidence Required**: Run `check_active_docs_link_hygiene.py`. diff --git a/docs/records/audits/2026-03_documentation_refresh/OUTPUT_F_UPDATED_DOCUMENTS/docs/architecture/OVERVIEW.md b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_F_UPDATED_DOCUMENTS/docs/architecture/OVERVIEW.md new file mode 100644 index 000000000..61372990c --- /dev/null +++ b/docs/records/audits/2026-03_documentation_refresh/OUTPUT_F_UPDATED_DOCUMENTS/docs/architecture/OVERVIEW.md @@ -0,0 +1,102 @@ +# T81 Architecture Overview + +Status: Active +Last Verified (UTC): 2026-02-26 +Maturity: Mixed (`Frozen` core, `Experimental` periphery) + +> **Architecture File Style Guide** +> - Terminology mapping: "TISC ISA" -> `isa/`; "VM Interpreter" -> `vm/`; "Axion Governance Engine" -> `kernel/axion/`; "CanonFS" -> `fs/` + `include/t81/canonfs/`; "Experimental tiers" -> `experimental/`. +> - Link style: repo-relative markdown links to concrete files only. +> - Diagram conventions: GitHub-renderable Mermaid only. +> - Maturity labels: `Frozen`, `Stable`, `Experimental`, `Stubbed`. +> - Authority: `/spec` > `docs/architecture/OVERVIEW.md` > `/docs` > `/book`. + +## Purpose + +T81 is a ternary operating system for AI. This document is the canonical architecture snapshot of its implemented components, layer boundaries, and bounded determinism claim scope. + +## Layer Cake + +```mermaid +flowchart TD + L[T81Lang Frontend/Stdlib] + I[TISC ISA] + V[T81VM Interpreter] + A[Axion Policy Engine] + C[CanonFS] + X[Experimental: Cognitive Tiers + Hanoi Concepts] + + L --> I --> V --> A --> C + X -. optional / non-DCP .-> V + X -. optional / non-DCP .-> A +``` + +Diagram source: [`diagrams/overview-layer-cake.mmd`](./diagrams/overview-layer-cake.mmd) + +## Current State by Layer + +| Layer | Primary code | Primary spec | Maturity | Notes | +| :--- | :--- | :--- | :--- | :--- | +| Data types | `include/t81/types/` | [`spec/t81-data-types.md`](../../spec/t81-data-types.md) | Frozen | Deterministic-core surface. | +| TISC ISA | `isa/` + VM decode/dispatch | [`spec/tisc-spec.md`](../../spec/tisc-spec.md) | Frozen | Opcode semantics/freeze governed. | +| VM interpreter | `vm/` | [`spec/t81vm-spec.md`](../../spec/t81vm-spec.md) | Stable | DCP includes interpreter path, not JIT. | +| Axion governance | `kernel/axion/` | [`spec/axion-kernel.md`](../../spec/axion-kernel.md) | Stable (bounded) | Policy verdicts integrated in VM step path. | +| CanonFS | `fs/` + `include/t81/canonfs/` | [`spec/supplemental/canonfs-spec.md`](../../spec/supplemental/canonfs-spec.md) | Stable (bounded) | Integrity controls implemented; claims remain bounded. | +| Experimental tiers/kernel concepts | `experimental/` | [`spec/cognitive-tiers.md`](../../spec/cognitive-tiers.md), [`spec/supplemental/hanoi-kernel-spec.md`](../../spec/supplemental/hanoi-kernel-spec.md) | Experimental / Stubbed | Not part of DCP guarantees. | + +## Binary Host Execution Boundary + +T81 is a **ternary semantic architecture executed on binary hardware**. This is an intentional design choice, not a compromise. The platform implements native ternary semantics through a binary substrate compatibility layer: + +- **2-Bit Packed Trits**: Trits are packed using 2 bits per trit (0=N, 1=Z, 2=P), allowing 4 trits per byte, naturally aligning with binary storage. +- **SWAR Vectorization**: Operations on these packed trits use SIMD Within A Register (SWAR) techniques, delivering extreme performance on modern x86 and ARM processors without sacrificing ternary correctness. + +## Key Invariants + +1. Determinism claims are bounded to verified surfaces in [`DETERMINISTIC_CORE_PROFILE.md`](../product/DETERMINISTIC_CORE_PROFILE.md) and [`DETERMINISM_SURFACE_REGISTRY.md`](../governance/DETERMINISM_SURFACE_REGISTRY.md). +2. VM execution is policy-aware: interpreter dispatch and trace paths call Axion verdict evaluation before protected effects. +3. Fault behavior is explicit trap semantics, not undefined behavior (`include/t81/vm/traps.hpp` + VM dispatch checks). +4. Dependency boundaries are governed by [`DEPENDENCY_FIREWALL.md`](./DEPENDENCY_FIREWALL.md). + +## Execution Summary + +```mermaid +sequenceDiagram + participant FE as Frontend + participant ISA as TISC Program + participant VM as Interpreter + participant AX as Axion + participant FS as CanonFS + + FE->>ISA: deterministic bytecode emit + ISA->>VM: load_program() + VM->>AX: eval syscall context (step/opcode) + AX-->>VM: Allow/Warn/Deny + reason + VM->>FS: guarded persistence/read paths (when invoked) + VM-->>VM: trap or continue deterministically +``` + +Diagram source: [`diagrams/governance-axion-sequence.mmd`](./diagrams/governance-axion-sequence.mmd) + +## Indeterminate + +- Full JIT/interpreter semantic equivalence status is not asserted here. +- Universal cross-platform bit-identity for all floating-point transcendental behavior is not asserted here. + +## Evidence + +- [`vm/vm.cpp`](../../vm/vm.cpp) +- [`include/t81/vm/vm.hpp`](../../include/t81/vm/vm.hpp) +- [`include/t81/vm/state.hpp`](../../include/t81/vm/state.hpp) +- [`kernel/axion/policy_engine.cpp`](../../kernel/axion/policy_engine.cpp) +- [`fs/persistent_driver.cpp`](../../fs/persistent_driver.cpp) +- [`docs/product/DETERMINISTIC_CORE_PROFILE.md`](../product/DETERMINISTIC_CORE_PROFILE.md) +- [`docs/governance/DETERMINISM_SURFACE_REGISTRY.md`](../governance/DETERMINISM_SURFACE_REGISTRY.md) +- [`docs/status/IMPLEMENTATION_MATRIX.md`](../status/IMPLEMENTATION_MATRIX.md) + +## Acceptance Criteria + +- Every non-trivial claim maps to at least one item in **Evidence**. +- Implemented vs experimental surfaces are explicitly separated. +- Diagrams render in GitHub Markdown (Mermaid). +- Determinism statements are bounded to DCP/registry language. diff --git a/docs/records/audits/2026-03_documentation_refresh/README_MITIGATION.md b/docs/records/audits/2026-03_documentation_refresh/README_MITIGATION.md new file mode 100644 index 000000000..af19f82b0 --- /dev/null +++ b/docs/records/audits/2026-03_documentation_refresh/README_MITIGATION.md @@ -0,0 +1,3 @@ +# README Determinism Boundary Update +The translated versions of README (`README.es.md`, `README.pt-BR.md`, `README.ru.md`, `README.zh-CN.md`) require a specific mention of the "Determinism Surface Registry" or a direct link to `docs/governance/DETERMINISM_SURFACE_REGISTRY.md` to pass the `check_determinism_claims.py` governance script. +We will append the link to the end of each document as a small footer to fulfill this claim boundary. diff --git a/scripts/governance/check_docs_structure.py b/scripts/governance/check_docs_structure.py index 8637fab6d..8d18e6d9b 100755 --- a/scripts/governance/check_docs_structure.py +++ b/scripts/governance/check_docs_structure.py @@ -6,11 +6,11 @@ from pathlib import Path BOOK_DIRS = [ - "book/book-en", - "book/book-cn", - "book/book-es", - "book/book-pt", - "book/book-ru", + "docs/book/book-en", + "docs/book/book-cn", + "docs/book/book-es", + "docs/book/book-pt", + "docs/book/book-ru", ] REQUIRED_PREFIXES = {f"{n:02d}" for n in range(1, 16)} diff --git a/ternaryos/dev/gicv3.cpp b/ternaryos/dev/gicv3.cpp index abfb21a01..67e7b835d 100644 --- a/ternaryos/dev/gicv3.cpp +++ b/ternaryos/dev/gicv3.cpp @@ -133,7 +133,9 @@ void gicv3_init(uint64_t dist_base, uint64_t redist_base) noexcept { if (!(gicd_read32(redist_base, kGicrWaker) & kGicrWakerChildrenAsleep)) { break; } +#if defined(__aarch64__) && !defined(__APPLE__) && !defined(T81_TERNARYOS_HOSTED_BUILD) && !defined(_MSC_VER) __asm__ volatile("isb"); +#endif } // 3. Set all SGIs (0..15) and PPIs (16..31) in the SGI frame to Group 1 NS. diff --git a/ternaryos/tests/hal_boot_test.cpp b/ternaryos/tests/hal_boot_test.cpp index fdcc3b332..327d2b58c 100644 --- a/ternaryos/tests/hal_boot_test.cpp +++ b/ternaryos/tests/hal_boot_test.cpp @@ -8917,6 +8917,7 @@ static void test_kernel_abi_wire_blocks() { .supervisor_id = 89, .address_space_id = 97, .target_process_group_id = 101, + .thread_label = "test-label", .process_group_owned_page_count = 3, .process_group_pending_fault_count = 1, .runtime_boot_critical_address_space_count = 2,