Skip to content

[ISSUE-842] Define provenance model for facts, chunks, and evidence - #843

Open
E2ern1ty wants to merge 1 commit into
apache:masterfrom
E2ern1ty:issue-842-provenance-model
Open

[ISSUE-842] Define provenance model for facts, chunks, and evidence#843
E2ern1ty wants to merge 1 commit into
apache:masterfrom
E2ern1ty:issue-842-provenance-model

Conversation

@E2ern1ty

Copy link
Copy Markdown
Contributor

Purpose of the change

Implements #842 for the geaflow-ai Graph Memory module. Adds the source-lineage contracts needed so extracted facts can point back to the document and chunk they came from, which later citation-aware answers and deletion propagation will build on.

Brief change log

  • Add SourceSpan: an immutable span (chunkId, startOffset, endOffset) referencing positions within a chunk, with fail-closed validation.
  • Add ProvenanceRef: an immutable lineage record linking an extracted fact to documentId, chunkId, an optional SourceSpan, extractorVersion and schemaVersion. A static validate(ProvenanceRef) fails closed on missing provenance for extracted facts; the optional span must belong to the referenced chunk.
  • Provenance records reference source coordinates only and never carry raw document text (guarded by a test asserting serialized provenance contains no raw body).
  • Add JSON examples under geaflow-ai/src/test/resources/provenance and JUnit 5 tests covering validation failures, JSON round-trips and equality.

Verifying this change

mvn -pl geaflow-ai -am test -Dtest='ProvenanceRefTest,SourceSpanTest' passes: 15 tests, 0 failures.

Does this pull request potentially affect one of the following parts

  • No. This change is additive: new contracts and tests only, no existing behavior modified.

Documentation

  • Contract semantics are documented via Javadoc; no user-facing behavior to document yet.

Add SourceSpan and ProvenanceRef contracts under
org.apache.geaflow.ai.provenance linking extracted facts to source
document, chunk, optional span within the chunk, extractor version and
schema version. Validation fails closed for missing provenance and
provenance records reference source coordinates only, never raw
document text.

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant