@byollm/protocol 0.1.0-alpha.57 → 0.1.0-alpha.59

package/dist/index.d.ts

@@ -22,9 +22,9 @@ type BackendClass = z.infer<typeof BackendClass>;
  *
  * This replaced a two-valued `account` field that conflated two unrelated
  * constraints and, in doing so, left a hole: `openai-http` was "open", but it
- * accepts an API key, so an owner could point it at a paid endpoint, offer it
- * `public`, and donate their credit balance to strangers. The community
- * budgets cap job *count*, not spend.
+ * accepts an API key, so an owner could point it at a paid endpoint, share it,
+ * and donate their credit balance to strangers. The community budgets cap job
+ * *count*, not spend.
  *
  * - `free` — local compute. Costs electricity, not money. Shareable.
  * - `metered` — per-token billing against the owner's account. Legal to
@@ -165,7 +165,7 @@ declare function backendDescriptor(id: BackendId): BackendDescriptor;
  * an act by the machine's owner against their own account, and the threat
  * model here is a hostile *job*, not an owner routing around a rule that
  * exists to protect them. What this catches is the accident — a remote paid
- * endpoint offered `public` because nobody thought about the bill. See
+ * endpoint offered to a team because nobody thought about the bill. See
  * `docs/security.md` §4a.
  */
 declare function isLocalHost(hostname: string): boolean;
