@byollm/server 0.1.0-alpha.3 → 0.1.0-alpha.31

package/dist/store-Dno2fnHH.d.ts

@@ -0,0 +1,436 @@
+import { JobKind, JobPayload, Audience, SealedEnvelope, SizeClass, JobState, Lease, JobOutcome, ResultProvenance, Capability, PublicIdentity } 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;
+    /**
+     * The work, sealed to this site's own encryption key (byollm_009 §10).
+     *
+     * The store never holds plaintext. The app sees plaintext at enqueue and at
+     * result because the app *is* the endpoint; everything in between —
+     * database, backups, log aggregators, a support engineer with read access —
+     * sees ciphertext.
+     *
+     * This is not protection from the application the user deliberately sent
+     * their work to. It is protection from everything the application's storage
+     * touches, which is a longer list than most people picture.
+     */
+    readonly envelope: SealedEnvelope;
+    /** Fixed at enqueue, where the plaintext is. */
+    readonly sizeClass: SizeClass;
+    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;
+    /**
+     * The grant that recorded this job's result — cloud_008 §3.6.
+     *
+     * Kept after `lease` is nulled, because "who finished this" outlives "who
+     * holds this" and the two are asked for different reasons. It is what lets
+     * a replay from the device that finished the job be answered *as a
+     * duplicate* rather than as a stale lease — and lets a replay from any
+     * other device be refused exactly as it would be for a job that is not
+     * terminal, so a job id is not a terminality probe.
+     */
+    readonly completedByLeaseId: string | 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;
+    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;
+    /**
+     * The device's pinned public keys. What later signatures verify against —
+     * a runner id names a machine, this proves it.
+     */
+    readonly device: PublicIdentity;
+}
+/** 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;
+    /**
+     * Whether this approval has already been collected — cloud_008 §2.4.
+     *
+     * This was `runnerTokenOnce`, a bearer token held until the daemon's next
+     * poll and then nulled. The token is gone (finding 37: minted, hashed,
+     * written to two disks, never sent or compared), but the *deliver-once*
+     * property it carried is real and separate: a replayed device code must get
+     * nothing, or a code seen in a shell history is a second pairing.
+     *
+     * So the flag stays and the secret does not. Nulling a token to mean
+     * "collected" was one field doing two jobs, and only one of them was load
+     * bearing.
+     */
+    readonly collected: boolean;
+    readonly label: string;
+    readonly platform: "darwin" | "linux" | "win32";
+    readonly daemonVersion: string;
+    readonly capabilities: readonly Capability[];
+    /**
+     * The device's public keys, presented at pair start (byollm_009 §5).
+     *
+     * Kept on the pairing so the approving user is approving a *specific
+     * machine*, not a code that any machine could later redeem. It is copied
+     * onto the runner at approval.
+     */
+    readonly device: PublicIdentity;
+    readonly expiresAt: number;
+    readonly createdAt: number;
+}
+/** What the app supplies to enqueue a job. */
+interface EnqueueInput {
+    readonly kind: JobKind;
+    /** The work, in plaintext. The server seals it before it is stored. */
+    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;
+}
+/**
+ * What the *store* is given — the sealed form.
+ *
+ * Distinct from {@link EnqueueInput} because the two are genuinely different
+ * things: an app hands over work in plaintext, and what gets written down is
+ * sealed. Collapsing them into one type would mean a field that is sometimes
+ * readable and sometimes not, which is the kind of ambiguity that ends with
+ * plaintext in a database.
+ */
+interface StoredJobInput extends Omit<EnqueueInput, "payload" | "id"> {
+    readonly id: string;
+    readonly envelope: SealedEnvelope;
+    readonly sizeClass: SizeClass;
+}
+
+/**
+ * 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: StoredJobInput, 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}).
+     */
+    /**
+     * Record a lease granted by an upstream this store does not own.
+     *
+     * The cloud lane's one addition to the store contract, and it exists
+     * because of a question the direct plane never has to answer: **who grants
+     * the lease?** On the direct plane the site is the upstream, so `claim`
+     * both selects the job and grants the lease in one atomic step. Through a
+     * relay the relay selects and grants, and the site finds out afterwards.
+     *
+     * Without this the site's own row stays `queued` while a device is
+     * actively running the work, which breaks two things that are not
+     * cosmetic: `complete` refuses the result because no lease matches
+     * ({@link MUSTS.LEASE_HONORED} enforced against a lease that was never
+     * recorded), and `expireDue` expires a job someone is in the middle of.
+     *
+     * Not a second grant: it records one, and returns `null` if the job is not
+     * in a state that can accept it. The authority over who holds what remains
+     * the upstream that granted it — a store adopting a lease is bookkeeping,
+     * not a decision.
+     */
+    adopt(args: AdoptArgs): Promise<JobRecord | null>;
+    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<LeaseRef[]>;
+}
+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;
+}
+/** What an upstream tells a store it has granted. */
+interface AdoptArgs {
+    readonly jobId: string;
+    /**
+     * The lease, by its own id — and deliberately **not** a runner id.
+     *
+     * A relayed device is not this site's runner. It never paired here, the
+     * site holds no token for it and cannot revoke it, and `byollm_runners` is
+     * a table of machines this site has a relationship with. Fabricating a row
+     * to satisfy a foreign key would manufacture a record the site cannot act
+     * on, which is worse than not having one.
+     *
+     * What the site legitimately knows is that the job is out on a lease
+     * granted by an upstream, and when that lease ends. Identity of the machine
+     * that ran it arrives with the result, proved by a signature — which is a
+     * stronger claim than a row anyway.
+     */
+    readonly leaseId: string;
+    readonly expiresAt: number;
+    readonly now: number;
+}
+/** A lease named by its grant, not only by the job it covers. */
+interface LeaseRef {
+    readonly jobId: string;
+    readonly leaseId: string;
+}
+interface RenewArgs {
+    readonly runnerId: string;
+    readonly leases: readonly LeaseRef[];
+    readonly leaseMs: number;
+    readonly now: number;
+}
+interface RenewResult {
+    readonly renewed: readonly {
+        jobId: string;
+        expiresAt: number;
+    }[];
+    /**
+     * Grants the runner claimed to hold but no longer does — V1-3.
+     *
+     * Both halves, because a job id is chosen per site: a daemon serving two
+     * sites that picked the same id cannot act on a bare one without guessing.
+     */
+    readonly lost: readonly LeaseRef[];
+}
+/**
+ * Which grant is being completed — the `LEASE_HONORED` guard, as a shape.
+ *
+ * A discriminated union rather than two optional fields, because the earlier
+ * version was safe only by data: it read "match the runner, unless a lease id
+ * was supplied", and a caller supplying neither would have matched
+ * `undefined === undefined` and written a result into a job it never held.
+ * Nothing did that, and nothing was going to — but the type permitted it, and
+ * this codebase has spent a week learning that a permitted mistake is a
+ * scheduled one.
+ *
+ * Two ways to name a holder because there are two planes. A direct runner
+ * paired with this site and is known by id. A relayed device never did, and
+ * is known only by the grant it holds — which is the more exact check anyway:
+ * `LEASE_HONORED` is a statement about a lease instance, the lesson the
+ * release endpoint learned when a replayed release yanked a later grant.
+ */
+type CompleteHolder = {
+    readonly by: "runner";
+    readonly runnerId: string;
+} | {
+    readonly by: "lease";
+    readonly leaseId: string;
+};
+interface CompleteArgs {
+    readonly jobId: string;
+    /**
+     * The authenticated caller — cloud_008 §3.6, and for the duplicate answer
+     * only.
+     *
+     * Never for authorisation: {@link CompleteHolder} decides whether this
+     * write may happen, and that has not changed. This decides which of two
+     * refusals a caller is owed once the write is refused.
+     *
+     * It exists because a *grant* is not a device. Scoping the duplicate answer
+     * to the lease id alone let a second daemon replay under a lease id it had
+     * learned and be told "already recorded" — which is both untrue and a
+     * terminality probe. Found by writing C010's third case.
+     */
+    readonly runnerId: string;
+    /** Who claims to hold this job. Both variants are checked, never trusted. */
+    readonly holder: CompleteHolder;
+    readonly outcome: JobOutcome;
+    readonly provenance: ResultProvenance;
+    readonly now: number;
+}
+interface CompleteResult {
+    /** False when this submission wrote nothing. */
+    readonly accepted: boolean;
+    /**
+     * True when the caller is the device that already recorded this result.
+     *
+     * cloud_008 §3.6. `RESULT_IDEMPOTENT` used to hold as a *side effect* of
+     * `LEASE_HONORED`: `complete` nulls the lease on success, so a replay was
+     * refused for not holding the job and the idempotency branch was never
+     * reached. Deleting that branch failed no check.
+     *
+     * byollm_009 §4's case for signing requests rather than issuing nonces
+     * rests on every write being idempotent per the instance it names. A MUST
+     * that another MUST's security argument leans on cannot be one that holds
+     * only because a null happened to trip first.
+     */
+    readonly duplicate?: boolean;
+    readonly job: JobRecord | null;
+}
+interface ReleaseArgs {
+    readonly runnerId: string;
+    readonly leases: readonly LeaseRef[];
+    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>;
+    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[]>;
+    /**
+     * Watch one job for state changes — the push seam (byollm_009 §8.3).
+     *
+     * **Required of every adapter, from day one, even though v1 uses it only
+     * for result readiness.** byollm_006 located streaming's real difficulty at
+     * the server→app leg: polling cannot carry deltas by construction. If the
+     * store contract were request/response only, adding streaming later would
+     * force a *second* adapter-breaking reshape — so the channel exists now and
+     * gets one more use later, rather than the interface changing twice.
+     *
+     * The handler is called after a change lands; it is a signal, not a
+     * payload, so a missed or duplicated call is survivable and the caller
+     * re-reads. That looseness is deliberate: it is the weakest contract every
+     * plausible backend can honour, and a stronger one would exclude adapters
+     * for no gain.
+     *
+     * Returns an unsubscribe function. Calling it twice MUST be safe.
+     */
+    subscribe(jobId: string, onChange: () => void): () => void;
+}
+interface ApproveArgs {
+    readonly userCode: string;
+    /** From the approving user's session, never from the daemon. */
+    readonly owner: string;
+    readonly runnerId: 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 { AdoptArgs as A, ByollmStore as B, ClaimArgs as C, EnqueueInput as E, JobRecord as J, PairingRecord as P, RunnerRecord as R, StoredJobInput as S, TouchArgs as T, RenewArgs as a, RenewResult as b, CompleteArgs as c, CompleteResult as d, ReleaseArgs as e, ApproveArgs as f, CompleteHolder as g, JobStore as h, RunnerStore as i };

package/dist/supabase/index.d.ts

@@ -1,5 +1,5 @@
 import { SupabaseClient } from '@supabase/supabase-js';
-import { B as ByollmStore } from '../store-D23N6iiP.js';
+import { B as ByollmStore } from '../store-Dno2fnHH.js';
 import { P as PollingDeliveryDeps, R as ResultDelivery } from '../delivery-36nIe-b3.js';
 import '@byollm/protocol';