opencode-swarm 7.181.1 → 7.181.2

package/dist/db/qa-gate-session-override.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Service layer for the `qa_gate_session_override` table in the per-project
+ * database (issue #2668).
+ *
+ * A session's ratchet-tighter QA gate overrides (`/swarm qa-gates override`)
+ * are durable runtime policy: they must survive a host restart, unlike the
+ * ephemeral execution authority (leases, child handles, in-flight timers) that
+ * expires at the rehydrate boundary. The in-memory
+ * `AgentSessionState.qaGateSessionOverrides` remains the live cache the
+ * enforcement sites read; this table is the restart authority, restored by
+ * `rehydrateState` and kept in lockstep (created by the durable-first write in
+ * the `/swarm qa-gates override` command, deleted at session end/stale
+ * eviction).
+ *
+ * Semantics mirror the spec-level profile ratchet: only `true` wins. A session
+ * with no `true` gates has NO row — an empty merge deletes it.
+ */
+import { type QaGates } from './qa-gate-profile.js';
+/**
+ * Test-only dependency-injection seam — see `gitignore-warning.ts:_internals`
+ * for the rationale (`mock.module` from `bun:test` leaks across files in
+ * Bun's shared test-runner process). Mutating this local object is
+ * file-scoped and trivially restorable via `afterEach`.
+ */
+export declare const _internals: {
+    getOverrideForSession: typeof getOverrideForSession;
+    setOverrideForSession: typeof setOverrideForSession;
+    clearOverrideForSession: typeof clearOverrideForSession;
+    clearAllSessionOverrides: typeof clearAllSessionOverrides;
+};
+/**
+ * Read the durable ratchet-tighter overrides for a session.
+ *
+ * Read-only: if `.swarm/swarm.db` does not exist yet, returns `{}`
+ * without creating the DB file. A malformed row fails closed to `{}`
+ * (with a debug-gated warn naming the session) — corruption must not
+ * break rehydration or silently widen the effective gates.
+ */
+export declare function getOverrideForSession(directory: string, sessionId: string): Partial<QaGates>;
+/**
+ * Merge ratchet-tighter gates into a session's durable override row.
+ *
+ * Only `true` values win (mirrors `getEffectiveGates` semantics); a `false`
+ * input never disables. If the merged map has no `true` gates the row is
+ * DELETED (empty-overrides invariant, #2668) — an empty override is the
+ * absence of policy, not a policy.
+ */
+export declare function setOverrideForSession(directory: string, sessionId: string, gates: Partial<QaGates>): Partial<QaGates>;
+/**
+ * Delete a session's durable override row. Idempotent: clearing an absent
+ * row is a no-op. Returns true when a row was removed.
+ */
+export declare function clearOverrideForSession(directory: string, sessionId: string): boolean;
+/**
+ * Delete every durable override row in the project. Used by
+ * `/swarm reset-session`, which clears all in-memory sessions for the
+ * project — their durable policy rows go with them (bounded: one row per
+ * session). Returns the number of rows removed.
+ */
+export declare function clearAllSessionOverrides(directory: string): number;
+/**
+ * Delete override rows whose session is no longer live in this project
+ * (#2668 orphan-row reaper). `sweepStaleSessions` can evict a stale session
+ * in-memory WITHOUT being able to clear its durable row — the hot-path
+ * `ensureAgentSession` sweep runs with no `directory`, so the project DB is
+ * unreachable there. This reaper runs at the rehydrate boundary (which knows
+ * the directory) and removes every row whose session id is not in
+ * `keepSessionIds` — the restored/live sessions of the hydrating project.
+ * Bounded: one indexed scan over a session-keyed table. Returns the number
+ * of orphaned rows removed.
+ */
+export declare function sweepOrphanOverrides(directory: string, keepSessionIds: ReadonlySet<string>): number;