@opengeni/db 0.2.0

package/drizzle/0015_workspace_agent_instructions.sql

@@ -0,0 +1,17 @@
+-- Per-workspace white-label agent persona override.
+--
+-- NULL means "use the deployment default template"
+-- (OPENGENI_AGENT_INSTRUCTIONS_TEMPLATE / DEFAULT_AGENT_INSTRUCTIONS), so every
+-- existing workspace keeps the historical, byte-identical preamble after this
+-- migration without a backfill. The runtime always injects the non-bypassable
+-- CORE (goal-loop ownership + workspace-environment block) regardless of this
+-- value, so an override can restyle the persona but never drop that contract.
+ALTER TABLE "workspaces"
+  ADD COLUMN IF NOT EXISTS "agent_instructions" text;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0016_session_create_idempotency.sql

@@ -0,0 +1,27 @@
+-- Workspace-scoped CREATE idempotency for sessions.
+--
+-- Closes the stuck-queued create-path bug: createSessionForRequest used to
+-- unconditionally insert a brand-new session on every call, so a double-fire
+-- (client double-submit / retry / double-dispatch) created duplicate sessions,
+-- some stranded status=queued forever. clientEventId cannot dedup this — its
+-- unique index is per-session, so two brand-new sessions never collide on it.
+--
+-- The new nullable key + PARTIAL unique index gives the create path a
+-- workspace-scoped dedup target: concurrent creates carrying the same key
+-- collapse to a single row (the loser sees a unique violation, which the
+-- domain layer catches and turns into "return the existing session"). NULL
+-- keys are exempt from the index, so back-compat (key-less) creates stay
+-- independent and existing rows need no backfill.
+ALTER TABLE "sessions"
+  ADD COLUMN IF NOT EXISTS "create_idempotency_key" text;
+
+CREATE UNIQUE INDEX IF NOT EXISTS "sessions_workspace_create_idempotency_idx"
+  ON "sessions" ("workspace_id", "create_idempotency_key")
+  WHERE "create_idempotency_key" IS NOT NULL;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0017_sandbox_leases.sql

