@worker-protocol/conformance 0.1.0

package/dist/index.js

@@ -0,0 +1,128 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { EDITION } from "@worker-protocol/schemas";
+import { checkActions } from "./checks/actions.js";
+import { checkActivity } from "./checks/activity.js";
+import { checkAlerts } from "./checks/alerts.js";
+import { checkArranged } from "./checks/arranged.js";
+import { readDescriptor } from "./checks/descriptor.js";
+import { judgeTranscript } from "./checks/endpoints.js";
+import { checkEvents } from "./checks/events.js";
+import { checkHealth } from "./checks/health.js";
+import { checkMetrics } from "./checks/metrics.js";
+import { checkNudges } from "./checks/nudges.js";
+import { callSurfaces } from "./checks/surfaces.js";
+import { checkTasks } from "./checks/tasks.js";
+import { unclaimed } from "./report.js";
+import { transcript } from "./transcript.js";
+export { tally } from "./report.js";
+/** Generated from `spec/` by `src/generate-rules.ts` and committed beside the source. */
+export async function universe() {
+    const path = join(import.meta.dirname, "..", "rules.json");
+    return JSON.parse(await readFile(path, "utf8"));
+}
+export async function verify(options) {
+    const { rules: all, codes, attribution } = await universe();
+    const byId = new Map(all.map((rule) => [rule.id, rule]));
+    const tape = transcript(options.fetch ?? globalThis.fetch, options.credential);
+    const descriptor = await readDescriptor(options.baseUrl, byId, attribution, tape);
+    // DESC-25: a verifier that does not hold the declared edition's MAJOR verifies NOTHING and
+    // reports that it is older than the Worker — rather than failing a Worker for a surface added
+    // after this tool was built. The ordering DESC-23 fixes is what lets it say `older` rather than
+    // merely `unrecognised`, and that is the difference between telling an operator to upgrade the
+    // verifier and leaving the Worker under suspicion for what is the reader's problem.
+    const declaredMajor = descriptor.document?.edition.split(".")[0];
+    if (declaredMajor !== undefined && declaredMajor !== EDITION.split(".")[0]) {
+        return {
+            baseUrl: options.baseUrl,
+            edition: descriptor.document?.edition ?? null,
+            verifierEdition: EDITION,
+            older: true,
+            results: all.map((rule) => ({
+                rule,
+                verdict: "notExercised",
+                detail: `this verifier holds edition ${EDITION} and the Worker declares ${descriptor.document?.edition}`,
+            })),
+        };
+    }
+    const results = [...descriptor.results];
+    // Addresses a Capability declares INSIDE its own entry rather than beside it — `configure`'s
+    // reading address is the first. ENDP-1 judges what the verifier called against what the
+    // Descriptor declared, so an address it could not see would read as the Worker's fault.
+    const nested = [];
+    /** The address a Capability declared, resolved by `readDescriptor` per DESC-12. */
+    const surface = (name) => descriptor.surfaces.find((one) => one.capability === name)?.url ?? null;
+    if (descriptor.document !== null && descriptor.url !== null) {
+        results.push(...(await callSurfaces(descriptor.surfaces, descriptor.url, 
+        // ENDP-6 is probed on every write this protocol has, and being wrong on a write is what
+        // the rule is for: a Worker that refuses an unanswerable version on a read and performs
+        // one here has done the thing it exists to prevent.
+        [surface("actions"), surface("nudges")].filter((url) => url !== null), byId, tape, options.credential, options.mayPerform === true)));
+        // TASK-32 is an agreement between two entries rather than a shape inside one, so the tasks
+        // check is handed the `actions` entry itself: it judges the name an entry points at AND the
+        // input that Action declares, and neither is reachable from inside `tasks`.
+        const accepts = descriptor.document.capabilities.actions?.accepts ?? {};
+        // Tasks before Actions, and the order is not a preference: an Action that answers a Task
+        // resolves its condition (TASK-15), so a Worker whose Tasks are read after its Actions are
+        // performed may have none left to read. Every check here is a GET and changes nothing.
+        const listed = await checkTasks(descriptor.document.capabilities.tasks, surface("tasks"), Object.keys(descriptor.document.skills ?? {}), accepts, byId, attribution, tape);
+        results.push(...listed.results);
+        nested.push(...listed.addresses);
+        const performed = await checkActions(descriptor.document.capabilities.actions, surface("actions"), descriptor.url, byId, attribution, tape, options.mayPerform === true, options.arrangement ?? {});
+        results.push(...performed.results);
+        nested.push(...performed.addresses);
+        results.push(...(await checkMetrics(descriptor.document.capabilities.metrics, surface("metrics"), byId, attribution, tape)));
+        // `events` has no address by design (DESC-22), so this check sends nothing and takes no
+        // transcript. It is the only Capability a verifier judges entirely from the Descriptor.
+        results.push(...checkEvents(descriptor.document.capabilities.events, byId, attribution));
+        results.push(...(await checkAlerts(descriptor.document.capabilities.alerts, surface("alerts"), Object.keys(accepts), byId, attribution, tape)));
+        results.push(...(await checkActivity(descriptor.document.capabilities.activity, surface("activity"), byId, attribution, tape)));
+        results.push(...(await checkHealth(descriptor.document.capabilities.health, surface("health"), byId, attribution, tape)));
+        // Last of the Capability checks, because it is the only one that sends the Worker somewhere: a
+        // nudge it accepts has it read a Task list. Everything above it is a read.
+        results.push(...(await checkNudges(descriptor.document.capabilities.nudges, surface("nudges"), Object.keys(descriptor.document.skills ?? {}), byId, attribution, tape, options.mayPerform === true)));
+    }
+    if (descriptor.document !== null) {
+        const configure = descriptor.document.capabilities.actions?.accepts?.configure?.readAddress;
+        results.push(...(await checkArranged({
+            descriptorUrl: descriptor.url,
+            alertsUrl: surface("alerts"),
+            activityUrl: surface("activity"),
+            tasksUrl: surface("tasks"),
+            settingsUrl: configure === undefined || descriptor.url === null
+                ? null
+                : new URL(configure, descriptor.url).toString(),
+            workerId: descriptor.document.id,
+            eventTypes: Object.keys(descriptor.document.capabilities.events
+                ?.publishes ?? {}),
+        }, {
+            ...(options.arrangement ?? {}),
+            healthUrl: surface("health") ?? undefined,
+            actionsUrl: surface("actions") ?? undefined,
+        }, options.mayPerform === true, byId, tape)));
+    }
+    // Last, and over everything the run provoked. ENDP-26 is a statement about a set of responses
+    // rather than about one, so it cannot be asked until there are no more to come.
+    const declared = new Set([
+        ...(descriptor.url === null ? [] : [descriptor.url]),
+        ...descriptor.surfaces.map((s) => s.url),
+        ...nested,
+    ]);
+    results.push(...judgeTranscript(tape.exchanges, codes, declared, byId));
+    // Every rule gets a verdict, never only the ones a check claimed. A report covering 23 rules of
+    // 102, all green, tells an operator the Worker was checked against the protocol — and the reader
+    // concludes more than was established, which is the fault this whole directory is written
+    // against. `unclaimed` is what says which kind of silence each remaining rule is.
+    const claimed = new Set(results.map((result) => result.rule.id));
+    const complete = [
+        ...results,
+        ...all.filter((rule) => !claimed.has(rule.id)).map(unclaimed),
+    ];
+    complete.sort((a, b) => a.rule.id.localeCompare(b.rule.id, "en", { numeric: true }));
+    return {
+        baseUrl: options.baseUrl,
+        edition: descriptor.document?.edition ?? null,
+        verifierEdition: EDITION,
+        results: complete,
+    };
+}

