dsh-surface-contract-proof
dsh-surface-contract-proof verifies that recorded DeepSeek Harness ToolRuntime, MCP JSON-RPC, and CLI JSON envelopes preserve one pinned semantic contract across a baseline and an observed revision.
Version 0.2.0 removes the bundled DSH tool runtime and the default export that stock Cordis Loader misclassified. It exposes host-neutral tool definitions through its namespace export and is regression-tested through real local-path and fixed-commit stock Web profiles.
It reads explicit, SHA-256-pinned JSON fixtures. It does not execute the target, start arbitrary commands, call a network service, replay side effects, or implement an action core.
Complementary boundary
dsh-action-parity proves that interfaces bind the same Action ID/core and that runtime success/conflict behavior is reachable. This plugin answers a different upgrade question: given immutable recordings, did request/response schema versions, success bits, error classes, exit-code mapping, conflict and confirmation semantics, normalization, timeout/stale/out-of-order behavior, and result digests remain identical across ToolRuntime, MCP, and CLI?
Generic OpenAPI/Pact tools validate HTTP consumer-provider contracts. This verifier is specific to the three DSH machine surfaces and uses offline recorded envelopes.
Safety and evidence
- Exactly three surface kinds are required:
dsh-toolruntime, mcp-jsonrpc, and cli-json.
- Baseline and observed fixtures bind target revisions, contract/schema versions, transport versions, and SHA-256 bytes.
- Surface-specific fields normalize into one canonical case digest; the manifest pins each expected digest.
- Missing, stale, malformed, secret-shaped, schema/version-drifted, or semantically different fixtures fail closed.
- Reports expose hashes, identities, statuses, and differing field names only—never request arguments, response bodies, CLI output, prompts, messages, credentials, or secrets.
- Paths are workspace-relative regular files; traversal and symlinks are rejected. Writes are atomic, read back, and limited to explicit
artifactDir.
CLI
dsh-surface-contract-proof inspect --workspace . --manifest contract.json
dsh-surface-contract-proof verify --workspace . --manifest contract.json --artifactDir artifacts
Use inspect to obtain canonical baseline digests, review them, then pin them as cases[].expectedSha256. Exit 0 means verified; exit 2 means failed or invalid evidence.
DSH / MCP tools
dsh_surface_contract_inspectdsh_surface_contract_verify- MCP aliases:
surface_contract_inspect, surface_contract_verify
The MCP surface is proof-only and in-memory: it accepts bounded inline manifest/fixture JSON, reads or writes no files, and returns no fixture bodies. DSH/CLI may write only a content-addressed report beneath an explicit workspace-relative artifactDir, with atomic read-back verification.
dsh plugin --profile surface-contract add github:dongsheng123132/dsh-surface-contract-proof#<commit>
Development
npm ci
npm test
npm run check
npm run smoke:plugin
npm run smoke:mcp
MIT licensed. See SECURITY.md.