@@ -0,0 +1,313 @@
+-- Sandbox singleton lease + refcounted holders + the cross-workspace reaper sweep.
+--
+-- The SOLE enforcer of one-box-per-group (P1.1; design-of-record
+-- 08-implementation-plan.md P1.1 + modules/01-lease.md, re-keyed to
+-- sandbox_group_id per addendum B.2). Two tables, authored GROUP-keyed from the
+-- start so today's 1:1 world (sandbox_group_id == session id, set in 0018) is a
+-- behavior-preserving no-op and the shared-sandbox surface (P1.4) needs no
+-- re-key later.
+--
+-- The three Criticals land here together:
+--   * CAS keys   — every lease op keyed (workspace_id, sandbox_group_id).
+--   * meter key  — last_meter_at/last_meter_tick shape (warm_seconds accrues
+--                  idempotent on (sandbox_group_id, lease_epoch, last_meter_tick)
+--                  in P2.1; the column shape lands here).
+--   * envelope split — resume_backend_id + resume_state fold the group's box
+--                  recovery envelope onto the lease (no per-session join).
+--
+-- lease_epoch is INTEGER (not bigint/int8): the lease-epoch spike proved
+-- postgres-js returns int8 from a raw query as a JS STRING, so the strict
+-- epoch-fence compare (row.lease_epoch !== expectedEpoch) was always-true and
+-- fenced every turn; an integer/int4 column comes back as a JS number, which
+-- restores the fence. Epochs never approach 2^31, so the narrower type loses
+-- nothing.
+--
+-- sandbox_group_id is a BARE uuid, DELIBERATELY NOT an FK to sessions(id): the
+-- value is a session id or an ancestor's id in the same workspace; an FK would
+-- let a founder's deletion cascade-kill a box still in use by a spawned session.
+-- The live lease row IS the materialization of "this group has a box" (there is
+-- no sandbox_groups table).
+--
+-- DDL is INERT until P1.2 wires it (flag sandboxOwnershipEnabled); this
+-- migration only creates the tables, indexes, RLS, grants, and the sweep fn.
+
+-- ============== sandbox_leases (exactly one logical row per group) ===========
+-- The UNIQUE (workspace_id, sandbox_group_id) index is the only hardware that
+-- prevents a second box. CAS, epoch, and FOR UPDATE all layer on top of it.
+CREATE TABLE IF NOT EXISTS "sandbox_leases" (
+  "id"               uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "account_id"       uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"     uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+
+  -- The BOX's identity: a session id (singleton group) or an ancestor's id
+  -- (shared group). NOT an FK (see header). The lease is per-group, not
+  -- per-session; holders carry the attributing session_id.
+  "sandbox_group_id" uuid NOT NULL,
+
+  -- The 4-state machine. CHECK pins the domain at the DB edge so a buggy writer
+  -- cannot persist an off-grid liveness value.
+  "liveness"         text NOT NULL DEFAULT 'cold'
+                       CHECK ("liveness" IN ('cold','warming','warm','draining')),
+
+  -- Derived refcount = COUNT(sandbox_lease_holders for this lease). Stored
+  -- denormalized for fast branch decisions, but every mutation recomputes it
+  -- from the holder rows (holders are the source of truth; this is a cache).
+  "refcount"         integer NOT NULL DEFAULT 0 CHECK ("refcount" >= 0),
+
+  -- Split counts. turn_holders is TTL-EXEMPT (released only by the Temporal
+  -- activity lifecycle / worker-death requeue, never reaped). viewer_holders is
+  -- TTL-reapable. The warm->draining CAS is guarded AND turn_holders = 0.
+  "turn_holders"     integer NOT NULL DEFAULT 0 CHECK ("turn_holders"   >= 0),
+  "viewer_holders"   integer NOT NULL DEFAULT 0 CHECK ("viewer_holders" >= 0),
+
+  -- Provider identity of the live box + how to reach it.
+  "instance_id"      text,                 -- provider sandbox id (NULL while cold)
+  "backend"          text NOT NULL,        -- 'modal'|'daytona'|... (sessions.sandbox_backend copy)
+  "os"               text NOT NULL DEFAULT 'linux',
+  "data_plane_url"   text,                 -- current scoped Channel-B (VNC-WS) URL,
+                                           -- recorded by any worker via an
+                                           -- event-driven resolveExposedPort under
+                                           -- the epoch fence (no owner process).
+
+  -- THE FENCE. Monotonic, bumped on every warming->warm commit / re-establish.
+  -- A stale re-dispatched writer fails its CAS and backs off when its cached
+  -- epoch != row epoch. integer (NOT bigint) — see header.
+  "lease_epoch"      integer NOT NULL DEFAULT 0,
+
+  -- THE GROUP BOX-ENVELOPE (the "envelope split" Critical). resume_backend_id +
+  -- resume_state are the small recovery descriptor needed to resume()-by-id the
+  -- group's box (warm reattach or cold restore from snapshot) without a
+  -- per-session DB join. Folded onto the lease so the group has ONE envelope.
+  "resume_backend_id" text,
+  "resume_state"      jsonb,
+
+  -- Warm-time billing cursor (the meter the stateless ticks advance in P2.1):
+  --   * last_meter_at   = the accrual cursor (when warm-seconds were last metered);
+  --   * last_meter_tick = the idempotency tick; warm_seconds is accrued idempotent
+  --     on (sandbox_group_id, lease_epoch, last_meter_tick) so a retried/duplicate
+  --     tick never double-counts.
+  "last_meter_at"    timestamptz,
+  "last_meter_tick"  integer NOT NULL DEFAULT 0,
+
+  -- Heartbeat-TTL of the LEASE itself: refreshed on acquire, on the turn's 30s
+  -- activity heartbeat, and on a viewer's app-level API heartbeat. A 'warming'
+  -- row whose expires_at lapses = an uncaught spawner death -> reaper resets to
+  -- 'cold' (warming-death == lapse, single expires_at).
+  "expires_at"       timestamptz NOT NULL,
+
+  "created_at"       timestamptz NOT NULL DEFAULT now(),
+  "updated_at"       timestamptz NOT NULL DEFAULT now()
+);
+
+-- THE SINGLETON GUARANTEE. One lease row per (workspace, group); INSERT ON
+-- CONFLICT DO NOTHING + this index is what makes acquireLease idempotent under
+-- a race.
+CREATE UNIQUE INDEX IF NOT EXISTS "sandbox_leases_group_idx"
+  ON "sandbox_leases" ("workspace_id", "sandbox_group_id");
+
+-- Reaper scan index: find lapsed leases cheaply. Partial on the three states the
+-- reaper sweep acts on (warming-TTL-expired -> cold; warm-idle -> draining;
+-- draining-grace-elapsed -> drainable). The SECURITY-DEFINER sweep predicate
+-- rides this index.
+CREATE INDEX IF NOT EXISTS "sandbox_leases_reaper_idx"
+  ON "sandbox_leases" ("expires_at")
+  WHERE "liveness" IN ('warming','warm','draining');
+
+-- ============== sandbox_lease_holders (one row per holder) ===================
+-- Release is delete-my-row, never a blind refcount--. A retried release
+-- (Temporal at-least-once) deleting an already-gone row is a clean no-op.
+CREATE TABLE IF NOT EXISTS "sandbox_lease_holders" (
+  "id"                 uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "account_id"         uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"       uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+  "lease_id"           uuid NOT NULL REFERENCES "sandbox_leases"("id")   ON DELETE CASCADE,
+
+  "kind"               text NOT NULL CHECK ("kind" IN ('turn','viewer')),
+
+  -- Stable per-holder identity:
+  --   turn   -> the session_turns.id (one turn = one holder; turns are sequential)
+  --   viewer -> the access-grant-scoped viewer connection id minted at handshake
+  -- Carrying holder_id makes acquire idempotent: a duplicate acquire for the
+  -- same (lease,kind,holder) is ON CONFLICT DO UPDATE (heartbeat refresh), not a
+  -- double-increment.
+  "holder_id"          text NOT NULL,
+
+  -- The attributing session within the (possibly shared) group: which session
+  -- this holder belongs to (attribution/disclosure for shared boxes). The lease
+  -- is group-keyed; the holder records the session.
+  "subject_id"         uuid,
+
+  -- Last app-level heartbeat. turn holders refresh via the 30s activity
+  -- heartbeat; viewer holders via the client->server Channel-A viewer ping.
+  -- reapStaleLeaseHolders deletes viewer rows older than viewerHolderTTL.
+  "last_heartbeat_at"  timestamptz NOT NULL DEFAULT now(),
+  "created_at"         timestamptz NOT NULL DEFAULT now()
+);
+
+-- Idempotency key for a holder: a given (lease, kind, holder) exists at most
+-- once. acquireLease inserts ON CONFLICT DO UPDATE (refresh heartbeat) so a
+-- reconnecting viewer or a retried acquire never double-counts.
+CREATE UNIQUE INDEX IF NOT EXISTS "sandbox_lease_holders_holder_idx"
+  ON "sandbox_lease_holders" ("lease_id", "kind", "holder_id");
+
+-- Reaper scan: viewer holders by staleness.
+CREATE INDEX IF NOT EXISTS "sandbox_lease_holders_stale_idx"
+  ON "sandbox_lease_holders" ("kind", "last_heartbeat_at");
+
+-- Recompute-refcount join.
+CREATE INDEX IF NOT EXISTS "sandbox_lease_holders_lease_idx"
+  ON "sandbox_lease_holders" ("lease_id");
+
+-- ============== RLS + grants (verbatim 0005/0007 boilerplate) ================
+ALTER TABLE "sandbox_leases"        ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "sandbox_leases"        FORCE  ROW LEVEL SECURITY;
+ALTER TABLE "sandbox_lease_holders" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "sandbox_lease_holders" FORCE  ROW LEVEL SECURITY;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = current_schema() AND tablename = 'sandbox_leases' AND policyname = 'workspace_isolation'
+  ) THEN
+    DROP POLICY workspace_isolation ON "sandbox_leases";
+  END IF;
+END $$;
+CREATE POLICY workspace_isolation ON "sandbox_leases"
+  USING (opengeni_private.workspace_rls_visible(account_id, workspace_id))
+  WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id));
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = current_schema() AND tablename = 'sandbox_lease_holders' AND policyname = 'workspace_isolation'
+  ) THEN
+    DROP POLICY workspace_isolation ON "sandbox_lease_holders";
+  END IF;
+END $$;
+CREATE POLICY workspace_isolation ON "sandbox_lease_holders"
+  USING (opengeni_private.workspace_rls_visible(account_id, workspace_id))
+  WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id));
+
+-- ============== The SECURITY-DEFINER cross-workspace reaper sweep (OD-3) =====
+-- The reaper Temporal Schedule (P1.3) runs ONE global sweep, not a per-workspace
+-- loop: it must see stale rows across ALL workspaces in a single pass. Under
+-- FORCE RLS the workspace_isolation policy would hide every other workspace's
+-- rows from a scoped connection, so the sweep is a SECURITY DEFINER function
+-- owned by the migration role (which owns the tables and thus is not subject to
+-- their RLS when it runs as DEFINER) — the one sanctioned cross-workspace read.
+--
+-- DB-ONLY: this function does NOT call any provider. It mutates the lease rows
+-- (TTL-reap stale viewer holders, reset warming-death to cold, recompute
+-- refcounts, enter draining at refcount 0) and RETURNS the (workspace_id,
+-- sandbox_group_id) of leases whose drain grace has elapsed so the caller can
+-- issue the provider stop() (that stop() is P1.3's runtime concern, not the
+-- DB's). One predicate-driven pass over the reaper index.
+CREATE OR REPLACE FUNCTION opengeni_private.reap_sandbox_leases(
+  p_viewer_holder_ttl_ms bigint,
+  p_idle_grace_ms        bigint
+)
+RETURNS TABLE (workspace_id uuid, sandbox_group_id uuid, instance_id text, lease_epoch integer)
+LANGUAGE plpgsql
+SECURITY DEFINER
+-- EMBED-SAFE: this function references sandbox_leases / sandbox_lease_holders
+-- (the DATA schema) and opengeni_private helpers. It deliberately does NOT pin
+-- `SET search_path = public, ...` because under the embedded dedicated-schema
+-- topology those tables live in the host's chosen schema (e.g. `opengeni`), not
+-- `public`; a pinned `public` path would silently resolve them to an empty/
+-- absent table and the reaper sweep would no-op. Inheriting the caller's
+-- search_path resolves the data tables in standalone (caller path `public,
+-- opengeni_private`) AND embedded (caller path `<schema>, opengeni_private`)
+-- alike. opengeni_private fns are still called with an absolute prefix below.
+AS $$
+BEGIN
+  -- (a) Reap stale VIEWER holders cross-workspace (turn holders are TTL-exempt).
+  DELETE FROM sandbox_lease_holders h
+  WHERE h.kind = 'viewer'
+    AND h.last_heartbeat_at < now() - make_interval(secs => p_viewer_holder_ttl_ms / 1000.0);
+
+  -- (b) Recompute refcounts from the holder rows for every lease; warm leases
+  --     that hit 0 (AND turn_holders = 0) enter draining with a fresh grace
+  --     deadline (idleGraceMs, the SAME horizon releaseLeaseHolder stamps).
+  UPDATE sandbox_leases L SET
+    refcount       = c.total,
+    turn_holders   = c.turns,
+    viewer_holders = c.viewers,
+    liveness = CASE WHEN L.liveness = 'warm' AND c.total = 0 AND c.turns = 0
+                    THEN 'draining' ELSE L.liveness END,
+    expires_at = CASE WHEN L.liveness = 'warm' AND c.total = 0 AND c.turns = 0
+                    THEN now() + make_interval(secs => p_idle_grace_ms / 1000.0)
+                    ELSE L.expires_at END,
+    updated_at = now()
+  FROM (
+    SELECT L2.id,
+           (SELECT count(*) FROM sandbox_lease_holders h WHERE h.lease_id = L2.id)::int                          AS total,
+           (SELECT count(*) FROM sandbox_lease_holders h WHERE h.lease_id = L2.id AND h.kind = 'turn')::int      AS turns,
+           (SELECT count(*) FROM sandbox_lease_holders h WHERE h.lease_id = L2.id AND h.kind = 'viewer')::int    AS viewers
+    FROM sandbox_leases L2
+  ) c
+  WHERE L.id = c.id;
+
+  -- (c) WARMING-death: a 'warming' row whose LEASE TTL lapsed = the spawner
+  --     process died mid-resume. Reset to cold so a queued turn can re-acquire
+  --     and re-spawn. instance_id/data_plane_url cleared (a warming row may have
+  --     a stale handle from a prior epoch).
+  UPDATE sandbox_leases SET
+    liveness = 'cold', instance_id = NULL,
+    resume_backend_id = NULL, resume_state = NULL,
+    data_plane_url = NULL, updated_at = now()
+  WHERE liveness = 'warming' AND expires_at < now();
+
+  -- (d) DRAINING-grace elapsed: surface the (workspace, group) of every lease
+  --     whose grace is up AND still idle, with instance_id + epoch, so the
+  --     caller (P1.3) can issue the provider stop() then confirmDrainCold-CAS
+  --     draining->cold under the epoch fence. DB-only: no provider call here.
+  RETURN QUERY
+    SELECT L.workspace_id, L.sandbox_group_id, L.instance_id, L.lease_epoch
+    FROM sandbox_leases L
+    WHERE L.liveness = 'draining' AND L.expires_at < now() AND L.refcount = 0;
+END;
+$$;
+
+-- ============================================================================
+-- Warm-meter read (P2.1) — the reaper-tick metering input.
+--
+-- The reaper sweep is the warm-meter tick for VIEWER-ONLY boxes between turns (a
+-- turn-held box is metered by the turn's own activity heartbeat, so we EXCLUDE
+-- turn_holders > 0 here to avoid double-metering). Like the reaper sweep this is
+-- a cross-workspace read that FORCE RLS would hide from a scoped connection, so
+-- it is a SECURITY DEFINER read fn (DB-only, no mutation — the worker calls
+-- accrueWarmSeconds per row, which does the epoch-fenced cursor advance + the
+-- (group, epoch, tick)-idempotent usage insert under the lease row lock).
+--
+-- Returns ONE row per WARM group with no turn holders (a singleton group is one
+-- box → one row → one warm-seconds stream regardless of N viewer sessions).
+CREATE OR REPLACE FUNCTION opengeni_private.list_meterable_warm_leases()
+RETURNS TABLE (
+  account_id        uuid,
+  workspace_id      uuid,
+  sandbox_group_id  uuid,
+  lease_epoch       integer,
+  backend           text
+)
+LANGUAGE sql
+SECURITY DEFINER
+-- EMBED-SAFE: see reap_sandbox_leases above — no pinned `public` search_path so
+-- the cross-workspace warm-lease read resolves sandbox_leases in whatever data
+-- schema the caller's search_path selects (standalone `public`, embedded
+-- `<schema>`). Inherits the caller's path instead of hardcoding `public`.
+AS $$
+  SELECT L.account_id, L.workspace_id, L.sandbox_group_id, L.lease_epoch, L.backend
+  FROM sandbox_leases L
+  WHERE L.liveness = 'warm' AND L.turn_holders = 0;
+$$;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+    GRANT EXECUTE ON FUNCTION opengeni_private.reap_sandbox_leases(bigint, bigint) TO opengeni_app;
+    GRANT EXECUTE ON FUNCTION opengeni_private.list_meterable_warm_leases() TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0018_sandbox_os.sql