@@ -270,54 +270,53 @@ declare function classifyCost(id: BackendId, baseUrl: string | undefined, model:
  * Who may run a job, declared by the app that enqueued it.
  *
  * - `private` — only the job owner's own devices.
- * - `team` — a device whose owner has this person on their roster.
- * - `public` — any device offering `public` compute.
+ * - `team` — a device whose owner admits this person.
  *
  * **One vocabulary, ruled 2026-08-24.** These were `self | named | public`
- * while {@link OfferScope} became `private | team | public`, which would have
- * left every seam where the two meet speaking two languages for one idea, and
- * every doc explaining "self versus private" for ever. They are still
- * independent axes — a job says who may run it, a service says who it will run
- * for — and a job runs only where both agree
- * ({@link MUSTS.AUDIENCE_BOTH_SIDES}). Sharing the words costs nothing and
- * saves a mapping layer nobody would have enjoyed maintaining.
+ * while {@link OfferScope} used different words for the same idea, which would
+ * have left every seam where the two meet speaking two languages, and every
+ * doc explaining "self versus private" for ever. They are still independent
+ * axes — a job says who may run it, a service says who it will run for — and a
+ * job runs only where both agree ({@link MUSTS.AUDIENCE_BOTH_SIDES}).
+ *
+ * **`public` is gone, ruled 2026-08-26 (byollm_016).** Not deprecated,
+ * removed, and removed from the OSS daemon too rather than parked as a
+ * community posture. The argument was a measurement rather than a preference:
+ * device-side admission had never once been exercised end to end, because
+ * every cross-user test ran against a publicly offered service and
+ * {@link matchAudience} returned ALLOWED for those *without consulting the
+ * device at all*. `public` was the off switch for admission, and an enum with
+ * a value that skips verification is a fail-open waiting for the wiring bug
+ * that reaches it. There is now no such value.
  */
 declare const Audience: z.ZodEnum<{
     private: "private";
     team: "team";
-    public: "public";
 }>;
 type Audience = z.infer<typeof Audience>;
 /**
  * What a device's owner is willing to run for other people, per service.
  *
  * - `private` — the owner's own work only.
- * - `team` — the owner's roster. Membership is **central**, not per-person:
- *   the device follows the roster rather than holding its own copy of who is
- *   in it (byollm_016, 2026-08-24).
- * - `public` — any job, from anyone. This is the community posture the daemon
- *   has always had (`byollm offer <service> public`), bounded by community
- *   budgets. byollm_016 parks it as a **hosted-product** surface — the cloud
- *   dashboard does not offer it — which is not the same as removing it from
- *   the daemon, and the CLI still accepts it.
- *
- * Deliberately *not* the same words as {@link Audience}, which they used to
- * share. They are independent axes — a job says who may run it, a service says
- * who it will run for — and identical spellings made that read as one concept
- * with two homes. A job runs only where both agree
- * ({@link MUSTS.AUDIENCE_BOTH_SIDES}); {@link matches} is the one place the
- * correspondence lives.
+ * - `team` — whoever the owner's authority admits. Membership is **central**,
+ *   not per-person: the device follows what it is told by a signature it can
+ *   check, rather than holding its own copy of who is in it (byollm_016).
+ *
+ * Two values, and no third that means "everyone". See {@link Audience} for
+ * why `public` was removed rather than parked, and note the shape of the
+ * remaining enum: **every value left requires the device to verify
+ * something.** `private` checks the owner; `team` checks admission. That is
+ * the property, not an accident of there being two.
  */
 declare const OfferScope: z.ZodEnum<{
     private: "private";
     team: "team";
-    public: "public";
 }>;
 type OfferScope = z.infer<typeof OfferScope>;
 /** All audience values, in widening order. */
-declare const AUDIENCES: readonly ("private" | "team" | "public")[];
+declare const AUDIENCES: readonly ("private" | "team")[];
 /** All offer scopes, in widening order. */
-declare const OFFER_SCOPES: readonly ("private" | "team" | "public")[];
+declare const OFFER_SCOPES: readonly ("private" | "team")[];
 /**
  * Why a job was refused. Distinct codes because byollm_002 requires that
  * different truths never share a message — "no matching work" and "refused on
@@ -356,7 +355,7 @@ interface SpendConsent {
  * its matcher call, so no code path can observe a scope wider than the cost
  * class allows:
  *
- * - `subscription` is locked to `self` regardless of config
+ * - `subscription` is locked to `private` regardless of config
  *   ({@link MUSTS.SUBSCRIPTION_SELF_LOCK}) — someone else's terms.
  * - `metered` narrows to `private` unless the owner has explicitly acknowledged
  *   the spend ({@link MUSTS.METERED_DEFAULTS_SELF}) — their money.
@@ -374,7 +373,8 @@ interface MatchJob {
     readonly audience: Audience;
     /**
      * Optional server-side restriction on which runner owners may take a
-     * `named` job. Defence in depth only — the daemon's local allowlist is the
+     * `team` job. Defence in depth only, and direct-mode only — it never
+     * reaches a daemon (cloud_008 §0.2), so the device's own admission is the
      * enforcing side ({@link MUSTS.NAMED_LOCAL_ALLOWLIST}).
      */
     readonly audienceAllow?: readonly string[] | undefined;
@@ -390,13 +390,24 @@ interface MatchDaemon {
     /** What the owner agreed to spend on others, for a `metered` backend. */
     readonly spend?: SpendConsent | undefined;
     /**
-     * Does this daemon's *local* allowlist admit the given owner for the server
-     * origin the job came from? Supplied as a predicate so the protocol package
-     * stays free of file I/O; the daemon passes its allowlist, the server
-     * passes a conservative `() => true` because it cannot know a remote
-     * daemon's local list and must not pretend to.
+     * Has something **this device verified** admitted the job's owner?
+     *
+     * A predicate rather than a value so the protocol package stays free of
+     * both file I/O and signature state. What supplies it has changed twice and
+     * will change again — a local allowlist, then a held roster, and now a
+     * claim-time signed grant (Amendment J) — and the law it feeds has not
+     * changed at all: a `team` service runs a stranger's work only when
+     * somebody this device can check said so.
+     *
+     * The server passes a conservative `() => true`: it cannot know what a
+     * remote device verified and must not pretend to. The device is the
+     * enforcing side, which is the whole point of asking here.
+     *
+     * Named for the question, not for where the answer lives. This was called
+     * `locallyAllows`, and "locally" stopped being true the moment the answer
+     * came from a document somebody else signed.
      */
-    readonly locallyAllows: (owner: string) => boolean;
+    readonly admits: (owner: string) => boolean;
 }
 /**
  * Decide whether a job may run on a daemon.
@@ -405,8 +416,8 @@ interface MatchDaemon {
  * 1. the job's audience must admit the daemon's owner, and
  * 2. the backend's offer scope must admit the job's owner.
  *
- * The full nine-way matrix (three audiences × three offer scopes) is asserted
- * by the conformance kit. The function is pure and total so both the daemon
+ * The full four-way matrix (two audiences × two offer scopes) is asserted by
+ * the conformance kit. The function is pure and total so both the daemon
  * and the server can run the identical rule — the daemon refuses, and the
  * server refuses too (byollm_003 §Server-side MUSTs).
  *
@@ -418,7 +429,7 @@ interface MatchDaemon {
  *     owner: "bob",
  *     offerScope: "team",
  *     cost: "free",
- *     locallyAllows: (o) => o === "alice",
+ *     admits: (o) => o === "alice",
  *   },
  * );
  * // result.ok === true
@@ -443,9 +454,9 @@ declare const REFUSAL_MESSAGES: Readonly<Record<MatchRefusal, string>>;
  * per-field limits were real and the aggregate one was a number in a frozen
  * object.
  *
- * byollm_004 §4 requires stricter limits for community (`named`/`public`)
- * jobs; those are applied on top of these by the daemon's budget check, which
- * knows the job's audience. These are the absolute ceilings for any job.
+ * byollm_004 §4 requires stricter limits for community (`team`) jobs; those
+ * are applied on top of these by the daemon's budget check, which knows the
+ * job's audience. These are the absolute ceilings for any job.
  */
 declare const PAYLOAD_LIMITS: Readonly<{
     /** Max characters in any single text field. */
@@ -466,7 +477,7 @@ declare const ChatMessage: z.ZodObject<{
         assistant: "assistant";
     }>;
     content: z.ZodString;
-}, z.core.$strip>;
+}, z.core.$strict>;
 type ChatMessage = z.infer<typeof ChatMessage>;
 /**
  * Payload for `llm.generate`.
@@ -493,7 +504,7 @@ declare const ChatPayload: z.ZodObject<{
             assistant: "assistant";
         }>;
         content: z.ZodString;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     system: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 type ChatPayload = z.infer<typeof ChatPayload>;
@@ -520,7 +531,7 @@ declare const KindedPayload: z.ZodDiscriminatedUnion<[z.ZodObject<{
         prompt: z.ZodString;
         system: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"llm.chat">;
     payload: z.ZodObject<{
         messages: z.ZodArray<z.ZodObject<{
@@ -530,10 +541,10 @@ declare const KindedPayload: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 assistant: "assistant";
             }>;
             content: z.ZodString;
-        }, z.core.$strip>>;
+        }, z.core.$strict>>;
         system: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
-}, z.core.$strip>], "kind">;
+}, z.core.$strict>], "kind">;
 type KindedPayload = z.infer<typeof KindedPayload>;
 /** The payload type for a given kind. */
 type PayloadFor<K extends JobKind> = K extends "llm.generate" ? GeneratePayload : ChatPayload;
