npm - @byollm/control-plane - Versions diffs - 0.1.0-alpha.59 → 0.1.0-alpha.60 - Mend

@byollm/control-plane 0.1.0-alpha.59 → 0.1.0-alpha.60

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +1 -1
package/dist/index.d.ts +8 -1
package/dist/index.js +14 -3
package/dist/index.js.map +1 -1
package/dist/{store-CzDvurIM.d.ts → store-CIcrDxN3.d.ts} +28 -9
package/dist/store-contract.d.ts +1 -1
package/dist/store-contract.js +10 -10
package/dist/store-contract.js.map +1 -1
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @byollm/control-plane
-> **Alpha (`0.1.0-alpha.59`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.60`) — under active development. Don't use this yet.**
 The reference control plane: it resolves a person's mapping and authors one
 signed grant per job, against a policy store it does not own and with a key it

package/dist/index.d.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import { GrantClaims, SignedGrant, StoredKeys, ClaimedStub, CapabilityMatrix } from '@byollm/protocol';
-import { P as PolicyStore, M as Mapping, a as PolicySnapshot } from './store-CzDvurIM.js';
+import { P as PolicyStore, M as Mapping, a as PolicySnapshot } from './store-CIcrDxN3.js';
 /**
  * Whatever holds the key that grants are signed with.
@@ -119,6 +119,13 @@ type DeclineReason =
 "not-a-member"
 /** This person has not authorised this site. */
  | "not-consented"
+/**
+ * Authorised, and temporarily not routing — byollm-review 2026-08-27.
+ *
+ * Transient by the same test every reason here is judged by: the person can
+ * lift it themselves, so the job must still be waiting when they do.
+ */
+ | "consent-paused"
 /** They authorised it and left this slot empty. */
  | "unmapped"
 /** Their mapping names a service this device does not offer. */

package/dist/index.js CHANGED Viewed

@@ -3,6 +3,13 @@ import { randomUUID } from "crypto";
 import {
   RESERVED_PURPOSE
 } from "@byollm/protocol";
+var WIDENS = {
+  private: false,
+  team: true
+};
+var WIDENING_SCOPES = new Set(
+  Object.entries(WIDENS).filter(([, widens]) => widens).map(([scope]) => scope)
+);
 var ControlPlane = class {
   #store;
   #signer;
@@ -43,7 +50,8 @@ var ControlPlane = class {
     } catch {
       return decline("store-unavailable");
     }
-    if (!snapshot.consented) return decline("not-consented");
+    if (snapshot.consented === "no") return decline("not-consented");
+    if (snapshot.consented === "paused") return decline("consent-paused");
     if (job.owner !== owner && !snapshot.member) return decline("not-a-member");
     const mapped = snapshot.mappings.find(
       (mapping) => mapping.purpose === purpose && mapping.kind === job.kind
@@ -53,7 +61,7 @@ var ControlPlane = class {
       return decline("resolved-elsewhere");
     }
     const offered = input.capabilities.some(
-      (capability) => capability.kind === job.kind && capability.service === mapped.service
+      (capability) => capability.kind === job.kind && capability.service === mapped.service && (job.owner === owner || WIDENING_SCOPES.has(capability.offerScope))
     );
     if (!offered) return decline("resolved-elsewhere");
     return {
@@ -152,7 +160,10 @@ var MemoryPolicyStore = class {
     const id = key(input.siteId, input.user);
     const mappings = this.#consents.get(id);
     return Promise.resolve({
-      consented: mappings !== void 0 && !this.#paused.has(id),
+      // The three states the reference store can be in, told apart rather
+      // than collapsed: a pause is somebody's own to lift, and the engine
+      // needs to know that before it decides whether a refusal is forever.
+      consented: mappings === void 0 ? "no" : this.#paused.has(id) ? "paused" : "yes",
       member: this.#members.get(input.owner)?.has(input.user) ?? false,
       mappings: mappings ?? []
     });

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/engine.ts","../src/memory.ts","../src/signer.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n RESERVED_PURPOSE,\n type CapabilityMatrix,\n type ClaimedStub,\n type SignedGrant,\n} from \"@byollm/protocol\";\nimport type { GrantSigner } from \"./signer.js\";\nimport type { PolicyStore } from \"./store.js\";\n\n/*\n The control plane: one signed grant per job, or a reason there is none.\n \n byollm_016 Amendment J and L. This is the open engine behind a relay's\n * `authorGrant` seam. It reads policy from a {@link PolicyStore} it does not\n * own and signs with a {@link GrantSigner} whose key it never sees, so the\n * two things byollm.cloud keeps — the data and the key — sit outside it, and\n * the rule over them is readable by anybody.\n \n ## One routes, one authorises, only one signs\n \n A relay already filters what it offers a device, by consent and by\n * membership. That filter is an optimisation and this is the authority.\n * Everything is checked again here, because the relay's projection can be\n * stale and because a grant asserting \"consented, member, admitted\" must be\n * true when it is signed rather than when something upstream last looked. If\n * the two disagree, this one wins and refuses.\n /\nexport class ControlPlane {\n readonly #store: PolicyStore;\n readonly #signer: GrantSigner;\n readonly #now: () => number;\n readonly #newId: () => string;\n\n constructor(options: {\n readonly store: PolicyStore;\n readonly signer: GrantSigner;\n /* Injectable clock, so tests move time instead of sleeping. /\n readonly now?: () => number;\n /* Injectable id source, so a test can assert what was signed. /\n readonly newGrantId?: () => string;\n }) {\n this.#store = options.store;\n this.#signer = options.signer;\n this.#now = options.now ?? Date.now;\n this.#newId = options.newGrantId ?? (() => `grant_${randomUUID()}`);\n }\n\n /* The key devices pin at pairing, from the same object that signs. /\n get publicKey(): string {\n return this.#signer.publicKey;\n }\n\n /\n Author a grant for one claimed job, or decline with a reason.\n \n The order below is the law, and it is ordered by whose fact each step\n * is: the device's own owner first, then the person's consent, then their\n * membership, then their mapping, then this machine's ability to honour it.\n * A step that fails stops the rest, so the reason returned names the first\n * thing that was actually wrong rather than whichever check ran last.\n /\n async authorGrant(input: {\n readonly job: ClaimedStub;\n /* The site's id in this control plane's namespace, for the policy read. /\n readonly siteId: string;\n /\n The same site, as the key id the device pinned — the value that gets\n * signed.\n \n Two ids for one site, and both are needed: the store is keyed by the\n * control plane's own id, and the device knows sites only by what it\n * pinned. The grant carries the one the device can check without asking\n * anybody, which is the whole point of a signed document.\n /\n readonly siteKey: string;\n /* The device owner asking. /\n readonly owner: string;\n /\n Which of the site's declared purposes this job serves.\n \n Supplied by the caller rather than read off the job, because in the\n * release that built this engine the stub does not carry one yet — every\n * job is the site's {@link RESERVED_PURPOSE}. When purposes reach the\n * wire, the caller passes the job's own and nothing here changes.\n /\n readonly purpose?: string;\n /\n What this device advertised it can serve.\n \n The control plane resolves a mapping to a service *from what the\n device said*, never from a name it invented. A mapping naming\n something this device does not offer is not honoured here — see\n * `resolved-elsewhere`.\n /\n readonly capabilities: CapabilityMatrix;\n }): Promise<GrantOutcome> {\n const { job, owner } = input;\n const purpose = input.purpose ?? RESERVED_PURPOSE;\n\n let snapshot;\n try {\n snapshot = await this.#store.read({\n // The control plane's own id: the store is keyed by it, and the key\n // id below is for the device. Two ids, two readers, neither\n // substitutable for the other.\n siteId: input.siteId,\n user: job.owner,\n owner,\n });\n } catch {\n /\n A store that could not answer is not a refusal.\n \n Failing closed is right — nothing is signed — but the shape of the\n * failure matters more than it looks. A permanent refusal here would\n * mean a database blip permanently unpicked a job from a device, and\n * nothing would ever put it back. Transient, therefore, and the job\n * goes back in the queue.\n /\n return decline(\"store-unavailable\");\n }\n\n if (!snapshot.consented) return decline(\"not-consented\");\n\n /\n A device always runs its own owner's work, and no store is asked.\n \n Not an optimisation. Routing this through the store would put a law\n * somewhere an implementation could get wrong — including by answering\n * `member: false` for somebody's own account and silently stopping their\n * own device. There is no answer a store could give that should change\n * this, so it is not asked the question.\n /\n if (job.owner !== owner && !snapshot.member) return decline(\"not-a-member\");\n\n const mapped = snapshot.mappings.find(\n (mapping) => mapping.purpose === purpose && mapping.kind === job.kind,\n );\n /\n An unmapped slot makes a purpose unavailable, never a site broken.\n \n Transient, because the remedy is the user's and they may take it: a\n * mapping authored a minute from now should let this job run, and a\n * permanent refusal would have quietly excluded the one device it was\n * about to point at.\n /\n if (!mapped) return decline(\"unmapped\");\n\n /\n The device has to actually offer it, for this kind.\n \n Two different situations arrive here and this vantage cannot tell them\n * apart: the mapping resolved to a different device of this owner's, or\n * its referent is gone entirely — a service renamed or deleted. From one\n * device's capabilities both look identical, so the name says only what\n * is knowable here.\n \n Whether it is no device is a question for a sweep across the owner's\n * services, which is where the \"your mapping needs updating\" notification\n * belongs — not on the claim path, which sees one machine at a time.\n /\n /\n Whose machine, before which service.\n \n A service id means something only inside its owner's namespace, so a\n * mapping naming a teammate's `qwen` must not be satisfied by a different\n * teammate's `qwen` — or by the mapper's own. Checked before the\n * capability list, because a device that merely shares a name is not\n * \"the wrong service\" but the wrong machine, and the capabilities of the\n * wrong machine say nothing either way.\n /\n if ((mapped.owner ?? job.owner) !== owner) {\n return decline(\"resolved-elsewhere\");\n }\n\n const offered = input.capabilities.some(\n (capability) =>\n capability.kind === job.kind && capability.service === mapped.service,\n );\n if (!offered) return decline(\"resolved-elsewhere\");\n\n return {\n granted: await this.#signer.sign({\n grantId: this.#newId(),\n jobId: job.id,\n site: input.siteKey,\n user: job.owner,\n owner,\n purpose,\n kind: job.kind,\n service: mapped.service,\n issuedAt: this.#now(),\n }),\n };\n }\n}\n\n/\n Why no grant was authored — and, load-bearing, whether that is forever.\n \n The distinction exists because a relay releases a declined job, and a\n * release can carry `refused`, which means never offer this job to this\n device again. Getting that wrong in the permissive direction is a\n claim-refuse loop; getting it wrong in the strict direction is a job that\n * can never reach the machine it was always meant for, and no error anywhere.\n /\nexport type DeclineReason =\n /* This person may not use this owner's devices. /\n \| \"not-a-member\"\n /* This person has not authorised this site. /\n \| \"not-consented\"\n /* They authorised it and left this slot empty. /\n \| \"unmapped\"\n /* Their mapping names a service this device does not offer. /\n \| \"resolved-elsewhere\"\n /* The policy store could not answer. Says nothing about the job. /\n \| \"store-unavailable\";\n\nexport interface Decline {\n readonly reason: DeclineReason;\n /\n Never offer this job to this device again.\n \n True only for the two facts that a queued job cannot outlive: a person\n * removed from a team, and consent withdrawn. Hole 1 ruled that removal\n * stops future claims including queued ones, and this is where that is\n * enforced.\n \n Everything else is a state the user can change, or a fault of ours. A\n * permanent mark on those would outlive the condition that caused it.\n /\n readonly permanent: boolean;\n}\n\nexport type GrantOutcome =\n \| { readonly granted: SignedGrant; readonly declined?: undefined }\n \| { readonly granted?: undefined; readonly declined: Decline };\n\nconst PERMANENT: ReadonlySet<DeclineReason> = new Set([\n \"not-a-member\",\n \"not-consented\",\n]);\n\nfunction decline(reason: DeclineReason): GrantOutcome {\n return { declined: { reason, permanent: PERMANENT.has(reason) } };\n}\n","import type { Mapping, PolicySnapshot, PolicyStore } from \"./store.js\";\n\n/\n A policy store in a `Map`, for tests and for a single-process self-hoster.\n \n It is the reference implementation in the sense that matters: the contract\n * suite runs against it, so it is the thing anybody else's store is compared\n * to. It is not a suggestion about how to build one — a real store is a\n * database, and this one forgets everything when the process ends.\n /\nexport class MemoryPolicyStore implements PolicyStore {\n /* (siteId, user) to what that person authorised for that site. /\n readonly #consents = new Map<string, Mapping[]>();\n /* (siteId, user) pairs whose owner has paused them. /\n readonly #paused = new Set<string>();\n /* owner to the people who may use their devices. /\n readonly #members = new Map<string, Set<string>>();\n\n /\n Record a consent, with the mapping it carries.\n \n One call because they are one act: the mapping is the consent\n * (Amendment L), and a store that let them be written separately would\n * allow a state — consented, no mappings, no way to have got there — that\n * the product cannot produce.\n \n Consenting with an empty list is the real signup state, though: a person\n * whose slots all had two candidates and who has not chosen yet.\n /\n consent(input: {\n siteId: string;\n user: string;\n mappings?: readonly Mapping[];\n }): void {\n this.#consents.set(key(input.siteId, input.user), [\n ...(input.mappings ?? []),\n ]);\n this.#paused.delete(key(input.siteId, input.user));\n }\n\n /\n Pause a consent without withdrawing it.\n \n A real product state and not the same as revoking: the mapping survives,\n * so resuming does not ask somebody to author their choices again. What it\n * must not do is let work through — a relay's projection can lag by\n * seconds, and a grant authored in that window would run work whose owner\n * had just stopped it.\n /\n pause(input: { siteId: string; user: string }): void {\n this.#paused.add(key(input.siteId, input.user));\n }\n\n /* Let it move again. /\n resume(input: { siteId: string; user: string }): void {\n this.#paused.delete(key(input.siteId, input.user));\n }\n\n /\n Withdraw consent, which deletes the mapping with it.\n \n Not two operations. \"Revoking consent deletes the mapping — the mapping\n * is the consent, so un-consenting unmaps\" (hole 2), and a store that could\n * leave one behind would leave a resolution pointing at a service the\n * person no longer authorises anybody to reach.\n /\n revoke(input: { siteId: string; user: string }): void {\n this.#consents.delete(key(input.siteId, input.user));\n this.#paused.delete(key(input.siteId, input.user));\n }\n\n /* Add somebody to an owner's team. /\n addMember(input: { owner: string; user: string }): void {\n const members = this.#members.get(input.owner) ?? new Set<string>();\n members.add(input.user);\n this.#members.set(input.owner, members);\n }\n\n /\n Remove somebody from an owner's team.\n \n There is no \"blocked but still a member\": a team is access to its\n * owner's devices and nothing else, so member-but-blocked is not a deferred\n * feature, it is an empty state (Amendment J).\n /\n removeMember(input: { owner: string; user: string }): void {\n this.#members.get(input.owner)?.delete(input.user);\n }\n\n read(input: {\n siteId: string;\n user: string;\n owner: string;\n }): Promise<PolicySnapshot> {\n const id = key(input.siteId, input.user);\n const mappings = this.#consents.get(id);\n return Promise.resolve({\n consented: mappings !== undefined && !this.#paused.has(id),\n member: this.#members.get(input.owner)?.has(input.user) ?? false,\n mappings: mappings ?? [],\n });\n }\n}\n\n/\n NUL-joined, for the reason `routeKey` is.\n \n A composite key is a parser waiting to meet an id containing its separator.\n * NUL cannot appear in either half, so no arrangement of a site id and a user\n * id can spell a different pair.\n /\nconst key = (siteId: string, user: string): string => `${siteId}\\u0000${user}`;\n","import {\n signGrant,\n type GrantClaims,\n type SignedGrant,\n type StoredKeys,\n} from \"@byollm/protocol\";\n\n/\n Whatever holds the key that grants are signed with.\n \n A function rather than a key, so custody never enters this package. A\n * self-hoster hands over a keypair; a hosted deployment can put the private\n * half behind a KMS and pass a signer that calls it, and the engine cannot\n * tell the difference — which is the point. Custody of the signing key is one\n * of the two things byollm.cloud keeps, and an engine that had to be given\n * the key could not be run any other way.\n \n `publicKey` sits on the same object deliberately. It is the value a relay\n * hands a device at pairing, and it is the value that must verify what\n * `sign` produces. Two separate configuration items would be two things a\n * deployment could set inconsistently — and the failure mode is a fleet that\n * refuses every job while every process reports itself healthy.\n /\nexport interface GrantSigner {\n /* The public half, for a relay to hand devices at pairing. /\n readonly publicKey: string;\n sign(claims: GrantClaims): Promise<SignedGrant> \| SignedGrant;\n}\n\n/\n Sign with a keypair this process holds.\n \n The implementation a self-hoster wants, and the one the tests use. A hosted\n * deployment writes its own against whatever holds its key.\n */\nexport function keypairSigner(\n keys: Pick<StoredKeys, \"identityPrivate\" \| \"identityPublic\">,\n): GrantSigner {\n return {\n publicKey: keys.identityPublic,\n sign: (claims) => signGrant(keys, claims),\n };\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/engine.ts","../src/memory.ts","../src/signer.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n RESERVED_PURPOSE,\n type CapabilityMatrix,\n type ClaimedStub,\n type OfferScope,\n type SignedGrant,\n} from \"@byollm/protocol\";\nimport type { GrantSigner } from \"./signer.js\";\nimport type { PolicyStore } from \"./store.js\";\n\n/*\n Which offer scopes reach somebody other than the owner.\n \n An allowlist, never a denylist. A filter written against the excluded case\n * fails open the moment somebody renames the excluded value — which is\n * exactly what happened when `self` became `private` and every owner-locked\n * route was listed to a whole team. A scope this build has not been taught\n * stays narrow.\n \n Exhaustive over the protocol's vocabulary, so a scope added upstream fails\n * this file to compile until somebody decides whether it widens.\n /\nconst WIDENS: Readonly<Record<OfferScope, boolean>> = {\n private: false,\n team: true,\n};\nconst WIDENING_SCOPES: ReadonlySet<string> = new Set(\n Object.entries(WIDENS)\n .filter(([, widens]) => widens)\n .map(([scope]) => scope),\n);\n\n/\n The control plane: one signed grant per job, or a reason there is none.\n \n byollm_016 Amendment J and L. This is the open engine behind a relay's\n * `authorGrant` seam. It reads policy from a {@link PolicyStore} it does not\n * own and signs with a {@link GrantSigner} whose key it never sees, so the\n * two things byollm.cloud keeps — the data and the key — sit outside it, and\n * the rule over them is readable by anybody.\n \n ## One routes, one authorises, only one signs\n \n A relay already filters what it offers a device, by consent and by\n * membership. That filter is an optimisation and this is the authority.\n * Everything is checked again here, because the relay's projection can be\n * stale and because a grant asserting \"consented, member, admitted\" must be\n * true when it is signed rather than when something upstream last looked. If\n * the two disagree, this one wins and refuses.\n /\nexport class ControlPlane {\n readonly #store: PolicyStore;\n readonly #signer: GrantSigner;\n readonly #now: () => number;\n readonly #newId: () => string;\n\n constructor(options: {\n readonly store: PolicyStore;\n readonly signer: GrantSigner;\n /* Injectable clock, so tests move time instead of sleeping. /\n readonly now?: () => number;\n /* Injectable id source, so a test can assert what was signed. /\n readonly newGrantId?: () => string;\n }) {\n this.#store = options.store;\n this.#signer = options.signer;\n this.#now = options.now ?? Date.now;\n this.#newId = options.newGrantId ?? (() => `grant_${randomUUID()}`);\n }\n\n /* The key devices pin at pairing, from the same object that signs. /\n get publicKey(): string {\n return this.#signer.publicKey;\n }\n\n /\n Author a grant for one claimed job, or decline with a reason.\n \n The order below is the law, and it is ordered by whose fact each step\n * is: the device's own owner first, then the person's consent, then their\n * membership, then their mapping, then this machine's ability to honour it.\n * A step that fails stops the rest, so the reason returned names the first\n * thing that was actually wrong rather than whichever check ran last.\n /\n async authorGrant(input: {\n readonly job: ClaimedStub;\n /* The site's id in this control plane's namespace, for the policy read. /\n readonly siteId: string;\n /\n The same site, as the key id the device pinned — the value that gets\n * signed.\n \n Two ids for one site, and both are needed: the store is keyed by the\n * control plane's own id, and the device knows sites only by what it\n * pinned. The grant carries the one the device can check without asking\n * anybody, which is the whole point of a signed document.\n /\n readonly siteKey: string;\n /* The device owner asking. /\n readonly owner: string;\n /\n Which of the site's declared purposes this job serves.\n \n Supplied by the caller rather than read off the job, because in the\n * release that built this engine the stub does not carry one yet — every\n * job is the site's {@link RESERVED_PURPOSE}. When purposes reach the\n * wire, the caller passes the job's own and nothing here changes.\n /\n readonly purpose?: string;\n /\n What this device advertised it can serve.\n \n The control plane resolves a mapping to a service *from what the\n device said*, never from a name it invented. A mapping naming\n something this device does not offer is not honoured here — see\n * `resolved-elsewhere`.\n /\n readonly capabilities: CapabilityMatrix;\n }): Promise<GrantOutcome> {\n const { job, owner } = input;\n const purpose = input.purpose ?? RESERVED_PURPOSE;\n\n let snapshot;\n try {\n snapshot = await this.#store.read({\n // The control plane's own id: the store is keyed by it, and the key\n // id below is for the device. Two ids, two readers, neither\n // substitutable for the other.\n siteId: input.siteId,\n user: job.owner,\n owner,\n });\n } catch {\n /\n A store that could not answer is not a refusal.\n \n Failing closed is right — nothing is signed — but the shape of the\n * failure matters more than it looks. A permanent refusal here would\n * mean a database blip permanently unpicked a job from a device, and\n * nothing would ever put it back. Transient, therefore, and the job\n * goes back in the queue.\n /\n return decline(\"store-unavailable\");\n }\n\n /\n Refused, or asked again later — and the difference is the whole point.\n \n `not-consented` is permanent: never offer this job to this device\n * again. That is right for revoked and for never-authorised, because\n * somebody decided it and a queued job cannot outlive the decision.\n \n A pause is not a decision of that kind. The hosted product pauses a\n * consent the moment its author joins a team — no row changes — and the\n * remedy is theirs: read the sentence they have not read. Marking those\n * jobs permanently refused meant that by the time they re-consented,\n * every device that had claimed during the window would never offer them\n * again, and nothing anywhere said so.\n /\n if (snapshot.consented === \"no\") return decline(\"not-consented\");\n if (snapshot.consented === \"paused\") return decline(\"consent-paused\");\n\n /\n A device always runs its own owner's work, and no store is asked.\n \n Not an optimisation. Routing this through the store would put a law\n * somewhere an implementation could get wrong — including by answering\n * `member: false` for somebody's own account and silently stopping their\n * own device. There is no answer a store could give that should change\n * this, so it is not asked the question.\n /\n if (job.owner !== owner && !snapshot.member) return decline(\"not-a-member\");\n\n const mapped = snapshot.mappings.find(\n (mapping) => mapping.purpose === purpose && mapping.kind === job.kind,\n );\n /\n An unmapped slot makes a purpose unavailable, never a site broken.\n \n Transient, because the remedy is the user's and they may take it: a\n * mapping authored a minute from now should let this job run, and a\n * permanent refusal would have quietly excluded the one device it was\n * about to point at.\n /\n if (!mapped) return decline(\"unmapped\");\n\n /\n The device has to actually offer it, for this kind.\n \n Two different situations arrive here and this vantage cannot tell them\n * apart: the mapping resolved to a different device of this owner's, or\n * its referent is gone entirely — a service renamed or deleted. From one\n * device's capabilities both look identical, so the name says only what\n * is knowable here.\n \n Whether it is no device is a question for a sweep across the owner's\n * services, which is where the \"your mapping needs updating\" notification\n * belongs — not on the claim path, which sees one machine at a time.\n /\n /\n Whose machine, before which service.\n \n A service id means something only inside its owner's namespace, so a\n * mapping naming a teammate's `qwen` must not be satisfied by a different\n * teammate's `qwen` — or by the mapper's own. Checked before the\n * capability list, because a device that merely shares a name is not\n * \"the wrong service\" but the wrong machine, and the capabilities of the\n * wrong machine say nothing either way.\n /\n if ((mapped.owner ?? job.owner) !== owner) {\n return decline(\"resolved-elsewhere\");\n }\n\n /\n Offered to this person, not merely present on the machine.\n \n byollm-review 2026-08-27. This asked only whether a capability row with\n * that kind and service existed, and every row carries an `offerScope` it\n * never looked at. So a mapping naming a service its owner has since\n * narrowed to `private` was granted: the engine signed a document\n * asserting a teammate's admission onto a service offered to nobody.\n \n Nothing widened — the device's private-is-absolute check is structural\n * and refuses it. But the shape of the failure was wrong, and that is\n * the real defect. A device's refusal releases the job as `refused`,\n * which the upstream remembers permanently; the engine declining\n * `resolved-elsewhere` is a thirty-second wait. So an owner flipping\n * `qwen` to private for a minute permanently unpicked a teammate's queued\n * job from the one device it was always meant for, with nothing anywhere\n * reporting why — precisely what the transient-decline machinery exists\n * to prevent.\n \n The owner's own work is exempt structurally rather than by scope: a\n * device always runs its owner's jobs, `private` is a statement about\n * other people, and consulting the scope here would let the narrowest\n * setting stop somebody's own machine from serving them.\n /\n const offered = input.capabilities.some(\n (capability) =>\n capability.kind === job.kind &&\n capability.service === mapped.service &&\n (job.owner === owner \|\| WIDENING_SCOPES.has(capability.offerScope)),\n );\n if (!offered) return decline(\"resolved-elsewhere\");\n\n return {\n granted: await this.#signer.sign({\n grantId: this.#newId(),\n jobId: job.id,\n site: input.siteKey,\n user: job.owner,\n owner,\n purpose,\n kind: job.kind,\n service: mapped.service,\n issuedAt: this.#now(),\n }),\n };\n }\n}\n\n/\n Why no grant was authored — and, load-bearing, whether that is forever.\n \n The distinction exists because a relay releases a declined job, and a\n * release can carry `refused`, which means never offer this job to this\n device again. Getting that wrong in the permissive direction is a\n claim-refuse loop; getting it wrong in the strict direction is a job that\n * can never reach the machine it was always meant for, and no error anywhere.\n /\nexport type DeclineReason =\n /* This person may not use this owner's devices. /\n \| \"not-a-member\"\n /* This person has not authorised this site. /\n \| \"not-consented\"\n /\n Authorised, and temporarily not routing — byollm-review 2026-08-27.\n \n Transient by the same test every reason here is judged by: the person can\n * lift it themselves, so the job must still be waiting when they do.\n /\n \| \"consent-paused\"\n /* They authorised it and left this slot empty. /\n \| \"unmapped\"\n /* Their mapping names a service this device does not offer. /\n \| \"resolved-elsewhere\"\n /* The policy store could not answer. Says nothing about the job. /\n \| \"store-unavailable\";\n\nexport interface Decline {\n readonly reason: DeclineReason;\n /\n Never offer this job to this device again.\n \n True only for the two facts that a queued job cannot outlive: a person\n * removed from a team, and consent withdrawn. Hole 1 ruled that removal\n * stops future claims including queued ones, and this is where that is\n * enforced.\n \n Everything else is a state the user can change, or a fault of ours. A\n * permanent mark on those would outlive the condition that caused it.\n /\n readonly permanent: boolean;\n}\n\nexport type GrantOutcome =\n \| { readonly granted: SignedGrant; readonly declined?: undefined }\n \| { readonly granted?: undefined; readonly declined: Decline };\n\nconst PERMANENT: ReadonlySet<DeclineReason> = new Set([\n \"not-a-member\",\n \"not-consented\",\n]);\n\nfunction decline(reason: DeclineReason): GrantOutcome {\n return { declined: { reason, permanent: PERMANENT.has(reason) } };\n}\n","import type { Mapping, PolicySnapshot, PolicyStore } from \"./store.js\";\n\n/\n A policy store in a `Map`, for tests and for a single-process self-hoster.\n \n It is the reference implementation in the sense that matters: the contract\n * suite runs against it, so it is the thing anybody else's store is compared\n * to. It is not a suggestion about how to build one — a real store is a\n * database, and this one forgets everything when the process ends.\n /\nexport class MemoryPolicyStore implements PolicyStore {\n /* (siteId, user) to what that person authorised for that site. /\n readonly #consents = new Map<string, Mapping[]>();\n /* (siteId, user) pairs whose owner has paused them. /\n readonly #paused = new Set<string>();\n /* owner to the people who may use their devices. /\n readonly #members = new Map<string, Set<string>>();\n\n /\n Record a consent, with the mapping it carries.\n \n One call because they are one act: the mapping is the consent\n * (Amendment L), and a store that let them be written separately would\n * allow a state — consented, no mappings, no way to have got there — that\n * the product cannot produce.\n \n Consenting with an empty list is the real signup state, though: a person\n * whose slots all had two candidates and who has not chosen yet.\n /\n consent(input: {\n siteId: string;\n user: string;\n mappings?: readonly Mapping[];\n }): void {\n this.#consents.set(key(input.siteId, input.user), [\n ...(input.mappings ?? []),\n ]);\n this.#paused.delete(key(input.siteId, input.user));\n }\n\n /\n Pause a consent without withdrawing it.\n \n A real product state and not the same as revoking: the mapping survives,\n * so resuming does not ask somebody to author their choices again. What it\n * must not do is let work through — a relay's projection can lag by\n * seconds, and a grant authored in that window would run work whose owner\n * had just stopped it.\n /\n pause(input: { siteId: string; user: string }): void {\n this.#paused.add(key(input.siteId, input.user));\n }\n\n /* Let it move again. /\n resume(input: { siteId: string; user: string }): void {\n this.#paused.delete(key(input.siteId, input.user));\n }\n\n /\n Withdraw consent, which deletes the mapping with it.\n \n Not two operations. \"Revoking consent deletes the mapping — the mapping\n * is the consent, so un-consenting unmaps\" (hole 2), and a store that could\n * leave one behind would leave a resolution pointing at a service the\n * person no longer authorises anybody to reach.\n /\n revoke(input: { siteId: string; user: string }): void {\n this.#consents.delete(key(input.siteId, input.user));\n this.#paused.delete(key(input.siteId, input.user));\n }\n\n /* Add somebody to an owner's team. /\n addMember(input: { owner: string; user: string }): void {\n const members = this.#members.get(input.owner) ?? new Set<string>();\n members.add(input.user);\n this.#members.set(input.owner, members);\n }\n\n /\n Remove somebody from an owner's team.\n \n There is no \"blocked but still a member\": a team is access to its\n * owner's devices and nothing else, so member-but-blocked is not a deferred\n * feature, it is an empty state (Amendment J).\n /\n removeMember(input: { owner: string; user: string }): void {\n this.#members.get(input.owner)?.delete(input.user);\n }\n\n read(input: {\n siteId: string;\n user: string;\n owner: string;\n }): Promise<PolicySnapshot> {\n const id = key(input.siteId, input.user);\n const mappings = this.#consents.get(id);\n return Promise.resolve({\n // The three states the reference store can be in, told apart rather\n // than collapsed: a pause is somebody's own to lift, and the engine\n // needs to know that before it decides whether a refusal is forever.\n consented:\n mappings === undefined ? \"no\" : this.#paused.has(id) ? \"paused\" : \"yes\",\n member: this.#members.get(input.owner)?.has(input.user) ?? false,\n mappings: mappings ?? [],\n });\n }\n}\n\n/\n NUL-joined, for the reason `routeKey` is.\n \n A composite key is a parser waiting to meet an id containing its separator.\n * NUL cannot appear in either half, so no arrangement of a site id and a user\n * id can spell a different pair.\n /\nconst key = (siteId: string, user: string): string => `${siteId}\\u0000${user}`;\n","import {\n signGrant,\n type GrantClaims,\n type SignedGrant,\n type StoredKeys,\n} from \"@byollm/protocol\";\n\n/\n Whatever holds the key that grants are signed with.\n \n A function rather than a key, so custody never enters this package. A\n * self-hoster hands over a keypair; a hosted deployment can put the private\n * half behind a KMS and pass a signer that calls it, and the engine cannot\n * tell the difference — which is the point. Custody of the signing key is one\n * of the two things byollm.cloud keeps, and an engine that had to be given\n * the key could not be run any other way.\n \n `publicKey` sits on the same object deliberately. It is the value a relay\n * hands a device at pairing, and it is the value that must verify what\n * `sign` produces. Two separate configuration items would be two things a\n * deployment could set inconsistently — and the failure mode is a fleet that\n * refuses every job while every process reports itself healthy.\n /\nexport interface GrantSigner {\n /* The public half, for a relay to hand devices at pairing. /\n readonly publicKey: string;\n sign(claims: GrantClaims): Promise<SignedGrant> \| SignedGrant;\n}\n\n/\n Sign with a keypair this process holds.\n \n The implementation a self-hoster wants, and the one the tests use. A hosted\n * deployment writes its own against whatever holds its key.\n */\nexport function keypairSigner(\n keys: Pick<StoredKeys, \"identityPrivate\" \| \"identityPublic\">,\n): GrantSigner {\n return {\n publicKey: keys.identityPublic,\n sign: (claims) => signGrant(keys, claims),\n };\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAC3B;AAAA,EACE;AAAA,OAKK;AAgBP,IAAM,SAAgD;AAAA,EACpD,SAAS;AAAA,EACT,MAAM;AACR;AACA,IAAM,kBAAuC,IAAI;AAAA,EAC/C,OAAO,QAAQ,MAAM,EAClB,OAAO,CAAC,CAAC,EAAE,MAAM,MAAM,MAAM,EAC7B,IAAI,CAAC,CAAC,KAAK,MAAM,KAAK;AAC3B;AAoBO,IAAM,eAAN,MAAmB;AAAA,EACf;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,SAOT;AACD,SAAK,SAAS,QAAQ;AACtB,SAAK,UAAU,QAAQ;AACvB,SAAK,OAAO,QAAQ,OAAO,KAAK;AAChC,SAAK,SAAS,QAAQ,eAAe,MAAM,SAAS,WAAW,CAAC;AAAA,EAClE;AAAA;AAAA,EAGA,IAAI,YAAoB;AACtB,WAAO,KAAK,QAAQ;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,YAAY,OAkCQ;AACxB,UAAM,EAAE,KAAK,MAAM,IAAI;AACvB,UAAM,UAAU,MAAM,WAAW;AAEjC,QAAI;AACJ,QAAI;AACF,iBAAW,MAAM,KAAK,OAAO,KAAK;AAAA;AAAA;AAAA;AAAA,QAIhC,QAAQ,MAAM;AAAA,QACd,MAAM,IAAI;AAAA,QACV;AAAA,MACF,CAAC;AAAA,IACH,QAAQ;AAUN,aAAO,QAAQ,mBAAmB;AAAA,IACpC;AAgBA,QAAI,SAAS,cAAc,KAAM,QAAO,QAAQ,eAAe;AAC/D,QAAI,SAAS,cAAc,SAAU,QAAO,QAAQ,gBAAgB;AAWpE,QAAI,IAAI,UAAU,SAAS,CAAC,SAAS,OAAQ,QAAO,QAAQ,cAAc;AAE1E,UAAM,SAAS,SAAS,SAAS;AAAA,MAC/B,CAAC,YAAY,QAAQ,YAAY,WAAW,QAAQ,SAAS,IAAI;AAAA,IACnE;AASA,QAAI,CAAC,OAAQ,QAAO,QAAQ,UAAU;AAyBtC,SAAK,OAAO,SAAS,IAAI,WAAW,OAAO;AACzC,aAAO,QAAQ,oBAAoB;AAAA,IACrC;AA0BA,UAAM,UAAU,MAAM,aAAa;AAAA,MACjC,CAAC,eACC,WAAW,SAAS,IAAI,QACxB,WAAW,YAAY,OAAO,YAC7B,IAAI,UAAU,SAAS,gBAAgB,IAAI,WAAW,UAAU;AAAA,IACrE;AACA,QAAI,CAAC,QAAS,QAAO,QAAQ,oBAAoB;AAEjD,WAAO;AAAA,MACL,SAAS,MAAM,KAAK,QAAQ,KAAK;AAAA,QAC/B,SAAS,KAAK,OAAO;AAAA,QACrB,OAAO,IAAI;AAAA,QACX,MAAM,MAAM;AAAA,QACZ,MAAM,IAAI;AAAA,QACV;AAAA,QACA;AAAA,QACA,MAAM,IAAI;AAAA,QACV,SAAS,OAAO;AAAA,QAChB,UAAU,KAAK,KAAK;AAAA,MACtB,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAkDA,IAAM,YAAwC,oBAAI,IAAI;AAAA,EACpD;AAAA,EACA;AACF,CAAC;AAED,SAAS,QAAQ,QAAqC;AACpD,SAAO,EAAE,UAAU,EAAE,QAAQ,WAAW,UAAU,IAAI,MAAM,EAAE,EAAE;AAClE;;;ACnTO,IAAM,oBAAN,MAA+C;AAAA;AAAA,EAE3C,YAAY,oBAAI,IAAuB;AAAA;AAAA,EAEvC,UAAU,oBAAI,IAAY;AAAA;AAAA,EAE1B,WAAW,oBAAI,IAAyB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAajD,QAAQ,OAIC;AACP,SAAK,UAAU,IAAI,IAAI,MAAM,QAAQ,MAAM,IAAI,GAAG;AAAA,MAChD,GAAI,MAAM,YAAY,CAAC;AAAA,IACzB,CAAC;AACD,SAAK,QAAQ,OAAO,IAAI,MAAM,QAAQ,MAAM,IAAI,CAAC;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,OAA+C;AACnD,SAAK,QAAQ,IAAI,IAAI,MAAM,QAAQ,MAAM,IAAI,CAAC;AAAA,EAChD;AAAA;AAAA,EAGA,OAAO,OAA+C;AACpD,SAAK,QAAQ,OAAO,IAAI,MAAM,QAAQ,MAAM,IAAI,CAAC;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,OAAO,OAA+C;AACpD,SAAK,UAAU,OAAO,IAAI,MAAM,QAAQ,MAAM,IAAI,CAAC;AACnD,SAAK,QAAQ,OAAO,IAAI,MAAM,QAAQ,MAAM,IAAI,CAAC;AAAA,EACnD;AAAA;AAAA,EAGA,UAAU,OAA8C;AACtD,UAAM,UAAU,KAAK,SAAS,IAAI,MAAM,KAAK,KAAK,oBAAI,IAAY;AAClE,YAAQ,IAAI,MAAM,IAAI;AACtB,SAAK,SAAS,IAAI,MAAM,OAAO,OAAO;AAAA,EACxC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,aAAa,OAA8C;AACzD,SAAK,SAAS,IAAI,MAAM,KAAK,GAAG,OAAO,MAAM,IAAI;AAAA,EACnD;AAAA,EAEA,KAAK,OAIuB;AAC1B,UAAM,KAAK,IAAI,MAAM,QAAQ,MAAM,IAAI;AACvC,UAAM,WAAW,KAAK,UAAU,IAAI,EAAE;AACtC,WAAO,QAAQ,QAAQ;AAAA;AAAA;AAAA;AAAA,MAIrB,WACE,aAAa,SAAY,OAAO,KAAK,QAAQ,IAAI,EAAE,IAAI,WAAW;AAAA,MACpE,QAAQ,KAAK,SAAS,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,KAAK;AAAA,MAC3D,UAAU,YAAY,CAAC;AAAA,IACzB,CAAC;AAAA,EACH;AACF;AASA,IAAM,MAAM,CAAC,QAAgB,SAAyB,GAAG,MAAM,KAAS,IAAI;;;ACnH5E;AAAA,EACE;AAAA,OAIK;AA8BA,SAAS,cACd,MACa;AACb,SAAO;AAAA,IACL,WAAW,KAAK;AAAA,IAChB,MAAM,CAAC,WAAW,UAAU,MAAM,MAAM;AAAA,EAC1C;AACF;","names":[]}

package/dist/{store-CzDvurIM.d.ts → store-CIcrDxN3.d.ts} RENAMED Viewed

@@ -67,21 +67,40 @@ interface Mapping {
  */
 interface PolicySnapshot {
     /**
-     * May this user's work move for this site **right now**?
+     * May this user's work move for this site **right now**, and if not, is
+     * that reversible?
      *
-     * Three states collapse into this one boolean, and the collapse is
-     * deliberate: never authorised, authorised then revoked, and authorised but
-     * *paused* are different things to a person and the same thing to a grant.
-     * A store must report a paused consent as `false` — a relay's projection
-     * can be a few seconds behind, and a grant authored in that window would
-     * run work its owner had just stopped.
+     * This was a boolean, and the collapse was defended: never authorised,
+     * revoked, and *paused* are different to a person and identical to a grant.
+     * True of the grant, and the engine does not only decide grant-or-not — it
+     * decides whether the refusal is **permanent**, and the three states are
+     * emphatically not identical there.
+     *
+     * byollm-review 2026-08-27. `decline("not-consented")` is in the permanent
+     * set, and the relay releases a permanent decline as `refused`: never offer
+     * this job to this device again. A pause is the hosted product's own
+     * everyday path — a consent auto-pauses the moment its author joins a team,
+     * with no row changing — so somebody's queued work was permanently unpicked
+     * from every device that claimed during the window, and re-consenting
+     * minutes later did not bring it back. The engine's own law, stated two
+     * lines above its permanence table: a permanent mark must not outlive the
+     * condition that caused it.
+     *
+     * So the states that differ in remedy are told apart:
+     *
+     * - `"yes"` — authorised, and nothing is in the way.
+     * - `"paused"` — authorised, and temporarily not routing. The person can
+     *   lift it themselves by reading the sentence they have not read; the job
+     *   must still be there when they do.
+     * - `"no"` — never authorised, or revoked. Somebody decided this, and a
+     *   queued job cannot outlive that decision.
      *
      * Distinct from having mappings, which is a different real state: a person
      * can consent and leave a slot unmapped, because it had two candidates and
      * they have not chosen. "Not authorised" and "authorised, this slot empty"
      * send them to different places, so the engine is told which.
      */
-    readonly consented: boolean;
+    readonly consented: "yes" | "paused" | "no";
     /**
      * May this user's work run on this owner's devices?
      *
@@ -103,7 +122,7 @@ interface PolicyStore {
      * device. The engine short-circuits it; this method is only ever asked
      * about other people.
      *
-     * Returning a snapshot with `consented: false` is the ordinary answer for a
+     * Returning a snapshot with `consented: "no"` is the ordinary answer for a
      * site this user has never authorised. Throwing is for a store that could
      * not answer, which is a different thing and must not be turned into a
      * refusal — see the engine's failure handling.

package/dist/store-contract.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { P as PolicyStore, M as Mapping } from './store-CzDvurIM.js';
+import { P as PolicyStore, M as Mapping } from './store-CIcrDxN3.js';
 /**
  * The policy store's behaviour, written once and run against every

package/dist/store-contract.js CHANGED Viewed

@@ -18,7 +18,7 @@ function describePolicyStoreContract(name, options) {
         user: USER,
         owner: OWNER
       });
-      expect(snapshot.consented).toBe(false);
+      expect(snapshot.consented).toBe("no");
       expect(snapshot.mappings).toEqual([]);
       await done();
     });
@@ -30,7 +30,7 @@ function describePolicyStoreContract(name, options) {
         user: USER,
         owner: OWNER
       });
-      expect(snapshot.consented).toBe(true);
+      expect(snapshot.consented).toBe("yes");
       expect([...snapshot.mappings]).toEqual([MAPPING]);
       await s.done();
     });
@@ -42,7 +42,7 @@ function describePolicyStoreContract(name, options) {
         user: USER,
         owner: OWNER
       });
-      expect(snapshot.consented).toBe(true);
+      expect(snapshot.consented).toBe("yes");
       expect(snapshot.mappings).toEqual([]);
       await s.done();
     });
@@ -55,7 +55,7 @@ function describePolicyStoreContract(name, options) {
         user: USER,
         owner: OWNER
       });
-      expect(snapshot.consented).toBe(false);
+      expect(snapshot.consented).toBe("no");
       expect(snapshot.mappings).toEqual([]);
       await s.done();
     });
@@ -72,7 +72,7 @@ function describePolicyStoreContract(name, options) {
         user: USER,
         owner: OWNER
       });
-      expect(snapshot.consented).toBe(false);
+      expect(snapshot.consented).toBe("paused");
       await s.done();
     });
     it("keeps one person's consent out of another's", async () => {
@@ -83,7 +83,7 @@ function describePolicyStoreContract(name, options) {
         user: "carol",
         owner: OWNER
       });
-      expect(other.consented).toBe(false);
+      expect(other.consented).toBe("no");
       await s.done();
     });
     it("keeps one site's consent out of another's", async () => {
@@ -94,7 +94,7 @@ function describePolicyStoreContract(name, options) {
         user: USER,
         owner: OWNER
       });
-      expect(other.consented).toBe(false);
+      expect(other.consented).toBe("no");
       await s.done();
     });
     it("reports membership per owner, not per person", async () => {
@@ -135,14 +135,14 @@ function describePolicyStoreContract(name, options) {
         owner: OWNER
       });
       expect(noConsent.member).toBe(true);
-      expect(noConsent.consented).toBe(false);
+      expect(noConsent.consented).toBe("no");
       await s.consent({ siteId: SITE, user: "carol", mappings: [MAPPING] });
       const noMembership = await s.store.read({
         siteId: SITE,
         user: "carol",
         owner: OWNER
       });
-      expect(noMembership.consented).toBe(true);
+      expect(noMembership.consented).toBe("yes");
       expect(noMembership.member).toBe(false);
       await s.done();
     });
@@ -154,7 +154,7 @@ function describePolicyStoreContract(name, options) {
         user: "c",
         owner: OWNER
       });
-      expect(confusable.consented).toBe(false);
+      expect(confusable.consented).toBe("no");
       await s.done();
     });
   });

package/dist/store-contract.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/store-contract.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport type { Mapping, PolicyStore } from \"./store.js\";\n\n/*\n The policy store's behaviour, written once and run against every\n * implementation.\n \n The same reasoning as `@byollm/relay/store-contract`, and more of it. The\n * implementation that matters most is byollm.cloud's, in another repository\n * and not open — so this is the only way a reader can know that the hosted\n * product's store answers the same questions the same way the reference one\n * does. A contract only its author can run is a description.\n \n ## What a store has to do to be tested\n \n `PolicyStore` has one method, and it reads. Everything that writes —\n * consenting, mapping, adding somebody to a team — is the deployment's own\n * surface, and no two will agree on it. So the contract takes a small harness\n * that performs those acts however the implementation performs them, and\n * asserts only what `read` must then answer.\n \n That is the honest boundary: this proves the store's answers, not its\n * admin API. A store that passes has the semantics the engine relies on.\n /\nexport interface PolicyStoreContractOptions {\n /\n A fresh, empty store, its write surface, and how to dispose of it.\n \n Arrow-typed rather than methods, for the reason the routing store's\n * contract gives: a method signature lets `this` travel with a call read\n * off an options object, which is exactly where that goes wrong.\n /\n readonly make: () => Promise<{\n store: PolicyStore;\n consent: (input: {\n siteId: string;\n user: string;\n mappings?: readonly Mapping[];\n }) => Promise<void> \| void;\n revoke: (input: { siteId: string; user: string }) => Promise<void> \| void;\n /\n Pause a consent without withdrawing it.\n \n Optional because not every deployment offers pausing. A store that does\n * not is not asked to prove it — but one that does must prove a paused\n * consent reads as not-consented, which is the case below.\n /\n pause?: (input: { siteId: string; user: string }) => Promise<void> \| void;\n addMember: (input: { owner: string; user: string }) => Promise<void> \| void;\n removeMember: (input: {\n owner: string;\n user: string;\n }) => Promise<void> \| void;\n done: () => Promise<void>;\n }>;\n}\n\nconst SITE = \"site_demo\";\nconst OWNER = \"bob\";\nconst USER = \"alice\";\nconst MAPPING: Mapping = {\n purpose: \"writing_assistant\",\n kind: \"llm.generate\",\n service: \"qwen\",\n owner: null,\n};\n\n/* Run the contract. Call inside a suite; it declares its own `describe`. /\nexport function describePolicyStoreContract(\n name: string,\n options: PolicyStoreContractOptions,\n): void {\n describe(`the policy store — ${name}`, () => {\n it(\"says a site nobody authorised is not consented\", async () => {\n // The ordinary answer, not an error. A person who has never heard of a\n // site is the common case, and a store that threw here would make the\n // engine treat \"no\" as \"broken\".\n const { store, done } = await options.make();\n const snapshot = await store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(false);\n expect(snapshot.mappings).toEqual([]);\n await done();\n });\n\n it(\"returns the mapping the consent carried\", async () => {\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(true);\n expect([...snapshot.mappings]).toEqual([MAPPING]);\n await s.done();\n });\n\n it(\"distinguishes consented-and-unmapped from never-consented\", async () => {\n // A real signup state: every slot had two candidates, so nothing\n // auto-mapped and the person has not chosen. It is not the same as\n // never having authorised the site, and it sends them somewhere else.\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [] });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(true);\n expect(snapshot.mappings).toEqual([]);\n await s.done();\n });\n\n it(\"deletes the mapping when consent is withdrawn\", async () => {\n // Hole 2: the mapping is* the consent, so un-consenting unmaps. A\n // store that kept the mapping would hold a resolution pointing at a\n // service its author no longer authorises anybody to reach.\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n await s.revoke({ siteId: SITE, user: USER });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(false);\n expect(snapshot.mappings).toEqual([]);\n await s.done();\n });\n\n it(\"reads a paused consent as not consented\", async () => {\n // Three states, one boolean, on purpose: never authorised, revoked and\n // paused are different to a person and identical to a grant. A relay's\n // projection can lag by seconds, so a store that reported a paused\n // consent as live would let a grant be authored for work its owner had\n // just stopped.\n const s = await options.make();\n if (!s.pause) {\n await s.done();\n return;\n }\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n await s.pause({ siteId: SITE, user: USER });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(false);\n await s.done();\n });\n\n it(\"keeps one person's consent out of another's\", async () => {\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n const other = await s.store.read({\n siteId: SITE,\n user: \"carol\",\n owner: OWNER,\n });\n expect(other.consented).toBe(false);\n await s.done();\n });\n\n it(\"keeps one site's consent out of another's\", async () => {\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n const other = await s.store.read({\n siteId: \"site_other\",\n user: USER,\n owner: OWNER,\n });\n expect(other.consented).toBe(false);\n await s.done();\n });\n\n it(\"reports membership per owner, not per person\", async () => {\n // A team is one owner's, and being on one confers nothing about\n // anybody else's devices. A store that kept a global \"alice is a team\n // member\" flag would share every owner's hardware with her.\n const s = await options.make();\n await s.addMember({ owner: OWNER, user: USER });\n const mine = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n const theirs = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: \"carol\",\n });\n expect(mine.member).toBe(true);\n expect(theirs.member).toBe(false);\n await s.done();\n });\n\n it(\"stops reporting membership once somebody is removed\", async () => {\n // Removal is the whole of it — there is no blocked-but-still-a-member,\n // because a team is access to its owner's devices (Amendment J).\n const s = await options.make();\n await s.addMember({ owner: OWNER, user: USER });\n await s.removeMember({ owner: OWNER, user: USER });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.member).toBe(false);\n await s.done();\n });\n\n it(\"keeps membership and consent independent\", async () => {\n // Two different questions, and both have to be yes. A store that\n // conflated them would let a team member's work run on a site they\n // never authorised, or refuse a person their own site because nobody\n // had added them to a team.\n const s = await options.make();\n await s.addMember({ owner: OWNER, user: USER });\n const noConsent = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(noConsent.member).toBe(true);\n expect(noConsent.consented).toBe(false);\n\n await s.consent({ siteId: SITE, user: \"carol\", mappings: [MAPPING] });\n const noMembership = await s.store.read({\n siteId: SITE,\n user: \"carol\",\n owner: OWNER,\n });\n expect(noMembership.consented).toBe(true);\n expect(noMembership.member).toBe(false);\n await s.done();\n });\n\n it(\"does not let a site id and a user id be confused for each other\", async () => {\n // Composite keys are parsers waiting to meet an id containing their\n // separator. These two consents differ only in where the boundary\n // falls, and a store that joined them naively would answer one for the\n // other.\n const s = await options.make();\n await s.consent({ siteId: \"a\", user: \"b:c\", mappings: [MAPPING] });\n const confusable = await s.store.read({\n siteId: \"a:b\",\n user: \"c\",\n owner: OWNER,\n });\n expect(confusable.consented).toBe(false);\n await s.done();\n });\n });\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../src/store-contract.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport type { Mapping, PolicyStore } from \"./store.js\";\n\n/*\n The policy store's behaviour, written once and run against every\n * implementation.\n \n The same reasoning as `@byollm/relay/store-contract`, and more of it. The\n * implementation that matters most is byollm.cloud's, in another repository\n * and not open — so this is the only way a reader can know that the hosted\n * product's store answers the same questions the same way the reference one\n * does. A contract only its author can run is a description.\n \n ## What a store has to do to be tested\n \n `PolicyStore` has one method, and it reads. Everything that writes —\n * consenting, mapping, adding somebody to a team — is the deployment's own\n * surface, and no two will agree on it. So the contract takes a small harness\n * that performs those acts however the implementation performs them, and\n * asserts only what `read` must then answer.\n \n That is the honest boundary: this proves the store's answers, not its\n * admin API. A store that passes has the semantics the engine relies on.\n /\nexport interface PolicyStoreContractOptions {\n /\n A fresh, empty store, its write surface, and how to dispose of it.\n \n Arrow-typed rather than methods, for the reason the routing store's\n * contract gives: a method signature lets `this` travel with a call read\n * off an options object, which is exactly where that goes wrong.\n /\n readonly make: () => Promise<{\n store: PolicyStore;\n consent: (input: {\n siteId: string;\n user: string;\n mappings?: readonly Mapping[];\n }) => Promise<void> \| void;\n revoke: (input: { siteId: string; user: string }) => Promise<void> \| void;\n /\n Pause a consent without withdrawing it.\n \n Optional because not every deployment offers pausing. A store that does\n * not is not asked to prove it — but one that does must prove a paused\n * consent reads as not-consented, which is the case below.\n /\n pause?: (input: { siteId: string; user: string }) => Promise<void> \| void;\n addMember: (input: { owner: string; user: string }) => Promise<void> \| void;\n removeMember: (input: {\n owner: string;\n user: string;\n }) => Promise<void> \| void;\n done: () => Promise<void>;\n }>;\n}\n\nconst SITE = \"site_demo\";\nconst OWNER = \"bob\";\nconst USER = \"alice\";\nconst MAPPING: Mapping = {\n purpose: \"writing_assistant\",\n kind: \"llm.generate\",\n service: \"qwen\",\n owner: null,\n};\n\n/* Run the contract. Call inside a suite; it declares its own `describe`. /\nexport function describePolicyStoreContract(\n name: string,\n options: PolicyStoreContractOptions,\n): void {\n describe(`the policy store — ${name}`, () => {\n it(\"says a site nobody authorised is not consented\", async () => {\n // The ordinary answer, not an error. A person who has never heard of a\n // site is the common case, and a store that threw here would make the\n // engine treat \"no\" as \"broken\".\n const { store, done } = await options.make();\n const snapshot = await store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(\"no\");\n expect(snapshot.mappings).toEqual([]);\n await done();\n });\n\n it(\"returns the mapping the consent carried\", async () => {\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(\"yes\");\n expect([...snapshot.mappings]).toEqual([MAPPING]);\n await s.done();\n });\n\n it(\"distinguishes consented-and-unmapped from never-consented\", async () => {\n // A real signup state: every slot had two candidates, so nothing\n // auto-mapped and the person has not chosen. It is not the same as\n // never having authorised the site, and it sends them somewhere else.\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [] });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(\"yes\");\n expect(snapshot.mappings).toEqual([]);\n await s.done();\n });\n\n it(\"deletes the mapping when consent is withdrawn\", async () => {\n // Hole 2: the mapping is* the consent, so un-consenting unmaps. A\n // store that kept the mapping would hold a resolution pointing at a\n // service its author no longer authorises anybody to reach.\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n await s.revoke({ siteId: SITE, user: USER });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(\"no\");\n expect(snapshot.mappings).toEqual([]);\n await s.done();\n });\n\n it(\"reads a paused consent as not consented\", async () => {\n // Three states, one boolean, on purpose: never authorised, revoked and\n // paused are different to a person and identical to a grant. A relay's\n // projection can lag by seconds, so a store that reported a paused\n // consent as live would let a grant be authored for work its owner had\n // just stopped.\n const s = await options.make();\n if (!s.pause) {\n await s.done();\n return;\n }\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n await s.pause({ siteId: SITE, user: USER });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.consented).toBe(\"paused\");\n\n /*\n `\"paused\"`, not `\"no\"` — byollm-review 2026-08-27.\n \n The distinction is the whole reason this stopped being a boolean. A\n * store reporting a pause as \"no\" is not merely imprecise: the engine\n * declines `not-consented`, which is permanent, and the relay never\n * offers that job to that device again. The hosted product pauses a\n * consent the moment its author joins a team, so this is an everyday\n * path, and re-consenting minutes later did not bring the work back.\n \n A pause is somebody's own to lift, so the job has to still be there\n * when they do.\n /\n await s.done();\n });\n\n it(\"keeps one person's consent out of another's\", async () => {\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n const other = await s.store.read({\n siteId: SITE,\n user: \"carol\",\n owner: OWNER,\n });\n expect(other.consented).toBe(\"no\");\n await s.done();\n });\n\n it(\"keeps one site's consent out of another's\", async () => {\n const s = await options.make();\n await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });\n const other = await s.store.read({\n siteId: \"site_other\",\n user: USER,\n owner: OWNER,\n });\n expect(other.consented).toBe(\"no\");\n await s.done();\n });\n\n it(\"reports membership per owner, not per person\", async () => {\n // A team is one owner's, and being on one confers nothing about\n // anybody else's devices. A store that kept a global \"alice is a team\n // member\" flag would share every owner's hardware with her.\n const s = await options.make();\n await s.addMember({ owner: OWNER, user: USER });\n const mine = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n const theirs = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: \"carol\",\n });\n expect(mine.member).toBe(true);\n expect(theirs.member).toBe(false);\n await s.done();\n });\n\n it(\"stops reporting membership once somebody is removed\", async () => {\n // Removal is the whole of it — there is no blocked-but-still-a-member,\n // because a team is* access to its owner's devices (Amendment J).\n const s = await options.make();\n await s.addMember({ owner: OWNER, user: USER });\n await s.removeMember({ owner: OWNER, user: USER });\n const snapshot = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(snapshot.member).toBe(false);\n await s.done();\n });\n\n it(\"keeps membership and consent independent\", async () => {\n // Two different questions, and both have to be yes. A store that\n // conflated them would let a team member's work run on a site they\n // never authorised, or refuse a person their own site because nobody\n // had added them to a team.\n const s = await options.make();\n await s.addMember({ owner: OWNER, user: USER });\n const noConsent = await s.store.read({\n siteId: SITE,\n user: USER,\n owner: OWNER,\n });\n expect(noConsent.member).toBe(true);\n expect(noConsent.consented).toBe(\"no\");\n\n await s.consent({ siteId: SITE, user: \"carol\", mappings: [MAPPING] });\n const noMembership = await s.store.read({\n siteId: SITE,\n user: \"carol\",\n owner: OWNER,\n });\n expect(noMembership.consented).toBe(\"yes\");\n expect(noMembership.member).toBe(false);\n await s.done();\n });\n\n it(\"does not let a site id and a user id be confused for each other\", async () => {\n // Composite keys are parsers waiting to meet an id containing their\n // separator. These two consents differ only in where the boundary\n // falls, and a store that joined them naively would answer one for the\n // other.\n const s = await options.make();\n await s.consent({ siteId: \"a\", user: \"b:c\", mappings: [MAPPING] });\n const confusable = await s.store.read({\n siteId: \"a:b\",\n user: \"c\",\n owner: OWNER,\n });\n expect(confusable.consented).toBe(\"no\");\n await s.done();\n });\n });\n}\n"],"mappings":";AAAA,SAAS,UAAU,QAAQ,UAAU;AAyDrC,IAAM,OAAO;AACb,IAAM,QAAQ;AACd,IAAM,OAAO;AACb,IAAM,UAAmB;AAAA,EACvB,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,EACT,OAAO;AACT;AAGO,SAAS,4BACd,MACA,SACM;AACN,WAAS,2BAAsB,IAAI,IAAI,MAAM;AAC3C,OAAG,kDAAkD,YAAY;AAI/D,YAAM,EAAE,OAAO,KAAK,IAAI,MAAM,QAAQ,KAAK;AAC3C,YAAM,WAAW,MAAM,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,SAAS,SAAS,EAAE,KAAK,IAAI;AACpC,aAAO,SAAS,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACpC,YAAM,KAAK;AAAA,IACb,CAAC;AAED,OAAG,2CAA2C,YAAY;AACxD,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,QAAQ,EAAE,QAAQ,MAAM,MAAM,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;AACjE,YAAM,WAAW,MAAM,EAAE,MAAM,KAAK;AAAA,QAClC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,SAAS,SAAS,EAAE,KAAK,KAAK;AACrC,aAAO,CAAC,GAAG,SAAS,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC;AAChD,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,6DAA6D,YAAY;AAI1E,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,QAAQ,EAAE,QAAQ,MAAM,MAAM,MAAM,UAAU,CAAC,EAAE,CAAC;AAC1D,YAAM,WAAW,MAAM,EAAE,MAAM,KAAK;AAAA,QAClC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,SAAS,SAAS,EAAE,KAAK,KAAK;AACrC,aAAO,SAAS,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACpC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,iDAAiD,YAAY;AAI9D,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,QAAQ,EAAE,QAAQ,MAAM,MAAM,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;AACjE,YAAM,EAAE,OAAO,EAAE,QAAQ,MAAM,MAAM,KAAK,CAAC;AAC3C,YAAM,WAAW,MAAM,EAAE,MAAM,KAAK;AAAA,QAClC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,SAAS,SAAS,EAAE,KAAK,IAAI;AACpC,aAAO,SAAS,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACpC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,2CAA2C,YAAY;AAMxD,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,UAAI,CAAC,EAAE,OAAO;AACZ,cAAM,EAAE,KAAK;AACb;AAAA,MACF;AACA,YAAM,EAAE,QAAQ,EAAE,QAAQ,MAAM,MAAM,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;AACjE,YAAM,EAAE,MAAM,EAAE,QAAQ,MAAM,MAAM,KAAK,CAAC;AAC1C,YAAM,WAAW,MAAM,EAAE,MAAM,KAAK;AAAA,QAClC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,SAAS,SAAS,EAAE,KAAK,QAAQ;AAexC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,+CAA+C,YAAY;AAC5D,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,QAAQ,EAAE,QAAQ,MAAM,MAAM,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;AACjE,YAAM,QAAQ,MAAM,EAAE,MAAM,KAAK;AAAA,QAC/B,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,MAAM,SAAS,EAAE,KAAK,IAAI;AACjC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,6CAA6C,YAAY;AAC1D,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,QAAQ,EAAE,QAAQ,MAAM,MAAM,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;AACjE,YAAM,QAAQ,MAAM,EAAE,MAAM,KAAK;AAAA,QAC/B,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,MAAM,SAAS,EAAE,KAAK,IAAI;AACjC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,gDAAgD,YAAY;AAI7D,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,UAAU,EAAE,OAAO,OAAO,MAAM,KAAK,CAAC;AAC9C,YAAM,OAAO,MAAM,EAAE,MAAM,KAAK;AAAA,QAC9B,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,YAAM,SAAS,MAAM,EAAE,MAAM,KAAK;AAAA,QAChC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,KAAK,MAAM,EAAE,KAAK,IAAI;AAC7B,aAAO,OAAO,MAAM,EAAE,KAAK,KAAK;AAChC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,uDAAuD,YAAY;AAGpE,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,UAAU,EAAE,OAAO,OAAO,MAAM,KAAK,CAAC;AAC9C,YAAM,EAAE,aAAa,EAAE,OAAO,OAAO,MAAM,KAAK,CAAC;AACjD,YAAM,WAAW,MAAM,EAAE,MAAM,KAAK;AAAA,QAClC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,SAAS,MAAM,EAAE,KAAK,KAAK;AAClC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,4CAA4C,YAAY;AAKzD,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,UAAU,EAAE,OAAO,OAAO,MAAM,KAAK,CAAC;AAC9C,YAAM,YAAY,MAAM,EAAE,MAAM,KAAK;AAAA,QACnC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,UAAU,MAAM,EAAE,KAAK,IAAI;AAClC,aAAO,UAAU,SAAS,EAAE,KAAK,IAAI;AAErC,YAAM,EAAE,QAAQ,EAAE,QAAQ,MAAM,MAAM,SAAS,UAAU,CAAC,OAAO,EAAE,CAAC;AACpE,YAAM,eAAe,MAAM,EAAE,MAAM,KAAK;AAAA,QACtC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,aAAa,SAAS,EAAE,KAAK,KAAK;AACzC,aAAO,aAAa,MAAM,EAAE,KAAK,KAAK;AACtC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAED,OAAG,mEAAmE,YAAY;AAKhF,YAAM,IAAI,MAAM,QAAQ,KAAK;AAC7B,YAAM,EAAE,QAAQ,EAAE,QAAQ,KAAK,MAAM,OAAO,UAAU,CAAC,OAAO,EAAE,CAAC;AACjE,YAAM,aAAa,MAAM,EAAE,MAAM,KAAK;AAAA,QACpC,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,OAAO;AAAA,MACT,CAAC;AACD,aAAO,WAAW,SAAS,EAAE,KAAK,IAAI;AACtC,YAAM,EAAE,KAAK;AAAA,IACf,CAAC;AAAA,EACH,CAAC;AACH;","names":[]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@byollm/control-plane",
-  "version": "0.1.0-alpha.59",
+  "version": "0.1.0-alpha.60",
   "type": "module",
   "description": "The reference control plane: resolves a user's mapping and authors one signed grant per job, against a policy store it does not own.",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@byollm/protocol": "0.1.0-alpha.59"
+    "@byollm/protocol": "0.1.0-alpha.60"
   },
   "publishConfig": {
     "access": "public"