@abot-ai/socket 0.1.0 → 0.2.0

package/src/relay/relay-approvals.mjs

@@ -0,0 +1,86 @@
+import { expectedResponseType } from '../protocol/protocol.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.mjs';
+import { isRecord, isRelayId, relayError } from './relay-runtime-registration.mjs';
+import { RelayRequestAdoption } from './relay-request-adoption.mjs';
+
+function validWait(wait) {
+  return isRecord(wait) && isRelayId(wait.generation) && isRelayId(wait.waitId)
+    && Number.isSafeInteger(wait.revision) && wait.revision >= 0;
+}
+
+function validResponse(command, body) {
+  if (!body.ok) return typeof body.error === 'string' && body.error.length <= 256;
+  if (command.type === 'request.approval.decide.request') {
+    return isRecord(body.result) && typeof body.result.accepted === 'boolean'
+      && (body.result.duplicate === undefined || typeof body.result.duplicate === 'boolean')
+      && (body.result.reason === undefined || typeof body.result.reason === 'string');
+  }
+  if (!Array.isArray(body.approvals) || body.approvals.length > 64) return false;
+  const seen = new Set();
+  for (const approval of body.approvals) {
+    const request = approval?.request;
+    if (!isRecord(approval) || !isRecord(request) || request.requestId !== command.requestId) return false;
+    if (typeof request.approvalId !== 'string' || !request.approvalId || request.approvalId.length > 512) return false;
+    if (seen.has(request.approvalId)) return false;
+    seen.add(request.approvalId);
+    if (approval.wait !== undefined && !validWait(approval.wait)) return false;
+  }
+  if (body.lifecycle !== null && !isRecord(body.lifecycle)) return false;
+  if (body.lifecycle?.sessionId !== undefined && body.lifecycle.sessionId !== command.sessionId) return false;
+  if (body.lifecycle?.requestId !== undefined && body.lifecycle.requestId !== command.requestId) return false;
+  if (body.finalState === null) return true;
+  return isRecord(body.finalState) && ['completed', 'failed'].includes(body.finalState.status)
+    && body.approvals.length === 0;
+}
+
+/** An owner-scoped transport view. The runtime alone stores and decides approvals. */
+export class RelayApprovals {
+  constructor({ ownership, requests, correlations, transmit, respond, error,
+    connected, currentRuntime, assertSessionAvailable }) {
+    Object.assign(this, { ownership, requests, correlations, transmit, respond, error });
+    this.adoption = new RelayRequestAdoption({ ownership, requests, correlations, transmit, error,
+      connected, currentRuntime, assertSessionAvailable,
+      recover: (client, runtime, id, command) => this.dispatch(client, runtime, id, command) });
+  }
+
+  owned(client, runtime, command) {
+    if (!this.ownership) throw relayError('approval_access_unavailable');
+    if (!runtime.features.includes('request_approvals_v1')) throw relayError('approvals_unsupported');
+    const owner = this.ownership.get(runtime.runtimeId, command.requestId);
+    if (!owner || owner.subject !== client.subject || owner.sessionId !== command.sessionId) {
+      throw relayError('request_not_owned');
+    }
+    return owner;
+  }
+
+  dispatch(client, runtime, id, command) {
+    if (this.adoption.beginIfUnowned(client, runtime, id, command)) return;
+    this.adoption.assertNoPendingRequest(runtime, command.requestId);
+    const owner = this.owned(client, runtime, command);
+    for (const entry of this.correlations.pending.values()) {
+      if (entry.runtime === runtime && entry.command.requestId === command.requestId
+        && isApprovalCommand(entry.command.type)) throw relayError('approval_request_pending');
+    }
+    let view;
+    const entry = this.correlations.create(client, runtime, id, command, expectedResponseType(command.type), {
+      matches: body => validResponse(command, body),
+      respond: (_entry, body) => {
+        if (!body.ok || body.result?.accepted === false) view.rollback();
+        else if (body.finalState) this.requests.markTerminal(view.record);
+        this.respond(client, runtime, id, body);
+      },
+      unknown: () => {
+        view.rollback();
+        this.error(client, runtime, id, 'outcome_unknown');
+      },
+      // A sent decision can still take effect after its client closes. Keep the
+      // mutation guard until its reply/deadline, but disconnect removes the view.
+      retainOnClientDisconnect: true,
+    });
+    try { view = this.requests.restore(client, runtime, owner); }
+    catch (error) { this.correlations.remove(entry); throw error; }
+    if (!this.transmit(runtime.peer, { ...command, correlationId: entry.correlationId })) {
+      this.correlations.fail(entry);
+    }
+  }
+}

