@delacour/warden-e2e 0.6.0 → 0.8.0

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

@@ -0,0 +1,42 @@
+import type { NetworkCondition, NetworkPreset } from "./conditions.types";
+/**
+ * One table for every layer that applies a network condition: the Android emulator console (`emu network
+ * speed|delay`, COND-3), the per-lease shaping proxy (COND-4) and the iOS per-app routing (COND-5).
+ *
+ * Shaping units: `latencyMs` is the added round-trip time, `jitterMs` the +/- spread on it, kbps are
+ * kilobits per second (0 = unlimited), `lossPct` is 0-100. The emulator console's `delay` is per packet, so
+ * its `min:max` is half the round trip, widened by the jitter.
+ *
+ * Sources: Apple Network Link Conditioner profiles (edge, 3g, lte, wifi, lossy = "Very Bad Network"),
+ * Chrome DevTools "Slow 3G" (400 kbps both ways, 2000 ms), WebPageTest "4G" (9 Mbps, 170 ms RTT).
+ */
+export type NetworkShaping = {
+    latencyMs: number;
+    jitterMs: number;
+    downKbps: number;
+    upKbps: number;
+    lossPct: number;
+};
+/** Arguments for `adb emu network speed <speed>` and `... delay <delay>`. */
+export type EmuNetwork = {
+    speed: string;
+    delay: string;
+};
+export type NetworkPresetSpec = {
+    emu: EmuNetwork;
+    shaping: NetworkShaping;
+};
+export declare const NETWORK_PRESET_NAMES: readonly NetworkPreset[];
+export declare const NETWORK_PRESETS: Readonly<Record<NetworkPreset, NetworkPresetSpec>>;
+/** What a condition means for a device: no network at all, or shaped (all zeros = unshaped) with the emulator args. */
+export type NetworkPlan = {
+    online: false;
+} | ({
+    online: true;
+} & NetworkPresetSpec);
+/**
+ * The effective parameters of a condition. `custom` names only what it changes (the rest is unshaped, a
+ * direction left out takes the other's rate for the emulator); `flap` resolves to its up phase, because the
+ * scheduler (COND-6) drives the transitions as plain online/offline conditions.
+ */
+export declare function resolveNetwork(condition: NetworkCondition): NetworkPlan;

package/types/core/src/conditions/text-size.d.ts

@@ -0,0 +1,19 @@
+import { type Result } from "../../../types/src/result";
+import { TEXT_SIZE_NAMES, type TextSize } from "./conditions.types";
+/** Approximate font scale of each iOS content size category (UIFontMetrics body text; 1 = `large`, the default). */
+export declare const TEXT_SIZE_SCALE: Record<(typeof TEXT_SIZE_NAMES)[number], number>;
+/** The largest `font_scale` Android's own settings offer; asking for more is clamped to it. */
+export declare const ANDROID_MAX_FONT_SCALE = 2;
+export declare const ANDROID_MIN_FONT_SCALE = 0.5;
+export type ResolvedTextSize = {
+    /** iOS content size category (the nearest one for a number) */
+    category: (typeof TEXT_SIZE_NAMES)[number];
+    /** font scale (the category's for a name) */
+    scale: number;
+};
+/** A name or a scale as both: the category iOS needs and the scale Android needs. */
+export declare function resolveTextSize(size: TextSize): Result<ResolvedTextSize>;
+/** Android's `font_scale` for `scale`, clamped to what the platform takes. */
+export declare const androidFontScale: (scale: number) => number;
+/** The part of an a11y request the platform applied (a skipped setting is not on the device, so not recorded). */
+export declare function appliedA11y<T extends object>(op: T, applied: readonly string[]): Partial<T>;

package/types/core/src/golden/android-biometrics.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Android fingerprint enrollment for the golden build emulator: set a screen-lock PIN, open the system
+ * enrollment wizard, answer its screens (PIN entry, Next/Agree/Done) and present the virtual finger until
+ * `dumpsys fingerprint` reports one enrolled. Slow (tens of seconds), so it runs once in the snapshot build
+ * and claims start enrolled. Idempotent: an already enrolled device is left alone. Emulator serials only.
+ */
+import { type AsyncResult } from "../../../types/src/result";
+import type { Exec } from "../exec";
+/**
+ * Whether `dumpsys fingerprint` lists an enrolled fingerprint: the JSON `"prints":[{"id":0,"count":N,…}]` of Android 10+
+ * (`count` = fingerprints enrolled for that user) or the older `Enrolled fingerprints: N` / `prints: N` lines.
+ */
+export declare function parseFingerprintEnrolled(dump: string): boolean;
+export type TapTarget = {
+    label: string;
+    x: number;
+    y: number;
+};
+/** Centre of the first wizard button in a `uiautomator dump`. */
+export declare function findTapTarget(xml: string): TapTarget | undefined;
+/** The lock-screen credential entry the wizard asks before it starts. */
+export declare function isPinEntry(xml: string): boolean;
+export type EnrollDeps = {
+    exec: Exec;
+    sleep: (ms: number) => Promise<void>;
+    /** the adb binary (`androidTools(env).adb`) */
+    adb: string;
+    /** wizard rounds before giving up (default 60) */
+    maxSteps?: number;
+    /** pause after each round (default 700 ms) */
+    stepMs?: number;
+};
+export declare function enrollFingerprint(deps: EnrollDeps, serial: string): AsyncResult<{
+    alreadyEnrolled: boolean;
+}>;

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/classify.d.ts

