@worker-protocol/conformance 0.1.0

package/dist/checks/activity.js

@@ -0,0 +1,64 @@
+import { activityEntry, activityPage } from "@worker-protocol/schemas";
+import { ruleFor } from "../attribution.js";
+import { verdicts } from "../report.js";
+/**
+ * The `activity` Capability.
+ *
+ * Alerts with the words changed, which is what `spec/activity.md` says it is: one address, one
+ * page, items that carry a closed-vocabulary state and a summary addressed to a person. What these
+ * checks can reach is exactly what a program can act on — that the page has the shape and that
+ * every state is one of the three.
+ *
+ * ACTV-5 is absent because nothing can reach it. An activity that disappears may have finished,
+ * failed, or been dropped, and no tool outside the Worker can tell which — the same shape as ALRT-5
+ * and TASK-15. ACTV-6 is `H` and lives in `arranged.ts` with ALRT-6, because two credentials have
+ * to exist before two lists can be compared.
+ */
+export const CLAIMS = ["ACTV-1", "ACTV-2", "ACTV-3", "ACTV-4"];
+export async function checkActivity(entry, url, rules, attribution, transcript) {
+    const { results, say, allExcept } = verdicts(rules, CLAIMS);
+    if (entry === undefined) {
+        allExcept("notExercised", "the Worker declares no `activity`");
+        return results;
+    }
+    const declared = activityEntry.safeParse(entry);
+    if (!declared.success) {
+        const issue = declared.error.issues[0];
+        const id = ruleFor(attribution, "activity-entry", issue?.path ?? []) ?? "ACTV-1";
+        say(id, "fails", `${issue?.path.join(".") || "(root)"}: ${issue?.message}`);
+        allExcept("notExercised", "the `activity` entry did not validate", [id]);
+        return results;
+    }
+    say("ACTV-1", "passes");
+    if (url === null) {
+        allExcept("notExercised", "the declared address did not resolve", ["ACTV-1"]);
+        return results;
+    }
+    const answer = await transcript.send(url, "what the Worker is doing and has undertaken");
+    if (answer.status !== 200) {
+        say("ACTV-2", "fails", `the address answered ${answer.status}`);
+        allExcept("notExercised", "no page of activities was read", ["ACTV-1", "ACTV-2"]);
+        return results;
+    }
+    const page = activityPage.safeParse(answer.json);
+    if (!page.success) {
+        const issue = page.error.issues[0];
+        const id = ruleFor(attribution, "activity-page", issue?.path ?? []) ?? "ACTV-2";
+        say(id, "fails", `${issue?.path.join(".") || "(root)"}: ${issue?.message}`);
+        allExcept("notExercised", "the page did not validate", ["ACTV-1", id]);
+        return results;
+    }
+    say("ACTV-2", "passes");
+    // ACTV-3 and ACTV-4 are what validation established, said per rule because a report naming one
+    // of them is the point of having ids. A Worker holding nothing exercises neither, and that is
+    // `not exercised` rather than a pass: an empty page is conformant and proves nothing about the
+    // shape of an activity.
+    if (page.data.items.length === 0) {
+        say("ACTV-3", "notExercised", "the Worker holds nothing, so no activity was read");
+        say("ACTV-4", "notExercised", "the Worker holds nothing, so no state was read");
+        return results;
+    }
+    say("ACTV-3", "passes");
+    say("ACTV-4", "passes");
+    return results;
+}

package/dist/checks/alerts.d.ts

@@ -0,0 +1,16 @@
+import { type Attribution } from "../attribution.ts";
+import { type Result, type Rule } from "../report.ts";
+import type { Transcript } from "../transcript.ts";
+/**
+ * The `alerts` Capability.
+ *
+ * The smallest surface in the protocol after `health`, and the only one whose whole content is
+ * addressed to a person: ALRT-3's summary is parsed by nothing. What a program acts on is the
+ * severity and the Actions, and both are closed vocabularies a console renders without knowing
+ * anything about the Worker — which is what these checks can therefore reach.
+ *
+ * ALRT-5 is absent because nothing can reach it. An Alert that disappears may have had its
+ * condition stop holding, or may have been dismissed by somebody this verifier never saw.
+ */
+export declare const CLAIMS: readonly ["ALRT-1", "ALRT-2", "ALRT-3", "ALRT-4", "ALRT-7"];
+export declare function checkAlerts(entry: Record<string, unknown> | undefined, url: string | null, actionNames: string[], rules: Map<string, Rule>, attribution: Attribution, transcript: Transcript): Promise<Result[]>;