@@ -0,0 +1,89 @@
+-- Per-session sandbox OS + the shared-sandbox group identity.
+--
+-- Two forward-only, behavior-preserving column adds (P0.5; design-of-record
+-- 08-implementation-plan.md P0.5 + 05-addendum-shared-sandboxes.md B.1):
+--
+-- (a) OS axis. sessions.sandbox_os carries the OS the session's box runs
+--     (default 'linux' — today's only OS, so every existing + new row is
+--     'linux' with no behavior change). session_turns.sandbox_os is a NULLable
+--     per-turn override (NULL = inherit the session's OS). Both CHECK-constrained
+--     to the SandboxOs enum (linux|macos|windows). The OS is also stamped into
+--     the recovery-envelope JSON so re-establish needs no DB join.
+--
+-- (b) Shared-sandbox group. sessions.sandbox_group_id is the BOX's identity:
+--     every session that founds its own box has sandbox_group_id == id (a
+--     singleton group, group === session), so today's 1:1 world is a
+--     behavior-preserving no-op. A session spawned shared inherits its parent's
+--     sandbox_group_id so both run in ONE box. The live lease row (0017), not a
+--     sandbox_groups table, materializes "this group has a box."
+--
+--     DELIBERATELY NOT an FK to sessions(id): the value is either this row's own
+--     id or an ANCESTOR session's id in the same workspace. An FK would let a
+--     founder's deletion cascade-kill a box still in use by a spawned session
+--     (addendum stress b.1). Do not "tidy" this into an FK.
+--
+--     The value cannot SQL-default to id (id is gen_random_uuid(), unknown at
+--     default-eval time) — the app generates one uuid and uses it for both id
+--     and sandbox_group_id in a single insert. The column is added NULLable for
+--     the backfill, populated (= id for every existing row), then SET NOT NULL.
+
+-- (a) OS axis ---------------------------------------------------------------
+
+ALTER TABLE "sessions"
+  ADD COLUMN IF NOT EXISTS "sandbox_os" text NOT NULL DEFAULT 'linux';
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'sessions_sandbox_os_check'
+  ) THEN
+    ALTER TABLE "sessions"
+      ADD CONSTRAINT "sessions_sandbox_os_check"
+      CHECK ("sandbox_os" IN ('linux', 'macos', 'windows'));
+  END IF;
+END $$;
+
+ALTER TABLE "session_turns"
+  ADD COLUMN IF NOT EXISTS "sandbox_os" text;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'session_turns_sandbox_os_check'
+  ) THEN
+    ALTER TABLE "session_turns"
+      ADD CONSTRAINT "session_turns_sandbox_os_check"
+      CHECK ("sandbox_os" IS NULL OR "sandbox_os" IN ('linux', 'macos', 'windows'));
+  END IF;
+END $$;
+
+-- (b) Shared-sandbox group identity -----------------------------------------
+
+-- 1. Add NULLable transiently for the backfill.
+ALTER TABLE "sessions"
+  ADD COLUMN IF NOT EXISTS "sandbox_group_id" uuid;
+
+-- 2. Backfill: every existing session is its OWN singleton group (group === id).
+--    This is the behavior-preserving identity that makes the whole change a
+--    no-op for today's 1:1 world.
+UPDATE "sessions" SET "sandbox_group_id" = "id" WHERE "sandbox_group_id" IS NULL;
+
+-- 3. Enforce NOT NULL (the app supplies the value on every insert from here on).
+ALTER TABLE "sessions"
+  ALTER COLUMN "sandbox_group_id" SET NOT NULL;
+
+-- 4. Routing index: resolve session_id -> sandbox_group_id at every lease entry
+--    point (turn resume-by-id, viewer attach) and enumerate "all sessions in a
+--    group" for attribution/disclosure. Workspace-scoped (the workspace is the
+--    access boundary; the group uuid is not).
+CREATE INDEX IF NOT EXISTS "sessions_sandbox_group_idx"
+  ON "sessions" ("workspace_id", "sandbox_group_id");
+
+-- Re-grant on the new columns (idempotent; mirrors the boilerplate in earlier
+-- migrations so a fresh opengeni_app role can read/write the added columns).
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0019_session_stream_acknowledgments.sql

