@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/shared-kernel/device-completion-history.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('node:util');
+const { CommandError } = require('../command-errors');
+const { sanitizePersistentValue } = require('../fact-codec');
+const { getHostFactStore, withHostFactStore } = require('./host-fact-store');
+const { digest } = require('./uia-protocol');
+
+const schema = 'aab.device-completion/v1';
+const targetKey = serial => `device-completion:${serial}`;
+
+function representation(json, originalSha256) {
+  const stored = sanitizePersistentValue(json), storedSha256 = digest(stored);
+  return { representation: stored === json ? 'original-json' : 'redacted-json', originalSha256, storedSha256, json: stored };
+}
+
+function persistCompletion({ pending, proof, historyTarget }) {
+  const record = { schemaVersion: schema, kind: 'uia-node', serial: pending.target.serial,
+    bootId: pending.bootId, runtimeEpoch: pending.runtimeEpoch, actionId: pending.actionId,
+    request: representation(pending.requestJson, pending.requestSha256),
+    completion: representation(proof.receiptJson, proof.responseSha256) };
+  return withHostFactStore(historyTarget, store => {
+    const key = targetKey(record.serial);
+    const saved = store.record({ partition: 'action', targetKey: key, runtimeEpoch: record.runtimeEpoch, actionId: record.actionId,
+      dedupeKey: `${key}:${record.runtimeEpoch}:${record.actionId}:${pending.requestSha256}:${proof.responseSha256}`,
+      payload: record }, { durability: 'sync' });
+    if (saved.ok !== true || saved.receipt?.stored !== true)
+      throw new CommandError('device_completion_history_unavailable', 'The original completion could not be committed to FactStore; phone acknowledgement remains pending.');
+    const page = store.read({ partitions: ['action'], targetKey: key, runtimeEpoch: record.runtimeEpoch, actionId: record.actionId, limit: 2 });
+    if (!page.ok || page.items?.length !== 1 || !isDeepStrictEqual(page.items[0].payload, record))
+      throw new CommandError('device_completion_history_invalid', 'The committed completion representation could not be read back exactly.');
+    return { storeDirectory: historyTarget.directory, targetKey: key, globalSeq: page.items[0].globalSeq,
+      runtimeEpoch: record.runtimeEpoch, actionId: record.actionId,
+      originalCompletionAvailable: record.request.representation === 'original-json' && record.completion.representation === 'original-json' };
+  });
+}
+
+function readCompletion({ serial, runtimeEpoch, actionId }) {
+  const page = getHostFactStore().read({ partitions: ['action'], targetKey: targetKey(serial), runtimeEpoch, actionId, limit: 2 });
+  if (!page.ok) return { ok: false, error: page.error || 'device_completion_history_unavailable' };
+  if (page.items?.length !== 1) return { ok: false, error: page.items?.length ? 'device_completion_history_ambiguous' : 'device_completion_not_retained',
+    serial, runtimeEpoch, actionId, message: 'No unique retained completion representation matches this identity. Absence is not an action outcome.' };
+  const { payload: record, globalSeq } = page.items[0];
+  if (record?.schemaVersion !== schema || record.serial !== serial || record.runtimeEpoch !== runtimeEpoch || record.actionId !== actionId
+    || [record.request, record.completion].some(value => !value || typeof value.json !== 'string' || digest(value.json) !== value.storedSha256
+      || !/^[0-9a-f]{64}$/.test(value.originalSha256) || value.representation !== (value.originalSha256 === value.storedSha256 ? 'original-json' : 'redacted-json')))
+    return { ok: false, error: 'device_completion_history_invalid' };
+  return { ok: true, serial, runtimeEpoch, actionId, source: 'host-fact-store', globalSeq,
+    originalCompletionAvailable: record.request.representation === 'original-json' && record.completion.representation === 'original-json', record };
+}
+
+module.exports = { persistCompletion, readCompletion };

package/bin/shared-kernel/device-mutation-lease.js