package/src/relay/relay-correlations.mjs

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { isRecord, relayError } from './relay-runtime-registration.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.mjs';
+import { SPARK_OPEN_REQUEST, projectSparkOpenResponse } from '../protocol/spark-chat-protocol.mjs';
 
 const MAX_PENDING = 128;
 const RPC_TIMEOUT_MS = 30_000;
@@ -10,12 +12,14 @@ function steeringKey(runtime, body) {
 
 function matchesResponseIdentity(entry, body) {
   const command = entry.command;
+  if (command.type === SPARK_OPEN_REQUEST) return projectSparkOpenResponse(body) !== null;
   if (command.type === 'steer_request') {
     return body.requestId === command.requestId && body.steerId === command.steerId
       && typeof body.accepted === 'boolean';
   }
   if (typeof body.ok !== 'boolean') return false;
-  if (command.type === 'request.events.request' && body.requestId !== command.requestId) return false;
+  if ((command.type === 'request.events.request' || isApprovalCommand(command.type))
+    && body.requestId !== command.requestId) return false;
   // Upload responses intentionally do not echo requestId in the existing runtime.
   if (body.requestId !== undefined && body.requestId !== command.requestId) return false;
   if (command.sessionId !== undefined && body.sessionId !== command.sessionId) return false;
@@ -28,7 +32,7 @@ function matchesResponseIdentity(entry, body) {
     if (!Array.isArray(body.events) || body.events.length > 8192) return false;
     if (body.events.some(event => !isRecord(event) || (event.requestId !== undefined && event.requestId !== command.requestId))) return false;
   }
-  return true;
+  return entry.lifecycle.matches?.(body) ?? true;
 }
 
 export class RelayCorrelations {
@@ -69,7 +73,8 @@ export class RelayCorrelations {
     if (entry.expiresAt <= this.now() || !matchesResponseIdentity(entry, body)) return false;
     // An invalid reply must never consume the genuine request's pending record.
     this.remove(entry);
-    (entry.lifecycle.respond ?? this.respond)(entry, body);
+    const response = entry.command.type === SPARK_OPEN_REQUEST ? projectSparkOpenResponse(body) : body;
+    (entry.lifecycle.respond ?? this.respond)(entry, response);
     return true;
   }
 

package/src/relay/relay-request-adoption.mjs

@@ -0,0 +1,97 @@
+import { isRecord, relayError } from './relay-runtime-registration.mjs';
+
+const REQUEST_STATUSES = new Set(['streaming', 'awaiting_approval', 'completed', 'failed']);
+const requestKey = (runtime, requestId) => JSON.stringify([runtime.generation, requestId]);
+const isTerminalRequest = request => ['completed', 'failed'].includes(request.status);
+
+function confirmedSnapshotRequest(command, body) {
+  if (!body.ok) throw relayError('request_scope_unverified');
+  if (!Array.isArray(body.requests) || body.nextCursor !== null) throw relayError('request_scope_unverified');
+  const matches = body.requests.filter(request => isRecord(request) && request.requestId === command.requestId);
+  if (matches.length !== 1) throw relayError('request_scope_unverified');
+  const request = matches[0];
+  if (request.sessionId !== command.sessionId) throw relayError('request_scope_unverified');
+  if (!REQUEST_STATUSES.has(request.status)) throw relayError('request_scope_unverified');
+  return request;
+}
+
+/** First contact with existing computer work needs canonical proof, never a client ownership claim. */
+export class RelayRequestAdoption {
+  constructor({ ownership, requests, correlations, transmit, connected, currentRuntime,
+    assertSessionAvailable, recover, error }) {
+    Object.assign(this, { ownership, requests, correlations, transmit, connected, currentRuntime,
+      assertSessionAvailable, recover, error });
+    this.pending = new Map();
+  }
+
+  assertNoPendingRequest(runtime, requestId) {
+    if (this.pending.has(requestKey(runtime, requestId))) throw relayError('approval_request_pending');
+  }
+
+  assertNoPendingSession(runtime, sessionId) {
+    for (const operation of this.pending.values()) {
+      if (operation.runtime === runtime && operation.command.sessionId === sessionId) {
+        throw relayError('session_busy');
+      }
+    }
+  }
+
+  assertCurrentPrincipal(client, runtime) {
+    if (!this.connected(client)) throw relayError('approval_access_unavailable');
+    if (!this.currentRuntime(runtime)) throw relayError('runtime_offline');
+    if (!client.allowedRuntimeIds.has(runtime.runtimeId)) throw relayError('runtime_forbidden');
+    if (this.ownership?.isOwnerSubject?.(client.subject) !== true) throw relayError('request_not_owned');
+    if (typeof this.ownership.adopt !== 'function') throw relayError('approval_access_unavailable');
+  }
+
+  assertCompatibleBinding(client, runtime, command) {
+    const binding = this.requests.bindings.get(JSON.stringify([runtime.runtimeId, command.requestId]));
+    if (!binding) return;
+    if (!binding.durable || binding.subject !== client.subject || binding.sessionId !== command.sessionId) {
+      throw relayError('request_not_owned');
+    }
+  }
+
+  beginIfUnowned(client, runtime, id, command) {
+    if (command.type !== 'request.approvals.request') return false;
+    if (!this.ownership || !runtime.features.includes('request_approvals_v1')) return false;
+    if (this.ownership.get(runtime.runtimeId, command.requestId)) return false;
+    this.assertCurrentPrincipal(client, runtime);
+    this.assertNoPendingRequest(runtime, command.requestId);
+    this.assertCompatibleBinding(client, runtime, command);
+    this.assertSessionAvailable(runtime, command.sessionId);
+    const operation = { client, runtime, id, command, key: requestKey(runtime, command.requestId) };
+    const snapshot = { type: 'session.snapshot.request', sessionId: command.sessionId, includeRequests: true };
+    const entry = this.correlations.create(client, runtime, id, snapshot, 'session.snapshot.response', {
+      respond: (_entry, body) => this.afterSnapshot(operation, body),
+      unknown: () => this.error(client, runtime, id, 'outcome_unknown'),
+      removed: () => {
+        if (this.pending.get(operation.key) === operation) this.pending.delete(operation.key);
+      },
+    });
+    this.pending.set(operation.key, operation);
+    if (!this.transmit(runtime.peer, { ...snapshot, correlationId: entry.correlationId })) {
+      this.correlations.fail(entry);
+    }
+    return true;
+  }
+
+  afterSnapshot(operation, body) {
+    const { client, runtime, id, command } = operation;
+    try {
+      this.assertCurrentPrincipal(client, runtime);
+      this.assertSessionAvailable(runtime, command.sessionId);
+      this.assertCompatibleBinding(client, runtime, command);
+      const canonical = confirmedSnapshotRequest(command, body);
+      const terminal = isTerminalRequest(canonical);
+      const binding = this.requests.bindings.get(JSON.stringify([runtime.runtimeId, command.requestId]));
+      this.requests.assertCapacity(binding, !terminal);
+      this.ownership.adopt({ subject: client.subject, deviceId: client.sessionId,
+        runtimeId: runtime.runtimeId, sessionId: command.sessionId, requestId: command.requestId }, terminal);
+      // Normal recovery binds before receiving approval events and retains the runtime's decision checks.
+      this.recover(client, runtime, id, command);
+    } catch (error) {
+      this.error(client, runtime, id, error.code ?? 'approval_access_unavailable');
+    }
+  }
+}

package/src/relay/relay-requests.mjs

@@ -15,27 +15,83 @@ function canConsumeObservedApproval(approval, approved, now) {
 }
 
 export class RelayRequests {
-  constructor({ now, event, unknown, observe = () => {} }) {
+  constructor({ now, event, unknown, ownership, observe = () => {} }) {
     this.now = now;
     this.event = event;
     this.unknown = unknown;
     this.observe = observe;
+    this.ownership = ownership;
     this.bindings = new Map();
   }
 
   create(client, runtime, command) {
     const key = keyFor(runtime.runtimeId, command.requestId);
-    if (this.bindings.has(key)) throw relayError('request_id_conflict');
-    if (this.bindings.size >= MAX_BINDINGS) throw relayError('request_capacity');
-    const activeCount = [...this.bindings.values()].filter(record => record.state === 'active').length;
-    if (activeCount >= MAX_ACTIVE) throw relayError('active_request_capacity');
+    if (this.bindings.has(key) || this.ownership?.get(runtime.runtimeId, command.requestId)) {
+      throw relayError('request_id_conflict');
+    }
+    this.assertCapacity();
+    const durable = command.approvalMode === 'durable_v1';
+    if (durable) {
+      if (!this.ownership) throw relayError('approval_access_unavailable');
+      if (!runtime.features.includes('request_approvals_v1')) throw relayError('approvals_unsupported');
+      // This commit precedes transport: an uncertain send must never permit a replayed run.
+      this.ownership.create({ subject: client.subject, deviceId: client.sessionId,
+        runtimeId: runtime.runtimeId, sessionId: command.sessionId, requestId: command.requestId });
+    }
     const record = { key, subject: client.subject, deviceId: client.sessionId, runtime, requestId: command.requestId,
-      sessionId: command.sessionId, state: 'active', subscribers: new Set([client]),
-      expiresAt: this.now() + BINDING_TTL_MS, approvals: new Map(), steering: new Set() };
+      sessionId: command.sessionId, state: 'active', subscribers: new Set([client]), durable,
+      expiresAt: durable ? Infinity : this.now() + BINDING_TTL_MS,
+      version: 0, approvals: new Map(), steering: new Set() };
     this.bindings.set(key, record);
     return record;
   }
 
+  assertCapacity(existing, active = true) {
+    if (!existing && this.bindings.size >= MAX_BINDINGS) throw relayError('request_capacity');
+    const activeCount = [...this.bindings.values()].filter(record => record.state === 'active').length;
+    if (active && existing?.state !== 'active' && activeCount >= MAX_ACTIVE) {
+      throw relayError('active_request_capacity');
+    }
+  }
+
+  /** Restore a delivery view, not authority to execute or approve the saved request. */
+  restore(client, runtime, owner) {
+    const key = keyFor(runtime.runtimeId, owner.requestId);
+    const previous = this.bindings.get(key);
+    if (previous && (!previous.durable || previous.subject !== owner.subject
+      || previous.sessionId !== owner.sessionId)) throw relayError('request_not_owned');
+    const active = owner.status !== 'terminal';
+    const reusable = previous?.runtime === runtime && previous.state === (active ? 'active' : 'terminal');
+    this.assertCapacity(previous, active);
+    const record = reusable ? previous : { key, subject: owner.subject, deviceId: owner.deviceId,
+      runtime, sessionId: owner.sessionId, requestId: owner.requestId, durable: true,
+      state: active ? 'active' : 'terminal', expiresAt: active ? Infinity : owner.terminalAt + BINDING_TTL_MS,
+      version: 0, subscribers: new Set(previous?.subscribers), approvals: new Map(), steering: new Set() };
+    const wasSubscribed = record.subscribers.has(client);
+    const version = record.version;
+    record.subscribers.add(client);
+    this.bindings.set(key, record);
+    return { record, rollback: () => {
+      if (this.bindings.get(key) !== record || record.version !== version) return;
+      if (!reusable) {
+        if (!wasSubscribed) record.subscribers.delete(client);
+        if (previous) {
+          previous.subscribers = new Set(record.subscribers);
+          this.bindings.set(key, previous);
+        }
+        else this.bindings.delete(key);
+      } else if (!wasSubscribed) record.subscribers.delete(client);
+    } };
+  }
+
+  markTerminal(record) {
+    if (record.durable) this.ownership.markTerminal(record.runtime.runtimeId, record.requestId);
+    record.state = 'terminal';
+    record.expiresAt = this.now() + BINDING_TTL_MS;
+    record.version += 1;
+    this.invalidateApprovals(record);
+  }
+
   owned(client, runtime, requestId, requireActive = false) {
     const record = this.bindings.get(keyFor(runtime.runtimeId, requestId));
     if (!record || record.subject !== client.subject) throw relayError('request_not_owned');
@@ -61,7 +117,7 @@ export class RelayRequests {
 
   consumeApproval(client, runtime, body) {
     for (const record of this.bindings.values()) {
-      if (record.runtime !== runtime || record.subject !== client.subject || record.state !== 'active') continue;
+      if (record.durable || record.runtime !== runtime || record.subject !== client.subject || record.state !== 'active') continue;
       const approval = record.approvals.get(body.approvalId);
       if (!approval) continue;
       if (!canConsumeObservedApproval(approval, body.approved, this.now())) throw relayError('approval_not_pending');
@@ -78,7 +134,7 @@ export class RelayRequests {
     if (!record || record.runtime !== runtime || record.state !== 'active') return false;
     if (!this.acceptSessionIdentity(record, body)) return false;
     if (body.type === 'event' && (typeof body.name !== 'string' || body.name.length > 256)) return false;
-    if (body.type === 'event' && body.name === 'tool.approval.required') {
+    if (!record.durable && body.type === 'event' && body.name === 'tool.approval.required') {
       if (!this.observeApproval(record, body.approvalId)) return false;
     }
     if (body.type === 'event' && ['tool.approval.granted', 'tool.approval.rejected'].includes(body.name)) {
@@ -86,10 +142,9 @@ export class RelayRequests {
       if (approval) approval.state = 'closed';
     }
     if (body.type === 'completed' || body.type === 'failed') {
-      record.state = 'terminal';
-      record.expiresAt = this.now() + BINDING_TTL_MS;
-      this.invalidateApprovals(record);
+      this.markTerminal(record);
     }
+    record.version += 1;
     try {
       this.observe({ deviceId: record.deviceId, runtimeId: runtime.runtimeId,
         sessionId: record.sessionId, requestId: record.requestId }, body);
@@ -99,6 +154,7 @@ export class RelayRequests {
   }
 
   acceptSessionIdentity(record, body) {
+    if (record.durable) return body.sessionId === record.sessionId;
     if (body.sessionId === undefined || body.sessionId === null) return true;
     if (!isRelayId(body.sessionId)) return false;
     if (record.sessionId && record.sessionId !== body.sessionId) return false;
@@ -126,7 +182,7 @@ export class RelayRequests {
   markUnknown(record, notify = true) {
     if (record.state !== 'active') return;
     record.state = 'unknown';
-    record.expiresAt = this.now() + BINDING_TTL_MS;
+    record.expiresAt = record.durable ? Infinity : this.now() + BINDING_TTL_MS;
     this.invalidateApprovals(record);
     if (notify) for (const client of record.subscribers) this.unknown(client, record);
   }

package/src/relay/relay-session-mutations.mjs

@@ -1,5 +1,6 @@
 import { expectedResponseType } from '../protocol/protocol.mjs';
 import { relayError } from './relay-runtime-registration.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.mjs';
 
 const MUTATIONS = new Set([
   'session.delete.request', 'session.messages.clear.request', 'session.message.delete.request',
@@ -14,8 +15,8 @@ const sessionKey = (runtime, sessionId) => JSON.stringify([runtime.generation, s
 
 /** A bounded read-before-delete guard, not an atomic lock over independent clients. */
 export class RelaySessionMutations {
-  constructor({ now, correlations, requests, transmit, connected, error, respond }) {
-    Object.assign(this, { now, correlations, requests, transmit, connected, error, respond });
+  constructor({ now, correlations, requests, ownership, transmit, connected, error, respond }) {
+    Object.assign(this, { now, correlations, requests, ownership, transmit, connected, error, respond });
     this.pending = new Map();
   }
 
@@ -25,12 +26,20 @@ export class RelaySessionMutations {
 
   assertNoObservedWork(runtime, sessionId) {
     for (const record of this.requests.bindings.values()) {
-      if (record.runtime !== runtime || record.sessionId !== sessionId) continue;
+      if (record.sessionId !== sessionId) continue;
+      if (record.durable) {
+        if (record.runtime.runtimeId !== runtime.runtimeId) continue;
+        // Unknown durable work needs individual canonical proof below; it is
+        // never treated as completed merely because this relay restarted.
+        if (record.state === 'unknown') continue;
+      } else if (record.runtime !== runtime) continue;
       if (record.state !== 'terminal') throw relayError('session_busy');
     }
     for (const entry of this.correlations.pending.values()) {
       if (entry.runtime === runtime && entry.command.sessionId === sessionId
-        && entry.command.type === 'attachment.upload.request') throw relayError('session_busy');
+        && (entry.command.type === 'attachment.upload.request' || isApprovalCommand(entry.command.type))) {
+        throw relayError('session_busy');
+      }
     }
   }
 
@@ -62,12 +71,37 @@ export class RelaySessionMutations {
         if (request.sessionId !== operation.command.sessionId) throw relayError('session_state_unavailable');
         if (!['completed', 'failed'].includes(request.status)) throw relayError('session_busy');
       }
-      this.send(operation, operation.command, result => this.respond(operation, result));
+      this.reconcileOwnership(operation, body.requests);
+      this.send(operation, operation.command, result => {
+        const wholeSessionRemoved = result.ok && (
+          (operation.command.type === 'session.delete.request' && result.deleted === true)
+          || (operation.command.type === 'session.messages.clear.request' && result.cleared === true));
+        if (wholeSessionRemoved) this.ownership?.retireSession(operation.runtime.runtimeId, operation.command.sessionId);
+        this.respond(operation, result);
+      });
     } catch (error) {
       this.error(operation, error.code ?? 'session_state_unavailable');
     }
   }
 
+  reconcileOwnership(operation, canonical) {
+    const runtimeId = operation.runtime.runtimeId;
+    const owners = this.ownership?.listSession(runtimeId, operation.command.sessionId) ?? [];
+    const open = owners.filter(owner => owner.status === 'open');
+    // Missing requests and partial histories are not evidence of completion.
+    for (const owner of open) {
+      if (!canonical.some(request => request.requestId === owner.requestId
+        && request.sessionId === owner.sessionId && ['completed', 'failed'].includes(request.status))) {
+        throw relayError('session_busy');
+      }
+    }
+    for (const owner of open) {
+      this.ownership.markTerminal(runtimeId, owner.requestId);
+      const view = this.requests.bindings.get(JSON.stringify([runtimeId, owner.requestId]));
+      if (view?.durable && view.sessionId === owner.sessionId) this.requests.markTerminal(view);
+    }
+  }
+
   send(operation, command, respond) {
     const entry = this.correlations.create(operation.client, operation.runtime, operation.id,
       command, expectedResponseType(command.type), {

package/src/relay/relay.mjs

@@ -3,19 +3,23 @@ import { normalizeClientCommand, expectedResponseType } from '../protocol/protoc
 import { createRelayClient, admitRelayCommand } from './relay-client-admission.mjs';
 import { RelayCorrelations } from './relay-correlations.mjs';
 import { RelayRequests } from './relay-requests.mjs';
+import { RelayApprovals } from './relay-approvals.mjs';
+import { isApprovalCommand } from '../protocol/approval-protocol.mjs';
+import { assertSparkChatSupported } from '../protocol/spark-chat-protocol.mjs';
 import { RelaySessionMutations, isSessionMutation } from './relay-session-mutations.mjs';
 import { isBoundedRuntimeFrame, isRelayId, parseRuntimeRegistration,
   validateRuntimeGrant, relayError } from './relay-runtime-registration.mjs';
 
 export class Relay {
-  constructor({ now = Date.now, send, close, observeRequest }) {
+  constructor({ now = Date.now, send, close, observeRequest, ownership, isClientAuthorized = () => true }) {
     this.now = now;
     this.send = send;
     this.close = close;
+    this.ownership = ownership;
     this.clients = new Map();
     this.runtimes = new Map();
     this.runtimePeers = new Map();
-    this.requests = new RelayRequests({ now, observe: observeRequest,
+    this.requests = new RelayRequests({ now, ownership, observe: observeRequest,
       event: (client, runtimeId, body) => this.deliver(client, { type: 'relay.event', runtimeId, body }),
       unknown: (client, record) => this.error(client.peer, undefined, record.runtime.runtimeId,
         'outcome_unknown', { requestId: record.requestId }),
@@ -25,8 +29,17 @@ export class Relay {
         runtimeId: entry.runtime.runtimeId, body }),
       unknown: entry => this.error(entry.client.peer, entry.id, entry.runtime.runtimeId, 'outcome_unknown'),
     });
+    this.approvals = new RelayApprovals({ ownership, requests: this.requests, correlations: this.correlations,
+      transmit: (peer, body) => this.transmit(peer, body),
+      connected: client => this.clients.get(client.peer) === client && isClientAuthorized(client),
+      currentRuntime: runtime => this.runtimes.get(runtime.runtimeId) === runtime && runtime.registered,
+      assertSessionAvailable: (runtime, sessionId) => this.sessionMutations.assertNoPending(runtime, sessionId),
+      respond: (client, runtime, id, body) => this.deliver(client, { type: 'relay.response', id,
+        runtimeId: runtime.runtimeId, body }),
+      error: (client, runtime, id, code) => this.error(client.peer, id, runtime.runtimeId, code),
+    });
     this.sessionMutations = new RelaySessionMutations({ now, correlations: this.correlations,
-      requests: this.requests, transmit: (peer, body) => this.transmit(peer, body),
+      requests: this.requests, ownership, transmit: (peer, body) => this.transmit(peer, body),
       connected: client => this.clients.get(client.peer) === client,
       error: (operation, code) => this.error(operation.client.peer, operation.id, operation.runtime.runtimeId, code),
       respond: (operation, body) => this.deliver(operation.client, { type: 'relay.response',
@@ -136,11 +149,16 @@ export class Relay {
   }
 
   dispatch(client, runtime, id, command) {
-    if (isSessionMutation(command.type)) return this.sessionMutations.dispatch(client, runtime, id, command);
-    if (['run_request', 'attachment.upload.request'].includes(command.type)) {
+    assertSparkChatSupported(command, runtime);
+    if (isSessionMutation(command.type)) {
+      this.approvals.adoption.assertNoPendingSession(runtime, command.sessionId);
+      return this.sessionMutations.dispatch(client, runtime, id, command);
+    }
+    if (['run_request', 'attachment.upload.request'].includes(command.type) || isApprovalCommand(command.type)) {
       this.sessionMutations.assertNoPending(runtime, command.sessionId);
     }
     if (command.type === 'run_request') return this.dispatchRun(client, runtime, id, command);
+    if (isApprovalCommand(command.type)) return this.approvals.dispatch(client, runtime, id, command);
     if (command.type === 'subscribe_request') {
       this.requests.subscribe(client, runtime, command.requestId);
       return this.acknowledge(client, runtime, id, { requestId: command.requestId, status: 'subscribed' });
@@ -155,6 +173,7 @@ export class Relay {
   }
 
   dispatchRun(client, runtime, id, command) {
+    this.approvals.adoption.assertNoPendingRequest(runtime, command.requestId);
     const record = this.requests.create(client, runtime, command);
     if (!this.transmit(runtime.peer, command)) {
       this.requests.markUnknown(record, false);
@@ -198,5 +217,6 @@ export class Relay {
     }
     this.correlations.prune();
     this.requests.prune();
+    this.ownership?.prune();
   }
 }

package/src/relay/request-ownership-schema.mjs

@@ -0,0 +1,18 @@
+/** Routing identity only. Approval authority and execution state belong to the runtime. */
+export const REQUEST_OWNERSHIP_SCHEMA = `
+  CREATE TABLE request_ownership (
+    runtime_id TEXT NOT NULL CHECK(length(runtime_id) BETWEEN 1 AND 128),
+    request_id TEXT NOT NULL CHECK(length(request_id) BETWEEN 1 AND 128),
+    session_id TEXT NOT NULL CHECK(length(session_id) BETWEEN 1 AND 128),
+    subject TEXT NOT NULL CHECK(length(subject) BETWEEN 1 AND 320),
+    device_id TEXT NOT NULL CHECK(length(device_id) BETWEEN 1 AND 256),
+    status TEXT NOT NULL CHECK(status IN ('open', 'terminal')),
+    created_at INTEGER NOT NULL CHECK(created_at >= 0),
+    terminal_at INTEGER,
+    PRIMARY KEY(runtime_id, request_id),
+    CHECK((status = 'open' AND terminal_at IS NULL)
+      OR (status = 'terminal' AND terminal_at IS NOT NULL AND terminal_at >= 0))
+  ) STRICT;
+  CREATE INDEX request_ownership_session ON request_ownership(runtime_id, session_id);
+  CREATE INDEX request_ownership_terminal ON request_ownership(terminal_at) WHERE status = 'terminal';
+`;

package/src/relay/request-ownership-store.mjs

@@ -0,0 +1,115 @@
+import { isRelayId, relayError } from './relay-runtime-registration.mjs';
+
+const MAX_OWNERSHIP_RECORDS = 512;
+const TERMINAL_RETENTION_MS = 12 * 60 * 60 * 1000;
+const SELECT_RECORD = `SELECT runtime_id AS runtimeId, session_id AS sessionId,
+  request_id AS requestId, subject, device_id AS deviceId, status,
+  created_at AS createdAt, terminal_at AS terminalAt FROM request_ownership`;
+
+function assertRequestIdentity(runtimeId, requestId) {
+  if (!isRelayId(runtimeId)) throw relayError('invalid_request_identity');
+  if (!isRelayId(requestId)) throw relayError('invalid_request_identity');
+}
+
+function assertOwnershipIdentity(identity, ownerId) {
+  if (!identity || typeof identity !== 'object') throw relayError('invalid_request_identity');
+  assertRequestIdentity(identity.runtimeId, identity.requestId);
+  if (!isRelayId(identity.sessionId)) throw relayError('invalid_request_identity');
+  if (identity.subject !== ownerId) throw relayError('invalid_request_identity');
+  if (typeof identity.deviceId !== 'string') throw relayError('invalid_request_identity');
+  if (!identity.deviceId.trim() || identity.deviceId.length > 256) throw relayError('invalid_request_identity');
+}
+
+/** Durable owner binding, never an approval cache or a queue for replaying runs. */
+export class RequestOwnershipStore {
+  constructor({ database, now = Date.now }) {
+    if (typeof database?.prepare !== 'function' || typeof database?.transaction !== 'function') {
+      throw new TypeError('An authentication database is required');
+    }
+    if (typeof now !== 'function') throw new TypeError('An ownership clock is required');
+    this.database = database;
+    this.now = now;
+  }
+
+  create(identity) {
+    assertOwnershipIdentity(identity, this.database.ownerId);
+    const time = this.#time();
+    return this.database.transaction(() => {
+      if (this.get(identity.runtimeId, identity.requestId)) throw relayError('request_id_conflict');
+      return this.#insert(identity, time, false);
+    });
+  }
+
+  isOwnerSubject(subject) {
+    return subject === this.database.ownerId;
+  }
+
+  /** The relay must first verify the exact canonical request on the authorized runtime. */
+  adopt(identity, terminal = false) {
+    assertOwnershipIdentity(identity, this.database.ownerId);
+    if (typeof terminal !== 'boolean') throw relayError('invalid_request_identity');
+    const time = this.#time();
+    return this.database.transaction(() => {
+      const existing = this.get(identity.runtimeId, identity.requestId);
+      if (!existing) return this.#insert(identity, time, terminal);
+      if (existing.subject !== identity.subject) throw relayError('request_not_owned');
+      if (existing.sessionId !== identity.sessionId) throw relayError('request_not_owned');
+      return existing;
+    });
+  }
+
+  get(runtimeId, requestId) {
+    assertRequestIdentity(runtimeId, requestId);
+    const record = this.database.prepare(`${SELECT_RECORD} WHERE runtime_id = ? AND request_id = ?`)
+      .get(runtimeId, requestId);
+    return record ? { ...record } : null;
+  }
+
+  listSession(runtimeId, sessionId) {
+    if (!isRelayId(runtimeId) || !isRelayId(sessionId)) throw relayError('invalid_request_identity');
+    return this.database.prepare(`${SELECT_RECORD} WHERE runtime_id = ? AND session_id = ?
+      ORDER BY created_at, request_id LIMIT ?`)
+      .all(runtimeId, sessionId, MAX_OWNERSHIP_RECORDS).map(record => ({ ...record }));
+  }
+
+  markTerminal(runtimeId, requestId) {
+    assertRequestIdentity(runtimeId, requestId);
+    return this.database.prepare(`UPDATE request_ownership SET status = 'terminal', terminal_at = ?
+      WHERE runtime_id = ? AND request_id = ? AND status = 'open'`)
+      .run(this.#time(), runtimeId, requestId).changes > 0;
+  }
+
+  /** The caller must have confirmed deletion of the complete canonical session. */
+  retireSession(runtimeId, sessionId) {
+    if (!isRelayId(runtimeId) || !isRelayId(sessionId)) throw relayError('invalid_request_identity');
+    return this.database.prepare('DELETE FROM request_ownership WHERE runtime_id = ? AND session_id = ?')
+      .run(runtimeId, sessionId).changes;
+  }
+
+  prune() {
+    return this.#deleteExpired(this.#time());
+  }
+
+  #insert(identity, time, terminal) {
+    this.#deleteExpired(time);
+    const count = this.database.prepare('SELECT count(*) AS count FROM request_ownership').get().count;
+    if (count >= MAX_OWNERSHIP_RECORDS) throw relayError('request_capacity');
+    this.database.prepare(`INSERT INTO request_ownership
+      (runtime_id, request_id, session_id, subject, device_id, status, created_at, terminal_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(identity.runtimeId, identity.requestId, identity.sessionId, identity.subject, identity.deviceId,
+        terminal ? 'terminal' : 'open', time, terminal ? time : null);
+    return this.get(identity.runtimeId, identity.requestId);
+  }
+
+  #deleteExpired(time) {
+    return this.database.prepare("DELETE FROM request_ownership WHERE status = 'terminal' AND terminal_at <= ?")
+      .run(time - TERMINAL_RETENTION_MS).changes;
+  }
+
+  #time() {
+    const time = this.now();
+    if (!Number.isSafeInteger(time) || time < 0) throw new TypeError('Invalid ownership clock');
+    return time;
+  }
+}