@worker-protocol/conformance 0.1.0

package/dist/checks/surfaces.js

@@ -0,0 +1,249 @@
+import { verdicts } from "../report.js";
+/**
+ * What calling each declared address establishes, before any Capability's own file is consulted.
+ *
+ * DESC-18 is here rather than beside the Descriptor because its witness is a declared address
+ * answering `404`, which needs the call the Descriptor check deliberately does not make.
+ */
+export const CLAIMS = [
+    "DESC-18",
+    "REG-3",
+    "REG-7",
+    "REG-21",
+    "ENDP-2",
+    "ENDP-6",
+    "ENDP-24",
+];
+/**
+ * Capabilities whose surface is written rather than read.
+ *
+ * DESC-18's witness is a declared address answering `404`, and this sweep finds it with a GET —
+ * which is the right question for every surface but one. ENDP-3 puts everything that changes state
+ * behind a POST, so the Actions address answers `404` to a GET while serving perfectly well, and a
+ * check that read that as an undeclared surface would fail a conformant Worker on the one
+ * Capability that does anything. `checks/actions.ts` judges that address instead, with the POST it
+ * had to ask permission for, and `checks/nudges.ts` does the same for the other one.
+ */
+const WRITTEN = new Set(["actions", "nudges"]);
+export async function callSurfaces(surfaces, descriptorUrl, writeAddresses, rules, transcript, credential, mayPerform) {
+    const { results, say } = verdicts(rules, CLAIMS);
+    if (surfaces.length === 0) {
+        say("DESC-18", "passes", "the Descriptor declares no address, so none can be missing");
+    }
+    const missing = [];
+    const refused = [];
+    const answered = [];
+    for (const surface of surfaces) {
+        if (WRITTEN.has(surface.capability))
+            continue;
+        let answer;
+        try {
+            answer = await transcript.send(surface.url, `the \`${surface.capability}\` address`);
+        }
+        catch (cause) {
+            const why = cause instanceof Error ? cause.message : String(cause);
+            missing.push(`\`${surface.capability}\` at ${surface.url} could not be reached: ${why}`);
+            continue;
+        }
+        // DESC-18: a Descriptor that declares a Capability the Worker does not serve is a fault in the
+        // Descriptor, not in the surface — so the finding is reported against the document.
+        if (answer.status === 404) {
+            missing.push(`\`${surface.capability}\` is declared at ${surface.url} and answers 404`);
+        }
+        // REG-21: a Worker accepts the credential recorded for it on every address this protocol
+        // defines. A surface that refuses the recorded credential is not a surface a Tower can poll.
+        if (answer.status === 401 || answer.status === 403) {
+            refused.push(`\`${surface.capability}\` at ${surface.url} answered ${answer.status}`);
+        }
+        if (answer.status === 200) {
+            answered.push({ capability: surface.capability, url: surface.url, body: answer.body });
+        }
+    }
+    if (surfaces.length > 0) {
+        if (missing.length === 0)
+            say("DESC-18", "passes");
+        else
+            say("DESC-18", "fails", missing.join("; "));
+    }
+    await probeReads(answered, writeAddresses, mayPerform, transcript, say);
+    if (credential === undefined) {
+        // Without one there is nothing to present, and a Worker that reads openly is conformant —
+        // registration.md says in as many words that a Worker may answer more than REG-21 requires.
+        for (const id of ["REG-3", "REG-7", "REG-21"]) {
+            say(id, "notExercised", "no credential was given to the verifier");
+        }
+        return results;
+    }
+    if (refused.length === 0) {
+        say("REG-21", "passes");
+        // REG-3 fixes only how a credential is presented. What establishes it is that the Worker read
+        // one arriving as `Authorization: Bearer <token>` — which is what every call above did.
+        say("REG-3", "passes");
+    }
+    else {
+        say("REG-21", "fails", refused.join("; "));
+        say("REG-3", "notExercised", "the recorded credential was refused, so nothing read it");
+    }
+    // REG-7: a Worker does not answer 404 in place of 401 or 403 on an address it serves. The
+    // Descriptor's route is the one address every Worker has, and it answered above, so it is served
+    // by definition — which is exactly the precondition the rule needs.
+    const wrong = `${credential}-is-not-this`;
+    let probe;
+    try {
+        probe = await transcript.send(descriptorUrl, "the Descriptor with a credential it never issued", { headers: { authorization: `Bearer ${wrong}` }, permanent: true });
+    }
+    catch {
+        say("REG-7", "notExercised", "the Descriptor route could not be reached a second time");
+        return results;
+    }
+    if (probe.status === 404) {
+        say("REG-7", "fails", "the Descriptor route answered 404 to a credential it does not accept");
+    }
+    else if (probe.status === 401 || probe.status === 403) {
+        say("REG-7", "passes");
+    }
+    else {
+        // A Worker that serves its Descriptor openly is conformant (REG-31 only recommends a
+        // credential on addresses that change state), and there is then no refusal to judge.
+        say("REG-7", "notExercised", `the Worker answered ${probe.status} rather than refusing`);
+    }
+    return results;
+}
+/**
+ * What a declared surface can be asked, once it is known to answer.
+ *
+ * These are the last rules in [endpoints](../../../spec/endpoints.md) with a witness against an
+ * ordinary Worker, and each needs a request nothing else in a run would send: a parameter the
+ * Worker cannot know, a Capability version it cannot answer, a read repeated to see whether it
+ * changed anything.
+ */
+async function probeReads(answered, writeAddresses, mayPerform, transcript, say) {
+    // A Worker whose only declared surface is written — a thin proxy that accepts an operation and
+    // passes it on, which DESC-1's argument names as a Worker worth admitting — has nothing to read
+    // twice and nothing to hand an unknown filter to. ENDP-6 is not in that position: it is about a
+    // REQUEST, and a write is one, so it goes on below with whatever write addresses there are.
+    if (answered.length === 0) {
+        for (const id of ["ENDP-2", "ENDP-24"]) {
+            say(id, "notExercised", "no declared surface answered a read");
+        }
+        if (writeAddresses.length === 0 || !mayPerform) {
+            say("ENDP-6", "notExercised", "no surface was reachable to state a version at");
+            return;
+        }
+    }
+    // ENDP-2: a GET changes nothing a later reader could observe.
+    //
+    // **What is compared is which items came back, not which bytes.** Byte equality was the first
+    // form of this check and it was wrong in a way that only shows against a real Worker: a health
+    // `detail` carrying an observed value, or any surface whose facts moved between two reads,
+    // answers different bytes having changed nothing. Failing that Worker would be this tool
+    // inventing an obligation nobody wrote.
+    //
+    // What the rule is actually about is stated in its own argument: listing a Worker's open Tasks
+    // does not consume them, reading its Alerts does not dismiss them. The witness is items that
+    // were there and are gone, with none arriving — a read that empties what it read. That is not
+    // airtight either, because a Task may close on its own between two calls, and the detail says
+    // what was compared so a reader can weigh it.
+    const items = (payload) => {
+        try {
+            const parsed = JSON.parse(payload);
+            if (!Array.isArray(parsed.items))
+                return null;
+            return parsed.items.map((item) => typeof item === "object" && item !== null && "id" in item
+                ? String(item.id)
+                : JSON.stringify(item));
+        }
+        catch {
+            return null;
+        }
+    };
+    const emptied = [];
+    let collections = 0;
+    for (const surface of answered) {
+        const again = await transcript.send(surface.url, `the \`${surface.capability}\` address, again`);
+        if (again.status !== 200) {
+            emptied.push(`\`${surface.capability}\` answered ${again.status} on a second read`);
+            continue;
+        }
+        const before = items(surface.body);
+        const after = items(again.body);
+        if (before === null || after === null)
+            continue;
+        collections += 1;
+        const present = new Set(after);
+        const gone = before.filter((id) => !present.has(id));
+        const arrived = after.filter((id) => !new Set(before).has(id));
+        if (gone.length > 0 && arrived.length === 0) {
+            emptied.push(`\`${surface.capability}\` lost ${gone.length} item(s) to being read`);
+        }
+    }
+    if (answered.length > 0) {
+        if (emptied.length > 0)
+            say("ENDP-2", "fails", emptied.join("; "));
+        else if (collections === 0) {
+            say("ENDP-2", "notExercised", "no declared surface answered a collection to read twice");
+        }
+        else {
+            say("ENDP-2", "passes", "every collection answered the same items on a second read");
+        }
+    }
+    // ENDP-24: an unrecognized filter parameter is 400, and is never ignored.
+    const ignored = [];
+    for (const surface of answered) {
+        const probed = new URL(surface.url);
+        probed.searchParams.set("no-such-filter-8e31", "1");
+        const answer = await transcript.send(probed.toString(), "a filter the Worker cannot know", {
+            permanent: true,
+        });
+        const code = answer.json?.code;
+        if (answer.status !== 400 || code !== "unknown_filter") {
+            ignored.push(`\`${surface.capability}\` answered ${answer.status} with \`${code ?? "no code"}\``);
+        }
+    }
+    if (answered.length > 0) {
+        if (ignored.length === 0)
+            say("ENDP-24", "passes");
+        else
+            say("ENDP-24", "fails", ignored.join("; "));
+    }
+    // ENDP-6: a caller may state the Capability version it expects, and a Worker that cannot answer
+    // it refuses the request WHOLE rather than substituting its own. A version no edition will reach
+    // soon is the only way to ask without a Worker having to cooperate.
+    //
+    // The write addresses are probed too, and they are where the rule matters most: a Worker that
+    // refuses an unanswerable version on a read and PERFORMS one on a write has done the thing the
+    // rule exists to prevent, on the calls where being wrong costs something. They are POSTs, so
+    // they need `mayPerform` — and a Worker that obeys the rule performs nothing, which is why
+    // asking is safe once permission is given.
+    const unanswerable = [];
+    const probes = [
+        ...answered.map((surface) => ({
+            what: `\`${surface.capability}\``,
+            url: surface.url,
+            init: { headers: { "worker-protocol-capability-version": "99999" }, permanent: true },
+        })),
+        ...(mayPerform
+            ? writeAddresses.map((url) => ({
+                what: `the write address ${url}`,
+                url,
+                init: {
+                    method: "POST",
+                    body: "{}",
+                    headers: { "worker-protocol-capability-version": "99999" },
+                    permanent: true,
+                },
+            }))
+            : []),
+    ];
+    for (const probe of probes) {
+        const answer = await transcript.send(probe.url, "a Capability version the Worker cannot answer", probe.init);
+        const code = answer.json?.code;
+        if (answer.status !== 400 || code !== "unsupported_version") {
+            unanswerable.push(`${probe.what} answered ${answer.status} with \`${code ?? "no code"}\``);
+        }
+    }
+    if (unanswerable.length === 0)
+        say("ENDP-6", "passes");
+    else
+        say("ENDP-6", "fails", unanswerable.join("; "));
+}