@@ -562,11 +573,11 @@ declare function payloadTextLength(kinded: KindedPayload): number;
 declare const JobState: z.ZodEnum<{
     ok: "ok";
     error: "error";
+    expired: "expired";
     queued: "queued";
     claimed: "claimed";
     running: "running";
     canceled: "canceled";
-    expired: "expired";
 }>;
 type JobState = z.infer<typeof JobState>;
 /** States from which a job never moves again. */
@@ -580,7 +591,7 @@ declare const Lease: z.ZodObject<{
     id: z.ZodString;
     runnerId: z.ZodString;
     expiresAt: z.ZodNumber;
-}, z.core.$strip>;
+}, z.core.$strict>;
 type Lease = z.infer<typeof Lease>;
 /** Payload union as it appears on a job record. */
 declare const JobPayload: z.ZodUnion<readonly [z.ZodObject<{
@@ -594,7 +605,7 @@ declare const JobPayload: z.ZodUnion<readonly [z.ZodObject<{
             assistant: "assistant";
         }>;
         content: z.ZodString;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     system: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>]>;
 type JobPayload = z.infer<typeof JobPayload>;
@@ -623,13 +634,12 @@ declare const ClaimedJob: z.ZodObject<{
                 assistant: "assistant";
             }>;
             content: z.ZodString;
-        }, z.core.$strip>>;
+        }, z.core.$strict>>;
         system: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     audience: z.ZodEnum<{
         private: "private";
         team: "team";
-        public: "public";
     }>;
     owner: z.ZodString;
     site: z.ZodOptional<z.ZodString>;
@@ -638,13 +648,13 @@ declare const ClaimedJob: z.ZodObject<{
         id: z.ZodString;
         runnerId: z.ZodString;
         expiresAt: z.ZodNumber;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
 }, z.core.$strict>;
 type ClaimedJob = z.infer<typeof ClaimedJob>;
 /**
  * The provenance that travels with every result to the delivery seam.
  *
- * byollm_003 Rev 1: a `named`/`public` result is attacker-controlled text.
+ * byollm_003 Rev 1: a `team` result is attacker-controlled text.
  * The app must never render volunteer output as its own AI's answer without
  * knowing that is what it is ({@link MUSTS.PROVENANCE_NAMES_DEVICE}).
  */
