@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/controller/infrastructure/controller-session-store.ts

@@ -0,0 +1,804 @@
+import { createHash, randomUUID, timingSafeEqual } from 'crypto';
+import { join } from 'path';
+import { FORGE_INSTANCE_SCOPE_KEY, repositoryControllerRoot } from '../../../../src/cli/repositories/controller-home';
+import { withControllerLock } from '../../../../src/cli/repositories/locks';
+import {
+  peekExecutionSession,
+  peekExecutionSessionWithinTransaction,
+} from '../../../../src/runtime/control-plane/execution/session-store';
+import { readJsonFile } from '../../../../src/runtime/shared/json-files';
+import {
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  writeControlPlaneRecord,
+  writeControlPlaneRecordWithinTransaction,
+  type SqliteDatabase,
+} from '../../../../src/runtime/control-plane/persistence/sqlite-store';
+import { type ControllerSession, type ControllerSessionStore, type ControllerType } from '../domain/types';
+import { getWorkContract, semanticWorkState } from '../../work/api/index';
+
+export interface ControllerSessionStoreOptions {
+  controllerHome: string;
+  /** Legacy repository provenance/migration hint only; canonical ControllerSession state is ForgeInstance-scoped. */
+  repoId: string;
+  now?: () => string;
+}
+
+const SESSION_STORE_NAMESPACE = 'controller_session_claim_store';
+const SESSION_STORE_KEY = 'index';
+const SESSION_STORE_SCHEMA_VERSION = 1;
+
+function assertControllerWorkClaimable(options: ControllerSessionStoreOptions, workId: string): void {
+  const work = getWorkContract({ controllerHome: options.controllerHome, repoId: options.repoId }, workId);
+  if (!work) return;
+  const state = semanticWorkState(work);
+  if (state !== 'open') throw new Error(`WORK_CONTROLLER_CLAIM_TERMINAL: ${workId}:${state}`);
+}
+
+export type ClaimedControllerSession = ControllerSession & { claimGeneration: number };
+
+export interface ControllerSessionClaimInput {
+  workId: string;
+  controllerId: string;
+  controllerType: ControllerType;
+  sessionId: string;
+  /** Optional digest of the Work-bound controller capability. Plaintext is never persisted in ControllerSession. */
+  authorityDigest?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+  /** Optional compare-and-swap fence supplied by a recovering caller. */
+  expectedClaimGeneration?: number;
+  /**
+   * Permit a different authenticated controller epoch to recover this Work only
+   * after the canonical execution/activity grace has elapsed. Callers must pair
+   * this with expectedClaimGeneration from the owner they observed.
+   */
+  allowStaleRecovery?: boolean;
+  leaseMs?: number;
+}
+
+function path(options: ControllerSessionStoreOptions): string {
+  return join(repositoryControllerRoot(options.controllerHome, options.repoId), 'controller-sessions.json');
+}
+
+function now(options: ControllerSessionStoreOptions): string { return options.now?.() ?? new Date().toISOString(); }
+
+function legacyStore(options: ControllerSessionStoreOptions): ControllerSessionStore {
+  const sqlite = readControlPlaneRecord<ControllerSessionStore>(
+    options.controllerHome,
+    SESSION_STORE_NAMESPACE,
+    options.repoId,
+    SESSION_STORE_KEY,
+  )?.value;
+  if (sqlite) return sqlite;
+  return readJsonFile<ControllerSessionStore>(path(options), {
+    schemaVersion: 1,
+    updatedAt: now(options),
+    sessions: [],
+  });
+}
+
+function mergeSessionStores(
+  canonical: ControllerSessionStore,
+  legacy: ControllerSessionStore,
+): ControllerSessionStore {
+  const sessions = new Map(canonical.sessions.map((session) => [session.workId, session]));
+  for (const candidate of legacy.sessions) {
+    const existing = sessions.get(candidate.workId);
+    if (!existing) {
+      sessions.set(candidate.workId, candidate);
+      continue;
+    }
+    if (JSON.stringify(existing) === JSON.stringify(candidate)) continue;
+    const existingGeneration = existing.claimGeneration ?? 0;
+    const candidateGeneration = candidate.claimGeneration ?? 0;
+    const existingClaimedAt = Date.parse(existing.claimedAt);
+    const candidateClaimedAt = Date.parse(candidate.claimedAt);
+    if (existingGeneration > candidateGeneration
+      || (existingGeneration === candidateGeneration
+        && Number.isFinite(existingClaimedAt)
+        && Number.isFinite(candidateClaimedAt)
+        && existingClaimedAt > candidateClaimedAt)) {
+      // Canonical state has advanced since the read-only legacy snapshot.
+      continue;
+    }
+    throw new Error(`CONTROLLER_SESSION_ID_COLLISION: ${candidate.workId}`);
+  }
+  return {
+    schemaVersion: 1,
+    updatedAt: canonical.updatedAt >= legacy.updatedAt ? canonical.updatedAt : legacy.updatedAt,
+    sessions: [...sessions.values()],
+  };
+}
+
+function read(options: ControllerSessionStoreOptions): ControllerSessionStore {
+  const canonical = readControlPlaneRecord<ControllerSessionStore>(
+    options.controllerHome,
+    SESSION_STORE_NAMESPACE,
+    FORGE_INSTANCE_SCOPE_KEY,
+    SESSION_STORE_KEY,
+  )?.value ?? { schemaVersion: 1 as const, updatedAt: now(options), sessions: [] };
+  return mergeSessionStores(canonical, legacyStore(options));
+}
+
+function write(options: ControllerSessionStoreOptions, store: ControllerSessionStore): void {
+  writeControlPlaneRecord(options.controllerHome, {
+    namespace: SESSION_STORE_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: SESSION_STORE_KEY,
+    schemaVersion: SESSION_STORE_SCHEMA_VERSION,
+    value: store,
+    action: 'controller_session_claim_write',
+  });
+}
+
+const RETAINED_SESSION_NAMESPACE = 'controller_session_identity';
+
+interface RetainedControllerSessionRecord {
+  schemaVersion: 1;
+  session: ControllerSession;
+  retainedAt: string;
+  releasedAt?: string;
+}
+
+function retainedControllerSessionRecord(
+  options: ControllerSessionStoreOptions,
+  session: ControllerSession,
+  releasedAt?: string,
+): RetainedControllerSessionRecord {
+  const retainedAt = now(options);
+  return { schemaVersion: 1, session, retainedAt, ...(releasedAt ? { releasedAt } : {}) };
+}
+
+function persistRetainedControllerSession(
+  options: ControllerSessionStoreOptions,
+  session: ControllerSession,
+  releasedAt?: string,
+): void {
+  writeControlPlaneRecord(options.controllerHome, {
+    namespace: RETAINED_SESSION_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: session.workId,
+    schemaVersion: 1,
+    value: retainedControllerSessionRecord(options, session, releasedAt),
+    action: releasedAt ? 'controller_session_identity_released' : 'controller_session_identity_retained',
+  });
+}
+
+function persistRetainedControllerSessionWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+  session: ControllerSession,
+  releasedAt?: string,
+): void {
+  writeControlPlaneRecordWithinTransaction(database, {
+    namespace: RETAINED_SESSION_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: session.workId,
+    schemaVersion: 1,
+    value: retainedControllerSessionRecord(options, session, releasedAt),
+    action: releasedAt ? 'controller_session_identity_released' : 'controller_session_identity_retained',
+  });
+}
+
+/** Durable session identity survives transport/lease release; it is not an ownership lease. */
+export function getRetainedControllerSession(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+): ControllerSession | undefined {
+  const canonical = readControlPlaneRecord<RetainedControllerSessionRecord>(
+    options.controllerHome,
+    RETAINED_SESSION_NAMESPACE,
+    FORGE_INSTANCE_SCOPE_KEY,
+    workId,
+  )?.value.session;
+  const legacy = readControlPlaneRecord<RetainedControllerSessionRecord>(
+    options.controllerHome,
+    RETAINED_SESSION_NAMESPACE,
+    options.repoId,
+    workId,
+  )?.value.session;
+  if (canonical && legacy && JSON.stringify(canonical) !== JSON.stringify(legacy)) {
+    const canonicalGeneration = canonical.claimGeneration ?? 0;
+    const legacyGeneration = legacy.claimGeneration ?? 0;
+    const canonicalClaimedAt = Date.parse(canonical.claimedAt);
+    const legacyClaimedAt = Date.parse(legacy.claimedAt);
+    if (!(canonicalGeneration > legacyGeneration
+      || (canonicalGeneration === legacyGeneration
+        && Number.isFinite(canonicalClaimedAt)
+        && Number.isFinite(legacyClaimedAt)
+        && canonicalClaimedAt > legacyClaimedAt))) {
+      throw new Error(`CONTROLLER_SESSION_ID_COLLISION: ${workId}`);
+    }
+  }
+  return canonical ?? legacy ?? read(options).sessions.find((entry) => entry.workId === workId);
+}
+
+const DEFAULT_CONTROLLER_RECOVERY_GRACE_MS = 5 * 60_000;
+const MAX_CONTROLLER_RECOVERY_GRACE_MS = 60 * 60_000;
+const DEFAULT_CONTROLLER_LEASE_MS = 60 * 60_000;
+const MAX_CONTROLLER_LEASE_MS = 60 * 60_000;
+
+function optionsNowMs(options: ControllerSessionStoreOptions): number {
+  const parsed = Date.parse(now(options));
+  return Number.isFinite(parsed) ? parsed : Date.now();
+}
+
+function activeSession(store: ControllerSessionStore, workId: string, atMs: number = Date.now()): ControllerSession | undefined {
+  return store.sessions.find((session) => session.workId === workId && Date.parse(session.leaseExpiresAt) > atMs);
+}
+
+function sessionBlocksRecovery(
+  options: ControllerSessionStoreOptions,
+  owner: ControllerSession,
+  input: { nowMs: number; graceMs?: number },
+): boolean {
+  const execution = peekExecutionSession(options.controllerHome, owner.sessionId);
+  const graceMs = Math.max(60_000, Math.min(input.graceMs ?? DEFAULT_CONTROLLER_RECOVERY_GRACE_MS, MAX_CONTROLLER_RECOVERY_GRACE_MS));
+  if (execution?.invalidatedAt) {
+    const invalidatedAtMs = Date.parse(execution.invalidatedAt);
+    if (!Number.isFinite(invalidatedAtMs)) return true;
+    return input.nowMs - invalidatedAtMs < graceMs;
+  }
+  if (execution?.activeWorkId && execution.activeWorkId !== owner.workId) return false;
+  const activityMs = [execution?.lastValidatedAt, execution?.updatedAt, owner.claimedAt]
+    .map((value) => value ? Date.parse(value) : Number.NaN)
+    .filter(Number.isFinite)
+    .reduce((latest, value) => Math.max(latest, value), Number.NEGATIVE_INFINITY);
+  if (!Number.isFinite(activityMs)) return false;
+  return input.nowMs - activityMs < graceMs;
+}
+
+export function controllerSessionBlocksRecovery(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+  input: { nowMs?: number; graceMs?: number } = {},
+): boolean {
+  const nowMs = input.nowMs ?? Date.now();
+  const owner = activeSession(read(options), workId, nowMs);
+  if (!owner) return false;
+  return sessionBlocksRecovery(options, owner, { nowMs, graceMs: input.graceMs });
+}
+
+function assertIdentity(input: ControllerSessionClaimInput): void {
+  if (!input.workId.trim() || !input.controllerId.trim() || !input.sessionId.trim()) {
+    throw new Error('CONTROLLER_SESSION_IDENTITY_REQUIRED');
+  }
+}
+
+/**
+ * Compatibility no-op. ControllerSession is mechanical dispatch/reattachment
+ * state and does not decide whether semantic Work is open or terminal.
+ */
+export function assertControllerSessionWorkClaimable(_options: ControllerSessionStoreOptions, _workId: string): void {}
+
+function claimedSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput,
+  claimedAt: string,
+  previous?: ControllerSession,
+): ClaimedControllerSession {
+  const leaseExpiresAt = new Date(
+    Date.parse(claimedAt) + Math.max(1_000, Math.min(input.leaseMs ?? DEFAULT_CONTROLLER_LEASE_MS, MAX_CONTROLLER_LEASE_MS)),
+  ).toISOString();
+  const previousPrincipal = previous?.principalId?.trim() || previous?.controllerId;
+  const inputPrincipal = input.principalId?.trim() || input.controllerId;
+  const sameOwner = previous?.controllerId === input.controllerId
+    && previous?.controllerType === input.controllerType
+    && previousPrincipal === inputPrincipal
+    && (previous.controllerInstanceId ?? '') === (input.controllerInstanceId?.trim() ?? '');
+  const claimGeneration = sameOwner
+    ? Math.max(1, previous?.claimGeneration ?? 1)
+    : Math.max(0, previous?.claimGeneration ?? 0) + 1;
+  const authorityDigest = input.authorityDigest?.trim() || (sameOwner ? previous?.authorityDigest?.trim() : '') || '';
+  return {
+    schemaVersion: 1,
+    workId: input.workId,
+    controllerId: input.controllerId,
+    controllerType: input.controllerType,
+    sessionId: input.sessionId,
+    ...(authorityDigest ? { authorityDigest } : {}),
+    ...(input.principalId?.trim() ? { principalId: input.principalId.trim() } : {}),
+    ...(input.controllerInstanceId?.trim() ? { controllerInstanceId: input.controllerInstanceId.trim() } : {}),
+    claimGeneration,
+    claimedAt,
+    leaseExpiresAt,
+  };
+}
+
+function assertExpectedGeneration(input: ControllerSessionClaimInput, current: ControllerSession | undefined): void {
+  if (input.expectedClaimGeneration === undefined) return;
+  const actual = current?.claimGeneration ?? 0;
+  if (actual !== input.expectedClaimGeneration) {
+    throw new Error(`WORK_CLAIM_GENERATION_MISMATCH: ${input.workId} expected=${input.expectedClaimGeneration} actual=${actual}`);
+  }
+}
+
+function preparedClaim(
+  options: ControllerSessionStoreOptions,
+  store: ControllerSessionStore,
+  input: ControllerSessionClaimInput,
+  previous?: ControllerSession,
+): { claimedAt: string; session: ClaimedControllerSession; nextStore: ControllerSessionStore } {
+  const claimedAt = now(options);
+  const claimedAtMs = Date.parse(claimedAt);
+  const session = claimedSession(options, input, claimedAt, previous);
+  const sessions = [
+    ...store.sessions.filter((entry) => entry.workId !== input.workId && Date.parse(entry.leaseExpiresAt) > claimedAtMs),
+    session,
+  ];
+  return { claimedAt, session, nextStore: { schemaVersion: 1, updatedAt: claimedAt, sessions } };
+}
+
+function persistClaim(
+  options: ControllerSessionStoreOptions,
+  store: ControllerSessionStore,
+  input: ControllerSessionClaimInput,
+  previous?: ControllerSession,
+): ClaimedControllerSession {
+  const prepared = preparedClaim(options, store, input, previous);
+  write(options, prepared.nextStore);
+  persistRetainedControllerSession(options, prepared.session);
+  return prepared.session;
+}
+
+function readSessionStoreWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+) {
+  let current = readControlPlaneRecordWithinTransaction<ControllerSessionStore>(
+    database, SESSION_STORE_NAMESPACE, FORGE_INSTANCE_SCOPE_KEY, SESSION_STORE_KEY,
+  );
+  const legacySqlite = readControlPlaneRecordWithinTransaction<ControllerSessionStore>(
+    database, SESSION_STORE_NAMESPACE, options.repoId, SESSION_STORE_KEY,
+  )?.value;
+  const legacy = legacySqlite ?? readJsonFile<ControllerSessionStore>(path(options), {
+    schemaVersion: 1,
+    updatedAt: now(options),
+    sessions: [],
+  });
+  if (current) return { ...current, value: mergeSessionStores(current.value, legacy) };
+  current = writeControlPlaneRecordWithinTransaction(database, {
+    namespace: SESSION_STORE_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: SESSION_STORE_KEY,
+    schemaVersion: SESSION_STORE_SCHEMA_VERSION,
+    value: legacy,
+    action: 'legacy_controller_session_import',
+    expectedRevision: null,
+  });
+  return current;
+}
+
+function persistClaimWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+  storeRecord: ReturnType<typeof readSessionStoreWithinTransaction>,
+  input: ControllerSessionClaimInput,
+  previous?: ControllerSession,
+): ClaimedControllerSession {
+  const prepared = preparedClaim(options, storeRecord.value, input, previous);
+  writeControlPlaneRecordWithinTransaction(database, {
+    namespace: SESSION_STORE_NAMESPACE,
+    scope: FORGE_INSTANCE_SCOPE_KEY,
+    key: SESSION_STORE_KEY,
+    schemaVersion: SESSION_STORE_SCHEMA_VERSION,
+    value: prepared.nextStore,
+    action: 'controller_session_claim_write',
+    expectedRevision: storeRecord.revision,
+  });
+  persistRetainedControllerSessionWithinTransaction(database, options, prepared.session);
+  return prepared.session;
+}
+
+export function getControllerSession(options: ControllerSessionStoreOptions, workId: string): ControllerSession | undefined {
+  return activeSession(read(options), workId, optionsNowMs(options));
+}
+
+export function listControllerSessions(options: ControllerSessionStoreOptions): ControllerSession[] {
+  const at = optionsNowMs(options);
+  return read(options).sessions.filter((session) => Date.parse(session.leaseExpiresAt) > at);
+}
+
+export interface ControllerOwnershipAuthority {
+  controllerId: string;
+  controllerType: ControllerType;
+  principalId: string;
+  controllerInstanceId: string;
+  claimGeneration: number;
+}
+
+export type ControllerTerminalizationAuthority = ControllerOwnershipAuthority;
+
+export function controllerSessionPrincipalId(
+  owner: Pick<ControllerSession, 'principalId' | 'controllerId'>,
+): string {
+  return owner.principalId?.trim() || owner.controllerId;
+}
+
+function digestControllerAuthority(authorityId: string): string {
+  return createHash('sha256').update(authorityId).digest('hex');
+}
+
+/** Mint a non-relay Work-bound capability. Only the digest belongs in durable ControllerSession state. */
+export function mintControllerSessionAuthority(): { authorityId: string; authorityDigest: string } {
+  const authorityId = `ctrl_${randomUUID().replace(/-/g, '')}`;
+  return { authorityId, authorityDigest: digestControllerAuthority(authorityId) };
+}
+
+/** Bind an already-authorized opaque capability without persisting its plaintext value. */
+export function controllerSessionAuthorityDigest(authorityId: string): string {
+  const normalized = authorityId.trim();
+  if (!normalized) throw new Error('WORK_CONTROLLER_AUTHORITY_REQUIRED');
+  return digestControllerAuthority(normalized);
+}
+
+/** Verify an opaque capability without exposing or persisting its plaintext value. */
+export function controllerSessionAuthorityMatches(owner: ControllerSession, authorityId: string | undefined): boolean {
+  const expected = owner.authorityDigest?.trim() || '';
+  const candidate = authorityId?.trim() || '';
+  if (!expected || !candidate) return false;
+  const actual = digestControllerAuthority(candidate);
+  if (expected.length !== actual.length) return false;
+  return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(actual, 'hex'));
+}
+
+export function requireControllerOwnershipAuthority(
+  owner: ControllerSession,
+  workId: string = owner.workId,
+): ControllerOwnershipAuthority {
+  const principalId = controllerSessionPrincipalId(owner);
+  const controllerInstanceId = owner.controllerInstanceId?.trim() || '';
+  if (!controllerInstanceId) throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${workId}`);
+  if (typeof owner.claimGeneration !== 'number' || owner.claimGeneration < 1) {
+    throw new Error(`WORK_CONTROLLER_CLAIM_GENERATION_REQUIRED: ${workId}`);
+  }
+  return {
+    controllerId: owner.controllerId,
+    controllerType: owner.controllerType,
+    principalId,
+    controllerInstanceId,
+    claimGeneration: owner.claimGeneration,
+  };
+}
+
+export function assertControllerOwnershipAuthority(
+  owner: ControllerSession,
+  expected: {
+    workId?: string;
+    controllerId: string;
+    principalId: string;
+    controllerInstanceId?: string;
+    controllerType?: ControllerType;
+  },
+): ControllerOwnershipAuthority {
+  const workId = expected.workId ?? owner.workId;
+  const authority = requireControllerOwnershipAuthority(owner, workId);
+  if (authority.controllerId !== expected.controllerId.trim()) {
+    throw new Error(`WORK_CONTROLLER_OWNER_MISMATCH: ${workId} is owned by ${owner.controllerId}`);
+  }
+  if (expected.controllerType && authority.controllerType !== expected.controllerType) {
+    throw new Error(`WORK_CONTROLLER_TYPE_MISMATCH: ${workId} is owned by ${owner.controllerType}`);
+  }
+  if (authority.principalId !== expected.principalId.trim()) {
+    throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${workId}`);
+  }
+  if (expected.controllerInstanceId !== undefined
+    && authority.controllerInstanceId !== expected.controllerInstanceId.trim()) {
+    throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${workId}`);
+  }
+  return authority;
+}
+
+export type ControllerTerminalizationFenceReason =
+  | 'active_controller_claim'
+  | 'stale_controller_authority'
+  | 'controller_claim_missing';
+
+export type ControllerTerminalizationFenceResult<T> =
+  | { allowed: true; value: T; owner?: ControllerSession }
+  | { allowed: false; reason: ControllerTerminalizationFenceReason; owner?: ControllerSession };
+
+export function controllerTerminalizationAuthorityFromSession(
+  owner: ControllerSession,
+): ControllerTerminalizationAuthority | undefined {
+  try {
+    return requireControllerOwnershipAuthority(owner);
+  } catch {
+    return undefined;
+  }
+}
+
+function controllerTerminalizationAuthorityMatches(
+  owner: ControllerSession,
+  authority: ControllerTerminalizationAuthority,
+): boolean {
+  const ownerPrincipal = controllerSessionPrincipalId(owner);
+  const ownerInstanceId = owner.controllerInstanceId?.trim() || '';
+  return owner.controllerId === authority.controllerId
+    && owner.controllerType === authority.controllerType
+    && ownerPrincipal === authority.principalId.trim()
+    && ownerInstanceId === authority.controllerInstanceId.trim()
+    && owner.claimGeneration === authority.claimGeneration;
+}
+
+/**
+ * Serialize control-path Work terminalization against the same canonical
+ * ControllerSession task lock used by claim/resume/release. This is a fence,
+ * not a second lifecycle authority: WorkContract remains the terminal state
+ * authority and ControllerSession remains the ownership authority.
+ *
+ * A caller without Controller authority may terminalize only while the Work is
+ * unclaimed. A caller that observed a live owner must present that exact durable
+ * owner epoch. Transport session ids are intentionally not compared because MCP
+ * transports may rotate without moving Work ownership; controller instance plus
+ * claim generation fence stale controller epochs while preserving that rotation.
+ */
+export function withControllerSessionTerminalizationFence<T>(
+  options: ControllerSessionStoreOptions,
+  input: {
+    workId: string;
+    actor: string;
+    authority?: ControllerTerminalizationAuthority;
+  },
+  operation: () => T,
+): ControllerTerminalizationFenceResult<T> {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'global', resource: 'controller-session-store' },
+    input.actor,
+    () => {
+      const owner = activeSession(read(options), input.workId, optionsNowMs(options));
+      if (!owner) {
+        if (input.authority) return { allowed: false, reason: 'controller_claim_missing' };
+        return { allowed: true, value: operation() };
+      }
+      if (!input.authority) return { allowed: false, reason: 'active_controller_claim', owner };
+
+      if (!controllerTerminalizationAuthorityMatches(owner, input.authority)) {
+        return { allowed: false, reason: 'stale_controller_authority', owner };
+      }
+      return { allowed: true, value: operation(), owner };
+    },
+  );
+}
+
+/**
+ * Release a live ControllerSession only when the caller still owns the exact
+ * durable controller epoch it observed. This closes the release-then-terminalize
+ * race without changing WorkContract lifecycle authority.
+ */
+export function releaseControllerSessionWithAuthority(
+  options: ControllerSessionStoreOptions,
+  input: {
+    workId: string;
+    actor: string;
+    authority: ControllerTerminalizationAuthority;
+  },
+): ControllerTerminalizationFenceResult<void> {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'global', resource: 'controller-session-store' },
+    input.actor,
+    () => {
+      const store = read(options);
+      const owner = activeSession(store, input.workId, optionsNowMs(options));
+      if (!owner) return { allowed: false, reason: 'controller_claim_missing' };
+      if (!controllerTerminalizationAuthorityMatches(owner, input.authority)) {
+        return { allowed: false, reason: 'stale_controller_authority', owner };
+      }
+      const releasedAt = now(options);
+      persistRetainedControllerSession(options, owner, releasedAt);
+      const sessions = store.sessions.filter((entry) => entry.workId !== input.workId);
+      write(options, { schemaVersion: 1, updatedAt: releasedAt, sessions });
+      return { allowed: true, value: undefined, owner };
+    },
+  );
+}
+
+export function releaseObservedControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: { workId: string; actor: string; owner: ControllerSession },
+): ControllerTerminalizationFenceResult<void> {
+  const authority = controllerTerminalizationAuthorityFromSession(input.owner);
+  if (!authority) return { allowed: false, reason: 'stale_controller_authority', owner: input.owner };
+  return releaseControllerSessionWithAuthority(options, {
+    workId: input.workId,
+    actor: input.actor,
+    authority,
+  });
+}
+
+/**
+ * Strict claim used for first ownership acquisition and explicit release/reclaim flows.
+ * A live claim with any different controller or transport session remains fenced.
+ */
+export function claimControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput,
+): ClaimedControllerSession {
+  assertIdentity(input);
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'global', resource: 'controller-session-store' },
+    `controller-claim:${input.controllerId}:${input.sessionId}`,
+    () => {
+      assertControllerWorkClaimable(options, input.workId);
+      const store = read(options);
+      const current = activeSession(store, input.workId, optionsNowMs(options));
+      const previous = current ?? store.sessions
+        .filter((entry) => entry.workId === input.workId)
+        .sort((left, right) => (right.claimGeneration ?? 0) - (left.claimGeneration ?? 0))[0];
+      assertExpectedGeneration(input, current);
+      if (current && (current.controllerId !== input.controllerId || current.sessionId !== input.sessionId)) {
+        throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} is owned by ${current.controllerId}`);
+      }
+      return persistClaim(options, store, input, previous);
+    },
+  );
+}
+
+/**
+ * Resume a claim after transport replacement. Durable Work ownership belongs to
+ * the authenticated principal/controller epoch, not to one MCP transport session.
+ * A same-principal session rotation therefore preserves ownership generation;
+ * a controller-epoch change is recovery and advances the generation fence.
+ */
+function resumableControllerSessionPrevious(
+  options: ControllerSessionStoreOptions,
+  store: ControllerSessionStore,
+  input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
+  database?: SqliteDatabase,
+): ControllerSession | undefined {
+  assertControllerWorkClaimable(options, input.workId);
+  const currentNowMs = optionsNowMs(options);
+  const current = activeSession(store, input.workId, currentNowMs);
+  assertExpectedGeneration(input, current);
+  if (!current) {
+    return store.sessions
+      .filter((entry) => entry.workId === input.workId)
+      .sort((left, right) => (right.claimGeneration ?? 0) - (left.claimGeneration ?? 0))[0];
+  }
+  const explicitPrincipal = current.principalId?.trim();
+  const priorExecution = explicitPrincipal
+    ? undefined
+    : database
+      ? peekExecutionSessionWithinTransaction(database, options.controllerHome, current.sessionId)
+      : peekExecutionSession(options.controllerHome, current.sessionId);
+  const currentPrincipal = explicitPrincipal || priorExecution?.principalId?.trim() || current.controllerId;
+  const staleRecoveryAllowed = input.allowStaleRecovery === true
+    && input.expectedClaimGeneration !== undefined
+    && !sessionBlocksRecovery(options, current, { nowMs: currentNowMs });
+  if (currentPrincipal !== input.principalId.trim() && !staleRecoveryAllowed) {
+    throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${input.workId} is owned by another authenticated principal`);
+  }
+  if (current.controllerId !== input.controllerId && !staleRecoveryAllowed) {
+    throw new Error(`WORK_ALREADY_CLAIMED: ${input.workId} is owned by ${current.controllerId}`);
+  }
+  if (current.controllerType !== input.controllerType && !staleRecoveryAllowed) {
+    throw new Error(`WORK_CONTROLLER_TYPE_MISMATCH: ${input.workId} is owned by ${current.controllerType}`);
+  }
+  return current;
+}
+
+export function withControllerSessionMutationLock<T>(
+  options: ControllerSessionStoreOptions,
+  workId: string,
+  actor: string,
+  operation: () => T,
+): T {
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'global', resource: 'controller-session-store' },
+    actor,
+    operation,
+  );
+}
+
+/** Transaction-aware resume used only by higher-level Controller claim orchestration while the canonical session lock is held. */
+export function resumeControllerSessionWithinTransaction(
+  database: SqliteDatabase,
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
+): ClaimedControllerSession {
+  assertIdentity(input);
+  if (!input.principalId.trim() || !input.controllerInstanceId.trim()) throw new Error('CONTROLLER_RESUME_AUTHORITY_REQUIRED');
+  const storeRecord = readSessionStoreWithinTransaction(database, options);
+  const previous = resumableControllerSessionPrevious(options, storeRecord.value, input, database);
+  return persistClaimWithinTransaction(database, options, storeRecord, input, previous);
+}
+
+export function resumeControllerSession(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput & { principalId: string; controllerInstanceId: string },
+): ClaimedControllerSession {
+  assertIdentity(input);
+  if (!input.principalId.trim() || !input.controllerInstanceId.trim()) {
+    throw new Error('CONTROLLER_RESUME_AUTHORITY_REQUIRED');
+  }
+  return withControllerSessionMutationLock(
+    options,
+    input.workId,
+    `controller-resume:${input.controllerId}:${input.sessionId}`,
+    () => {
+      const store = read(options);
+      const previous = resumableControllerSessionPrevious(options, store, input);
+      return persistClaim(options, store, input, previous);
+    },
+  );
+}
+
+/**
+ * Rebind one active Work to the authenticated Controller transport/Runtime that
+ * is serving the current request. Same-instance transport rollover needs only
+ * principal/controller proof. A Runtime-instance change additionally requires
+ * positive proof that the requested instance is the live canonical Runtime;
+ * this prevents a stale old Runtime request from migrating ownership backwards.
+ * The observed claim generation is always supplied as a CAS fence.
+ */
+export function bindControllerSessionToCurrentRuntime(
+  options: ControllerSessionStoreOptions,
+  input: ControllerSessionClaimInput & {
+    principalId: string;
+    controllerInstanceId: string;
+    currentRuntimeInstanceId?: string;
+    allowClaimIfMissing?: boolean;
+  },
+): ControllerSession {
+  assertIdentity(input);
+  const current = getControllerSession(options, input.workId);
+  if (!current) {
+    if (input.allowClaimIfMissing !== true) throw new Error(`WORK_CONTROLLER_OWNER_REQUIRED: ${input.workId}`);
+    return claimControllerSession(options, { ...input, expectedClaimGeneration: 0 });
+  }
+  const currentPrincipal = controllerSessionPrincipalId(current);
+  if (current.controllerId !== input.controllerId) {
+    throw new Error(`WORK_CONTROLLER_OWNER_MISMATCH: ${input.workId} is owned by ${current.controllerId}`);
+  }
+  if (current.controllerType !== input.controllerType) {
+    throw new Error(`WORK_CONTROLLER_TYPE_MISMATCH: ${input.workId} is owned by ${current.controllerType}`);
+  }
+  if (currentPrincipal !== input.principalId.trim()) {
+    throw new Error(`WORK_CONTROLLER_PRINCIPAL_MISMATCH: ${input.workId}`);
+  }
+  const ownerInstanceId = current.controllerInstanceId?.trim() || '';
+  const requestedInstanceId = input.controllerInstanceId.trim();
+  if (ownerInstanceId !== requestedInstanceId) {
+    const currentRuntimeInstanceId = input.currentRuntimeInstanceId?.trim() || '';
+    if (!currentRuntimeInstanceId || currentRuntimeInstanceId !== requestedInstanceId) {
+      throw new Error(`WORK_CONTROLLER_INSTANCE_MISMATCH: ${input.workId}`);
+    }
+  }
+  const requestedAuthorityDigest = input.authorityDigest?.trim() || '';
+  const currentAuthorityDigest = current.authorityDigest?.trim() || '';
+  if (
+    ownerInstanceId === requestedInstanceId
+    && current.sessionId === input.sessionId
+    && (!requestedAuthorityDigest || requestedAuthorityDigest === currentAuthorityDigest)
+  ) return current;
+  // The opaque Work capability belongs to durable ownership, not to one
+  // transport or Runtime process. A positively-current Runtime migration keeps
+  // the same digest while claim generation fences the new controller epoch.
+  const preservedAuthorityDigest = input.authorityDigest?.trim() || current.authorityDigest?.trim() || undefined;
+  return resumeControllerSession(options, {
+    ...input,
+    ...(preservedAuthorityDigest ? { authorityDigest: preservedAuthorityDigest } : {}),
+    expectedClaimGeneration: current.claimGeneration,
+  });
+}
+
+export function releaseControllerSession(options: ControllerSessionStoreOptions, workId: string, controllerId: string): void {
+  withControllerLock(
+    options.controllerHome,
+    { scope: 'global', resource: 'controller-session-store' },
+    `controller-release:${controllerId}`,
+    () => {
+      const store = read(options);
+      const owner = store.sessions.find((entry) => entry.workId === workId && entry.controllerId === controllerId);
+      const releasedAt = now(options);
+      if (owner) persistRetainedControllerSession(options, owner, releasedAt);
+      const sessions = store.sessions.filter((entry) => entry.workId !== workId || entry.controllerId !== controllerId);
+      write(options, { schemaVersion: 1, updatedAt: releasedAt, sessions });
+    },
+  );
+}