@opengeni/db 4.0.0-canary.2 → 4.0.0-canary.3

package/dist/managed-auth-session-sets.js

@@ -20,9 +20,9 @@ import {
   reapManagedAuthIsolatedSessions,
   releaseManagedAuthActorMutationLease,
   validateManagedAuthActorMutationLease
-} from "./chunk-VU2IK37Y.js";
-import "./chunk-XIYAXH47.js";
-import "./chunk-PWJJKCTF.js";
+} from "./chunk-OWZ36ST7.js";
+import "./chunk-GPKHEPVX.js";
+import "./chunk-WU3MSPZS.js";
 import "./chunk-PZ5AY32C.js";
 export {
   ManagedAuthActorMutationInFlightError,

package/dist/schema.d.ts

@@ -1463,6 +1463,91 @@ export declare const workspaceInferenceControls: import("drizzle-orm/pg-core").P
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        timerId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timer_id";
+            tableName: "workspace_inference_controls";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timerAction: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timer_action";
+            tableName: "workspace_inference_controls";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timerDueAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timer_due_at";
+            tableName: "workspace_inference_controls";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timerPauseForSeconds: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timer_pause_for_seconds";
+            tableName: "workspace_inference_controls";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timerPauseRevision: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timer_pause_revision";
+            tableName: "workspace_inference_controls";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         workspacePauseRevision: import("drizzle-orm/pg-core").PgColumn<{
             name: "workspace_pause_revision";
             tableName: "workspace_inference_controls";

package/dist/schema.js

@@ -350,7 +350,7 @@ import {
   xaiRotationSettings,
   xaiSessionAccountPins,
   xaiSubscriptionCredentials
-} from "./chunk-PWJJKCTF.js";
+} from "./chunk-WU3MSPZS.js";
 import "./chunk-PZ5AY32C.js";
 export {
   agentRunStates,

package/dist/session-background-commands.js

@@ -22,10 +22,10 @@ import {
   settleClaimedConnectedMachineBackgroundCommandWithMutation,
   settleConnectedMachineSessionBackgroundCommandWithMutation,
   settleSessionBackgroundCommandForRetainedProcessInTransaction
-} from "./chunk-DUB3LUVM.js";
-import "./chunk-CQF6G4IF.js";
-import "./chunk-XIYAXH47.js";
-import "./chunk-PWJJKCTF.js";
+} from "./chunk-R6LIJYG6.js";
+import "./chunk-HUCU5BDD.js";
+import "./chunk-GPKHEPVX.js";
+import "./chunk-WU3MSPZS.js";
 import "./chunk-PZ5AY32C.js";
 export {
   COMMAND_OUTPUT_DEFAULT_BYTES,

package/dist/session-command-output.js

@@ -1,10 +1,10 @@
 import {
   lockSessionEventWriteRows
-} from "./chunk-DUB3LUVM.js";
-import "./chunk-CQF6G4IF.js";
+} from "./chunk-R6LIJYG6.js";
+import "./chunk-HUCU5BDD.js";
 import {
   withSessionActivityRlsContext
-} from "./chunk-XIYAXH47.js";
+} from "./chunk-GPKHEPVX.js";
 import {
   fromPostgresLosslessJson,
   sandboxRetainedProcesses,
@@ -12,7 +12,7 @@ import {
   sessionEvents,
   sessions,
   withLosslessContentWriteVersion
-} from "./chunk-PWJJKCTF.js";
+} from "./chunk-WU3MSPZS.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/session-command-output.ts

package/dist/session-control.d.ts

@@ -1,4 +1,4 @@
-import { type SessionMcpApprovalPolicy, type TurnInitiatorContext } from "@opengeni/contracts";
+import { type WorkspacePauseTimerRequest, type SessionMcpApprovalPolicy, type TurnInitiatorContext } from "@opengeni/contracts";
 import type { Database, SessionActivityDatabase } from "./database.js";
 import * as schema from "./schema.js";
 export declare const SESSION_ANCESTRY_LIMIT = 10000;