package/dist/checks/tasks.d.ts

@@ -0,0 +1,23 @@
+import { type Attribution } from "../attribution.ts";
+import { type Result, type Rule } from "../report.ts";
+import type { Transcript } from "../transcript.ts";
+/**
+ * The `tasks` Capability, which is now reading and nothing else.
+ *
+ * Every check here is a GET, so none of them needs the operators' permission and none leaves the
+ * Worker changed. That was not true while a Claim existed: taking one was the most consequential
+ * thing a caller could do through this protocol, and half of this file was the sequence that took
+ * one carefully and gave it back. The lease is withdrawn and the sequence with it.
+ */
+export declare const CLAIMS: readonly ["TASK-27", "TASK-32", "TASK-4", "TASK-5", "TASK-8", "TASK-28", "NAME-7"];
+export declare function checkTasks(entry: Record<string, unknown> | undefined, url: string | null, 
+/** TASK-31, read off the Descriptor ROOT. Its names are Task types, so NAME-7 and TASK-4 reach
+ * them — and reach them even for a Worker that declares a Skill and no `tasks` entry. */
+skills: string[], 
+/** The `actions` entry's own map, because TASK-32 is about the Action's name AND its input. */
+accepts: Record<string, {
+    input?: unknown;
+}>, rules: Map<string, Rule>, attribution: Attribution, transcript: Transcript): Promise<{
+    results: Result[];
+    addresses: string[];
+}>;

