Core store file
counters.toml
The ID authority, at .working/toml/counters.toml: one monotonic
high-water value per record namespace.
About
Every record ID has the form <NS>-<n>: a two-letter namespace mapped
one-to-one to its type (BI for backlog_item, FN for finding, WL for worklog, and so on) and a
positive integer. This file holds the highest integer ever allocated in each namespace. A
fresh store starts every counter at zero, covering the twelve baseline namespaces plus LF,
the importer's quarantine namespace, so an import can be accepted from day one.
Why
Durable records need permanent names. A backlog number that gets reused after a revert, or a finding ID that means two different things in two eras of the project, quietly corrupts every link and every audit trail that referenced it. A single monotonic counter per namespace, claimed atomically, makes ID permanence structural rather than a policy people must remember.
Description
The smallest schema in the store: a schema marker and one table of namespace-to-integer pairs. The scaffolded document, byte for byte:
schema = 1 [counters] AD = 0 BI = 0 BL = 0 CN = 0 DN = 0 FN = 0 HO = 0 LF = 0 MD = 0 PD = 0 PP = 0 RF = 0 WL = 0
How it works
Allocation increments the counter under the store's lock as one atomic claim, so no gap between choosing an ID and reserving it can double-allocate. Counters are never reset and IDs are never reused, even when a record is superseded, refuted, or its work reverted. Rotation, index rewrites, and store relocation never touch this file. The schema upgrade to 1.1.0 extends it with the CN, MD, and PP namespaces while preserving every existing high-water.
Generated view
None. Counters are a control ledger, not a record type; no view renders from them.
Value
Permanent IDs make every cross-reference in the store durable: a link written today still resolves years and relocations later. The integrity gate checks that every live ID fits within its counter and that counters only ever grow, which helps prevent silent renumbering from entering the record at all.
Usage
- Created by:
opf init, all namespaces at zero. - Updated by: ID allocation, atomically under the store lock, whenever any process creates a record in any type;
opf upgradeextends the namespace roster. - Read by:
opf doctor(counter completeness, monotonicity against a prior committed snapshot, and every live or archived ID within its high-water); record creation, to allocate the next ID.