@@ -652,7 +662,6 @@ declare const ResultProvenance: z.ZodObject<{
     audience: z.ZodEnum<{
         private: "private";
         team: "team";
-        public: "public";
     }>;
     runnerId: z.ZodString;
     runnerOwner: z.ZodString;
@@ -744,7 +753,6 @@ type JobOutcome = z.infer<typeof JobOutcome>;
  * list rather than three private vocabularies.
  */
 declare const RefusalReason: z.ZodEnum<{
-    "select-unavailable": "select-unavailable";
     "default-ambiguity": "default-ambiguity";
     "default-unusable": "default-unusable";
 }>;
@@ -774,7 +782,6 @@ type RefusalReason = z.infer<typeof RefusalReason>;
 declare const JobRefused: z.ZodObject<{
     outcome: z.ZodLiteral<"refused">;
     reason: z.ZodEnum<{
-        "select-unavailable": "select-unavailable";
         "default-ambiguity": "default-ambiguity";
         "default-unusable": "default-unusable";
     }>;
@@ -818,11 +825,11 @@ declare const DeliveredResult: z.ZodObject<{
     state: z.ZodEnum<{
         ok: "ok";
         error: "error";
+        expired: "expired";
         queued: "queued";
         claimed: "claimed";
         running: "running";
         canceled: "canceled";
-        expired: "expired";
     }>;
     outcome: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         outcome: z.ZodLiteral<"ok">;
@@ -840,7 +847,6 @@ declare const DeliveredResult: z.ZodObject<{
         audience: z.ZodEnum<{
             private: "private";
             team: "team";
-            public: "public";
         }>;
         runnerId: z.ZodString;
         runnerOwner: z.ZodString;
@@ -919,9 +925,8 @@ declare const JobStub: z.ZodObject<{
     audience: z.ZodEnum<{
         private: "private";
         team: "team";
-        public: "public";
     }>;
-    service: z.ZodOptional<z.ZodString>;
+    purpose: z.ZodOptional<z.ZodString>;
     sizeClass: z.ZodEnum<{
         small: "small";
         medium: "medium";
@@ -932,7 +937,23 @@ declare const JobStub: z.ZodObject<{
     deadlineAt: z.ZodNumber;
 }, z.core.$strict>;
 type JobStub = z.infer<typeof JobStub>;
-/** A stub, plus the lease the claiming runner now holds for it. */
+/**
+ * A stub, plus the lease the claiming runner now holds for it — and, on a
+ * relayed route, the grant that says it may run at all.
+ *
+ * The grant lives here rather than on {@link JobStub} because of *when* it is
+ * authored. A stub exists from enqueue; a grant is written at claim, against
+ * the membership and mapping true at that moment. That timing is the whole of
+ * Amendment J: a job queued yesterday for somebody removed this morning gets
+ * no grant when it is finally claimed, and a roster held on the device could
+ * never have known.
+ *
+ * Optional, and the absence is meaningful rather than lenient. A device that
+ * pinned a control-plane key at pairing **requires** one — a claimed job
+ * arriving without it is refused, not admitted by default. A device that
+ * pinned none is in direct mode, where there is no control plane to author
+ * anything and the owner's own work is the only work that runs.
+ */
 declare const ClaimedStub: z.ZodObject<{
     id: z.ZodString;
     kind: z.ZodEnum<{
@@ -944,9 +965,8 @@ declare const ClaimedStub: z.ZodObject<{
     audience: z.ZodEnum<{
         private: "private";
         team: "team";
-        public: "public";
     }>;
-    service: z.ZodOptional<z.ZodString>;
+    purpose: z.ZodOptional<z.ZodString>;
     sizeClass: z.ZodEnum<{
         small: "small";
         medium: "medium";
@@ -959,7 +979,19 @@ declare const ClaimedStub: z.ZodObject<{
         id: z.ZodString;
         runnerId: z.ZodString;
         expiresAt: z.ZodNumber;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
+    grant: z.ZodOptional<z.ZodObject<{
+        grantId: z.ZodString;
+        jobId: z.ZodString;
+        site: z.ZodString;
+        user: z.ZodString;
+        owner: z.ZodString;
+        purpose: z.ZodString;
+        kind: z.ZodString;
+        service: z.ZodString;
+        issuedAt: z.ZodNumber;
+        signature: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 type ClaimedStub = z.infer<typeof ClaimedStub>;
 
@@ -1297,105 +1329,270 @@ declare function verifyRequest(input: {
 }): SignatureFailure | null;
 
 /**
- * The roster a daemon holds, and how it knows the roster is real.
+ * What a site says it needs — byollm_016 Amendment L.
+ *
+ * A site declares **purposes**, and each purpose lists the job kinds it uses.
+ * A person then maps each purpose to one of their own services, on the consent
+ * screen, and that mapping *is* the consent. The control plane joins the two
+ * at claim time and signs the result into a grant.
+ *
+ * ## Why a site declares needs instead of naming services
+ *
+ * Because it cannot name one. The site's vocabulary is its own purposes; the
+ * person's vocabulary is their services; and the two never meet. A site asks
+ * for "writing assistant, llm.chat" and learns only whether that slot is
+ * satisfiable — never which model answered, never whose machine, never even
+ * the name of the service. Key-vs-value reaches its strongest form here: the
+ * site cannot describe what it wants *or* name it, only ask for what it
+ * declared.
+ *
+ * ## Keys are ids; labels are prose
+ *
+ * They are separate fields and nothing derives one from the other, which is
+ * the amendment's ruling and worth restating where somebody will read it. A
+ * key travels on every job and is what mappings are stored against, so it is
+ * stable-or-nothing: renaming one deletes a purpose and creates another,
+ * unmapping everybody who had chosen for it. A label is changeable whenever
+ * the site likes and is the **only** thing a consent screen renders.
+ */
+/**
+ * The purpose a site gets when it declares no purposes of its own.
+ *
+ * Reserved, and refused by {@link Manifest} rather than by whatever handles
+ * registration. A site with a single undifferentiated use has one purpose —
+ * everything it does — and that purpose needs an id because mappings are
+ * keyed by one. An id taken from the site's own vocabulary would collide the
+ * day it declared a real purpose of the same name.
+ *
+ * **Never rendered.** "default → your Claude" tells a person nothing; a
+ * consent screen shows the site's own name for this slot, because that is
+ * what a single-purpose site's one purpose actually is.
+ */
+declare const RESERVED_PURPOSE = "default";
+declare const Purpose: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    kinds: z.ZodArray<z.ZodEnum<{
+        "llm.generate": "llm.generate";
+        "llm.chat": "llm.chat";
+    }>>;
+}, z.core.$strict>;
+type Purpose = z.infer<typeof Purpose>;
+declare const Manifest: z.ZodRecord<z.ZodString, z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    kinds: z.ZodArray<z.ZodEnum<{
+        "llm.generate": "llm.generate";
+        "llm.chat": "llm.chat";
+    }>>;
+}, z.core.$strict>>;
+type Manifest = z.infer<typeof Manifest>;
+/**
+ * The manifest a site with no declared purposes is treated as having.
+ *
+ * The sugar in Amendment L, made explicit rather than special-cased
+ * downstream: everything after this point sees a manifest with one purpose,
+ * so no consent screen, mapping table or resolver needs a branch for the
+ * flat-list case.
+ *
+ * The label is the caller's — a site's own name — because it is the one thing
+ * that can make "everything this site does" read as a sentence about a
+ * particular site rather than about software in general.
+ */
+declare function singlePurposeManifest(input: {
+    readonly label: string;
+    readonly kinds: readonly JobKind[];
+}): Manifest;
+
+/**
+ * One job, one signature, one answer — byollm_016 Amendment J.
+ *
+ * A grant is the control plane's signed statement that a particular job may
+ * run on a particular device, authored at claim time and verified against the
+ * key that device pinned when it paired.
+ *
+ * ## What it replaced, and why the replacement is smaller
+ *
+ * Until 2026-08-26 a device held a signed **roster** and answered admission
+ * from it. Amendment G's four properties were right and the mechanism was a
+ * cache — one that bought nothing. On the cloud route the job path and the
+ * roster path share fate: jobs arrive through the relay, so if the relay is
+ * unreachable there are no jobs to admit and a locally held roster adds no
+ * availability. What it did add was staleness, which is the only reason
+ * `ROSTER_MAX_AGE_MS` existed: a bound on how long a removed person keeps
+ * running. Authoring at claim collapses that bound to this document's own
+ * lifetime — add somebody and their next job runs, remove them and their next
+ * claim fails, including jobs already queued.
+ *
+ * It also collapses four questions into one signature. Consented, member,
+ * admitted, and *which service* were four mechanisms answering separately;
+ * they are now four fields of one statement, and the device verifies once.
  *
- * byollm_001 Amendment G, RATIFIED 2026-08-25. A `team` job is admitted by a
- * list **this device holds**, signed by the owner's control plane and verified
- * against a key pinned at pairing — never by an assertion from the party
- * routing the job, per-job or in bulk.
+ * ## What it is not
  *
- * The relay's power over this is exactly denial: it can withhold a roster as
- * it can withhold a job, and it can forge neither. That is what lets the hub
- * go on reading and filtering rosters for its own routing without being
- * trusted for admission — non-authorship, not blindness.
+ * Amendment G property 1 outlawed admitting on a per-job assertion, and this
+ * is per-job. The distinction is authorship: G outlawed trusting the
+ * **relay's or site's unsigned** claim. A grant is signed by the control
+ * plane with a key the device pinned at pairing, so the relay can withhold it
+ * and cannot forge it — exactly the power a relay has over a job.
+ * `RELAY_BLIND` is untouched: the relay delivers, it never authors.
+ *
+ * ## What the device still checks for itself
+ *
+ * A grant is necessary and not sufficient. Four checks stay on the device and
+ * none of them is delegated:
+ *
+ * 1. the signature, against the pinned key;
+ * 2. replay — {@link SignedGrant.grantId} is single-use;
+ * 3. offer-consistency — the named service is one this device actually
+ *    offers, at a scope that includes this user;
+ * 4. **private is absolute** — a `private` service runs for the paired owner
+ *    and nobody else, so no compromise of a control plane can grant somebody
+ *    else's job onto it.
  */
 /**
- * How old a held roster may be before a device stops honouring it.
+ * How long a grant is honoured after it was signed. Ruled 120s (2026-08-26).
  *
- * One hour, and the shortest constant in this protocol on purpose: every other
- * one bounds how long a *thing* stays valid, and this one alone bounds how
- * long a *person* keeps access after the owner has said no.
+ * This bounds **acceptance**, not execution: a job admitted inside the window
+ * runs to completion however long it takes. So the number only has to cover
+ * the trip from the control plane signing to the device checking — claim,
+ * deliver, verify — and every second past that is a second a captured grant
+ * stays useful.
  *
- * A failure bound, not a sync interval. A daemon refreshes on every heartbeat
- * and a removal propagates in seconds; the hour is what a device gets when
- * that conversation stops working — enough that a closed laptop or a flaky
- * café network does not narrow a working device, and not so much that a
- * removed teammate outlives the owner's patience.
+ * Two minutes is generous for that trip and mean for the capture. It is also
+ * the number ordinary clock drift is measured against, which is why
+ * {@link CLOCK_SKEW_WARN_MS} sits well inside it: a device whose clock is off
+ * by half the window would refuse real work, and must be told before it does.
+ *
+ * The verifier's policy, deliberately not a field on the document. An
+ * `expiresAt` the signer chose would let whoever signs decide how long their
+ * own statement stays good, and the party with the most reason to want a
+ * longer window is the party being bounded.
  */
-declare const ROSTER_MAX_AGE_MS: number;
+declare const GRANT_MAX_AGE_MS = 120000;
 /**
- * The domain separator, and why a roster gets its own.
+ * Clock disagreement past which a device says so, before it starts refusing.
+ *
+ * Skew eats {@link GRANT_MAX_AGE_MS} directly — a device 60s behind its
+ * relay's clock has half a window left, and one 120s behind has none and
+ * refuses everything for a reason no refusal message would otherwise name.
+ * Thirty seconds is a quarter of the window: far enough out to be a real
+ * problem, early enough to be a warning rather than an outage.
+ */
+declare const CLOCK_SKEW_WARN_MS = 30000;
+/**
+ * Skew past which a freshness refusal names the clock instead of the grant.
+ *
+ * Five seconds, because below that the clock is not the story and saying so
+ * would send somebody to check ntp about an unrelated failure. Above it, "this
+ * grant expired" and "your clock is wrong" are the same event wearing
+ * different words, and only one of them can be acted on.
+ */
+declare const CLOCK_ATTRIBUTION_MS = 5000;
+/**
+ * The domain separator.
  *
  * Every signature in this system says what kind of statement it is before it
- * says anything else. Without that, bytes signed for one purpose verify for
- * another: a roster document and a request body are both "some bytes this key
- * signed", and a scheme that could not tell them apart would let a captured
- * roster be replayed as a request — or worse, let a control plane that signs
- * one thing be held to have signed the other.
- */
-declare const ROSTER_CONTEXT = "byollm/v1/roster";
-declare const SignedRoster: z.ZodObject<{
+ * says anything else. Without it, bytes signed for one purpose verify for
+ * another — a grant and a request are both "bytes this key signed", and a
+ * scheme that could not tell them apart would let one be replayed as the
+ * other.
+ */
+declare const GRANT_CONTEXT = "byollm/v1/grant";
+declare const SignedGrant: z.ZodObject<{
+    grantId: z.ZodString;
+    jobId: z.ZodString;
+    site: z.ZodString;
+    user: z.ZodString;
     owner: z.ZodString;
-    members: z.ZodArray<z.ZodString>;
+    purpose: z.ZodString;
+    kind: z.ZodString;
+    service: z.ZodString;
     issuedAt: z.ZodNumber;
     signature: z.ZodString;
 }, z.core.$strict>;
-type SignedRoster = z.infer<typeof SignedRoster>;
+type SignedGrant = z.infer<typeof SignedGrant>;
+/** Everything a grant says, before it is signed. */
+type GrantClaims = Omit<SignedGrant, "signature">;
+/**
+ * Every field of {@link SignedGrant} except the signature, sorted.
+ *
+ * **Derived from the schema, never written out by hand.** The unsigned-field
+ * attack is that somebody adds a field to the document, forgets to add it to
+ * the bytes, and ships a value an intermediary can rewrite without breaking
+ * any signature. A hand-maintained list is exactly the shape that fails: it
+ * does not grow when the code does, and nothing about adding a field reminds
+ * you it exists.
+ *
+ * Reading the shape closes it structurally rather than by review. A new field
+ * is signed the moment it is declared, and grant.test.ts asserts this list
+ * still covers the schema so a future zod version that hides `shape` fails
+ * loudly instead of silently signing less.
+ */
+declare const GRANT_SIGNED_FIELDS: readonly (keyof GrantClaims)[];
 /**
  * The exact bytes both sides sign and verify.
  *
- * Every field that decides what the roster *means* is in here. Leave one out
- * and it becomes something an intermediary can change without breaking the
- * signature — `owner` most of all: a roster whose owner was not signed over
- * could be lifted from one account and delivered to another's devices, and
- * every signature check would pass.
+ * JSON-encoded rather than joined with a separator, because a separator can
+ * be imitated. Newline-joining `["a", "b\nc"]` and `["a\nb", "c"]` produces
+ * identical bytes, so two different grants would share a signature — and the
+ * values here include a site id and a user id, at least one of which comes
+ * from somebody else's namespace. JSON escapes the separator it uses, so no
+ * arrangement of field values can spell a different document.
  *
- * Members are joined with NUL, which cannot appear in an id, so no arrangement
- * of member names can imitate a different membership. Joining on a comma would
- * let `["a,b"]` and `["a","b"]` sign identically.
+ * The context string leads, and the field order is the schema's own sorted
+ * keys, so the encoding is canonical without anyone maintaining a list.
  */
-declare function rosterStatement(input: {
-    owner: string;
-    members: readonly string[];
-    issuedAt: number;
-}): Uint8Array;
-/** Sign a roster with the control plane's own key. */
-declare function signRoster(keys: Pick<StoredKeys, "identityPrivate">, input: {
-    owner: string;
-    members: readonly string[];
-    issuedAt: number;
-}): SignedRoster;
-/** Why a roster was refused. Typed for logs; never returned to a caller. */
-type RosterRefusal = "bad-signature" | "wrong-owner" | "stale" | "from-the-future"
+declare function grantStatement(claims: GrantClaims): Uint8Array;
+/** Sign a grant with the control plane's own key. */
+declare function signGrant(keys: Pick<StoredKeys, "identityPrivate">, claims: GrantClaims): SignedGrant;
 /**
- * A roster arrived and this device pinned no key to check it against.
+ * Why a grant was refused.
+ *
+ * Split by remedy, because these send somebody to different places: fix your
+ * clock, take it up with the relay, or nothing at all — you are being
+ * attacked and the refusal worked.
  *
- * Not a bad signature — nothing was checked. It is the one refusal that is
- * evidence *about the pairing* rather than about the document: an upstream
- * that sends rosters has a control plane, so a device holding no key from
- * it paired before roster sync existed and can never verify one. The remedy
- * is re-pairing, and this is the only refusal here that has one.
+ * There is deliberately no `no-pinned-key` here. A device that pinned no
+ * control-plane key never reaches this function: it is in direct mode, and
+ * the question "is this grant good" does not arise. A value nothing can
+ * return is a branch every caller has to handle and no test can reach.
  */
- | "no-pinned-key";
+type GrantRefusal = 
+/** The signature does not verify against the pinned key. */
+"bad-signature"
+/** Genuine, and for a different device's owner. */
+ | "wrong-owner"
+/** Genuine, and lifted from a different job. */
+ | "wrong-job"
+/** Older than {@link GRANT_MAX_AGE_MS}. */
+ | "expired"
 /**
- * Is this roster one this device may admit people from, right now?
+ * Issued further in the future than clock drift explains.
  *
- * `owner` is passed in rather than read out of the document, for the reason
- * {@link verifyLink} takes its successor as an argument: a verifier that
- * recovered the owner from the signed bytes would accept a genuine roster
- * belonging to somebody else, and every check would pass.
+ * Checked, and not as pedantry: an `issuedAt` ahead of now extends a
+ * grant's life past the bound, which is the whole thing being enforced.
+ *
+ * Tolerant by {@link CLOCK_SKEW_WARN_MS}, because it was tolerant by
+ * nothing and that made ordinary drift a total outage — see
+ * {@link verifyGrant}.
+ */
+ | "from-the-future";
+/**
+ * Is this grant one this device may act on, right now?
  *
- * Age is checked in **both** directions. A clock far ahead is as much a
- * problem as one behind: an `issuedAt` in the future would extend a roster's
- * life past the bound, which is the whole thing being enforced.
+ * Document-level checks only. Replay, offer-consistency and the private rule
+ * need state this function does not have and are the device's to apply — see
+ * the class comment for the full list of four.
  */
-declare function verifyRoster(input: {
-    roster: SignedRoster;
+declare function verifyGrant(input: {
+    grant: SignedGrant;
     owner: string;
+    jobId: string;
     controlPlanePublic: string;
     now: number;
     maxAgeMs?: number;
-}): RosterRefusal | null;
+}): GrantRefusal | null;
 
 /**
  * Rotation — byollm_009 Amendment C.
@@ -1762,7 +1959,6 @@ declare const Capability: z.ZodObject<{
         "llm.chat": "llm.chat";
     }>;
     service: z.ZodString;
-    isDefault: z.ZodBoolean;
     backendId: z.ZodEnum<{
         ollama: "ollama";
         mlx: "mlx";
@@ -1792,7 +1988,6 @@ declare const Capability: z.ZodObject<{
     offerScope: z.ZodEnum<{
         private: "private";
         team: "team";
-        public: "public";
     }>;
 }, z.core.$strict>;
 type Capability = z.infer<typeof Capability>;
@@ -1803,7 +1998,6 @@ declare const CapabilityMatrix: z.ZodArray<z.ZodObject<{
         "llm.chat": "llm.chat";
     }>;
     service: z.ZodString;
-    isDefault: z.ZodBoolean;
     backendId: z.ZodEnum<{
         ollama: "ollama";
         mlx: "mlx";
@@ -1833,7 +2027,6 @@ declare const CapabilityMatrix: z.ZodArray<z.ZodObject<{
     offerScope: z.ZodEnum<{
         private: "private";
         team: "team";
-        public: "public";
     }>;
 }, z.core.$strict>>;
 type CapabilityMatrix = z.infer<typeof CapabilityMatrix>;
@@ -1861,11 +2054,26 @@ declare const WithheldKind: z.ZodObject<{
         offer: z.ZodEnum<{
             private: "private";
             team: "team";
-            public: "public";
         }>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 type WithheldKind = z.infer<typeof WithheldKind>;
+/**
+ * One grant, named by both halves — V1-3.
+ *
+ * A job id is chosen per site, so the lease id is the unique thing an upstream
+ * and a daemon can both point at. Anywhere a request says "this piece of work,
+ * held by me", it says it with both.
+ *
+ * Declared once because it was written out twice — `activeLeases` and
+ * `ReleaseRequest.leases` — and both needed the same `.strict()` added. Two
+ * copies of a shape are two places to forget it.
+ */
+declare const GrantRef: z.ZodObject<{
+    jobId: z.ZodString;
+    leaseId: z.ZodString;
+}, z.core.$strict>;
+type GrantRef = z.infer<typeof GrantRef>;
 /**
  * Pairing is a device-code exchange, not a pasted secret
  * ({@link MUSTS.PAIR_INTERACTIVE}). The daemon starts a pairing, shows the
@@ -1884,7 +2092,7 @@ declare const PairStartRequest: z.ZodObject<{
             linux: "linux";
             win32: "win32";
         }>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     device: z.ZodObject<{
         identity: z.ZodString;
         encryption: z.ZodString;
@@ -1896,7 +2104,6 @@ declare const PairStartRequest: z.ZodObject<{
             "llm.chat": "llm.chat";
         }>;
         service: z.ZodString;
-        isDefault: z.ZodBoolean;
         backendId: z.ZodEnum<{
             ollama: "ollama";
             mlx: "mlx";
@@ -1926,7 +2133,6 @@ declare const PairStartRequest: z.ZodObject<{
         offerScope: z.ZodEnum<{
             private: "private";
             team: "team";
-            public: "public";
         }>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -1975,7 +2181,7 @@ declare const PairRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
             linux: "linux";
             win32: "win32";
         }>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     device: z.ZodObject<{
         identity: z.ZodString;
         encryption: z.ZodString;
@@ -1987,7 +2193,6 @@ declare const PairRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
             "llm.chat": "llm.chat";
         }>;
         service: z.ZodString;
-        isDefault: z.ZodBoolean;
         backendId: z.ZodEnum<{
             ollama: "ollama";
             mlx: "mlx";
@@ -2017,7 +2222,6 @@ declare const PairRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
         offerScope: z.ZodEnum<{
             private: "private";
             team: "team";
-            public: "public";
         }>;
     }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
@@ -2035,7 +2239,6 @@ declare const ClaimRequest: z.ZodObject<{
             "llm.chat": "llm.chat";
         }>;
         service: z.ZodString;
-        isDefault: z.ZodBoolean;
         backendId: z.ZodEnum<{
             ollama: "ollama";
             mlx: "mlx";
@@ -2065,7 +2268,6 @@ declare const ClaimRequest: z.ZodObject<{
         offerScope: z.ZodEnum<{
             private: "private";
             team: "team";
-            public: "public";
         }>;
     }, z.core.$strict>>;
     max: z.ZodNumber;
@@ -2083,9 +2285,8 @@ declare const ClaimResponse: z.ZodObject<{
         audience: z.ZodEnum<{
             private: "private";
             team: "team";
-            public: "public";
         }>;
-        service: z.ZodOptional<z.ZodString>;
+        purpose: z.ZodOptional<z.ZodString>;
         sizeClass: z.ZodEnum<{
             small: "small";
             medium: "medium";
@@ -2098,7 +2299,19 @@ declare const ClaimResponse: z.ZodObject<{
             id: z.ZodString;
             runnerId: z.ZodString;
             expiresAt: z.ZodNumber;
-        }, z.core.$strip>;
+        }, z.core.$strict>;
+        grant: z.ZodOptional<z.ZodObject<{
+            grantId: z.ZodString;
+            jobId: z.ZodString;
+            site: z.ZodString;
+            user: z.ZodString;
+            owner: z.ZodString;
+            purpose: z.ZodString;
+            kind: z.ZodString;
+            service: z.ZodString;
+            issuedAt: z.ZodNumber;
+            signature: z.ZodString;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     leaseMs: z.ZodNumber;
 }, z.core.$strict>;
@@ -2113,7 +2326,6 @@ declare const HeartbeatRequest: z.ZodObject<{
             "llm.chat": "llm.chat";
         }>;
         service: z.ZodString;
-        isDefault: z.ZodBoolean;
         backendId: z.ZodEnum<{
             ollama: "ollama";
             mlx: "mlx";
@@ -2143,7 +2355,6 @@ declare const HeartbeatRequest: z.ZodObject<{
         offerScope: z.ZodEnum<{
             private: "private";
             team: "team";
-            public: "public";
         }>;
     }, z.core.$strict>>;
     withheld: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -2156,14 +2367,13 @@ declare const HeartbeatRequest: z.ZodObject<{
             offer: z.ZodEnum<{
                 private: "private";
                 team: "team";
-                public: "public";
             }>;
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
     activeLeases: z.ZodArray<z.ZodObject<{
         jobId: z.ZodString;
         leaseId: z.ZodString;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     paused: z.ZodBoolean;
 }, z.core.$strict>;
 type HeartbeatRequest = z.infer<typeof HeartbeatRequest>;
@@ -2194,12 +2404,6 @@ declare const HeartbeatResponse: z.ZodObject<{
     }, z.core.$strict>>;
     serverTime: z.ZodNumber;
     awaitingConsent: z.ZodArray<z.ZodString>;
-    roster: z.ZodOptional<z.ZodObject<{
-        owner: z.ZodString;
-        members: z.ZodArray<z.ZodString>;
-        issuedAt: z.ZodNumber;
-        signature: z.ZodString;
-    }, z.core.$strict>>;
 }, z.core.$strict>;
 type HeartbeatResponse = z.infer<typeof HeartbeatResponse>;
 /**
@@ -2254,7 +2458,7 @@ declare const ReleaseRequest: z.ZodObject<{
     leases: z.ZodArray<z.ZodObject<{
         jobId: z.ZodString;
         leaseId: z.ZodString;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     reason: z.ZodEnum<{
         refused: "refused";
         shutdown: "shutdown";
@@ -2335,4 +2539,4 @@ declare const FetchResponse: z.ZodObject<{
 }, z.core.$strict>;
 type FetchResponse = z.infer<typeof FetchResponse>;
 
-export { AUDIENCES, Audience, BACKENDS, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, GeneratePayload, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, REFUSAL_MESSAGES, RETIREMENT_WINDOW_MS, ROSTER_CONTEXT, ROSTER_MAX_AGE_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, type RosterRefusal, RunMetadata, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedRoster, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkProtocolVersion, classifyCost, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, rosterStatement, seal, signRequest, signRoster, signSiteRequest, signSuccession, signWith, sizeClassCeiling, sizeClassOf, successionStatement, verifyLink, verifyPublicIdentity, verifyRequest, verifyRoster, verifySiteRequest, verifyWith, walkSuccession };
+export { AUDIENCES, Audience, BACKENDS, BACKEND_IDS, BackendClass, BackendCost, type BackendDescriptor, type BackendId, BackendIdSchema, CLOCK_ATTRIBUTION_MS, CLOCK_SKEW_WARN_MS, Capability, CapabilityMatrix, ChatMessage, ChatPayload, ClaimRequest, ClaimResponse, ClaimedJob, ClaimedStub, DeliveredResult, ENCRYPTION_KEY_CONTEXT, ENDPOINTS, ENVELOPE_MAX_AGE_MS, ERROR_STATUS, type Endpoint, type EnvelopeContext, EnvelopeDirection, type EnvelopeFailure, FetchRequest, FetchResponse, GRANT_CONTEXT, GRANT_MAX_AGE_MS, GRANT_SIGNED_FIELDS, GeneratePayload, type GrantClaims, GrantRef, type GrantRefusal, HeartbeatRequest, HeartbeatResponse, JOB_KINDS, JobKind, JobOutcome, JobPayload, JobRefused, JobResultCanceled, JobResultError, JobResultOk, JobState, JobStub, KindedPayload, Lease, MAX_CLOCK_SKEW_MS, MAX_SUCCESSION_CHAIN, MIN_PROTOCOL_VERSION, MUSTS, MUST_IDS, Manifest, type MatchDaemon, type MatchJob, MatchRefusal, type MatchResult, type Must, type MustEnforcer, type MustId, type MustVerification, type MustVerifiedBy, OFFER_SCOPES, OfferScope, type OpenResult, PAYLOAD_LIMITS, PROTOCOL_PREFIX, PROTOCOL_VERSION, PairPollRequest, PairPollResponse, PairRequest, PairStartRequest, PairStartResponse, type PayloadFor, PublicIdentity, Purpose, REFUSAL_MESSAGES, RESERVED_PURPOSE, RETIREMENT_WINDOW_MS, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SignedGrant, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, backendName, canTransition, canonicalRequest, checkProtocolVersion, classifyCost, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, grantStatement, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signGrant, signRequest, signSiteRequest, signSuccession, signWith, singlePurposeManifest, sizeClassCeiling, sizeClassOf, successionStatement, verifyGrant, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession };