@matuto-ai/opencode-broker-connector 0.0.0-stage → 0.1.0

package/vendor/broker/reference/client.mjs

@@ -0,0 +1,318 @@
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { readFileSync, openSync, fstatSync, closeSync, constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ApiError, canonical, validateMetadata, validateRegistration, validateMetadataPatch,
+  validateClaim, validateCompletion, validateRenew, validateUuid } from '../src/protocol.mjs';
+import { LocalError } from './errors.mjs';
+
+const ALLOWED_ERROR_CODES = new Set(['invalid_request', 'unauthenticated', 'forbidden', 'recipient_not_found',
+  'message_not_found', 'identity_conflict', 'stale_lease_epoch', 'idempotency_conflict', 'metadata_conflict',
+  'claim_conflict', 'session_closed', 'message_expired', 'payload_too_large',
+  'incompatible_receiver_transport', 'receiving_disabled', 'rate_limited', 'mailbox_full',
+  'storage_unavailable', 'not_ready']);
+
+export class BrokerError extends LocalError {
+  constructor(status, value, retryAfter = 0) {
+    super('invalid_response', { effect: 'unknown' });
+    this.name = 'BrokerError';
+    this.status = status;
+    this.retryAfter = retryAfter;
+    const raw = value?.error;
+    const code = ALLOWED_ERROR_CODES.has(raw?.code) ? raw.code : 'invalid_request';
+    // Never reproduce a remote free-text message or details in local tools/logs.
+    this.api = new ApiError(status, code, null, {
+      effect: ['not_applied', 'unknown'].includes(raw?.effect) ? raw.effect : 'unknown',
+      retryable: raw?.retryable === true && [429, 503].includes(status),
+    });
+    this.code = this.api.code;
+    this.message = this.api.message;
+    this.effect = this.api.effect;
+    this.retryable = this.api.retryable;
+  }
+  toJSON() { return this.api.toJSON(null); }
+}
+
+function readSecret(path) {
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.size > 8192
+      || (process.getuid && stat.uid !== process.getuid())) throw new Error('invalid');
+    const token = readFileSync(fd, 'utf8').trim();
+    if (!/^[A-Za-z0-9_-]{43,256}$/.test(token)) throw new Error('invalid');
+    return token;
+  } catch { throw new LocalError('invalid_configuration', { field: 'tokenFile' }); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function positiveSeconds(value, fallback) {
+  return Number.isSafeInteger(value) && value > 0 && value <= 365 * 86400 ? value : fallback;
+}
+
+/** HTTPS-only by default. No redirects; no credential-bearing URLs or command-line arguments. */
+export class BrokerClient {
+  constructor({ url, tokenFile, tokenEnvironment, caFile, insecureDevelopment = false, inbox,
+    now = Date.now, random = Math.random, sleep = delay, maxAttempts = 4,
+    maxResponseBytes = 256 * 1024, requestTimeoutMs = 40000 }) {
+    try { this.base = new URL(url); } catch { throw new LocalError('invalid_configuration', { field: 'url' }); }
+    const host = this.base.hostname.replace(/^\[|\]$/g, '');
+    if (this.base.username || this.base.password || this.base.search || this.base.hash || this.base.pathname !== '/'
+      || !['https:', 'http:'].includes(this.base.protocol)
+      || (this.base.protocol === 'http:' && (!insecureDevelopment || !['127.0.0.1', '::1'].includes(host)))) {
+      throw new LocalError('invalid_configuration', { field: 'url' });
+    }
+    if (!inbox || (!tokenFile && !tokenEnvironment) || (tokenFile && tokenEnvironment)
+      || !Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10
+      || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1024 || maxResponseBytes > 1048576
+      || !Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 100 || requestTimeoutMs > 120000) throw new LocalError('invalid_configuration');
+    this.inbox = inbox;
+    this.now = now;
+    this.random = random;
+    this.sleep = sleep;
+    this.maxAttempts = maxAttempts;
+    this.maxResponseBytes = maxResponseBytes;
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.tokenFile = tokenFile;
+    this.tokenEnvironment = tokenEnvironment;
+    try { this.ca = caFile ? readFileSync(caFile) : undefined; }
+    catch { throw new LocalError('invalid_configuration', { field: 'caFile' }); }
+    this.clockOffset = 0;
+    this.connectPromise = null;
+  }
+
+  get identity() { return this.inbox.identity; }
+  get attachment() { return this.inbox.getState('attachment') ?? {}; }
+  get policy() { return this.attachment.policy ?? {}; }
+  serverNow() { return this.now() + this.clockOffset; }
+
+  credential() {
+    if (this.tokenFile) return readSecret(this.tokenFile);
+    const token = process.env[this.tokenEnvironment];
+    if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{43,256}$/.test(token)) throw new LocalError('invalid_configuration', { field: 'tokenEnvironment' });
+    return token;
+  }
+
+  async request(method, path, { body, key, session = true, signal, idempotent = false, deadline = Infinity } = {}) {
+    if (!/^\/v1\/[A-Za-z0-9_/?=&.%+~-]+$/.test(path)) throw new LocalError('invalid_configuration');
+    for (let attempt = 0; ; attempt++) {
+      if (this.now() >= deadline) throw new LocalError('retry_window_elapsed', { effect: 'unknown' });
+      try { return await this.requestOnce(method, path, { body, key, session, signal, timeoutMs: Math.min(this.requestTimeoutMs, deadline - this.now()) }); }
+      catch (error) {
+        if (signal?.aborted) throw new LocalError('request_aborted', { effect: 'unknown' });
+        const retryable = error instanceof BrokerError ? error.retryable
+          : error instanceof LocalError && error.code === 'request_failed';
+        if (!idempotent || !retryable || attempt + 1 >= this.maxAttempts) throw error;
+        const milliseconds = Math.max(error.retryAfter * 1000 || 0, Math.min(10000, 250 * 2 ** attempt) * (0.8 + this.random() * 0.4));
+        if (this.now() + milliseconds >= deadline) throw new LocalError('retry_window_elapsed', { effect: 'unknown' });
+        try { await this.sleep(milliseconds, undefined, { signal }); }
+        catch { throw new LocalError('request_aborted', { effect: 'unknown' }); }
+      }
+    }
+  }
+
+  requestOnce(method, path, { body, key, session, signal, timeoutMs }) {
+    const serialized = body === undefined ? null : canonical(body);
+    if (serialized && Buffer.byteLength(serialized) > 98304) throw new LocalError('invalid_configuration', { field: 'body' });
+    const headers = { Accept: 'application/json', Authorization: `Bearer ${this.credential()}` };
+    if (session) {
+      if (!Number.isSafeInteger(this.attachment.lease_epoch) || this.attachment.lease_epoch < 1) throw new LocalError('session_mismatch');
+      headers['X-Client-ID'] = this.identity.client_id;
+      headers['X-Lease-Epoch'] = String(this.attachment.lease_epoch);
+    }
+    if (key) headers['Idempotency-Key'] = key;
+    if (serialized !== null) { headers['Content-Type'] = 'application/json'; headers['Content-Length'] = Buffer.byteLength(serialized); }
+    const target = new URL(path, this.base);
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let absoluteTimer;
+      const finish = (error, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(absoluteTimer);
+        if (error) reject(error); else resolve(value);
+      };
+      const transport = target.protocol === 'https:' ? httpsRequest : httpRequest;
+      const request = transport(target, { method, headers, signal, ca: this.ca,
+        rejectUnauthorized: true, timeout: timeoutMs, maxHeaderSize: 16384 }, response => {
+        const chunks = [];
+        let bytes = 0;
+        response.on('data', chunk => {
+          bytes += chunk.length;
+          if (bytes > this.maxResponseBytes) { finish(new LocalError('invalid_response', { effect: 'unknown' })); response.destroy(); }
+          else chunks.push(chunk);
+        });
+        response.on('error', () => finish(new LocalError('request_failed', { effect: 'unknown', retryable: true })));
+        response.on('end', () => {
+          try {
+            const status = response.statusCode;
+            if (status === 204) { finish(null, null); return; }
+            if (!String(response.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) throw new LocalError('invalid_response', { effect: 'unknown' });
+            const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+            if (status < 200 || status >= 300) {
+              const retryAfter = /^\d+$/.test(String(response.headers['retry-after'] ?? '')) ? Math.min(3600, Number(response.headers['retry-after'])) : 0;
+              finish(new BrokerError(status, value, retryAfter)); return;
+            }
+            const timestamp = value?.server_time;
+            // Registration/send/completion retries may return their original
+            // stored result. Historical server_time is not a current clock sample.
+            if ((method === 'GET' || path.endsWith('/heartbeat') || method === 'PATCH')
+              && typeof timestamp === 'string' && Number.isFinite(Date.parse(timestamp))) this.clockOffset = Date.parse(timestamp) - this.now();
+            finish(null, value);
+          } catch (error) { finish(error instanceof LocalError ? error : new LocalError('invalid_response', { effect: 'unknown' })); }
+        });
+      });
+      request.on('timeout', () => request.destroy());
+      request.on('error', () => finish(new LocalError(signal?.aborted ? 'request_aborted' : 'request_failed', { effect: 'unknown', retryable: !signal?.aborted })));
+      absoluteTimer = setTimeout(() => request.destroy(), timeoutMs);
+      request.end(serialized);
+    });
+  }
+
+  capabilities(receiveEnabled = true) {
+    return { protocol_version: '1', adapter_version: '0.1.0', client_type: this.identity.client_type,
+      receive_enabled: receiveEnabled, durable_inbox: true };
+  }
+
+  applyRegistration(result, pending) {
+    if (!result || result.client_id !== this.identity.client_id || !Number.isSafeInteger(result.lease_epoch)
+      || result.lease_epoch !== pending.body.previous_epoch + 1 || !Number.isSafeInteger(result.metadata_revision)
+      || result.metadata_revision < 1 || !result.policy) throw new LocalError('invalid_response', { effect: 'unknown' });
+    this.inbox.setState('attachment', { ...this.attachment, ...result, connection_id: pending.body.connection_id });
+    this.inbox.setState('metadata', pending.body.metadata);
+    this.inbox.setState('registration_pending', null);
+    this.inbox.setState('claim_pending', null);
+    return result;
+  }
+
+  async register(metadata, { receiveEnabled = true, signal } = {}) {
+    let pending = this.inbox.getState('registration_pending');
+    if (!pending) {
+      const body = validateRegistration({ protocol_version: '1', ...this.identity, connection_id: randomUUID(),
+        previous_epoch: this.attachment.lease_epoch ?? 0, metadata: validateMetadata(metadata), capabilities: this.capabilities(receiveEnabled) });
+      pending = { body, retry_until: this.now() + positiveSeconds(this.policy.registration_retry_seconds, 86400) * 1000 };
+      this.inbox.setState('registration_pending', pending);
+    }
+    const result = await this.request('POST', '/v1/sessions', { body: pending.body, session: false,
+      idempotent: true, deadline: pending.retry_until, signal });
+    const state = await this.request('GET', `/v1/sessions/${this.identity.client_id}`, { session: false, idempotent: true, signal });
+    if (state?.client_id !== this.identity.client_id || state.session_instance_id !== this.identity.session_instance_id
+      || state.client_type !== this.identity.client_type || state.connection_id !== pending.body.connection_id
+      || state.lease_epoch !== result?.lease_epoch) throw new LocalError('session_mismatch', { effect: 'unknown' });
+    const confirmed = this.applyRegistration({ ...result, server_time: state.server_time, lease_expires_at: state.lease_expires_at }, pending);
+    if (state.closed === true) throw new BrokerError(410, { error: { code: 'session_closed', effect: 'unknown' } });
+    if (state.connected !== true || Date.parse(state.lease_expires_at) <= this.serverNow()) {
+      throw new BrokerError(409, { error: { code: 'stale_lease_epoch', effect: 'unknown' } });
+    }
+    return confirmed;
+  }
+
+  async reconnect({ verifySession, signal, metadata, receiveEnabled } = {}) {
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = this.reconnectOnce({ verifySession, signal, metadata, receiveEnabled });
+    try { return await this.connectPromise; } finally { this.connectPromise = null; }
+  }
+
+  async reconnectOnce({ verifySession, signal, metadata, receiveEnabled }) {
+    if (typeof verifySession !== 'function' || await verifySession(this.identity) !== true) throw new LocalError('session_mismatch');
+    const local = this.attachment;
+    const pending = this.inbox.getState('registration_pending');
+    const state = await this.request('GET', `/v1/sessions/${this.identity.client_id}`, { session: false, idempotent: true, signal });
+    if (state.client_id !== this.identity.client_id || state.session_instance_id !== this.identity.session_instance_id
+      || state.client_type !== this.identity.client_type || !Number.isSafeInteger(state.lease_epoch)
+      || ![local.connection_id, pending?.body.connection_id].filter(Boolean).includes(state.connection_id)) throw new LocalError('session_mismatch');
+    if (state.closed === true || state.closed_at != null) throw new BrokerError(410, { error: { code: 'session_closed', effect: 'not_applied' } });
+    // The owned-state read is a reconciliation, not permission to steal a different attachment.
+    this.inbox.setState('attachment', { ...local, lease_epoch: state.lease_epoch, connection_id: state.connection_id,
+      metadata_revision: state.metadata_revision, policy: state.policy ?? local.policy });
+    this.inbox.setState('registration_pending', null);
+    const refreshedMetadata = metadata ?? pending?.body.metadata ?? state.metadata ?? this.inbox.getState('metadata');
+    return this.register(refreshedMetadata, { receiveEnabled: receiveEnabled ?? pending?.body.capabilities.receive_enabled ?? state.capabilities?.receive_enabled ?? false, signal });
+  }
+
+  async heartbeat({ signal } = {}) {
+    return this.request('POST', `/v1/sessions/${this.identity.client_id}/heartbeat`, { body: {}, idempotent: true, signal });
+  }
+
+  async closeSession({ signal } = {}) {
+    return this.request('POST', `/v1/sessions/${this.identity.client_id}/close`, { body: {}, idempotent: true, signal });
+  }
+
+  async listClients(filters = {}, { signal } = {}) {
+    const allowed = ['connected', 'client_type', 'name', 'project', 'limit', 'cursor'];
+    if (Object.keys(filters).some(key => !allowed.includes(key))) throw new LocalError('invalid_configuration');
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(filters)) query.set(key, String(value));
+    return this.request('GET', `/v1/clients${query.size ? `?${query}` : ''}`, { idempotent: true, signal });
+  }
+
+  async updateMetadata(patch, { expectedRevision = this.attachment.metadata_revision, signal } = {}) {
+    const body = validateMetadataPatch({ metadata_patch: patch, expected_metadata_revision: expectedRevision });
+    // CAS is not blindly retried after response loss: read owned state to reconcile first.
+    const result = await this.request('PATCH', `/v1/sessions/${this.identity.client_id}/metadata`, { body, signal });
+    if (!Number.isSafeInteger(result?.metadata_revision)) throw new LocalError('invalid_response', { effect: 'unknown' });
+    this.inbox.setState('attachment', { ...this.attachment, metadata_revision: result.metadata_revision });
+    this.inbox.setState('metadata', { ...this.inbox.getState('metadata'), ...patch });
+    return result;
+  }
+
+  async refreshOwnedMetadata({ signal } = {}) {
+    const state = await this.request('GET', `/v1/sessions/${this.identity.client_id}`, { session: false, idempotent: true, signal });
+    if (state.client_id !== this.identity.client_id || state.session_instance_id !== this.identity.session_instance_id
+      || state.connection_id !== this.attachment.connection_id || state.lease_epoch !== this.attachment.lease_epoch
+      || !Number.isSafeInteger(state.metadata_revision)) throw new LocalError('session_mismatch');
+    const metadata = validateMetadata(state.metadata);
+    this.inbox.setState('attachment', { ...this.attachment, metadata_revision: state.metadata_revision });
+    this.inbox.setState('metadata', metadata);
+    return metadata;
+  }
+
+  prepareSend(request, options = {}) {
+    return this.inbox.prepareSend(request, { retryWindowSeconds: positiveSeconds(this.policy.send_retry_seconds, 86400), ...options });
+  }
+
+  async sendPrepared(key, { signal } = {}) {
+    const operation = this.inbox.outgoing(key);
+    if (!operation) throw new LocalError('invalid_configuration');
+    if (operation.result) return { ...operation.result, send_key: key };
+    const result = await this.request('POST', '/v1/messages', { body: operation.request, key, idempotent: true,
+      deadline: operation.retry_until, signal });
+    try { validateUuid(result?.message_id); } catch { throw new LocalError('invalid_response', { effect: 'unknown' }); }
+    this.inbox.recordSendResult(key, result);
+    if (operation.request.metadata_patch) {
+      this.inbox.setState('metadata', { ...this.inbox.getState('metadata'), ...operation.request.metadata_patch });
+      // Sender revision is not guessed; reconcile from owned state before a future CAS mutation.
+    }
+    return { ...result, send_key: key };
+  }
+
+  async messageStatus(messageId, { signal } = {}) {
+    return this.request('GET', `/v1/messages/${validateUuid(messageId)}`, { idempotent: true, signal });
+  }
+
+  async claim(waitSeconds = 30, { signal } = {}) {
+    let pending = this.inbox.getState('claim_pending');
+    if (!pending) {
+      pending = { key: randomUUID(), body: validateClaim({ wait_seconds: waitSeconds }), lease_epoch: this.attachment.lease_epoch };
+      this.inbox.setState('claim_pending', pending);
+    }
+    if (pending.lease_epoch !== this.attachment.lease_epoch) throw new LocalError('session_mismatch');
+    const result = await this.request('POST', '/v1/mailbox/claim', { body: pending.body, key: pending.key, idempotent: true, signal });
+    if (result === null) this.inbox.setState('claim_pending', null);
+    return result;
+  }
+
+  async complete(messageId, completion, { signal } = {}) {
+    const result = await this.request('POST', `/v1/mailbox/${validateUuid(messageId)}/complete`, {
+      body: validateCompletion(completion), idempotent: true, signal });
+    this.inbox.setState('claim_pending', null);
+    return result;
+  }
+
+  async renew(messageId, claimId, { signal } = {}) {
+    return this.request('POST', `/v1/mailbox/${validateUuid(messageId)}/renew`, {
+      body: validateRenew({ claim_id: claimId }), idempotent: true, signal });
+  }
+}