package/dist/checks/alerts.js

@@ -0,0 +1,84 @@
+import { alertPage, alertsEntry } from "@worker-protocol/schemas";
+import { ruleFor } from "../attribution.js";
+import { verdicts } from "../report.js";
+/**
+ * The `alerts` Capability.
+ *
+ * The smallest surface in the protocol after `health`, and the only one whose whole content is
+ * addressed to a person: ALRT-3's summary is parsed by nothing. What a program acts on is the
+ * severity and the Actions, and both are closed vocabularies a console renders without knowing
+ * anything about the Worker — which is what these checks can therefore reach.
+ *
+ * ALRT-5 is absent because nothing can reach it. An Alert that disappears may have had its
+ * condition stop holding, or may have been dismissed by somebody this verifier never saw.
+ */
+export const CLAIMS = ["ALRT-1", "ALRT-2", "ALRT-3", "ALRT-4", "ALRT-7"];
+export async function checkAlerts(entry, url, actionNames, rules, attribution, transcript) {
+    const { results, say, allExcept } = verdicts(rules, CLAIMS);
+    if (entry === undefined) {
+        allExcept("notExercised", "the Worker declares no `alerts`");
+        return results;
+    }
+    const declared = alertsEntry.safeParse(entry);
+    if (!declared.success) {
+        const issue = declared.error.issues[0];
+        const id = ruleFor(attribution, "alerts-entry", issue?.path ?? []) ?? "ALRT-1";
+        say(id, "fails", `${issue?.path.join(".") || "(root)"}: ${issue?.message}`);
+        allExcept("notExercised", "the `alerts` entry did not validate", [id]);
+        return results;
+    }
+    say("ALRT-1", "passes");
+    if (url === null) {
+        allExcept("notExercised", "the declared address did not resolve", ["ALRT-1"]);
+        return results;
+    }
+    const answer = await transcript.send(url, "the Alerts whose conditions hold");
+    if (answer.status !== 200) {
+        say("ALRT-2", "fails", `the address answered ${answer.status}`);
+        allExcept("notExercised", "no page of Alerts was read", ["ALRT-1", "ALRT-2"]);
+        return results;
+    }
+    const page = alertPage.safeParse(answer.json);
+    if (!page.success) {
+        const issue = page.error.issues[0];
+        const id = ruleFor(attribution, "alert-page", issue?.path ?? []) ?? "ALRT-2";
+        say(id, "fails", `${issue?.path.join(".") || "(root)"}: ${issue?.message}`);
+        allExcept("notExercised", "the page did not validate", ["ALRT-1", id]);
+        return results;
+    }
+    say("ALRT-2", "passes");
+    // ALRT-3 and ALRT-4 are what validation established, said per rule because a report naming one
+    // of them is the point of having ids. A Worker with nothing to report exercises neither, and
+    // that is `not exercised` rather than a pass — an empty page is conformant and proves nothing
+    // about the shape of an Alert.
+    if (page.data.items.length === 0) {
+        say("ALRT-3", "notExercised", "no condition is holding, so no Alert was read");
+        say("ALRT-4", "notExercised", "no condition is holding, so no severity was read");
+        say("ALRT-7", "notExercised", "no condition is holding, so no Action was offered");
+        return results;
+    }
+    say("ALRT-3", "passes");
+    say("ALRT-4", "passes");
+    // ALRT-7: every Action an Alert offers is one this Worker's own `actions` entry accepts. An
+    // agreement between two entries, which is the part no schema reaches — and a Descriptor
+    // disagreeing with itself is DESC-18 one level down.
+    const accepted = new Set(actionNames);
+    const dangling = [];
+    for (const alert of page.data.items) {
+        for (const action of alert.actions) {
+            if (!accepted.has(action))
+                dangling.push(`${alert.id} offers \`${action}\``);
+        }
+    }
+    const offered = page.data.items.some((alert) => alert.actions.length > 0);
+    if (!offered) {
+        say("ALRT-7", "notExercised", "no Alert offers an Action");
+    }
+    else if (dangling.length === 0) {
+        say("ALRT-7", "passes");
+    }
+    else {
+        say("ALRT-7", "fails", `${dangling.join("; ")}, which its \`actions\` entry does not accept`);
+    }
+    return results;
+}

