@byollm/relay 0.1.0-alpha.22 → 0.1.0-alpha.23

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.22`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.23`) — 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
@@ -72,7 +72,7 @@
 > packages published and `@byollm/server` did not: a Sigstore
 > transparency-log 409 on its provenance attestation. The workflow's
 > "already published" guard correctly refuses to resume a partial publish,
-> so `0.1.0-alpha.22` is that release, whole.
+> so `0.1.0-alpha.23` is that release, whole.
 >
 > If you run the Supabase adapter, `alpha.21` needs
 > `20260819010000_completed_by_lease_id.sql`: alpha.19 shipped §3.6's
@@ -153,7 +153,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.22`, which on a relay reachable from the
+word for who it was until `0.1.0-alpha.23`, 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.
@@ -161,7 +161,7 @@ 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.22`: `RelayState` is async
+## Breaking in `0.1.0-alpha.23`: `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

package/dist/index.d.ts

@@ -1,514 +1,7 @@
-import { PublicIdentity, JobStub, SealedEnvelope, ClaimedStub } from '@byollm/protocol';
+import { R as RoutingStore } from './store-C_NtPAvT.js';
+export { A as AWAITING_PAYLOAD_MS, C as ClaimInput, H as HolderRefusal, P as Presence, a as RelayState, b as ReleaseReason, c as RoutedJob, d as RoutedState } from './store-C_NtPAvT.js';
 import { z } from 'zod';
