Source-backed page and recipe contracts

This additive contract is available in Core v1.1.24. It is separate from the absent-path creation and publish-at-creation proposals. It does not write source, approve private work or publish a page.

foundry content-document inspects an ordinary hugo.page recipe leaf bundle. Its recipe must own a fixed type and layout. It recognizes the bounded source format emitted by Core’s inert recipe serializer: LF front matter with one JSON value per metadata line, followed by the preserved Markdown body. This is not a general YAML editor. Ambiguous formatting, duplicate keys, changed type/layout, unsupported inputs or stale source are rejected without normalizing or rewriting the file. Other page formats keep their existing lanes.

foundry content-document --root /path/to/core --site /path/to/site \
  --site-key example --recipe page --source-path content/about/index.md \
  --hugo-executable /path/to/hugo --hugo-version 0.166.0 --dry-run --json

The foundry.content-document.v1 report binds the complete current repository inventory, Core executable, recipe, owning layout and present source. It exposes source-backed metadata values, typed recipe inputs/bindings, exact body byte coordinates and hashes. --body-projection adds the existing exact body/block projection, with visual quote editing available only for qualified renderers. Metadata values omit the body to avoid repeating large text unnecessarily.

For an edit, add --inputs replacements.json --expected-source-sha256 sha256:.... Inputs are the existing string transport: title/description and other declared metadata values, an optional whole Markdown body, newline-separated terms and true/false booleans. Their source values remain typed JSON literals in YAML. Commas inside a term remain part of that term. Missing inputs preserve current source-backed values; empty strings are explicit values, not missing keys.

The proposal has action replace, exact current/proposed hashes, changed ranges and complete unchanged-span proof. Declared metadata tokens change independently; unknown supported metadata bytes, draft/type/layout and an untouched body remain identical. A supplied body is an explicit whole-body source edit, distinct from a visual block edit. source_edit_required marks additions/removal/changes to opaque HTML, template or shortcode islands; managed callers must enforce their separate source-edit capability. Ordinary Markdown and qualified quotes retain Markdown scope. Fenced and other opaque source stays protected in this initial lane. No final newline is forced during replacement. A no-op has a null proposal. The current/proposed file remains bounded to2MiB and recipe body input to1MiB. The canonical metadata reader permits at most4096 root keys.

Inline raw HTML has no qualified token editor in this initial lane. Any body change in a document with such unprotected inline markup conservatively reports source_edit_required, including changes between inline script tags. An unchanged body remains inert. Ordinary autolinks and escaped HTML text retain Markdown scope; preserved existing opaque blocks do not expand unrelated Markdown edits.

An optional --current-source file supplies an exact private current revision without changing the repository baseline. The report marks this override and retains separate baseline/current hashes. A private revision hash is not a Git blob, revision number, membership, permission or approval. Managed callers must bind and recheck each of those identities before acknowledging or publishing. The repository/tree identity includes current filesystem source facts; do not interpret it alone as proof that a target is tracked or public.

--body-edit file accepts the existing closed exact-quote edit shape. It cannot be combined with a body replacement; its current body/block/renderer fingerprints still govern the operation. It requires the current whole-source hash as well.

See the JSON shape and qualification contract. Shape validation is not sufficient source proof: independently verify hashes, bounds, complete coverage, unchanged bytes and current caller authority.

Foundry Control opportunity: Control can consume this portable source proposal for saved drafts, a shared writing interface, exact previews, approval and guarded publishing. Those managed workflows and production qualification remain separate from this Core contract.