package/dist/checks/arranged.d.ts

@@ -0,0 +1,27 @@
+import type { Arrangement } from "../index.ts";
+import { type Result, type Rule } from "../report.ts";
+import type { Transcript } from "../transcript.ts";
+/**
+ * The rules that need something no Worker has by accident.
+ *
+ * A second credential, a boot window, settings its operators will let go of, an event it already
+ * published. `conformance/verifiability.md` classes these `H` because nothing a tool can do to an
+ * unarranged Worker will ever see a violation — and the arrangement cannot come from the protocol,
+ * because test scaffolding in a Descriptor would be carried by every Worker in the network to
+ * serve a tool most of them will never meet.
+ *
+ * Every one of them reports what was missing rather than a verdict, which is a gap somebody can
+ * close and not a claim about the Worker.
+ */
+export declare const CLAIMS: readonly ["REG-8", "REG-28", "REG-32", "ALRT-6", "ACTV-6", "TASK-6", "HLTH-4", "ACT-14", "EVT-1"];
+type Surfaces = {
+    descriptorUrl: string | null;
+    alertsUrl: string | null;
+    activityUrl: string | null;
+    tasksUrl: string | null;
+    settingsUrl: string | null;
+    workerId: string | null;
+    eventTypes: string[];
+};
+export declare function checkArranged(surfaces: Surfaces, arrangement: Arrangement, mayPerform: boolean, rules: Map<string, Rule>, transcript: Transcript): Promise<Result[]>;
+export {};

package/dist/checks/arranged.js