package/vendor/broker/reference/errors.mjs

@@ -0,0 +1,42 @@
+/** Local errors deliberately never include content, paths, credentials or native responses. */
+const MESSAGES = {
+  invalid_configuration: 'Correct the local adapter configuration before retrying.',
+  session_mismatch: 'Verify the exact surviving harness session; do not adopt its mailbox.',
+  owner_conflict: 'Another worker owns this session inbox. Stop it before starting another.',
+  storage_unavailable: 'Restore local durable storage before retrying.',
+  inbox_full: 'The local inbox or deduplication budget is full; preserve pending input.',
+  envelope_mismatch: 'A message ID changed its immutable envelope. Pause and inspect the protocol.',
+  envelope_expired: 'The transport deadline passed; do not accept a new inbox item.',
+  invalid_envelope: 'The broker envelope is invalid; no inbox item was accepted.',
+  invalid_response: 'The broker response is invalid. Reconcile the original operation.',
+  request_failed: 'The network result is unknown. Retry only the original idempotent operation.',
+  request_aborted: 'The request was canceled. Reconcile any potentially applied operation.',
+  retry_window_elapsed: 'The automatic retry window ended. Reconcile; do not allocate a replacement key.',
+  send_conflict: 'The local send key already names a different request.',
+  injection_uncertain: 'Native acceptance is uncertain. The local FIFO head is paused for operator review.',
+  unsafe_boundary: 'Keep the input pending until the harness provides a verified safe boundary.',
+  receipt_required: 'A supported native acceptance receipt is required before consumption is recorded.',
+  unknown_tool: 'Use a documented broker tool name.',
+};
+
+export class LocalError extends Error {
+  constructor(code, { effect = 'not_applied', retryable = false, field = null } = {}) {
+    super(MESSAGES[code] ?? MESSAGES.invalid_configuration);
+    this.name = 'LocalError';
+    this.code = code;
+    this.effect = effect;
+    this.retryable = retryable;
+    this.field = field;
+  }
+  toJSON() {
+    return { error: { code: this.code, message: this.message, action: this.message,
+      retryable: this.retryable, effect: this.effect, field: this.field,
+      contract_ref: 'docs/reference.md#local-errors' } };
+  }
+}
+
+export function safeError(error) {
+  if (error instanceof LocalError) return error.toJSON();
+  if (error?.toJSON && error?.name === 'BrokerError') return error.toJSON();
+  return new LocalError('storage_unavailable', { effect: 'unknown' }).toJSON();
+}

