Reference

Technical details: the store and the tooling

The store's control and ledger files: the manifest that declares the store, the ID counters, the version ledger, the worklog (appended per change, correctable until released, then frozen), and the concurrency lease. The record indexes and the files around them follow, 1 line each, then the reference tooling: its commands, what it checks, and how to verify it.

manifest.toml

The store manifest

The store's control document and discovery marker: declarations for its schema, types, views, modules, and enforcement posture. Closed keysets throughout: an unknown key in any base section is a validation finding. The base [opf] table carries the exact discovery token standard = "opf", the spec version the store conforms to, and the homes generation. The base of a spec 2.0.0 store:

.working/toml/manifest.toml

[opf]
standard = "opf"
spec_version = "2.0.0"
homes = 2
layout = "inline"
posture = "required"
import_status = "none"

[modules]
governance = false

Note

The reference tooling does not yet implement spec 2.0.0: its scaffold still writes spec_version = "1.2.0" with no homes key.

The top-level tables

11 tables

The top-level tables of the store manifest
Table	Holds
`[opf]`	standard, spec_version, homes (2), layout (inline \| per-record), posture (off \| warn \| required), import_status (none \| partial \| complete)
`[store]`	sync_target (empty under the in-repo default)
`[modules]`	governance, delivery_assurance, operational_policy, concurrent_operation
`[profiles.*]`	additive requirement bundles; may only add requirements
`[types.*]`	1 table per enabled type, carrying its normative namespace
`[providers.*]`	handler and roles (create, auth, sync); local-directory and generic-git-remote ship as universal fallbacks
`[views.*]`	kind (deterministic, composed or projection), sources, target
`[deliverables.*]`	the curated CHANGELOG.md declaration
`[archive]`	period ("year")
`[unmanaged]`	pre-existing files kept in place, enumerated
`[vendors]`	registered x-<vendor> extension namespaces

Declare the store contract so tools need not infer it.

A tool validates the base before operating, enforces only what is declared, and records a profile it does not support as present-but-unevaluated rather than failing over it. Tooling locates the machine store by finding exactly 1 immediate subdirectory of .working/ whose manifest declares the token. 0 matches or more than 1 stops the tool, never guesses.

At a glance

Declares: [opf] [modules] [types.*] [views.*] [providers.*] [profiles.*]
Read by: opf render, opf doctor, opf absorb, opf record
Written by: opf init, a reviewed adopter edit, and opf migrate (in progress; it exits 2 in the reference CLI)

counters.toml

The ID counters

The ID authority: 1 monotonic high-water value per record namespace.

version.toml

The version ledger

The version and release ledger: numbers, dates, spans, and digests, never release prose.

worklog.toml

The worklog

The detailed operational record: 1 entry per change, appended as the work happens. Entries are correctable until released, then frozen.

lease.toml

The single-writer lease

Present only while a run holds the store's single-writer lease; its absence is the normal state.

Record indexes

The backlog

11 baseline typed indexes, their declared generated views, and the planned module schemas. One record per unit of planned work, with a permanent ID, a closed set of states, and a "done" that is ratified.

Completion receipts

A durable completion receipt, created in its single terminal state and immutable from birth.