@@ -0,0 +1,232 @@
+import { health as healthSchema, taskPage } from "@worker-protocol/schemas";
+import { verdicts } from "../report.js";
+/**
+ * The rules that need something no Worker has by accident.
+ *
+ * A second credential, a boot window, settings its operators will let go of, an event it already
+ * published. `conformance/verifiability.md` classes these `H` because nothing a tool can do to an
+ * unarranged Worker will ever see a violation — and the arrangement cannot come from the protocol,
+ * because test scaffolding in a Descriptor would be carried by every Worker in the network to
+ * serve a tool most of them will never meet.
+ *
+ * Every one of them reports what was missing rather than a verdict, which is a gap somebody can
+ * close and not a claim about the Worker.
+ */
+export const CLAIMS = [
+    "REG-8",
+    "REG-28",
+    "REG-32",
+    "ALRT-6",
+    "ACTV-6",
+    "TASK-6",
+    "HLTH-4",
+    "ACT-14",
+    "EVT-1",
+];
+/**
+ * The surfaces where two credentials must be served one list, and the rule each one is.
+ *
+ * A table rather than a block each, because the rule is mechanical: any read-only surface whose
+ * audience is whoever operates the Worker gets one, and the two that exist derive from each other
+ * by substitution. TASK-6 is deliberately not here — the comment below says why it reads the
+ * other way.
+ */
+const SAME_TO_BOTH = [
+    { rule: "ALRT-6", url: "alertsUrl", capability: "alerts", one: "the Alerts", many: "Alerts" },
+    {
+        rule: "ACTV-6",
+        url: "activityUrl",
+        capability: "activity",
+        one: "the activity",
+        many: "activities",
+    },
+];
+export async function checkArranged(surfaces, arrangement, mayPerform, rules, transcript) {
+    const { results, say } = verdicts(rules, CLAIMS);
+    const asSecond = (url, intent) => transcript.send(url, intent, {
+        headers: { authorization: `Bearer ${arrangement.secondCredential}` },
+    });
+    // REG-28 (recommended), REG-8, ALRT-6 and ACTV-6 all need a second credential, and it is one
+    // arrangement because it is one thing an operator issues.
+    const second = arrangement.secondCredential;
+    if (second === undefined || surfaces.descriptorUrl === null) {
+        for (const id of ["REG-28", "REG-8", ...SAME_TO_BOTH.map((one) => one.rule)]) {
+            say(id, "notExercised", "no second credential was given to the verifier");
+        }
+    }
+    else {
+        // REG-28: without it rotation is a flag day — the old credential stops at the instant the new
+        // one starts, and every caller holding the old one fails in the window between.
+        const withSecond = await asSecond(surfaces.descriptorUrl, "the Descriptor, second credential");
+        if (withSecond.status === 200) {
+            say("REG-28", "passes");
+        }
+        else {
+            say("REG-28", "fails", `the second credential answered ${withSecond.status}`);
+        }
+        // REG-8: a Descriptor filtered per reader is a different document to every reader, and a
+        // consumer then cannot tell a Capability it may not use from one the Worker withdrew.
+        const withFirst = await transcript.send(surfaces.descriptorUrl, "the Descriptor, again");
+        if (withSecond.status !== 200 || withFirst.status !== 200) {
+            say("REG-8", "notExercised", "one of the two credentials did not read the Descriptor");
+        }
+        else if (withFirst.body === withSecond.body) {
+            say("REG-8", "passes");
+        }
+        else {
+            say("REG-8", "fails", "the two credentials were served different Descriptors");
+        }
+        // ALRT-6 and ACTV-6 are one rule read on two surfaces: both are for whoever OPERATES the
+        // Worker, which is a relationship of enrollment, so every credential it authenticates sees one
+        // list. A third read-only surface with that audience gets a row here rather than a block.
+        for (const { rule, url, capability, one, many } of SAME_TO_BOTH) {
+            const address = surfaces[url];
+            if (address === null) {
+                say(rule, "notExercised", `the Worker declares no \`${capability}\``);
+                continue;
+            }
+            const first = await transcript.send(address, `${one}, first credential`);
+            const second = await asSecond(address, `${one}, second credential`);
+            if (first.status !== 200 || second.status !== 200) {
+                say(rule, "notExercised", `one of the two credentials did not read ${one}`);
+            }
+            else if (first.body === second.body) {
+                say(rule, "passes");
+            }
+            else {
+                say(rule, "fails", `the two credentials were served different ${many}`);
+            }
+        }
+    }
+    // TASK-6 is the one that reads the other way. Alerts are for whoever operates the Worker, so
+    // two credentials seeing the same list is the rule holding; Tasks are what a Contract covers,
+    // so two credentials seeing the same list proves only that this Worker had nothing to filter.
+    // The credential compared against is a Contract's where one was arranged — that is the party
+    // the rule is about — and the second credential otherwise.
+    const consumer = arrangement.consumerCredential ?? second;
+    if (consumer === undefined) {
+        say("TASK-6", "notExercised", "no Contract credential was given to the verifier");
+    }
+    else if (surfaces.tasksUrl === null) {
+        say("TASK-6", "notExercised", "the Worker declares no `tasks`");
+    }
+    else {
+        const a = taskPage.safeParse((await transcript.send(surfaces.tasksUrl, "Tasks, first")).json);
+        const b = taskPage.safeParse((await transcript.send(surfaces.tasksUrl, "Tasks, Contract credential", {
+            headers: { authorization: `Bearer ${consumer}` },
+        })).json);
+        if (!a.success || !b.success) {
+            say("TASK-6", "notExercised", "one of the two reads did not validate");
+        }
+        else {
+            const ids = (page) => (page.success ? page.data.items.map((t) => t.id) : []);
+            const first = new Set(ids(a));
+            const other = ids(b);
+            if (other.length === first.size && other.every((id) => first.has(id))) {
+                say("TASK-6", "notExercised", "both credentials see the same Tasks, which is consistent with filtering and with not filtering");
+            }
+            else {
+                say("TASK-6", "passes");
+            }
+        }
+    }
+    // REG-32 (recommended): a refusal that explains itself is an oracle. A caller told *that key is
+    // expired* rather than *no* has learned the key exists.
+    const unprivileged = arrangement.unprivilegedCredential;
+    if (unprivileged === undefined || surfaces.descriptorUrl === null) {
+        say("REG-32", "notExercised", "no credential was given that authenticates and lacks a right");
+    }
+    else {
+        const lacking = await transcript.send(surfaces.descriptorUrl, "a credential that lacks a right", {
+            headers: { authorization: `Bearer ${unprivileged}` },
+            permanent: true,
+        });
+        const nonsense = await transcript.send(surfaces.descriptorUrl, "a credential never issued", {
+            headers: { authorization: "Bearer never-issued-7a2c" },
+            permanent: true,
+        });
+        if (lacking.status < 400 || nonsense.status < 400) {
+            say("REG-32", "notExercised", "the Worker refused neither, so there is nothing to compare");
+        }
+        else if (lacking.body === nonsense.body || lacking.status !== nonsense.status) {
+            // Either the two refusals say the same thing, or they are different KINDS of refusal, which
+            // ENDP-29 divides at whether the credential could be read. Neither tells a caller which
+            // credential or scope would have changed the answer.
+            say("REG-32", "passes");
+        }
+        else {
+            say("REG-32", "fails", "two refusals of the same status said different things");
+        }
+    }
+    // HLTH-4: a Worker that has not yet established its state answers `unhealthy`, never `healthy`.
+    // The window is between a process starting and its first evaluation, and only whoever started it
+    // knows the verifier is inside one.
+    if (arrangement.justStarted !== true) {
+        say("HLTH-4", "notExercised", "the verifier was not told the Worker had just started");
+    }
+    else if (arrangement.healthUrl === undefined) {
+        say("HLTH-4", "notExercised", "no health address was resolved");
+    }
+    else {
+        const polled = await transcript.send(arrangement.healthUrl, "health, immediately after start");
+        const parsed = healthSchema.safeParse(polled.json);
+        if (!parsed.success) {
+            say("HLTH-4", "notExercised", "the health answer did not validate");
+        }
+        else if (parsed.data.status === "healthy") {
+            say("HLTH-4", "fails", "it answered `healthy` before establishing its state");
+        }
+        else {
+            say("HLTH-4", "passes");
+        }
+    }
+    // ACT-14: the input of `configure` is the complete settings document. What a check establishes
+    // is that the whole document round-trips — over a closed schema that requires every member,
+    // replacing and merging are the same operation, and this is the honest limit of the witness.
+    if (arrangement.replaceableSettings !== true || !mayPerform) {
+        say("ACT-14", "notExercised", "the verifier was not permitted to replace this Worker's settings");
+    }
+    else if (surfaces.settingsUrl === null || arrangement.actionsUrl === undefined) {
+        say("ACT-14", "notExercised", "no `configure` reading address was resolved");
+    }
+    else {
+        const before = await transcript.send(surfaces.settingsUrl, "the settings, before");
+        const written = await transcript.send(`${arrangement.actionsUrl}?action=configure`, "configure, with what it already holds", {
+            method: "POST",
+            body: before.body,
+        });
+        const after = await transcript.send(surfaces.settingsUrl, "the settings, after");
+        if (written.status >= 400) {
+            say("ACT-14", "fails", `configure refused its own document with ${written.status}`);
+        }
+        else if (before.body === after.body) {
+            say("ACT-14", "passes");
+        }
+        else {
+            say("ACT-14", "fails", "the settings changed when the Worker was handed what it already held");
+        }
+    }
+    // EVT-1: `source` is the Worker's id and `type` is one the entry declares. The verifier holds no
+    // broker and sees no event, so the only way to reach this is to be handed one.
+    const published = arrangement.publishedEvent;
+    if (published === undefined) {
+        say("EVT-1", "notExercised", "no published event was given to the verifier");
+    }
+    else {
+        const event = published;
+        const faults = [];
+        if (typeof event.id !== "string" || event.id.length === 0)
+            faults.push("no `id`");
+        if (event.source !== surfaces.workerId) {
+            faults.push(`\`source\` is ${JSON.stringify(event.source)} and the Worker's id is ${JSON.stringify(surfaces.workerId)}`);
+        }
+        if (typeof event.type !== "string" || !surfaces.eventTypes.includes(event.type)) {
+            faults.push(`\`type\` ${JSON.stringify(event.type)} is not one the entry declares`);
+        }
+        if (faults.length === 0)
+            say("EVT-1", "passes");
+        else
+            say("EVT-1", "fails", faults.join("; "));
+    }
+    return results;
+}

