@delacour/warden-e2e 0.7.0 → 0.8.0

package/types/core/src/conditions/conditions.types.d.ts

@@ -104,6 +104,22 @@ export type A11yCondition = {
     reduceMotion?: boolean;
     boldText?: boolean;
     contrast?: "increased" | "normal";
+    reduceTransparency?: boolean;
+    buttonShapes?: boolean;
+    differentiateWithoutColor?: boolean;
+    onOffLabels?: boolean;
+    highContrastText?: boolean;
+    colorInversion?: boolean;
+    screenReader?: boolean;
+    /**
+     * Android TalkBack: the `enabled_accessibility_services` and `accessibility_enabled` values (`null` = unset) the
+     * device had before warden turned TalkBack on, so undo puts back exactly those and never drops a service warden
+     * did not add. Present only while `screenReader` is true on Android.
+     */
+    screenReaderPrevious?: {
+        services: string | null;
+        enabled: string | null;
+    };
 };
 /** `cosmetic`: the status bar says so, the OS and the app still see the real battery (iOS simulators) */
 export type BatteryCondition = {
@@ -111,6 +127,19 @@ export type BatteryCondition = {
     charging?: boolean;
     cosmetic?: boolean;
 };
+export type CameraFacing = "back" | "front";
+export declare const CAMERA_FACINGS: readonly CameraFacing[];
+/** A staged asset the simulated camera plays; `path` is the staged copy under the device's camera dir. */
+export type CameraFeed = {
+    kind: "image";
+    path: string;
+} | {
+    kind: "video";
+    path: string;
+    loop: boolean;
+};
+/** The simulated camera per facing; a facing left out has no camera (iOS) or the emulator's default (Android). */
+export type CameraCondition = Partial<Record<CameraFacing, CameraFeed>>;
 /** Everything a lease can have set on its device, one slot per area. */
 export type ConditionValues = {
     network: NetworkCondition;
@@ -120,6 +149,7 @@ export type ConditionValues = {
     locale: LocaleCondition;
     a11y: A11yCondition;
     battery: BatteryCondition;
+    camera: CameraCondition;
 };
 export type ConditionArea = keyof ConditionValues;
 /** Display/iteration order; also the order undo resets areas in. */

package/types/core/src/conditions/inject-state.d.ts

@@ -6,7 +6,7 @@
  */
 export declare function injectStatePath(wardenHome: string, udid: string): string;
 /**
- * Write `{ seq: previous + 1, offline: false, clockOffsetMs: 0 }` (no freeze) when a state file exists; the dylib
+ * Write `{ seq: previous + 1, offline: false, clockOffsetMs: 0, camera: {} }` (no freeze, no camera feeds) when a state file exists; the dylib
  * applies any higher `seq`. No file = no injected app was ever launched on the device: nothing to do.
  * Returns an error message, or undefined.
  */

package/types/core/src/ios-runner/build.d.ts

@@ -0,0 +1,28 @@
+import { type AsyncResult } from "../../../types/src/result";
+import type { EnsureRunnerBuildInput, RunnerBuild, RunnerBuildError } from "./runner-build.types";
+export declare const RUNNER_SCHEME = "WardenRunner";
+/**
+ * The `xcodebuild` argv that builds the runner for one phone. `-destination id=` is what registers the UDID in the
+ * provisioning profile; the bundle id goes through `WARDEN_RUNNER_BUNDLE_ID` (the project derives the host app's,
+ * the UI-test bundle's and the runner app's ids from it, which `PRODUCT_BUNDLE_IDENTIFIER` would collapse into one).
+ */
+export declare function buildRunnerArgv(o: {
+    project: string;
+    derivedData: string;
+    udid: string;
+    team: string;
+    bundleId: string;
+}): string[];
+/**
+ * The derived-data directory `ensureRunnerBuild` would use for the current team, Xcode build and runner sources,
+ * without staging, building or taking the build lease: one Xcode version probe, the team lookup and a hash of the
+ * sources. It is the identity of a runner build; a resident host that serves another directory serves an old runner.
+ */
+export declare function expectedRunnerDerivedData(input: Pick<EnsureRunnerBuildInput, "team" | "configTeamId" | "env" | "home" | "exec" | "loadSources">): AsyncResult<string, RunnerBuildError>;
+/**
+ * A runner build signed for `udid`, ready for `xcodebuild test-without-building -xctestrun`. Cached per
+ * (team, Xcode build, runner sources) and rebuilt only for a phone the profile does not list yet, or when the
+ * profile ends within 24 h. Builds are serialised by a build lease; a waiting warden re-reads the cache and
+ * reuses what the holder built. Never installs or launches anything itself.
+ */
+export declare function ensureRunnerBuild(input: EnsureRunnerBuildInput): AsyncResult<RunnerBuild, RunnerBuildError>;

package/types/core/src/ios-runner/cache.d.ts

@@ -0,0 +1,44 @@
+import type { Exec } from "../exec";
+/** Rebuild when the provisioning profile ends within this long (free teams get 7-day profiles). */
+export declare const PROFILE_MARGIN_MS: number;
+/** When the profile's expiry cannot be read, assume a free team's 7 days minus a day of margin from the build. */
+export declare const UNKNOWN_PROFILE_LIFETIME_MS: number;
+/** `meta.json` next to `dd/` in a cache directory. */
+export type RunnerMeta = {
+    /** every phone the profile was built for (a new UDID needs a build: `-destination id=` registers it) */
+    udids: string[];
+    /** earliest expiry (ms since epoch) of the profiles embedded in the products; null = unreadable */
+    profileExpires: number | null;
+    builtAt: number;
+    bundleId: string;
+};
+export type RebuildReason = "none" | "new_udid" | "profile_expiring" | "bundle_id" | "missing";
+/** `<home>/ios-runner/<team>/<xcodeBuild>-<srcHash>`: holds `dd/` (derived data) and `meta.json`. */
+export declare function runnerCacheDir(home: string, team: string, xcodeBuild: string, srcHash: string): string;
+export declare function derivedDataDir(cacheDir: string): string;
+/** The cache's meta, or undefined when absent or not ours (a half-written file never reads as a hit). */
+export declare function readRunnerMeta(cacheDir: string): RunnerMeta | undefined;
+/** Written last, after the build, through a rename: the meta is what makes a build count. */
+export declare function writeRunnerMeta(cacheDir: string, meta: RunnerMeta): void;
+/** The `.xctestrun` `build-for-testing` wrote under `Build/Products`. */
+export declare function findXctestrun(derivedData: string): string | undefined;
+export type ReuseDecision = {
+    reuse: true;
+} | {
+    reuse: false;
+    because: RebuildReason;
+};
+/** Can the cached build serve `udid` now? */
+export declare function decideReuse(o: {
+    meta: RunnerMeta | undefined;
+    xctestrun: string | undefined;
+    udid: string;
+    bundleId: string;
+    now: number;
+}): ReuseDecision;
+/** `<key>ExpirationDate</key><date>2026-11-05T01:02:03Z</date>` of a decoded provisioning profile. */
+export declare function parseProfileExpiry(plist: string): number | undefined;
+/** Paths of the `embedded.mobileprovision` of every app `build-for-testing` produced (host app and test runner app). */
+export declare function embeddedProfiles(derivedData: string): string[];
+/** The earliest expiry among the built apps' profiles (`security cms -D`), null when none can be read. */
+export declare function readProfileExpiry(exec: Exec, derivedData: string): Promise<number | null>;

package/types/core/src/ios-runner/pack.d.ts

@@ -0,0 +1,17 @@
+import { type AsyncResult, type Result } from "../../../types/src/result";
+import type { RunnerSourceFiles } from "./runner-build.types";
+/**
+ * The iPhone runner's Xcode project, as the text files the binary embeds (`ios-runner.bin`: a JSON map of
+ * path -> text), the way the `@delacour/warden-e2e` runtime is. Paths are relative to `packages/e2e/native`
+ * and keep that layout, because the project reaches the shared `warden-simd` files through `../ios/…`.
+ */
+/** Name of the embedded blob (`Bun.embeddedFiles` reports it with a content hash: `ios-runner-<hash>.bin`). */
+export declare const RUNNER_BLOB = "ios-runner.bin";
+/** Read the runner sources from a checkout's `packages/e2e/native` directory. */
+export declare function collectRunnerSources(nativeDir: string): Result<RunnerSourceFiles>;
+export declare function writeRunnerBlob(nativeDir: string, outFile: string): Result<void>;
+/** A path inside the staged root: relative, `/`-separated, no `..`. */
+export declare function isSafeSourcePath(path: string): boolean;
+export declare function parseRunnerBlob(text: string): Result<RunnerSourceFiles>;
+/** The blob embedded in the compiled binary (`Bun.embeddedFiles`, name `ios-runner-<hash>.bin`). */
+export declare function loadEmbeddedRunnerSources(embedded?: readonly Blob[]): AsyncResult<RunnerSourceFiles>;

package/types/core/src/ios-runner/signing.d.ts

@@ -0,0 +1,40 @@
+import { type AsyncResult } from "../../../types/src/result";
+import type { Exec } from "../exec";
+import type { RunnerBuildError, SigningTeam, TeamSource } from "./runner-build.types";
+/** Env var that names the signing team; wins over `ios.teamId`. */
+export declare const IOS_TEAM_ENV = "WARDEN_IOS_TEAM_ID";
+/** `nz.co.delacour.warden.runner.<team>` (what the Xcode project defaults to too). */
+export declare function defaultRunnerBundleId(team: string): string;
+export type SigningIdentity = {
+    sha1: string;
+    name: string;
+};
+/** `  3) 1111…11 "Apple Development: Test User (AB12CD34EF)"` lines of `security find-identity -v -p codesigning`. */
+export declare function parseIdentities(stdout: string): SigningIdentity[];
+/** The DER of every `-----BEGIN CERTIFICATE-----` block in `text`. */
+export declare function certificatesFromPem(text: string): Uint8Array[];
+export declare function sha1Hex(der: Uint8Array): string;
+/**
+ * The `OU` of the certificate's subject: for Apple Development certificates the team id. Walks
+ * Certificate > TBSCertificate > subject (the issuer's own `OU` is a different element and never read).
+ */
+export declare function teamOfCertificate(der: Uint8Array): string | undefined;
+/** The teams the keychain holds a valid `Apple Development` identity for. Read-only: two `security` calls. */
+export declare function listSigningTeams(exec: Exec): AsyncResult<SigningTeam[]>;
+export type ResolvedTeam = {
+    team: string;
+    source: TeamSource;
+};
+/**
+ * The signing team, first hit wins: the explicit one, `WARDEN_IOS_TEAM_ID`, `ios.teamId`, then the keychain when
+ * it holds `Apple Development` identities of exactly one team. Several teams is `ios_team_ambiguous` (never a
+ * guess: a wrong team signs with the wrong account); none is `no_team`.
+ */
+export declare function resolveTeam(input: {
+    explicit?: string | undefined;
+    configTeamId?: string | undefined;
+    env: Record<string, string | undefined>;
+    exec: Exec;
+}): AsyncResult<ResolvedTeam, RunnerBuildError>;
+/** The runner's bundle id: the override (checked), else `nz.co.delacour.warden.runner.<team>`. */
+export declare function resolveRunnerBundleId(team: string, configured: string | undefined): string | RunnerBuildError;

package/types/core/src/ios-runner/sim-build.d.ts

@@ -0,0 +1,36 @@
+import { type AsyncResult } from "../../../types/src/result";
+import { type BuildLockDeps } from "../builds/lock";
+import { type Exec } from "../exec";
+import type { RunnerSourceFiles } from "./runner-build.types";
+/**
+ * The runner (XCUITest server) built for the iOS Simulator: no signing, no team, no device registration, so it is one
+ * `xcodebuild build-for-testing -destination 'generic/platform=iOS Simulator'` (about 4-10 s) per Xcode build and runner
+ * source hash, cached under `<home>/ios-runner/simulator/<xcodeBuild>-<hash>`. Any simulator can then run it
+ * (`test-without-building -destination id=<udid>`). Used by the XCUITest accessibility audit (A11Y-4).
+ */
+export type SimRunnerBuild = {
+    /** the `.xctestrun` inside `derivedData` */
+    xctestrun: string;
+    derivedData: string;
+    /** false: built just now */
+    cached: boolean;
+};
+export type EnsureSimRunnerInput = {
+    env: Record<string, string | undefined>;
+    exec: Exec;
+    /** warden's own version (part of the staged-source directory name) */
+    version: string;
+    loadSources: () => AsyncResult<RunnerSourceFiles>;
+    /** serialises builds of one (Xcode, sources); without it two concurrent callers may both build */
+    lock?: BuildLockDeps;
+    home?: string;
+    log?: (line: string) => void;
+    timeoutMs?: number;
+};
+export declare function simRunnerCacheDir(home: string, xcodeBuild: string, srcHash: string): string;
+export declare function buildSimRunnerArgv(o: {
+    project: string;
+    derivedData: string;
+}): string[];
+/** A simulator runner build for the current Xcode and runner sources; built now when the cache has none. */
+export declare function ensureSimRunnerBuild(input: EnsureSimRunnerInput): AsyncResult<SimRunnerBuild>;

package/types/core/src/ios-runner/stage.d.ts

@@ -0,0 +1,26 @@
+import { type AsyncResult } from "../../../types/src/result";
+import type { RunnerSourceFiles } from "./runner-build.types";
+export type StagedRunner = {
+    /** `<home>/ios-runner/src/<version>-<hash>` */
+    dir: string;
+    /** the Xcode project inside it */
+    project: string;
+    /** `<version>-<hash>`: part of the build cache key */
+    key: string;
+    /** first 10 hex digits of the sources' hash */
+    hash: string;
+};
+/** Where the runner builds live: `<home>/ios-runner`. */
+export declare function runnerRoot(home: string): string;
+/** Content hash of the sources: names and texts, in name order. */
+export declare function runnerSourceHash(files: RunnerSourceFiles): string;
+/**
+ * Write the runner sources to `<home>/ios-runner/src/<version>-<hash>/` (the layout of `packages/e2e/native`).
+ * Content-keyed and never rewritten in place, so a build still running from an older copy is safe. Written to a
+ * sibling temp directory and renamed, so a concurrent warden never sees half a copy; `.ready` marks a complete one.
+ */
+export declare function stageRunnerSources(o: {
+    home: string;
+    version: string;
+    loadSources: () => AsyncResult<RunnerSourceFiles>;
+}): AsyncResult<StagedRunner>;

package/types/core/src/lease-events.d.ts

@@ -0,0 +1,126 @@
+import type { Database } from "bun:sqlite";
+import type { Result } from "../../types/src/result";
+import type { WaitReason } from "./queue";
+import type { Platform } from "./types";
+/**
+ * The lease event log: an append-only `lease_events` table, one row per thing that happened to a device
+ * lease or device. Event type names are `snake_case` throughout (`heartbeat_lost`, `device_unhealthy`).
+ * Rows are written inside the same store transaction as the change they record (see `Store`), pruned by
+ * `warden gc` after `WARDEN_EVENTS_DAYS` (default 7).
+ */
+/** How a granted lease came to be: `leased` is a caller-side lease on a named device (`warden ui`). */
+export type GrantAction = "reuse" | "boot" | "create" | "leased";
+/** Per-type payloads (the JSON `data` column). */
+export type LeaseEventPayloads = {
+    /** a `claimDevices` call started */
+    requested: {
+        platform: Platform;
+        profile: string;
+        count: number;
+    };
+    /** a claim started waiting (boot queue or polling for a device): once per claim call, with why */
+    queued: {
+        platform: Platform;
+        profile: string;
+        queueId: string;
+        reason?: WaitReason;
+    };
+    /** a device lease was handed to the caller; `waitMs` = time since the claim was requested */
+    granted: {
+        platform: Platform;
+        profile?: string;
+        deviceId: string;
+        deviceName: string;
+        action: GrantAction;
+        waitMs: number;
+    };
+    /** a holder's heartbeat found its lease gone (released or reclaimed by someone else) */
+    heartbeat_lost: Record<string, never>;
+    /** the lease was deleted by its owner / a release; `heldMs` = time since it was granted */
+    released: {
+        heldMs: number;
+    };
+    /** the lease went stale (owner process gone, heartbeat expired) and was reclaimed */
+    expired: {
+        heldMs: number;
+    };
+    /** an idle warden device was shut down to make room for the queue head */
+    evicted: {
+        platform: Platform;
+        deviceId: string;
+        deviceName: string;
+    };
+    quarantined: {
+        platform: Platform;
+        deviceId: string;
+        deviceName: string;
+        reason?: string;
+    };
+    unquarantined: {
+        platform: Platform;
+        deviceId: string;
+    };
+    /** warden shut a device down: `idle` (gc idle pass) or `release` (a lease ended with the device) */
+    shutdown: {
+        platform: Platform;
+        deviceId: string;
+        deviceName?: string;
+        cause: "idle" | "release";
+    };
+    /** the health monitor under a lease read a device bad `consecutive` times in a row (once per episode) */
+    device_unhealthy: {
+        platform: Platform;
+        deviceId: string;
+        reason?: string;
+        consecutive?: number;
+    };
+    /** the monitor rebooted the device under the same lease after `attempts` tries, `durationMs` in all */
+    device_recovered: {
+        platform: Platform;
+        deviceId: string;
+        attempts?: number;
+        durationMs?: number;
+    };
+};
+export type LeaseEventType = keyof LeaseEventPayloads;
+export declare const LEASE_EVENT_TYPES: readonly LeaseEventType[];
+type EventBase = {
+    at: number;
+    leaseId?: string;
+    resourceKey?: string;
+    ownerKey?: string;
+    label?: string;
+    claimId?: string;
+};
+/** An event to write; `data` is typed by `type`. */
+export type NewLeaseEvent = {
+    [T in LeaseEventType]: EventBase & {
+        type: T;
+        data: LeaseEventPayloads[T];
+    };
+}[LeaseEventType];
+/** A stored event. */
+export type LeaseEvent = NewLeaseEvent & {
+    id: number;
+};
+export declare function insertLeaseEvent(db: Database, event: NewLeaseEvent): void;
+export type EventFilter = {
+    /** only events at or after this time (ms) */
+    since?: number;
+    /** exact lease id */
+    leaseId?: string;
+    /** the owner key (`agent:<sessionId>`, `user:<pid>`, `ci:<runId>`) or any substring of it */
+    owner?: string;
+    /** only events with an id above this (the `--follow` cursor) */
+    afterId?: number;
+};
+/** Events oldest first (by id), matching every given filter. */
+export declare function queryLeaseEvents(db: Database, filter?: EventFilter): LeaseEvent[];
+/** Delete events older than `before` (ms); returns how many. */
+export declare function pruneLeaseEvents(db: Database, before: number): number;
+export declare const DEFAULT_EVENTS_DAYS = 7;
+/** How long events are kept: `WARDEN_EVENTS_DAYS` (a positive integer) else 7 days. */
+export declare function eventsRetentionMs(env: Record<string, string | undefined>): Result<number>;
+/** Labels of leases warden holds for its own housekeeping: never user-visible grants. */
+export declare const INTERNAL_LEASE_LABELS: readonly string[];
+export {};

package/types/core/src/ownership.d.ts

@@ -0,0 +1,44 @@
+import type { Store } from "./store";
+/**
+ * Ownership marker: warden writes `.warden-owned.json` into the device dir of every iOS simulator it creates,
+ * naming the host instance (a random id kept in the store `meta`) that made it. Destructive paths (shutdown on
+ * release, erase, delete) refuse a sim whose marker names another instance: a second `WARDEN_HOME` or user
+ * account on the same machine owns it. A sim with no marker keeps today's rules. Android emulators are AVDs
+ * launched from a shared definition, not created per claim, so they carry no marker.
+ */
+export declare const MARKER_FILE = ".warden-owned.json";
+export declare const INSTANCE_META_KEY = "instance_id";
+export type OwnershipMarker = {
+    instanceId: string;
+    name: string;
+    createdAt: number;
+};
+/** The filesystem the marker lives on, injectable for tests. */
+export type MarkerFs = {
+    readText: (path: string) => string | undefined;
+    writeText: (path: string, text: string) => void;
+    isDir: (path: string) => boolean;
+};
+export declare const realMarkerFs: MarkerFs;
+type Env = Record<string, string | undefined>;
+/** This host's stable instance id: created on first use inside a transaction, then read from `meta`. */
+export declare function instanceId(store: Store): string;
+/** `~/Library/Developer/CoreSimulator/Devices/<udid>` (the default device set); undefined without `HOME`. */
+export declare function simDeviceDir(env: Env, udid: string): string | undefined;
+export type MarkerRead = {
+    kind: "absent";
+} | {
+    kind: "present";
+    marker: OwnershipMarker;
+} | {
+    kind: "unreadable";
+};
+export declare function readMarker(fs: MarkerFs, env: Env, udid: string): MarkerRead;
+/** Best-effort: only into a device dir that exists, and a failure never fails the create. */
+export declare function writeMarker(fs: MarkerFs, env: Env, store: Store, udid: string, name: string, now: number): boolean;
+/**
+ * Why a destructive step must leave this sim alone, else undefined: its marker names another warden instance.
+ * A missing or unreadable marker blocks nothing (sims made before markers existed).
+ */
+export declare function markerBlock(fs: MarkerFs, env: Env, store: Store, udid: string): string | undefined;
+export {};

package/types/core/src/providers/android.d.ts

@@ -1,5 +1,7 @@
 import { type AsyncResult, type Result } from "../../../types/src/result";
+import { type CameraMode } from "../camera-mode";
 import { type PidAlive } from "../liveness";
+import { type Store } from "../store";
 import type { Lease } from "../types";
 import type { DeviceProvider, ProviderDeps } from "./provider.types";
 /** Emulator console ports: even, 5554–5584; the adb port is console + 1. */
@@ -115,7 +117,12 @@ export declare function rejectedOption(error: string): boolean;
 /** A claim's emulator: headless, `-read-only` (one AVD backs many), from `snapshot` when given, never saving on exit. */
 export declare function claimEmulatorArgv(tools: AndroidTools, env: Record<string, string | undefined>, avd: string, port: number, snapshot?: string, 
 /** `false` leaves out `headlessEmulatorFlags` (an emulator that rejected them) */
-headless?: boolean): string[];
+headless?: boolean, 
+/** a `+cam` device's feeds: each camera plays `mode`'s video, else reads `<facing>.png` from `dir` */
+camera?: {
+    dir: string;
+    mode: CameraMode;
+}): string[];
 export type BootWaitDeps = ExecDeps & {
     now: () => number;
     sleep: (ms: number) => Promise<void>;
@@ -150,6 +157,8 @@ export declare const GOLDEN_PORT_LABEL = "emulator golden ";
  * and unverified on a device; a successful load logs `Successfully loaded snapshot …`, which does not match.
  */
 export declare function snapshotLoadFailed(log: string): boolean;
+/** The bookkeeping of an emulator that is gone: its console-port lease and its `devices` record. */
+export declare function forgetAndroidEmulator(store: Store, serial: string): void;
 /**
  * Global settings applied after every boot. On a fresh playstore image the first `adb install` can pop a Play
  * Protect consent dialog (a GMS activity the e2e alert detector cannot classify), and every adb install otherwise

package/types/core/src/providers/provider.types.d.ts

@@ -1,5 +1,6 @@
 import type { AsyncResult } from "../../../types/src/result";
 import type { Exec } from "../exec";
+import type { MarkerFs } from "../ownership";
 import type { Store } from "../store";
 import type { InventoryDevice, Owner, Platform } from "../types";
 import type { Timer } from "./health";
@@ -36,6 +37,12 @@ export interface DeviceProvider {
      * shutdown reuse), never for an already-booted one. A failure is logged by the provider, never fatal.
      */
     prepareBoot?(id: string): Promise<void>;
+    /**
+     * Restart a running warden device in place (same id, same console port, device record and port lease kept) so
+     * launch-time settings apply again; the caller then waits with `waitReady`. Android camera emulators only
+     * (the camera source is fixed at launch). Absent = the platform cannot.
+     */
+    relaunch?(id: string): AsyncResult<void>;
     /** Called once the device is ready, before the health probe. Best effort. */
     afterReady?(id: string): Promise<void>;
 }
@@ -60,4 +67,6 @@ export type ProviderDeps = {
     timer?: (ms: number) => Timer;
     /** progress notes (e.g. "cloning from golden…") — stderr in the CLI */
     log?: (line: string) => void;
+    /** where the iOS ownership marker is written (default: the real filesystem) */
+    markerFs?: MarkerFs;
 };

package/types/core/src/queue.d.ts

@@ -0,0 +1,43 @@
+import { type Result } from "../../types/src/result";
+import type { CapacityReason } from "./claim-errors";
+import type { QueueEntry } from "./types";
+export declare const PRIORITY: {
+    readonly interactive: 30;
+    readonly high: 20;
+    readonly normal: 10;
+    readonly low: 0;
+};
+export type PriorityName = keyof typeof PRIORITY;
+/** `high` for 20, the number itself for a custom priority. */
+export declare const priorityName: (priority: number) => string;
+/** Gap between adjacent named priorities (`low` → `normal` → `high` → `interactive`). */
+export declare const PRIORITY_STEP = 10;
+/**
+ * One priority level (`PRIORITY_STEP` points) is earned per this much waiting, so a `low` row overtakes
+ * a fresh `high` one after 20 min, inside the default 30 min `--wait`.
+ */
+export declare const AGING_MS: number;
+export declare function parsePriority(input: string): Result<number>;
+/** `priority + PRIORITY_STEP × floor(age / 10 min)`; clock skew (now < enqueuedAt) earns nothing. */
+export declare function effectivePriority(entry: QueueEntry, now: number): number;
+/** Head first: effective priority desc, then enqueued_at asc, then id. */
+export declare function queueOrder(entries: readonly QueueEntry[], now: number): QueueEntry[];
+/** 1-based position, or undefined when `id` is not queued. */
+export declare function queuePosition(entries: readonly QueueEntry[], id: string, now: number): number | undefined;
+export declare function isHead(entries: readonly QueueEntry[], id: string, now: number): boolean;
+/** Why a polling claim has no device yet although the host has room: nothing to reserve. */
+export declare const DEVICE_WAIT_REASONS: readonly ["device-limit", "requester-limit", "waiting-for-device"];
+export type DeviceWaitReason = (typeof DEVICE_WAIT_REASONS)[number];
+/**
+ * Why a claim is not running yet. Queued for host capacity: behind an earlier claim, or the resource the
+ * host is out of. Polling for a device: the pool is at `--max`, the owner is at its limit, or a physical
+ * device is not free / ready.
+ */
+export type WaitReason = "behind-earlier" | CapacityReason | DeviceWaitReason;
+export declare const isWaitReason: (s: string) => s is WaitReason;
+export declare const isDeviceWaitReason: (reason: WaitReason | undefined) => reason is DeviceWaitReason;
+/**
+ * Rows that take part in admission order. A claim polling for a device holds a row so `warden queue` can
+ * show why it waits, but it needs no boot slot: it is never ahead of, or counted against, a claim that does.
+ */
+export declare const admissionQueue: (entries: readonly QueueEntry[]) => QueueEntry[];

package/types/core/src/store.d.ts

@@ -1,9 +1,21 @@
 import { Database } from "bun:sqlite";
+import { type EventFilter, type LeaseEvent, type NewLeaseEvent } from "./lease-events";
 import { type PidAlive } from "./liveness";
+import { type WaitReason } from "./queue";
 import type { Lease, Owner, Platform, QueueEntry, Resource } from "./types";
 /** `$WARDEN_HOME`, else `~/.warden`. */
 export declare function wardenHome(env?: Record<string, string | undefined>): string;
 export declare function defaultDbPath(env?: Record<string, string | undefined>): string;
+/** An owner's idempotency key and the claim it created (one row per key, however many leases the claim holds). */
+export type ClaimKey = {
+    ownerKey: string;
+    key: string;
+    claimId: string;
+    platform: string;
+    profile: string;
+    count: number;
+    ready: boolean;
+};
 /**
  * Ordered schema migrations; index + 1 = `PRAGMA user_version` after applying. Append only — never
  * edit an entry that has shipped.
@@ -12,6 +24,11 @@ export declare const MIGRATIONS: readonly string[];
 /** A queued claim that has not refreshed within this long is dead (its waiter polls every few seconds). */
 export declare const QUEUE_TTL_MS = 60000;
 export declare function ownerKey(owner: Owner): string;
+/** Why leases are being deleted when it is history worth logging (see `Store.deleteLeases`). */
+export type LeaseEnd = {
+    type: "released" | "expired";
+    now: number;
+};
 export type NewLease = {
     resource: Resource;
     owner: Owner;
@@ -20,6 +37,7 @@ export type NewLease = {
     pid?: number;
     bootedByOwner?: boolean;
     shared?: boolean;
+    claimId?: string;
 };
 /** A device warden created (sim) or launched (emulator). */
 export type DeviceRecord = {
@@ -35,6 +53,8 @@ export type DeviceRecord = {
     quarantineReason?: string;
     /** set while the simulator's daemons are switched off (`sim slim`); cleared by `--restore` */
     slimmedAt?: number;
+    /** set when `warden dev` took the sim: kept on shutdown (not ephemeral) so installs and logins survive */
+    persistentAt?: number;
 };
 export declare function newLeaseId(): string;
 /**
@@ -61,7 +81,29 @@ export declare class Store {
     listLeases(): Lease[];
     listLeasesByOwner(owner: Owner): Lease[];
     findLeaseByResource(resource: Resource): Lease | undefined;
-    deleteLeases(ids: readonly string[]): number;
+    /**
+     * Delete leases. With `end`, a device lease that was granted (has a `granted` event) also logs `end.type`
+     * in the same transaction. Without it nothing is logged: rollbacks, create placeholders, eviction holds,
+     * ports and build locks are not lease history.
+     */
+    deleteLeases(ids: readonly string[], end?: LeaseEnd): number;
+    private recordLeaseEnd;
+    /** Append one lease event (join the caller's transaction when there is one). */
+    recordEvent(event: NewLeaseEvent): void;
+    /** `queued` is logged once per claim call (its queue row is refreshed every round): false when already there. */
+    recordQueuedOnce(event: Extract<NewLeaseEvent, {
+        type: "queued";
+    }>): boolean;
+    /**
+     * A holder's heartbeat found these leases gone: log `heartbeat_lost` for those no longer held, copying
+     * who/what from their `granted` event. Returns how many were logged.
+     */
+    recordHeartbeatLost(ids: readonly string[], now: number): number;
+    /** The `heartbeat_lost` event of a granted lease (who/what copied from its grant); undefined for one never granted (ports, builds). */
+    private heartbeatLostEvent;
+    listEvents(filter?: EventFilter): LeaseEvent[];
+    /** Delete events older than `before` (ms). */
+    pruneEvents(before: number): number;
     /**
      * Stamp `heartbeat_at = now` on `ids`; returns how many leases were updated (fewer than `ids` = some
      * were released). `periodMs` (the holder's heartbeat interval) marks them supervised: with a pid,
@@ -72,8 +114,17 @@ export declare class Store {
     reclaimStale(now: number, pidAlive: PidAlive): string[];
     /** Insert a queue row; an existing id keeps its `enqueuedAt` (queue age) and updates the rest. */
     enqueue(entry: QueueEntry): QueueEntry;
-    /** Stamp `heartbeat_at`; false when the row is gone (reclaimed or dequeued). */
-    refreshQueue(id: string, now: number): boolean;
+    /** Stamp `heartbeat_at` and the live wait `reason`; false when the row is gone (reclaimed or dequeued). */
+    refreshQueue(id: string, now: number, reason?: WaitReason): boolean;
+    /** The claim an owner's idempotency key points at (caller holds the transaction), if any. */
+    getClaimKey(ownerKey: string, key: string): ClaimKey | undefined;
+    /** Point (owner, key) at a claim, replacing a stale mapping; `ready` stays false until the claim is granted. */
+    setClaimKey(entry: Omit<ClaimKey, "ready">, now: number): void;
+    /** The claim's leases are all granted: a repeat of its key now returns them. */
+    markClaimKeyReady(claimId: string): void;
+    deleteClaimKey(ownerKey: string, key: string): void;
+    /** Forget the keys of a claim that failed (its leases are gone). */
+    deleteClaimKeysOf(claimId: string): void;
     dequeue(id: string): boolean;
     /** Raw insertion order (`enqueued_at`, id); use `queueOrder` for admission order. */
     listQueue(): QueueEntry[];
@@ -83,11 +134,16 @@ export declare class Store {
     listDevices(platform?: Platform): DeviceRecord[];
     touchDevice(platform: Platform, id: string, now: number): void;
     /** Quarantine a warden device (recording it first when only its name marked it ours). */
-    quarantineDevice(device: Omit<DeviceRecord, "createdAt" | "lastUsedAt" | "quarantinedAt" | "quarantineReason" | "slimmedAt">, reason: string | undefined, now: number): void;
+    quarantineDevice(device: Omit<DeviceRecord, "createdAt" | "lastUsedAt" | "quarantinedAt" | "quarantineReason" | "slimmedAt" | "persistentAt">, reason: string | undefined, now: number): void;
     /** Clear quarantine on every recorded device with this id (any platform); returns how many were cleared. */
-    unquarantineDevice(id: string): number;
+    unquarantineDevice(id: string, now: number): number;
     /** Record (`at` set) or clear (`at` undefined) that a recorded device's daemons are slimmed. */
     setSlimmed(platform: Platform, id: string, at: number | undefined): void;
+    /**
+     * Mark a recorded device persistent (never deleted as ephemeral). Update-only: a record is what makes a device
+     * warden-created (`shouldShutdown`), so a sim that was already running when leased must not gain one here.
+     */
+    markPersistent(platform: Platform, id: string, now: number): void;
     forgetDevice(platform: Platform, id: string): void;
     /**
      * What a `warden gc` pass could find to do, from the store alone (no simulator is asked):