From 215855609bf3908e0fe6825720e1386cd3d1f656 Mon Sep 17 00:00:00 2001 From: NHTanvir Date: Tue, 17 Nov 2026 21:38:49 +0600 Subject: [PATCH 1/2] Judge documents in another version by their version, not by the 1.0 field rules A 0.4 document failed agent.protocols for a missing description, which only 1.0 requires. Now a non-1.x document fails version.compatible (an error, since a 1.0-only agent must not use it), passes when supported_versions lists a 1.x document, and skips the 1.0 field and OAuth rules with a note. Rules for what spec 3.4 keeps stable across versions still run. Refs #1 --- docs/SPEC-NOTES.md | 20 ++++++++++++++++++++ src/check.ts | 18 +++++++++++++++--- src/report.ts | 4 ++-- src/rules/define.ts | 1 + src/rules/document.ts | 33 +++++++++++++++++++++++---------- src/spec.ts | 1 + src/types.ts | 6 ++++++ src/util.ts | 5 +++++ 8 files changed, 73 insertions(+), 15 deletions(-) diff --git a/docs/SPEC-NOTES.md b/docs/SPEC-NOTES.md index 18a7312..6f0d17a 100644 --- a/docs/SPEC-NOTES.md +++ b/docs/SPEC-NOTES.md @@ -177,6 +177,26 @@ because there's no host to fetch them from. - Each `supported_versions` URL MUST be HTTPS on the host that served `poppy.json`. - Keys are `major.minor`, and name versions *other* than `protocol_version`. +### How Pollen treats other versions + +Pollen's rules are the 1.0 rules, and versions before 1.0 differ in breaking ways. For example, +`agent.protocols[].description` became required in 1.0 (changelog, "Conversation protocol +descriptions", breaking), so a valid 0.4 document fails the 1.0 field rules. So: + +- A document whose `protocol_version` isn't 1.x fails `version.compatible` (an error): before 1.0 a + version is compatible only with the same minor version, so a Personal Agent that implements only + 1.0 MUST NOT use it (3.4). +- Unless `supported_versions` lists a 1.x document: a 1.0 Personal Agent uses that one instead, so + `version.compatible` passes. Pollen doesn't fetch that document yet. +- Either way, the 1.0 field rules and OAuth checks are skipped for a non-1.x document. Only the + rules for what 3.4 says keeps its meaning in every version still run: the location and fetching + of `poppy.json`, `protocol_version`, and `supported_versions`. +- A missing or malformed `protocol_version` fails `version.present` or `version.format`, and the + 1.0 rules still run, since there's no other version to judge by. + +Found in the wild: Shopify publishes a `poppy.json` for every store, and on 2026-11-17 the ones +checked declared `0.4` with agent entries that have no `description`. + ## Score Not part of the spec; Pollen's own measure. The score starts at 100. Each failed error rule costs diff --git a/src/check.ts b/src/check.ts index 5759747..9b267f3 100644 --- a/src/check.ts +++ b/src/check.ts @@ -7,7 +7,7 @@ import { fetchFollowing, parseJson, type Fetcher } from "./fetch.js"; import { RULES } from "./rules/index.js"; import { SPEC_VERSION, WELL_KNOWN_PATH } from "./spec.js"; import type { Context, Report, Rule, RuleResult, Summary } from "./types.js"; -import { hostOf, isDomain, isObject } from "./util.js"; +import { hostOf, isDomain, isObject, majorOf } from "./util.js"; import { VERSION } from "./version.js"; export interface CheckOptions { @@ -73,8 +73,11 @@ export async function check(input: string, options: CheckOptions = {}): Promise< if (http.status === 200 && !http.error && http.body !== undefined) readText(ctx, http.body); const org = ctx.doc && isObject(ctx.doc.organization) ? ctx.doc.organization : undefined; + const otherVersion = versionSkip(ctx); if (!ctx.doc) { ctx.oauthSkipped = ctx.raw === undefined ? "No document was retrieved." : "No JSON object to check."; + } else if (otherVersion) { + ctx.oauthSkipped = otherVersion; } else if (options.skipOAuth) { ctx.oauthSkipped = "Skipped with --skip-oauth."; } else if (!org || !isDomain(org.domain)) { @@ -107,6 +110,14 @@ function readText(ctx: Context, raw: string): void { if (ctx.parsed.ok && isObject(ctx.parsed.value)) ctx.doc = ctx.parsed.value; } +/** Why the 1.0 rules don't apply: the document declares a version that isn't 1.x. */ +function versionSkip(ctx: Context): string | undefined { + const value = ctx.doc?.protocol_version; + const major = majorOf(value); + if (major === undefined || major === 1) return undefined; // version.present and version.format report bad values + return `protocol_version is ${String(value)}: Pollen applies the ${SPEC_VERSION} rules only to 1.x documents.`; +} + function skipReason(rule: Rule, ctx: Context): string | undefined { switch (rule.stage) { case "transport": @@ -114,10 +125,11 @@ function skipReason(rule: Rule, ctx: Context): string | undefined { case "parse": return ctx.raw === undefined ? "No document was retrieved." : undefined; case "document": - if (ctx.doc) return undefined; - return ctx.raw === undefined ? "No document was retrieved." : "No JSON object to check."; + if (!ctx.doc) return ctx.raw === undefined ? "No document was retrieved." : "No JSON object to check."; + return rule.allVersions ? undefined : versionSkip(ctx); case "oauth": if (ctx.oauth) return undefined; + if (versionSkip(ctx)) return versionSkip(ctx); if (ctx.mode === "file") return "Local file: OAuth metadata is checked only against a live URL."; return ctx.oauthSkipped ?? "OAuth metadata wasn't fetched."; } diff --git a/src/report.ts b/src/report.ts index 1accd0e..03dfdc9 100644 --- a/src/report.ts +++ b/src/report.ts @@ -66,11 +66,11 @@ export function formatText(report: Report, options: TextOptions = {}): string { ); if (report.ok) { const extra = warnings > 0 ? ` Fix the ${plural(warnings, "warning")} to reach 100.` : ""; - lines.push(`${paint("green", "PASS")} Personal Agents can use this document.${extra}`); + lines.push(`${paint("green", "PASS")} Poppy ${report.spec_version} Personal Agents can use this document.${extra}`); } else if (!report.results.some((r) => r.group !== "Transport" && r.status !== "skip")) { lines.push(`${paint("red", "FAIL")} There's no document Personal Agents can read here.`); } else { - lines.push(`${paint("red", "FAIL")} Fix the ${plural(errors, "error")} above. Personal Agents won't use this document until then.`); + lines.push(`${paint("red", "FAIL")} Fix the ${plural(errors, "error")} above before Poppy ${report.spec_version} Personal Agents can use this document.`); } return `${lines.join("\n")}\n`; } diff --git a/src/rules/define.ts b/src/rules/define.ts index c88c246..e5c89df 100644 --- a/src/rules/define.ts +++ b/src/rules/define.ts @@ -9,6 +9,7 @@ interface RuleSpec { stage: Stage; severity: Severity; section: string; + allVersions?: boolean; } export function defineRule(spec: RuleSpec, check: (ctx: Context) => Outcome): Rule { diff --git a/src/rules/document.ts b/src/rules/document.ts index ee7fcc3..868076e 100644 --- a/src/rules/document.ts +++ b/src/rules/document.ts @@ -1,7 +1,8 @@ // Section 3.1 and 3.4: protocol_version, organization, and supported_versions. -import { SPEC_VERSION } from "../spec.js"; -import { Problems, VERSION_PATTERN, describe, hostOf, isDomain, isObject, show } from "../util.js"; +import { CHANGELOG_URL, SPEC_VERSION } from "../spec.js"; +import { Problems, VERSION_PATTERN, describe, hostOf, isDomain, isHttpsUrl, isObject, majorOf, show } from "../util.js"; +import { VERSION } from "../version.js"; import { defineRule, docOf, fail, pass, skip } from "./define.js"; export const versionPresent = defineRule( @@ -12,6 +13,7 @@ export const versionPresent = defineRule( stage: "document", severity: "error", section: "3.1", + allVersions: true, }, (ctx) => { const value = docOf(ctx).protocol_version; @@ -34,6 +36,7 @@ export const versionFormat = defineRule( stage: "document", severity: "error", section: "3.1", + allVersions: true, }, (ctx) => { const value = docOf(ctx).protocol_version; @@ -48,25 +51,34 @@ export const versionFormat = defineRule( export const versionCompatible = defineRule( { id: "version.compatible", - title: "protocol_version is a 1.x version", + title: "protocol_version is compatible with 1.0", group: "Document", stage: "document", - severity: "warning", + severity: "error", section: "3.4", + allVersions: true, }, (ctx) => { - const value = docOf(ctx).protocol_version; - if (typeof value !== "string" || !VERSION_PATTERN.test(value)) return skip("protocol_version isn't valid; see version.format."); - const major = Number(value.split(".")[0]); + const doc = docOf(ctx); + const value = doc.protocol_version; + const major = majorOf(value); + if (major === undefined) return skip("protocol_version isn't valid; see version.format."); if (major === 1) return pass; + // A 1.0 Personal Agent uses a 1.x document that supported_versions lists instead (spec 3.4). + const versions = doc.supported_versions; + if (isObject(versions) && Object.entries(versions).some(([v, url]) => majorOf(v) === 1 && isHttpsUrl(url))) return pass; if (major === 0) { return fail( "protocol_version", - `${value} is a pre-1.0 draft. Before 1.0, versions are compatible only with the same minor version, so only Personal Agents that implement exactly ${value} will use this document`, - `Update the document to ${SPEC_VERSION}, the current published version. Keep the old one in supported_versions if you still serve it.`, + `${value} is a pre-1.0 draft. Before 1.0, a version is compatible only with the same minor version, so a Personal Agent that implements only ${SPEC_VERSION} must not use this document. Pollen checks ${SPEC_VERSION} documents, so it skipped the field rules`, + `Publish a ${SPEC_VERSION} document: set protocol_version to "${SPEC_VERSION}" and apply the changes since ${value} in the changelog (${CHANGELOG_URL}). To keep serving ${value} as well, move it to another URL and list it in supported_versions. If your platform generates poppy.json for you, it has to make this change.`, ); } - return fail("protocol_version", `${value} is newer than any published version; Pollen checks against ${SPEC_VERSION}`, `Check the version. The current published version is ${SPEC_VERSION}.`); + return fail( + "protocol_version", + `${value} is a newer major version than ${SPEC_VERSION}, and Pollen ${VERSION} checks only 1.x documents, so it skipped the field rules`, + `Check the version, or use a Pollen release that supports ${major}.x.`, + ); }, ); @@ -195,6 +207,7 @@ export const supportedVersions = defineRule( stage: "document", severity: "error", section: "3.4", + allVersions: true, }, (ctx) => { const doc = docOf(ctx); diff --git a/src/spec.ts b/src/spec.ts index 78909e7..5f7ac22 100644 --- a/src/spec.ts +++ b/src/spec.ts @@ -14,6 +14,7 @@ export const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-serve export const SPEC_BASE = "https://personalagentprotocol.org/docs/1.0/spec"; export const EXTENSIONS_BASE = "https://personalagentprotocol.org/docs/1.0/extensions"; export const ROADMAP_URL = "https://personalagentprotocol.org/docs/introduction#mediated-sign-in"; +export const CHANGELOG_URL = "https://personalagentprotocol.org/docs/changelog"; /** Spec section number to its anchor on the spec page. */ export const SECTION_ANCHORS: Record = { diff --git a/src/types.ts b/src/types.ts index c4a5f9b..1f570a4 100644 --- a/src/types.ts +++ b/src/types.ts @@ -102,6 +102,12 @@ export interface Rule { section: string; /** Absolute URL of the section in the spec. */ specUrl: string; + /** + * Runs whatever protocol_version says. Spec 3.4: the document's location and fetching, + * protocol_version, and supported_versions keep their meaning in every version. Other + * document and OAuth rules are 1.0 rules, and only run on 1.x documents. + */ + allVersions?: boolean; check(ctx: Context): Outcome; } diff --git a/src/util.ts b/src/util.ts index fbfa3c1..33395a3 100644 --- a/src/util.ts +++ b/src/util.ts @@ -31,6 +31,11 @@ export function isDomain(value: unknown): value is string { export const VERSION_PATTERN = /^[0-9]+\.[0-9]+$/; +/** The major version of a major.minor string, or undefined if it isn't one. */ +export function majorOf(value: unknown): number | undefined { + return typeof value === "string" && VERSION_PATTERN.test(value) ? Number(value.split(".")[0]) : undefined; +} + /** Scope tokens, RFC 6749 §3.3. */ export const SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/; From 2e2d06bfcc867e483f04b99e4bede7cafe66e634 Mon Sep 17 00:00:00 2001 From: NHTanvir Date: Tue, 17 Nov 2026 21:38:49 +0600 Subject: [PATCH 2/2] Test version handling and add a pre-1.0 fixture Refs #1 --- tests/check.test.ts | 48 ++++++++++++++++++++- tests/cli.test.ts | 2 +- tests/fixtures/invalid/pre-1.0-version.json | 23 ++++++++++ tests/fixtures/manifest.json | 1 + tests/report.test.ts | 2 +- tests/rules.test.ts | 7 ++- 6 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 tests/fixtures/invalid/pre-1.0-version.json diff --git a/tests/check.test.ts b/tests/check.test.ts index 8f1e246..9a8b794 100644 --- a/tests/check.test.ts +++ b/tests/check.test.ts @@ -6,7 +6,7 @@ import { after, describe, it } from "node:test"; import { check, PENALTIES, resolveTarget, score, TargetError, validateDocument } from "../src/check.js"; import { RULES } from "../src/rules/index.js"; import type { RuleResult } from "../src/types.js"; -import { WELL_KNOWN, base, live, make } from "./helpers.js"; +import { DOMAIN, ORIGIN, WELL_KNOWN, base, failedErrors, fakeFetcher, live, make, offline, result } from "./helpers.js"; const dir = mkdtempSync(join(tmpdir(), "pollen-check-")); after(() => rmSync(dir, { recursive: true, force: true })); @@ -124,3 +124,49 @@ describe("reports", () => { assert.equal(report.results.find((x) => x.id === "organization.domain-host")?.status, "fail"); }); }); + +describe("documents in another version", () => { + // The shape of a 0.4 document: its agent entry has no description, which only 1.0 requires. + const draft = () => ({ + protocol_version: "0.4", + organization: { name: "Fern & Finch Bakery", domain: DOMAIN }, + agent: { protocols: [{ type: "ucp", endpoint: `${ORIGIN}/.well-known/ucp` }] }, + web: {}, + extensions: { ucp: [{ version: "1" }] }, + }); + + it("fail version.compatible, not the 1.0 field rules", () => { + const report = offline(draft()); + assert.deepEqual(failedErrors(report), ["version.compatible"]); + const agent = result(report, "agent.protocols"); + assert.equal(agent.status, "skip"); + assert.match(agent.note!, /protocol_version is 0\.4/); + assert.equal(report.score, 75); + }); + + it("still run the rules every version shares", async () => { + const report = await live(draft()); + for (const id of ["transport.https", "transport.status", "transport.final-url", "document.json", "version.present", "version.format"]) { + assert.equal(result(report, id).status, "pass", id); + } + assert.equal(result(report, "versions.supported").note, "No supported_versions (optional)."); + }); + + it("don't fetch OAuth metadata", async () => { + const log: string[] = []; + const report = await check(DOMAIN, { fetcher: fakeFetcher({ [WELL_KNOWN]: { body: draft() } }, log) }); + assert.deepEqual(log, [WELL_KNOWN]); + assert.match(result(report, "oauth.issuer").note!, /only to 1\.x documents/); + }); + + it("are checked against the 1.0 rules when the version is malformed", () => { + const report = offline({ ...draft(), protocol_version: "zero" }); + assert.deepEqual(failedErrors(report), ["version.format", "agent.protocols"]); + }); + + it("pass when supported_versions lists a 1.x document, without checking this one's fields", () => { + const report = offline({ ...draft(), supported_versions: { "1.0": `${ORIGIN}/poppy/1.0.json` } }); + assert.deepEqual(failedErrors(report), []); + assert.equal(result(report, "agent.protocols").status, "skip"); + }); +}); diff --git a/tests/cli.test.ts b/tests/cli.test.ts index 4030829..17c4cbb 100644 --- a/tests/cli.test.ts +++ b/tests/cli.test.ts @@ -79,7 +79,7 @@ describe("pollen check", () => { it("exits 0 for a valid document", async () => { const { code, stdout } = await run(["check", VALID]); assert.equal(code, 0); - assert.match(stdout, /PASS {2}Personal Agents can use this document\./); + assert.match(stdout, /PASS {2}Poppy 1\.0 Personal Agents can use this document\./); }); it("exits 1 for an invalid document and shows the fix", async () => { diff --git a/tests/fixtures/invalid/pre-1.0-version.json b/tests/fixtures/invalid/pre-1.0-version.json new file mode 100644 index 0000000..d56cf85 --- /dev/null +++ b/tests/fixtures/invalid/pre-1.0-version.json @@ -0,0 +1,23 @@ +{ + "protocol_version": "0.4", + "organization": { + "name": "Fern & Finch Bakery", + "domain": "fernandfinch.example" + }, + "agent": { + "protocols": [ + { + "type": "ucp", + "endpoint": "https://fernandfinch.example/.well-known/ucp" + } + ] + }, + "web": {}, + "extensions": { + "ucp": [ + { + "version": "1" + } + ] + } +} diff --git a/tests/fixtures/manifest.json b/tests/fixtures/manifest.json index 516addf..535f95b 100644 --- a/tests/fixtures/manifest.json +++ b/tests/fixtures/manifest.json @@ -9,6 +9,7 @@ "invalid": { "missing-protocol-version.json": "version.present", "version-not-major-minor.json": "version.format", + "pre-1.0-version.json": "version.compatible", "domain-with-scheme.json": "organization.domain", "supported-version-on-other-host.json": "versions.supported", "no-channels.json": "channels.present", diff --git a/tests/report.test.ts b/tests/report.test.ts index 117fc36..d5c7437 100644 --- a/tests/report.test.ts +++ b/tests/report.test.ts @@ -23,7 +23,7 @@ describe("formatText", () => { const text = formatText(broken()); assert.match(text, /Score 70\/100 {3}\d+ passed · 1 error · 1 warning · \d+ skipped/); assert.match(text, /FAIL {2}Fix the 1 error above/); - assert.match(formatText(offline(base())), /PASS {2}Personal Agents can use this document\.\n$/); + assert.match(formatText(offline(base())), /PASS {2}Poppy 1\.0 Personal Agents can use this document\.\n$/); }); it("says when there's no document at all", async () => { diff --git a/tests/rules.test.ts b/tests/rules.test.ts index b655d09..18a451b 100644 --- a/tests/rules.test.ts +++ b/tests/rules.test.ts @@ -104,8 +104,13 @@ const CASES: Record = { "version.compatible": [ { name: "1.0", run: () => offline(base()), expect: "pass" }, { name: "1.1 (draft minor)", run: () => offline(make((d) => (d.protocol_version = "1.1"))), expect: "pass" }, + { + name: "0.4 that lists a 1.0 document in supported_versions", + run: () => offline(make((d) => ((d.protocol_version = "0.4"), (d.supported_versions = { "1.0": `${ORIGIN}/poppy/1.0.json` })))), + expect: "pass", + }, { name: "0.4 (pre-1.0)", run: () => offline(make((d) => (d.protocol_version = "0.4"))), expect: "fail", match: /pre-1\.0/ }, - { name: "2.0 (unknown major)", run: () => offline(make((d) => (d.protocol_version = "2.0"))), expect: "fail", match: /newer than any published/ }, + { name: "2.0 (unknown major)", run: () => offline(make((d) => (d.protocol_version = "2.0"))), expect: "fail", match: /newer major version/ }, { name: "malformed", run: () => offline(make((d) => (d.protocol_version = "one"))), expect: "skip" }, ], "organization.present": [