package/dist/checks/descriptor.d.ts

@@ -0,0 +1,34 @@
+import { type Attribution } from "../attribution.ts";
+import { type Result, type Rule } from "../report.ts";
+import type { Transcript } from "../transcript.ts";
+/**
+ * What the Descriptor document alone establishes.
+ *
+ * Every rule here is one `conformance/verifiability.md` classifies `W`, and every one of them is
+ * reached without calling a single declared address — which is why this is the slice the verifier
+ * started with: it is the only surface a Worker is required to have at all (DESC-1).
+ *
+ * DESC-18 is deliberately absent. It is `W`, but its witness is a declared address answering 404,
+ * so it belongs with the checks that call one.
+ */
+export declare const CLAIMS: readonly ["DESC-1", "DESC-3", "DESC-5", "DESC-6", "DESC-8", "DESC-9", "DESC-12", "DESC-14", "DESC-22", "DESC-23", "TASK-31"];
+export type Descriptor = {
+    id: string;
+    edition: string;
+    /** TASK-31. Absent for a Worker with no Skill, which DESC-2 admits of anything it does not do. */
+    skills?: Record<string, unknown>;
+    capabilities: Record<string, Record<string, unknown>>;
+};
+export type DescriptorReading = {
+    results: Result[];
+    /** The document, where one was read and validated. Later checks need its addresses. */
+    document: Descriptor | null;
+    /** The route it was read from, which later checks probe again. */
+    url: string | null;
+    /** Each declared address resolved against that route (DESC-12). */
+    surfaces: {
+        capability: string;
+        url: string;
+    }[];
+};
+export declare function readDescriptor(baseUrl: string, rules: Map<string, Rule>, attribution: Attribution, transcript: Transcript): Promise<DescriptorReading>;