@@ -131,6 +131,11 @@ export type WorkspaceControlRow = {
     revision: number | string;
     workspaceState: string;
     workspacePauseRevision: number | string | null;
+    timerId: string | null;
+    timerAction: string | null;
+    timerDueAt: Date | string | null;
+    timerPauseForSeconds: number | null;
+    timerPauseRevision: number | string | null;
     reason: string | null;
     changedBy: string | null;
     changedAt: Date | string | null;
@@ -584,7 +589,27 @@ export declare function mutateWorkspaceControlInTransaction(db: Database, input:
     operationKey: string;
     action: "pause" | "resume";
     reason?: string | null;
+    /** Internal timer executor retains/replaces its own timer atomically. */
+    timerExecution?: boolean;
     expectedRevision?: number | null;
     /** Request-scoped callers bound the control prefix wait; lifecycle callers omit it. */
     controlLockTimeoutMs?: number;
 }): Promise<WorkspaceControlMutationResult>;
+export declare class WorkspacePauseTimerInputError extends Error {
+}
+/** Called under workspace RLS. The same control fence serializes timers and human actions. */
+export declare function setWorkspacePauseTimerInTransaction(db: Database, input: WorkspacePauseTimerRequest & {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+}): Promise<{
+    workspaceControlEventId: string | null;
+}>;
+/** Discovery is a hint. Identity, deadline and pause ownership are rechecked under the fence. */
+export declare function fireWorkspacePauseTimerInTransaction(db: Database, input: {
+    workspaceId: string;
+    timerId: string;
+}): Promise<{
+    workspaceControlEventId: string | null;
+    wakeCount: number;
+} | null>;

package/dist/session-event-slices.js

@@ -1,13 +1,13 @@
 import {
   rawRows,
   withWorkspaceRls
-} from "./chunk-XIYAXH47.js";
+} from "./chunk-GPKHEPVX.js";
 import {
   LOSSLESS_JSON_STRING_PREFIX,
   fromPostgresLosslessJson,
   sessionEvents,
   sessionTurns
-} from "./chunk-PWJJKCTF.js";
+} from "./chunk-WU3MSPZS.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/session-event-slices.ts

package/dist/session-tenancy.js

