Carry opaque source revisions in proposition provenance

[jimador]

Goal

Carry an opaque source revision through DICE extraction and existing source provenance so
successive versions of one logical source are queryable without changing locator identity.

Context

DICE already records typed source locators and DerivedFrom grounding. Source revision is
an additional scalar property of that source relationship, separate from extraction-run
lineage, and must not add a new SourceLocator subtype or duplicate the locator key.

The design follows stable-key + opaque-version APIs such as S3, W3C PROV's stable
entity/specialization split, and OpenTelemetry's distinction between one parent and many
causal links. SourceRevisionRef(sourceKey, sourceRevision) is the exact-query/run-lineage
value; stored provenance keeps only the scalar revision beside its existing locator.

Acceptance criteria

• Extraction entry points accept an optional opaque source revision.
• Existing source-grounding equality and locator keys remain stable.
• SourceRevisionRef.sourceKey equals canonical SourceLocator.key() at the DICE boundary.
• Store APIs provide tenant-scoped all-version (including revisionless), exact-version,
  and revisionless-only queries with Drivine push-down.
• Legacy revisionless callers remain compatible.
• REST and canonical proposition JSON round-trip source revision losslessly.
• Two revisions of one source remain related and independently queryable.
• Tests prove source grounding does not multiply when two runs analyze one revision.
• After Snapshot and move what DICE knows #46 lands, real unit and Neo4j knowledge-bundle round-trips preserve revision;
  this issue remains open until that external gate passes or acceptance is revised.

Constraints

• Keep source revision independent from extraction-run lineage.
• Do not infer provider revision semantics inside DICE.
• One aggregate input may carry one truthful aggregate revision; Record durable extraction runs and proposition run lineage #67 owns the ordered set
  of causal member source revisions.
• Coordinate bundle changes with DICE issue Snapshot and move what DICE knows #46 and metamodel versioning with Version the metamodel and catch drift before it corrupts the graph #45.
• The operator accepted source/JSON/Java compatibility and existing Java constructor
  descriptors as the boundary; full Kotlin synthetic constructor/copy ABI is not claimed.
• PR Embabel Agent 1.5.0 #71 completed the Spring/Embabel upgrade; the operator confirmed main is the sole
  delivery target and no backport is required.
• Before the PR, disposable copies of the checked-out Embabel assistant and me apps must
  compile and pass representative DICE-using tests against the integrated 0.2.0-SNAPSHOT;
  any failure is compared with unmodified DICE origin/main to isolate regressions.

Out of scope

• Source deletion and retirement.
• Host-side mutation detection.
• Provider identity.

Original request

Record which revision of a source produced a proposition so supersession and historical
reporting can be queried without breaking legacy callers.

Activity

• 2026-07-24T22:42:28Z [groom] Rewritten against the validated proposition extraction roadmap. Claims were checked against current Me and DICE contracts; dependencies and verification boundaries are now explicit.
• 2026-07-24T22:45:05Z [groom] Mirrored to GitHub: Carry opaque source revisions in proposition provenance #64
• 2026-07-26T12:56:15Z [codex] Brigade claimed the ticket for source-revision contract, provenance cardinality, query, serialization, and compatibility planning.
• 2026-07-26T13:47:00Z [codex] Six Brigade scouts completed; the plan was split into 16 narrow packets. Stored provenance uses one scalar revision beside the existing locator; one shared evidence-key codec protects collector fold/undo; Drivine uses deterministic relationship identity and tenant-first push-down.
• 2026-07-26T13:47:00Z [codex] Brigade Inspector cleared every technical blocker. Claude Fable final signoff has no unresolved high finding; Kotlin synthetic ABI scope remains the sole operator decision.
• 2026-07-26T13:47:00Z [codex] Ticket blocked at the human checkpoint. Core work targets a PR to protected main; the bundle criterion remains a real post-Snapshot and move what DICE knows #46 test gate, not a comment or fixture substitute.
• 2026-07-26T14:23:00Z [codex] Verified PR Embabel Agent 1.5.0 #71 merged with successful build/DCO gates and main now carries the Spring Boot 4.1, Spring AI 2.0.0, Jackson 3.0, Kotlin 2.2.21, Embabel Agent 1.5.0-SNAPSHOT, and DICE 0.2.0-SNAPSHOT upgrade. Operator confirmed main-only delivery; removed the backport gate.