@byollm/server 0.1.0-alpha.4 → 0.1.0-alpha.40

package/dist/index.d.ts

@@ -1,10 +1,134 @@
-import { JobKind, StoredKeys, DeliveredResult, Endpoint, Capability } from '@byollm/protocol';
+import { StoredKeys, JobKind, DeliveredResult, Endpoint, Capability } from '@byollm/protocol';
 import { P as PollingDeliveryDeps, R as ResultDelivery, W as WaitOptions } from './delivery-36nIe-b3.js';
 export { N as NoRunnerAvailableError, a as PollingDelivery, b as ResultTimeoutError } from './delivery-36nIe-b3.js';
-import { B as ByollmStore, E as EnqueueInput, J as JobRecord, R as RunnerRecord, S as StoredJobInput, C as ClaimArgs, a as RenewArgs, b as RenewResult, c as CompleteArgs, d as CompleteResult, e as ReleaseArgs, P as PairingRecord, A as ApproveArgs, T as TouchArgs } from './store-gFEEN1Dt.js';
-export { f as JobStore, g as RunnerStore } from './store-gFEEN1Dt.js';
-import { H as HandlerConfig } from './handlers-CF3yE-t2.js';
-export { B as ByollmHandlers, a as HandlerResult, S as SERVED_PROTOCOL_VERSION } from './handlers-CF3yE-t2.js';
+import { B as ByollmStore, J as JobRecord, E as EnqueueInput, R as RunnerRecord, S as StoredJobInput, C as ClaimArgs, a as RenewArgs, b as RenewResult, A as AdoptArgs, c as CompleteArgs, d as CompleteResult, e as ReleaseArgs, P as PairingRecord, f as ApproveArgs, T as TouchArgs } from './store-Dno2fnHH.js';
+export { g as CompleteHolder, h as JobStore, i as RunnerStore } from './store-Dno2fnHH.js';
+import { H as HandlerConfig } from './handlers-BJYm2kdq.js';
+export { B as ByollmHandlers, a as HandlerResult, S as SERVED_PROTOCOL_VERSION } from './handlers-BJYm2kdq.js';
+
+/**
+ * The cloud lane — cloud_004 §9.4.
+ *
+ * `app.enqueue(...)` is identical in every lane; the lane picks the connection
+ * plane. In `direct` mode a daemon reaches the site's own handlers. In `cloud`
+ * mode it reaches a relay instead, and the site's side of that is this file.
+ *
+ * ## What actually changes, and what deliberately does not
+ *
+ * Enqueue does not change at all. The job is validated, sealed at rest to the
+ * site's own key and stored, exactly as before — jobs-at-rest encryption is a
+ * direct-mode property that the cloud lane inherits rather than replaces.
+ *
+ * What changes is *who asks for the payload and when*. On the direct plane the
+ * daemon asks, and the site answers synchronously because it is the upstream.
+ * Through a relay the site is not the upstream, so nobody asks: the site has to
+ * find out that a device claimed its job, and seal to that device. Hence a
+ * pump rather than a handler.
+ *
+ * ```
+ *  enqueue ──stub──▶ relay        (payload stays here, sealed at rest)
+ *                      │
+ *   pump ◀──who claimed it, and what key?
+ *        ──payload sealed to that device──▶
+ *   pump ◀──sealed result──  ──▶ store.complete → the app's delivery channel
+ * ```
+ *
+ * ## Why the site polls
+ *
+ * Everything in this product is outbound. A relay that called site webhooks
+ * would need every site publicly reachable, which is the connectivity problem
+ * the hub exists to remove — and a serverless site has nowhere to receive a
+ * webhook anyway. So the site polls, exactly as a daemon does.
+ */
+interface CloudLaneOptions {
+    /** Where the relay lives, e.g. `https://relay.byollm.cloud`. */
+    readonly relayOrigin: string;
+    /** This site's id at the relay. */
+    readonly siteId: string;
+    /** Injectable fetch, for tests and for proxies. */
+    readonly fetch?: typeof fetch;
+}
+/** What one pump cycle did, for logging and for tests. */
+/**
+ * A relay that could not answer this request — alpha.31.
+ *
+ * `retryable` is the whole point: a draining pod and a bad signature are both
+ * failures, and treating them alike is how a site either falls over on every
+ * deploy or stays silently disconnected for a week.
+ */
+declare class RelayUnavailable extends Error {
+    readonly retryable: boolean;
+    /** The protocol's own code, when the relay sent one. */
+    readonly code: string;
+    constructor(message: string, retryable: boolean, code: string);
+}
+interface PumpReport {
+    /** Jobs sealed to a claiming device this cycle. */
+    readonly sealed: string[];
+    /** Results opened, verified and written to the store. */
+    readonly completed: string[];
+    /**
+     * Jobs the relay offered that this site refused to seal for.
+     *
+     * Never silent: a site that cannot open its own at-rest envelope has a key
+     * problem, and a device waiting on a payload that will never come is
+     * exactly the case `awaiting-payload` exists to bound.
+     */
+    readonly refused: string[];
+    /**
+     * Why this cycle stopped early, when it did — alpha.31.
+     *
+     * A relay can legitimately say "ask me later": a pod draining through its
+     * `preStop` window answers `503 not-ready` to every routed call, and that
+     * happens on **every deploy**. Before this existed the lane read the body
+     * of that answer, found no `jobs` in it, and threw `TypeError: finished.jobs
+     * is not iterable` — a site falling over because its relay was polite.
+     *
+     * Absent on an ordinary cycle. Present, with the reason, when the lane
+     * deferred: a site that quietly did nothing and a site that was told to wait
+     * must not look the same in a log.
+     */
+    readonly deferred?: string;
+}
+declare class CloudLane {
+    #private;
+    constructor(deps: {
+        options: CloudLaneOptions;
+        store: ByollmStore;
+        siteKeys: StoredKeys;
+        now: () => number;
+    });
+    /**
+     * Publish a job's stub for routing.
+     *
+     * The stub and nothing else — byollm_009 §6 makes that exhaustive by
+     * construction, so this cannot leak a payload even by mistake: there is no
+     * field on `JobStub` to put one in.
+     */
+    publish(record: JobRecord): Promise<void>;
+    /**
+     * Withdraw a job at the relay — cloud_008 §2.2.
+     *
+     * `app.cancel()` marks the site's own row terminal, which stops the *next*
+     * seal. It cannot stop a device that is already running the work, because
+     * on this lane the site is not the upstream: only the relay talks to the
+     * daemon, and it answered `cancel: []` unconditionally.
+     *
+     * So the cancellation has to travel. The relay marks the job, stops
+     * offering it, and names it to the holding device at its next heartbeat —
+     * the same path the direct plane has always had, arriving one hop later.
+     */
+    cancel(jobId: string): Promise<void>;
+    /**
+     * One cycle: seal for anything claimed, collect anything finished.
+     *
+     * Idempotent and safe to call as often as you like. Exposed as a single
+     * cycle rather than hidden behind a timer so a caller decides its own
+     * cadence — a serverless site runs it on a cron, a long-lived one on an
+     * interval, and a test runs it exactly when it means to.
+     */
+    pump(): Promise<PumpReport>;
+}
 
 /** Why a job cannot presently run. */
 type NoRunnerReason = "no-runner-paired" | "no-runner-online" | "no-matching-capability" | "audience-admits-nobody";