@@ -0,0 +1,7 @@
+import type { RunnerBuildError } from "./runner-build.types";
+/** `Unlock Chris's iPhone to Continue`: xcodebuild waits for the passcode and never says it is locked any other way. */
+export declare const UNLOCK_LINE: RegExp;
+/** The known failure in xcodebuild's / devicectl's output, or undefined for one warden has no fix for. */
+export declare function classifyRunnerOutput(text: string): RunnerBuildError | undefined;
+/** The last `lines` lines of the output: what `build_failed` shows when nothing classifies. */
+export declare function outputTail(text: string, lines?: number): string;

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/runner-build.types.d.ts

@@ -0,0 +1,76 @@
+import type { AsyncResult } from "../../../types/src/result";
+import type { BuildLockDeps } from "../builds/lock";
+import type { Exec } from "../exec";
+/** Codes `classify.ts` and `signing.ts` give a failure that has a known fix; every one comes with a `hint`. */
+export declare const CLASSIFIED_RUNNER_ERRORS: readonly ["no_account", "no_team", "ios_team_ambiguous", "bundle_id_taken", "device_locked", "developer_mode_off", "runner_untrusted", "ui_automation_disabled", "device_busy", "ddi_unavailable", "unsupported_os"];
+export type ClassifiedRunnerErrorCode = (typeof CLASSIFIED_RUNNER_ERRORS)[number];
+/** A team the keychain holds an `Apple Development` identity for. */
+export type SigningTeam = {
+    teamId: string;
+    identities: string[];
+};
+type RunnerErrorBase = {
+    message: string;
+    hint: string;
+};
+/**
+ * Why the on-device runner cannot be built / signed / started. `hint` is the one thing to do about it.
+ * `ios_team_ambiguous` carries the teams to pick from; `build_failed` is anything unclassified (with the
+ * tail of the output).
+ */
+export type RunnerBuildError = (RunnerErrorBase & {
+    code: Exclude<ClassifiedRunnerErrorCode, "ios_team_ambiguous">;
+}) | (RunnerErrorBase & {
+    code: "ios_team_ambiguous";
+    teams: SigningTeam[];
+}) | (RunnerErrorBase & {
+    code: "build_failed";
+    output: string;
+});
+export type RunnerBuildErrorCode = RunnerBuildError["code"];
+/** Where the signing team came from. */
+export type TeamSource = "input" | "env" | "config" | "keychain";
+/** The runner sources as a map of path (relative to the staged root, `/`-separated) to text. */
+export type RunnerSourceFiles = Readonly<Record<string, string>>;
+export type EnsureRunnerBuildInput = {
+    /** the phone the runner must be signed for (`-destination id=`; registers it in the provisioning profile) */
+    udid: string;
+    /** signing team; default: `WARDEN_IOS_TEAM_ID`, then `ios.teamId`, then the keychain */
+    team?: string | undefined;
+    /** `ios.teamId` of `warden.config.ts` */
+    configTeamId?: string | undefined;
+    /** `ios.runnerBundleId` of `warden.config.ts` */
+    configBundleId?: string | undefined;
+    env: Record<string, string | undefined>;
+    /** `$WARDEN_HOME` (default: from `env`) */
+    home?: string | undefined;
+    exec: Exec;
+    /** warden's own version (part of the staged-source directory name) */
+    version: string;
+    /** the embedded runner sources (blob in a compiled binary, the checkout when run from source) */
+    loadSources: () => AsyncResult<RunnerSourceFiles>;
+    /** serialises builds of one (team, Xcode, sources): the build lease */
+    lock: BuildLockDeps;
+    now?: () => number;
+    /** progress lines (xcodebuild's own output is not forwarded) */
+    log?: (line: string) => void;
+    /** `xcodebuild` is stopped after this long (default 15 min) */
+    timeoutMs?: number;
+    /** after xcodebuild asks to unlock the phone, wait this long before giving up with `device_locked` (default 45 s) */
+    lockGraceMs?: number;
+};
+/** A runner build ready for `xcodebuild test-without-building -xctestrun <xctestrun>`. */
+export type RunnerBuild = {
+    /** the `.xctestrun` inside `derivedData` */
+    xctestrun: string;
+    derivedData: string;
+    /** the host app's bundle id (the UI-test bundle is `<id>.uitests`, its runner app `<id>.uitests.xctrunner`) */
+    bundleId: string;
+    team: string;
+    teamSource: TeamSource;
+    /** false: built just now */
+    cached: boolean;
+    /** why it was (re)built when `cached` is false */
+    rebuiltBecause?: "none" | "new_udid" | "profile_expiring" | "bundle_id" | "missing";
+};
+export {};

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/netproxy/control.d.ts

