@byollm/protocol 0.1.0-alpha.44 → 0.1.0-alpha.46

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.44`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.46`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npm install @byollm/protocol@alpha`.
 >
@@ -83,7 +83,7 @@
 > packages published and `@byollm/server` did not: a Sigstore
 > transparency-log 409 on its provenance attestation. The workflow's
 > "already published" guard correctly refuses to resume a partial publish,
-> so `0.1.0-alpha.44` is that release, whole.
+> so `0.1.0-alpha.46` is that release, whole.
 >
 > If you run the Supabase adapter, `alpha.21` needs
 > `20260819010000_completed_by_lease_id.sql`: alpha.19 shipped §3.6's

package/dist/index.d.ts

@@ -659,6 +659,58 @@ declare const JobOutcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
     outcome: z.ZodLiteral<"canceled">;
 }, z.core.$strict>], "outcome">;
 type JobOutcome = z.infer<typeof JobOutcome>;
+/**
+ * Why a job can never run — byollm_016 Phase B.
+ *
+ * Every one of these is **terminal**, and that is the whole point of naming
+ * them. A job that cannot be matched used to sit queued until its deadline,
+ * which reads exactly like a job that is merely waiting for a device to come
+ * online — so an app could not tell "any moment now" from "never", and neither
+ * could the person watching a spinner. Silence must never read as pending.
+ *
+ * They are decided by whoever knows first: the site's own SDK where it can see
+ * the answer without asking, the router where matching happens, and the daemon
+ * again on arrival under the both-sides rule. All three reason from the same
+ * list rather than three private vocabularies.
+ */
+declare const RefusalReason: z.ZodEnum<{
+    "select-unavailable": "select-unavailable";
+    "default-ambiguity": "default-ambiguity";
+    "default-unusable": "default-unusable";
+}>;
+type RefusalReason = z.infer<typeof RefusalReason>;
+/**
+ * A terminal outcome nobody sealed — byollm_016 Phase B.
+ *
+ * Every other finished job carries an envelope encrypted by the device that
+ * ran it, which is what makes a result unforgeable. These have no device: the
+ * job was refused *before* anything could run it, so there is nobody to seal
+ * from and no content to seal.
+ *
+ * **What that costs, stated plainly.** This is the one terminal outcome a
+ * router can author. It is worth being exact about the power that grants,
+ * because "the relay can write this" sounds alarming until you compare it with
+ * what a relay could already do: drop the job, never offer it, and let it
+ * expire. A router-authored refusal is *denial of service by a shorter route*,
+ * which is a power the router has always had and which the trust model has
+ * always said it has. What it emphatically is **not** is forgery: this shape
+ * carries no envelope and no output, so it can never be mistaken for an answer
+ * a device produced. A relay still cannot fabricate a result, because that
+ * needs a signature it does not hold.
+ *
+ * So the rule this shape enforces by construction: a refusal may deny, and may
+ * never assert. Anything that claims work was *done* still comes sealed.
+ */
+declare const JobRefused: z.ZodObject<{
+    outcome: z.ZodLiteral<"refused">;
+    reason: z.ZodEnum<{
+        "select-unavailable": "select-unavailable";
+        "default-ambiguity": "default-ambiguity";
+        "default-unusable": "default-unusable";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>;
+type JobRefused = z.infer<typeof JobRefused>;
 /**
  * The plaintext inside a result envelope.
  *
@@ -799,6 +851,7 @@ declare const JobStub: z.ZodObject<{
         team: "team";
         public: "public";
     }>;
+    service: z.ZodOptional<z.ZodString>;
     sizeClass: z.ZodEnum<{
         small: "small";
         medium: "medium";
@@ -823,6 +876,7 @@ declare const ClaimedStub: z.ZodObject<{
         team: "team";
         public: "public";
     }>;
+    service: z.ZodOptional<z.ZodString>;
     sizeClass: z.ZodEnum<{
         small: "small";
         medium: "medium";
@@ -1398,6 +1452,27 @@ declare const MUSTS: Readonly<{
     readonly PROVENANCE_NAMES_DEVICE: Must;
     readonly INGRESS_LOGGED_BEFORE_EXECUTION: Must;
     readonly NO_SHELL_INTERPOLATION: Must;
+    /**
+     * Amended for byollm_016 Phase B, and the amendment is deliberately narrow.
+     *
+     * A site may now name a **service** on the stub. The temptation is to read
+     * that as a crack in this law, so the statement below says exactly where the
+     * line is: a name selects from a menu the owner published, and resolves to a
+     * model, backend, base URL and flags **only** through that owner's own
+     * config. The site supplies a key; the owner supplies every value it maps
+     * to. A name the owner does not advertise is refused rather than
+     * substituted, because substitution is how "you may pick from my list" turns
+     * into "you may ask for anything and get something".
+     *
+     * Two properties keep it from drifting into "sites demand models":
+     *
+     *   1. **Nothing the site sends is ever a value.** No model string, no URL,
+     *      no flag crosses the wire — only a key that means nothing off this
+     *      owner's machine.
+     *   2. **It is a stub field, never a payload field.** The prompt cannot
+     *      reach it. That is unchanged and is the sentence the second clause
+     *      below still enforces verbatim.
+     */
     readonly NO_PAYLOAD_ROUTING: Must;
     readonly STRIPPED_CHILD_ENV: Must;
     readonly HTTP_BASE_URL_SAFE: Must;
@@ -1823,6 +1898,7 @@ declare const ClaimResponse: z.ZodObject<{
             team: "team";
             public: "public";
         }>;
+        service: z.ZodOptional<z.ZodString>;
         sizeClass: z.ZodEnum<{
             small: "small";
             medium: "medium";
@@ -1986,11 +2062,11 @@ declare const ReleaseRequest: z.ZodObject<{
         leaseId: z.ZodString;
     }, z.core.$strip>>;
     reason: z.ZodEnum<{
+        refused: "refused";
         shutdown: "shutdown";
         pause: "pause";
         revoked: "revoked";
         "backend-down": "backend-down";
-        refused: "refused";
     }>;
 }, z.core.$strict>;
 type ReleaseRequest = z.infer<typeof ReleaseRequest>;
@@ -2065,4 +2141,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, 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, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, canTransition, canonicalRequest, checkProtocolVersion, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signRequest, signSiteRequest, signSuccession, signWith, sizeClassCeiling, sizeClassOf, successionStatement, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession };
+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, RefusalReason, ReleaseRequest, ReleaseResponse, RequestSignature, ResultDisposition, ResultProvenance, ResultRequest, ResultResponse, RunMetadata, SIZE_CLASS_LIMITS, SUCCESSION_CONTEXT, SUPPORTED_PROTOCOL_VERSIONS, SealedEnvelope, SealedOutcome, type SignatureFailure, SizeClass, type SpendConsent, StoredKeys, Succession, type SuccessionFailure, type SuccessionWalk, TERMINAL_STATES, type VersionRefusal, WireError, WireErrorCode, WithheldKind, backendDescriptor, canTransition, canonicalRequest, checkProtocolVersion, cryptoReady, declaredVersion, effectiveOfferScope, fingerprint, generateKeys, isBackendId, isCloudTaggedModel, isJobKind, isLocalHost, isTerminal, keyId, kindsOf, matchAudience, mustsVerifiedBy, open, payloadTextLength, provenanceFor, publicIdentityOf, resolveCost, seal, signRequest, signSiteRequest, signSuccession, signWith, sizeClassCeiling, sizeClassOf, successionStatement, verifyLink, verifyPublicIdentity, verifyRequest, verifySiteRequest, verifyWith, walkSuccession };

package/dist/index.js

@@ -466,6 +466,67 @@ var JobOutcome = z4.discriminatedUnion("outcome", [
   JobResultError,
   JobResultCanceled
 ]);
+var RefusalReason = z4.enum([
+  /**
+   * A selection this requester cannot be served — byollm_016 Phase B.
+   *
+   * **One value for two causes, and the collapse is the security property.**
+   * A named service may be unknown to this owner, or known and not offered to
+   * this requester. Those are different facts and the requester may learn
+   * neither, because telling them apart turns refusal wording into an
+   * inventory oracle: probe names, sort the answers, and enumerate a device
+   * you were never offered. The finer cause lives owner-side, where the person
+   * reading it already owns the machine — see {@link SelectionFailure}.
+   *
+   * The first draft of this enum had both causes on the wire with a comment
+   * claiming they disclosed identically. They did not; the comment described a
+   * property the code lacked, which is the more dangerous half of that mistake.
+   */
+  "select-unavailable",
+  /**
+   * Two or more services answer this kind and the owner has named no default,
+   * so the kind is withheld. Nobody may pick on the owner's behalf — the wrong
+   * guess is the metered one.
+   *
+   * Not collapsed into the value above, and the reason is that a kind is not
+   * probeable. There are two kinds; a requester asking about one is not
+   * enumerating a namespace, and learns nothing they could not learn by
+   * looking at what the device advertises. It is also already what a roster
+   * member sees on the devices page — `awaitingDefault` carries exactly this,
+   * by kind, for exactly this reason.
+   */
+  "default-ambiguity",
+  /**
+   * A default exists and this requester can never use it — byollm_016's
+   * defaults-meet-audiences corner.
+   *
+   * The specimen: an owner's default for `llm.chat` is their Claude
+   * subscription, self-locked by `SUBSCRIPTION_SELF_LOCK`. A team member's
+   * unselected job resolves to it and can never be served by it. That must be
+   * a refusal on the spot, not a wait that expires an hour later looking like
+   * nobody was online.
+   *
+   * Bounded like the value above and probeable for the same reason it is not:
+   * the requester named nothing, so there is no name space to walk.
+   */
+  "default-unusable"
+]);
+var JobRefused = z4.object({
+  outcome: z4.literal("refused"),
+  reason: RefusalReason,
+  /** Plain words for a human reading a log, never parsed. */
+  message: z4.string().min(1)
+}).strict();
+var REFUSAL_TEXT = Object.freeze({
+  "select-unavailable": "that service is not available to you on this device",
+  "default-ambiguity": "this device serves that kind from more than one service and its owner has not chosen which",
+  "default-unusable": "this device's default for that kind cannot run work for you"
+});
+var REFUSED_SELECTION = Object.freeze({
+  outcome: "refused",
+  reason: "select-unavailable",
+  message: REFUSAL_TEXT["select-unavailable"]
+});
 var SealedOutcome = z4.object({ outcome: JobOutcome, ran: RunMetadata }).strict();
 var DeliveredResult = z4.object({
   jobId: z4.string().min(1),
@@ -553,6 +614,30 @@ var JobStub = z4.object({
   // The site keeps its own copy on `JobRecord` and still filters candidates
   // with it before offering. That is server-internal, where the party
   // holding the list authored it.
+  /**
+   * Which of the owner's services should answer — byollm_016 Phase B.
+   *
+   * **A selection from a menu, never a demand.** The owner advertises named
+   * services; a site may name one of them, and that is the entire power the
+   * field grants. It carries no model, no base URL, no flags — the daemon
+   * resolves the name against its own config and nothing else, so what
+   * actually runs is still decided exclusively by the person who owns the
+   * hardware. A name that is not on that owner's menu is refused
+   * (`select-unadvertised`), never silently substituted, because a
+   * substitution is how "select" would quietly become "whatever we had".
+   *
+   * Absent means "the owner's default for this kind", which is the only
+   * behaviour Phase A had.
+   *
+   * It travels because the router matches on it, under the rule the absent
+   * `audienceAllow` above establishes: *a class the router acts on may
+   * travel; membership never does.* This is a class.
+   *
+   * It is a **stub** field and never a payload field, which is the line
+   * `NO_PAYLOAD_ROUTING` draws: the prompt cannot reach it, so no amount of
+   * user text can influence what runs.
+   */
+  service: z4.string().min(1).optional(),
   sizeClass: SizeClass,
   /** Reserved for byollm_006. False until streaming exists. */
   streaming: z4.boolean(),
@@ -1221,12 +1306,33 @@ var MUSTS = Object.freeze({
     verifiedBy: "adversarial",
     source: "byollm_004 \xA72"
   }),
+  /**
+   * Amended for byollm_016 Phase B, and the amendment is deliberately narrow.
+   *
+   * A site may now name a **service** on the stub. The temptation is to read
+   * that as a crack in this law, so the statement below says exactly where the
+   * line is: a name selects from a menu the owner published, and resolves to a
+   * model, backend, base URL and flags **only** through that owner's own
+   * config. The site supplies a key; the owner supplies every value it maps
+   * to. A name the owner does not advertise is refused rather than
+   * substituted, because substitution is how "you may pick from my list" turns
+   * into "you may ask for anything and get something".
+   *
+   * Two properties keep it from drifting into "sites demand models":
+   *
+   *   1. **Nothing the site sends is ever a value.** No model string, no URL,
+   *      no flag crosses the wire — only a key that means nothing off this
+   *      owner's machine.
+   *   2. **It is a stub field, never a payload field.** The prompt cannot
+   *      reach it. That is unchanged and is the sentence the second clause
+   *      below still enforces verbatim.
+   */
   NO_PAYLOAD_ROUTING: must({
     id: "NO_PAYLOAD_ROUTING",
-    statement: "Model, backend, base URL, and flags MUST come from owner config only; a payload MUST NOT influence any of them.",
+    statement: "Model, backend, base URL, and flags MUST come from owner config only; a payload MUST NOT influence any of them. A stub MAY name a service the owner advertises, which selects among that owner's own config entries and MUST NOT introduce any value the owner did not write; an unadvertised name MUST be refused, never substituted.",
     enforcedBy: "daemon",
     verifiedBy: "adversarial",
-    source: "byollm_004 \xA72"
+    source: "byollm_004 \xA72, amended byollm_016 \xA7Phase B"
   }),
   STRIPPED_CHILD_ENV: must({
     id: "STRIPPED_CHILD_ENV",
@@ -1967,6 +2073,7 @@ export {
   JobKind,
   JobOutcome,
   JobPayload,
+  JobRefused,
   JobResultCanceled,
   JobResultError,
   JobResultOk,
@@ -1993,6 +2100,7 @@ export {
   PublicIdentity,
   REFUSAL_MESSAGES,
   RETIREMENT_WINDOW_MS,
+  RefusalReason,
   ReleaseRequest,
   ReleaseResponse,
   RequestSignature,