@byollm/control-plane 0.1.0-alpha.58

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Of Tomorrow, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @byollm/control-plane
+
+> **Alpha (`0.1.0-alpha.58`) — 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
+never sees.
+
+```ts
+import { ControlPlane, MemoryPolicyStore, keypairSigner } from "@byollm/control-plane";
+import { Relay } from "@byollm/relay";
+
+const engine = new ControlPlane({
+  store: new MemoryPolicyStore(),
+  signer: keypairSigner(keys),
+});
+
+const relay = new Relay({
+  fixture,
+  controlPlanePublic: engine.publicKey,
+  authorGrant: (input) => engine.authorGrant(input),
+});
+```
+
+## What this is for
+
+A byollm device runs nothing on somebody else's behalf without a **grant**: a
+short-lived, single-use, signed statement that this job, for this person, on
+this device, may run — and which of the owner's services should answer. The
+device verifies it against a key it pinned when it paired, so the party
+routing the job can withhold a grant and cannot forge one.
+
+This package is what writes them.
+
+## Two things it deliberately does not hold
+
+**Your data.** Accounts, consents, memberships and mappings live behind
+[`PolicyStore`](src/store.ts). This package reads; it never owns. That is the
+split that lets a hosted product keep its database while the *rule* over that
+database stays readable — because a rule nobody can read is a rule nobody can
+check.
+
+**Your key.** [`GrantSigner`](src/signer.ts) is a function, not a keypair, so
+custody can sit behind a KMS and this code cannot tell.
+
+## The contract
+
+`@byollm/control-plane/store-contract` is a suite any `PolicyStore` can run
+against itself:
+
+```ts
+import { describePolicyStoreContract } from "@byollm/control-plane/store-contract";
+
+describePolicyStoreContract("my store", { make: async () => ({ /* … */ }) });
+```
+
+It ships in the package because the implementation that matters most is in
+somebody else's repository, and a contract only its author can run is a
+description.
+
+## The law it applies
+
+In order, and the order is by whose fact each step is:
+
+1. **A device always runs its own owner's work**, and no store is asked. It is
+   a law rather than an optimisation — routing it through a store would put it
+   somewhere an implementation could get wrong.
+2. The person has **consented** to this site, and has not paused it.
+3. They are a **member** of this device owner's team — asked only about other
+   people.
+4. Their **mapping** for this (purpose, kind) names a service.
+5. This device **actually offers** it, for this kind.
+
+Any step failing stops the rest, so the reason returned names the first thing
+that was wrong rather than whichever check ran last.
+
+## Declining says whether it is forever
+
+A relay releases a declined job, and a release can be permanent — never offer
+this job to this device again. Getting that wrong permissively is a
+claim-refuse loop, which announces itself. Getting it wrong strictly is a job
+that can never reach the machine it was always meant for, and no error
+anywhere. So only two reasons are permanent: a person removed from a team, and
+consent withdrawn. An unfilled slot, a mapping that resolved to another
+machine, and a policy store that was briefly unreachable are all states that
+can change, and the job goes back in the queue.
+
+## Licence
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import { GrantClaims, SignedGrant, StoredKeys, ClaimedStub, CapabilityMatrix } from '@byollm/protocol';
+import { P as PolicyStore, M as Mapping, a as PolicySnapshot } from './store-CzDvurIM.js';
+
+/**
+ * Whatever holds the key that grants are signed with.
+ *
+ * A function rather than a key, so custody never enters this package. A
+ * self-hoster hands over a keypair; a hosted deployment can put the private
+ * half behind a KMS and pass a signer that calls it, and the engine cannot
+ * tell the difference — which is the point. Custody of the signing key is one
+ * of the two things byollm.cloud keeps, and an engine that had to be given
+ * the key could not be run any other way.
+ *
+ * `publicKey` sits on the same object deliberately. It is the value a relay
+ * hands a device at pairing, and it is the value that must verify what
+ * `sign` produces. Two separate configuration items would be two things a
+ * deployment could set inconsistently — and the failure mode is a fleet that
+ * refuses every job while every process reports itself healthy.
+ */
+interface GrantSigner {
+    /** The public half, for a relay to hand devices at pairing. */
+    readonly publicKey: string;
+    sign(claims: GrantClaims): Promise<SignedGrant> | SignedGrant;
+}
+/**
+ * Sign with a keypair this process holds.
+ *
+ * The implementation a self-hoster wants, and the one the tests use. A hosted
+ * deployment writes its own against whatever holds its key.
+ */
+declare function keypairSigner(keys: Pick<StoredKeys, "identityPrivate" | "identityPublic">): GrantSigner;
+
+/**
+ * The control plane: one signed grant per job, or a reason there is none.
+ *
+ * byollm_016 Amendment J and L. This is the open engine behind a relay's
+ * `authorGrant` seam. It reads policy from a {@link PolicyStore} it does not
+ * own and signs with a {@link GrantSigner} whose key it never sees, so the
+ * two things byollm.cloud keeps — the data and the key — sit outside it, and
+ * the rule over them is readable by anybody.
+ *
+ * ## One routes, one authorises, only one signs
+ *
+ * A relay already filters what it offers a device, by consent and by
+ * membership. **That filter is an optimisation and this is the authority.**
+ * Everything is checked again here, because the relay's projection can be
+ * stale and because a grant asserting "consented, member, admitted" must be
+ * true when it is signed rather than when something upstream last looked. If
+ * the two disagree, this one wins and refuses.
+ */
+declare class ControlPlane {
+    #private;
+    constructor(options: {
+        readonly store: PolicyStore;
+        readonly signer: GrantSigner;
+        /** Injectable clock, so tests move time instead of sleeping. */
+        readonly now?: () => number;
+        /** Injectable id source, so a test can assert what was signed. */
+        readonly newGrantId?: () => string;
+    });
+    /** The key devices pin at pairing, from the same object that signs. */
+    get publicKey(): string;
+    /**
+     * Author a grant for one claimed job, or decline with a reason.
+     *
+     * The order below is the law, and it is ordered by *whose* fact each step
+     * is: the device's own owner first, then the person's consent, then their
+     * membership, then their mapping, then this machine's ability to honour it.
+     * A step that fails stops the rest, so the reason returned names the first
+     * thing that was actually wrong rather than whichever check ran last.
+     */
+    authorGrant(input: {
+        readonly job: ClaimedStub;
+        /** The site's id in this control plane's namespace, not its key id. */
+        readonly siteId: string;
+        /** The device owner asking. */
+        readonly owner: string;
+        /**
+         * Which of the site's declared purposes this job serves.
+         *
+         * Supplied by the caller rather than read off the job, because in the
+         * release that built this engine the stub does not carry one yet — every
+         * job is the site's {@link RESERVED_PURPOSE}. When purposes reach the
+         * wire, the caller passes the job's own and nothing here changes.
+         */
+        readonly purpose?: string;
+        /**
+         * What this device advertised it can serve.
+         *
+         * The control plane resolves a mapping to a service **from what the
+         * device said**, never from a name it invented. A mapping naming
+         * something this device does not offer is not honoured here — see
+         * `resolved-elsewhere`.
+         */
+        readonly capabilities: CapabilityMatrix;
+    }): Promise<GrantOutcome>;
+}
+/**
+ * Why no grant was authored — and, load-bearing, whether that is forever.
+ *
+ * The distinction exists because a relay releases a declined job, and a
+ * release can carry `refused`, which means *never offer this job to this
+ * device again*. Getting that wrong in the permissive direction is a
+ * claim-refuse loop; getting it wrong in the strict direction is a job that
+ * can never reach the machine it was always meant for, and no error anywhere.
+ */
+type DeclineReason = 
+/** This person may not use this owner's devices. */
+"not-a-member"
+/** This person has not authorised this site. */
+ | "not-consented"
+/** They authorised it and left this slot empty. */
+ | "unmapped"
+/** Their mapping names a service this device does not offer. */
+ | "resolved-elsewhere"
+/** The policy store could not answer. Says nothing about the job. */
+ | "store-unavailable";
+interface Decline {
+    readonly reason: DeclineReason;
+    /**
+     * Never offer this job to this device again.
+     *
+     * True only for the two facts that a queued job cannot outlive: a person
+     * removed from a team, and consent withdrawn. Hole 1 ruled that removal
+     * stops future claims *including queued ones*, and this is where that is
+     * enforced.
+     *
+     * Everything else is a state the user can change, or a fault of ours. A
+     * permanent mark on those would outlive the condition that caused it.
+     */
+    readonly permanent: boolean;
+}
+type GrantOutcome = {
+    readonly granted: SignedGrant;
+    readonly declined?: undefined;
+} | {
+    readonly granted?: undefined;
+    readonly declined: Decline;
+};
+
+/**
+ * A policy store in a `Map`, for tests and for a single-process self-hoster.
+ *
+ * It is the reference implementation in the sense that matters: the contract
+ * suite runs against it, so it is the thing anybody else's store is compared
+ * to. It is not a suggestion about how to build one — a real store is a
+ * database, and this one forgets everything when the process ends.
+ */
+declare class MemoryPolicyStore implements PolicyStore {
+    #private;
+    /**
+     * Record a consent, with the mapping it carries.
+     *
+     * One call because they are one act: the mapping **is** the consent
+     * (Amendment L), and a store that let them be written separately would
+     * allow a state — consented, no mappings, no way to have got there — that
+     * the product cannot produce.
+     *
+     * Consenting with an empty list is the real signup state, though: a person
+     * whose slots all had two candidates and who has not chosen yet.
+     */
+    consent(input: {
+        siteId: string;
+        user: string;
+        mappings?: readonly Mapping[];
+    }): void;
+    /**
+     * Pause a consent without withdrawing it.
+     *
+     * A real product state and not the same as revoking: the mapping survives,
+     * so resuming does not ask somebody to author their choices again. What it
+     * must not do is let work through — a relay's projection can lag by
+     * seconds, and a grant authored in that window would run work whose owner
+     * had just stopped it.
+     */
+    pause(input: {
+        siteId: string;
+        user: string;
+    }): void;
+    /** Let it move again. */
+    resume(input: {
+        siteId: string;
+        user: string;
+    }): void;
+    /**
+     * Withdraw consent, which deletes the mapping with it.
+     *
+     * Not two operations. "Revoking consent deletes the mapping — the mapping
+     * is the consent, so un-consenting unmaps" (hole 2), and a store that could
+     * leave one behind would leave a resolution pointing at a service the
+     * person no longer authorises anybody to reach.
+     */
+    revoke(input: {
+        siteId: string;
+        user: string;
+    }): void;
+    /** Add somebody to an owner's team. */
+    addMember(input: {
+        owner: string;
+        user: string;
+    }): void;
+    /**
+     * Remove somebody from an owner's team.
+     *
+     * There is no "blocked but still a member": a team **is** access to its
+     * owner's devices and nothing else, so member-but-blocked is not a deferred
+     * feature, it is an empty state (Amendment J).
+     */
+    removeMember(input: {
+        owner: string;
+        user: string;
+    }): void;
+    read(input: {
+        siteId: string;
+        user: string;
+        owner: string;
+    }): Promise<PolicySnapshot>;
+}
+
+export { ControlPlane, type Decline, type DeclineReason, type GrantOutcome, type GrantSigner, Mapping, MemoryPolicyStore, PolicySnapshot, PolicyStore, keypairSigner };

