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

package/dist/store-C_NtPAvT.d.ts

@@ -0,0 +1,512 @@
+import { PublicIdentity, JobStub, SealedEnvelope, ClaimedStub } from '@byollm/protocol';
+
+/**
+ * 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[]>;
+}
+
+export { AWAITING_PAYLOAD_MS as A, type ClaimInput as C, type HolderRefusal as H, type Presence as P, type RoutingStore as R, RelayState as a, type ReleaseReason as b, type RoutedJob as c, type RoutedState as d };

package/dist/store-contract.d.ts

@@ -0,0 +1,67 @@
+import { R as RoutingStore } from './store-C_NtPAvT.js';
+import '@byollm/protocol';
+
+/**
+ * The routing store's behaviour, written once and run against every
+ * implementation — cloud_008 finding 54.
+ *
+ * There were two copies. This package tested `RelayState`; `byollm-cloud`
+ * tested `ValkeyRoutingStore` with a file that opened by explaining it was
+ * "written once and parameterised… a second copy of the scenario is a second
+ * place for two implementations to quietly diverge" — and was itself the
+ * second copy. It had drifted to sixteen cases against the eighteen in the
+ * ledger, which is exactly the divergence the sentence predicted, happening
+ * to the sentence.
+ *
+ * So the contract lives here, in the package that declares `RoutingStore`,
+ * and both repositories import it. A store that cannot pass this is not a
+ * routing store, whatever it implements.
+ *
+ * ## Why this ships in the published package
+ *
+ * Because the implementation that matters most is in another repository. A
+ * contract only the author can run is a description; one a third party runs
+ * against their own implementation is a contract. `@byollm/relay/store-contract`
+ * is a subpath export so nothing that imports the relay itself pulls in a
+ * test framework.
+ *
+ * ## What this cannot prove
+ *
+ * `CLAIM_ATOMIC` is a MUST and every case here would pass against a store
+ * that read, decided and wrote in three steps — in one process there is
+ * nothing to interleave. Concurrency belongs with the implementation that
+ * has a network in it, and `byollm-cloud`'s suite runs it against Valkey with
+ * many connections. Named here so the omission is a decision rather than an
+ * oversight.
+ */
+/** The control-plane site id these cases route under. */
+declare const CONTRACT_SITE = "site_store";
+interface StoreContractOptions {
+    /**
+     * A fresh, empty store, and how to dispose of it.
+     *
+     * Arrow-typed rather than a method, because the caller passes these
+     * around: a method signature lets `this` travel with the call, and a
+     * factory read off an options object is exactly where that goes wrong.
+     */
+    readonly make: () => Promise<{
+        store: RoutingStore;
+        done: () => Promise<void>;
+    }>;
+    /**
+     * Whether this store writes stubs as bytes and reads them back.
+     *
+     * An in-process store holds typed objects and cannot hold a stub it cannot
+     * parse; a serialising one can, because what it wrote may have been written
+     * by a previous version. The case that covers it is skipped rather than
+     * hidden — a reader should know which half of this contract each store is
+     * proving (cloud_008 §2.1a).
+     */
+    readonly serialising?: boolean;
+    /** Write a stub's raw bytes, bypassing serialisation. */
+    readonly writeRawStub?: (store: RoutingStore, id: string, raw: string) => Promise<void>;
+}
+/** Run the contract. Call inside a suite; it declares its own `describe`. */
+declare function describeStoreContract(name: string, options: StoreContractOptions): void;
+
+export { CONTRACT_SITE, type StoreContractOptions, describeStoreContract };