dsh-lineage

Content-addressed data and action lineage evidence for DeepSeek Harness.

The DSH ecosystem already has a security-audit plugin that reports plugin provenance. dsh-lineage addresses a different gap: it builds a local, verifiable object graph for artifacts, verified-fact records, actions, and reports. It never stores chat transcripts or factual prose; a node is only a typed ID plus an explicit workspace-relative object reference and expected SHA-256.

Version 0.2.0 is a formal Codex plugin and standalone proof-only MCP server, and uses the namespace export shape required by the stock DSH Web Loader. A real Cordis boot regression test guards that loader contract.

Adjacent tools track Skill bundle versions, hash-chain agent activity, or register provenance. This project stays at the object-graph evidence layer: typed content-addressed nodes, explicit causal edges, resolvable references, DAG validation, upstream/downstream closure, and missing/stale disclosure.

Graph model

Node types:

• artifact
• fact
• action
• report

Edge types point from the dependent object toward its provenance:

• derived-from
• observed-by
• produced-by
• supersedes

Every node reference is dereferenced inside workspaceRoot and hashed. The verifier distinguishes:

• verified: the object exists and matches its expected hash;
• missing: the reference cannot be resolved;
• stale: the object exists but its current hash differs;
• dangling graph references, invalid relation types, and cycles.

No missing or stale object is silently promoted into a fact.

Append-only ledger

Input is explicit JSONL. Each event has an idempotencyKey and either put-node or put-edge. The key maps to one immutable event file in ledgerDir:

1. validate the complete hypothetical graph before writing;
2. write a temporary file inside the explicit ledger directory;
3. read it back;
4. atomically hard-link it into its final immutable slot;
5. read the published file back and verify SHA-256.

Replaying the same key and event is safe. Reusing a key with different content fails closed. Event files are never updated; a new object revision gets a new node ID and a supersedes edge.

Safety model

• All ledger, JSONL, object and report paths are workspace-relative; traversal and symlink components are rejected.
• Writes occur only inside explicit ledgerDir or artifactDir.
• Event schemas allow only structural IDs, types, paths and hashes. Keys for claims, chat, prompts, messages, raw content, text, credentials, tokens, cookies and authorization are rejected.
• Referenced object bytes are hashed but never copied into the ledger or reports.
• Ingest rejects self-edges, graph cycles and invalid producer/observer/supersedes type constraints before publication.
• Closure reports are content addressed and read-back verified.

Run this over evidence objects you created or were authorized to inspect. A hash proves identity, not truth; dsh-lineage reports what is present, missing or changed and does not invent assertions.

Install in DSH

dsh plugin --profile lineage add github:dongsheng123132/dsh-lineage

Registered tools:

• dsh_lineage_inspect
• dsh_lineage_ingest
• dsh_lineage_query
• dsh_lineage_verify

MCP

.mcp.json declares a standalone stdio MCP server:

• lineage_events_inspect validates a bounded inline JSONL graph and reports structural hashes, counts, dangling references, cycles and relation errors.
• lineage_events_query returns deterministic upstream/downstream closure over those inline events.

MCP accepts at most 1 MiB of inline structural events. It never dereferences object paths and never reads or writes the filesystem. Persistent append-only ingestion and object-hash verification remain available only through the workspace-bounded DSH tool and CLI surfaces.

CLI

dsh-lineage ingest --root /workspace --ledger ledger --events lineage.events.jsonl
dsh-lineage inspect --root /workspace --ledger ledger
dsh-lineage query --root /workspace --ledger ledger --node report:proof --direction upstream
dsh-lineage verify --root /workspace --ledger ledger --node report:proof --direction upstream --artifact-dir artifacts

query supports upstream, downstream, and both. verify exits 0 for a fully verified closure, 2 when a report is written but evidence is missing/stale/invalid, and 1 for an operational or schema error.

Example

node bin/dsh-lineage.mjs ingest --root . --ledger ledger --events examples/lineage.events.jsonl
node bin/dsh-lineage.mjs verify --root . --ledger ledger --node fact:normalized-v1 --direction both --artifact-dir artifacts

See examples/lineage.events.jsonl.

Develop

npm test
npm run check
npm run smoke:plugin
npm run smoke:mcp
python C:/Users/ZhuanZ/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .

Requires Node.js 22+. There are no runtime dependencies or install lifecycle scripts beyond the optional DSH tools SDK peer.

License

MIT