-
-/**
- * The relay's routing state — byollm_009 §7, reachable at last.
- *
- * §7 described a state machine the direct plane could not produce. There, the
- * site and the upstream are the same party: it seals when it likes, and a job
- * is never claimed-but-unsealed. Here they are different parties, and the gap
- * between them is a state:
- *
- * ```
- * queued ──claim──▶ awaiting-payload ──sealed──▶ ready ──fetch──▶ running
- *    ▲                    │                                          │
- *    └────────────────────┘                                          ▼
- *      site never seals, or seals too late              ok | error | canceled
- * ```
- *
- * The relay cannot seal, so it cannot shortcut this. A payload is encrypted
- * to *the device that claimed it*, and nobody knows which device that is until
- * the claim happens — which is precisely why claim-then-fetch makes a blind
- * relay possible at all. The window is the price.
- *
- * ## What the relay holds, and what it cannot
- *
- * Stubs (metadata the site chose to publish), sealed envelopes it cannot open,
- * and public keys. There is no field on any type in this file that could hold
- * a private key or a plaintext, which is `RELAY_BLIND` expressed as a data
- * model rather than as a policy.
- */
-/** Where a routed job is. */
-type RoutedState = "queued" | "awaiting-payload" | "ready" | "running" | "done";
-/**
- * How long a site has to seal after one of its jobs is claimed.
- *
- * **Distinct from the lease, and distinct from the job's TTL** — byollm_009
- * §7.1. Three clocks, three different questions:
- *
- * - the **TTL** asks how long the work is worth doing at all;
- * - the **lease** asks how long this device gets to run it;
- * - this asks how long we wait for a site that has gone away.
- *
- * Collapsing any pair of them looks harmless until a site restarts during a
- * deploy: with only a lease, the device sits politely holding a job whose
- * payload will never arrive, and the lease's whole minute is spent waiting on
- * a party that is not coming back. Short, because a site that is up answers in
- * milliseconds and a site that is down will not answer sooner for waiting.
- */
-declare const AWAITING_PAYLOAD_MS = 10000;
-/** A job the relay is routing. Metadata and ciphertext, nothing else. */
-/** Why a daemon gave a job back. Only `refused` means "not me, ever". */
-type ReleaseReason = "shutdown" | "pause" | "revoked" | "backend-down" | "refused";
-interface RoutedJob {
-    readonly id: string;
-    /** Which site enqueued it — the party that will be asked to seal. */
-    readonly siteId: string;
-    /**
-     * Everything the relay knows about the work, which is everything the site
-     * chose to publish and not one field more (byollm_009 §6).
-     */
-    readonly stub: JobStub;
-    state: RoutedState;
-    /** Set from the claim; the site seals to these keys. */
-    claimedBy?: {
-        readonly runnerId: string;
-        readonly owner: string;
-        readonly device: PublicIdentity;
-        readonly leaseId: string;
-        readonly leaseExpiresAt: number;
-    };
-    /** When {@link AWAITING_PAYLOAD_MS} runs out for this claim. */
-    awaitingUntil?: number;
-    /**
-     * Runners that released this job with reason `refused` — cloud_008 §2.1.
-     *
-     * `REFUSAL_NOT_REOFFERED`, which the relay did not implement: it dropped
-     * `ReleaseRequest.reason` on the floor. The field's own docstring says why
-     * that is not cosmetic — an upstream cannot evaluate a daemon's *local*
-     * `named` allowlist, so it may legitimately offer work the daemon then
-     * declines, and without a record the two spin between claim and release
-     * forever. The direct plane has always kept this list.
-     */
-    refusedBy: string[];
-    /**
-     * The site withdrew this job — cloud_008 §2.2.
-     *
-     * A flag rather than a state, because a cancelled job that a device is
-     * *running* is not finished: the daemon has to be told, abort its backend
-     * call and report `canceled`, and the ordinary `complete` path then closes
-     * it. Making it a state would strand the in-flight case between two
-     * machines' ideas of what happened.
-     */
-    cancelled?: boolean;
-    /** Sealed to the claiming device by the site. Opaque here. */
-    payload?: SealedEnvelope;
-    /** Sealed to the site by the device. Opaque here. */
-    result?: SealedEnvelope;
-    /**
-     * The result's clear-text discriminator — byollm_009 §6.1.
-     *
-     * The one outcome fact the relay is given, and the reason it is given:
-     * without it the relay cannot stop dispatching a finished job. A routing
-     * hint and never a fact — the *site* verifies it against the sealed
-     * outcome, because only the site can open the envelope. The relay acts on
-     * it and is entitled to be wrong; a lying daemon costs it a dispatch
-     * decision, not a security property.
-     */
-    disposition?: "ok" | "error" | "canceled";
-}
-/** A device the relay has seen recently. */
-interface Presence {
-    readonly runnerId: string;
-    readonly owner: string;
-    readonly device: PublicIdentity;
-    lastSeenAt: number;
-}
-/**
- * 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;
-}
-/**
- * Where the store's sense of time comes from — cloud_006 §3.4.
- *
- * **The store owns its clock; callers do not pass one.** Every deadline the
- * relay decides — a lease's expiry, the `awaiting-payload` window, what a
- * sweep considers due — is now stamped by one source, and it is the same
- * source that will later stamp them for every replica.
- *
- * It used to be a parameter. `claim` took `now`, `sweep` took `now`, and each
- * plane called its own `now()` before calling in — which is fine in one
- * process and is the recurring bug the moment there are two. A lease granted
- * by a pod whose clock runs fast is short; the same lease swept by a pod whose
- * clock runs slow outlives it. Nobody is wrong and the lease has no length.
- *
- * A Valkey-backed store returns `TIME` here, so the deadline and the sweep
- * that enforces it are read from the same server. The injected clock stays for
- * tests, which is what lets them move time instead of sleeping.
- *
- * **What deliberately does not use this**: request-signature freshness. That
- * is checked against the *local* clock on purpose — it is a question about the
- * caller's clock versus this process's, `MAX_CLOCK_SKEW_MS` already tolerates
- * two minutes of disagreement, and a network round trip to timestamp every
- * inbound request would be a cost with no property behind it.
- */
-interface RelayStateOptions {
-    readonly now?: () => number | Promise<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.
- *
- * Deliberately not durable. The skeleton proves the protocol, and the
- * production hub replaces this with the closed multi-tenant router behind the
- * same shape (cloud_004 §9). Anything a restart loses here is a job that
- * returns to its site's queue — which is the behaviour a lapsed lease already
- * has to produce, so nothing new needs to be true for this to be safe.
- */
-declare class RelayState implements RoutingStore {
-    #private;
-    constructor(options?: RelayStateOptions);
-    /** The one clock every deadline in this store is stamped from. */
-    now(): Promise<number>;
-    /**
-     * Take a stub for routing. The payload is not here and will not be.
-     *
-     * **Idempotent by job id, and that is a security property rather than a
-     * convenience.** Site-plane calls are authenticated by signature, and
-     * byollm_009 §4.2's argument for signing the request instead of a
-     * server-issued nonce rests entirely on every write being idempotent per the
-     * instance it names. This one was not: re-enqueueing a known id built a
-     * fresh `queued` job over the top of the old one, discarding a live claim,
-     * its lease and any payload the site had already sealed to a device. A
-     * replayed enqueue inside the two-minute freshness window was therefore a
-     * way to yank a job back from the machine running it — the `release` bug of
-     * §4.2, rediscovered on the other plane.
-     *
-     * So a known id returns what is already routing, unchanged. A site that
-     * restarts and republishes its queue is the normal case, and it must not
-     * disturb work in flight.
-     */
-    enqueue(input: {
-        id: string;
-        siteId: string;
-        stub: JobStub;
-    }): Promise<RoutedJob>;
-    job(jobId: string): Promise<RoutedJob | undefined>;
-    jobs(): Promise<RoutedJob[]>;
-    /** Jobs a site must seal for, right now. */
-    awaiting(siteId: string): Promise<RoutedJob[]>;
-    /** Sealed results waiting to go home. */
-    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;
-    }>;
-    /**
-     * Record a finished job.
-     *
-     * `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.
-     */
-    complete(input: {
-        jobId: string;
-        runnerId: string;
-        leaseId: string;
-        envelope: SealedEnvelope;
-        disposition: "ok" | "error" | "canceled";
-    }): Promise<{
-        accepted: boolean;
-        duplicate?: 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;
-        }[];
-        reason?: ReleaseReason;
-    }): 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;
-    }>;
-    /** {@link RoutingStore.cancel} — the site withdraws a job. */
-    cancel(input: {
-        jobId: string;
-        siteId: string;
-    }): Promise<boolean>;
-    /** {@link RoutingStore.cancelRequests} — cancelled jobs this runner holds. */
-    cancelRequests(runnerId: string): Promise<string[]>;
-    /** {@link RoutingStore.renewLeases} — extend what is still held, name what is not. */
-    renewLeases(input: {
-        runnerId: string;
-        leases: readonly {
-            jobId: string;
-            leaseId: string;
-        }[];
-        leaseMs: number;
-    }): Promise<{
-        renewed: {
-            jobId: string;
-            expiresAt: number;
-        }[];
-        lost: string[];
-    }>;
-    seen(presence: Omit<Presence, "lastSeenAt">): Promise<Presence>;
-    presence(runnerId: string): Promise<Presence | undefined>;
-    everyone(): Promise<Presence[]>;
-    /**
-     * Fire whatever the clock says is due, and report it.
-     *
-     * Returns the jobs it requeued so a caller can log or surface them — a
-     * timeout that fires invisibly is indistinguishable from a job that was
-     * never claimed, and those want very different debugging.
-     */
-    sweep(): Promise<RoutedJob[]>;
-}
-
-/**
- * What the relay needs from a place to keep routing state — cloud_006 §3.2.
- *
- * `RelayState` implements this in memory and is the reference; a Valkey-backed
- * store implements the same thing across replicas. The interface exists so the
- * relay depends on the *contract* rather than on either, and so the properties
- * below are stated once rather than rediscovered per implementation.
- *
- * ## Every method is a decision plus its write
- *
- * Not one is a read the caller follows with a mutation. That is the whole
- * design, and it is not a style preference: `claim` used to be
- * `jobs()` → filter → mutate in the plane, which is atomic for exactly one
- * reason — Node is single-threaded and the Maps are local. Neither survives a
- * store on a network, and `packages/relay/test/two-replicas.test.ts` holds the
- * resulting race as a failing assertion.
- *
- * **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.
- *
- * ## What an implementation must guarantee
- *
- * 1. **`claim` is atomic.** Two callers claiming concurrently must not both
- *    receive the same job. `CLAIM_ATOMIC` is a protocol MUST.
- * 2. **`enqueue` is idempotent by job id.** A known id returns what is already
- *    routing rather than rebuilding it — byollm_009 §4.2's replay argument
- *    rests on every write being idempotent per the instance it names.
- * 3. **`complete` is idempotent.** A replayed result changes nothing, and the
- *    decision is made by the same operation that would have written it.
- * 4. **Lease-scoped operations name the grant.** `takePayload`, `complete` and
- *    `releaseLeases` check the lease *id*, not just the runner — a runner
- *    survives a claim-release-reclaim cycle and a grant does not.
- * 5. **`now()` is the only clock.** Every deadline the store stamps and every
- *    deadline it enforces come from here (§3.4). An implementation backed by a
- *    server returns that server's time, so two replicas cannot disagree about
- *    how long a lease is.
- *
- * ## What it must not do
- *
- * Hold a key, or learn about consent. `claim` takes `owners` as data because a
- * predicate cannot travel to Valkey — and the effect is that the store cannot
- * express an opinion about who may route, only about what it was told. That is
- * what keeps `RELAY_BLIND` a property of the shape rather than of the code.
- */
-interface RoutingStore {
-    /** The one clock every deadline in this store is stamped from. */
-    now(): Promise<number>;
-    /** Take a stub for routing. Idempotent by id. */
-    enqueue(input: {
-        id: string;
-        siteId: string;
-        stub: JobStub;
-    }): Promise<RoutedJob>;
-    job(jobId: string): Promise<RoutedJob | undefined>;
-    jobs(): Promise<RoutedJob[]>;
-    /** Jobs a site must seal for, right now. */
-    awaiting(siteId: string): Promise<RoutedJob[]>;
-    /** Sealed results waiting to go home. */
-    finished(siteId: string): Promise<RoutedJob[]>;
-    /** Grant work to a device — one operation, because it has to be. */
-    claim(input: ClaimInput): Promise<ClaimedStub[]>;
-    /** Hand the sealed payload to the device that holds the lease. */
-    takePayload(input: {
-        jobId: string;
-        runnerId: string;
-        leaseId: string;
-    }): Promise<{
-        envelope: SealedEnvelope;
-    } | {
-        refused: HolderRefusal;
-    }>;
-    /** Record a finished job. Idempotent. */
-    complete(input: {
-        jobId: string;
-        runnerId: string;
-        /**
-         * The grant the result was produced under — cloud_008 §1.4a.
-         *
-         * `takePayload` and `releaseLeases` have always checked this and said why;
-         * the operation that *writes* checked only the runner, which survives a
-         * claim-release-reclaim cycle.
-         */
-        leaseId: string;
-        envelope: SealedEnvelope;
-        disposition: "ok" | "error" | "canceled";
-    }): Promise<{
-        accepted: boolean;
-        duplicate?: boolean;
-        state: RoutedState;
-    } | {
-        refused: HolderRefusal;
-    }>;
-    /** Give back the grants this runner names. */
-    releaseLeases(input: {
-        runnerId: string;
-        leases: readonly {
-            jobId: string;
-            leaseId: string;
-        }[];
-        /**
-         * Why — cloud_008 §2.1. `refused` MUST be remembered and that job MUST
-         * NOT be offered to that runner again (`REFUSAL_NOT_REOFFERED`); every
-         * other reason means "not now" and must leave the job claimable by the
-         * same device, or a restart would strand its own work.
-         */
-        reason?: ReleaseReason;
-    }): Promise<string[]>;
-    /** Take a site's sealed payload for a claimed job. */
-    seal(input: {
-        jobId: string;
-        siteId: string;
-        envelope: SealedEnvelope;
-    }): Promise<{
-        state: RoutedState;
-    } | {
-        refused: "not-found" | "too-late";
-        was?: RoutedState;
-    }>;
-    /**
-     * Extend the leases this runner still holds, and name the ones it does not.
-     *
-     * One call because it is one question — cloud_008 §0.6. This was
-     * `lostLeases`, which answered only the second half, and the relay's
-     * heartbeat answered the first half with the literal `leases: []`. A daemon
-     * was therefore told, every few seconds, that none of its work had been
-     * renewed; the sweep requeued at `leaseMs` regardless of how alive the
-     * device was, and any job that took longer than a lease was handed to
-     * somebody else while the first device was still running it. The direct
-     * plane has always renewed here (`handlers.ts` §3), so this was also the two
-     * upstreams disagreeing about a rule the daemon cannot see.
-     *
-     * Renewal and loss come from one read of one state: asked separately they
-     * are two answers to "who holds this now", and under two replicas they can
-     * differ.
-     */
-    renewLeases(input: {
-        runnerId: string;
-        leases: readonly {
-            jobId: string;
-            leaseId: string;
-        }[];
-        leaseMs: number;
-    }): Promise<{
-        renewed: readonly {
-            jobId: string;
-            expiresAt: number;
-        }[];
-        lost: readonly string[];
-    }>;
-    /**
-     * The site withdraws a job — cloud_008 §2.2.
-     *
-     * Returns false when the job is not this site's, which is the same scoping
-     * every other site-plane operation carries: a site must not cancel
-     * somebody else's work by guessing an id.
-     */
-    cancel(input: {
-        jobId: string;
-        siteId: string;
-    }): Promise<boolean>;
-    /**
-     * Cancelled jobs this runner is holding, for the heartbeat to report.
-     *
-     * The relay answered `cancel: []` unconditionally, so a site could not stop
-     * a job it had already withdrawn — a device went on running work whose
-     * result nobody would accept, on somebody's own machine, at their expense.
-     */
-    cancelRequests(runnerId: string): Promise<string[]>;
-    /** Record a device as present. The store stamps when. */
-    seen(presence: Omit<Presence, "lastSeenAt">): Promise<Presence>;
-    presence(runnerId: string): Promise<Presence | undefined>;
-    everyone(): Promise<Presence[]>;
-    /** Fire whatever the clock says is due, and report it. */
-    sweep(): Promise<RoutedJob[]>;
-}
+import '@byollm/protocol';
 
 declare function debugPage(state: RoutingStore, now: number, 
 /**
@@ -861,4 +354,4 @@ declare class Relay {
     handle(request: Request): Promise<Response>;
 }
 
-export { AWAITING_PAYLOAD_MS, type ClaimInput, ConsentRecord, DeviceRecord, EMPTY_FIXTURE, type HolderRefusal, type Presence, Projection, Relay, RelayFixture, RelayFixture as RelayFixtureSchema, type RelayOptions, RelayState, type ReleaseReason, RevocationRecord, RosterRecord, type RoutedJob, type RoutedState, type RoutingStore, SiteRecord, debugPage };
+export { ConsentRecord, DeviceRecord, EMPTY_FIXTURE, Projection, Relay, RelayFixture, RelayFixture as RelayFixtureSchema, type RelayOptions, RevocationRecord, RosterRecord, RoutingStore, SiteRecord, debugPage };