Preface

In DSH plugin development, ToolRuntime, MCP JSON-RPC, and CLI JSON are three common machine communication surfaces. If comparing baseline and observation versions, re-executing the target directly may introduce network calls, side effects, and credential exposure.

dsh-surface-contract-proof provides an alternative path: based on recorded JSON fixtures, checking whether the three surfaces still maintain the same fixed semantic contract. Below is an introduction to its features, boundaries, installation method, and typical usage.

What is it

dsh-surface-contract-proof is an MIT-licensed DSH plugin maintained by dongsheng123132.

It reads explicitly SHA-256-hashed JSON fixtures and performs a content-addressed conformance proof on the recorded DSH ToolRuntime, MCP JSON-RPC, and CLI JSON envelopes.

This plugin requires Node.js >= 22.

Core Features

  • Validates recorded DSH ToolRuntime, MCP JSON-RPC, and CLI JSON envelopes, requiring exactly three surfaces: dsh-toolruntime, mcp-jsonrpc, and cli-json.
  • Reads explicitly SHA-256-hashed JSON fixtures.
  • Normalizes surface-specific fields into a canonical case digest, with the manifest fixing each expected digest.
  • Provides DSH tools dsh_surface_contract_inspect and dsh_surface_contract_verify.
  • Provides MCP aliases surface_contract_inspect and surface_contract_verify.
  • The MCP surface is proof-only and in-memory, accepting bounded inline manifest/fixture JSON, not reading/writing files, and not returning fixture bodies.

Boundaries & Failure Strategies

This plugin does not execute the target, does not start arbitrary commands, does not call network services, does not replay side effects, and does not implement action core.

When fixtures are missing, expired, malformed, suspected secrets, schema/version drift, or semantically different, it fails closed.

Reports only expose hashes, identities, statuses, and differing field names, not request parameters, response bodies, CLI output, prompts, messages, credentials, or secrets.

File paths must be workspace-relative regular files; traversal and symlinks are rejected. Writes are atomic, read back, and limited to the explicit artifactDir.

Installation & Enabling

First, confirm the runtime environment meets Node.js >= 22, and pin the plugin commit as needed:

dsh plugin --profile surface-contract add github:dongsheng123132/dsh-surface-contract-proof#<commit>

It is recommended to check the source code and license before installation. The plugin runs with the current DSH process permissions, so do not install repositories whose source or behavior cannot be confirmed.

Typical Usage

First, perform inspect to get canonical baseline digests, review them, and then pin them to the manifest:

dsh-surface-contract-proof inspect --workspace . --manifest contract.json

Pin the reviewed digest to cases[].expectedSha256.

After the above steps, perform verify:

dsh-surface-contract-proof verify --workspace . --manifest contract.json --artifactDir artifacts

Exit code 0 means verified; exit code 2 means failed or invalid evidence.

DSH & MCP Tools

DSH surfaces expose:

  • dsh_surface_contract_inspect
  • dsh_surface_contract_verify

MCP aliases:

  • surface_contract_inspect
  • surface_contract_verify

The MCP path remains proof-only and in-memory: it accepts bounded inline manifest/fixture JSON, does not read/write files, and does not return fixture bodies. If generating a report, writing is limited to the explicit artifactDir and uses atomic, read-back methods.

Version Notes

Version 0.2.0 removes the bundled DSH tool runtime and the default export that the stock Cordis Loader misclassified.

Use Cases & Notes

Suitable for scenarios where baseline and observation version recordings already exist, especially when checking whether the three surfaces (DSH ToolRuntime, MCP JSON-RPC, and CLI JSON) still conform to the same fixed contract.

Note the following points:

  • It does not execute the target, does not start arbitrary commands, does not call network services, does not replay side effects, and does not implement action core.
  • Fixtures must be explicitly SHA-256-hashed JSON fixtures.
  • Reports only expose hashes, identities, statuses, and differing field names.
  • You should check the source code, license, and pinned commit before installation.

Conclusion

The value of dsh-surface-contract-proof lies in pinning the recorded evidence of the three DSH machine surfaces to comparable digests, avoiding direct replay of request content during contract checking.

GitHub: https://github.com/dongsheng123132/dsh-surface-contract-proof

Community Directory Page: The materials verified in this article do not contain a verifiable directory page URL; if the plugin provides a directory page address in clues, you can access it via that clue.