machine .toml source > generated view > drift gate

Core store file

manifest.toml

The store's control document and discovery marker, at .working/toml/manifest.toml. Everything a tool needs to know about a store, it learns here first.

About

The manifest declares what this store is (the base [opf] table, carrying the exact discovery token standard = "opf" and the spec version the store conforms to), how it is stored and enforced (layout, posture, import status), which optional modules and record types are enabled, which views and deliverables it generates, and which providers, vendor extensions, and unmanaged paths it recognizes. Tooling locates the machine store by finding exactly one immediate subdirectory of .working/ whose manifest declares the token; zero matches or more than one stops the tool, never guesses.

Why

A store with no self-declaration forces every tool to assume, and assumptions drift. The manifest makes the store's contract explicit and machine-checkable: 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. Because the machine subdirectory is observed at each use rather than declared and trusted, renaming it is a directory move with nothing to go stale.

Description

Closed keysets throughout: an unknown key in any base section is a validation finding. The top-level tables:

[opf]           standard, spec_version, 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 (version, base_compat, posture_floor,
                required_modules, extension_namespace); may only ADD requirements
[types.*]       one table per enabled type, carrying its normative namespace
[providers.*]   handler + roles (create, auth, sync); local-directory and
                generic-git-remote ship as universal fallbacks
[views.*]       kind (deterministic | composed | 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

The reference scaffold writes: every module false, no profile, an empty vendor registry, posture = "required", import_status = "none", layout = "inline", the twelve baseline type bindings, and thirteen declared views (the twelve Markdown views plus the DECISIONS.toml projection), each targeting .working/<name>.

How it works

Every OPF operation resolves the store through the pointer, then validates the manifest before acting; an unreadable or unparseable manifest is a cannot-evaluate that stops the tool. A profile a tool supports is enforced fail-closed; a profile it does not support is ignored for enforcement and recorded as unevaluated, so an unknown profile does not fail base validation. Weakening the posture (required toward warn or off) is a guardrail-configuration change: it takes effect only through the maintainer's explicit, recorded authorization, and a profile floor can raise, never lower, the effective posture.

Generated view

None. The manifest is control data, not a record source; it has no paired Markdown view. It is, however, what declares every other pair: the [views.*] map is the registry the renderer and the drift gate read.

Value

One reviewed file settles what would otherwise live in tool defaults and tribal knowledge. Because the manifest is validated on every load and its keysets are closed, a misconfiguration surfaces as a named finding at the point of use, which helps prevent a tool from operating on a store it misunderstands.

Usage

  • Created by: opf init, validated before a byte is written.
  • Updated by: opf upgrade (a canonical model regeneration, never a textual edit, for the 1.0.0 to 1.1.0 schema migration); the adopter's own reviewed edit to enable a module, register a vendor, or record an unmanaged path; opf migrate (when it ships) re-points the recorded sync target.
  • Read by: every verb at store resolution; opf render for the view map; opf doctor for posture, types, modules, unmanaged containment, and pointer-to-sync-target agreement.