package/dist/report.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The verdict vocabulary, which `conformance/README.md` states and this file encodes.
+ *
+ * Nothing here decides anything. Every verdict corresponds to a sentence in that document, and the
+ * one property worth protecting in code is the one the prose spends a paragraph on: `notExercised`
+ * and `unverified` are separate, because they read alike on a page and are opposite facts.
+ */
+/** A rule as `packages/conformance/rules.json` records it, generated from `spec/`. */
+export type Rule = {
+    id: string;
+    /** The `spec/` file that defines it, so a report can group by subject. */
+    file: string;
+    /** `spec/README.md`: a contract, or advice this specification has standing to give. */
+    class: "required" | "recommended";
+    /** `conformance/verifiability.md`: what a check can observe. */
+    reach: "W" | "H" | "P" | "N" | "—";
+};
+export type Verdict = 
+/** The check ran and the Worker satisfied it. */
+"passes"
+/**
+ * The check ran and the Worker did not satisfy it. A `recommended` rule is still reported with
+ * this verdict; it is the rule's class, printed beside it, that keeps a report from reading as a
+ * verdict where the specification has no standing to give one.
+ */
+ | "fails"
+/**
+ * A check exists and this run did not reach it: the Worker declares no such Capability, or the
+ * check needs a Worker arranged to be observed and this one is not.
+ */
+ | "notExercised"
+/** The rule's subject is the Worker and no party outside it can observe a violation. */
+ | "unverified"
+/** The rule binds a verifier, a Tower, a consumer, an issuer or this specification. */
+ | "otherSubject";
+export type Result = {
+    rule: Rule;
+    verdict: Verdict;
+    /** Why, in one line. Required for every verdict but `passes`, where the rule says it already. */
+    detail?: string;
+};
+export type Report = {
+    /** The base URL the Worker was enrolled as, exactly as the caller gave it. */
+    baseUrl: string;
+    /** The edition the Descriptor declared, or null where none could be read. */
+    edition: string | null;
+    /**
+     * The edition this verifier holds.
+     *
+     * DESC-25 binds a verifier rather than a Worker, and publishing an edition is what made it ours
+     * to obey: a tool that does not hold the declared MAJOR verifies nothing and says it is the one
+     * that is behind. A report that left this out would leave a reader unable to tell a Worker that
+     * failed from a verifier that could not read it.
+     */
+    verifierEdition: string;
+    /** Set where DESC-25 stopped the run: this verifier is older than the Worker. */
+    older?: true;
+    results: Result[];
+};
+/**
+ * The verdict a rule gets when no check claimed it.
+ *
+ * This is the whole reason a report covers every rule rather than only the ones it exercised. A
+ * rule whose reach says a Worker could be observed and that nothing observed is `notExercised` —
+ * a gap somebody can close. One that binds another party, or that nothing can ever see, is not a
+ * gap and says so under its own name.
+ */
+export declare const unclaimed: (rule: Rule) => Result;
+/** Counts by verdict, for the one line a report ends with. */
+export declare const tally: (results: Result[]) => Record<Verdict, number>;
+/**
+ * Where a check module accumulates its verdicts.
+ *
+ * Every one of them was opening with the same seven lines — an array, a `say` that looks the rule
+ * up and drops what this verifier does not hold, and an `allExcept` that answers for the rest of
+ * its claims. None of it decides anything: which id, which verdict and which reason are the
+ * module's, and are still written there, beside the rule each one argues for.
+ *
+ * `say` drops an id the universe does not carry rather than throwing, and that is deliberate: a
+ * verifier holding an older `rules.json` than the module was written against reports what it can
+ * and stays silent about what it cannot, which is DESC-25's posture one level down.
+ */
+export declare function verdicts(rules: Map<string, Rule>, claims: readonly string[]): {
+    results: Result[];
+    say: (id: string, verdict: Verdict, detail?: string) => void;
+    allExcept: (verdict: Verdict, why: string, except?: string[]) => void;
+};