package/vendor/broker/reference/inbox.mjs

@@ -0,0 +1,289 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, lstatSync, statfsSync, readdirSync, chmodSync, realpathSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { canonical, digest, validateEnvelope, validateUuid, validateSend, validateIdempotencyKey, TYPES } from '../src/protocol.mjs';
+import { LocalError } from './errors.mjs';
+
+export function newSessionIdentity(clientType) {
+  if (!TYPES.includes(clientType)) throw new LocalError('invalid_configuration');
+  return { client_id: randomUUID(), session_instance_id: randomUUID(), client_type: clientType };
+}
+
+function identityValue(identity) {
+  if (!identity || Object.keys(identity).sort().join(',') !== 'client_id,client_type,session_instance_id'
+    || !TYPES.includes(identity.client_type)) throw new LocalError('invalid_configuration');
+  return { client_id: validateUuid(identity.client_id), session_instance_id: validateUuid(identity.session_instance_id), client_type: identity.client_type };
+}
+
+/** One session-bound durable journal. A separate SQLite OS lock survives no process crash. */
+export class Inbox {
+  constructor({ directory, identity, now = Date.now, maxPendingCount = 1000,
+    maxPendingBytes = 64 * 1024 * 1024, maxLedgerCount = 50000,
+    maxOutgoingCount = 10000, maxDatabaseBytes = 128 * 1024 * 1024,
+    minFreeBytes = 16 * 1024 * 1024, retentionSeconds = 8 * 86400,
+    diskCheck, failurePoint = () => {} }) {
+    this.identity = identityValue(identity);
+    this.now = now;
+    this.failurePoint = failurePoint;
+    this.retentionSeconds = retentionSeconds;
+    this.limits = { maxPendingCount, maxPendingBytes, maxLedgerCount, maxOutgoingCount, maxDatabaseBytes, minFreeBytes };
+    for (const [key, value] of Object.entries({ ...this.limits, retentionSeconds })) {
+      if (!Number.isSafeInteger(value) || value < (key === 'minFreeBytes' ? 0 : 1)) throw new LocalError('invalid_configuration');
+    }
+    if (retentionSeconds < 7 * 86400) throw new LocalError('invalid_configuration');
+    this.directory = resolve(directory);
+    this.diskCheck = diskCheck;
+    this.closed = false;
+    this.storageUncertain = false;
+    try {
+      mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+      const dir = lstatSync(this.directory);
+      if (!dir.isDirectory() || dir.isSymbolicLink() || realpathSync(this.directory) !== this.directory || (dir.mode & 0o077) !== 0
+        || (process.getuid && dir.uid !== process.getuid())) throw new LocalError('invalid_configuration');
+      for (const name of ['inbox.sqlite', 'owner.sqlite']) {
+        const path = join(this.directory, name);
+        try {
+          const file = lstatSync(path);
+          if (!file.isFile() || file.isSymbolicLink() || (file.mode & 0o077) !== 0) throw new LocalError('invalid_configuration');
+        } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      }
+      this.checkDisk();
+      this.owner = new DatabaseSync(join(this.directory, 'owner.sqlite'));
+      chmodSync(join(this.directory, 'owner.sqlite'), 0o600);
+      try { this.owner.exec('PRAGMA busy_timeout=0; PRAGMA journal_mode=DELETE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner(singleton INTEGER PRIMARY KEY CHECK(singleton=1));'); }
+      catch { throw new LocalError('owner_conflict'); }
+      this.db = new DatabaseSync(join(this.directory, 'inbox.sqlite'));
+      chmodSync(join(this.directory, 'inbox.sqlite'), 0o600);
+      if (this.db.prepare('PRAGMA user_version').get().user_version > 1) throw new LocalError('invalid_configuration');
+      this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON;
+        PRAGMA busy_timeout=0; PRAGMA wal_autocheckpoint=100;
+        CREATE TABLE IF NOT EXISTS state(key TEXT PRIMARY KEY, value TEXT NOT NULL);
+        CREATE TABLE IF NOT EXISTS inbox(
+          message_id TEXT PRIMARY KEY, sequence INTEGER NOT NULL UNIQUE, digest TEXT NOT NULL,
+          envelope TEXT NOT NULL, bytes INTEGER NOT NULL, state TEXT NOT NULL,
+          received_at INTEGER NOT NULL, retain_until INTEGER NOT NULL,
+          injection_id TEXT, native_receipt TEXT, consumed_at INTEGER);
+        CREATE TABLE IF NOT EXISTS outgoing(
+          key TEXT PRIMARY KEY, digest TEXT NOT NULL, request TEXT NOT NULL,
+          created_at INTEGER NOT NULL, retry_until INTEGER NOT NULL, result TEXT);
+        PRAGMA user_version=1;`);
+      const stored = this.getState('identity');
+      if (stored && canonical(stored) !== canonical(this.identity)) throw new LocalError('session_mismatch');
+      if (!stored) this.setState('identity', this.identity);
+      this.db.prepare("UPDATE inbox SET state='uncertain' WHERE state='injecting'").run();
+    } catch (error) {
+      this.db?.close();
+      this.owner?.close();
+      if (error instanceof LocalError) throw error;
+      throw new LocalError('storage_unavailable');
+    }
+  }
+
+  checkDisk(extra = 0) {
+    this.assertUsable();
+    if (this.closed) throw new LocalError('storage_unavailable');
+    try {
+      if (this.diskCheck && !this.diskCheck(extra)) throw new Error('disk');
+      const disk = statfsSync(this.directory);
+      if ([0x6969, 0x517b, 0xff534d42].includes(Number(disk.type))) throw new Error('unsupported filesystem');
+      const bytes = readdirSync(this.directory).reduce((total, name) => {
+        const stat = lstatSync(join(this.directory, name));
+        return total + (stat.isFile() ? stat.size : 0);
+      }, 0);
+      if (Number(disk.bavail) * Number(disk.bsize) < this.limits.minFreeBytes + extra
+        || bytes + extra > this.limits.maxDatabaseBytes) throw new Error('disk');
+    } catch { throw new LocalError('storage_unavailable', { retryable: true }); }
+  }
+
+  transaction(callback, { growth = 0 } = {}) {
+    this.checkDisk(growth);
+    let commitAttempted = false;
+    let committed = false;
+    try {
+      this.db.exec('BEGIN IMMEDIATE');
+      const result = callback();
+      this.failurePoint('before_commit');
+      commitAttempted = true;
+      this.db.exec('COMMIT');
+      committed = true;
+      this.failurePoint('after_commit');
+      return result;
+    } catch (error) {
+      let rollbackConfirmed = false;
+      try { this.failurePoint('before_rollback'); this.db.exec('ROLLBACK'); rollbackConfirmed = true; } catch { /* The effect may be unknown. */ }
+      const effect = committed || (commitAttempted && !rollbackConfirmed) || !rollbackConfirmed ? 'unknown' : 'not_applied';
+      // A failed rollback can leave uncommitted rows visible on this connection.
+      // Do not allow a later duplicate lookup to ACK those rows. Reopen first.
+      if (!committed && !rollbackConfirmed) this.storageUncertain = true;
+      if (error instanceof LocalError && effect === 'not_applied') throw error;
+      throw new LocalError('storage_unavailable', { retryable: true, effect });
+    }
+  }
+
+  assertUsable() {
+    if (this.closed || this.storageUncertain) throw new LocalError('storage_unavailable', { effect: this.storageUncertain ? 'unknown' : 'not_applied', retryable: true });
+  }
+
+  getState(key) {
+    this.assertUsable();
+    const row = this.db.prepare('SELECT value FROM state WHERE key=?').get(key);
+    return row ? JSON.parse(row.value) : null;
+  }
+
+  setState(key, value) {
+    if (!['identity', 'attachment', 'registration_pending', 'claim_pending', 'metadata'].includes(key)) throw new LocalError('invalid_configuration');
+    const encoded = canonical(value);
+    if (Buffer.byteLength(encoded) > 256 * 1024) throw new LocalError('invalid_configuration');
+    return this.transaction(() => this.db.prepare('INSERT INTO state(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run(key, encoded), { growth: Buffer.byteLength(encoded) + 4096 });
+  }
+
+  accept(rawEnvelope, { serverNow = this.now(), retentionSeconds = this.retentionSeconds, retryWindowSeconds = 86400 } = {}) {
+    this.assertUsable();
+    let envelope;
+    try { envelope = validateEnvelope(rawEnvelope); }
+    catch { throw new LocalError('invalid_envelope'); }
+    if (envelope.recipient_id !== this.identity.client_id) throw new LocalError('session_mismatch');
+    const encoded = canonical(envelope);
+    const hash = digest(envelope);
+    const bytes = Buffer.byteLength(encoded);
+    if (!Number.isSafeInteger(retentionSeconds) || retentionSeconds < 7 * 86400
+      || !Number.isSafeInteger(retryWindowSeconds) || retryWindowSeconds < 1) throw new LocalError('invalid_configuration');
+    const existing = this.db.prepare('SELECT digest FROM inbox WHERE message_id=?').get(envelope.message_id);
+    if (existing) {
+      if (existing.digest !== hash) throw new LocalError('envelope_mismatch');
+      // A late redelivery restarts the local retention guarantee. If extending it
+      // fails, withhold ACK: saying not_stored would contradict this known row.
+      try {
+        this.transaction(() => this.db.prepare('UPDATE inbox SET retain_until=MAX(retain_until,?) WHERE message_id=?')
+          .run(this.now() + Math.max(retentionSeconds, this.retentionSeconds) * 1000, envelope.message_id));
+      } catch { throw new LocalError('storage_unavailable', { effect: 'unknown', retryable: true }); }
+      return { stored: true, duplicate: true, message_id: envelope.message_id };
+    }
+    if (Date.parse(envelope.expires_at) <= serverNow) throw new LocalError('envelope_expired');
+    return this.transaction(() => {
+      const usage = this.stats();
+      if (usage.pending_count >= this.limits.maxPendingCount || usage.pending_bytes + bytes > this.limits.maxPendingBytes
+        || usage.ledger_count >= this.limits.maxLedgerCount) throw new LocalError('inbox_full', { retryable: true });
+      const highest = this.db.prepare('SELECT MAX(sequence) AS sequence FROM inbox').get().sequence ?? 0;
+      const lastSequence = this.getState('attachment')?.highest_received_sequence ?? 0;
+      if (envelope.recipient_sequence <= Math.max(highest, lastSequence)) throw new LocalError('envelope_mismatch');
+      const retainUntil = Math.max(this.now() + Math.max(retentionSeconds, this.retentionSeconds) * 1000,
+        this.now() + Math.max(0, Date.parse(envelope.expires_at) - serverNow) + retryWindowSeconds * 1000);
+      this.db.prepare(`INSERT INTO inbox(message_id,sequence,digest,envelope,bytes,state,received_at,retain_until)
+        VALUES(?,?,?,?,?,'pending',?,?)`).run(envelope.message_id, envelope.recipient_sequence, hash, encoded, bytes, this.now(), retainUntil);
+      const attachment = { ...(this.getState('attachment') ?? {}), highest_received_sequence: envelope.recipient_sequence };
+      this.db.prepare('INSERT INTO state(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value').run('attachment', canonical(attachment));
+      this.failurePoint('after_inbox_insert');
+      return { stored: true, duplicate: false, message_id: envelope.message_id };
+    }, { growth: bytes * 3 + 16384 });
+  }
+
+  stats() {
+    this.assertUsable();
+    const row = this.db.prepare("SELECT COUNT(*) AS ledger_count, COALESCE(SUM(CASE WHEN state!='consumed' THEN 1 ELSE 0 END),0) AS pending_count, COALESCE(SUM(CASE WHEN state!='consumed' THEN bytes ELSE 0 END),0) AS pending_bytes FROM inbox").get();
+    return { ...row };
+  }
+
+  head() {
+    this.assertUsable();
+    const row = this.db.prepare("SELECT * FROM inbox WHERE state!='consumed' ORDER BY sequence LIMIT 1").get();
+    return row ? { message_id: row.message_id, sequence: row.sequence, state: row.state,
+      envelope: JSON.parse(row.envelope), injection_id: row.injection_id } : null;
+  }
+
+  beginInjection(messageId) {
+    return this.transaction(() => {
+      const head = this.head();
+      if (!head || head.message_id !== messageId) throw new LocalError('unsafe_boundary');
+      if (head.state !== 'pending') throw new LocalError('injection_uncertain');
+      const injectionId = randomUUID();
+      this.db.prepare("UPDATE inbox SET state='injecting', injection_id=? WHERE message_id=?").run(injectionId, messageId);
+      return injectionId;
+    });
+  }
+
+  recordNativeAcceptance(messageId, injectionId, receipt) {
+    if (!receipt || receipt.accepted !== true || typeof receipt.receipt_id !== 'string'
+      || receipt.receipt_id.length < 1 || receipt.receipt_id.length > 256
+      || /[\x00-\x1f\x7f]/.test(receipt.receipt_id)) throw new LocalError('receipt_required', { effect: 'unknown' });
+    return this.transaction(() => {
+      const row = this.db.prepare('SELECT state,injection_id FROM inbox WHERE message_id=?').get(messageId);
+      if (!row || !['injecting', 'uncertain'].includes(row.state) || row.injection_id !== injectionId) throw new LocalError('injection_uncertain');
+      this.db.prepare("UPDATE inbox SET state='consumed', native_receipt=?, consumed_at=? WHERE message_id=?").run(receipt.receipt_id, this.now(), messageId);
+    });
+  }
+
+  recordNativeRejection(messageId, injectionId, { definitelyNotAccepted } = {}) {
+    if (definitelyNotAccepted !== true) throw new LocalError('injection_uncertain', { effect: 'unknown' });
+    return this.transaction(() => {
+      const row = this.db.prepare('SELECT state,injection_id FROM inbox WHERE message_id=?').get(messageId);
+      if (!row || row.state !== 'injecting' || row.injection_id !== injectionId) throw new LocalError('injection_uncertain');
+      this.db.prepare("UPDATE inbox SET state='pending', injection_id=NULL WHERE message_id=?").run(messageId);
+    });
+  }
+
+  /** Operator-only local API. Never expose this through an agent tool. */
+  resolveUncertain(messageId, { resolution, duplicateRiskAcknowledged = false } = {}) {
+    if (!['accepted', 'retry'].includes(resolution) || (resolution === 'retry' && duplicateRiskAcknowledged !== true)) throw new LocalError('injection_uncertain');
+    return this.transaction(() => {
+      const row = this.db.prepare('SELECT state FROM inbox WHERE message_id=?').get(messageId);
+      if (!row || !['injecting', 'uncertain'].includes(row.state)) throw new LocalError('injection_uncertain');
+      if (resolution === 'accepted') this.db.prepare("UPDATE inbox SET state='consumed',native_receipt='operator-confirmed',consumed_at=? WHERE message_id=?").run(this.now(), messageId);
+      else this.db.prepare("UPDATE inbox SET state='pending',injection_id=NULL WHERE message_id=?").run(messageId);
+    });
+  }
+
+  prepareSend(rawRequest, { key = randomUUID(), retryWindowSeconds = 86400 } = {}) {
+    key = validateIdempotencyKey(key);
+    const request = validateSend(rawRequest);
+    const encoded = canonical(request);
+    const hash = digest(request);
+    const existing = this.outgoing(key);
+    if (existing) {
+      if (existing.digest !== hash) throw new LocalError('send_conflict');
+      return key;
+    }
+    if (!Number.isSafeInteger(retryWindowSeconds) || retryWindowSeconds < 1) throw new LocalError('invalid_configuration');
+    this.transaction(() => {
+      if (this.db.prepare('SELECT COUNT(*) AS n FROM outgoing').get().n >= this.limits.maxOutgoingCount) throw new LocalError('inbox_full');
+      this.db.prepare('INSERT INTO outgoing(key,digest,request,created_at,retry_until) VALUES(?,?,?,?,?)').run(key, hash, encoded, this.now(), this.now() + retryWindowSeconds * 1000);
+    }, { growth: Buffer.byteLength(encoded) * 3 + 8192 });
+    return key;
+  }
+
+  outgoing(key) {
+    this.assertUsable();
+    const row = this.db.prepare('SELECT * FROM outgoing WHERE key=?').get(key);
+    return row ? { ...row, request: JSON.parse(row.request), result: row.result ? JSON.parse(row.result) : null } : null;
+  }
+
+  unresolvedSends() {
+    this.assertUsable();
+    return this.db.prepare('SELECT key,created_at,retry_until FROM outgoing WHERE result IS NULL ORDER BY created_at LIMIT 100').all().map(row => ({ ...row }));
+  }
+
+  recordSendResult(key, result) {
+    const encoded = canonical(result);
+    if (Buffer.byteLength(encoded) > 16384) throw new LocalError('invalid_response', { effect: 'unknown' });
+    this.transaction(() => {
+      if (!this.outgoing(key)) throw new LocalError('invalid_configuration');
+      this.db.prepare('UPDATE outgoing SET result=? WHERE key=?').run(encoded, key);
+    }, { growth: Buffer.byteLength(encoded) * 2 + 8192 });
+  }
+
+  collect(limit = 100) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new LocalError('invalid_configuration');
+    return this.transaction(() => {
+      const removedInbox = this.db.prepare("DELETE FROM inbox WHERE message_id IN (SELECT message_id FROM inbox WHERE state='consumed' AND retain_until<? ORDER BY retain_until LIMIT ?)").run(this.now(), limit).changes;
+      const removedSends = this.db.prepare('DELETE FROM outgoing WHERE key IN (SELECT key FROM outgoing WHERE result IS NOT NULL AND retry_until<? ORDER BY retry_until LIMIT ?)').run(this.now(), limit).changes;
+      return { removed_inbox: removedInbox, removed_sends: removedSends };
+    });
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    try { this.db.close(); } finally { this.owner.close(); }
+  }
+}