package/dist/index.js

@@ -0,0 +1,175 @@
+// src/engine.ts
+import { randomUUID } from "crypto";
+import {
+  RESERVED_PURPOSE
+} from "@byollm/protocol";
+var ControlPlane = class {
+  #store;
+  #signer;
+  #now;
+  #newId;
+  constructor(options) {
+    this.#store = options.store;
+    this.#signer = options.signer;
+    this.#now = options.now ?? Date.now;
+    this.#newId = options.newGrantId ?? (() => `grant_${randomUUID()}`);
+  }
+  /** The key devices pin at pairing, from the same object that signs. */
+  get publicKey() {
+    return this.#signer.publicKey;
+  }
+  /**
+   * Author a grant for one claimed job, or decline with a reason.
+   *
+   * The order below is the law, and it is ordered by *whose* fact each step
+   * is: the device's own owner first, then the person's consent, then their
+   * membership, then their mapping, then this machine's ability to honour it.
+   * A step that fails stops the rest, so the reason returned names the first
+   * thing that was actually wrong rather than whichever check ran last.
+   */
+  async authorGrant(input) {
+    const { job, owner } = input;
+    const purpose = input.purpose ?? RESERVED_PURPOSE;
+    let snapshot;
+    try {
+      snapshot = await this.#store.read({
+        siteId: input.siteId,
+        user: job.owner,
+        owner
+      });
+    } catch {
+      return decline("store-unavailable");
+    }
+    if (!snapshot.consented) return decline("not-consented");
+    if (job.owner !== owner && !snapshot.member) return decline("not-a-member");
+    const mapped = snapshot.mappings.find(
+      (mapping) => mapping.purpose === purpose && mapping.kind === job.kind
+    );
+    if (!mapped) return decline("unmapped");
+    if ((mapped.owner ?? job.owner) !== owner) {
+      return decline("resolved-elsewhere");
+    }
+    const offered = input.capabilities.some(
+      (capability) => capability.kind === job.kind && capability.service === mapped.service
+    );
+    if (!offered) return decline("resolved-elsewhere");
+    return {
+      granted: await this.#signer.sign({
+        grantId: this.#newId(),
+        jobId: job.id,
+        siteId: input.siteId,
+        user: job.owner,
+        owner,
+        purpose,
+        kind: job.kind,
+        service: mapped.service,
+        issuedAt: this.#now()
+      })
+    };
+  }
+};
+var PERMANENT = /* @__PURE__ */ new Set([
+  "not-a-member",
+  "not-consented"
+]);
+function decline(reason) {
+  return { declined: { reason, permanent: PERMANENT.has(reason) } };
+}
+
+// src/memory.ts
+var MemoryPolicyStore = class {
+  /** (siteId, user) to what that person authorised for that site. */
+  #consents = /* @__PURE__ */ new Map();
+  /** (siteId, user) pairs whose owner has paused them. */
+  #paused = /* @__PURE__ */ new Set();
+  /** owner to the people who may use their devices. */
+  #members = /* @__PURE__ */ new Map();
+  /**
+   * Record a consent, with the mapping it carries.
+   *
+   * One call because they are one act: the mapping **is** the consent
+   * (Amendment L), and a store that let them be written separately would
+   * allow a state — consented, no mappings, no way to have got there — that
+   * the product cannot produce.
+   *
+   * Consenting with an empty list is the real signup state, though: a person
+   * whose slots all had two candidates and who has not chosen yet.
+   */
+  consent(input) {
+    this.#consents.set(key(input.siteId, input.user), [
+      ...input.mappings ?? []
+    ]);
+    this.#paused.delete(key(input.siteId, input.user));
+  }
+  /**
+   * Pause a consent without withdrawing it.
+   *
+   * A real product state and not the same as revoking: the mapping survives,
+   * so resuming does not ask somebody to author their choices again. What it
+   * must not do is let work through — a relay's projection can lag by
+   * seconds, and a grant authored in that window would run work whose owner
+   * had just stopped it.
+   */
+  pause(input) {
+    this.#paused.add(key(input.siteId, input.user));
+  }
+  /** Let it move again. */
+  resume(input) {
+    this.#paused.delete(key(input.siteId, input.user));
+  }
+  /**
+   * Withdraw consent, which deletes the mapping with it.
+   *
+   * Not two operations. "Revoking consent deletes the mapping — the mapping
+   * is the consent, so un-consenting unmaps" (hole 2), and a store that could
+   * leave one behind would leave a resolution pointing at a service the
+   * person no longer authorises anybody to reach.
+   */
+  revoke(input) {
+    this.#consents.delete(key(input.siteId, input.user));
+    this.#paused.delete(key(input.siteId, input.user));
+  }
+  /** Add somebody to an owner's team. */
+  addMember(input) {
+    const members = this.#members.get(input.owner) ?? /* @__PURE__ */ new Set();
+    members.add(input.user);
+    this.#members.set(input.owner, members);
+  }
+  /**
+   * Remove somebody from an owner's team.
+   *
+   * There is no "blocked but still a member": a team **is** access to its
+   * owner's devices and nothing else, so member-but-blocked is not a deferred
+   * feature, it is an empty state (Amendment J).
+   */
+  removeMember(input) {
+    this.#members.get(input.owner)?.delete(input.user);
+  }
+  read(input) {
+    const id = key(input.siteId, input.user);
+    const mappings = this.#consents.get(id);
+    return Promise.resolve({
+      consented: mappings !== void 0 && !this.#paused.has(id),
+      member: this.#members.get(input.owner)?.has(input.user) ?? false,
+      mappings: mappings ?? []
+    });
+  }
+};
+var key = (siteId, user) => `${siteId}\0${user}`;
+
+// src/signer.ts
+import {
+  signGrant
+} from "@byollm/protocol";
+function keypairSigner(keys) {
+  return {
+    publicKey: keys.identityPublic,
+    sign: (claims) => signGrant(keys, claims)
+  };
+}
+export {
+  ControlPlane,
+  MemoryPolicyStore,
+  keypairSigner
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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, not its key id. */\n    readonly siteId: 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        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        siteId: input.siteId,\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":[]}

package/dist/store-CzDvurIM.d.ts

@@ -0,0 +1,121 @@
+/**
+ * What the control plane reads, and never owns.
+ *
+ * byollm_016 Amendment L. Every fact the engine needs to author one grant —
+ * whether a person consented to a site, whether they may use somebody's
+ * devices, and which of that owner's services their mapping resolves to —
+ * comes from here. The engine holds none of it.
+ *
+ * ## Why this is an interface rather than a table
+ *
+ * The policy store is where accounts, consents, memberships, mappings and
+ * billing live, and it is the part of byollm.cloud that stays proprietary.
+ * The *law* over that data is not: it is the engine, and it is open, so a
+ * self-hoster runs the same resolution against their own store and a reader
+ * can check what the hosted product does with theirs.
+ *
+ * The split is drawn where it is because these are genuinely different kinds
+ * of thing. Who is on whose team is somebody's data. What that membership
+ * *entitles* is a rule, and a rule nobody can read is a rule nobody can
+ * check.
+ *
+ * ## The contract
+ *
+ * `@byollm/control-plane/store-contract` is a suite any implementation can
+ * run against itself. It ships in the package for the reason the routing
+ * store's does: the implementation that matters most lives in another
+ * repository, and a contract only its author can run is a description.
+ */
+/**
+ * One slot a user has filled: this site's purpose, for this kind, runs there.
+ *
+ * Keyed by (purpose, kind) because a purpose may span kinds — "writing
+ * assistant" might use both `llm.chat` and `llm.generate` — and a person may
+ * reasonably want different services behind them.
+ *
+ * `service` is a service id in the **device owner's** namespace, which is why
+ * a mapping is only meaningful alongside the owner it was authored against.
+ */
+interface Mapping {
+    readonly purpose: string;
+    readonly kind: string;
+    /** The service id, in {@link Mapping.owner}'s namespace. */
+    readonly service: string;
+    /**
+     * Whose service it is. `null` means the mapper's own.
+     *
+     * **Not optional decoration.** Service ids are namespace-local: alice may
+     * be on two teams that both have a service called `qwen`, and the consent
+     * screen shows them as the two different choices they are. A mapping that
+     * stored only the name could not tell them apart — so her work would be
+     * admitted on whichever of those machines claimed it first, which is
+     * exactly the substitution this design exists to forbid.
+     *
+     * The first draft of this interface had only the name, and the consent
+     * screen's own test — "keeps a teammate's identical service name separate
+     * from your own" — was already asserting the distinction that the storage
+     * could not keep.
+     */
+    readonly owner: string | null;
+}
+/**
+ * Everything the engine needs about one (site, user, owner) triple.
+ *
+ * One read rather than three, because this happens on every claim and a
+ * control plane that made three round trips per job would be the reason
+ * somebody ran their own.
+ */
+interface PolicySnapshot {
+    /**
+     * May this user's work move for this site **right now**?
+     *
+     * 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.
+     *
+     * 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;
+    /**
+     * May this user's work run on this owner's devices?
+     *
+     * The store answers for other people. It is **not** consulted for the
+     * owner's own work — see {@link PolicyStore.read}.
+     */
+    readonly member: boolean;
+    /** This user's mappings for this site. Order is not meaningful. */
+    readonly mappings: readonly Mapping[];
+}
+interface PolicyStore {
+    /**
+     * Read the policy for one job's worth of question.
+     *
+     * **`owner === user` is not asked about here.** A device always runs its
+     * own owner's work, and routing that through a store would put a law in a
+     * place any implementation could get wrong — including by returning
+     * `member: false` for somebody's own account and quietly stopping their
+     * 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
+     * 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.
+     */
+    read(input: {
+        /** The site's id in the control plane's namespace, not its key id. */
+        readonly siteId: string;
+        /** Whose job it is. */
+        readonly user: string;
+        /** Whose device is asking. */
+        readonly owner: string;
+    }): Promise<PolicySnapshot>;
+}
+
+export type { Mapping as M, PolicyStore as P, PolicySnapshot as a };

package/dist/store-contract.d.ts

@@ -0,0 +1,68 @@
+import { P as PolicyStore, M as Mapping } from './store-CzDvurIM.js';
+
+/**
+ * The policy store's behaviour, written once and run against every
+ * implementation.
+ *
+ * The same reasoning as `@byollm/relay/store-contract`, and more of it. The
+ * implementation that matters most is byollm.cloud's, in another repository
+ * and not open — so this is the only way a reader can know that the hosted
+ * product's store answers the same questions the same way the reference one
+ * does. A contract only its author can run is a description.
+ *
+ * ## What a store has to do to be tested
+ *
+ * `PolicyStore` has one method, and it reads. Everything that *writes* —
+ * consenting, mapping, adding somebody to a team — is the deployment's own
+ * surface, and no two will agree on it. So the contract takes a small harness
+ * that performs those acts however the implementation performs them, and
+ * asserts only what `read` must then answer.
+ *
+ * That is the honest boundary: this proves the store's *answers*, not its
+ * admin API. A store that passes has the semantics the engine relies on.
+ */
+interface PolicyStoreContractOptions {
+    /**
+     * A fresh, empty store, its write surface, and how to dispose of it.
+     *
+     * Arrow-typed rather than methods, for the reason the routing store's
+     * contract gives: a method signature lets `this` travel with a call read
+     * off an options object, which is exactly where that goes wrong.
+     */
+    readonly make: () => Promise<{
+        store: PolicyStore;
+        consent: (input: {
+            siteId: string;
+            user: string;
+            mappings?: readonly Mapping[];
+        }) => Promise<void> | void;
+        revoke: (input: {
+            siteId: string;
+            user: string;
+        }) => Promise<void> | void;
+        /**
+         * Pause a consent without withdrawing it.
+         *
+         * Optional because not every deployment offers pausing. A store that does
+         * not is not asked to prove it — but one that does must prove a paused
+         * consent reads as not-consented, which is the case below.
+         */
+        pause?: (input: {
+            siteId: string;
+            user: string;
+        }) => Promise<void> | void;
+        addMember: (input: {
+            owner: string;
+            user: string;
+        }) => Promise<void> | void;
+        removeMember: (input: {
+            owner: string;
+            user: string;
+        }) => Promise<void> | void;
+        done: () => Promise<void>;
+    }>;
+}
+/** Run the contract. Call inside a suite; it declares its own `describe`. */
+declare function describePolicyStoreContract(name: string, options: PolicyStoreContractOptions): void;
+
+export { type PolicyStoreContractOptions, describePolicyStoreContract };

package/dist/store-contract.js

@@ -0,0 +1,165 @@
+// src/store-contract.ts
+import { describe, expect, it } from "vitest";
+var SITE = "site_demo";
+var OWNER = "bob";
+var USER = "alice";
+var MAPPING = {
+  purpose: "writing_assistant",
+  kind: "llm.generate",
+  service: "qwen",
+  owner: null
+};
+function describePolicyStoreContract(name, options) {
+  describe(`the policy store \u2014 ${name}`, () => {
+    it("says a site nobody authorised is not consented", async () => {
+      const { store, done } = await options.make();
+      const snapshot = await store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      expect(snapshot.consented).toBe(false);
+      expect(snapshot.mappings).toEqual([]);
+      await done();
+    });
+    it("returns the mapping the consent carried", async () => {
+      const s = await options.make();
+      await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });
+      const snapshot = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      expect(snapshot.consented).toBe(true);
+      expect([...snapshot.mappings]).toEqual([MAPPING]);
+      await s.done();
+    });
+    it("distinguishes consented-and-unmapped from never-consented", async () => {
+      const s = await options.make();
+      await s.consent({ siteId: SITE, user: USER, mappings: [] });
+      const snapshot = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      expect(snapshot.consented).toBe(true);
+      expect(snapshot.mappings).toEqual([]);
+      await s.done();
+    });
+    it("deletes the mapping when consent is withdrawn", async () => {
+      const s = await options.make();
+      await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });
+      await s.revoke({ siteId: SITE, user: USER });
+      const snapshot = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      expect(snapshot.consented).toBe(false);
+      expect(snapshot.mappings).toEqual([]);
+      await s.done();
+    });
+    it("reads a paused consent as not consented", async () => {
+      const s = await options.make();
+      if (!s.pause) {
+        await s.done();
+        return;
+      }
+      await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });
+      await s.pause({ siteId: SITE, user: USER });
+      const snapshot = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      expect(snapshot.consented).toBe(false);
+      await s.done();
+    });
+    it("keeps one person's consent out of another's", async () => {
+      const s = await options.make();
+      await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });
+      const other = await s.store.read({
+        siteId: SITE,
+        user: "carol",
+        owner: OWNER
+      });
+      expect(other.consented).toBe(false);
+      await s.done();
+    });
+    it("keeps one site's consent out of another's", async () => {
+      const s = await options.make();
+      await s.consent({ siteId: SITE, user: USER, mappings: [MAPPING] });
+      const other = await s.store.read({
+        siteId: "site_other",
+        user: USER,
+        owner: OWNER
+      });
+      expect(other.consented).toBe(false);
+      await s.done();
+    });
+    it("reports membership per owner, not per person", async () => {
+      const s = await options.make();
+      await s.addMember({ owner: OWNER, user: USER });
+      const mine = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      const theirs = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: "carol"
+      });
+      expect(mine.member).toBe(true);
+      expect(theirs.member).toBe(false);
+      await s.done();
+    });
+    it("stops reporting membership once somebody is removed", async () => {
+      const s = await options.make();
+      await s.addMember({ owner: OWNER, user: USER });
+      await s.removeMember({ owner: OWNER, user: USER });
+      const snapshot = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      expect(snapshot.member).toBe(false);
+      await s.done();
+    });
+    it("keeps membership and consent independent", async () => {
+      const s = await options.make();
+      await s.addMember({ owner: OWNER, user: USER });
+      const noConsent = await s.store.read({
+        siteId: SITE,
+        user: USER,
+        owner: OWNER
+      });
+      expect(noConsent.member).toBe(true);
+      expect(noConsent.consented).toBe(false);
+      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.member).toBe(false);
+      await s.done();
+    });
+    it("does not let a site id and a user id be confused for each other", async () => {
+      const s = await options.make();
+      await s.consent({ siteId: "a", user: "b:c", mappings: [MAPPING] });
+      const confusable = await s.store.read({
+        siteId: "a:b",
+        user: "c",
+        owner: OWNER
+      });
+      expect(confusable.consented).toBe(false);
+      await s.done();
+    });
+  });
+}
+export {
+  describePolicyStoreContract
+};
+//# sourceMappingURL=store-contract.js.map

package/dist/store-contract.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@byollm/control-plane",
+  "version": "0.1.0-alpha.58",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oftomorrowinc/byollm.git",
+    "directory": "packages/control-plane"
+  },
+  "homepage": "https://github.com/oftomorrowinc/byollm/tree/main/packages/control-plane",
+  "bugs": {
+    "url": "https://github.com/oftomorrowinc/byollm/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./store-contract": {
+      "types": "./dist/store-contract.d.ts",
+      "import": "./dist/store-contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@byollm/protocol": "0.1.0-alpha.58"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}