@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.9

package/out/pack/governor.js

@@ -0,0 +1,309 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveDenyMode = effectiveDenyMode;
+exports.createGovernor = createGovernor;
+exports.withGovernor = withGovernor;
+const caps_1 = require("./caps");
+const lease_1 = require("./lease");
+/**
+ * What a deny mode MEANS on this deployment, as opposed to what it was written as.
+ *
+ * Without a sandbox driver there is no non-cooperative way to stop a turn already executing in
+ * this process, so `kill` degrades to `drain`. The degradation is real and unavoidable at this
+ * layer; what is not acceptable is reporting `kill` while doing `drain`.
+ */
+function effectiveDenyMode(mode, supportsInFlightTermination) {
+    if (mode === 'kill' && !supportsInFlightTermination) {
+        return 'drain';
+    }
+    return mode;
+}
+function createGovernor(opts) {
+    const meter = new caps_1.CapMeter(opts.caps);
+    // Not const: every lease poll re-merges the control plane's caps over the local ones.
+    let unbounded = (0, caps_1.capsAreUnbounded)(opts.caps);
+    let timer;
+    /** Latches once the lease kills us: no further turn may sneak through between polls. */
+    let killed;
+    /** Last lease seen, so per-session deny checks need no fetch on the turn path. */
+    let currentLease;
+    /**
+     * sessionKey → the verified user it belongs to, learned from `admitTurn`.
+     *
+     * Only the turn path knows the resolved identity, but the lease WATCHER is what ends running
+     * work — so without remembering it, a `user`-scoped kill could refuse the next turn and still
+     * leave the user's live sandbox running.
+     */
+    const sessionUsers = new Map();
+    /** True unless the deployment has no way to end a running turn — see GovernableSandboxes. */
+    const canTerminateInFlight = opts.sandboxes.supportsInFlightTermination !== false;
+    /** Session rules extended to the users behind them, so id rotation does not escape. */
+    let followedUsers = new Map();
+    /** Kill rules already reported as degraded, so the warning is loud once, not every poll. */
+    const degradedKillsReported = new Set();
+    const audit = (event, fields) => {
+        try {
+            opts.audit?.(event, fields);
+        }
+        catch { /* evidence must never break enforcement */ }
+    };
+    /**
+     * Bounded on purpose: a long-lived serve sees unbounded distinct session keys (every anonymous
+     * gateway sender gets a fresh uuid), and an unbounded map here would be a slow leak in the one
+     * component that must never be the reason an instance falls over. Oldest-first eviction costs
+     * only the ability to kill an already-idle session by user scope.
+     */
+    const MAX_TRACKED_SESSION_USERS = 10_000;
+    const rememberSessionUser = (sessionKey, userId) => {
+        if (sessionUsers.size >= MAX_TRACKED_SESSION_USERS && !sessionUsers.has(sessionKey)) {
+            const oldest = sessionUsers.keys().next();
+            if (!oldest.done) {
+                sessionUsers.delete(oldest.value);
+            }
+        }
+        sessionUsers.set(sessionKey, userId);
+    };
+    const enforce = async (sessionKey, decision) => {
+        // The MERGED policy, not the local one: a control plane that escalates revoke → destroy
+        // must be obeyed on the next breach, not on the next restart.
+        const action = meter.policy().onBreach ?? 'revoke-inference';
+        try {
+            if (action === 'destroy-sandbox') {
+                // The SANDBOX is destroyed; the session's meter deliberately survives it.
+                // `meter.forget` here reset turns and the duration clock, so a breached session got
+                // a brand-new budget and `maxTurnsPerSession: 10` degraded into "one refused turn
+                // every ten, forever" — a cap that renews on breach is not a cap.
+                await opts.sandboxes.destroySession(sessionKey);
+            }
+            else {
+                // Narrower: the session keeps its sandbox (and its state, for inspection) but loses
+                // the model route, so it cannot spend another token.
+                await opts.sandboxes.revokeRoute(sessionKey, 'inference');
+            }
+        }
+        catch (err) {
+            // A tier-0 sandbox cannot revoke a single route; falling back to destroy keeps the cap
+            // honest instead of silently letting the session continue.
+            opts.logger?.warn(`[Governor] ${action} failed for ${sessionKey}, destroying instead: ${err instanceof Error ? err.message : String(err)}`);
+            await opts.sandboxes.destroySession(sessionKey).catch(() => undefined);
+            // Same rule as the deliberate destroy above: the meter outlives the sandbox, or the
+            // fallback path quietly hands back the budget the primary path refused.
+        }
+        opts.logger?.warn(`[Governor] cap breach on ${sessionKey}: ${decision.reason} — ${action}`);
+        audit('cap_breach', { sessionKey, cap: decision.cap, reason: decision.reason, action });
+    };
+    const killAll = async (reason) => {
+        const live = opts.sandboxes.sandboxes();
+        for (const c of live) {
+            await opts.sandboxes.destroySession(c.sessionKey).catch(() => undefined);
+            // The meter deliberately SURVIVES the kill, for exactly the reason `enforce` gives when
+            // it destroys a sandbox on a cap breach: a cap that renews when the sandbox goes away is
+            // not a cap. `meter.forget` here meant a kill-then-restore (a billing hold lifted, a
+            // drill, an operator toggling the switch) handed every session a brand-new turn and
+            // duration budget — so the cheapest way past a cap was to trip the kill switch. The two
+            // paths now agree: destroying a sandbox never returns budget.
+        }
+        if (live.length > 0) {
+            opts.logger?.warn(`[Governor] kill switch: destroyed ${live.length} live sandbox(s) — ${reason}`);
+        }
+        else if (!canTerminateInFlight) {
+            // Without a driver there is nothing to destroy, and the kill switch reduces to refusing
+            // the next turn. Say so rather than logging a successful stop of zero sandboxes.
+            opts.logger?.warn(`[Governor] kill switch: no sandbox driver, so nothing running can be stopped — ` +
+                `in-flight turns will finish and only NEW turns are refused (${reason}). Run with --sandbox for true in-flight kill.`);
+        }
+        audit('kill_switch', { reason, destroyed: live.length, inFlightTerminated: canTerminateInFlight });
+        return live.length;
+    };
+    const checkLease = async () => {
+        if (!opts.getLease) {
+            return;
+        }
+        try {
+            const lease = await opts.getLease();
+            // Adopt caps the control plane has pushed since boot. Same tighten-only merge as at
+            // construction, re-applied every poll: an operator who lowers a cap in the console
+            // must not have to restart the fleet for it to bite. Without this the instance
+            // reported the new policy while enforcing the boot-time one.
+            const merged = (0, caps_1.mergeCaps)(lease?.caps, opts.caps);
+            meter.setCaps(merged);
+            unbounded = (0, caps_1.capsAreUnbounded)(merged);
+            // Cache the deny rules so `admitTurn` stays synchronous and cheap: enforcement latency
+            // is the poll interval, exactly like the kill switch, rather than a fetch per turn.
+            currentLease = lease;
+            // Recomputed each poll from what the turn path has learned, so a session stop reaches the
+            // user's other sessions even after they rotate `session_id`.
+            followedUsers = (0, lease_1.resolveFollowedUsers)(lease, sessionUsers);
+            // A `kill` rule this deployment cannot honour must not be reported as honoured. Warn
+            // once per rule, before sweeping, so an operator learns immediately that the rule they
+            // just published means `drain` here.
+            if (!canTerminateInFlight) {
+                for (const rule of lease?.deny ?? []) {
+                    if (rule.mode !== 'kill') {
+                        continue;
+                    }
+                    const id = `${rule.scope}:${rule.match}`;
+                    if (degradedKillsReported.has(id)) {
+                        continue;
+                    }
+                    degradedKillsReported.add(id);
+                    opts.logger?.warn(`[Governor] deny(kill) on ${id} DEGRADED TO DRAIN: this deployment has no sandbox driver, so a turn ` +
+                        'already executing cannot be stopped. It will run to completion; only the next turn is refused. ' +
+                        'Run serve with --sandbox for a kill that ends work mid-flight.');
+                    audit('deny_kill_degraded', { scope: rule.scope, match: rule.match, effectiveMode: 'drain' });
+                }
+            }
+            // `kill` rules end work already running. `drain` deliberately does not — it lets the
+            // in-flight turn finish and only refuses the next one.
+            for (const sandbox of opts.sandboxes.sandboxes()) {
+                const v = (0, lease_1.denyVerdict)(lease, {
+                    sessionKey: sandbox.sessionKey,
+                    pack: opts.pack ?? '',
+                    userHash: opts.userHash,
+                    // Remembered from this session's turns, so a `user`-scoped kill reaches a
+                    // gateway session whose key carries no `u<hash>--` prefix to read it off.
+                    userId: sessionUsers.get(sandbox.sessionKey),
+                    followedUsers,
+                });
+                if (v.denied && effectiveDenyMode(v.mode, canTerminateInFlight) === 'kill') {
+                    await opts.sandboxes.destroySession(sandbox.sessionKey).catch(() => undefined);
+                    sessionUsers.delete(sandbox.sessionKey);
+                    // The meter survives, same rule as `killAll` and `enforce`: a stop order must not
+                    // hand the session a fresh budget when it is lifted.
+                    opts.logger?.warn(`[Governor] deny(kill) destroyed ${sandbox.sandboxId} — ${v.reason}`);
+                    audit('session_killed', { sessionKey: sandbox.sessionKey, sandboxId: sandbox.sandboxId, reason: v.reason });
+                }
+            }
+            const verdict = (0, lease_1.leaseIsDead)(lease);
+            if (verdict.dead) {
+                killed = verdict.reason ?? 'lease revoked';
+                await killAll(killed);
+            }
+            else if (killed) {
+                // A restored lease lifts the latch — an operator can turn the fleet back on
+                // without restarting every instance.
+                opts.logger?.info('[Governor] lease restored — accepting turns again');
+                audit('kill_switch_lifted', {});
+                killed = undefined;
+            }
+        }
+        catch (err) {
+            // Fail-open on transport, exactly like the lease source: a control-plane outage must
+            // not take a customer's fleet down.
+            opts.logger?.warn(`[Governor] lease check failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    return {
+        async admitTurn(sessionKey, userId) {
+            if (killed) {
+                return { allowed: false, reason: `stopped by the control plane: ${killed}` };
+            }
+            if (userId) {
+                rememberSessionUser(sessionKey, userId);
+            }
+            // Scoped stop orders refuse NEW work in both modes; the difference between drain and
+            // kill is only what happened to the turn already running, decided at the last poll.
+            const denied = (0, lease_1.denyVerdict)(currentLease, {
+                sessionKey,
+                pack: opts.pack ?? '',
+                userHash: opts.userHash,
+                userId: userId ?? sessionUsers.get(sessionKey),
+                // A session stop follows the user, so sending a fresh `session_id` does not escape it.
+                // Recomputed here as well as on the poll because the identity behind THIS session may
+                // only just have become known — waiting a poll would admit exactly the turn we are
+                // trying to refuse.
+                followedUsers: (0, lease_1.resolveFollowedUsers)(currentLease, sessionUsers),
+            });
+            if (denied.denied) {
+                return { allowed: false, reason: denied.reason };
+            }
+            // What is running, not just whether it may run: signature + pin, for the no-sandbox
+            // path where nothing else asks. Before the caps check, because an unsigned or
+            // unpinned pack must be refused whether or not the session has budget left.
+            if (opts.admitPack) {
+                // The lease the poll last saw — the SAME view the kill and deny checks just used,
+                // and no fetch on the turn path.
+                const packVerdict = opts.admitPack(sessionKey, currentLease);
+                if (!packVerdict.allowed) {
+                    return { allowed: false, reason: packVerdict.reason ?? 'refused by pack admission' };
+                }
+            }
+            if (unbounded) {
+                return { allowed: true };
+            }
+            const decision = meter.check(sessionKey, opts.sandboxes.sandboxes().length);
+            if (!decision.allowed) {
+                // Concurrency is a "come back later" refusal about the INSTANCE — there is no
+                // offending session to punish, and revoking someone else's route would be wrong.
+                if (decision.cap !== 'concurrency') {
+                    await enforce(sessionKey, decision);
+                }
+            }
+            return decision;
+        },
+        recordTurn(sessionKey) {
+            // Always meter, even while unbounded: caps can be tightened mid-flight from the
+            // control plane, and a session must not get a clean slate the moment one appears.
+            meter.record(sessionKey);
+        },
+        killAll,
+        refresh: checkLease,
+        start() {
+            if (!opts.getLease || timer) {
+                return;
+            }
+            // One constant for the poll interval, shared with the lease source's cache — see
+            // DEFAULT_LEASE_POLL_SECONDS. These two used to disagree (30 vs 60) and the banner
+            // printed the smaller one.
+            const everyMs = (0, lease_1.resolveLeasePollSeconds)(opts.pollSeconds) * 1000;
+            timer = setInterval(() => { void checkLease(); }, everyMs);
+            timer.unref?.();
+            void checkLease();
+        },
+        stop() {
+            if (timer) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+        },
+        // The caps ACTUALLY in force, which after a poll may be tighter than the boot-time ones.
+        policy: () => meter.policy(),
+    };
+}
+/**
+ * Put the governor in front of a runner, so every turn passes the gate no matter which endpoint
+ * it arrived on. serve has three call sites into `runner.run`; decorating the runner covers all
+ * of them and cannot be forgotten when a fourth is added — the same relocation trick
+ * `createSandboxRunner` uses one layer down.
+ */
+function withGovernor(runner, governor) {
+    return {
+        async run(options) {
+            const sessionKey = options.sessionId ?? 'default';
+            // The identity serve resolved for this turn — what makes "stop this user" exact.
+            const decision = await governor.admitTurn(sessionKey, options.analyticsUserId);
+            if (!decision.allowed) {
+                // A refusal is a normal, reportable outcome — not an exception. The caller turns
+                // this into a 429/403 with the operator's reason intact.
+                return {
+                    success: false,
+                    text: '',
+                    thinking: '',
+                    toolCalls: [],
+                    error: decision.reason ?? 'refused by policy',
+                };
+            }
+            // Counted BEFORE the turn runs: a turn that crashes or is aborted still consumed the
+            // budget, and not counting it would let a session retry past its cap forever.
+            governor.recordTurn(sessionKey);
+            return runner.run(options);
+        },
+        dispose() {
+            governor.stop();
+            runner.dispose();
+        },
+    };
+}

package/out/pack/lease-schema.js

@@ -0,0 +1,270 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DENY_SCOPE_ALIASES = exports.DENY_MODE_ALIASES = exports.STRICTEST_DENY_MODE = exports.DENY_MODES = exports.DENY_SCOPES = exports.STRICTEST_ON_BREACH = exports.ON_BREACH_ALIASES = exports.ON_BREACH_ACTIONS = exports.DEPRECATED_CAP_SPELLINGS = exports.LEASE_CAP_ALIASES = exports.LEASE_CAP_FIELDS = void 0;
+exports.parseCapPolicy = parseCapPolicy;
+exports.parseLease = parseLease;
+// ---------------------------------------------------------------------------------------------
+// Vocabulary tables — extend these, not the code below
+// ---------------------------------------------------------------------------------------------
+/** Numeric cap fields, and what a valid value looks like. */
+exports.LEASE_CAP_FIELDS = {
+    maxTurnsPerSession: { kind: 'positive-int' },
+    maxSessionSeconds: { kind: 'positive-int' },
+    maxConcurrentSandboxes: { kind: 'positive-int' },
+};
+/**
+ * Alternative spellings for cap fields, mapped onto the canonical name.
+ *
+ * The extension point for vocabulary migrations. Adding a row is the entire change — there is no
+ * second place that reads a cap field, so an alias added here works for leases, env and CLI flags
+ * at once.
+ */
+exports.LEASE_CAP_ALIASES = {
+    /** Pre-rename vocabulary: a "cell" is what a sandbox used to be called. */
+    maxConcurrentCells: 'maxConcurrentSandboxes',
+};
+/** Deprecated cap spellings → the message an operator should see. Keyed by the OLD name. */
+exports.DEPRECATED_CAP_SPELLINGS = {
+    maxConcurrentCells: 'maxConcurrentSandboxes',
+    AGENTHIPPO_MAX_CONCURRENT_CELLS: 'AGENTHIPPO_MAX_CONCURRENT_SANDBOXES',
+    'destroy-cell': 'destroy-sandbox',
+    '--max-concurrent-cells': '--max-concurrent-sandboxes',
+};
+/**
+ * Breach actions, ordered by STRICTNESS. An unrecognised value clamps to the highest strictness
+ * in this table, never to the lowest and never to "unset".
+ */
+exports.ON_BREACH_ACTIONS = {
+    'revoke-inference': { strictness: 1 },
+    'destroy-sandbox': { strictness: 2 },
+};
+/** Alternative spellings for breach actions. Same extension point as `LEASE_CAP_ALIASES`. */
+exports.ON_BREACH_ALIASES = {
+    /** Pre-rename vocabulary. Deliberately mapped rather than dropped: dropping it SOFTENED the action. */
+    'destroy-cell': 'destroy-sandbox',
+};
+/** The strictest action this build knows about — where an unrecognised value lands. */
+exports.STRICTEST_ON_BREACH = Object.keys(exports.ON_BREACH_ACTIONS)
+    .reduce((a, b) => (exports.ON_BREACH_ACTIONS[a].strictness >= exports.ON_BREACH_ACTIONS[b].strictness ? a : b));
+/** Deny-rule scopes. An unknown scope rejects the document — see rule 1 above. */
+exports.DENY_SCOPES = ['session', 'user', 'pack'];
+/** Deny-rule modes, ordered by strictness for the same reason `onBreach` is. */
+exports.DENY_MODES = { drain: { strictness: 1 }, kill: { strictness: 2 } };
+exports.STRICTEST_DENY_MODE = 'kill';
+/** Alternative spellings for deny modes / scopes, for the back-compat layer. */
+exports.DENY_MODE_ALIASES = {};
+exports.DENY_SCOPE_ALIASES = {};
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * A cap value the meter can actually compare against.
+ *
+ * Rejects — never coerces — strings. `parseInt("lots")` is NaN and `Number("")` is 0; both would
+ * turn a control-plane typo into a disabled or absurd cap. A cap that cannot be read is a lease
+ * that cannot be trusted.
+ */
+function parseCapNumber(field, raw) {
+    if (typeof raw !== 'number') {
+        return { ok: false, reason: `${field} must be a number, got ${typeof raw} (${JSON.stringify(raw)})` };
+    }
+    if (!Number.isFinite(raw)) {
+        return { ok: false, reason: `${field} must be finite, got ${raw}` };
+    }
+    if (raw <= 0) {
+        // 0 has meant "unlimited" for --max-turns-per-session since before caps existed, but from a
+        // control plane it is far more likely to be an unset field serialised as a number. Refuse
+        // rather than guess which meaning was intended.
+        return { ok: false, reason: `${field} must be greater than 0, got ${raw} (omit the field for "unbounded")` };
+    }
+    if (!Number.isInteger(raw)) {
+        return { ok: false, reason: `${field} must be a whole number, got ${raw}` };
+    }
+    return { ok: true, value: raw };
+}
+/**
+ * Validate a cap policy from an untrusted source.
+ *
+ * Also used by `capsFromEnv`, so a local flag and a control-plane field are held to exactly the
+ * same standard — the alternative is two vocabularies that drift.
+ */
+function parseCapPolicy(raw, where = 'caps') {
+    if (raw === undefined || raw === null) {
+        return { ok: true, caps: {}, warnings: [] };
+    }
+    if (!isPlainObject(raw)) {
+        return { ok: false, reason: `${where} must be an object` };
+    }
+    const warnings = [];
+    const caps = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (key === 'onBreach') {
+            continue;
+        }
+        const canonical = (key in exports.LEASE_CAP_FIELDS ? key : exports.LEASE_CAP_ALIASES[key]);
+        if (!canonical) {
+            // Unknown cap fields are TOLERATED (a newer control plane may send a cap this build does
+            // not implement) but never silently: an operator must be able to see that the bound they
+            // configured is not being enforced by this version.
+            warnings.push(`${where}.${key} is not a cap this build understands and is NOT being enforced`);
+            continue;
+        }
+        const parsed = parseCapNumber(`${where}.${key}`, value);
+        if (!parsed.ok) {
+            return { ok: false, reason: parsed.reason };
+        }
+        caps[canonical] = parsed.value;
+    }
+    const rawBreach = raw.onBreach;
+    if (rawBreach !== undefined && rawBreach !== null) {
+        if (typeof rawBreach !== 'string') {
+            return { ok: false, reason: `${where}.onBreach must be a string, got ${typeof rawBreach}` };
+        }
+        const canonical = (rawBreach in exports.ON_BREACH_ACTIONS ? rawBreach : exports.ON_BREACH_ALIASES[rawBreach]);
+        if (canonical) {
+            caps.onBreach = canonical;
+        }
+        else {
+            // FAIL CLOSED, LOUDLY. Leaving it unset let an unrecognised value fall through mergeCaps
+            // and soften the breach action from destroy-sandbox to revoke-inference — a typo in the
+            // control plane weakening enforcement is the exact failure mode this guards.
+            caps.onBreach = exports.STRICTEST_ON_BREACH;
+            warnings.push(`${where}.onBreach="${rawBreach}" is not an action this build understands. ` +
+                `Failing CLOSED to "${exports.STRICTEST_ON_BREACH}" (the strictest known action). ` +
+                `Known actions: ${Object.keys(exports.ON_BREACH_ACTIONS).join(', ')}.`);
+        }
+    }
+    return { ok: true, caps, warnings };
+}
+function parseDenyRule(raw, index) {
+    if (!isPlainObject(raw)) {
+        return { ok: false, reason: `deny[${index}] must be an object` };
+    }
+    const warnings = [];
+    const rawScope = raw.scope;
+    if (typeof rawScope !== 'string') {
+        return { ok: false, reason: `deny[${index}].scope must be a string` };
+    }
+    const scope = exports.DENY_SCOPES.includes(rawScope)
+        ? rawScope
+        : exports.DENY_SCOPE_ALIASES[rawScope];
+    if (!scope) {
+        // Rejecting the document is the fail-closed choice: a rule this build cannot evaluate is a
+        // stop order it would silently not apply, while the console reports it as applied.
+        return { ok: false, reason: `deny[${index}].scope "${rawScope}" is not a scope this build understands (known: ${exports.DENY_SCOPES.join(', ')})` };
+    }
+    if (typeof raw.match !== 'string' || raw.match.length === 0) {
+        return { ok: false, reason: `deny[${index}].match must be a non-empty string` };
+    }
+    const rawMode = raw.mode;
+    if (typeof rawMode !== 'string') {
+        return { ok: false, reason: `deny[${index}].mode must be a string` };
+    }
+    let mode = (rawMode in exports.DENY_MODES ? rawMode : exports.DENY_MODE_ALIASES[rawMode]);
+    if (!mode) {
+        // Same asymmetry as onBreach: clamp UP. A stop order whose mode we cannot read is treated as
+        // the strictest one, never dropped and never softened.
+        mode = exports.STRICTEST_DENY_MODE;
+        warnings.push(`deny[${index}].mode="${rawMode}" is not a mode this build understands. ` +
+            `Failing CLOSED to "${exports.STRICTEST_DENY_MODE}". Known modes: ${Object.keys(exports.DENY_MODES).join(', ')}.`);
+    }
+    const rule = { scope, match: raw.match, mode };
+    if (raw.reason !== undefined) {
+        if (typeof raw.reason !== 'string') {
+            return { ok: false, reason: `deny[${index}].reason must be a string` };
+        }
+        rule.reason = raw.reason;
+    }
+    if (raw.until !== undefined && raw.until !== null) {
+        if (typeof raw.until !== 'number' || !Number.isFinite(raw.until)) {
+            return { ok: false, reason: `deny[${index}].until must be a finite epoch-seconds number` };
+        }
+        rule.until = raw.until;
+    }
+    if (raw.user !== undefined && raw.user !== null) {
+        if (typeof raw.user !== 'string') {
+            return { ok: false, reason: `deny[${index}].user must be a string` };
+        }
+        rule.user = raw.user;
+    }
+    if (raw.followUser !== undefined && raw.followUser !== null) {
+        if (typeof raw.followUser !== 'boolean') {
+            return { ok: false, reason: `deny[${index}].followUser must be a boolean` };
+        }
+        rule.followUser = raw.followUser;
+    }
+    return { ok: true, rule, warnings };
+}
+/**
+ * Parse and validate a whole lease document.
+ *
+ * **This is the exported validator the back-compat/alias work layers onto.** Adding a row to
+ * `LEASE_CAP_ALIASES`, `ON_BREACH_ALIASES`, `DENY_MODE_ALIASES` or `DENY_SCOPE_ALIASES` is
+ * sufficient; there is no second place that reads a lease field.
+ */
+function parseLease(raw) {
+    if (!isPlainObject(raw)) {
+        return { ok: false, reason: 'lease must be a JSON object' };
+    }
+    const warnings = [];
+    if (typeof raw.pack !== 'string' || raw.pack.length === 0) {
+        return { ok: false, reason: 'lease.pack must be a non-empty string' };
+    }
+    if (typeof raw.enabled !== 'boolean') {
+        // Not coerced. `enabled: "false"` is truthy in JavaScript, so a string here would lift the
+        // kill switch rather than apply it — the single most dangerous coercion in this document.
+        return { ok: false, reason: `lease.enabled must be a boolean, got ${typeof raw.enabled}` };
+    }
+    if (typeof raw.expiresAt !== 'number' || !Number.isFinite(raw.expiresAt)) {
+        return { ok: false, reason: `lease.expiresAt must be a finite epoch-seconds number, got ${JSON.stringify(raw.expiresAt)}` };
+    }
+    const lease = { pack: raw.pack, enabled: raw.enabled, expiresAt: raw.expiresAt };
+    for (const key of ['version', 'imageDigest', 'reason']) {
+        const v = raw[key];
+        if (v === undefined || v === null) {
+            continue;
+        }
+        if (typeof v !== 'string') {
+            return { ok: false, reason: `lease.${key} must be a string, got ${typeof v}` };
+        }
+        lease[key] = v;
+    }
+    for (const key of ['requireSignedPack', 'requireSignedLease']) {
+        const v = raw[key];
+        if (v === undefined || v === null) {
+            continue;
+        }
+        if (typeof v !== 'boolean') {
+            return { ok: false, reason: `lease.${key} must be a boolean, got ${typeof v}` };
+        }
+        lease[key] = v;
+    }
+    if (raw.caps !== undefined && raw.caps !== null) {
+        const caps = parseCapPolicy(raw.caps, 'lease.caps');
+        if (!caps.ok) {
+            return { ok: false, reason: caps.reason };
+        }
+        lease.caps = caps.caps;
+        warnings.push(...caps.warnings);
+    }
+    if (raw.deny !== undefined && raw.deny !== null) {
+        if (!Array.isArray(raw.deny)) {
+            return { ok: false, reason: 'lease.deny must be an array' };
+        }
+        const rules = [];
+        for (let i = 0; i < raw.deny.length; i++) {
+            const parsed = parseDenyRule(raw.deny[i], i);
+            if (!parsed.ok) {
+                return { ok: false, reason: parsed.reason };
+            }
+            rules.push(parsed.rule);
+            warnings.push(...parsed.warnings);
+        }
+        lease.deny = rules;
+    }
+    return { ok: true, lease, warnings };
+}