@@ -14,9 +14,9 @@ import {
   replayAppliedSessionFork,
   sessionTenancyProductActivated,
   transitionSessionVisibility
-} from "./chunk-B5Y3TCSP.js";
-import "./chunk-XIYAXH47.js";
-import "./chunk-PWJJKCTF.js";
+} from "./chunk-3JGOYOWD.js";
+import "./chunk-GPKHEPVX.js";
+import "./chunk-WU3MSPZS.js";
 import "./chunk-PZ5AY32C.js";
 export {
   SessionTenancyAccessError,

package/dist/video-generation.js

@@ -29,9 +29,9 @@ import {
   settleVideoGenerationFailure,
   settleVideoGenerationReady,
   updateWorkspaceVideoGenerationPolicy
-} from "./chunk-CQF6G4IF.js";
-import "./chunk-XIYAXH47.js";
-import "./chunk-PWJJKCTF.js";
+} from "./chunk-HUCU5BDD.js";
+import "./chunk-GPKHEPVX.js";
+import "./chunk-WU3MSPZS.js";
 import "./chunk-PZ5AY32C.js";
 export {
   ACTIVE_VIDEO_GENERATION_STATUSES,

package/drizzle/0420_workspace_pause_timers.sql

@@ -0,0 +1,53 @@
+-- deployment-mode: maintenance
+-- Drain old API/control/turn workers before activation. New timer event actions
+-- and manual-control cancellation semantics must be installed together.
+ALTER TABLE workspace_inference_controls
+  ADD COLUMN timer_id uuid,
+  ADD COLUMN timer_action text,
+  ADD COLUMN timer_due_at timestamptz,
+  ADD COLUMN timer_pause_for_seconds integer,
+  ADD COLUMN timer_pause_revision bigint,
+  ADD CONSTRAINT workspace_pause_timer_shape CHECK (
+    (timer_id IS NULL AND timer_action IS NULL AND timer_due_at IS NULL
+      AND timer_pause_for_seconds IS NULL AND timer_pause_revision IS NULL)
+    OR (timer_id IS NOT NULL AND timer_action IS NOT NULL AND timer_due_at IS NOT NULL
+      AND ((timer_action = 'pause' AND timer_pause_revision IS NULL)
+        OR (timer_action = 'resume' AND timer_pause_revision IS NOT NULL AND timer_pause_for_seconds IS NULL))
+      AND (timer_pause_for_seconds IS NULL OR timer_pause_for_seconds BETWEEN 60 AND 2592000))
+  );
+CREATE INDEX workspace_pause_timer_due_idx ON workspace_inference_controls(timer_due_at, workspace_id)
+  WHERE timer_id IS NOT NULL;
+ALTER TABLE workspace_control_events DROP CONSTRAINT workspace_control_events_action_check;
+ALTER TABLE workspace_control_events ADD CONSTRAINT workspace_control_events_action_check
+  CHECK (action IN ('pause', 'resume', 'timer_set', 'timer_cancelled'));
+
+-- Narrow, read-only inventory capability. FORCE RLS stays enabled; only the
+-- table owner inside this SECURITY DEFINER function gets cross-tenant discovery.
+DO $migration$
+DECLARE data_schema text := current_schema(); owner_name text := current_user;
+BEGIN
+  EXECUTE format('CREATE POLICY workspace_pause_timer_discovery ON %I.workspace_inference_controls
+    FOR SELECT TO %I USING (current_setting(''opengeni.pause_timer_discovery'', true) = ''1'')',
+    data_schema, owner_name);
+  EXECUTE format($create$
+    CREATE FUNCTION opengeni_private.list_due_workspace_pause_timers(p_limit integer)
+    RETURNS TABLE(workspace_id uuid, timer_id uuid)
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog
+    AS $body$
+    DECLARE previous text := current_setting('opengeni.pause_timer_discovery', true);
+    BEGIN
+      PERFORM set_config('opengeni.pause_timer_discovery', '1', true);
+      RETURN QUERY SELECT c.workspace_id, c.timer_id FROM %I.workspace_inference_controls c
+        WHERE c.timer_id IS NOT NULL AND c.timer_due_at <= clock_timestamp()
+        ORDER BY c.timer_due_at, c.workspace_id LIMIT greatest(1, least(coalesce(p_limit, 100), 1000));
+      PERFORM set_config('opengeni.pause_timer_discovery', coalesce(previous, ''), true);
+    END $body$;
+  $create$, data_schema);
+END $migration$;
+REVOKE ALL ON FUNCTION opengeni_private.list_due_workspace_pause_timers(integer) FROM PUBLIC;
+DO $grant$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    GRANT EXECUTE ON FUNCTION opengeni_private.list_due_workspace_pause_timers(integer) TO opengeni_app;
+  END IF;
+END $grant$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "4.0.0-canary.2",
+  "version": "4.0.0-canary.3",
   "description": "OpenGeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -86,11 +86,11 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codemode": "^0.4.27-canary.2",
-    "@opengeni/codex": "^0.2.21-canary.2",
-    "@opengeni/config": "^1.0.0-canary.2",
-    "@opengeni/contracts": "^2.13.0-canary.2",
-    "@opengeni/network": "^0.3.0-canary.2",
+    "@opengeni/codemode": "^0.4.27-canary.3",
+    "@opengeni/codex": "^0.2.21-canary.3",
+    "@opengeni/config": "^1.0.0-canary.3",
+    "@opengeni/contracts": "^2.13.0-canary.3",
+    "@opengeni/network": "^0.3.0-canary.3",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"
   },

package/src/index.ts

