Preface¶

In the DSH workflow, there may be reference relationships among artifacts, verified-fact records, actions, and reports. Looking at a single object or report alone is insufficient to confirm whether a node is resolvable, still matches expected content, or whether upstream/downstream evidence is complete. dsh-lineage is used to build a locally verifiable object graph: node references are resolved within workspaceRoot, referenced object bytes are used to compute SHA-256, and states of verified, missing, and stale are reported.

Below is an introduction to its positioning, capabilities, installation method, and typical usage.

What This Is¶

dsh-lineage is a plugin maintained by dongsheng123132, with the repository dongsheng123132/dsh-lineage, licensed under MIT. The package.json declares version 0.2.0, requires Node.js 22+, and declares an optional peer dependency @deepseek-ai/dsh-tools.

It targets artifacts, verified-fact records, actions, and reports, building a locally verifiable object graph. Referenced objects are hashed, but their content is not copied into the ledger or reports. SHA-256 is used to prove identity, not truth; the plugin reports whether objects are present, missing, or changed, and does not invent assertions.

Core Features¶

Object Graph Verification¶

dsh-lineage supports the following checks:

• DAG validation
• upstream/downstream closure
• missing/stale disclosure
• Distinguishing verified, missing, stale
• Detecting dangling references, invalid relation types, cycles

Missing or stale objects are not silently promoted to facts.

Append-only Ledger¶

Event input is explicit JSONL. Each event contains an idempotencyKey, with types put-node or put-edge.

Replay rules:

1. Replaying the same key/event is safe
2. Using different content for the same key fails closed
3. Event files are never updated

Path and Write Boundaries¶

The plugin’s path and write boundaries are as follows:

• All paths must be workspace-relative
• Traversal and symlink components are rejected
• Writes occur only within explicit ledgerDir or artifactDir

The event schema rejects keys such as claims, chat, prompts, messages, raw content, text, credentials, tokens, cookies, authorization, etc.

DSH Tools¶

The plugin registers the following DSH tools:

• dsh_lineage_inspect
• dsh_lineage_ingest
• dsh_lineage_query
• dsh_lineage_verify

Standalone MCP Server¶

The plugin provides a standalone stdio MCP server exposing:

• lineage_events_inspect
• lineage_events_query

MCP only accepts inline structural events up to 1 MiB. It does not dereference object paths and does not read or write to the file system. Persistent append-only ingestion and object-hash verification are provided only through workspace-bounded DSH tools and CLI surfaces.

Installation and Enablement¶

First, confirm the Node.js version is at least 22:

node --version

Next, install the plugin in DSH:

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

After installation, lineage capabilities can be invoked through the dsh_lineage_* tools listed above. Apart from the optional @deepseek-ai/dsh-tools peer, there are no runtime dependencies or installation lifecycle scripts.

Typical Usage¶

First prepare a JSONL event file in the workspace, e.g., lineage.events.jsonl.

ingest¶

ingest writes events to an explicit ledger:

dsh-lineage ingest --root /workspace --ledger ledger --events lineage.events.jsonl

inspect¶

inspect examines the ledger and object states under the current workspace:

dsh-lineage inspect --root /workspace --ledger ledger

query¶

query is used to query upstream or downstream closures related to a node:

dsh-lineage query --root /workspace --ledger ledger --node report:proof --direction upstream

verify¶

verify checks closure in a node direction and verifies object evidence:

dsh-lineage verify --root /workspace --ledger ledger --node report:proof --direction upstream --artifact-dir artifacts

You can also directly run the repository entry point using Node:

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

Through the above steps, you can complete the process from event writing to object evidence verification.

Applicable Scenarios and Notes¶

Suitable for the following scenarios:

• Maintaining locally verifiable references for artifacts, verified-fact records, actions, and reports
• Distinguishing verified, missing, stale
• Avoiding mixing raw chat content, raw content, or credential-like fields into events
• Choosing between DSH tools, CLI, or standalone MCP with different boundaries

Notes before use:

• Requires Node.js 22+
• @deepseek-ai/dsh-tools is an optional peer dependency
• The plugin runs with the current dsh process permissions; review the source and MIT license before installation
• MCP only handles inline structural events and does not access the file system
• Persistent append-only ingestion and object-hash verification are provided via DSH tools or CLI

Conclusion¶

dsh-lineage provides a set of locally executable lineage evidence checks: reference resolution, SHA-256 comparison, closure queries, ledger replay, and missing/stale disclosure.

Verified materials do not provide a directory page address. GitHub repository address:

https://github.com/dongsheng123132/dsh-lineage