package/dist/report.js

@@ -0,0 +1,71 @@
+/**
+ * The verdict vocabulary, which `conformance/README.md` states and this file encodes.
+ *
+ * Nothing here decides anything. Every verdict corresponds to a sentence in that document, and the
+ * one property worth protecting in code is the one the prose spends a paragraph on: `notExercised`
+ * and `unverified` are separate, because they read alike on a page and are opposite facts.
+ */
+/**
+ * The verdict a rule gets when no check claimed it.
+ *
+ * This is the whole reason a report covers every rule rather than only the ones it exercised. A
+ * rule whose reach says a Worker could be observed and that nothing observed is `notExercised` —
+ * a gap somebody can close. One that binds another party, or that nothing can ever see, is not a
+ * gap and says so under its own name.
+ */
+export const unclaimed = (rule) => {
+    switch (rule.reach) {
+        case "P":
+            return { rule, verdict: "otherSubject", detail: "the subject of this rule is not a Worker" };
+        case "N":
+            return { rule, verdict: "unverified", detail: "no party outside the Worker can observe it" };
+        case "—":
+            return {
+                rule,
+                verdict: "notExercised",
+                detail: "the surface it is about belongs to a spec/ file that is still open",
+            };
+        default:
+            return { rule, verdict: "notExercised", detail: "no check in this verifier claims it yet" };
+    }
+};
+/** Counts by verdict, for the one line a report ends with. */
+export const tally = (results) => {
+    const counts = {
+        passes: 0,
+        fails: 0,
+        notExercised: 0,
+        unverified: 0,
+        otherSubject: 0,
+    };
+    for (const result of results)
+        counts[result.verdict] += 1;
+    return counts;
+};
+/**
+ * Where a check module accumulates its verdicts.
+ *
+ * Every one of them was opening with the same seven lines — an array, a `say` that looks the rule
+ * up and drops what this verifier does not hold, and an `allExcept` that answers for the rest of
+ * its claims. None of it decides anything: which id, which verdict and which reason are the
+ * module's, and are still written there, beside the rule each one argues for.
+ *
+ * `say` drops an id the universe does not carry rather than throwing, and that is deliberate: a
+ * verifier holding an older `rules.json` than the module was written against reports what it can
+ * and stays silent about what it cannot, which is DESC-25's posture one level down.
+ */
+export function verdicts(rules, claims) {
+    const results = [];
+    const say = (id, verdict, detail) => {
+        const rule = rules.get(id);
+        if (rule)
+            results.push({ rule, verdict, detail });
+    };
+    /** The claims this module has not already spoken for, all at one verdict and one reason. */
+    const allExcept = (verdict, why, except = []) => {
+        for (const id of claims)
+            if (!except.includes(id))
+                say(id, verdict, why);
+    };
+    return { results, say, allExcept };
+}