@@ -0,0 +1,75 @@
+import { type AsyncResult } from "../../../types/src/result";
+import { z } from "zod";
+import type { HostFault } from "../conditions/conditions.types";
+import type { ProxyConditions, ShapingParams } from "./shaping";
+/** Where a running proxy listens and how to steer it. Persisted as JSON so another process can find it. */
+export type ProxyHandle = {
+    pid: number;
+    /** loopback address the proxy and control channel bind */
+    host: string;
+    /** the forward proxy: what a device's HTTP proxy setting points at */
+    port: number;
+    /** loopback HTTP control channel */
+    controlPort: number;
+    /** required as `x-warden-token` on every control call */
+    token: string;
+};
+export type ProxyStats = {
+    connections: number;
+    resets: number;
+    stalls: number;
+    faulted: number;
+    bytesUp: number;
+    bytesDown: number;
+};
+export type ProxyStatus = ProxyConditions & {
+    pid: number;
+    stats: ProxyStats;
+};
+/** Replace `params` and/or `faults`; an omitted field keeps its current value. */
+export type ConditionsUpdate = {
+    params?: ShapingParams;
+    faults?: readonly HostFault[];
+};
+export declare const conditionsUpdateSchema: z.ZodObject<{
+    params: z.ZodOptional<z.ZodObject<{
+        latencyMs: z.ZodOptional<z.ZodNumber>;
+        jitterMs: z.ZodOptional<z.ZodNumber>;
+        downKbps: z.ZodOptional<z.ZodNumber>;
+        upKbps: z.ZodOptional<z.ZodNumber>;
+        lossPct: z.ZodOptional<z.ZodNumber>;
+        offline: z.ZodOptional<z.ZodEnum<{
+            blackhole: "blackhole";
+            refuse: "refuse";
+        }>>;
+    }, z.core.$strict>>;
+    faults: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        match: z.ZodString;
+        action: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"status">;
+            code: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"reset">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"delay">;
+            ms: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"blackhole">;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** What the control server needs from the proxy it steers. */
+export type ControlApi = {
+    status(): ProxyStatus;
+    update(update: ConditionsUpdate): void;
+    shutdown(): void;
+};
+/** Loopback HTTP control channel: `GET /status`, `PUT /conditions`, `POST /shutdown`; token-guarded. */
+export declare function serveControl(api: ControlApi, token: string, host: string): Bun.Server<undefined>;
+/** Live-reconfigure a running proxy without dropping its listener or open connections. */
+export declare function setProxyConditions(handle: ProxyHandle, update: ConditionsUpdate): AsyncResult<ProxyStatus>;
+export declare function getProxyStatus(handle: ProxyHandle): AsyncResult<ProxyStatus>;
+/** Ask the proxy to close its listeners and exit. */
+export declare function stopProxy(handle: ProxyHandle): AsyncResult<{
+    ok: true;
+}>;

package/types/core/src/netproxy/decide.d.ts

@@ -0,0 +1,22 @@
+import type { ProxyEvent } from "./proxy";
+import { type ProxyConditions, type Rng } from "./shaping";
+/** What to do with one request once its target host is known. */
+export type Verdict = {
+    act: {
+        kind: "reset";
+    } | {
+        kind: "hold";
+    } | {
+        kind: "status";
+        code: number;
+    } | {
+        kind: "go";
+    };
+    /** delay before the act: params latency (+ a `delay` fault) */
+    waitMs: number;
+    event?: ProxyEvent;
+    /** which counter to bump */
+    count?: "faulted" | "resets";
+};
+/** Faults first (first glob match wins), then connection loss, then plain latency. */
+export declare function decide(conditions: ProxyConditions, host: string, isConnect: boolean, rng: Rng): Verdict;

package/types/core/src/netproxy/handle-file.d.ts

@@ -0,0 +1,12 @@
+import type { ProxyHandle } from "./control";
+/** `$WARDEN_HOME/netproxy/<leaseId>.json`: how another warden process finds a lease's proxy. */
+export declare function handlePath(leaseId: string, env?: Record<string, string | undefined>): string;
+/** What `netproxy.main.ts` writes once it is listening. `portLeaseId` is added by `ensureLeaseProxy`. */
+export type HandleFile = ProxyHandle & {
+    leaseId: string;
+    portLeaseId?: string;
+};
+/** Atomic (tmp + rename) and owner-only: the file carries the control token. */
+export declare function writeHandleFile(path: string, data: HandleFile): void;
+export declare function readHandleFile(path: string): HandleFile | undefined;
+export declare function removeHandleFile(path: string): void;