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 gate_path x model_partition

The storage-driving relation is still note_path x gate_path: a note is reviewed against many gate notes, a gate note applies to many notes, and the review state belongs to their edge. 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 note file does not say which model reviewed it. The gate file does not say which model applied it. The model-side partition lives in review lineage state:

  • review_runs.model_partition records the declared model-side partition for a prompt invocation;
  • review_pairs.model_partition keys each reviewed (note, gate) pair to that model partition;
  • acceptance_events.model_partition makes current acceptance specific to that model;
  • selectors compare current note/gate content hashes against the latest accepted baseline for (note_path, gate_path, model_partition).

The migration should rename the physical DB columns to model_partition at the same time as the architectural concept changes. model_partition is a declared partition that may be exact, coarse, or parameter-bearing. Post-run telemetry can carry the literal observed model as evidence, but it must not re-key accepted review state.

That is why review freshness is operationally keyed by note_path x gate_path x model_partition, even though only the reviewed note and gate note are durable markdown endpoints. In the current implementation, the model dimension is derivation-state metadata stored in the DB. That does not settle whether rendered review artifacts should also carry literal producer-model provenance in frontmatter for inspection, export, or future file-backed lineage.

This is also why one model's review cannot satisfy another model's freshness. A review result is a model-conditioned judgment. The same note and gate reviewed by a different model is a different edge-state partition.

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, gate_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;
  • ad-hoc distillations 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

  • Where should a derivative use a declared model_partition, and where should it record a literal generated_by_model observed after execution?
  • 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?