@@ -0,0 +1,94 @@
+-- The un-redacted-pixel consent gate (P3.2; design-of-record
+-- 08-implementation-plan.md P3.2 + modules/07-channel-b.md §1.1/§6 +
+-- 05-addendum-shared-sandboxes.md E.1).
+--
+-- A row here records that a PRINCIPAL (subject) explicitly acknowledged the
+-- un-redacted desktop pixel plane for a (workspace, group, subject) — and, when
+-- the box is shared with sibling sessions, that they also consented to the
+-- SHARED-EXPOSURE disclosure (watching A's desktop also shows B's agent on the
+-- one framebuffer; the pixels cannot be redacted, so consent — not authz — is
+-- the gate, addendum E.1 / stress g).
+--
+-- The acknowledgment is keyed on the GROUP, not the session: the un-redacted
+-- surface is the BOX's :0 framebuffer (one per group), so acknowledging it once
+-- for a group covers every conversation in that group. The shared bit is
+-- recorded so a later transition from solo→shared can re-require consent if the
+-- product wants it (today the negotiation reports `shared` from the live group
+-- session-set and the gate keys on the recorded `acknowledged_shared`).
+--
+-- Reuses the acknowledgment machinery from P3.1 — NO new permission beyond
+-- stream:acknowledge (the principal must hold stream:acknowledge to write a row,
+-- and stream:view to use the desktop path the row gates).
+--
+-- DDL is INERT until the routes wire it (flag sandboxOwnershipEnabled); this
+-- migration only creates the table, indexes, RLS, and grants. Forward-only,
+-- behavior-preserving: no existing row references it.
+
+-- ============== session_stream_acknowledgments (one row per consent) =========
+-- The natural key is (workspace_id, sandbox_group_id, subject_id): a principal's
+-- consent to the group's un-redacted pixel plane. acknowledged_shared records
+-- whether the shared-exposure disclosure was also consented (the gate returns
+-- 409 shared_acknowledgment_required until this is true for a shared box).
+CREATE TABLE IF NOT EXISTS "session_stream_acknowledgments" (
+  "id"                  uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "account_id"          uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"        uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+
+  -- The GROUP whose un-redacted :0 framebuffer this consent covers. A bare uuid
+  -- (NOT an FK), matching sandbox_leases.sandbox_group_id: the value is a session
+  -- id or an ancestor's id in the same workspace; the lease row, not a
+  -- sandbox_groups table, materializes the group (addendum B.1).
+  "sandbox_group_id"    uuid NOT NULL,
+
+  -- The acknowledging PRINCIPAL (the access-grant subjectId). Consent is
+  -- per-principal: A acknowledging does not consent on B's behalf.
+  "subject_id"          text NOT NULL,
+
+  -- Always true when a row exists (the un-redacted pixel plane was acknowledged);
+  -- carried explicitly so the column self-documents and a future "withdraw"
+  -- toggles it without deleting attribution.
+  "acknowledged_unredacted" boolean NOT NULL DEFAULT true,
+
+  -- Whether the SHARED-EXPOSURE disclosure was also consented (addendum E.1).
+  -- The gate returns 409 shared_acknowledgment_required for a shared box until
+  -- this is true; for a solo box it is irrelevant (the un-redacted ack suffices).
+  "acknowledged_shared" boolean NOT NULL DEFAULT false,
+
+  "acknowledged_at"     timestamptz NOT NULL DEFAULT now(),
+  "created_at"          timestamptz NOT NULL DEFAULT now(),
+  "updated_at"          timestamptz NOT NULL DEFAULT now()
+);
+
+-- One consent row per (workspace, group, subject). Re-acknowledging (e.g. a
+-- solo→shared upgrade flipping acknowledged_shared) is an ON CONFLICT DO UPDATE,
+-- never a duplicate row.
+CREATE UNIQUE INDEX IF NOT EXISTS "session_stream_ack_subject_idx"
+  ON "session_stream_acknowledgments" ("workspace_id", "sandbox_group_id", "subject_id");
+
+-- Lookup-by-group (enumerate who has consented to a group's pixel plane).
+CREATE INDEX IF NOT EXISTS "session_stream_ack_group_idx"
+  ON "session_stream_acknowledgments" ("workspace_id", "sandbox_group_id");
+
+-- ============== RLS + grants (verbatim 0017 boilerplate) =====================
+ALTER TABLE "session_stream_acknowledgments" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "session_stream_acknowledgments" FORCE  ROW LEVEL SECURITY;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = current_schema() AND tablename = 'session_stream_acknowledgments' AND policyname = 'workspace_isolation'
+  ) THEN
+    DROP POLICY workspace_isolation ON "session_stream_acknowledgments";
+  END IF;
+END $$;
+CREATE POLICY workspace_isolation ON "session_stream_acknowledgments"
+  USING (opengeni_private.workspace_rls_visible(account_id, workspace_id))
+  WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id));
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "session_stream_acknowledgments" TO opengeni_app;
+  END IF;
+END $$;

