Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Durable, machine-local journal for ONE in-flight snapshot database restore
* (#9725). Its presence is the admission fence: while the file exists, only
* the matching recovery operation may use the database, in this process and
* across restart. The record carries what recovery needs and nothing else —
* the operation id, the admitted dump digest, the ORIGINAL pre-replay sync
* feed positions and the pending stage. No credentials, no copied records.
*
* Stages:
* replaying — published BEFORE the destructive replay. Whether the replay
* committed is unknown until its transactional receipt (a row in
* `restore_receipts` keyed by this id, written inside the replay
* transaction) is inspected.
* repairing — replay committed; schema/migration/sequence/cursor repair is
* pending. Never replays again.
* Completion (or a proven rollback) removes the file and syncs its directory
* before reopening admission.
*/
import { closeSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { randomUUID } from 'node:crypto';
import { z } from 'zod';
import { PATHS } from './paths.js';
import { assertNotRealDataWrite } from './testDataIsolation.js';
export const DATABASE_RESTORE_RECOVERY_FILE = 'database-restore-recovery.json';
export const DATABASE_RESTORE_RECOVERY_STAGES = Object.freeze(['replaying', 'repairing']);
const recordSchema = z.object({
version: z.literal(1),
id: z.string().uuid(),
stage: z.enum(DATABASE_RESTORE_RECOVERY_STAGES),
createdAt: z.string().datetime(),
snapshotId: z.string().min(1).max(255),
dumpSha256: z.string().regex(/^[0-9a-f]{64}$/),
// pg_sequences rows captured before replay; last_value stays a decimal
// string because feed positions exceed Number.MAX_SAFE_INTEGER.
feedPositions: z.array(z.object({
sequencename: z.string().regex(/^[a-z_][a-z0-9_]{0,62}$/),
last_value: z.string().regex(/^-?\d{1,20}$/),
}).strict()).max(256),
}).strict();
export const databaseRestoreRecoveryError = () => Object.assign(
new Error('A committed database restore is awaiting recovery. Finish it from Settings > Backup (or restart PortOS to retry automatically) before using the database.'),
{ status: 503, code: 'DATABASE_RESTORE_RECOVERY' },
);
function syncDirectory(path) {
// Windows does not expose directory fsync through Node.
if (process.platform === 'win32') return;
const fd = openSync(path, 'r');
try { fsyncSync(fd); } finally { closeSync(fd); }
}
function writeDurableExclusive(path, value) {
const fd = openSync(path, 'wx', 0o600);
try {
writeFileSync(fd, JSON.stringify(value, null, 2) + '\n');
fsyncSync(fd);
} finally {
closeSync(fd);
}
}
export function createDatabaseRestoreRecovery(dataDir = PATHS.data) {
const recordPath = join(dataDir, DATABASE_RESTORE_RECOVERY_FILE);
let pendingRelease = null;
const pendingPath = () => join(dataDir, `.database-restore-recovery-${randomUUID()}.pending`);
// A pending directory sync also fences this process. Otherwise anything at the
// path other than a confirmed ENOENT (unreadable, wrong type, damaged)
// keeps ordinary database work closed.
const isFenced = () => {
if (pendingRelease) return true;
try {
lstatSync(recordPath);
return true;
} catch (err) {
return err.code !== 'ENOENT';
}
};
const assertAdmission = () => {
if (isFenced()) throw databaseRestoreRecoveryError();
};
// null when no restore is pending; throws (fails closed) when the record
// exists but cannot be read or validated.
const read = () => {
if (pendingRelease) return recordSchema.parse(pendingRelease);
if (!isFenced()) return null;
try {
if (!lstatSync(recordPath).isFile()) throw databaseRestoreRecoveryError();
return recordSchema.parse(JSON.parse(readFileSync(recordPath, 'utf8')));
} catch {
if (!isFenced()) return null;
throw databaseRestoreRecoveryError();
}
};
// Published before the destructive replay. link() is an atomic no-replace
// publication of already-fsynced bytes, so a second restore can never
// overwrite a pending operation's original feed positions.
const begin = ({ snapshotId, dumpSha256, feedPositions }) => {
assertNotRealDataWrite(recordPath, 'database restore recovery begin');
assertAdmission();
const record = recordSchema.parse({
version: 1, id: randomUUID(), stage: 'replaying', createdAt: new Date().toISOString(),
snapshotId, dumpSha256, feedPositions,
});
const pending = pendingPath();
writeDurableExclusive(pending, record);
try {
linkSync(pending, recordPath);
} catch (err) {
if (err.code === 'EEXIST') throw databaseRestoreRecoveryError();
throw err;
} finally {
unlinkSync(pending);
}
syncDirectory(dataDir);
return record;
};
// Forward-only: replaying -> repairing, for the SAME operation. Identity,
// digest and the original floors are carried over unchanged.
const markCommitted = (id) => {
assertNotRealDataWrite(recordPath, 'database restore recovery commit');
const current = read();
if (!current || current.id !== id) throw databaseRestoreRecoveryError();
if (current.stage === 'repairing') return current;
const next = recordSchema.parse({ ...current, stage: 'repairing' });
const pending = pendingPath();
writeDurableExclusive(pending, next);
renameSync(pending, recordPath);
syncDirectory(dataDir);
return next;
};
// Reopen admission: repair completed, or the replay provably rolled back.
const release = (id) => {
assertNotRealDataWrite(recordPath, 'database restore recovery release');
const current = read();
if (!current || current.id !== id) throw databaseRestoreRecoveryError();
if (!pendingRelease) {
unlinkSync(recordPath);
// Unlink alone is not durable completion. Retain identity and admission
// locally until the directory sync succeeds, including across retries.
pendingRelease = current;
}
syncDirectory(dataDir);
pendingRelease = null;
};
return { path: recordPath, isFenced, assertAdmission, read, begin, markCommitted, release };
}