package/dist/checks/tasks.js

@@ -0,0 +1,171 @@
+import { taskPage, tasksEntry } from "@worker-protocol/schemas";
+import { ruleFor } from "../attribution.js";
+import { verdicts } from "../report.js";
+/**
+ * The `tasks` Capability, which is now reading and nothing else.
+ *
+ * Every check here is a GET, so none of them needs the operators' permission and none leaves the
+ * Worker changed. That was not true while a Claim existed: taking one was the most consequential
+ * thing a caller could do through this protocol, and half of this file was the sequence that took
+ * one carefully and gave it back. The lease is withdrawn and the sequence with it.
+ */
+export const CLAIMS = [
+    "TASK-27",
+    "TASK-32",
+    "TASK-4",
+    "TASK-5",
+    "TASK-8",
+    "TASK-28",
+    "NAME-7",
+];
+/**
+ * Whether a union's variants are told apart by a discriminator — TASK-32's second obligation.
+ *
+ * A member that every variant fixes to a constant of its own, which is what a discriminated union
+ * writes and what an answerer needs in order to say which ending it is producing. Without one a
+ * consumer reading the schema cannot name the ending it can reach, and the mapping TASK-32 exists
+ * to dissolve comes back as a conversation between two parties.
+ *
+ * The same walk `packages/client`'s `skills.ts` does when it decides whether one Worker can answer
+ * another's Tasks. It is six lines and it is written twice rather than imported, because a verifier
+ * depending on a consumer library would make the tool's verdicts turn on a package it is supposed
+ * to be able to judge.
+ */
+function told(variants) {
+    const first = variants[0];
+    if (first === undefined)
+        return false;
+    return Object.keys(first.properties ?? {}).some((member) => {
+        const fixed = variants.map((one) => one.properties?.[member]?.const);
+        return fixed.every((one) => one !== undefined) && new Set(fixed).size === variants.length;
+    });
+}
+export async function checkTasks(entry, url, 
+/** TASK-31, read off the Descriptor ROOT. Its names are Task types, so NAME-7 and TASK-4 reach
+ * them — and reach them even for a Worker that declares a Skill and no `tasks` entry. */
+skills, 
+/** The `actions` entry's own map, because TASK-32 is about the Action's name AND its input. */
+accepts, rules, attribution, transcript) {
+    const { results, say, allExcept } = verdicts(rules, CLAIMS);
+    const addresses = [];
+    // NAME-7 and TASK-4 are about the NAMES, wherever they were declared. A Worker that only answers
+    // Tasks has them under `skills` alone, and judging them only through a `tasks` entry would have
+    // reported nothing about the one Worker the root declaration exists for.
+    const crossing = (raised) => {
+        if (raised + skills.length === 0) {
+            say("NAME-7", "notExercised", "the Worker neither raises nor answers a Task type");
+            say("TASK-4", "notExercised", "the Worker declares no Task type");
+        }
+        else {
+            say("NAME-7", "passes");
+            say("TASK-4", "passes");
+        }
+    };
+    if (entry === undefined) {
+        crossing(0);
+        allExcept("notExercised", "the Worker declares no `tasks`", ["NAME-7", "TASK-4"]);
+        return { results, addresses };
+    }
+    const declared = tasksEntry.safeParse(entry);
+    if (!declared.success) {
+        const blamed = new Set();
+        for (const issue of declared.error.issues) {
+            const id = ruleFor(attribution, "tasks-entry", issue.path) ?? "TASK-27";
+            if (blamed.has(id))
+                continue;
+            blamed.add(id);
+            say(id, "fails", `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+        }
+        allExcept("notExercised", "the `tasks` entry did not validate", [...blamed]);
+        return { results, addresses };
+    }
+    const { raises } = declared.data;
+    say("TASK-27", "passes");
+    // NAME-7: a name this protocol expects one party to match against a name that came from
+    // somewhere else is namespaced. A Task type is the first such name the protocol actually serves,
+    // and TASK-4 is that rule applied — so the schema's qualified-name key carries both, and this
+    // says so per rule rather than once, because a report naming one of them is the point.
+    crossing(Object.keys(raises).length);
+    // TASK-32 has two obligations and neither is a shape inside one entry, which is why the schema
+    // reaches neither and both are here.
+    //
+    // The first is the name: answering a Task is performing one of the OWNER's own Actions, so a
+    // Task type naming an Action the Worker does not accept is a Descriptor disagreeing with itself.
+    //
+    // The second is the input of the Action it names. Where a Task can end more than one way the
+    // endings are variants of that input, told apart by a discriminator — and without one, a
+    // consumer holding a schema it can satisfy cannot say WHICH ending it is reporting, so the
+    // mapping this rule dissolved comes back as something two parties have to agree out of band.
+    // Unions of one are not judged: an input that is not a union is a Task that ends one way.
+    const dangling = [];
+    const untold = [];
+    for (const [type, declaration] of Object.entries(raises)) {
+        const declared = accepts[declaration.answeredBy];
+        if (declared === undefined) {
+            dangling.push(`${type} names \`${declaration.answeredBy}\`, which its \`actions\` entry does not accept`);
+            continue;
+        }
+        const input = declared.input;
+        const variants = input?.anyOf ?? input?.oneOf;
+        if (variants !== undefined && variants.length > 1 && !told(variants)) {
+            untold.push(`${type} is answered by \`${declaration.answeredBy}\`, whose input is a union of ${variants.length} with no member fixed to a different constant in each`);
+        }
+    }
+    const faults = [...dangling, ...untold];
+    if (Object.keys(raises).length === 0) {
+        say("TASK-32", "notExercised", "the Worker raises no Task type");
+    }
+    else if (faults.length === 0) {
+        say("TASK-32", "passes");
+    }
+    else {
+        say("TASK-32", "fails", faults.join("; "));
+    }
+    if (url === null) {
+        allExcept("notExercised", "the reading address did not resolve", [
+            "TASK-27",
+            "TASK-32",
+            "TASK-4",
+            "NAME-7",
+        ]);
+        return { results, addresses };
+    }
+    // TASK-5, TASK-28: the Tasks whose conditions hold, in the page envelope, each carrying what a
+    // consumer needs in order to decide whether to try.
+    const answer = await transcript.send(url, "the Tasks whose conditions hold");
+    if (answer.status !== 200) {
+        say("TASK-5", "fails", `the reading address answered ${answer.status}`);
+        say("TASK-28", "notExercised", "no page of Tasks was read");
+    }
+    else {
+        const page = taskPage.safeParse(answer.json);
+        if (page.success) {
+            say("TASK-5", "passes");
+            if (page.data.items.length === 0) {
+                say("TASK-28", "notExercised", "no condition is holding, so no Task was read");
+            }
+            else {
+                say("TASK-28", "passes");
+            }
+        }
+        else {
+            const issue = page.error.issues[0];
+            const id = ruleFor(attribution, "task-page", issue?.path ?? []) ?? "TASK-5";
+            say(id, "fails", `${issue?.path.join(".") || "(root)"}: ${issue?.message}`);
+            say(id === "TASK-5" ? "TASK-28" : "TASK-5", "notExercised", "the page did not validate");
+        }
+    }
+    // TASK-8: a type the entry does not declare. A name no Worker would raise is the only way to ask
+    // without a Worker having to cooperate, and a read refuses without changing anything.
+    const probe = new URL(url);
+    probe.searchParams.set("type", "tech.rowing.no-such.task-type-4c1f");
+    const refused = await transcript.send(probe.toString(), "a Task type the entry does not declare", {
+        permanent: true,
+    });
+    const code = refused.json?.code;
+    if (refused.status === 400 && code === "invalid_parameter")
+        say("TASK-8", "passes");
+    else
+        say("TASK-8", "fails", `answered ${refused.status} with \`${code ?? "no code"}\``);
+    return { results, addresses };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { verify } from "./index.js";
+import { tally } from "./report.js";
+/**
+ * `npx @worker-protocol/conformance <base-url>` — the verifier, from a shell.
+ *
+ * `docs/roadmap.md` says each language's repository ships its own reference Worker and runs this
+ * package against it in CI, and that the report is what ties those repositories together: an SDK is
+ * right because its Worker passes, not because somebody read the prose carefully. That promise was
+ * being made to repositories in Python, C# and Go, and what it offered them was a TypeScript
+ * function — so honouring it began with writing a Node program, which is a toolchain a Python
+ * repository should not have to acquire in order to find out whether it conforms. This file is the
+ * difference between that and one line of YAML.
+ *
+ * **Its exit code is the whole point and is the one thing here that must not be clever.** Zero when
+ * no rule failed, 1 when one did, 2 when no verdict was reached.
+ *
+ * Which of those an unreachable Worker is, `verify` has already decided and this file does not
+ * revisit: it fails DESC-1, naming what could not be fetched. That is a verdict and a correct one —
+ * a Worker is not conformant at an address that does not answer — so it exits 1 like any other
+ * failure. What exits 2 is the case where this tool is the one that is behind (DESC-25), and
+ * whatever `verify` does not turn into a verdict at all.
+ *
+ * `notExercised` never fails the run. `conformance/README.md` spends a paragraph on why it is not
+ * `fails`: the Worker declares no such Capability, or nobody arranged what the check needs to see.
+ * Both are gaps somebody can close, and neither is the Worker breaking an obligation.
+ */
+const USAGE = `worker-protocol-conformance <base-url> [options]
+
+Verify a Worker against the edition of worker-protocol this package encodes.
+
+Options:
+  --credential <token>  Presented as \`Authorization: Bearer <token>\` (REG-3).
+                        Prefer WORKER_PROTOCOL_CREDENTIAL: argv is visible to
+                        every process on the machine, and a CI log often keeps it.
+  --may-perform         Allow POSTs to Actions. Off by default: an Action is an
+                        operation somebody's operators chose to expose, and a tool
+                        pointed at a Worker to inspect it does not perform work on
+                        it uninvited. Rules needing one report notExercised.
+  --json                Write the report to stdout as JSON, and nothing else.
+  -h, --help            This.
+
+Exit: 0 nothing failed, 1 a rule failed, 2 the run could not be made.`;
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        credential: { type: "string" },
+        "may-perform": { type: "boolean", default: false },
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+    },
+});
+if (values.help) {
+    console.log(USAGE);
+    process.exit(0);
+}
+const [baseUrl, ...extra] = positionals;
+if (baseUrl === undefined || extra.length > 0) {
+    console.error(baseUrl === undefined
+        ? "A Worker's base URL is required.\n"
+        : `Expected one base URL, got ${positionals.length}.\n`);
+    console.error(USAGE);
+    process.exit(2);
+}
+/** The order `tally` fixes, which is the order a reader of `conformance/README.md` meets them in. */
+const ORDER = ["passes", "fails", "notExercised", "unverified", "otherSubject"];
+function print(report) {
+    const counts = tally(report.results);
+    console.log(`\n${report.baseUrl}`);
+    console.log(`edition ${report.edition ?? "(none declared)"}, verifier ${report.verifierEdition}\n`);
+    for (const verdict of ORDER) {
+        console.log(`  ${verdict.padEnd(14)}${String(counts[verdict]).padStart(4)}`);
+    }
+    const failures = report.results.filter((result) => result.verdict === "fails");
+    if (failures.length === 0)
+        return;
+    console.log("\nfailed:\n");
+    for (const { rule, detail } of failures) {
+        // The class is printed beside the id and never folded into the verdict. A `recommended` rule
+        // that is not met is still reported — spec/README.md says this specification has standing to
+        // give advice — and it is this column that keeps a reader from reading advice as a contract.
+        console.log(`  ${rule.id.padEnd(10)} ${rule.class.padEnd(12)} ${rule.file}`);
+        if (detail !== undefined)
+            console.log(`    ${detail}`);
+    }
+}
+let report;
+try {
+    report = await verify({
+        baseUrl,
+        credential: values.credential ?? process.env.WORKER_PROTOCOL_CREDENTIAL,
+        mayPerform: values["may-perform"],
+    });
+}
+catch (thrown) {
+    // A backstop, and it should stay empty. `verify` turns an unreachable Worker, an unresolvable
+    // host and a base URL that is not a URL into verdicts of their own, so anything arriving here is
+    // this tool failing rather than the Worker — and reporting that as a conformance failure would be
+    // the one mistake a CI could not see through.
+    console.error(`Could not verify ${baseUrl}: ${thrown.message}`);
+    process.exit(2);
+}
+if (values.json) {
+    console.log(JSON.stringify(report, null, 2));
+}
+else {
+    print(report);
+}
+// DESC-25 binds a verifier rather than a Worker: one that does not hold the declared MAJOR has
+// verified nothing and says so. Exit 2, for the same reason as the catch above — the Worker has
+// not been judged, and the thing that is behind is this tool.
+if (report.older) {
+    if (!values.json) {
+        console.error(`\nThis verifier encodes edition ${report.verifierEdition} and the Worker declares ` +
+            `${report.edition}. Nothing was judged. Install a newer @worker-protocol/conformance.`);
+    }
+    process.exit(2);
+}
+process.exit(report.results.some((result) => result.verdict === "fails") ? 1 : 0);

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import type { Attribution } from "./attribution.ts";
+import { type Code } from "./checks/endpoints.ts";
+import { type Report, type Rule } from "./report.ts";
+export type { Attribution } from "./attribution.ts";
+export type { Report, Result, Rule, Verdict } from "./report.ts";
+export { tally } from "./report.ts";
+export type { Exchange } from "./transcript.ts";
+/**
+ * `@worker-protocol/conformance` — point it at a Worker's base URL, get a report of what it
+ * complies with.
+ *
+ * Its subject is a Worker and nothing else. Twenty-seven rules in `spec/` bind a verifier, a Control
+ * Tower, a consumer, an issuer or the specification itself; this tool reports those as
+ * `otherSubject` rather than passing them, because it never contacted the party they oblige.
+ * `conformance/verifiability.md` is where that classification is decided and `conformance/
+ * README.md` holds the verdict vocabulary.
+ *
+ * Nothing here carries behaviour of its own. Every check reports against a rule id, and a check
+ * that observed something `spec/` does not require would be this package making the standard.
+ */
+export type VerifyOptions = {
+    /** The Worker's enrolled base URL, with or without a path. */
+    baseUrl: string;
+    /** Presented as `Authorization: Bearer <token>` (REG-3). */
+    credential?: string;
+    /**
+     * Whether the verifier may POST to this Worker.
+     *
+     * Every surface but `actions` is read, and a read establishes what it establishes and leaves the
+     * Worker as it found it. An Action is an operation somebody's operators chose to expose, so the
+     * default is `false`: a tool pointed at a Worker to inspect it does not perform work on it
+     * uninvited, and the rules that need a POST report `notExercised` with that as the reason.
+     */
+    mayPerform?: boolean;
+    /**
+     * What the Worker's operators arranged so that a rule with no ordinary witness can be observed.
+     *
+     * `conformance/verifiability.md` classes a rule `H` when nothing a tool can do to an unarranged
+     * Worker will ever see a violation — a performance that succeeds, an input refused on content, a
+     * second credential. The arrangement cannot come from the protocol, because putting test
+     * scaffolding into a Descriptor would make every Worker in the network carry it. So it arrives
+     * the way the base URL and the credential do: out of band, from the person who set it up.
+     *
+     * Anything not arranged reports `notExercised` naming what was missing, which is a gap somebody
+     * can close rather than a verdict.
+     */
+    arrangement?: Arrangement;
+    /** For tests and for a caller that needs its own agent. Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+};
+export type Arrangement = {
+    /** An Action that is safe to perform, and an input its declared schema accepts. */
+    safeAction?: {
+        name: string;
+        input: unknown;
+    };
+    /** An input that is schema-valid and that the Worker refuses on its own rules (ACT-9). */
+    refusedInput?: {
+        name: string;
+        input: unknown;
+    };
+    /** An Action that declares it does not complete within the call, and an input for it (ACT-11). */
+    asyncAction?: {
+        name: string;
+        input: unknown;
+    };
+    /** A second credential issued to the same holder (REG-8, REG-28, ALRT-6). */
+    secondCredential?: string;
+    /**
+     * A credential issued under a Contract rather than recorded at enrollment (TASK-6).
+     *
+     * TASK-6 compares what it sees against what the recorded credential sees. Where none is given it
+     * falls back to the second credential.
+     */
+    consumerCredential?: string;
+    /** A credential the Worker authenticates and that carries no right here (REG-32). */
+    unprivilegedCredential?: string;
+    /** That this Worker was started moments ago, so HLTH-4's window is still open. */
+    justStarted?: boolean;
+    /** That the operators will let the verifier write this Worker's settings back (ACT-14). */
+    replaceableSettings?: boolean;
+    /** An event this Worker published, since a verifier holds no broker and sees none (EVT-1). */
+    publishedEvent?: unknown;
+    /** Resolved by `verify` and not by a caller: the addresses the arranged checks need. */
+    healthUrl?: string;
+    actionsUrl?: string;
+};
+type Universe = {
+    rules: Rule[];
+    codes: Code[];
+    attribution: Attribution;
+};
+/** Generated from `spec/` by `src/generate-rules.ts` and committed beside the source. */
+export declare function universe(): Promise<Universe>;
+export declare function verify(options: VerifyOptions): Promise<Report>;