yellowgram

Spec

What the lock does and does not

Frozen: canonicalization surfacepin-jcs-v2 in lockfile v3 (the format SurfacePin 1.6.0 writes). It hashes title on tools, resources, prompts and prompt arguments, tool annotations.title, and the server’s instructions (opt-in: --surface …,instructions). Older surfacepin-jcs-v1 lockfiles still verify. Unknown profiles are rejected (exit 2). Pass or fail is an exact hash; the field-diff explains a mismatch and does not decide it. Digests are lowercase hex SHA-256. The MCP schema revision 2026-07-28 is a documentation reference, not a runtime fetch.

DoesDoes not
Hash tools (name, title, description, inputSchema, annotations including annotations.title, outputSchema), resources (uri, name, title, description, mimeType), prompts (name, title, description, and each argument’s name, title, description, required), and the server’s instructions when selected.Semantic similarity, embeddings, or an LLM match.
Write lockfile v3 with canonicalization surfacepin-jcs-v2, including the surface that was hashed. Verify still accepts lockfile v1, v2 and v3 (surfacepin-jcs-v1) and rejects unknown profiles with exit 2.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 (resources/templates/list).
Leave icons, _meta, and resource annotations and size 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.

Compatibility promise

  • A pin keeps its meaning. For the same input, every future release computes the same surfacepin-jcs-v2 bytes, digests and roots, so a lockfile that passes today keeps passing and one that fails keeps failing.
  • No silent changes. Any future need ships as a new, separately named profile, never as a change to surfacepin-jcs-v2.
  • Existing pins are never dropped. surfacepin-jcs-v1 (lockfile v1, v2 and v3) and surfacepin-jcs-v2 (lockfile v3) keep verifying, each with the profile it records. surfacepin-jcs-v1 means the rules of 1.4 and later; locks written by 1.0 to 1.3 for tools with annotations or outputSchema need a re-lock.
  • Unknown means reject. A verifier that does not know a lockfile’s profile exits 2 and never falls back to another profile.
  • New profiles are opt-in for existing pins. Existing lockfiles keep the profile they record until you re-lock.

Format freeze and compatibility promise in SPEC.md