@@ -75741,6 +75741,15 @@ async function workspaceControlProjection(
       .limit(1);
     if (!control) throw new Error(`Workspace ${workspaceId} has no inference control`);
     return {
+      timer: control.timerId
+        ? {
+            id: control.timerId,
+            action: control.timerAction as "pause" | "resume",
+            dueAt: control.timerDueAt!.toISOString(),
+            pauseForSeconds: control.timerPauseForSeconds,
+          }
+        : null,
+      serverTime: new Date().toISOString(),
       state: control.workspaceState as "active" | "paused",
       revision: Number(control.revision),
       reason: control.reason,
@@ -76470,3 +76479,15 @@ export * from "./session-tenancy";
 export * from "./governed-learning-activation";
 export * from "./automations";
 export * from "./organization-model-providers";
+
+export {
+  setWorkspacePauseTimerInTransaction,
+  fireWorkspacePauseTimerInTransaction,
+} from "./session-control";
+
+export async function listDueWorkspacePauseTimers(db: Database, limit = 100) {
+  return await rawRows<{ workspace_id: string; timer_id: string }>(
+    db,
+    sql`select * from opengeni_private.list_due_workspace_pause_timers(${limit})`,
+  );
+}

package/src/schema.ts

@@ -405,6 +405,11 @@ export const workspaceInferenceControls = pgTable(
     accountId: uuid("account_id").notNull(),
     revision: bigint("revision", { mode: "number" }).notNull().default(0),
     workspaceState: text("workspace_state").notNull().default("active"),
+    timerId: uuid("timer_id"),
+    timerAction: text("timer_action"),
+    timerDueAt: timestamp("timer_due_at", { withTimezone: true }),
+    timerPauseForSeconds: integer("timer_pause_for_seconds"),
+    timerPauseRevision: bigint("timer_pause_revision", { mode: "number" }),
     workspacePauseRevision: bigint("workspace_pause_revision", {
       mode: "number",
     }),
@@ -420,6 +425,20 @@ export const workspaceInferenceControls = pgTable(
       columns: [table.workspaceId, table.accountId],
       foreignColumns: [workspaces.id, workspaces.accountId],
     }).onDelete("cascade"),
+    timerDue: index("workspace_pause_timer_due_idx")
+      .on(table.timerDueAt, table.workspaceId)
+      .where(sql`${table.timerId} is not null`),
+    timerShape: check(
+      "workspace_pause_timer_shape",
+      sql`
+      (${table.timerId} is null and ${table.timerAction} is null and ${table.timerDueAt} is null
+        and ${table.timerPauseForSeconds} is null and ${table.timerPauseRevision} is null)
+      or (${table.timerId} is not null and ${table.timerAction} is not null and ${table.timerDueAt} is not null
+        and ((${table.timerAction} = 'pause' and ${table.timerPauseRevision} is null)
+          or (${table.timerAction} = 'resume' and ${table.timerPauseRevision} is not null and ${table.timerPauseForSeconds} is null))
+        and (${table.timerPauseForSeconds} is null or ${table.timerPauseForSeconds} between 60 and 2592000))
+    `,
+    ),
     workspaceAccountIdentity: uniqueIndex("workspace_inference_controls_workspace_account_uq").on(
       table.workspaceId,
       table.accountId,
@@ -7526,7 +7545,7 @@ export const workspaceControlEvents = pgTable(
     ),
     actionValid: check(
       "workspace_control_events_action_check",
-      sql`${table.action} in ('pause', 'resume')`,
+      sql`${table.action} in ('pause', 'resume', 'timer_set', 'timer_cancelled')`,
     ),
   }),
 );

package/src/session-control.ts

@@ -4,6 +4,7 @@ import {
   childPausedClassification,
   McpPersonalConnectionDelegations,
   workspaceControlUtf8Bytes,
+  type WorkspacePauseTimerRequest,
   type SessionMcpApprovalPolicy,
   type TurnInitiatorContext,
 } from "@opengeni/contracts";