package/dist/transcript.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Every exchange the verifier had with the Worker, kept so that the cross-cutting rules can be
+ * judged over all of them.
+ *
+ * Several rules in [endpoints](../../../spec/endpoints.md) are about *every* response rather than
+ * about one surface — ENDP-5 puts two headers on all of them, ENDP-26 forbids one code arriving
+ * under two statuses, which is a statement no single response can break. A verifier that checked
+ * those inside each surface's own check would be asking a question it could not answer, so the
+ * exchanges are collected first and the cross-cutting checks run last, over the whole record.
+ */
+export type Exchange = {
+    url: string;
+    method: string;
+    status: number;
+    headers: Headers;
+    /** The raw body, so that a check can report what failed to parse rather than that it did. */
+    body: string;
+    /** The parsed body, or null where it is not JSON. */
+    json: unknown;
+    /** What the verifier was doing, for a report that has to say why a response was provoked. */
+    intent: string;
+    /**
+     * Whether the verifier knows this request is wrong in a way that will not change.
+     *
+     * ENDP-11 forbids a `5xx` for a condition that will not change, and its witness is ordinarily
+     * out of reach: nothing outside a Worker can tell a transient fault from a permanent one. But a
+     * verifier holds one fact nobody else does — it knows which of its own requests were deliberately
+     * and permanently wrong, because it made them that way. An Action no entry declares will never
+     * exist; a filter no surface knows will never be recognised; a credential never issued will
+     * never be accepted. A `5xx` to any of those is the rule broken, with no arrangement needed.
+     */
+    permanent: boolean;
+};
+export type Transcript = {
+    exchanges: Exchange[];
+    /** Performs a request, records it, and returns it. A network failure throws, as fetch does. */
+    send: (url: string, intent: string, init?: RequestInit & {
+        permanent?: boolean;
+    }) => Promise<Exchange>;
+};
+export type Sender = typeof globalThis.fetch;
+export declare function transcript(send: Sender, credential?: string): Transcript;
+/** `application/json; charset=utf-8` and `application/json` are the same media type (ENDP-4). */
+export declare const isJson: (headers: Headers) => boolean;

package/dist/transcript.js

@@ -0,0 +1,49 @@
+/**
+ * Every exchange the verifier had with the Worker, kept so that the cross-cutting rules can be
+ * judged over all of them.
+ *
+ * Several rules in [endpoints](../../../spec/endpoints.md) are about *every* response rather than
+ * about one surface — ENDP-5 puts two headers on all of them, ENDP-26 forbids one code arriving
+ * under two statuses, which is a statement no single response can break. A verifier that checked
+ * those inside each surface's own check would be asking a question it could not answer, so the
+ * exchanges are collected first and the cross-cutting checks run last, over the whole record.
+ */
+export function transcript(send, credential) {
+    const exchanges = [];
+    return {
+        exchanges,
+        async send(url, intent, init = {}) {
+            // REG-3: a credential is presented as `Authorization: Bearer <token>`, and this protocol
+            // fixes nothing else about it. A caller that presented it anywhere else would produce a call
+            // that cannot complete however good either party's intentions are.
+            const headers = new Headers(init.headers);
+            if (credential !== undefined && !headers.has("authorization")) {
+                headers.set("authorization", `Bearer ${credential}`);
+            }
+            const { permanent = false, ...request } = init;
+            const response = await send(url, { ...request, headers, redirect: "manual" });
+            const body = await response.text();
+            let json = null;
+            try {
+                json = JSON.parse(body);
+            }
+            catch {
+                json = null;
+            }
+            const exchange = {
+                url,
+                method: init.method ?? "GET",
+                status: response.status,
+                headers: response.headers,
+                body,
+                json,
+                intent,
+                permanent,
+            };
+            exchanges.push(exchange);
+            return exchange;
+        },
+    };
+}
+/** `application/json; charset=utf-8` and `application/json` are the same media type (ENDP-4). */
+export const isJson = (headers) => (headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase() === "application/json";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@worker-protocol/conformance",
+  "version": "0.1.0",
+  "workerProtocolEdition": "0.1",
+  "description": "Point it at a Worker's base URL, get a report of what it complies with",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rowing-tech/worker-protocol.git",
+    "directory": "packages/conformance"
+  },
+  "homepage": "https://github.com/rowing-tech/worker-protocol#readme",
+  "bugs": "https://github.com/rowing-tech/worker-protocol/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "worker-protocol-conformance": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "rules.json",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@worker-protocol/schemas": "0.1.0",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "26.5.1",
+    "@worker-protocol/client": "0.1.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0",
+    "wrangler": "4.131.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
+}