From 874a6307a0b2a17fd7c6200e23c029ea5ff2ce23 Mon Sep 17 00:00:00 2001 From: yellowgram Date: Tue, 20 Oct 2026 10:56:48 -0400 Subject: [PATCH 1/4] Pin L2 Send Guard 2.0.0 Bump the /oss install line to npx l2-send-guard@2.0.0 and add a version-guard test for the 1.x to 2.x line change. Merge only after l2-send-guard 2.0.0 is npm latest; before that the guard fails the build because 2.0.0 is not published. --- scripts/site-version-guard.test.mjs | 6 ++++++ src/lib/site.ts | 5 +++-- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/scripts/site-version-guard.test.mjs b/scripts/site-version-guard.test.mjs index 2c18b9f..2bdec73 100644 --- a/scripts/site-version-guard.test.mjs +++ b/scripts/site-version-guard.test.mjs @@ -129,6 +129,12 @@ test("surfacepin patch/minor lag only warns", () => { assert.ok(r.warnings.some((w) => /surfacepin@1\.5\.0/.test(w))); }); test("l2-send-guard@0.5.0 (pre-1.0 line) fails", () => fails(page({ l2: "npx l2-send-guard@0.5.0" }), /line/)); +test("l2-send-guard@1.0.0 after 2.0.0 publishes fails (major line); @2.0.0 passes", () => { + const reg = REGISTRY(); + reg.set("l2-send-guard", pkg("2.0.0", ["0.5.0", "1.0.0", "2.0.0"])); + fails(page(), /l2-send-guard@1\.0\.0.*line/, reg); + passes(page({ l2: "npx l2-send-guard@2.0.0" }), reg); +}); // Markup that splits tokens. test("JSX-split pin ( separators) fails", () => diff --git a/src/lib/site.ts b/src/lib/site.ts index 2afb849..1f3e14e 100644 --- a/src/lib/site.ts +++ b/src/lib/site.ts @@ -105,7 +105,8 @@ export const keelHow = [ export const l2Migrating = "https://github.com/yellowgram/l2-safety-proxy#migrating"; /** - * The six earlier send/recv packages, deprecated on npm ("Merged into l2-send-guard 1.x"). + * The six earlier send/recv packages, deprecated on npm ("Merged into l2-send-guard 1.x"; that npm + * text predates 2.0, and the README's migration section covers both 1.x and 2.0). * They appear on the site only in the L2 Send Guard replacement line (the version guard * enforces this); /oss# anchors land on that line. */ @@ -129,7 +130,7 @@ export const l2SendGuard = { "JSON-RPC proxy or signer library · offline demo · MIT", "Arbitrum, OP, Base and their Sepolias, Ethereum, Sepolia (mainnets need your RPC) · no keys held · no warranty", ], - install: "npx l2-send-guard@1.0.0", + install: "npx l2-send-guard@2.0.0", npm: "https://www.npmjs.com/package/l2-send-guard", repo: "yellowgram/l2-safety-proxy", github: "https://github.com/yellowgram/l2-safety-proxy", From da0c8d1bad618b8f3ddb9b16d4e52bdd3615f865 Mon Sep 17 00:00:00 2001 From: yellowgram Date: Tue, 20 Oct 2026 12:42:21 -0400 Subject: [PATCH 2/4] SurfacePin: describe the frozen jcs-v2 format and pin 1.6.1 /spec/surfacepin now states the frozen format (canonicalization surfacepin-jcs-v2 in lockfile v3), what is hashed (titles, annotations.title, opt-in instructions), that older jcs-v1 lockfiles still verify and unknown profiles exit 2, and the compatibility promise, with a link to SPEC.md section 0. The FAQ no longer says titles and instructions are not pinned. Install and softwareVersion move to 1.6.1; JSON-LD says Node.js 22+. The site version guard fails until surfacepin 1.6.1 is on npm. --- src/app/spec/surfacepin/page.tsx | 19 ++++++++++++++----- src/lib/site.ts | 5 +++-- src/lib/surfacepin-copy.ts | 29 +++++++++++++++++++---------- 3 files changed, 36 insertions(+), 17 deletions(-) diff --git a/src/app/spec/surfacepin/page.tsx b/src/app/spec/surfacepin/page.tsx index af86650..e486c6b 100644 --- a/src/app/spec/surfacepin/page.tsx +++ b/src/app/spec/surfacepin/page.tsx @@ -3,7 +3,7 @@ import Link from "next/link"; import { PageShell } from "@/components/SiteChrome"; import { externalLinkProps } from "@/components/ToolListing"; import { pageMetadata } from "@/lib/seo"; -import { specDescription, specIntro, specRows, specTitle } from "@/lib/surfacepin-copy"; +import { specDescription, specIntro, specPromises, specRows, specTitle } from "@/lib/surfacepin-copy"; import { surfacepin } from "@/lib/site"; export const metadata: Metadata = pageMetadata({ @@ -38,10 +38,19 @@ export default function SurfacePinSpecPage() { -

