@worker-protocol/client 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Rowing Tech, S.A.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+worker-protocol
+Copyright 2026 Rowing Tech, S.A.
+
+This product includes software developed at Rowing Tech, S.A. (https://rowing.tech).
+
+Licensed under the Apache License, Version 2.0. See LICENSE for the full text.
+
+"worker-protocol" and any conformance claim made in its name are not licensed under Apache-2.0;
+see section 6 of the License.

package/dist/call.d.ts

@@ -0,0 +1,110 @@
+import type * as z from "zod";
+/**
+ * One call to a Worker, and every rule in `spec/` that binds the party making it.
+ *
+ * Nine rules in the specification oblige a consumer rather than a Worker, and until this package
+ * existed none of them had a subject: `conformance/verifiability.md` classes them `P` and a report
+ * says *other subject*, because a tool pointed at a base URL never contacted whoever they bind.
+ * They are all here, each cited where it is obeyed, and `__tests__/consumer-rules.test.ts` is what
+ * holds this to them.
+ *
+ * DESC-13, DESC-30, ENDP-13, ENDP-14, ENDP-21, ENDP-27, ENDP-28, ENDP-30, ENDP-31 — that is the
+ * whole list, and a line below cites each. It was eleven until the Claim lifecycle was withdrawn:
+ * TASK-18 bound a holder not to do arithmetic on a lease it no longer has, and TASK-20 had it name
+ * that lease on the Action.
+ */
+/** A Worker refused, and the refusal is the Worker's own statement about itself (ENDP-25). */
+export declare class Refused extends Error {
+    readonly code: string;
+    readonly status: number;
+    /** ENDP-25. `reject` will be wrong again; `retry` may not be. */
+    readonly kind: "reject" | "retry";
+    readonly url: string;
+    constructor(code: string, status: number, 
+    /** ENDP-25. `reject` will be wrong again; `retry` may not be. */
+    kind: "reject" | "retry", url: string, message: string);
+}
+/**
+ * A Worker answered something this protocol does not admit.
+ *
+ * It names the rule, because a consumer told *the response was invalid* cannot act on it and two
+ * very different faults read identically — which is the whole reason the ids exist. What is
+ * checked is only what `schemas/` fixes; a Task's payload, an Action's result and an event's data
+ * are the Worker's own and this never looks inside them.
+ */
+export declare class Malformed extends Error {
+    readonly rule: string;
+    readonly url: string;
+    readonly detail: string;
+    constructor(rule: string, url: string, detail: string);
+}
+/** A declared address that serves nothing, which DESC-30 makes a contract error and not a retry. */
+export declare class Unserved extends Error {
+    readonly url: string;
+    constructor(url: string);
+}
+export type Fetch = typeof globalThis.fetch;
+export type CallerOptions = {
+    /** REG-3. Presented as `Authorization: Bearer <token>`, and nowhere else. */
+    credential?: string;
+    /** ENDP-30 (recommended). How many times a `retry` is repeated before the caller gives up. */
+    retries?: number;
+    /** ENDP-30. The first wait, doubled each time. */
+    backoffMs?: number;
+    fetch?: Fetch;
+    /** For a test that needs the clock still. Defaults to a real wait. */
+    wait?: (ms: number) => Promise<void>;
+};
+export type Call = {
+    url: string;
+    method?: "GET" | "POST";
+    body?: string;
+    /** ENDP-15. Where the Action declares it reads a key from the header. */
+    idempotencyKey?: string;
+    /**
+     * Whether a `404` here means the ADDRESS serves nothing (DESC-30) or that a resource is gone.
+     *
+     * The division is the one DESC-30 was narrowed to: a read of a Capability's own address asks
+     * whether the Worker answers there at all, and a call naming a metric, an Action or a Task asks
+     * about a thing — the first is a Descriptor that lied, the second is an ordinary refusal.
+     */
+    addressLevel?: boolean;
+};
+export declare function caller(descriptorUrl: string, options?: CallerOptions): {
+    call: (spec: Call) => Promise<{
+        status: number;
+        body: string;
+        json: unknown;
+    }>;
+    validated: <T>(spec: Call, schema: z.ZodType<T>, rule: string) => Promise<T>;
+    /** DESC-12. Every address is resolved against the URL the Descriptor was read FROM. */
+    resolve: (address: string) => string;
+    edition: () => string | undefined;
+};
+export type Caller = ReturnType<typeof caller>;
+/**
+ * Every page of a collection, read the way ENDP-20 and ENDP-21 say.
+ *
+ * ENDP-31 is the rule this exists to obey and it is the one a caller breaks without noticing: it
+ * reads how many items it RECEIVED, never how many it asked for. A caller that assumed a full page
+ * meant more to come, or that a short page meant the end, silently loses the rest of a collection
+ * — so the only thing that ends this loop is the cursor being absent.
+ *
+ * ENDP-21: the cursor is opaque, is produced only by the Worker, and is never constructed here. It
+ * goes back exactly as it arrived.
+ */
+/**
+ * Every page of a collection, drained into one array.
+ *
+ * `pages` yields page by page so that a consumer may stop early; every caller in this package
+ * wants the whole thing, which is this. ENDP-20's envelope, ENDP-21's cursor and the bound on a
+ * Worker whose cursor never advances are all `pages`' — nothing is added here but the array.
+ */
+export declare function collect<T>(caller: Caller, url: string, schema: z.ZodType<{
+    items: T[];
+    nextCursor?: string;
+}>, rule: string, parameters?: Record<string, string>): Promise<T[]>;
+export declare function pages<T>(caller: Caller, url: string, schema: z.ZodType<{
+    items: T[];
+    nextCursor?: string;
+}>, rule: string, parameters?: Record<string, string>): AsyncGenerator<T[]>;

package/dist/call.js

@@ -0,0 +1,216 @@
+import { error as errorSchema } from "@worker-protocol/schemas";
+/**
+ * One call to a Worker, and every rule in `spec/` that binds the party making it.
+ *
+ * Nine rules in the specification oblige a consumer rather than a Worker, and until this package
+ * existed none of them had a subject: `conformance/verifiability.md` classes them `P` and a report
+ * says *other subject*, because a tool pointed at a base URL never contacted whoever they bind.
+ * They are all here, each cited where it is obeyed, and `__tests__/consumer-rules.test.ts` is what
+ * holds this to them.
+ *
+ * DESC-13, DESC-30, ENDP-13, ENDP-14, ENDP-21, ENDP-27, ENDP-28, ENDP-30, ENDP-31 — that is the
+ * whole list, and a line below cites each. It was eleven until the Claim lifecycle was withdrawn:
+ * TASK-18 bound a holder not to do arithmetic on a lease it no longer has, and TASK-20 had it name
+ * that lease on the Action.
+ */
+/** A Worker refused, and the refusal is the Worker's own statement about itself (ENDP-25). */
+export class Refused extends Error {
+    code;
+    status;
+    kind;
+    url;
+    constructor(code, status, 
+    /** ENDP-25. `reject` will be wrong again; `retry` may not be. */
+    kind, url, message) {
+        super(`${code} (${status}) at ${url}: ${message}`);
+        this.code = code;
+        this.status = status;
+        this.kind = kind;
+        this.url = url;
+        this.name = "Refused";
+    }
+}
+/**
+ * A Worker answered something this protocol does not admit.
+ *
+ * It names the rule, because a consumer told *the response was invalid* cannot act on it and two
+ * very different faults read identically — which is the whole reason the ids exist. What is
+ * checked is only what `schemas/` fixes; a Task's payload, an Action's result and an event's data
+ * are the Worker's own and this never looks inside them.
+ */
+export class Malformed extends Error {
+    rule;
+    url;
+    detail;
+    constructor(rule, url, detail) {
+        super(`${rule}: ${detail} — from ${url}`);
+        this.rule = rule;
+        this.url = url;
+        this.detail = detail;
+        this.name = "Malformed";
+    }
+}
+/** A declared address that serves nothing, which DESC-30 makes a contract error and not a retry. */
+export class Unserved extends Error {
+    url;
+    constructor(url) {
+        super(`DESC-30: ${url} is declared in the Descriptor and serves nothing. This is a contract error: the Descriptor says the Worker answers here and it does not.`);
+        this.url = url;
+        this.name = "Unserved";
+    }
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+export function caller(descriptorUrl, options = {}) {
+    const send = options.fetch ?? globalThis.fetch;
+    const wait = options.wait ?? sleep;
+    const retries = options.retries ?? 3;
+    const backoff = options.backoffMs ?? 200;
+    // DESC-13: a credential granted for this Worker is not presented to an address on an origin the
+    // operator did not record as the Worker's own. An address may point away — a Worker whose Tasks
+    // are held by one deployment and whose health is answered by another is a placement decision —
+    // and the Descriptor is a document the Worker controls, so an address in it is an instruction to
+    // send a request somewhere. Without this, a Worker could name any host and be handed the token.
+    const ownOrigin = new URL(descriptorUrl).origin;
+    /** DESC-30: addresses this consumer has found to serve nothing. It does not call them again. */
+    const unserved = new Set();
+    /** ENDP-5. What the Worker last said produced an answer, for a caller that wants to notice. */
+    let lastEdition;
+    const once = async (call) => {
+        const headers = new Headers();
+        if (options.credential !== undefined) {
+            if (new URL(call.url).origin === ownOrigin) {
+                headers.set("authorization", `Bearer ${options.credential}`);
+            }
+            // Off-origin: the request still goes, and without the credential. DESC-13 forbids presenting
+            // it, not calling the address — which the Worker declared and may well serve openly.
+        }
+        if (call.body !== undefined)
+            headers.set("content-type", "application/json");
+        if (call.idempotencyKey !== undefined) {
+            headers.set("idempotency-key", call.idempotencyKey);
+        }
+        return send(call.url, {
+            method: call.method ?? "GET",
+            headers,
+            ...(call.body === undefined ? {} : { body: call.body }),
+            redirect: "manual",
+        });
+    };
+    /**
+     * One call, classified, retried where the Worker said it may be, and never where it said not.
+     *
+     * ENDP-28 is the rule that costs the most to get wrong and it binds here: a caller that retries
+     * a `reject` hammers a Worker with a request that will never succeed and buries the failure. So
+     * a `reject` throws on the first answer, and only a `retry` comes round again.
+     */
+    const call = async (spec) => {
+        if (unserved.has(spec.url))
+            throw new Unserved(spec.url);
+        let waited = backoff;
+        for (let attempt = 0;; attempt++) {
+            const response = await once(spec);
+            const text = await response.text();
+            let json = null;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = null;
+            }
+            // ENDP-5: a caller that sees an edition it did not expect re-reads the Descriptor rather
+            // than parsing the body. What it does about it is the caller's; noticing is this line.
+            lastEdition = response.headers.get("worker-protocol-edition") ?? lastEdition;
+            if (response.status < 400)
+                return { status: response.status, body: text, json };
+            // DESC-30: an address the Descriptor declares and that serves nothing is a contract error,
+            // and a consumer stops. It is recorded so that nothing here calls it again, which is what
+            // *does not retry* means when the same consumer keeps running.
+            if (response.status === 404 && spec.addressLevel === true) {
+                unserved.add(spec.url);
+                throw new Unserved(spec.url);
+            }
+            // ENDP-14, ENDP-27: where the class and the status disagree, the class in the envelope wins
+            // when an envelope is present and parses, and the status wins when it is not. ENDP-13: an
+            // answer that can be classified by neither is `reject` — stopping loudly on something that
+            // would have succeeded costs an alert, and retrying on something that never will costs the
+            // work, silently.
+            const envelope = errorSchema.safeParse(json);
+            const kind = envelope.success
+                ? envelope.data.class
+                : RETRY_STATUS.has(response.status)
+                    ? "retry"
+                    : "reject";
+            const code = envelope.success ? envelope.data.code : `http_${response.status}`;
+            const message = envelope.success ? envelope.data.message : text.slice(0, 200);
+            // ENDP-28: a caller does not retry a reject. The request is wrong and will be wrong again.
+            if (kind === "reject" || attempt >= retries) {
+                throw new Refused(code, response.status, kind, spec.url, message);
+            }
+            // ENDP-30 (recommended): a caller backs off and repeats a `retry` unchanged. Unchanged is
+            // the load-bearing word — the same request, under the same key if it had one.
+            await wait(waited);
+            waited *= 2;
+        }
+    };
+    /** A call whose answer is a document this protocol fixes the shape of. */
+    const validated = async (spec, schema, rule) => {
+        const answer = await call(spec);
+        const parsed = schema.safeParse(answer.json);
+        if (!parsed.success) {
+            const issue = parsed.error.issues[0];
+            const where = issue?.path.join(".") || "(root)";
+            throw new Malformed(rule, spec.url, `${where}: ${issue?.message ?? "did not validate"}`);
+        }
+        return parsed.data;
+    };
+    return {
+        call,
+        validated,
+        /** DESC-12. Every address is resolved against the URL the Descriptor was read FROM. */
+        resolve: (address) => new URL(address, descriptorUrl).toString(),
+        edition: () => lastEdition,
+    };
+}
+/** ENDP-29's `retry` rows, for an answer that carries no envelope to read a class off. */
+const RETRY_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+/**
+ * Every page of a collection, read the way ENDP-20 and ENDP-21 say.
+ *
+ * ENDP-31 is the rule this exists to obey and it is the one a caller breaks without noticing: it
+ * reads how many items it RECEIVED, never how many it asked for. A caller that assumed a full page
+ * meant more to come, or that a short page meant the end, silently loses the rest of a collection
+ * — so the only thing that ends this loop is the cursor being absent.
+ *
+ * ENDP-21: the cursor is opaque, is produced only by the Worker, and is never constructed here. It
+ * goes back exactly as it arrived.
+ */
+/**
+ * Every page of a collection, drained into one array.
+ *
+ * `pages` yields page by page so that a consumer may stop early; every caller in this package
+ * wants the whole thing, which is this. ENDP-20's envelope, ENDP-21's cursor and the bound on a
+ * Worker whose cursor never advances are all `pages`' — nothing is added here but the array.
+ */
+export async function collect(caller, url, schema, rule, parameters = {}) {
+    const held = [];
+    for await (const page of pages(caller, url, schema, rule, parameters))
+        held.push(...page);
+    return held;
+}
+export async function* pages(caller, url, schema, rule, parameters = {}) {
+    let cursor;
+    // A bound, because a Worker whose cursor never advances would otherwise spin a consumer forever.
+    for (let page = 0; page < 10_000; page++) {
+        const target = new URL(url);
+        for (const [key, value] of Object.entries(parameters))
+            target.searchParams.set(key, value);
+        if (cursor !== undefined)
+            target.searchParams.set("cursor", cursor);
+        const answered = await caller.validated({ url: target.toString(), addressLevel: Object.keys(parameters).length === 0 }, schema, rule);
+        yield answered.items;
+        // ENDP-20: absent at the end of the collection — absent, not null, and not an empty page.
+        if (answered.nextCursor === undefined)
+            return;
+        cursor = answered.nextCursor;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { type activity as activitySchema, type alert, descriptor as descriptorSchema, health as healthSchema, type metricBucket, type task as taskSchema } from "@worker-protocol/schemas";
+import type * as z from "zod";
+import { type CallerOptions } from "./call.ts";
+/**
+ * `@worker-protocol/client` — read a Worker, and take work from it.
+ *
+ * `consume(url)` reads a Descriptor once, resolves every address the Worker declared (DESC-12) and
+ * answers an object with one member per Capability that Worker implements — and nothing for the
+ * ones it does not, because DESC-2 admits any combination including none.
+ *
+ * **It is the other half of `mount()` and it carries the same kind of thing.** A consumer that
+ * wrote this itself would write the address resolution, the paging and its cursor, the retry that
+ * must not happen on a `reject`, and the classification of an answer it cannot read. All of that
+ * is fixed by rules — nine of which oblige a consumer rather than a Worker — and `call.ts` cites
+ * every one.
+ *
+ * It depends on `@worker-protocol/schemas` and on `fetch`, and on nothing else. A Tower, a teams
+ * app or a Worker that consumes another Worker installs no web framework to do it.
+ *
+ * **Strict about what this protocol fixes, and blind to what it does not.** Every document
+ * `schemas/` describes is validated, and a Worker that answers something else raises `Malformed`
+ * naming the rule. A Task's payload, an Action's input and result, an event's data are the
+ * Worker's own — this protocol has no data model — and nothing here looks inside them.
+ */
+export { type Call, type Caller, type CallerOptions, Malformed, Refused, Unserved, } from "./call.ts";
+type Descriptor = z.infer<typeof descriptorSchema>;
+type Task = z.infer<typeof taskSchema>;
+type Alert = z.infer<typeof alert>;
+type Activity = z.infer<typeof activitySchema>;
+type Bucket = z.infer<typeof metricBucket>;
+/** What one Worker offers, read from its Descriptor and never guessed. */
+export type Consumed = {
+    /** The document itself, validated. Everything below was read out of it. */
+    descriptor: Descriptor;
+    /** DESC-23. The edition this Worker declares it speaks. */
+    edition: string;
+    health?: () => Promise<z.infer<typeof healthSchema>>;
+    metrics?: {
+        /** MET-8. One metric, every bucket in the interval, paged through (ENDP-20, ENDP-31). */
+        read: (metric: string, options?: MetricRead) => Promise<Bucket[]>;
+    };
+    actions?: {
+        /** ACT-5. The body is the input and carries nothing else. */
+        perform: (name: string, input: unknown, options?: PerformOptions) => Promise<unknown>;
+        /** ACT-15. The document `configure` would accept, where this Worker exposes one. */
+        settings?: () => Promise<unknown>;
+    };
+    alerts?: () => Promise<Alert[]>;
+    /** ACTV-2. What the Worker is doing and has undertaken to do. Read, never written. */
+    activity?: () => Promise<Activity[]>;
+    /**
+     * NDG-2. Tell this Worker there is work of a Task type it answers.
+     *
+     * The one write in this package that is not an Action, and the one whose body this protocol
+     * fixes rather than the Worker: a type, and nothing else. It buys latency and nothing else —
+     * TASK-19 recommends it and binds nobody, because a consumer reading on its own schedule is
+     * slower and never wrong, while one that reads only when told is a single dropped request away
+     * from stalling silently. So this answers nothing and is safe to lose.
+     *
+     * NDG-3: a type this Worker declares no Skill for is refused, and `Refused` carries the code.
+     * `skills.canAnswer` in this package is how a caller knows before sending one.
+     */
+    nudges?: (type: string) => Promise<void>;
+    tasks?: {
+        /**
+         * TASK-5. Every Task whose condition holds that this credential covers.
+         *
+         * Answering one is `actions.perform` with an Action the Task type names, and there is nothing
+         * to claim and nothing to close: the condition stops holding and the Task is gone.
+         */
+        list: (type?: string) => Promise<Task[]>;
+        /**
+         * How to answer a Task of this type: the Action to post, and the shape it takes.
+         *
+         * A Task carries its id, its type, its payload and when its condition began — and nothing about
+         * how to answer it, because that belongs to the Worker that raised it and is declared twice
+         * over in its Descriptor: the Task type names the Action that answers it (TASK-32), and that
+         * Action declares the JSON Schema of its input (ACT-2). Reading both is two walks down a
+         * document a consumer already holds, and every consumer was doing them by hand.
+         *
+         * The schema is handed back as it travels, so a console can render a form from it and an agent
+         * can build the document, neither having been told anything about this Worker. Where the Task
+         * can end several ways, that schema is a discriminated union and each ending is a variant.
+         *
+         * `undefined` where this Worker does not raise the type, or names an Action its own `actions`
+         * entry does not accept — a Descriptor disagreeing with itself is the verifier's to report
+         * against that Worker, and handing back a call that would answer `404` is not a consumer's job.
+         */
+        answers: (type: string) => {
+            action: string;
+            input: unknown;
+        } | undefined;
+    };
+};
+export type MetricRead = {
+    granularity?: string;
+    from?: Date;
+    to?: Date;
+    /** MET-19. Dimensions to break down by, each one that declared its set of values. */
+    by?: string[];
+    /** MET-16. Dimensions to fix, each spelled as a parameter of its own name. */
+    fixed?: Record<string, string>;
+};
+export type PerformOptions = {
+    /** ENDP-15. Where the Action declares it reads a key from the header. */
+    idempotencyKey?: string;
+};
+export { type Compatibility, canAnswer } from "./skills.ts";
+export declare function consume(baseUrl: string, options?: CallerOptions): Promise<Consumed>;

package/dist/index.js

@@ -0,0 +1,134 @@
+import { activityPage, alertPage, descriptor as descriptorSchema, health as healthSchema, metricPage, taskPage, } from "@worker-protocol/schemas";
+import { caller, collect } from "./call.js";
+/**
+ * `@worker-protocol/client` — read a Worker, and take work from it.
+ *
+ * `consume(url)` reads a Descriptor once, resolves every address the Worker declared (DESC-12) and
+ * answers an object with one member per Capability that Worker implements — and nothing for the
+ * ones it does not, because DESC-2 admits any combination including none.
+ *
+ * **It is the other half of `mount()` and it carries the same kind of thing.** A consumer that
+ * wrote this itself would write the address resolution, the paging and its cursor, the retry that
+ * must not happen on a `reject`, and the classification of an answer it cannot read. All of that
+ * is fixed by rules — nine of which oblige a consumer rather than a Worker — and `call.ts` cites
+ * every one.
+ *
+ * It depends on `@worker-protocol/schemas` and on `fetch`, and on nothing else. A Tower, a teams
+ * app or a Worker that consumes another Worker installs no web framework to do it.
+ *
+ * **Strict about what this protocol fixes, and blind to what it does not.** Every document
+ * `schemas/` describes is validated, and a Worker that answers something else raises `Malformed`
+ * naming the rule. A Task's payload, an Action's input and result, an event's data are the
+ * Worker's own — this protocol has no data model — and nothing here looks inside them.
+ */
+export { Malformed, Refused, Unserved, } from "./call.js";
+const rfc3339 = (at) => at.toISOString().replace(/\.\d{3}Z$/, "Z");
+export { canAnswer } from "./skills.js";
+export async function consume(baseUrl, options = {}) {
+    // DESC-3: the one route this protocol fixes, and the only address a consumer ever assembles.
+    // Everything else is declared, which is what ENDP-1 buys and why nothing below concatenates.
+    const descriptorUrl = new URL(".well-known/worker-protocol", baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).toString();
+    const call = caller(descriptorUrl, options);
+    const descriptor = await call.validated({ url: descriptorUrl, addressLevel: true }, descriptorSchema, "DESC-1");
+    const entry = (name) => descriptor.capabilities[name];
+    const addressOf = (name) => {
+        const declared = entry(name)?.address;
+        return typeof declared === "string" ? call.resolve(declared) : undefined;
+    };
+    const consumed = { descriptor, edition: descriptor.edition };
+    const healthAddress = addressOf("health");
+    if (healthAddress !== undefined) {
+        consumed.health = () => call.validated({ url: healthAddress, addressLevel: true }, healthSchema, "HLTH-2");
+    }
+    const metricsAddress = addressOf("metrics");
+    if (metricsAddress !== undefined) {
+        consumed.metrics = {
+            read: async (metric, read = {}) => {
+                // MET-19 travels as a repeated parameter — `?by=a&by=b` — which is why it goes on the URL
+                // here rather than into the flat record of single-valued parameters below.
+                const url = new URL(metricsAddress);
+                for (const dimension of read.by ?? [])
+                    url.searchParams.append("by", dimension);
+                const parameters = { metric };
+                if (read.granularity !== undefined)
+                    parameters.granularity = read.granularity;
+                // MET-11: RFC 3339 instants carrying an offset, and the interval is half-open.
+                if (read.from !== undefined)
+                    parameters.from = rfc3339(read.from);
+                if (read.to !== undefined)
+                    parameters.to = rfc3339(read.to);
+                // MET-16: a dimension is fixed with a parameter named exactly as the dimension.
+                for (const [name, value] of Object.entries(read.fixed ?? {}))
+                    parameters[name] = value;
+                return collect(call, url.toString(), metricPage, "MET-14", parameters);
+            },
+        };
+    }
+    const actionsAddress = addressOf("actions");
+    if (actionsAddress !== undefined) {
+        const perform = async (name, input, perform = {}) => {
+            // ACT-5: a POST to the declared address, naming the Action in the query parameter, with the
+            // body the input and nothing else. A resource-level 404 is ACT-6 and not DESC-30's.
+            const url = new URL(actionsAddress);
+            url.searchParams.set("action", name);
+            const answered = await call.call({
+                url: url.toString(),
+                method: "POST",
+                body: JSON.stringify(input),
+                idempotencyKey: perform.idempotencyKey,
+            });
+            // ACT-10, ACT-11: `200` with the Action's own result, `204` with none, `202` where it does
+            // not complete within the call. The result is the Worker's shape and is not validated.
+            return answered.status === 200 ? answered.json : undefined;
+        };
+        consumed.actions = { perform };
+        const configure = entry("actions")?.accepts
+            ?.configure;
+        if (typeof configure?.readAddress === "string") {
+            const settingsUrl = call.resolve(configure.readAddress);
+            // ACT-15: a GET answers a document `configure` would accept. Its shape is the Worker's own,
+            // so this reads it and does not judge it.
+            consumed.actions.settings = async () => (await call.call({ url: settingsUrl, addressLevel: true })).json;
+        }
+    }
+    const alertsAddress = addressOf("alerts");
+    if (alertsAddress !== undefined) {
+        consumed.alerts = () => collect(call, alertsAddress, alertPage, "ALRT-2");
+    }
+    const activityAddress = addressOf("activity");
+    if (activityAddress !== undefined) {
+        consumed.activity = () => collect(call, activityAddress, activityPage, "ACTV-2");
+    }
+    const nudgesAddress = addressOf("nudges");
+    if (nudgesAddress !== undefined) {
+        // NDG-2: a POST carrying the type and nothing else, answered `204`. Nothing comes back, so
+        // nothing is parsed — a body here would be the receiver holding state about work it has not
+        // looked at, which is the lease `spec/tasks.md` withdrew arriving through another door.
+        consumed.nudges = async (type) => {
+            await call.call({ url: nudgesAddress, method: "POST", body: JSON.stringify({ type }) });
+        };
+    }
+    const tasksAddress = addressOf("tasks");
+    if (tasksAddress !== undefined) {
+        consumed.tasks = {
+            list: (type) => 
+            // TASK-8 filters by type where one is asked for; absent, the read is unfiltered and a
+            // `404` from it would be DESC-30's rather than a resource's, which `pages` works out.
+            collect(call, tasksAddress, taskPage, "TASK-5", type === undefined ? {} : { type }),
+            // TASK-32 names the Action; ACT-2 declares its input. Both are already in the document this
+            // consumer read, so this walks it rather than calling anything.
+            answers: (type) => {
+                const raises = entry("tasks")
+                    ?.raises;
+                const accepts = entry("actions")
+                    ?.accepts;
+                const action = raises?.[type]?.answeredBy;
+                if (action === undefined)
+                    return undefined;
+                const taken = accepts?.[action];
+                return taken === undefined ? undefined : { action, input: taken.input };
+            },
+        };
+    }
+    return consumed;
+}

package/dist/skills.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Whether one Worker can answer another's Tasks, decided from what both of them declared.
+ *
+ * This is the question an operator asks when enrolling a Worker — *can it take that one's work?* —
+ * and `spec/tasks.md` is what answers it. TASK-32 has the owner declare the payload it sends under
+ * `raises`; TASK-31 has the answerer declare what it requires under `skills`. NAME-6 fixes which
+ * way to judge the two: a document a Worker receives is judged against the party that sends it.
+ *
+ * **It compares declarations and calls nothing.** Both Descriptors are already in hand — a Tower
+ * holds a dated copy of each (DESC-20) — so the answer arrives at enrollment, before any Task
+ * exists and before any work changes hands, which is the whole point of asking. Sampling the
+ * Tasks an owner happens to have open answers a weaker question: at enrollment there are usually
+ * none, and *nothing was open to check* is not *this pairing works*.
+ *
+ * It lives here rather than in a Tower because a Tower is a role and not a product, and this is an
+ * algorithm `spec/` states rather than a policy anybody chooses. `packages/README.md` puts the
+ * rules that bind a consumer in this package for the same reason: the alternative is every Tower,
+ * teams app and proxy deriving it again, and disagreeing about the cases below.
+ */
+import type { descriptor } from "@worker-protocol/schemas";
+import type * as z from "zod";
+type Descriptor = z.infer<typeof descriptor>;
+/**
+ * What was decided, and why — so that a console can say it rather than showing a boolean.
+ *
+ * `unknown` is not `false`. An answerer that declares the Skill and states no requirement has
+ * claimed the capability and said nothing about what it needs, which TASK-31 admits; a Tower that
+ * reported that as a refusal would be inventing an obligation the specification does not carry.
+ */
+export type Compatibility = {
+    verdict: "compatible" | "incompatible" | "unknown";
+    why: string;
+};
+/**
+ * Can `answerer` answer `owner`'s Tasks of this type?
+ *
+ * Two documents travel, one each way, so there are two halves to judge and both must hold. The
+ * Task goes from owner to answerer: what the answerer REQUIRES (TASK-31 `payload`) must be covered
+ * by what the owner SENDS (TASK-32 `payload`). The answer goes back: what the owner's answering
+ * Action TAKES (ACT-2 `input`, named by TASK-32 `answeredBy`) must be covered by what the answerer
+ * PRODUCES (TASK-31 `produces`). Either half the answerer left undeclared is `unknown` — a claim
+ * with nothing to check, which TASK-31 admits and a Tower must not report as a refusal.
+ */
+export declare function canAnswer(owner: Descriptor, answerer: Descriptor, type: string): Compatibility;
+export {};

package/dist/skills.js

@@ -0,0 +1,150 @@
+/**
+ * Whether one Worker can answer another's Tasks, decided from what both of them declared.
+ *
+ * This is the question an operator asks when enrolling a Worker — *can it take that one's work?* —
+ * and `spec/tasks.md` is what answers it. TASK-32 has the owner declare the payload it sends under
+ * `raises`; TASK-31 has the answerer declare what it requires under `skills`. NAME-6 fixes which
+ * way to judge the two: a document a Worker receives is judged against the party that sends it.
+ *
+ * **It compares declarations and calls nothing.** Both Descriptors are already in hand — a Tower
+ * holds a dated copy of each (DESC-20) — so the answer arrives at enrollment, before any Task
+ * exists and before any work changes hands, which is the whole point of asking. Sampling the
+ * Tasks an owner happens to have open answers a weaker question: at enrollment there are usually
+ * none, and *nothing was open to check* is not *this pairing works*.
+ *
+ * It lives here rather than in a Tower because a Tower is a role and not a product, and this is an
+ * algorithm `spec/` states rather than a policy anybody chooses. `packages/README.md` puts the
+ * rules that bind a consumer in this package for the same reason: the alternative is every Tower,
+ * teams app and proxy deriving it again, and disagreeing about the cases below.
+ */
+/** The variants of a union schema, or the schema itself where it is not one. */
+const variantsOf = (schema) => schema.anyOf ?? schema.oneOf ?? [schema];
+/**
+ * The member that tells a union's variants apart, where one does — TASK-32's discriminator.
+ *
+ * It is a member every variant fixes to a different constant, which is what `z.discriminatedUnion`
+ * writes and what TASK-32 requires of a Task with several endings.
+ */
+function discriminator(variants) {
+    if (variants.length < 2)
+        return undefined;
+    const first = variants[0];
+    if (first === undefined)
+        return undefined;
+    return Object.keys(first.properties ?? {}).find((member) => {
+        const fixed = variants.map((one) => one.properties?.[member]?.const);
+        return fixed.every((one) => one !== undefined) && new Set(fixed).size === variants.length;
+    });
+}
+/** The names a JSON Schema requires, or none where it names no `required` array. */
+const requiredOf = (schema) => Array.isArray(schema.required) ? schema.required.filter((one) => typeof one === "string") : [];
+/** The `type` a schema fixes for one member, where it fixes one. */
+const typeOf = (schema, member) => schema.properties?.[member]?.type;
+/**
+ * Whether what one party requires is covered by what the other provides — NAME-6, one direction.
+ *
+ * The tractable part of comparing two JSON Schemas, and the part `spec/tasks.md` states in TASK-31:
+ * a receiver may ask for less than the sender produces and may not ask for more. So every member
+ * the receiver requires must be one the sender declares, and where both fix a `type` for it the two
+ * must agree. Full subsumption is undecidable in general, and a Tower that attempted it would refuse
+ * pairings nobody could explain; this decides what the rule claims and no more. It is assignability
+ * and it reads the same in both directions, which is why it is stated here once rather than derived
+ * from either half's rule.
+ *
+ * **The discriminator is the owner's word and is not charged to the answerer.** TASK-32 puts a
+ * Task's endings in a union told apart by a member the OWNER mints — `outcome: "found"` — and an
+ * answerer writing its own Descriptor cannot know that word, because it serves owners it has never
+ * read. Counting it as coverage the answerer owes would refuse every honest answerer and would put
+ * the per-owner mapping back exactly where withdrawing TASK-2's list took it from. So it is skipped
+ * where the answerer says nothing about it, and used to pick the variant where it says something.
+ */
+function covered(requires, provides, noun) {
+    const takes = variantsOf(requires);
+    const told = discriminator(takes);
+    for (const produced of variantsOf(provides)) {
+        // Where the answerer names the ending, that variant is the one it is answering. Where it does
+        // not, any variant it satisfies will do — it produces a subtype, which is assignable.
+        const said = told === undefined ? undefined : produced.properties?.[told]?.const;
+        const against = takes
+            .filter((taken) => said === undefined || taken.properties?.[told]?.const === said)
+            .map((taken) => accepts(taken, produced, told));
+        if (against.length === 0) {
+            return { verdict: "incompatible", why: `${noun} no ending it names` };
+        }
+        if (!against.some((one) => one.length === 0)) {
+            return { verdict: "incompatible", why: `${noun} ${against[0].join(", ")}` };
+        }
+    }
+    return { verdict: "compatible", why: "" };
+}
+/**
+ * One variant against one: the members it is missing and the ones it disagrees about, or none.
+ *
+ * `told` is skipped, for the reason `covered` gives. The complaints come back as names rather than
+ * a sentence so that the direction is written once, by the caller that knows which way this is.
+ */
+function accepts(requires, provides, told) {
+    const offered = Object.keys(provides.properties ?? {});
+    const owed = requiredOf(requires).filter((member) => member !== told);
+    const missing = owed.filter((member) => !offered.includes(member));
+    const disagreeing = owed.filter((member) => {
+        const wanted = typeOf(requires, member);
+        const given = typeOf(provides, member);
+        return wanted !== undefined && given !== undefined && wanted !== given;
+    });
+    return [...missing, ...disagreeing];
+}
+/**
+ * Can `answerer` answer `owner`'s Tasks of this type?
+ *
+ * Two documents travel, one each way, so there are two halves to judge and both must hold. The
+ * Task goes from owner to answerer: what the answerer REQUIRES (TASK-31 `payload`) must be covered
+ * by what the owner SENDS (TASK-32 `payload`). The answer goes back: what the owner's answering
+ * Action TAKES (ACT-2 `input`, named by TASK-32 `answeredBy`) must be covered by what the answerer
+ * PRODUCES (TASK-31 `produces`). Either half the answerer left undeclared is `unknown` — a claim
+ * with nothing to check, which TASK-31 admits and a Tower must not report as a refusal.
+ */
+export function canAnswer(owner, answerer, type) {
+    const skill = answerer.skills?.[type];
+    if (skill === undefined) {
+        return { verdict: "incompatible", why: `it declares no Skill for ${type}` };
+    }
+    const tasks = owner.capabilities.tasks;
+    const raised = tasks?.raises?.[type];
+    if (raised === undefined) {
+        return { verdict: "incompatible", why: `the owner raises no ${type}` };
+    }
+    // Receiving: the Task the owner sends, against what the answerer needs to be handed.
+    const requires = skill.payload;
+    const receiving = requires === undefined
+        ? { verdict: "unknown", why: "it states no requirement for what it receives" }
+        : covered(requires, raised.payload, "it requires what the owner does not send:");
+    // Sending: what the answerer produces, against what the one Action the owner names will take.
+    // Where the Task has several endings they are variants of that input, and producing some of them
+    // is producing a subtype — assignable, and `covered` looks inside the union to say so.
+    const declared = owner.capabilities.actions
+        ?.accepts;
+    const produces = skill.produces;
+    const takes = declared?.[raised.answeredBy]?.input;
+    let sending;
+    if (produces === undefined) {
+        sending = { verdict: "unknown", why: "it states nothing about what it produces" };
+    }
+    else if (takes === undefined) {
+        sending = { verdict: "unknown", why: "the owner's answering Action is not one it accepts" };
+    }
+    else {
+        sending = covered(takes, produces, "the owner's Action requires what it does not produce:");
+    }
+    const halves = [receiving, sending];
+    const refused = halves.find((one) => one.verdict === "incompatible");
+    if (refused !== undefined)
+        return refused;
+    const open = halves.filter((one) => one.verdict === "unknown");
+    if (open.length > 0)
+        return { verdict: "unknown", why: open.map((one) => one.why).join("; ") };
+    return {
+        verdict: "compatible",
+        why: "it can read what the owner sends and produce what it takes",
+    };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@worker-protocol/client",
+  "version": "0.1.0",
+  "workerProtocolEdition": "0.1",
+  "description": "Read a Worker, and take work from it. The consumer half of worker-protocol",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rowing-tech/worker-protocol.git",
+    "directory": "packages/client"
+  },
+  "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"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@worker-protocol/schemas": "0.1.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "26.5.1",
+    "@worker-protocol/hono": "0.1.0",
+    "hono": "4.13.7",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0",
+    "zod": "4.5.4"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run"
+  }
+}