Model provenance for derivations
Every LLM-produced derivation is produced by a particular model, runner, prompt shape, and surrounding context. That fact matters, but the right storage surface is still an open design question. The current review DB placement is a working implementation, not proof that model provenance should always live outside markdown artifacts.
Review Relation
The current review freshness key is:
note_path x criterion_path x model_partition
The storage-driving relation is note_path x criterion_path: a note is assayed against many criteria, criteria apply to many notes, and the review state belongs to their edge. Criteria include verdict gates, type/collection conformance documents, and the open-ended critique instruction. model_partition partitions that edge state. It is not a property of either endpoint file, and it is not necessarily the literal observed model. The model-side partition lives in review lineage state:
review_jobs.model_partitionrecords the declared partition for one review invocation;review_pairsinherit that partition from their parent job;acceptance.model_partitionmakes current acceptance specific to the partition;- selectors compare current note/criterion content hashes against the accepted baseline for
(note_path, criterion_path, model_partition).
model_partition is now an implemented, normalized identity dimension. Optional finalization-time runner_model and runner_effort must map back to the job's declared partition; runner identity and opaque telemetry remain provenance rather than freshness identity. Per-pair result frontmatter carries both the partition and any available runner/model/effort fields for inspection without making the Markdown file canonical state.
That is why review freshness is operationally keyed by note_path x criterion_path x model_partition, even though the reviewed note and criterion are durable markdown endpoints. review_pairs.result_kind separately fixes whether completion produces a verdict or a decisionless report; it is protocol state, not another freshness-key dimension. In the current implementation, the model dimension is derivation-state metadata stored in the DB. Rendered result artifacts also carry the available partition/runner/model/effort provenance for inspection without becoming canonical state.
This is also why one model's assay cannot satisfy another model's freshness. A verdict or open-ended report is model-conditioned evidence. The same note and criterion run under a different partition is different edge state.
General Rule
Model provenance belongs on the derivation event or generated derivative, not automatically on the durable artifact being edited.
| artifact situation | model provenance rule |
|---|---|
| One-shot retained derivative | Strong candidate for model/runner/prompt metadata in frontmatter, because the artifact is the derivation. |
| Generated report that remains inspectable | Record model in report frontmatter, run manifest, or DB row; frontmatter may be preferable for typed standalone reports. |
| Review freshness state | Declared model partition is part of the freshness key: (note_path, criterion_path, model_partition). |
| Canonical note edited from reports | Do not store "last edited by model" in note frontmatter. Record model in commit message, merge-back event, or lineage ledger if needed. |
| Durable source analysis generated once | Strong candidate for a frontmatter model field, because the artifact is the derivation. |
| Deterministic generated view | Record generator/tool version rather than model. |
The distinction is between artifact identity and update provenance. A generated report, ingest, review, cue, or source analysis is itself the derivative; its producer model is part of its provenance. A canonical note may be edited many times by different agents and models; storing the last model on the note would be noisy, stale immediately, and semantically weak. The note's content is the durable object. The model belongs to the edit event that produced a version, not to the note as a stable property.
Frontmatter Candidate
Some derivative types should probably require or allow model provenance in frontmatter. Good candidates are retained artifacts whose content is primarily the output of one generation event:
- generated reports kept for inspection;
- source ingests generated by an LLM rather than mechanically captured;
- agent-memory-system reviews and other source analyses;
- adapted-from artifacts promoted into durable artifacts;
- compiled cues or prompt surfaces when generated by an LLM rather than deterministically rendered.
Possible fields:
generated_by_model: claude-3-5-sonnet
generated_by_runner: codex
generated_at: "2026-06-24T12:00:00Z"
generation_prompt: kb/reports/.../prompt.md
generation_source_manifest: kb/reports/.../MANIFEST.json
The field names should not be chosen casually. The workshop should decide whether model provenance belongs in every derivative type's schema, in a shared generated-artifact frontmatter block, or in per-run manifests with selected fields copied into frontmatter for standalone readability.
Merge-Back Implication
When a generated report drives an edit to a canonical artifact, there may be two model facts:
- the model that generated the report;
- the model or agent that performed the merge-back edit.
Both can matter for audit and debugging, but neither should become ordinary note metadata. Good carriers are:
- git commit messages for low-volume merge-back;
- an append-only merge-back ledger if report-driven edits become common;
- a DB row if merge-back becomes high-churn edge state over artifact/source/producer relations.
For current manual or agent-assisted edits, commit messages may be enough. For generated artifacts retained as standalone products, model metadata should travel with the artifact.
Open Questions
- Outside review, which derivatives need a declared model partition as identity, and which need only the literal observed producer model as provenance?
- Should generated reports and durable source analyses have a shared frontmatter provenance block that records model, runner, prompt/gate version, source versions, and generation time?
- When a retained derivative is revised by another model, does it keep a history of producer models or only the latest generation event?
- Should model provenance be required only for generated artifacts with durable authority, or also for gitignored reports used as merge-back inputs?
- Which derivative types should put model provenance in frontmatter rather than only in a manifest or DB row?