@@ -0,0 +1,219 @@
+'use strict';
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+const { randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { createOwnershipStore, schemaVersion } = require('./device-ownership-store');
+const acknowledgements = require('./device-acknowledgements');
+
+const context = new AsyncLocalStorage();
+const effectContext = new AsyncLocalStorage();
+
+function rejection(error, serial, ownership) {
+  return { ok: false, error, serial, active: 1, dispatched: false, ambiguous: false,
+    message: error === 'target_busy' ? 'Another Host operation owns this physical device.'
+      : 'A previous device action has no confirmed completion. Reconcile device ownership before another mutation.',
+    ...(ownership ? { ownership: structuredClone(ownership) } : {}) };
+}
+
+function knownOutcome(value) {
+  if (value?.settled === true) return true;
+  if (value?.settled === false || value?.ambiguous === true || value?.dispatched === null) return false;
+  if (value?.dispatched === false && value?.ambiguous === false) return true;
+  // A protocol error without dispatch metadata is not proof that the remote
+  // operation stopped. In particular, an H5 timeout can leave a queued write.
+  return value?.ok !== false && value?.error == null;
+}
+
+function createDeviceMutationLease({ directory } = {}) {
+  const store = createOwnershipStore(directory);
+  const held = new Map();
+  function acquire(serial) {
+    if (typeof serial !== 'string' || !serial) return { ok: false, error: 'serial_required', dispatched: false, ambiguous: false };
+    const parent = context.getStore();
+    if (parent?.serial === serial && parent.directory === store.directory && !parent.closed) {
+      if (parent.state.phase === 'unresolved') return rejection('device_ownership_unresolved', serial, parent.state);
+      return { ok: true, serial, run: action => {
+        if (parent.closed) throw new CommandError('device_ownership_lost', 'The owning device operation has already closed.');
+        return action();
+      }, release() {} };
+    }
+    if (held.has(serial)) return rejection('target_busy', serial, held.get(serial).state);
+    const lock = store.lock(serial);
+    if (!lock) return rejection('target_busy', serial);
+    try {
+      const previous = store.read(serial);
+      if (previous?.pending || previous?.reservations.length) { lock.close(); return rejection('device_ownership_unresolved', serial, previous); }
+      const state = { schemaVersion, serial, phase: 'owned', owner: { id: randomUUID(), pid: process.pid, acquiredAtMs: Date.now() },
+        pending: null, reservations: [], lastSettlement: previous?.lastSettlement ?? null,
+        pendingAcknowledgements: previous?.pendingAcknowledgements ?? [] };
+      store.write(serial, state);
+      const owner = { serial, directory: store.directory, state, closed: false,
+        commit() { if (owner.closed) throw new CommandError('device_ownership_lost', 'The owning device operation has already closed.'); store.write(serial, state); } };
+      held.set(serial, owner);
+      return {
+        ok: true, serial,
+        retain(descriptor) {
+          if (owner.closed || state.phase === 'unresolved') throw new CommandError('device_ownership_lost', 'Cannot start work after the owner has stopped.');
+          const reservation = { ...descriptor, id: randomUUID(), preparedAtMs: Date.now() };
+          state.reservations.push(reservation); owner.commit();
+          let done = false;
+          return { settle(proof) {
+            if (done) return;
+            if (owner.closed) throw new CommandError('device_ownership_lost', 'The device owner has closed.');
+            if (proof?.settled !== true) return;
+            state.reservations = state.reservations.filter(item => item !== reservation);
+            state.lastSettlement = { pendingId: reservation.id, settledAtMs: Date.now(), proof };
+            owner.commit(); done = true;
+          } };
+        },
+        async run(action) {
+          if (owner.closed) throw new CommandError('device_ownership_lost', 'The owning device operation has already closed.');
+          if (state.phase === 'unresolved' || state.pending) return rejection('device_ownership_unresolved', serial, state);
+          // Only an actual transport effect or installation reservation can
+          // outlive this Host. Observation/preparation does not dispatch work.
+          const receipts = [];
+          owner.receipts = receipts;
+          try {
+            return await context.run(owner, action);
+          } catch (error) {
+            if (receipts.length && !state.pending) {
+              error.settled = true;
+              if (receipts.some(proof => proof.dispatched === true)) error.dispatched = true;
+              if (receipts.length === 1) error.executionReceipt = receipts[0];
+              else error.executionReceipts = receipts;
+            }
+            throw error;
+          } finally {
+            if (state.pending) { state.phase = 'unresolved'; owner.commit(); }
+          }
+        },
+        release() {
+          if (owner.closed) return;
+          try { state.phase = state.pending || state.reservations.length ? 'unresolved' : 'idle'; owner.commit(); }
+          finally { owner.closed = true; held.delete(serial); lock.close(); }
+        },
+      };
+    } catch (error) { lock.close(); throw error; }
+  }
+  async function run(serial, action) {
+    const token = acquire(serial);
+    if (!token.ok) return token;
+    try { return await token.run(action); } finally { token.release(); }
+  }
+  function status(serial) {
+    if (typeof serial !== 'string' || !serial) return { ok: false, error: 'serial_required' };
+    const lock = held.has(serial) ? null : store.lock(serial);
+    try {
+      const state = store.read(serial);
+      const unresolved = state?.pending || state?.reservations.length;
+      return { ok: true, serial, active: !lock || unresolved ? 1 : 0, maxActive: 1,
+        phase: !lock ? 'owned' : unresolved ? 'unresolved' : 'idle', ownership: state ? structuredClone(state) : null };
+    } finally { lock?.close(); }
+  }
+  async function reconcile(serial, verify) {
+    const lock = held.has(serial) ? null : store.lock(serial);
+    if (!lock) return rejection('target_busy', serial);
+    try {
+      const state = store.read(serial);
+      if (!state?.pending && !state?.reservations.length) return { ok: true, serial, phase: 'idle', recovered: false };
+      for (const pending of [state.pending, ...state.reservations].filter(Boolean)) {
+        const proof = await verify(structuredClone(pending));
+        if (proof?.settled !== true) return { ...rejection('device_ownership_unresolved', serial, state), recovery: proof };
+        acknowledgements.append(state, pending, proof);
+        state.lastSettlement = { pendingId: pending.id, settledAtMs: Date.now(), proof };
+        if (state.pending === pending) state.pending = null;
+        else state.reservations = state.reservations.filter(item => item !== pending);
+        store.write(serial, state);
+      }
+      state.phase = 'idle'; store.write(serial, state);
+      return { ok: true, serial, phase: 'idle', recovered: true, settlement: state.lastSettlement,
+        executionReceipt: state.lastSettlement.proof };
+    } finally { lock.close(); }
+  }
+  async function drainAcknowledgements(serial, acknowledge) {
+    const lock = held.has(serial) ? null : store.lock(serial);
+    if (!lock) return rejection('target_busy', serial);
+    try {
+      const state = store.read(serial), errors = [], retired = [];
+      if (!state) return { ok: true, remaining: 0, errors, retired };
+      for (const entry of [...state.pendingAcknowledgements]) {
+        try {
+          const result = await retireAcknowledgement(state, entry, () => store.write(serial, state), acknowledge);
+          retired.push({ actionId: entry.pending.actionId, disposition: result.disposition, history: result.history });
+        }
+        catch (error) { errors.push({ actionId: entry.pending.actionId, error: error.code || 'uia_acknowledgement_failed' }); }
+      }
+      return { ok: true, remaining: state.pendingAcknowledgements.length, errors, retired };
+    } finally { lock.close(); }
+  }
+  return { acquire, run, status, reconcile, drainAcknowledgements, directory: store.directory };
+}
+
+// Ordinary transport calls inherit a managed provider's effect scope. Its
+// cancellation request must not replace the identity of the original action.
+async function runDeviceEffect(descriptor, action, settled = knownOutcome, { allowNested = false } = {}) {
+  const owner = context.getStore();
+  if (!owner) return action();
+  if (owner.closed) throw new CommandError('device_ownership_lost', 'The device owner has closed.');
+  if (effectContext.getStore() === owner) return action();
+  const state = owner.state;
+  if (state.phase === 'unresolved' || state.pending && state.pending.allowNested !== true) {
+    throw new CommandError('device_ownership_unresolved', 'The preceding device action is still unresolved.');
+  }
+  acknowledgements.checkCapacity(state, descriptor);
+  const pending = { ...descriptor, ...(allowNested ? { allowNested: true } : {}), id: randomUUID(), preparedAtMs: Date.now() };
+  state.pending = pending; owner.commit();
+  const finish = proof => {
+    if (owner.closed || state.pending !== pending) throw new CommandError('device_ownership_lost', 'A different device operation owns the settlement.');
+    acknowledgements.append(state, pending, proof);
+    state.lastSettlement = { pendingId: pending.id, settledAtMs: Date.now(), proof };
+    state.pending = null; owner.commit();
+    owner.receipts?.push(proof);
+  };
+  try {
+    const result = await (allowNested ? action() : effectContext.run(owner, action));
+    // The adapter's actual transport has taken responsibility for settlement.
+    // Do not restore a generic marker after its specific receipt is durable.
+    if (allowNested && state.pending !== pending) return result;
+    const proof = settled(result);
+    if (proof) finish(proof === true ? { kind: descriptor.kind, actionId: descriptor.actionId ?? null,
+      runtimeEpoch: descriptor.runtimeEpoch ?? null, settled: true, dispatched: result?.dispatched ?? null } : proof);
+    else { state.phase = 'unresolved'; owner.commit(); }
+    return result;
+  } catch (error) {
+    if (allowNested && state.pending !== pending) throw error;
+    if (error?.dispatched === false && error?.ambiguous !== true) finish({ kind: descriptor.kind, settled: true, dispatched: false });
+    else { state.phase = 'unresolved'; owner.commit(); }
+    throw error;
+  }
+}
+
+let processLease;
+function getProcessDeviceMutationLease() { return processLease ||= createDeviceMutationLease(); }
+
+function isDeviceSettlementDurable(proof) {
+  const owner = context.getStore();
+  return Boolean(owner && !owner.closed && JSON.stringify(owner.state.lastSettlement?.proof) === JSON.stringify(proof));
+}
+
+async function retireAcknowledgement(state, entry, commit, acknowledge) {
+  const history = require('./device-completion-history').persistCompletion(entry);
+  const result = await acknowledge(structuredClone(entry));
+  if (!acknowledgements.accepted(result))
+    throw new CommandError(result?.error || 'uia_acknowledgement_failed', 'The original receipt acknowledgement remains pending.');
+  const previous = state.pendingAcknowledgements;
+  state.pendingAcknowledgements = previous.filter(item => item !== entry);
+  try { commit(); } catch (error) { state.pendingAcknowledgements = previous; throw error; }
+  return { ...result, history };
+}
+
+async function completeDeviceAcknowledgement(proof, acknowledge) {
+  const owner = context.getStore();
+  if (!owner || owner.closed) throw new CommandError('device_ownership_lost', 'Acknowledgement requires the original device owner.');
+  const entry = owner.state.pendingAcknowledgements.find(item => JSON.stringify(item.proof) === JSON.stringify(proof));
+  if (!entry) throw new CommandError('device_acknowledgement_invalid', 'No durable acknowledgement matches this completion receipt.');
+  return retireAcknowledgement(owner.state, entry, () => owner.commit(), acknowledge);
+}
+
+module.exports = { createDeviceMutationLease, getProcessDeviceMutationLease, runDeviceEffect, isDeviceSettlementDurable, completeDeviceAcknowledgement };

package/bin/shared-kernel/device-ownership-recovery.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { getProcessDeviceMutationLease } = require('./device-mutation-lease');
+const protocols = { flutter: require('./flutter-execution'), native: require('./native-execution'), h5: require('./h5-execution') };
+const shellProtocol = require('./android-shell-execution');
+const installProtocol = require('./android-install-execution');
+const uiaProtocol = require('./uia-protocol');
+const { createUiaRuntimePort } = require('./uia-runtime-port');
+const acknowledgements = require('./device-acknowledgements');
+
+async function deviceOwnership(args, { lease = getProcessDeviceMutationLease(), ports,
+  shellPortFactory = shellProtocol.createAndroidShellPort, installPortFactory = installProtocol.createAndroidInstallPort,
+  uiaPortFactory = createUiaRuntimePort } = {}) {
+  if (args.operation === 'status') return lease.status(args.serial);
+  if (args.operation === 'receipt') return require('./device-completion-history').readCompletion(args);
+  const bridge = ports || require('../device-provider');
+  const installCleanup = [];
+  const recovered = await lease.reconcile(args.serial, async pending => {
+    if (pending.kind === 'uia-node') {
+      if (!uiaProtocol.validIdentity(pending) || pending.target.serial !== args.serial) return { settled: false, error: 'invalid_uia_execution_identity' };
+      try {
+        const port = uiaPortFactory({ ...pending.target, timeoutMs: args.timeoutMs ?? 5000 });
+        const result = await port.recover(pending);
+        const proof = uiaProtocol.settlementProof(result, pending);
+        if (!proof) return { settled: false, error: result?.error || 'uia_original_completion_unavailable', actionId: pending.actionId };
+        return proof;
+      } catch (error) { return { settled: false, error: error.code || 'uia_completion_query_failed', message: error.message }; }
+    }
+    if (pending.kind === 'android-install') {
+      if (pending.target?.serial !== args.serial || typeof pending.target.adb !== 'string' || !installProtocol.validIdentity(pending)) {
+        return { settled: false, error: 'invalid_install_execution_identity' };
+      }
+      try {
+        const port = installPortFactory({ ...pending.target, timeoutMs: args.timeoutMs ?? 5000 });
+        const result = await port.read(pending, true);
+        const proof = installProtocol.settlementProof(result, pending);
+        if (!proof) return { settled: false, error: 'install_completion_unavailable', actionId: pending.actionId };
+        installCleanup.push({ port, pending, result });
+        return proof;
+      } catch (error) { return { settled: false, error: error.code || 'install_completion_query_failed' }; }
+    }
+    if (pending.kind === 'android-shell') {
+      if (pending.target?.serial !== args.serial || typeof pending.target.adb !== 'string') {
+        return { settled: false, error: 'remote_completion_proof_unavailable' };
+      }
+      try {
+        const port = shellPortFactory({ ...pending.target, timeoutMs: args.timeoutMs ?? 5000 });
+        const result = await port.cancel(pending);
+        return shellProtocol.settlementProof(result, pending)
+          || { settled: false, error: result?.error || 'shell_action_not_settled', actionId: pending.actionId };
+      } catch (error) {
+        return { settled: false, error: error.code || 'remote_completion_query_failed', message: error.message };
+      }
+    }
+    const protocol = protocols[pending.kind];
+    if (!protocol || typeof pending.actionId !== 'string' || typeof pending.runtimeEpoch !== 'string'
+        || typeof pending.target?.packageName !== 'string') return { settled: false, error: 'remote_completion_proof_unavailable' };
+    const identity = { actionId: pending.actionId, runtimeEpoch: pending.runtimeEpoch };
+    const ctx = bridge.createBridgeContext({ ...pending.target, serial: args.serial, timeoutMs: args.timeoutMs ?? 5000 });
+    try {
+      // Re-discover and verify this phone/package connection. A changed runtime,
+      // missing action or idle SDK alone is never proof that this action ended.
+      const completion = { native: bridge.nativeCompletion, flutter: bridge.flutterCompletion, h5: bridge.h5Completion }[pending.kind];
+      const reply = await completion(ctx, identity);
+      if (reply?.ok !== true || reply.actionId !== identity.actionId || reply.runtimeEpoch !== identity.runtimeEpoch
+          || !protocol.terminalReceipt(reply.executionResult, identity)) return {
+        settled: false, error: reply?.error || `invalid_${pending.kind}_cancel_receipt`, actionId: identity.actionId,
+      };
+      return protocol.settlementProof(reply.executionResult, identity);
+    } catch (error) { return { settled: false, error: error.code || 'remote_completion_query_failed', message: error.message }; }
+  });
+  // Reconciliation fsyncs each exact proof before its phone copy may be retired.
+  // Even a later unresolved reservation cannot invalidate an earlier settlement.
+  for (const { port, pending, result } of installCleanup) {
+    try { await port.acknowledge(pending, result); }
+    catch (error) { (recovered.cleanupErrors ||= []).push({ actionId: pending.actionId, error: error.code || 'install_cleanup_failed' }); }
+  }
+  if (recovered.error !== 'target_busy') {
+    // This queue survives a Host exit even when there is no unresolved effect.
+    // Retiring an older known receipt never clears a different pending action.
+    const cleanup = await lease.drainAcknowledgements(args.serial, async ({ pending, proof }) => {
+      const port = uiaPortFactory({ ...pending.target, timeoutMs: args.timeoutMs ?? 5000 });
+      return port.acknowledge(pending, acknowledgements.completion(pending, proof));
+    });
+    if (!cleanup.ok) (recovered.cleanupErrors ||= []).push({ error: cleanup.error });
+    else {
+      recovered.pendingAcknowledgements = cleanup.remaining;
+      if (cleanup.retired.length) recovered.acknowledgements = cleanup.retired;
+      if (cleanup.errors.length) (recovered.cleanupErrors ||= []).push(...cleanup.errors);
+    }
+  }
+  return recovered;
+}
+
+module.exports = { deviceOwnership };

package/bin/shared-kernel/device-ownership-store.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { createHash, randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const acknowledgements = require('./device-acknowledgements');
+
+const schemaVersion = 'aab.device-ownership/v2';
+const maxJournalBytes = 4 * 1024 * 1024;
+// Keep the original physical lock namespace across journal format upgrades.
+const defaultDirectory = () => path.resolve(process.env.AI_APP_BRIDGE_DEVICE_OWNERSHIP_DIR
+  || path.join(os.homedir(), '.ai-app-bridge', 'device-ownership', 'v1'));
+
+// SQLite supplies an OS-managed exclusive file lock, with no heartbeat expiry.
+// Process death releases the lock; the separately committed journal survives.
+// Lock files are never unlinked, which would split ownership by inode.
+function createOwnershipStore(directory = defaultDirectory()) {
+  directory = path.resolve(directory);
+  function paths(serial) {
+    const key = createHash('sha256').update(serial).digest('hex');
+    return { lock: path.join(directory, `${key}.sqlite`), journal: path.join(directory, `${key}.json`) };
+  }
+  function read(serial) {
+    let value;
+    let fd;
+    try {
+      fd = fs.openSync(paths(serial).journal, 'r');
+      if (fs.fstatSync(fd).size > maxJournalBytes) throw new Error('Device ownership journal exceeds 4 MiB.');
+      const bytes = fs.readFileSync(fd);
+      if (bytes.length > maxJournalBytes) throw new Error('Device ownership journal exceeds 4 MiB.');
+      value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch (error) {
+      if (error.code === 'ENOENT') return null;
+      throw new CommandError('device_ownership_corrupt', 'Cannot read the device ownership journal.', { details: { serial, cause: error.message } });
+    } finally { if (fd !== undefined) fs.closeSync(fd); }
+    if (!['aab.device-ownership/v1', schemaVersion].includes(value?.schemaVersion) || value.serial !== serial || !Array.isArray(value.reservations) || !['owned', 'unresolved', 'idle'].includes(value.phase)
+        || !(value.pending === null || value.pending && typeof value.pending.id === 'string' && typeof value.pending.kind === 'string')) {
+      throw new CommandError('device_ownership_corrupt', 'Invalid device ownership journal.', { details: { serial } });
+    }
+    if (value.schemaVersion === 'aab.device-ownership/v1') {
+      if (Object.hasOwn(value, 'pendingAcknowledgements'))
+        throw new CommandError('device_ownership_corrupt', 'A v1 journal cannot contain v2 acknowledgement obligations.');
+      // Lossless data upgrade: never move the lock or discard an old unknown action.
+      value = { ...value, schemaVersion, pendingAcknowledgements: [] };
+    }
+    const queue = value.pendingAcknowledgements;
+    if (!Array.isArray(queue) || queue.length > acknowledgements.capacity || queue.some(item => !acknowledgements.valid(item, serial))
+      || new Set(queue.map(item => item.pending.id)).size !== queue.length)
+      throw new CommandError('device_ownership_corrupt', 'Invalid pending receipt acknowledgement journal.', { details: { serial } });
+    return value;
+  }
+  function lock(serial) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const { DatabaseSync } = require('node:sqlite');
+    const file = paths(serial).lock;
+    let db;
+    try {
+      db = new DatabaseSync(file);
+      fs.chmodSync(file, 0o600);
+      db.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE');
+    } catch (error) {
+      db?.close();
+      if (error.errcode === 5) return null;
+      throw new CommandError('device_ownership_unavailable', 'Cannot acquire the shared device ownership lock.', { details: { serial, cause: error.message } });
+    }
+    let closed = false;
+    return { close() { if (!closed) { closed = true; try { db.exec('ROLLBACK'); } finally { db.close(); } } } };
+  }
+  function write(serial, value) {
+    const file = paths(serial).journal;
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+      const bytes = JSON.stringify(value) + '\n';
+      if (Buffer.byteLength(bytes) > maxJournalBytes) throw new Error('Device ownership journal exceeds 4 MiB.');
+      fd = fs.openSync(temporary, 'wx', 0o600);
+      fs.writeFileSync(fd, bytes);
+      fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+      fs.renameSync(temporary, file);
+      const parent = fs.openSync(directory, 'r');
+      try { fs.fsyncSync(parent); } finally { fs.closeSync(parent); }
+    } catch (error) {
+      if (fd !== undefined) fs.closeSync(fd);
+      try { fs.unlinkSync(temporary); } catch (failure) { if (failure.code !== 'ENOENT') error.cleanupError = failure.code; }
+      throw new CommandError('device_ownership_unavailable', 'Cannot commit device ownership; no new action is allowed.', { details: { serial, cause: error.message } });
+    }
+  }
+  return { directory, read, lock, write };
+}
+
+module.exports = { createOwnershipStore, defaultDirectory, schemaVersion };