@byollm/relay 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.10`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.12`) — under active development. Don't use this yet.**
 >
 > This is a walking skeleton. It routes real jobs between real daemons and real
 > sites, and it is the fixture byollm_009 freezes against — but it keeps its
@@ -80,7 +80,7 @@ daemons pin at pairing, verified against the `sites` half of the projection.
 Nothing here trusts a `siteId` in a body or a query string.
 
 That is newer than the rest of this package. The site plane took the caller's
-word for who it was until `0.1.0-alpha.10`, which on a relay reachable from the
+word for who it was until `0.1.0-alpha.12`, which on a relay reachable from the
 internet is an open enqueue endpoint into consenting users' machines and an
 open read of who is online. It was blind the whole time — nothing could open a
 payload — and blind is not the same as safe.
@@ -88,6 +88,24 @@ payload — and blind is not the same as safe.
 If you are running this: the site plane is authenticated but this is still a
 single-tenant relay with in-memory state. One site, one replica.
 
+## Breaking in `0.1.0-alpha.12`: `RelayState` is async
+
+Every method on `RelayState` now returns a `Promise`, and `Relay.sweep()` and
+`debugPage()` with it. `RelayState.requeue` is private — it was only ever a
+step inside another operation.
+
+Nothing about the behaviour changed. The shape did, and it had to before
+routing state can live anywhere but this process: a store on a network cannot
+offer a synchronous read, and — more importantly — cannot offer a *read the
+caller follows with a write*. So the operations are now decisions plus their
+writes (`claim`, `takePayload`, `complete`, `releaseLeases`, `seal`) rather
+than scans the caller mutates.
+
+`claim` is the one that matters. It was atomic for exactly one reason — Node
+is single-threaded and the Maps are local — and `CLAIM_ATOMIC` is a MUST. See
+`packages/relay/test/two-replicas.test.ts`, where the resulting race is a
+failing assertion waiting for the fix.
+
 ## Running it
 
 ```ts

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PublicIdentity, JobStub, SealedEnvelope } from '@byollm/protocol';
+import { PublicIdentity, JobStub, SealedEnvelope, ClaimedStub } from '@byollm/protocol';
 import { z } from 'zod';
 
 /**
@@ -93,6 +93,48 @@ interface Presence {
     /** Set on revocation so the next request is refused rather than routed. */
     revoked: boolean;
 }
+/**
+ * What a routing store must do, expressed as operations — cloud_006 §3.2.
+ *
+ * Every method below is a **decision plus its write**, never a read the caller
+ * follows with a mutation. That is the whole point, and it is the difference
+ * between an interface a shared store can implement and one it cannot.
+ *
+ * `claim` is the specimen. It used to live in `DaemonPlane` as
+ * `jobs()` → filter → mutate, which is atomic for exactly one reason: Node is
+ * single-threaded and these Maps are local, so nothing runs between the read
+ * and the write. Neither survives a store on a network, and
+ * `packages/relay/test/two-replicas.test.ts` holds the resulting race as a
+ * failing assertion.
+ *
+ * So the rule for anything added here: **if a caller has to read, decide, and
+ * write back, the operation is in the wrong place.** Move the decision in.
+ *
+ * ## Why the projection does not come with it
+ *
+ * `claim` takes `owners: string[]` rather than a projection or a predicate.
+ * A closure cannot travel to Valkey, and the projection replicates for free
+ * from the control plane — so the caller collapses it with
+ * `Projection.ownersRunnableBy` and hands over data the store can match on.
+ * That keeps the store ignorant of consent, which is also what keeps it
+ * replaceable.
+ */
+interface ClaimInput {
+    readonly runnerId: string;
+    readonly owner: string;
+    readonly device: PublicIdentity;
+    /** The site this relay routes for. Multi-tenancy widens this to a set. */
+    readonly siteId: string;
+    /** Job kinds this device can actually run. */
+    readonly kinds: ReadonlySet<string>;
+    /** Whose work it may run — the projection, already collapsed to data. */
+    readonly owners: ReadonlySet<string>;
+    readonly max: number;
+    readonly leaseMs: number;
+    readonly now: number;
+}
+/** Why a lease-scoped operation was refused, in the caller's vocabulary. */
+type HolderRefusal = "not-found" | "not-holder" | "stale-lease" | "not-ready";
 /**
  * In-memory routing state.
  *
@@ -126,24 +168,92 @@ declare class RelayState {
         id: string;
         siteId: string;
         stub: JobStub;
-    }): RoutedJob;
-    job(jobId: string): RoutedJob | undefined;
-    jobs(): RoutedJob[];
+    }): Promise<RoutedJob>;
+    job(jobId: string): Promise<RoutedJob | undefined>;
+    jobs(): Promise<RoutedJob[]>;
     /** Jobs a site must seal for, right now. */
-    awaiting(siteId: string): RoutedJob[];
+    awaiting(siteId: string): Promise<RoutedJob[]>;
     /** Sealed results waiting to go home. */
-    finished(siteId: string): RoutedJob[];
-    seen(presence: Omit<Presence, "revoked">): Presence;
-    presence(runnerId: string): Presence | undefined;
-    everyone(): Presence[];
+    finished(siteId: string): Promise<RoutedJob[]>;
+    /**
+     * Claim work — one operation, because it has to be.
+     *
+     * Moved here wholesale from `DaemonPlane`, where it was a scan followed by
+     * per-job mutation. Nothing about the *decision* changed; what changed is
+     * that a store can now implement it, because the filter and the write are
+     * one call rather than a loop the caller drives.
+     *
+     * The order of the guards is worth preserving as-is when this becomes a Lua
+     * script: cheapest first, and `owners` last because it is the only one that
+     * needed the projection.
+     */
+    claim(input: ClaimInput): Promise<ClaimedStub[]>;
+    /**
+     * Hand over the sealed payload to the device that holds the lease.
+     *
+     * The read and the state transition are one operation for the same reason
+     * `claim` is: `running` must be set by whoever was told the envelope, or two
+     * replicas can both hand out the same work and both believe they were first.
+     */
+    takePayload(input: {
+        jobId: string;
+        runnerId: string;
+        leaseId: string;
+    }): Promise<{
+        envelope: SealedEnvelope;
+    } | {
+        refused: HolderRefusal;
+    }>;
     /**
-     * Return a job to the queue, forgetting the claim.
+     * Record a finished job.
      *
-     * The stub survives; nothing is lost. That is `LEASE_RECLAIMABLE` and it is
-     * why the awaiting-payload timeout is cheap to fire: the worst case is that
-     * a device did nothing for ten seconds and another one gets a turn.
+     * `RESULT_IDEMPOTENT` lives here rather than in the caller: a replayed
+     * result must be a no-op decided by the same operation that would have
+     * written it, or two replicas can both decide they were the first.
      */
-    requeue(job: RoutedJob): void;
+    complete(input: {
+        jobId: string;
+        runnerId: string;
+        envelope: SealedEnvelope;
+        disposition: "ok" | "error" | "canceled";
+    }): Promise<{
+        accepted: boolean;
+        state: RoutedState;
+    } | {
+        refused: HolderRefusal;
+    }>;
+    /** Give back leases this runner holds, naming each grant it means. */
+    releaseLeases(input: {
+        runnerId: string;
+        leases: readonly {
+            jobId: string;
+            leaseId: string;
+        }[];
+    }): Promise<string[]>;
+    /**
+     * Take a site's sealed payload for a claimed job.
+     *
+     * Refuses anything not `awaiting-payload`, which is what makes the timeout
+     * mean something: a late seal must not land on a claim that has moved.
+     */
+    seal(input: {
+        jobId: string;
+        siteId: string;
+        envelope: SealedEnvelope;
+    }): Promise<{
+        state: RoutedState;
+    } | {
+        refused: "not-found" | "too-late";
+        was?: RoutedState;
+    }>;
+    /** Which of these leases this runner no longer holds. */
+    lostLeases(runnerId: string, active: readonly {
+        jobId: string;
+        leaseId: string;
+    }[]): Promise<string[]>;
+    seen(presence: Omit<Presence, "revoked">): Promise<Presence>;
+    presence(runnerId: string): Promise<Presence | undefined>;
+    everyone(): Promise<Presence[]>;
     /**
      * Fire whatever the clock says is due, and report it.
      *
@@ -151,10 +261,10 @@ declare class RelayState {
      * timeout that fires invisibly is indistinguishable from a job that was
      * never claimed, and those want very different debugging.
      */
-    sweep(now: number): RoutedJob[];
+    sweep(now: number): Promise<RoutedJob[]>;
 }
 
-declare function debugPage(state: RelayState, now: number): string;
+declare function debugPage(state: RelayState, now: number): Promise<string>;
 
 /**
  * What the relay is told about the world — cloud_004 §14.
@@ -335,6 +445,30 @@ declare class Projection {
     deviceByFingerprint(identityPublic: string): DeviceRecord | null;
     /** The consent binding this owner to this site, if it exists and stands. */
     consentFor(owner: string, siteId: string): ConsentRecord | null;
+    /**
+     * Every owner whose work this device's owner may run, as a list.
+     *
+     * The same question {@link mayRunFor} answers, asked in the direction a
+     * *store* can use. That difference is the crux of making `claim` atomic
+     * (cloud_006 §3.2).
+     *
+     * Today `claim` scans every job and calls `mayRunFor` per candidate, which
+     * works because the projection is a local object. A shared routing store
+     * cannot do that: the filter has to travel to the store, and a predicate
+     * does not travel — you cannot send a closure to Valkey. So the projection
+     * is collapsed to **data** here and handed over as a set the store can
+     * match on.
+     *
+     * That the collapse is possible at all is a property of the design worth
+     * noticing: `mayRunFor` is a finite lookup over consent and rosters, not a
+     * computation over the jobs. If it ever became job-dependent — "may run
+     * work of this size", say — an atomic claim would stop being expressible,
+     * and that is the moment to argue rather than to add a parameter.
+     *
+     * The owner is always included: a device runs its owner's work, and the
+     * relay checks that before it checks a roster.
+     */
+    ownersRunnableBy(deviceOwner: string): string[];
     /**
      * May this device's owner run work belonging to `jobOwner`?
      *
@@ -406,9 +540,9 @@ declare class Relay {
      * site vanished should return to the queue without waiting for someone to
      * ask about it.
      */
-    sweep(): {
+    sweep(): Promise<{
         requeued: string[];
-    };
+    }>;
     /** The whole HTTP surface. */
     handle(request: Request): Promise<Response>;
 }