Document Status
This page is the front door for determining what Tosumu documentation means, how much authority it carries, and whether its work is current, pending, or historical.
Status Vocabulary
Authority and lifecycle are separate:
| Dimension | Value | Meaning |
|---|---|---|
| Authority | Normative | Defines a current Tosumu contract. Code and public docs must agree with it. |
| Authority | Binding | Records an accepted architectural decision until it is superseded. |
| Authority | Tracking | Sequences or reports work but does not create architecture. |
| Authority | Evidence | Preserves findings and alternatives without deciding them alone. |
| Authority | Informative | Provides explanation, context, or research only. |
| Lifecycle | Current | Describes the present supported or governing state. |
| Lifecycle | Active | Work is approved and currently being advanced. |
| Lifecycle | Proposed | Work is defined but has not been admitted for implementation. |
| Lifecycle | Incubating | Evidence is being gathered before a durable decision. |
| Lifecycle | Deferred | Intentionally waiting for a named trigger or dependency. |
| Lifecycle | Completed | In-scope work and acceptance criteria are complete. |
| Lifecycle | Historical | Retained for context; it does not describe current work. |
| Lifecycle | Superseded | Replaced by a named successor. |
Draft describes editorial stability, not authority. A normative pre-stability
specification may still be a draft while remaining the current contract.
Engineering Specifications
Durable design, error, and inspection contracts live together under
Specifications/. The repository-root
SECURITY.md remains in its conventional location for GitHub security tooling
and responsible-disclosure discovery.
| Document | Authority | Lifecycle | Scope |
|---|---|---|---|
| Tosumu Software Design Document | Normative | Current, pre-stability | Architecture, format, goals, and staged design |
| Tosumu Error Design Document | Normative | Current | Public structured error contract |
| Tosumu Inspect API Specification | Normative | Current | Machine-readable inspection contract |
Repository root: SECURITY.md |
Normative | Current, pre-audit | Threat model, limitations, and disclosure policy |
| Tosumu Reference Implementations | Informative | Current | External references and implementation influences |
The Tosumu Software Design Document contains both implemented architecture and clearly labeled future or deferred material. The current separation work is tracked by the Documentation Lifecycle And Design Decomposition Plan.
Curated Public Documentation
The top-level pages under docs/ are current user-facing explanations. They
are informative summaries and must agree with the normative root
specifications and accepted ADRs.
| Area | Lifecycle |
|---|---|
| Getting started, concepts, architecture, format, errors, inspection, CLI, safety | Current |
| Public roadmap | Current summary; implementation status is tracked by the main feature roadmap |
| Tosumu Command Language | Proposed / exploratory; not a supported command surface |
Accepted Decisions
| Record | Status |
|---|---|
| ADR-0001: Storage Engine Layer Boundaries | Accepted / binding |
| ADR-0002: Authenticated Pager Trust Boundary | Accepted / binding |
| ADR-0003: Source Unit Cohesion, Size Pressure, And Decomposition | Accepted / binding |
| ADR-0004: Cooperative Single-Writer Admission | Accepted / binding |
| ADR-0005: Committed Generation And Retained-WAL Snapshots | Accepted / binding |
| ADR-0006: Shared KV Store And Snapshot Transactions | Accepted / binding |
| ADR-0007: Database-Generation Conditional Writes | Accepted / binding |
| ADR-0008: SQL-Owned Secondary Index Keyspaces | Accepted / binding |
| ADR-0009: Offline VACUUM Rebuild Publication | Accepted / binding |
| ADR-0010: Private Format-v3 Cryptographic Mechanism Seams | Accepted / binding |
Architectural Reviews
AR-0009 is Accepted through ADR-0004, ADR-0005, and ADR-0006. AR-0011 is Accepted through ADR-0005, AR-0012 through ADR-0007, AR-0013 through ADR-0008, AR-0014 through ADR-0009, and the private Gate C1 portion of AR-0016 through ADR-0010. Other unresolved portions and current reviews, including the new replication scope review, are Incubating and do not change accepted architecture by themselves.
| Record | Question |
|---|---|
| AR-0001 | TQL ownership and lowering |
| AR-0002 | Reusable inspection facts versus CLI serialization |
| AR-0003 | Embedded, daemon, and remote authority boundaries |
| AR-0004 | Semantic history and sync ownership |
| AR-0005 | Witness, observer, and freshness evidence |
| AR-0006 | Format evolution and migration ownership |
| AR-0007 | Proportional evidence and resilience gates for core changes and risky crossings |
| AR-0008 | Terminal outcome and crash-observation evidence |
| AR-0009 | Multiple-reader visibility, locking, and execution ownership |
| AR-0010 | Dependency trust, exact source identity, and release provenance |
| AR-0011 | Accepted committed-generation, retained-WAL, checkpoint, and format-v3 evidence |
| AR-0012 | Database-generation tokens and conditional-write outcomes |
| AR-0013 | SQL-owned secondary-index representation and atomic maintenance |
| AR-0014 | Offline VACUUM rebuild and atomic publication |
| AR-0015 | Native replication scope, authority, identity, failure, and fencing boundaries |
| AR-0016 | Cryptographic backend, entropy, protector, suite-identity, and conservation boundaries |
Implementation Plans
| Plan | Lifecycle | Next action |
|---|---|---|
| Main Feature Roadmap | Active | Plan plain single-column secondary indexes with atomic mutation and recovery evidence |
| Initial SQL Layer | Completed baseline; retained | Resolve separately listed deferred SQL scope only through new evidence or a follow-up plan |
| Tosumu Command Language | Proposed | Complete Slice 0 evidence and retain AR-0001 ownership review |
| Documentation Lifecycle And Design Decomposition | Active | Apply metadata and separate current design from future proposals incrementally |
| Public Website And Repository Records | Proposed | Validate indexed navigation, then curate the public reader path separately from GitHub work records |
| Core Source Unit Decomposition | Completed | Maintain the behavior-preserving private-module boundaries and conservation evidence |
| Cluster Fault Tolerance And Replication | Proposed; admission required | Continue AR-0015 scope and authority evidence before native replication protocol work |
| High-Assurance Engineering And Evidence Export | Slice 1 active; assurance claims not admitted | Classify and audit the initial tosumu-core critical dependency closure under AR-0010 |
| Cryptographic Provider Seam And Suite Agility | Gate C1 admitted; later architecture not admitted | Implement ADR-0010 private format-v3 and entropy facades with full conservation evidence |
Change Requests
TOKIMU-001 is accepted with Tosumu provider scope complete. The Tokimu-side adapter remains the consumer's work and does not keep the Tosumu request active. See the Change Request index.
Supporting Material
| Collection | Lifecycle rule |
|---|---|
| Notes | Informative observations; promote when they become decisions or work |
| Conversations | Unreviewed source material |
| Archive | Historical or superseded support material |
.workbench/ |
Local scratch material; never authoritative |
Maintenance Rule
When a document changes lifecycle, update this page and its collection index in the same change. A document is not completed merely because implementation moved elsewhere; completed work must name its validation evidence and any remaining deferred scope.