Foundry
Home Schema

Cast provenance (_provenance.json, schema v2)

_provenance.json contract beside every cast: Mold revision, per-ref deterministic-vs-LLM origin, src/dst hashes, artifact handoff. Schema v2.

draft schema
Revised
2026-05-17
Rev
1
schema cast-provenance upstream ↗

Cast Provenance

Forensic record of a cast: what got produced, from which Mold revision, by which method, and what each ref's deterministic vs LLM provenance looks like.

2 sections. Anchor links per section (e.g. #root) are stable.

Cast Provenance

root

Forensic record of a cast: what got produced, from which Mold revision, by which method, and what each ref's deterministic vs LLM provenance looks like.

field type req description
cast_target string ✓
mold object ✓
provenance_schema_version = "2" const "2" ✓
refs → #/definitions/refEntry[] ✓ One entry per resolved reference, sorted by (kind, src) for stability.
artifacts object Pipeline artifact handoff contract copied from the Mold's frontmatter so harnesses can wire prior-step paths to a stable id.
cast_agent string
cast_at string
cast_date string
cast_history object[]
cast_method string
cast_revision integer
open_questions string[]
validation_results object[] Process evidence from artifact validator CLI runs. Exit code is authoritative; stdout/stderr are captured as opaque diagnostics.

refEntry

refEntry
field type req description
dst string ✓ Bundle-relative destination path.
kind any ✓
load any ✓
mode any ✓
source any ✓ Whether this ref's dst content was produced deterministically or by an LLM step.
src string ✓ Resolved repo-relative source path.
used_at any ✓
companion_of string Bundle-relative dst of the parent note when this ref is a sibling companion file copied alongside it.
dst_hash string | null sha256 of destination file at cast time. Null when pending_llm.
evidence any
model object LLM identity when source=llm. Optional but strongly recommended.
pending_llm boolean True when mode=condense and the LLM phase has not yet filled this entry. Verifier rejects committed provenance with any pending_llm=true.
prompt object Required when source=llm. Identifies the prompt used so casts can be reproduced.
purpose string
ref string The original Mold ref (wiki-link or path).
src_hash string | null sha256 of source file at cast time. Null only when pending_llm and source is a generated artifact.
trigger string
verification string

Every cast bundle carries a sibling _provenance.json: the forensic record of what was produced, from which Mold revision, by which method, and what each reference’s deterministic-vs-LLM provenance looks like. It is required, but it is not part of the skill — consumers read SKILL.md and references/; maintainers read _provenance.json.

Contract of record. The authoritative schema is the repo-local JSON Schema at scripts/lib/schemas/cast-provenance.schema.json (provenance_schema_version is a const: 2). It is Foundry-authored — there is no upstream package and no package_export; the upstream link above points at the in-repo file. The narrative in docs/COMPILATION_PIPELINE.md describes why the shape is what it is; this note plus the JSON Schema are the contract. When the two disagree, the JSON Schema wins.

Enforcement. The deterministic verifier scripts/cast-skill-verify.ts AJV-validates every committed _provenance.json against the schema and additionally rejects any entry still carrying pending_llm: true (an unfilled mode: condense placeholder). The verifier — not a packaged validator_bin — is the enforcement point, which is why this note declares neither package nor validator_bin.

Versioning. provenance_schema_version is a hard const, currently 2. A future v3 is a deliberate schema bump: change the const, migrate or re-cast existing bundles, and revise this note rather than silently widening v2. Old bundles do not auto-upgrade; foundry status surfaces staleness and foundry cast regenerates.

What it records

  • mold — name, source path, revision, content_hash, and the commit the cast was taken from. Drift detection compares the live Mold index.md content hash against mold.content_hash; a mismatch marks the cast stale.
  • refs[] — one entry per resolved typed reference, sorted by (kind, src) for stable diffs. Each records mode (verbatim / condense / sidecar), resolved src and bundle dst, src_hash / dst_hash (sha256 at cast time), and source (deterministic vs llm). Verbatim copies and sidecars are deterministic; only mode: condense refs are LLM-produced.
  • LLM provenance — when source: llm, the entry must carry prompt (origin + identity, optionally hash) so a cast can be reproduced; model (name/version) is optional but strongly recommended. pending_llm: true marks a condense slot the deterministic phase emitted but the LLM phase has not yet filled — committed provenance with any such entry fails verification.
  • artifacts — the pipeline handoff contract copied from the Mold’s frontmatter: produces[] (with producer-owned schema) and consumes[] (with inherited_schema and resolved producers), so a harness can wire a prior step’s output path to a stable id.
  • validation_results[] — process evidence from artifact-validator CLI runs: validator_bin, status (passed / failed / error), exit_code (authoritative), and captured stdout / stderr plus their hashes (opaque diagnostics).

Why it exists

Provenance is the foundation for three things the Foundry promises: drift detection (Mold or ref changed since the cast), reproducibility audits (which prompt and model produced a condensed reference), and “why does this cast contain X” forensics (every dst traces back to a Mold ref and a src hash). Deterministic assembly is expected to be byte-stable aside from timestamps and cast_history; explicit LLM condensation is not guaranteed byte-identical, but source, prompt, and model make each LLM-produced byte reviewable.

The field tables below are generated from the JSON Schema itself; anchors are stable for deep-linking from Mold bodies and design docs.