@@ -53,6 +177,15 @@ interface ByollmAppOptions {
      * holds plaintext (byollm_009 §10).
      */
     readonly siteKeys: StoredKeys;
+    /**
+     * Which connection plane this site uses — cloud_004 §9.4.
+     *
+     * Omitted means `direct`: a daemon reaches this site's own handlers, and
+     * everything works as it always has. Supplying a relay switches the plane
+     * and nothing else — `enqueue` is identical in every lane, which is the
+     * property that lets the same app move between them by config.
+     */
+    readonly lane?: CloudLaneOptions;
 }
 /**
  * An enqueued job, with the delivery channel attached.
@@ -80,6 +213,8 @@ interface JobHandle {
  */
 declare class ByollmApp {
     #private;
+    /** Present only in the cloud lane; the site's side of the relay. */
+    readonly cloud: CloudLane | undefined;
     constructor(options: ByollmAppOptions);
     /**
      * Enqueue a job.
@@ -97,7 +232,7 @@ declare class ByollmApp {
      * Check `provenance.untrusted` before rendering. It is true for every
      * `named`/`public` job, because that text came from someone else's machine
      * and the app must not present it as its own AI's answer
-     * ({@link MUSTS.RESULT_PROVENANCE}).
+     * ({@link MUSTS.PROVENANCE_NAMES_DEVICE}).
      */
     result(jobId: string): Promise<DeliveredResult | null>;
     /** Ask a runner to stop. Queued jobs cancel at once; held jobs at the next heartbeat. */
@@ -220,8 +355,6 @@ declare function formatSiteKeys(keys: StoredKeys): string;
 
 /** A device code: the secret the daemon polls with. Never shown to a user. */
 declare function generateDeviceCode(): string;
-/** A runner bearer token. */
-declare function generateRunnerToken(): string;
 /** A runner id. */
 declare function generateRunnerId(): string;
 /** A job id. */
@@ -264,20 +397,23 @@ declare class MemoryStore implements ByollmStore {
     get(jobId: string): Promise<JobRecord | null>;
     claim(args: ClaimArgs): Promise<JobRecord[]>;
     renewLeases(args: RenewArgs): Promise<RenewResult>;
+    adopt(args: AdoptArgs): Promise<JobRecord | null>;
     complete(args: CompleteArgs): Promise<CompleteResult>;
     subscribe(jobId: string, onChange: () => void): () => void;
     release(args: ReleaseArgs): Promise<string[]>;
     expireDue(now: number): Promise<JobRecord[]>;
     cancel(jobId: string, now: number): Promise<JobRecord | null>;
     listClaimedBy(runnerId: string): Promise<JobRecord[]>;
-    listCancelRequests(runnerId: string): Promise<string[]>;
+    listCancelRequests(runnerId: string): Promise<{
+        jobId: string;
+        leaseId: string;
+    }[]>;
     createPairing(record: PairingRecord): Promise<void>;
     getPairingByDeviceCodeHash(hash: string): Promise<PairingRecord | null>;
     getPairingByUserCode(userCode: string): Promise<PairingRecord | null>;
     approvePairing(args: ApproveArgs): Promise<RunnerRecord>;
     denyPairing(userCode: string, _now: number): Promise<void>;
     consumePairingToken(deviceCodeHash: string): Promise<void>;
-    getRunnerByTokenHash(hash: string): Promise<RunnerRecord | null>;
     getRunner(runnerId: string): Promise<RunnerRecord | null>;
     touchRunner(args: TouchArgs): Promise<RunnerRecord | null>;
     revokeRunner(runnerId: string, now: number): Promise<void>;
@@ -288,4 +424,4 @@ declare class MemoryStore implements ByollmStore {
 /** The capability that would serve a kind, if any. */
 declare function capabilityFor(capabilities: readonly Capability[], kind: string): Capability | undefined;
 
-export { ApproveArgs, type AvailabilityQuery, ByollmApp, type ByollmAppOptions, ByollmStore, ClaimArgs, CompleteArgs, CompleteResult, EnqueueInput, HandlerConfig, type JobHandle, JobRecord, MemoryStore, type MemoryStoreOptions, type NoRunnerReason, PairingRecord, PollingDeliveryDeps, ReleaseArgs, RenewArgs, RenewResult, ResultDelivery, type RunnerAvailability, RunnerRecord, TouchArgs, WaitOptions, capabilityFor, createFetchHandler, formatSiteKeys, generateDeviceCode, generateJobId, generateRunnerId, generateRunnerToken, generateSiteKeys, generateUserCode, hashSecret, normalizeUserCode, routeEndpoint, secretsMatch, signatureFrom, siteKeysFromEnv };
+export { AdoptArgs, ApproveArgs, type AvailabilityQuery, ByollmApp, type ByollmAppOptions, ByollmStore, ClaimArgs, CloudLane, type CloudLaneOptions, CompleteArgs, CompleteResult, EnqueueInput, HandlerConfig, type JobHandle, JobRecord, MemoryStore, type MemoryStoreOptions, type NoRunnerReason, PairingRecord, PollingDeliveryDeps, type PumpReport, RelayUnavailable, ReleaseArgs, RenewArgs, RenewResult, ResultDelivery, type RunnerAvailability, RunnerRecord, TouchArgs, WaitOptions, capabilityFor, createFetchHandler, formatSiteKeys, generateDeviceCode, generateJobId, generateRunnerId, generateSiteKeys, generateUserCode, hashSecret, normalizeUserCode, routeEndpoint, secretsMatch, signatureFrom, siteKeysFromEnv };