@byollm/server 0.1.0-alpha.2 → 0.1.0-alpha.21

package/dist/store-D23N6iiP.d.ts

@@ -1,255 +0,0 @@
-import { JobKind, JobPayload, Audience, JobState, Lease, JobOutcome, ResultProvenance, Capability } from '@byollm/protocol';
-
-/**
- * A job as the server stores it.
- *
- * Adapters map this shape onto their own storage; the field meanings are
- * normative because the conformance kit asserts behaviour that depends on
- * them (TTL clock start, dependency gating, refusal tracking).
- */
-interface JobRecord {
-    readonly id: string;
-    readonly kind: JobKind;
-    readonly payload: JobPayload;
-    readonly audience: Audience;
-    /** The app's id for the user who enqueued it. */
-    readonly owner: string;
-    /** Server-side restriction on which runner owners may take a `named` job. */
-    readonly audienceAllow: readonly string[] | undefined;
-    /** Job ids that must all be `ok` before this becomes claimable. */
-    readonly dependsOn: readonly string[];
-    readonly state: JobState;
-    readonly lease: Lease | null;
-    readonly createdAt: number;
-    /**
-     * When the job became claimable — enqueue time for a job with no
-     * dependencies, or the moment its last dependency reached `ok`.
-     *
-     * **The TTL clock starts here, not at `createdAt`.** Starting it at enqueue
-     * would expire a dependent job for the crime of waiting on a slow
-     * dependency (byollm_001 Rev 1 §D, TTL clock resolved in build review).
-     * `null` means still blocked.
-     */
-    readonly claimableAt: number | null;
-    /** How long an unclaimed job may wait once claimable. */
-    readonly ttlMs: number;
-    /** Optional absolute deadline, independent of the TTL. */
-    readonly deadlineAt: number | null;
-    /**
-     * Runners that released this job with reason `refused` — their local
-     * allowlist declined it. Never offered to them again
-     * ({@link MUSTS.REFUSAL_NOT_REOFFERED}).
-     */
-    readonly refusedBy: readonly string[];
-    /** How many times this job has been claimed, including lease-expiry retries. */
-    readonly attempts: number;
-    readonly outcome: JobOutcome | null;
-    readonly provenance: ResultProvenance | null;
-    readonly updatedAt: number;
-}
-/** A paired daemon as the server stores it. */
-interface RunnerRecord {
-    readonly id: string;
-    /** The app's id for the user this runner is bound to — exactly one. */
-    readonly owner: string;
-    /** SHA-256 of the bearer token. The token itself is never stored. */
-    readonly tokenHash: string;
-    readonly label: string;
-    readonly platform: "darwin" | "linux" | "win32";
-    readonly daemonVersion: string;
-    readonly capabilities: readonly Capability[];
-    readonly paused: boolean;
-    /** Set once; a revoked runner never un-revokes. */
-    readonly revokedAt: number | null;
-    readonly lastHeartbeatAt: number;
-    readonly createdAt: number;
-}
-/** An in-flight device-code pairing. */
-interface PairingRecord {
-    /** SHA-256 of the device code. The code itself is never stored. */
-    readonly deviceCodeHash: string;
-    /** The short code the user reads. Unique among live pairings. */
-    readonly userCode: string;
-    readonly state: "pending" | "approved" | "denied";
-    /** Set when approved — learned from the approving user's own session. */
-    readonly owner: string | null;
-    readonly runnerId: string | null;
-    /**
-     * The bearer token, held until the daemon's next poll collects it, then
-     * cleared. Delivered exactly once.
-     */
-    readonly runnerTokenOnce: string | null;
-    readonly label: string;
-    readonly platform: "darwin" | "linux" | "win32";
-    readonly daemonVersion: string;
-    readonly capabilities: readonly Capability[];
-    readonly expiresAt: number;
-    readonly createdAt: number;
-}
-/** What the app supplies to enqueue a job. */
-interface EnqueueInput {
-    readonly kind: JobKind;
-    readonly payload: JobPayload;
-    readonly owner: string;
-    /** Defaults to `self` — the safe direction. */
-    readonly audience?: Audience;
-    readonly audienceAllow?: readonly string[];
-    readonly dependsOn?: readonly string[];
-    /** Defaults to the server config's `defaultTtlMs`. */
-    readonly ttlMs?: number;
-    readonly deadlineAt?: number;
-    /** Caller-supplied id, for idempotent enqueue. */
-    readonly id?: string;
-}
-
-/**
- * The adapter seam.
- *
- * Everything in `@byollm/server` above this interface is storage-agnostic;
- * everything below it is one adapter. `MemoryJobStore` is the reference
- * implementation and the thing the conformance kit certifies first — an
- * adapter is correct when the same kit passes against it.
- */
-interface JobStore {
-    /** Create a job. Idempotent when `input.id` is supplied and already exists. */
-    create(input: EnqueueInput, now: number): Promise<JobRecord>;
-    get(jobId: string): Promise<JobRecord | null>;
-    /**
-     * Atomically claim up to `max` jobs for a runner
-     * ({@link MUSTS.CLAIM_ATOMIC}).
-     *
-     * An implementation MUST apply, inside the same atomic step:
-     * - state is `queued`;
-     * - `claimableAt` is non-null and `<= now` (dependencies satisfied,
-     *   {@link MUSTS.DEPENDS_ON_GATING});
-     * - the job's kind appears in `capabilities`
-     *   ({@link MUSTS.CLAIM_REQUIRES_CAPABILITY});
-     * - the audience rules admit this runner
-     *   ({@link MUSTS.AUDIENCE_BOTH_SIDES});
-     * - `runnerId` is not in the job's `refusedBy`
-     *   ({@link MUSTS.REFUSAL_NOT_REOFFERED}).
-     *
-     * SQL-backed adapters SHOULD use `FOR UPDATE SKIP LOCKED`.
-     */
-    claim(args: ClaimArgs): Promise<JobRecord[]>;
-    /**
-     * Renew leases for the jobs a runner believes it holds, and report which it
-     * has lost. A job whose lease expired un-renewed returns to `queued`
-     * ({@link MUSTS.LEASE_RECLAIMABLE}).
-     */
-    renewLeases(args: RenewArgs): Promise<RenewResult>;
-    /**
-     * Record a terminal outcome. Idempotent by job id: the first terminal
-     * outcome wins ({@link MUSTS.RESULT_IDEMPOTENT}).
-     *
-     * Recording `ok` MUST also unblock dependents whose remaining dependencies
-     * are all `ok`, setting their `claimableAt` — which is when their TTL clock
-     * starts ({@link MUSTS.TTL_EXPIRY}).
-     */
-    complete(args: CompleteArgs): Promise<CompleteResult>;
-    /**
-     * Return jobs to `queued`. When `reason` is `refused`, the runner MUST be
-     * added to each job's `refusedBy`.
-     */
-    release(args: ReleaseArgs): Promise<string[]>;
-    /**
-     * Move every claimable-but-unclaimed job past its TTL, and every job past
-     * its absolute deadline, to `expired`. Returns what changed.
-     *
-     * Called opportunistically by the handlers; an adapter MAY also run it on a
-     * schedule. It MUST be idempotent — firing twice is always safe.
-     */
-    expireDue(now: number): Promise<JobRecord[]>;
-    /** Cancel a job by app request. Returns the job, or null if unknown. */
-    cancel(jobId: string, now: number): Promise<JobRecord | null>;
-    /** Jobs a runner currently holds — used to build the heartbeat cancel list. */
-    listClaimedBy(runnerId: string): Promise<JobRecord[]>;
-    /** Jobs awaiting cancellation that a given runner holds. */
-    listCancelRequests(runnerId: string): Promise<string[]>;
-}
-interface ClaimArgs {
-    readonly runnerId: string;
-    /** The runner's owner, for audience matching. */
-    readonly runnerOwner: string;
-    readonly capabilities: readonly Capability[];
-    readonly max: number;
-    readonly leaseMs: number;
-    readonly now: number;
-}
-interface RenewArgs {
-    readonly runnerId: string;
-    readonly jobIds: readonly string[];
-    readonly leaseMs: number;
-    readonly now: number;
-}
-interface RenewResult {
-    readonly renewed: readonly {
-        jobId: string;
-        expiresAt: number;
-    }[];
-    /** Jobs the runner claimed to hold but no longer does. */
-    readonly lost: readonly string[];
-}
-interface CompleteArgs {
-    readonly jobId: string;
-    readonly runnerId: string;
-    readonly outcome: JobOutcome;
-    readonly provenance: ResultProvenance;
-    readonly now: number;
-}
-interface CompleteResult {
-    /** False when this submission lost an idempotency race or the lease was gone. */
-    readonly accepted: boolean;
-    readonly job: JobRecord | null;
-}
-interface ReleaseArgs {
-    readonly runnerId: string;
-    readonly jobIds: readonly string[];
-    readonly reason: "shutdown" | "pause" | "revoked" | "backend-down" | "refused";
-    readonly now: number;
-}
-/** Runner registry and pairing state. */
-interface RunnerStore {
-    /** Begin a device-code pairing. */
-    createPairing(record: PairingRecord): Promise<void>;
-    getPairingByDeviceCodeHash(hash: string): Promise<PairingRecord | null>;
-    getPairingByUserCode(userCode: string): Promise<PairingRecord | null>;
-    /**
-     * Approve a pairing on behalf of an authenticated user, creating the
-     * runner. The `owner` MUST come from the approving user's own session — a
-     * daemon can never assert who it is ({@link MUSTS.PAIR_ONE_USER}).
-     */
-    approvePairing(args: ApproveArgs): Promise<RunnerRecord>;
-    denyPairing(userCode: string, now: number): Promise<void>;
-    /** Clear the one-shot token after the daemon collects it. */
-    consumePairingToken(deviceCodeHash: string): Promise<void>;
-    getRunnerByTokenHash(hash: string): Promise<RunnerRecord | null>;
-    getRunner(runnerId: string): Promise<RunnerRecord | null>;
-    /** Record a heartbeat: capabilities, version, pause state, liveness. */
-    touchRunner(args: TouchArgs): Promise<RunnerRecord | null>;
-    /** Revoke a runner. Once revoked, never un-revoked. */
-    revokeRunner(runnerId: string, now: number): Promise<void>;
-    /** Live runners for an owner — used by the no-runner signal. */
-    listRunners(owner?: string): Promise<RunnerRecord[]>;
-}
-interface ApproveArgs {
-    readonly userCode: string;
-    /** From the approving user's session, never from the daemon. */
-    readonly owner: string;
-    readonly runnerId: string;
-    readonly runnerToken: string;
-    readonly tokenHash: string;
-    readonly now: number;
-}
-interface TouchArgs {
-    readonly runnerId: string;
-    readonly capabilities: readonly Capability[];
-    readonly daemonVersion: string;
-    readonly paused: boolean;
-    readonly now: number;
-}
-/** A store providing both halves. Most adapters implement one object. */
-interface ByollmStore extends JobStore, RunnerStore {
-}
-
-export type { ApproveArgs as A, ByollmStore as B, ClaimArgs as C, EnqueueInput as E, JobRecord as J, PairingRecord as P, RunnerRecord as R, TouchArgs as T, RenewArgs as a, RenewResult as b, CompleteArgs as c, CompleteResult as d, ReleaseArgs as e, JobStore as f, RunnerStore as g };