Created by opf init (empty index), by the ratified-done transition, and, as migrated history with provenance, by import (the reference CLI's retired importer, or post-adoption import, which the reference CLI does not implement yet); never updated, since records are immutable, though rotation relocates aged receipts to the archive; read by opf render (DONE.md and the mirror) and validated by opf doctor (schema, uniqueness, the one-to-one receipt link).

The finding register

An observation worth acting on, which links its remediation rather than containing it.

Pending decisions

A question that must be answered before dependent work settles.

Self-made decisions, on the record

A call an actor was authorized to make itself, with its basis, the action taken, and links to what it affected.

Rulings the maintainer made

A created-terminal, immutable ruling carrying its decision, the answer plus its rationale.

Standing preferences, distilled

The reusable rule beneath a family of individual rulings.

Blocks

A record that named work cannot proceed; it scopes an enumerated list of record IDs.

The session handoff

The durable state snapshot a session resumes from, with at most 1 current handoff at any time.

Sources, captured at the claim

An immutable captured source, recorded at the moment a claim or artefact that rests on it is produced.

Work proposed or sent to a peer project

It tracks proposal, delivery, and outcome.

Optional modules and importer types

4 optional modules, default-off.

Reserved namespace No module toggle: the standard reserves LF unassigned, with no record type on it (spec section 8.1). The reference tooling still recognizes legacy_fragment (LF, quarantined → resolved | ignored) in stores that hold such records from its retired import path; nothing in the reference CLI creates it now.

(none) LF reserved unassigned; the reference tooling still recognizes legacy_fragment (quarantined → resolved | ignored) in stores holding such records from its retired import path.

The standard reserves the LF namespace unassigned and defines no legacy_fragment type (spec section 8.1); the reference tooling still recognizes the type in existing stores and never scaffolds it.

Under the reference tooling's retired import contract, everything an import could not confidently map became quarantined fragment data with source path, digest, span, and run ID, so nothing was dropped.

Ordinary import is now retired and refuses with exit 2, nothing in the reference CLI creates legacy_fragment records, and the standard directs new imports to the imported series with verbatim unparsed text instead (spec section 8.1); the type remains in the tooling for existing stores and evidence.

A new store's counters file has no LF namespace; a store scaffolded by earlier reference tooling may carry LF (at zero, or higher if it imported records), and doctor and re-adoption accept it. That acceptance is the reference tooling's 1.2.0 behaviour and diverges from the standard, whose section 9.2 validation refuses a 1.2.0 manifest as a store.

Around the records

The store pointer

The committed pointer that names where the store repository lives. A pointer that does not resolve stops the tool and never falls back silently to the default location.

The archive

1 rotation manifest per calendar-year bucket: rotation is relocation, never deletion, and never ID reuse.

The decisions projection

The machine projection, generated at .working/DECISIONS.toml and rendered from the 4 decision types.

Tooling

The reference tooling

Reference CLI status. Available: init, render, doctor, absorb. Partial: record (create, transition, done-with-receipt, and worklog-append; receipt-repair exits 2), adopt (plan, approve, reconcile, and status; apply and complete exit 2). In progress: upgrade, import, migrate, sync; each exits 2 in this build. A base adopter can use their own tooling instead, or adopt by hand.

The command verbs
Verb	What it does
`init`	Scaffolds validated store sources and the committed pointer; surfaces, never absorbs, anything already at the store location.
`render`	Regenerates the declared views. `--check` compares bytes read-only and exits 1 on drift.
`doctor`	Runs the whole-store integrity layer read-only: exit 0 valid, 1 on a finding, 2 when it cannot evaluate. `--require-store` makes a missing store a cannot-evaluate for CI. `--store-identity` instead compares the committed pointer's target and the SHA-256 of the store's `init.toml` with the values pinned in `.github/opf-store-identity.toml` (`schema = 1`, `target`, `init_sha256`), and treats a `.opf.local.toml` override as a mismatch only when every other input evaluates; otherwise the result is cannot-evaluate.
`absorb`	Drafts changelog entries for human curation, or computes a curated entry's freeze digest; writes no files.
`record`	Authors 1 record change at a time and leaves it uncommitted for your review.
`adopt`	Plan, approve, reconcile, and status run; apply and complete refuse with exit 2.
`upgrade`	Refuses with exit 2 and writes nothing: the reference tooling defines no store upgrade.
`import`	The ordinary modes are retired and refuse with exit 2; clean-start adoption is the intake.
`migrate`	In progress; exits 2 in this build. Relocates the whole store, keeping git history and the worklog.
`sync`	In progress; exits 2 in this build. The pull and push step of the store consistency contract.

Coverage

What doctor checks

Schema validity; ID uniqueness and counter monotonicity; bidirectional index reconciliation; transition legality where observations suffice; byte drift for the declared baseline views; the root release-version file; worklog span tiling and frozen digests; changelog coverage and freeze; archive integrity; the tracked-store requirement; pointer and sync-target agreement; and path containment. At the strictest posture, an unreadable, unparseable, or unresolvable declared input is a failure, never an empty or clean result.

Integrity

Verify what you install

Before applying a downloaded pack, compare its digest with the reference published for that release at posluns.dev/hashes.txt (opens in a new tab), and refuse on a mismatch. The tooling also checks its own declaration file, opf/tools/opf-declaration.toml, against a shipped digest before it touches a store, and refuses with exit 2 if the file is missing or altered. python3 -I -B opf/tools/opf.py --declaration runs that check alone.

opf/tools/opf-declaration.toml

release = "1.0.5"
spec_version = "1.2.0"
homes = 1
worklog = 1

Create the store with opf init, or ask your assistant for a plan.

Adopt it