@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/xmtp/src/tools.ts

@@ -1,7 +1,7 @@
-import type { StationTool } from '@metro-labs/mcp/stations/types';
+import type { StationTool } from '@metro-labs/core/stations/types';
+import { PRIORITIES } from './labels.js';
 import {
   str,
-  createChannel,
   setChannelMetadata,
   xmtpSendAttachments,
 } from './tools-handlers.js';
@@ -15,43 +15,9 @@ const lineProp = {
 } as const;
 
 export const XMTP_TOOLS: StationTool[] = [
-  {
-    name: 'create_channel',
-    description:
-      'Create a new XMTP group conversation (channel). Args: addresses (required, array of ' +
-      'Ethereum 0x addresses to add as members), name (required, the group name), labels? ' +
-      '(optional string[] status labels applied after creation), account? ' +
-      '(defaults to your only XMTP account). Calls the daemon xmtp `newGroup`, then ' +
-      '`updateChannelMeta` if labels ' +
-      'are given. Returns the new metro:// line and convId. This is an xmtp-only operation. ' +
-      'NOTE: there is no add-members verb on the daemon, so members must be supplied at ' +
-      'creation time.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        addresses: {
-          type: 'array',
-          description: 'Ethereum 0x addresses to add as group members.',
-          items: { type: 'string' },
-        },
-        name: { type: 'string', description: 'The group/channel name.' },
-        labels: {
-          type: 'array',
-          description: 'Optional status labels to apply after creation.',
-          items: { type: 'string' },
-        },
-        account: {
-          type: 'string',
-          description:
-            'XMTP account to create under. Omit when you have only one.',
-        },
-      },
-      required: ['addresses', 'name'],
-    },
-    handle: (a, ctx) => createChannel(a, ctx),
-  },
   {
     name: 'ask',
+    group: 'write',
     description:
       'Ask a question as a poll in an XMTP conversation (mirrors Claude AskUserQuestion). ' +
       'Single-question form: question (required), options? (string[]), header?, multiSelect?, ' +
@@ -116,11 +82,12 @@ export const XMTP_TOOLS: StationTool[] = [
   },
   {
     name: 'dm',
+    group: 'write',
     description:
       'Open (or reuse) a 1:1 XMTP DM with an Ethereum address. Args: address (required, 0x...), ' +
       'account? (defaults to your only XMTP account). Returns the new metro:// line and ' +
       'convId. xmtp-only ' +
-      '(daemon `newDm`). Use this instead of create_channel when there is a single recipient.',
+      '(daemon `newDm`). For a group, use create_group.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -145,10 +112,13 @@ export const XMTP_TOOLS: StationTool[] = [
   },
   {
     name: 'group_info',
+    group: 'read',
     description:
       "Read an XMTP channel's current metadata + membership. Args: line (required). Returns " +
-      '{line, id, account, version (dm|group), name, memberCount, labels, github, preview, ' +
-      'members:[{inboxId, address}]}. xmtp-only (daemon `groupInfo`). Use before ' +
+      '{line, id, account, version (dm|group), name, memberCount, labels, category, status, priority, github, preview, ' +
+      'assigned, appData (stored JSON object), rawAppData (stored JSON string), ' +
+      'members:[{inboxId, address}]}. Syncs first and fails if metadata cannot be read. ' +
+      'xmtp-only (daemon `groupInfo`). Use before ' +
       'set_channel_metadata/add_members to see current state.',
     inputSchema: {
       type: 'object',
@@ -163,35 +133,88 @@ export const XMTP_TOOLS: StationTool[] = [
   },
   {
     name: 'close_channel',
+    group: 'write',
+    destructive: true,
     description:
-      'Archive/close an XMTP group (removes members). Args: line (required). xmtp-only ' +
-      '(daemon `closeGroup`). Irreversible-ish: members are removed from the group.',
+      'Remove members from an XMTP group, and optionally leave it. Args: line (required), ' +
+      'removeInboxIds? (inbox ids to remove; your own is ignored here), removeSelf? (true to ' +
+      'leave the group yourself). With neither, nothing changes. xmtp-only (daemon ' +
+      '`closeGroup`). Returns {removed, leftSelf}.',
     inputSchema: {
       type: 'object',
-      properties: { line: lineProp },
+      properties: {
+        line: lineProp,
+        removeInboxIds: {
+          type: 'array',
+          description: 'Inbox ids of the members to remove.',
+          items: { type: 'string' },
+        },
+        removeSelf: {
+          type: 'boolean',
+          description: 'Leave the group after removing the others.',
+        },
+      },
       required: ['line'],
     },
     async handle(a, ctx) {
       const line = str(a.line);
       if (!line) return ctx.err('close_channel requires `line`');
-      return ctx.okJson(await ctx.call('closeGroup', { line }));
+      const args: Record<string, unknown> = { line };
+      if (Array.isArray(a.removeInboxIds)) args.removeInboxIds = a.removeInboxIds.map(String);
+      if (a.removeSelf === true) args.removeSelf = true;
+      return ctx.okJson(await ctx.call('closeGroup', args));
     },
   },
   {
     name: 'set_channel_metadata',
+    group: 'write',
     description:
       "Update an existing channel's metadata. Args: line (required, the metro:// line), and " +
-      'any of labels? (string[]), github? (url), preview? (url), name? (string). All provided ' +
-      'fields are applied together in one atomic updateChannelMeta daemon call (a single ' +
-      'appData merge plus name update). xmtp-only ' +
-      '(channel metadata lives on xmtp groups). Returns the updated channel info.',
+      'any of metadata? (JSON object), github? (url), preview? (url), name? (string). ' +
+      'metadata is a shallow appData patch: omitted keys are preserved, supplied nested ' +
+      'values replace that key, and null deletes custom keys. v is reserved. Put labels, ' +
+      'assigned, category, status and priority inside metadata. assigned replaces the array with normalized lowercase ' +
+      'Ethereum addresses of current members. Read group_info and union existing IDs to ' +
+      'add assignees. category and status are each one free-form string per channel, trimmed, ' +
+      'whitespace collapsed and truncated to 24 characters. priority is trimmed and must be Urgent, High, Medium or Low. ' +
+      '"" or null clears category, status or priority. labels remains a legacy top-level alias. Duplicate top-level/metadata ' +
+      'label/link aliases are refused. All fields use one updateChannelMeta call. xmtp-only. ' +
+      'Returns updated metadata. Reread group_info to verify persistence.',
     inputSchema: {
       type: 'object',
       properties: {
         line: lineProp,
+        metadata: {
+          type: 'object',
+          description: 'Shallow JSON appData patch. Omitted keys stay unchanged. v is reserved.',
+          properties: {
+            labels: { type: 'array', items: { type: 'string' } },
+            assigned: {
+              type: 'array',
+              description: 'Replacement assignee list. Current member Ethereum addresses only. [] clears.',
+              items: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' },
+            },
+            category: {
+              type: ['string', 'null'],
+              description: 'One free-form category, trimmed, whitespace collapsed, truncated to 24 characters. "" or null clears it.',
+            },
+            status: {
+              type: ['string', 'null'],
+              description: 'One free-form status, trimmed, whitespace collapsed, truncated to 24 characters. "" or null clears it.',
+            },
+            priority: {
+              type: ['string', 'null'],
+              enum: [...PRIORITIES, '', null],
+              description: 'One priority: Urgent, High, Medium or Low. Surrounding whitespace is trimmed; empty or null clears it.',
+            },
+            github: { type: 'string' },
+            preview: { type: 'string' },
+          },
+          additionalProperties: true,
+        },
         labels: {
           type: 'array',
-          description: 'Status labels to set.',
+          description: 'Legacy alias. Prefer metadata.labels.',
           items: { type: 'string' },
         },
         github: {

package/runtime/node_modules/@metro-labs/xmtp/src/transcribe.ts

@@ -1,7 +1,6 @@
-import { errMsg } from '@metro-labs/mcp/log';
-import { mintId, SELF_URI } from './wire.js';
-
-type EmitInbound = (accountId: string, e: Record<string, unknown>) => void;
+import { errMsg } from '@metro-labs/core/log';
+import { emitInbound, selfUri } from '@metro-labs/core/stations/train-events';
+import { mintId } from '@metro-labs/core/stations/station-runtime';
 
 const WHISPER_BIN = process.env.METRO_WHISPER_BIN ?? 'whisper-cli';
 const WHISPER_MODEL =
@@ -14,7 +13,6 @@ export async function transcribeAndEmit(
   line: string,
   accountId: string,
   sourceMsgId: string,
-  emitInbound: EmitInbound,
 ): Promise<void> {
   const {
     existsSync: ex,
@@ -69,7 +67,7 @@ export async function transcribeAndEmit(
       ts: new Date().toISOString(),
       station: 'xmtp',
       line,
-      from: SELF_URI,
+      from: selfUri(),
       text: `🎙️ ${text}`,
       payload: {
         contentType: 'transcript',

package/runtime/node_modules/@metro-labs/xmtp/src/verify.ts

@@ -1,7 +1,8 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Client, type ClientOptions, type Signer } from '@xmtp/node-sdk';
-import { expandHome, signerFor, XMTP_ENV } from './identity.js';
+import { expandHome, identityFor, signerFor, XMTP_ENV } from './identity.js';
+import { ensureDeployed } from './smart.js';
 
 export class XmtpVerifyError extends Error {}
 
@@ -10,6 +11,7 @@ export interface XmtpVerified {
   address: string;
   installationId: string;
   dbPath: string;
+  smart: boolean;
 }
 
 interface RegisteredClient {
@@ -34,15 +36,25 @@ const reason = (err: unknown): string =>
 export async function verifyXmtpKey(
   privateKey: string,
   dbPath: string,
+  smart = false,
   create: CreateXmtpClient = openInbox,
 ): Promise<XmtpVerified> {
-  let signer: Signer;
-  let address: string;
+  let identity: Awaited<ReturnType<typeof identityFor>>;
   try {
-    ({ signer, address } = signerFor(privateKey));
+    signerFor(privateKey);
   } catch {
     throw new XmtpVerifyError('that is not a usable XMTP private key');
   }
+  try {
+    identity = await identityFor(privateKey, smart);
+  } catch (err) {
+    throw new XmtpVerifyError(`could not build the smart account on Base: ${reason(err)}`);
+  }
+  const { signer, address } = identity;
+  if (identity.smart !== null)
+    await ensureDeployed(identity.smart).catch((err: unknown) => {
+      throw new XmtpVerifyError(`could not deploy the smart account on Base (is the ZeroDev sponsorship still on?): ${reason(err)}`);
+    });
   const resolved = expandHome(dbPath);
   mkdirSync(dirname(resolved), { recursive: true });
   const client = await create(signer, resolved).catch((err: unknown) => {
@@ -59,6 +71,7 @@ export async function verifyXmtpKey(
     address,
     installationId: client.installationId,
     dbPath: resolved,
+    smart,
   };
 }
 
@@ -68,10 +81,11 @@ async function runCli(): Promise<void> {
     const input = JSON.parse(readFileSync(0, 'utf8')) as {
       privateKey?: unknown;
       dbPath?: unknown;
+      smart?: unknown;
     };
     if (typeof input.privateKey !== 'string' || typeof input.dbPath !== 'string')
       throw new XmtpVerifyError('xmtp verify needs a privateKey and a dbPath');
-    out = { ok: true, ...(await verifyXmtpKey(input.privateKey, input.dbPath)) };
+    out = { ok: true, ...(await verifyXmtpKey(input.privateKey, input.dbPath, input.smart === true)) };
   } catch (err) {
     out = { ok: false, error: reason(err) };
   }

package/runtime/node_modules/@metro-labs/xmtp/src/wallet.ts

@@ -0,0 +1,28 @@
+import type { EncodedContent } from '@xmtp/content-type-primitives';
+import {
+  SignatureReferenceCodec,
+  SignatureRequestCodec,
+  TransactionReferenceCodec,
+  WalletSendCallsCodec,
+} from './codecs.js';
+import { bad, isNode, parseJson } from './frames.js';
+
+const WALLET_TYPES: Record<string, { codec: { encode(c: Record<string, unknown>): EncodedContent }; needs: string[] }> = {
+  walletSendCalls: { codec: new WalletSendCallsCodec(), needs: ['version', 'chainId', 'from', 'calls'] },
+  transactionReference: { codec: new TransactionReferenceCodec(), needs: ['networkId', 'reference'] },
+  signatureRequest: { codec: new SignatureRequestCodec(), needs: ['id', 'kind'] },
+  signatureReference: { codec: new SignatureReferenceCodec(), needs: ['requestId', 'signature', 'signer'] },
+};
+
+export function buildWalletContent(raw: unknown): { encoded: EncodedContent; summary: string } {
+  const args = parseJson(raw, 'wallet');
+  const type = isNode(args) && typeof args.type === 'string' ? args.type : '';
+  const spec = Object.hasOwn(WALLET_TYPES, type) ? WALLET_TYPES[type] : undefined;
+  if (!isNode(args) || !spec) throw bad(`wallet type must be one of ${Object.keys(WALLET_TYPES).join(', ')}`);
+  const content = parseJson(args.content, 'wallet content');
+  if (!isNode(content)) throw bad(`wallet content must be the ${type} JSON object`);
+  const missing = spec.needs.filter((key) => content[key] === undefined);
+  if (missing.length > 0) throw bad(`${type} content needs ${missing.join(', ')}`);
+  const encoded = spec.codec.encode(content);
+  return { encoded, summary: encoded.fallback ?? type };
+}

package/runtime/node_modules/@metro-labs/xmtp/src/wire.ts

@@ -1,7 +1,3 @@
-export { emit, respond, mintId } from '@metro-labs/mcp/stations/station-runtime';
-
-export const SELF_URI = process.env.METRO_SELF_URI ?? '';
-
 const UID_MAP_MAX = 5000;
 const uidToXmtp = new Map<string, string>();
 
@@ -37,3 +33,17 @@ export function resolveMsgId(rawId: string): string {
       '(not seen by this train; pass the raw xmtp message_id)',
   );
 }
+
+const SENT_MAX = 5000;
+const sentIds = new Set<string>();
+
+export function rememberSent(xmtpId: string | undefined): void {
+  if (!xmtpId) return;
+  sentIds.add(xmtpId);
+  if (sentIds.size > SENT_MAX) {
+    const oldest = sentIds.values().next().value;
+    if (oldest !== undefined) sentIds.delete(oldest);
+  }
+}
+
+export const sentByMe = (xmtpId: string): boolean => sentIds.has(xmtpId);

package/runtime/patches/5bca2c07d5852d3f58453cff0448dd85da13d3665b61e3d758905b298d432d7c.patch

@@ -0,0 +1,31 @@
+diff --git a/lib/Types/Events.d.ts b/lib/Types/Events.d.ts
+index f55c4c325b08b8c25dc9d17032514ce5c80ad3fd..930cb143e813b9a656533ae765f9db70f6eb7ccd 100644
+--- a/lib/Types/Events.d.ts
++++ b/lib/Types/Events.d.ts
+@@ -46,6 +46,10 @@ export type BaileysEventMap = {
+     'lid-mapping.update': LIDMapping;
+     /** delete chats with given ID */
+     'chats.delete': string[];
++    'chats.clear': {
++        id: string;
++        messageRange?: proto.SyncActionValue.ISyncActionMessageRange | null;
++    };
+     /** presence of contact in a chat updated */
+     'presence.update': {
+         id: string;
+diff --git a/lib/Utils/chat-utils.js b/lib/Utils/chat-utils.js
+index c30265d36671bacd25a8c456cafedcd9fc2fdd9a..2be37df069eda49c546eac1eb3485e649432dbeb 100644
+--- a/lib/Utils/chat-utils.js
++++ b/lib/Utils/chat-utils.js
+@@ -763,7 +763,11 @@ export const processSyncAction = (syncAction, ev, me, initialSyncOpts, logger) =
+             }
+         ]);
+     }
++    else if (action?.clearChatAction || type === 'clearChat') {
++        ev.emit('chats.clear', { id, messageRange: action?.clearChatAction?.messageRange });
++    }
+     else if (action?.deleteChatAction || type === 'deleteChat') {
++        ev.emit('chats.clear', { id, messageRange: action?.deleteChatAction?.messageRange });
+         if (!isInitialSync) {
+             ev.emit('chats.delete', [id]);
+         }

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.31"
+  "version": "0.1.0-beta.310"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@metro-labs/core",
+  "version": "0.1.0",
+  "private": true,
+  "description": "What every metro process shares: the logger, the event bus and its types, ids, secure file writes, the train protocol, station types and attachment handling. No HTTP, no policy.",
+  "type": "module",
+  "exports": {
+    "./log": "./src/log.ts",
+    "./events": "./src/events.ts",
+    "./is-record": "./src/is-record.ts",
+    "./runner-activity": "./src/runner-activity.ts",
+    "./automation-store": "./src/automation-store.ts",
+    "./automation-types": "./src/automation-types.ts",
+    "./call": "./src/call.ts",
+    "./secure-fs": "./src/secure-fs.ts",
+    "./skill-source": "./src/skill-source.ts",
+    "./version": "./src/version.ts",
+    "./train-error": "./src/train-error.ts",
+    "./trains/protocol": "./src/protocol.ts",
+    "./ids": "./src/ids.ts",
+    "./tickets": "./src/tickets.ts",
+    "./station-names": "./src/station-names.ts",
+    "./str": "./src/str.ts",
+    "./lines": "./src/lines.ts",
+    "./endpoints": "./src/endpoints.ts",
+    "./stations/types": "./src/stations/types.ts",
+    "./stations/channel-directory": "./src/stations/channel-directory.ts",
+    "./stations/channel-pages": "./src/stations/channel-pages.ts",
+    "./stations/account-files": "./src/stations/account-files.ts",
+    "./stations/station-runtime": "./src/stations/station-runtime.ts",
+    "./stations/account-store": "./src/stations/account-store.ts",
+    "./stations/attachments": "./src/stations/attachments.ts",
+    "./stations/mail": "./src/stations/mail.ts",
+    "./stations/mail-text": "./src/stations/mail-text.ts",
+    "./stations/mail-trust": "./src/stations/mail-trust.ts",
+    "./stations/oauth": "./src/stations/oauth.ts",
+    "./stations/messaging-normalize": "./src/stations/messaging-normalize.ts",
+    "./stations/profile": "./src/stations/profile.ts",
+    "./stations/sender-profile": "./src/stations/sender-profile.ts",
+    "./stations/train-events": "./src/stations/train-events.ts",
+    "./stations/train-boot": "./src/stations/train-boot.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --noEmit && METRO_STATE_DIR=\"$(mktemp -d /tmp/metro-test.XXXXXX)\" bun test test/"
+  },
+  "dependencies": {
+    "pino": "^9.5.0",
+    "pino-pretty": "^13.1.3"
+  },
+  "devDependencies": {
+    "@stage-labs/config": "0.1.0-beta.3",
+    "eslint": "^10.3.0",
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/automation-files.ts

@@ -0,0 +1,216 @@
+import { randomUUID } from 'node:crypto';
+import fs, { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, type Stats } from 'node:fs';
+import { dirname, join, parse, resolve, sep } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { AutomationError } from './automation-types.js';
+import { isRecord } from './is-record.js';
+
+const FILE = 'automation.sqlite';
+const SCHEMA = `
+CREATE TABLE requests (
+  uuid TEXT PRIMARY KEY NOT NULL,
+  routine TEXT NOT NULL,
+  slot INTEGER NOT NULL,
+  payload TEXT NOT NULL,
+  UNIQUE (routine, slot)
+);
+CREATE TABLE statuses (
+  uuid TEXT PRIMARY KEY NOT NULL REFERENCES requests(uuid) ON DELETE CASCADE,
+  payload TEXT NOT NULL
+);
+CREATE TABLE resolutions (
+  uuid TEXT NOT NULL REFERENCES requests(uuid) ON DELETE CASCADE,
+  outcome TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  PRIMARY KEY (uuid, outcome)
+);
+PRAGMA user_version = 1;
+`;
+
+function hasCode(error: unknown, code: string): boolean {
+  return isRecord(error) && error.code === code;
+}
+
+function metadata(path: string): Stats | null {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (hasCode(error, 'ENOENT')) return null;
+    throw error;
+  }
+}
+
+function uid(): number {
+  if (process.getuid === undefined) throw new AutomationError('unsafe-storage');
+  return process.getuid();
+}
+
+function checkDirectory(info: Stats, privateDirectory: boolean): void {
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new AutomationError('unsafe-storage');
+  if (privateDirectory) {
+    if (info.uid !== uid() || (info.mode & 0o7777) !== 0o700) throw new AutomationError('unsafe-storage');
+    return;
+  }
+  if (info.uid !== uid() && info.uid !== 0) throw new AutomationError('unsafe-storage');
+  if ((info.mode & 0o022) !== 0 && (info.mode & 0o1000) === 0) throw new AutomationError('unsafe-storage');
+}
+
+function syncDirectory(path: string): void {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try {
+    fs.fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function directory(root: string, create: boolean): boolean {
+  let current = parse(root).root;
+  const base = metadata(current);
+  if (base === null) throw new AutomationError('unsafe-storage');
+  checkDirectory(base, current === root);
+  for (const component of root.slice(current.length).split(sep).filter(Boolean)) {
+    current = join(current, component);
+    let info = metadata(current);
+    if (info === null) {
+      if (!create) return false;
+      try {
+        mkdirSync(current, { mode: 0o700 });
+        syncDirectory(dirname(current));
+      } catch (error) {
+        if (!hasCode(error, 'EEXIST')) throw error;
+      }
+      info = metadata(current);
+    }
+    if (info === null) throw new AutomationError('unsafe-storage');
+    checkDirectory(info, current === root);
+  }
+  return true;
+}
+
+function checkFile(info: Stats, singleLink = false): void {
+  if (!info.isFile() || info.uid !== uid() || (info.mode & 0o7777) !== 0o600 || (singleLink && info.nlink !== 1)) throw new AutomationError('unsafe-storage');
+}
+
+function companions(path: string): void {
+  for (const suffix of ['-journal', '-wal', '-shm']) {
+    const info = metadata(`${path}${suffix}`);
+    if (info !== null) checkFile(info, true);
+  }
+}
+
+function sameFile(path: string, opened: Stats): void {
+  const current = metadata(path);
+  if (current === null || current.dev !== opened.dev || current.ino !== opened.ino) throw new AutomationError('unsafe-storage');
+  checkFile(current);
+}
+
+function initializeFile(path: string, fd: number): void {
+  const opened = fstatSync(fd);
+  checkFile(opened);
+  const db = new DatabaseSync(path);
+  try {
+    sameFile(path, opened);
+    db.exec('PRAGMA trusted_schema = OFF');
+    transaction(db, (database) => { database.exec(SCHEMA); });
+  } finally {
+    db.close();
+  }
+  fs.fsyncSync(fd);
+}
+
+function createFile(path: string): void {
+  if (metadata(path) !== null) return;
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    initializeFile(temporary, fd);
+    try {
+      fs.linkSync(temporary, path);
+    } catch (error) {
+      if (!hasCode(error, 'EEXIST')) throw error;
+    }
+  } finally {
+    closeSync(fd);
+    fs.unlinkSync(temporary);
+  }
+  syncDirectory(dirname(path));
+}
+
+function transaction<T>(db: DatabaseSync, action: (database: DatabaseSync) => T): T {
+  db.exec('PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL; PRAGMA foreign_keys = ON; BEGIN IMMEDIATE');
+  try {
+    const result = action(db);
+    db.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+}
+
+function useDatabase<T>(path: string, writable: boolean, action: (database: DatabaseSync) => T): T {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let db: DatabaseSync | undefined;
+  try {
+    const opened = fstatSync(fd);
+    checkFile(opened);
+    companions(path);
+    db = new DatabaseSync(path, { readOnly: !writable });
+    sameFile(path, opened);
+    db.exec('PRAGMA busy_timeout = 5000; PRAGMA trusted_schema = OFF');
+    if (db.prepare('PRAGMA user_version').get()?.user_version !== 1) throw new AutomationError('corrupt-storage');
+    if (writable) return transaction(db, action);
+    if (db.prepare('PRAGMA journal_mode').get()?.journal_mode !== 'delete') throw new AutomationError('corrupt-storage');
+    db.exec('BEGIN');
+    try {
+      return action(db);
+    } finally {
+      db.exec('ROLLBACK');
+    }
+  } finally {
+    db?.close();
+    closeSync(fd);
+  }
+}
+
+function databasePath(root: string, writable: boolean, existingOnly: boolean): string | null {
+  const create = writable && !existingOnly;
+  const absolute = resolve(root);
+  if (!directory(absolute, create)) return null;
+  const path = join(absolute, FILE);
+  companions(path);
+  if (create) createFile(path);
+  const info = metadata(path);
+  if (info === null) {
+    if (create) throw new AutomationError('storage-unavailable');
+    return null;
+  }
+  checkFile(info);
+  return path;
+}
+
+export function validateAutomationDirectory(root: string): void {
+  try {
+    databasePath(root, false, false);
+  } catch (error) {
+    if (error instanceof AutomationError) throw error;
+    throw new AutomationError('storage-unavailable', { cause: error });
+  }
+}
+
+export function automationDatabase<T>(root: string, writable: boolean, action: (database: DatabaseSync) => T, missing: T, existingOnly = false): T {
+  try {
+    const path = databasePath(root, writable, existingOnly);
+    if (path === null) return missing;
+    const result = useDatabase(path, writable, action);
+    if (writable) {
+      companions(path);
+      syncDirectory(dirname(path));
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof AutomationError) throw error;
+    throw new AutomationError('storage-unavailable', { cause: error });
+  }
+}