package/dist/checks/descriptor.js

@@ -0,0 +1,179 @@
+import { capabilityName, descriptor as descriptorSchema, vendorCapabilityName, } from "@worker-protocol/schemas";
+import { ruleFor } from "../attribution.js";
+import { verdicts } from "../report.js";
+/**
+ * What the Descriptor document alone establishes.
+ *
+ * Every rule here is one `conformance/verifiability.md` classifies `W`, and every one of them is
+ * reached without calling a single declared address — which is why this is the slice the verifier
+ * started with: it is the only surface a Worker is required to have at all (DESC-1).
+ *
+ * DESC-18 is deliberately absent. It is `W`, but its witness is a declared address answering 404,
+ * so it belongs with the checks that call one.
+ */
+export const CLAIMS = [
+    "DESC-1",
+    "DESC-3",
+    "DESC-5",
+    "DESC-6",
+    "DESC-8",
+    "DESC-9",
+    "DESC-12",
+    "DESC-14",
+    "DESC-22",
+    "DESC-23",
+    // TASK-31 lives here rather than in the tasks check because `skills` is on the ROOT: a Worker
+    // that only ANSWERS Tasks declares a Skill and no `tasks` Capability at all, and a verdict
+    // reached only through that Capability would have been silent about exactly that Worker.
+    "TASK-31",
+];
+const ROUTE = ".well-known/worker-protocol";
+export async function readDescriptor(baseUrl, rules, attribution, transcript) {
+    const { results, say } = verdicts(rules, CLAIMS);
+    const nothingRead = (why, except) => {
+        for (const id of CLAIMS)
+            if (!except.includes(id))
+                say(id, "notExercised", why);
+    };
+    // DESC-3 is answered before anything is called, because its subject is the enrolled base URL and
+    // not the document. A verifier that reached the Worker over plaintext has already established
+    // the fault, and says so without pretending a call proved it.
+    let base;
+    try {
+        base = new URL(baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    }
+    catch {
+        say("DESC-3", "fails", `not a URL: ${baseUrl}`);
+        nothingRead("no Descriptor could be read", ["DESC-3"]);
+        return { results, document: null, url: null, surfaces: [] };
+    }
+    if (base.protocol === "https:")
+        say("DESC-3", "passes");
+    else
+        say("DESC-3", "fails", `the base URL is \`${base.protocol}\` and DESC-3 fixes \`https\``);
+    const url = new URL(ROUTE, base).toString();
+    let first;
+    try {
+        first = await transcript.send(url, "the Descriptor route");
+    }
+    catch (cause) {
+        const why = cause instanceof Error ? cause.message : String(cause);
+        say("DESC-1", "fails", `${url} could not be reached: ${why}`);
+        nothingRead("no Descriptor could be read", ["DESC-1", "DESC-3"]);
+        return { results, document: null, url, surfaces: [] };
+    }
+    if (first.status < 200 || first.status >= 300) {
+        say("DESC-1", "fails", `${url} answered ${first.status}`);
+        nothingRead("no Descriptor could be read", ["DESC-1", "DESC-3"]);
+        return { results, document: null, url, surfaces: [] };
+    }
+    if (first.json === null) {
+        say("DESC-1", "fails", `${url} did not answer JSON`);
+        nothingRead("the Descriptor did not parse", ["DESC-1", "DESC-3"]);
+        return { results, document: null, url, surfaces: [] };
+    }
+    // DESC-5: a GET changes nothing a later reader could observe, so the same request answers the
+    // same document. This is the weakest form of the check and it is the honest one — a verifier
+    // cannot prove the absence of a side effect, only catch a Worker whose read has one it shows.
+    const second = await transcript.send(url, "the Descriptor route, a second time");
+    if (second.status === first.status && second.body === first.body)
+        say("DESC-5", "passes");
+    else
+        say("DESC-5", "fails", "a second GET of the Descriptor answered something else");
+    const validation = descriptorSchema.safeParse(first.json);
+    /**
+     * DESC-8 and DESC-14, judged before the document as a whole.
+     *
+     * The attribution map cannot reach these, and the reason is worth stating rather than working
+     * around: the key schema is a union of the reserved enumeration and the vendor pattern, and a
+     * key that fails it matched neither — so nothing in `schemas/` says which branch it was reaching
+     * for. Attribution would land on DESC-22, and DESC-8 would become a rule that can pass and never
+     * fail, which is a check that only knows how to say yes.
+     *
+     * What tells them apart is DESC-14 itself: a name containing a `.` is the Worker's own, and a
+     * name without one is reserved to the edition or is nothing. That is the rule, applied — not the
+     * verifier deciding anything — and the enumeration it compares against is `capabilityName`,
+     * which is the normative list DESC-8 points at.
+     */
+    const keys = Object.keys(first.json?.capabilities ?? {});
+    const reserved = new Set(capabilityName.options);
+    const unknownReserved = keys.filter((key) => !key.includes(".") && !reserved.has(key));
+    const malformedVendor = keys.filter((key) => key.includes(".") && !vendorCapabilityName.safeParse(key).success);
+    const judgedKeys = new Set();
+    if (unknownReserved.length > 0) {
+        judgedKeys.add("DESC-8");
+        const names = unknownReserved.map((k) => `\`${k}\``).join(", ");
+        say("DESC-8", "fails", `${names}: undotted, and this edition defines no such Capability`);
+    }
+    if (malformedVendor.length > 0) {
+        judgedKeys.add("DESC-14");
+        const names = malformedVendor.map((k) => `\`${k}\``).join(", ");
+        say("DESC-14", "fails", `${names}: dotted, and not a well-formed vendor Capability name`);
+    }
+    if (!validation.success) {
+        // A report that answered "the Descriptor is invalid" would be the failure the rule ids exist
+        // to prevent: an operator cannot act on it, and two very different faults read identically.
+        // The rule each issue belongs to is read off `schemas/` rather than judged here — see
+        // `src/attribution.ts` for why that distinction is worth the machinery.
+        const blamed = new Set(judgedKeys);
+        // Where a key was already judged precisely above, the map's coarser verdict on the same fault
+        // is suppressed: DESC-22 is about the map's shape, and reporting it beside DESC-8 would give
+        // an operator two findings for one mistake and send them to the wrong one first.
+        if (judgedKeys.size > 0)
+            blamed.add("DESC-22");
+        for (const issue of validation.error.issues) {
+            const id = ruleFor(attribution, "descriptor", issue.path) ?? "DESC-1";
+            if (blamed.has(id))
+                continue;
+            blamed.add(id);
+            say(id, "fails", `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+        }
+        nothingRead("the Descriptor did not validate, so this could not be judged", [
+            "DESC-3",
+            "DESC-5",
+            ...blamed,
+        ]);
+        return { results, document: null, url, surfaces: [] };
+    }
+    const document = validation.data;
+    say("DESC-1", "passes");
+    // TASK-31: what this Worker answers, which is what a Tower catalogs it by. Absent is conformant
+    // and is not a pass — a Worker with no Skill exercised nothing, and saying so is the difference
+    // between a report that was checked and one that had nothing to check.
+    if (document.skills === undefined) {
+        say("TASK-31", "notExercised", "the Worker declares no Skill");
+    }
+    else {
+        say("TASK-31", "passes");
+    }
+    // DESC-6: the id is not the URL it is served from. DESC-27 and DESC-28 carry the clauses nothing
+    // outside can reach, and the report marks those unverified rather than passing them here.
+    const addresses = [base.toString(), base.toString().replace(/\/$/, ""), url];
+    if (addresses.includes(document.id)) {
+        say("DESC-6", "fails", "the id is the URL the Descriptor is served from");
+    }
+    else {
+        say("DESC-6", "passes");
+    }
+    // The rest are what validation established. Saying so per rule rather than once is the whole
+    // point of the ids: a reader learns which obligations were actually judged.
+    for (const id of ["DESC-8", "DESC-9", "DESC-12", "DESC-14", "DESC-22", "DESC-23"]) {
+        if (!judgedKeys.has(id))
+            say(id, "passes");
+    }
+    // DESC-12: an address is an absolute https URL, or a relative reference resolved against the URL
+    // the Descriptor was read from — which is this route, not the base URL.
+    const surfaces = [];
+    for (const [capability, entry] of Object.entries(document.capabilities)) {
+        if (typeof entry.address !== "string")
+            continue;
+        try {
+            surfaces.push({ capability, url: new URL(entry.address, url).toString() });
+        }
+        catch {
+            // Unreachable while validation passed, and swallowing it silently would be the one thing
+            // this file exists against — so it is left to DESC-12, which validation already judged.
+        }
+    }
+    return { results, document, url, surfaces };
+}

package/dist/checks/endpoints.d.ts

@@ -0,0 +1,17 @@
+import { type Result, type Rule } from "../report.ts";
+import { type Exchange } from "../transcript.ts";
+/**
+ * The rules that are about every response rather than about one surface.
+ *
+ * These run last, over the whole transcript, because several of them are statements no single
+ * exchange can break: ENDP-26 forbids one code arriving under two statuses, which is a fact about
+ * a set. A check that asked it inside one surface would be asking a question it could not answer.
+ */
+export declare const CLAIMS: readonly ["ENDP-1", "ENDP-11", "ENDP-4", "ENDP-5", "ENDP-19", "ENDP-25", "ENDP-26", "ENDP-29"];
+/** The status and class each code fixes, generated from endpoints.md into rules.json (ENDP-26). */
+export type Code = {
+    code: string;
+    status: number;
+    class: "reject" | "retry";
+};
+export declare function judgeTranscript(exchanges: Exchange[], codes: Code[], declared: Set<string>, rules: Map<string, Rule>): Result[];