package/drizzle/0020_session_recordings.sql

@@ -0,0 +1,88 @@
+-- Session recordings — the durable index for the "agent films itself proving
+-- the fix" loop (P4.3; design-of-record 08-implementation-plan.md P4.3 +
+-- modules/05-computer-use.md §3.5).
+--
+-- One row per recording: an ffmpeg x11grab of the SAME :0 framebuffer humans
+-- watch (Channel B), captured while the box is held warm, finalized by reading
+-- the bytes off the box and PUTting them to @opengeni/storage IN THE SAME
+-- process that holds the resumed-by-id handle (the turn activity for an on-turn
+-- recording; the API in-process for an off-turn finalize) — the bytes are NEVER
+-- a Temporal payload (F10). The signed-URL replay route reads `storage_key`.
+--
+-- The acknowledgment / un-redacted-pixel consent (P3.2) gates whether a viewer
+-- may watch the LIVE desktop; a recording artifact is gated by sessions:read on
+-- the per-fetch signed-URL route (the row carries no long-lived URL). Recordings
+-- are un-redacted (the framebuffer may show creds on screen), so recordingEnabled
+-- is an opt-in per deployment and the artifact inherits workspace RLS.
+--
+-- DDL is INERT until the worker/API wire it (flag sandboxDesktopEnabled); this
+-- migration only creates the table, indexes, RLS, and grants. Forward-only,
+-- behavior-preserving: no existing row references it.
+
+-- ============== session_recordings (one row per recording) ===================
+CREATE TABLE IF NOT EXISTS "session_recordings" (
+  "id"                uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "account_id"        uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "workspace_id"      uuid NOT NULL REFERENCES "workspaces"("id")       ON DELETE CASCADE,
+  "session_id"        uuid NOT NULL REFERENCES "sessions"("id")         ON DELETE CASCADE,
+  -- The turn that started the recording (on-turn / on-verify modes). NULL for a
+  -- manual recording with no originating turn. ON DELETE SET NULL: a deleted
+  -- turn must not cascade-kill the recording artifact row.
+  "turn_id"           uuid REFERENCES "session_turns"("id") ON DELETE SET NULL,
+
+  -- recording | finalizing | available | failed (the §3.1 state machine).
+  "state"             text NOT NULL,
+  -- manual | on-turn | on-verify (who started it).
+  "mode"              text NOT NULL,
+  -- h264-mp4 | vp9-webm (the container/codec).
+  "codec"             text NOT NULL,
+
+  -- The @opengeni/storage object key (NULL until finalize commits `available`).
+  "storage_key"       text,
+  "size_bytes"        bigint,
+  "duration_seconds"  double precision,
+
+  -- The framebuffer geometry the recording was captured at (must match the live
+  -- Xvfb geometry — the §7 config coupling).
+  "width"             integer NOT NULL,
+  "height"            integer NOT NULL,
+
+  -- The verification rationale (on-verify "reason") OR the failure reason/detail.
+  -- Agent-authored free text — capped + scrubbed by the producer before storage.
+  "reason"            text,
+
+  "created_at"        timestamptz NOT NULL DEFAULT now(),
+  "finalized_at"      timestamptz,
+
+  CONSTRAINT "session_recordings_state_chk" CHECK ("state" IN ('recording','finalizing','available','failed')),
+  CONSTRAINT "session_recordings_mode_chk"  CHECK ("mode"  IN ('manual','on-turn','on-verify')),
+  CONSTRAINT "session_recordings_codec_chk" CHECK ("codec" IN ('h264-mp4','vp9-webm'))
+);
+
+-- List a session's recordings newest-first without scanning the event spine.
+CREATE INDEX IF NOT EXISTS "session_recordings_session_idx"
+  ON "session_recordings" ("workspace_id", "session_id", "created_at" DESC);
+
+-- ============== RLS + grants (verbatim 0017/0019 boilerplate) ================
+ALTER TABLE "session_recordings" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "session_recordings" FORCE  ROW LEVEL SECURITY;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_policies
+    WHERE schemaname = current_schema() AND tablename = 'session_recordings' AND policyname = 'workspace_isolation'
+  ) THEN
+    DROP POLICY workspace_isolation ON "session_recordings";
+  END IF;
+END $$;
+CREATE POLICY workspace_isolation ON "session_recordings"
+  USING (opengeni_private.workspace_rls_visible(account_id, workspace_id))
+  WITH CHECK (opengeni_private.workspace_rls_visible(account_id, workspace_id));
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT SELECT, INSERT, UPDATE, DELETE ON "session_recordings" TO opengeni_app;
+  END IF;
+END $$;