[jjk9090]

Summary

This PR builds on PR #35 and extends Workspace with lineage-aware, versioned graph storage and historical graph queries.

Changes

• Add deterministic Workspace lineage triples for source files, Workspace revisions, and source versions, and persist them in both Graph View and TerminusDB so they are available to graph schema, search, neighbor, traversal, and statistics queries.
• Support two graph triple ingestion modes:
  • Use caller-provided graph_sources as authoritative assertions.
  • When graph_sources is omitted and the backend is TerminusDB, extract triples through Ingest.graph_add_path using the legacy model.
• Add Workspace dirty-state tracking:
  • mark the Workspace dirty after write operations;
  • check dirty state before reads;
  • allow rollback to bypass the dirty-state read restriction;
  • validate and clear the dirty state after successful publication.
• Add TerminusDB Workspace version control using persistent dm_build_<revision> branches for pinned historical reads.
• Add TerminusDB revision branch cleanup to Workspace GC while retaining branches referenced by published manifests.
• Extend V1-to-V2 migration to preserve graph relations and add deterministic lineage data to the migrated revision.
• Add tests covering dirty-state checks, rollback, graph versioning, historical queries, migration, V1/V2 lineage, automatic extraction, and TerminusDB branch GC.

Relation to PR #35

This PR is based on and extends OpenDCAI/DataMind#35.

It builds on the TerminusDB graph backend and versioning foundation from PR #35, then adds Workspace-level lineage, historical graph queries, migration handling, and garbage collection of unreferenced revision branches.

Revision Retention

Dolt uses tags to retain Workspace revisions. The current TerminusDB Python client does not expose a tag API, so TerminusDB revision branches serve as durable revision references:

dm_build_<workspace_revision>

Successful branches remain available for pinned historical reads until Workspace GC confirms that no retained manifest references them. Failed build branches are removed immediately.

Testing

python -m py_compile \
  datamind/workspace_native.py \
  datamind/workspace_incremental.py \
  datamind/capabilities/graph/providers/terminusdb_store.py

pytest -q datamind/tests/test_workspace_incremental.py \
  -k terminusdb_gc

TerminusDB integration tests require a configured TerminusDB DSN and password. If the configured local TerminusDB instance is not already running,TerminusDBGraphStore automatically starts it through _init_terminusdb() when Docker is available.

The tests are skipped when the TerminusDB client is unavailable, the DSN or password is not configured, or the local TerminusDB service cannot be started.