Spec
What the lock does and does not
Lockfile spec v1.4. Pass or fail is an exact hash. The field-diff explains a mismatch. It does not decide it. Canonicalization is surfacepin-jcs-v1. Digests are lowercase hex SHA-256. The MCP schema revision 2026-07-28 is a documentation reference, not a runtime fetch.
| Does | Does not |
|---|---|
| Hash tools (name, description, inputSchema, annotations, outputSchema), resources (uri, name, description, mimeType), and prompts (name, description, arguments). | Semantic similarity, embeddings, or an LLM match. |
| Write lockfile v3, including the surface that was hashed. Verify still accepts lockfile v1, v2, and v3. | Streamable HTTP or SSE. Live listing is stdio only. |
| On mismatch, print a deterministic field-diff labeled COMPATIBLE|BREAKING|HINT_FLIP. Exit codes stay digest equality: 0 match, 1 drift, 2 usage. | A safety verdict from annotation hints. HINT_FLIP is not a safety verdict. The hash is not safety. |
| Verify offline from a JSON file and a lockfile. No network on that path. | A hosted service, telemetry, or signed locks. |
| List a live server over stdio when you pass --stdio -- and the server command. | Resource templates, or initialize.instructions. |
| Leave tool title, icons, and _meta out of the hash. | Materializing MCP annotation defaults into hashed fields. |
| Fail CI when the live digest does not match the pin, until someone re-locks on purpose. | A runtime proxy. SurfacePin does not sit on the request path. |
Re-lock after upgrading to 1.4 so embedded surfaces and digests include annotations and outputSchema. Older lockfiles still verify.