Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions scripts/site-version-guard.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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", () =>
Expand Down
22 changes: 13 additions & 9 deletions scripts/site-versions.snapshot.json
Original file line number Diff line number Diff line change
@@ -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": {
Expand All @@ -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": {
Expand Down Expand Up @@ -94,7 +97,7 @@
]
},
"surfacepin": {
"latest": "1.6.0",
"latest": "1.6.1",
"deprecated": null,
"versions": [
"1.0.0",
Expand All @@ -103,7 +106,8 @@
"1.3.0",
"1.4.0",
"1.5.0",
"1.6.0"
"1.6.0",
"1.6.1"
]
}
}
Expand Down
19 changes: 14 additions & 5 deletions src/app/spec/surfacepin/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand Down Expand Up @@ -38,10 +38,19 @@ export default function SurfacePinSpecPage() {
</tbody>
</table>

<p className="mt-10 max-w-2xl muted">
Re-lock after upgrading to 1.4 so embedded surfaces and digests include annotations and outputSchema.
Older lockfiles still verify.
</p>
<section className="mt-16" id="compatibility">
<h2 className="title">Compatibility promise</h2>
<ul className="mt-6 max-w-2xl list-disc space-y-3 pl-6 muted">
{specPromises.map((p) => (
<li key={p}>{p}</li>
))}
</ul>
<p className="mt-6 max-w-2xl">
<a className="text-link" href={surfacepin.specFreeze} {...externalLinkProps(surfacepin.specFreeze)}>
Format freeze and compatibility promise in SPEC.md
</a>
</p>
</section>

<div className="actions mt-10">
<Link className="btn btn-primary" href="/surfacepin">
Expand Down
16 changes: 9 additions & 7 deletions src/lib/site.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [
Expand Down Expand Up @@ -105,7 +106,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#<name> anchors land on that line.
*/
Expand All @@ -129,7 +131,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",
Expand Down Expand Up @@ -164,7 +166,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.
*/

Expand All @@ -178,7 +180,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",
Expand Down Expand Up @@ -235,7 +237,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",
Expand Down
29 changes: 19 additions & 10 deletions src/lib/surfacepin-copy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
},
{
Expand All @@ -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.",
},
{
Expand All @@ -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": [
Expand All @@ -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",
Expand Down