- Re-lock after upgrading to 1.4 so embedded surfaces and digests include annotations and outputSchema. - Older lockfiles still verify. -

+
+

Compatibility promise

+
    + {specPromises.map((p) => ( +
  • {p}
  • + ))} +
+

+ + Format freeze and compatibility promise in SPEC.md + +

+
diff --git a/src/lib/site.ts b/src/lib/site.ts index 2afb849..cb9f389 100644 --- a/src/lib/site.ts +++ b/src/lib/site.ts @@ -41,11 +41,12 @@ export const surfacepin = { "Fails CI on unexpected surface change", "MIT · CLI · CI-ready", ], - install: "npx surfacepin@1.6.0", + install: "npx surfacepin@1.6.1", repo: "yellowgram/surfacepin", github: "https://github.com/yellowgram/surfacepin", npm: "https://www.npmjs.com/package/surfacepin", - spec: "https://github.com/yellowgram/surfacepin/blob/main/SPEC.md", + spec: "https://github.com/yellowgram/surfacepin/blob/v1.6.1/SPEC.md", + specFreeze: "https://github.com/yellowgram/surfacepin/blob/v1.6.1/SPEC.md#0-format-freeze-and-compatibility-promise", }; export const howItWorks = [ diff --git a/src/lib/surfacepin-copy.ts b/src/lib/surfacepin-copy.ts index d580fab..7a4a31b 100644 --- a/src/lib/surfacepin-copy.ts +++ b/src/lib/surfacepin-copy.ts @@ -28,30 +28,30 @@ export const faqSeeds = [ }, { q: "Which lists are pinned?", - a: "tools/list, resources/list, and prompts/list. Resource templates and initialize.instructions are not pinned.", + a: "tools/list, resources/list, and prompts/list, including titles, and the server’s instructions when you add --surface …,instructions. Resource templates, icons and _meta are not pinned.", }, { q: "Which lockfiles still verify?", - a: "v1, v2, and v3. New locks are written as v3. Re-lock after upgrading to 1.4 so the digest includes annotations and outputSchema.", + a: "v1, v2, and v3. New locks are written as lockfile v3 with canonicalization surfacepin-jcs-v2, which is frozen: the same surface gives the same digests in every future release. Older surfacepin-jcs-v1 lockfiles still verify.", }, ] as const; export const specTitle = "SurfacePin — what the lock does and does not"; export const specDescription = - "Lockfile spec v1.4 for SurfacePin. Exact hash, offline verify, and a field-diff that does not decide pass or fail. Not semantic. Not a runtime proxy."; + "The frozen SurfacePin lockfile format: canonicalization surfacepin-jcs-v2 in lockfile v3. Exact hash, offline verify, and a field-diff that does not decide pass or fail. Not semantic. Not a runtime proxy."; export const specIntro = - "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."; + "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."; /** Contract rows. Paired so the table stays a does / does-not, not a pitch. */ export const specRows: readonly { does: string; doesNot: string }[] = [ { - does: "Hash tools (name, description, inputSchema, annotations, outputSchema), resources (uri, name, description, mimeType), and prompts (name, description, arguments).", + does: "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.", doesNot: "Semantic similarity, embeddings, or an LLM match.", }, { - does: "Write lockfile v3, including the surface that was hashed. Verify still accepts lockfile v1, v2, and v3.", + does: "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.", doesNot: "Streamable HTTP or SSE. Live listing is stdio only.", }, { @@ -64,10 +64,10 @@ export const specRows: readonly { does: string; doesNot: string }[] = [ }, { does: "List a live server over stdio when you pass --stdio -- and the server command.", - doesNot: "Resource templates, or initialize.instructions.", + doesNot: "Resource templates (resources/templates/list).", }, { - does: "Leave tool title, icons, and _meta out of the hash.", + does: "Leave icons, _meta, and resource annotations and size out of the hash.", doesNot: "Materializing MCP annotation defaults into hashed fields.", }, { @@ -76,6 +76,15 @@ export const specRows: readonly { does: string; doesNot: string }[] = [ }, ]; +/** Compatibility promise for the frozen format (SPEC.md section 0). */ +export const specPromises: readonly string[] = [ + "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.", +]; + export const surfacepinJsonLd = { "@context": "https://schema.org", "@graph": [ @@ -97,8 +106,8 @@ export const surfacepinJsonLd = { "@type": "SoftwareApplication", "@id": "https://www.yellowgram.dev/surfacepin#software", name: "SurfacePin", - softwareVersion: "1.6.0", - operatingSystem: "Node.js 20+", + softwareVersion: "1.6.1", + operatingSystem: "Node.js 22+", license: "https://spdx.org/licenses/MIT.html", url: "https://www.yellowgram.dev/surfacepin", installUrl: "https://www.npmjs.com/package/surfacepin", From ded49f4c90d4bee421c28458dbe18e35aa2127b9 Mon Sep 17 00:00:00 2001 From: yellowgram Date: Tue, 20 Oct 2026 13:20:59 -0400 Subject: [PATCH 3/4] Pin burnbrake 0.4.0 and @yellowgram/maydo 0.3.0 on /oss The install lines move to the new releases: burnbrake 0.4.0 (mid-stream kill) and the MayDo SDK 0.3.0. Merge after both are live on npm; the version guard in the build fails until then. --- src/lib/site.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib/site.ts b/src/lib/site.ts index 2afb849..8eab171 100644 --- a/src/lib/site.ts +++ b/src/lib/site.ts @@ -164,7 +164,7 @@ export const seattruthDemo = "https://github.com/yellowgram/seattruth/releases/download/clip-60s-approved/seattruth-60s-approved.mp4"; /* - * BurnBrake, HookSteel and SeatTruth are on npm at 0.3.0, the MayDo SDK at 0.2.0 (MIT). + * BurnBrake is on npm at 0.4.0, HookSteel and SeatTruth at 0.3.0, the MayDo SDK at 0.3.0 (MIT). * Install lines pin those versions. */ @@ -178,7 +178,7 @@ export const burnbrake = { "HTTP 402 BUDGET_EXHAUSTED · not retryable · never 429", `${mitLine} · you run it`, ], - install: "npm install burnbrake@0.3.0 && npx burnbrake serve", + install: "npm install burnbrake@0.4.0 && npx burnbrake serve", npm: "https://www.npmjs.com/package/burnbrake", repo: "yellowgram/burnbrake", github: "https://github.com/yellowgram/burnbrake", @@ -235,7 +235,7 @@ export const maydo = { "Thin TypeScript SDK (@yellowgram/maydo) on npm · server from GitHub · cache off by default", `${mitLine} · decision only, no invoicing`, ], - install: "npm install @yellowgram/maydo@0.2.0", + install: "npm install @yellowgram/maydo@0.3.0", npm: "https://www.npmjs.com/package/@yellowgram/maydo", repo: "yellowgram/maydo", github: "https://github.com/yellowgram/maydo", From 3dbc9564658d06573424ce3448236fb2e48ead95 Mon Sep 17 00:00:00 2001 From: yellowgram Date: Tue, 20 Oct 2026 13:44:45 -0400 Subject: [PATCH 4/4] Refresh site version snapshot --- scripts/site-versions.snapshot.json | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/scripts/site-versions.snapshot.json b/scripts/site-versions.snapshot.json index de710f6..7312cc5 100644 --- a/scripts/site-versions.snapshot.json +++ b/scripts/site-versions.snapshot.json @@ -1,21 +1,23 @@ { - "checkedAt": "2026-10-20T11:45:58.833Z", + "checkedAt": "2026-10-20T17:44:39.004Z", "packages": { "@yellowgram/maydo": { - "latest": "0.2.0", + "latest": "0.3.0", "deprecated": null, "versions": [ "0.0.0-stage", - "0.2.0" + "0.2.0", + "0.3.0" ] }, "burnbrake": { - "latest": "0.3.0", + "latest": "0.4.0", "deprecated": null, "versions": [ "0.0.0-stage", "0.2.0", - "0.3.0" + "0.3.0", + "0.4.0" ] }, "hooksteel": { @@ -28,11 +30,12 @@ ] }, "l2-send-guard": { - "latest": "1.0.0", + "latest": "2.0.0", "deprecated": null, "versions": [ "0.5.0", - "1.0.0" + "1.0.0", + "2.0.0" ] }, "recv-approval-watch": { @@ -94,7 +97,7 @@ ] }, "surfacepin": { - "latest": "1.6.0", + "latest": "1.6.1", "deprecated": null, "versions": [ "1.0.0", @@ -103,7 +106,8 @@ "1.3.0", "1.4.0", "1.5.0", - "1.6.0" + "1.6.0", + "1.6.1" ] } }