@@ -176,6 +177,11 @@ export type WorkspaceControlRow = {
   revision: number | string;
   workspaceState: string;
   workspacePauseRevision: number | string | null;
+  timerId: string | null;
+  timerAction: string | null;
+  timerDueAt: Date | string | null;
+  timerPauseForSeconds: number | null;
+  timerPauseRevision: number | string | null;
   reason: string | null;
   changedBy: string | null;
   changedAt: Date | string | null;
@@ -546,6 +552,9 @@ export async function lockWorkspaceInferenceControl(
         revision,
         workspace_state as "workspaceState",
         workspace_pause_revision as "workspacePauseRevision",
+        timer_id as "timerId", timer_action as "timerAction",
+        timer_due_at as "timerDueAt", timer_pause_for_seconds as "timerPauseForSeconds",
+        timer_pause_revision as "timerPauseRevision",
         reason,
         changed_by as "changedBy",
         changed_at as "changedAt"
@@ -3921,6 +3930,8 @@ export async function mutateWorkspaceControlInTransaction(
     operationKey: string;
     action: "pause" | "resume";
     reason?: string | null;
+    /** Internal timer executor retains/replaces its own timer atomically. */
+    timerExecution?: boolean;
     expectedRevision?: number | null;
     /** Request-scoped callers bound the control prefix wait; lifecycle callers omit it. */
     controlLockTimeoutMs?: number;
@@ -3986,7 +3997,8 @@ export async function mutateWorkspaceControlInTransaction(
     "workspace pause revision",
   );
   const changed =
-    input.action === "pause"
+    (!input.timerExecution && workspace.timerId != null) ||
+    (input.action === "pause"
       ? workspace.workspaceState !== "paused" ||
         workspacePauseRevision === null ||
         (await workspacePauseEffectsNeeded(db, {
@@ -3997,7 +4009,7 @@ export async function mutateWorkspaceControlInTransaction(
         (await continuableWakeRepairNeeded(db, {
           workspaceId: input.workspaceId,
           rootSessionId: null,
-        }));
+        })));
   if (!changed) {
     const receipt = await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
       result: {
@@ -4035,6 +4047,7 @@ export async function mutateWorkspaceControlInTransaction(
   const [updated] = await db
     .update(schema.workspaceInferenceControls)
     .set({
+      ...(!input.timerExecution ? clearWorkspaceTimerFields : {}),
       revision,
       workspaceState: input.action === "pause" ? "paused" : "active",
       workspacePauseRevision: input.action === "pause" ? revision : null,
@@ -4060,7 +4073,7 @@ export async function mutateWorkspaceControlInTransaction(
     scope: "workspace",
     rootSessionId: null,
     action: input.action,
-    automatic: false,
+    automatic: input.timerExecution === true,
     reason: input.reason ?? null,
     actor,
   });
@@ -4113,7 +4126,7 @@ async function insertWorkspaceControlEventInTransaction(
     revision: number;
     scope: "workspace" | "session";
     rootSessionId: string | null;
-    action: "pause" | "resume";
+    action: "pause" | "resume" | "timer_set" | "timer_cancelled";
     automatic: boolean;
     reason: string | null;
     actor: string;
@@ -4157,3 +4170,163 @@ async function insertWorkspaceControlEventInTransaction(
   }
   return event.id;
 }
+
+export class WorkspacePauseTimerInputError extends Error {}
+
+const clearWorkspaceTimerFields = {
+  timerId: null,
+  timerAction: null,
+  timerDueAt: null,
+  timerPauseForSeconds: null,
+  timerPauseRevision: null,
+};
+
+/** Called under workspace RLS. The same control fence serializes timers and human actions. */
+export async function setWorkspacePauseTimerInTransaction(
+  db: Database,
+  input: WorkspacePauseTimerRequest & { accountId: string; workspaceId: string; subjectId: string },
+): Promise<{ workspaceControlEventId: string | null }> {
+  let workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update", {
+    lockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
+  });
+  const reserved = await reserveSessionCommandReceipt(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    actor: { type: "human", subjectId: input.subjectId },
+    action: `workspace.timer.${input.action}`,
+    targetSessionId: null,
+    targetTurnId: null,
+    operationKey: input.clientEventId,
+    canonicalRequestHash: canonicalSessionCommandHash({
+      action: input.action,
+      pauseInSeconds: input.pauseInSeconds ?? 0,
+      pauseForSeconds: input.pauseForSeconds ?? null,
+      expectedRevision: input.expectedRevision,
+    }),
+  });
+  if (reserved.replay)
+    return {
+      workspaceControlEventId:
+        (reserved.receipt.result.workspaceControlEventId as string | null) ?? null,
+    };
+  if (Number(workspace.revision) !== input.expectedRevision)
+    throw new SessionControlConflictError();
+  let action: "pause" | "resume" = "pause";
+  let delay = input.pauseInSeconds ?? 0;
+  let pauseRevision: number | null = null;
+  if (input.action === "set") {
+    if (workspace.workspaceState === "paused") {
+      if (delay !== 0 || input.pauseForSeconds == null) {
+        throw new WorkspacePauseTimerInputError("A paused workspace requires a resume duration");
+      }
+      action = "resume";
+      delay = input.pauseForSeconds;
+      pauseRevision = Number(workspace.workspacePauseRevision);
+    } else if (delay === 0) {
+      await mutateWorkspaceControlInTransaction(db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        actor: { type: "human", subjectId: input.subjectId },
+        operationKey: `timer-pause:${reserved.receipt.id}`,
+        action: "pause",
+      });
+      workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update");
+      action = "resume";
+      delay = input.pauseForSeconds ?? 0;
+      pauseRevision = Number(workspace.workspacePauseRevision);
+    }
+  }
+  const hasTimer = input.action === "set" && delay > 0;
+  const [clock] = await db.execute<{ now: Date }>(sql`select clock_timestamp() as now`);
+  const revision = nextRevision(workspace);
+  await db
+    .update(schema.workspaceInferenceControls)
+    .set({
+      ...clearWorkspaceTimerFields,
+      ...(hasTimer
+        ? {
+            timerId: reserved.receipt.id,
+            timerAction: action,
+            timerDueAt: new Date(new Date(clock!.now).getTime() + delay * 1000),
+            timerPauseForSeconds: action === "pause" ? (input.pauseForSeconds ?? null) : null,
+            timerPauseRevision: pauseRevision,
+          }
+        : {}),
+      revision,
+      updatedAt: new Date(clock!.now),
+    })
+    .where(eq(schema.workspaceInferenceControls.workspaceId, input.workspaceId));
+  const workspaceControlEventId = await insertWorkspaceControlEventInTransaction(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    revision,
+    scope: "workspace",
+    rootSessionId: null,
+    action: hasTimer ? "timer_set" : "timer_cancelled",
+    automatic: false,
+    reason: null,
+    actor: input.subjectId,
+  });
+  await updateSessionCommandReceiptResult(db, reserved.receipt.id, {
+    controlRevision: revision,
+    result: { workspaceControlEventId },
+  });
+  return { workspaceControlEventId };
+}
+
+/** Discovery is a hint. Identity, deadline and pause ownership are rechecked under the fence. */
+export async function fireWorkspacePauseTimerInTransaction(
+  db: Database,
+  input: { workspaceId: string; timerId: string },
+): Promise<{ workspaceControlEventId: string | null; wakeCount: number } | null> {
+  const workspace = await lockWorkspaceInferenceControl(db, input.workspaceId, "update", {
+    lockTimeoutMs: 1000,
+  });
+  const [clock] = await db.execute<{ now: Date }>(sql`select clock_timestamp() as now`);
+  if (
+    workspace.timerId !== input.timerId ||
+    !workspace.timerDueAt ||
+    new Date(workspace.timerDueAt).getTime() > new Date(clock!.now).getTime()
+  )
+    return null;
+  const action = workspace.timerAction as "pause" | "resume";
+  // A superseding pause must never be undone by an old timer, even across rolling upgrades.
+  if (
+    action === "resume" &&
+    (workspace.workspaceState !== "paused" ||
+      Number(workspace.workspacePauseRevision) !== Number(workspace.timerPauseRevision))
+  ) {
+    await db
+      .update(schema.workspaceInferenceControls)
+      .set(clearWorkspaceTimerFields)
+      .where(eq(schema.workspaceInferenceControls.workspaceId, input.workspaceId));
+    return null;
+  }
+  const result = await mutateWorkspaceControlInTransaction(db, {
+    accountId: workspace.accountId,
+    workspaceId: input.workspaceId,
+    actor: { type: "service", subjectId: "service:workspace-pause-timer" },
+    operationKey: `timer:${input.timerId}:${action}`,
+    action,
+    timerExecution: true,
+  });
+  // Use application time only for display elsewhere; deadlines are database-clock based.
+  const [applied] = await db.execute<{ now: Date }>(sql`select clock_timestamp() as now`);
+  await db
+    .update(schema.workspaceInferenceControls)
+    .set({
+      ...clearWorkspaceTimerFields,
+      ...(action === "pause" && workspace.timerPauseForSeconds !== null
+        ? {
+            timerId: input.timerId,
+            timerAction: "resume",
+            timerDueAt: new Date(
+              new Date(applied!.now).getTime() + workspace.timerPauseForSeconds * 1000,
+            ),
+            timerPauseRevision: result.revision,
+          }
+        : {}),
+    })
+    .where(eq(schema.workspaceInferenceControls.workspaceId, input.workspaceId));
+  return result;
+}