Module document 

Documents — a plaintext file with an embedded metadata block and a body, or a config file whose entire content is the metadata.

The two shapes are one model: a config file is simply a document whose metadata carrier is the whole file and whose body is empty. Both parse to the same Document, link through the same relations, and participate in traversal, validation, and mutation identically — which is what lets a workspace mix prose documents and config documents in one tree.

Structs

Document

A parsed document: its path, its embedded metadata, and its body text.

Enums

EmbedStyle

The archetype family a workspace authors embedded metadata in — the “embed type” the CLI’s init prompts for, one level above the concrete EmbedType. A family plus a metadata fig::Format resolves to a carrier through embed_carrier: e.g. (CodeBlock, YAML) is a ```yaml block, (Delimited, TOML) is a +++ block, and (Separate, JSON) is a whole-file .json sidecar. It is what the config document records (via prov’s WorkspaceConfig) so a workspace stays self-describing about how its metadata is embedded, not just which format it is written in.

EmbedType

The embed archetype a fenced metadata block was found in. Re-exported from fig, which owns both detection (fig::detect) and the fence/format coupling (EmbedType::inner_format). Which embedded config to open — the flat mirror of fig’s parametric Embed.Type. The three parametric families (markdown ---<lang> frontmatter, ```<lang> fenced blocks, <script type> HTML data islands) are enumerated once per format. The first four names are historical (FrontmatterJson is the ;;; block, FrontmatterFig is the ```fig fenced block); the rest are grouped by container.

MetaCarrier

Where a document’s metadata physically lives — recorded at parse time so a write can preserve the original carrier exactly (a ```fig block is never rewritten as --- YAML; a bare .yaml file never grows fences).

Functions

embed_carrier

Resolve an EmbedStyle + metadata format to the carrier a new document should get. Separate maps to a whole-file sidecar in format; every other style maps to the concrete EmbedType for that (style, format) pair. None for a combination that has no archetype — notably Delimited + fig (the dialect has no ----style delimiter) and any fenced style paired with a format fig cannot fence (Zon).

embed_style_of

The EmbedStyle family a concrete EmbedType belongs to — the inverse (on the style axis) of embed_carrier, which resolves a (style, format) pair back to a carrier. Pairing it with a new metadata format is how a format conversion keeps a document’s embedding shape while changing only its frontmatter language: classify the current archetype, then embed_carrier the same style with the target format.

frontmatter_carrier

The fenced-frontmatter carrier for format — the archetype a new document gets when it inherits no parent block and the workspace default is format. A format whose feature is not compiled falls back to YAML frontmatter (which the default yaml feature always provides).

is_opaque_payload

Whether prov can read path as text — a recognized body format (Markdown/Djot/HTML) or a whole-file metadata format (YAML/JSON/…). Its negation is an opaque payload: a file prov treats as bytes (an image, a PDF, a font, any binary) and never parses. An attachment is exactly a whole-file metadata sidecar whose content points at such a payload, which is how an arbitrary file gains workspace-linked metadata without being able to carry frontmatter itself.

require_whole_file

Enforce that a record store at path (the id registry, the recycle-bin index, a flat vocabulary) is a whole-file config document, returning its format. A MetaCarrier::Fenced carrier — markdown frontmatter — is rejected with Error::MarkdownStore: prov re-lays-out these stores as a sorted record list (DESIGN §5), so human prose has no stable home in them and unambiguous extension→format sniffing depends on the carrier being whole-file. The single choke point every store loader passes through, so the rule cannot be enforced in one place and forgotten in another.

whole_file_extension

The canonical whole-file extension for a metadata format — the inverse of whole_file_format. Used when materializing a whole-file metadata document (a config/registry sidecar, or the metadata half of a separated document): yaml, json, figl. A format whose feature is not compiled falls back to yaml (the always-present default).

whole_file_format

The whole-file metadata format implied by path’s extension, if any. These are the extensions prov treats as config documents.