@north-light/api 0.3.441 → 0.3.442

package/dist/core/fs-utils.d.ts

@@ -27,6 +27,13 @@ export declare function syncDirectory(path: string): void;
  *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
  *  bytes or the new ones and never a truncated file mid-write. */
 export declare function atomicWriteText(path: string, content: string | Uint8Array, opts?: AtomicWriteOptions): void;
+/** Publish `path` with `content` so it is never observable empty or partial, and
+ *  never replaces an existing file. The bytes reach stable storage under a
+ *  temporary name first; a hard link then makes them appear at `path` in one
+ *  step and fails with EEXIST if another initializer won. The containing
+ *  directory is fsynced so the new entry survives a volume handoff or power loss.
+ *  Returns false when `path` already existed. */
+export declare function publishFileExclusive(path: string, content: string, mode: number): boolean;
 /** Fsync every file and directory under `root` (and `root` itself), so a tree about to be renamed into place
  *  reaches stable storage before the rename can. */
 export declare function syncTree(root: string): void;

package/dist/core/fs-utils.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, closeSync, fsyncSync, openSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, realpathSync, closeSync, fsyncSync, openSync, linkSync, unlinkSync, writeSync, } from 'node:fs';
 import { dirname, join, relative, sep } from 'node:path';
 import { homedir, platform } from 'node:os';
 /** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
@@ -80,6 +80,45 @@ export function atomicWriteText(path, content, opts) {
             rmSync(temp, { force: true });
     }
 }
+/** Publish `path` with `content` so it is never observable empty or partial, and
+ *  never replaces an existing file. The bytes reach stable storage under a
+ *  temporary name first; a hard link then makes them appear at `path` in one
+ *  step and fails with EEXIST if another initializer won. The containing
+ *  directory is fsynced so the new entry survives a volume handoff or power loss.
+ *  Returns false when `path` already existed. */
+export function publishFileExclusive(path, content, mode) {
+    const temporary = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    const fd = openSync(temporary, 'wx', mode);
+    try {
+        try {
+            const bytes = Buffer.from(content, 'utf8');
+            for (let offset = 0; offset < bytes.length;)
+                offset += writeSync(fd, bytes, offset, bytes.length - offset);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            linkSync(temporary, path);
+        }
+        catch (error) {
+            // No in-place fallback for a filesystem without hard links: creating the final name before its
+            // bytes are durable is exactly the empty marker this exists to prevent, so that fails loudly.
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+        syncDirectory(dirname(path));
+        return true;
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch { /* already gone */ }
+    }
+}
 /** Fsync every file and directory under `root` (and `root` itself), so a tree about to be renamed into place
  *  reaches stable storage before the rename can. */
 export function syncTree(root) {

package/dist/core/layout.d.ts

@@ -31,6 +31,14 @@ export declare function cronFolder(app: string, cronId: string): string;
  *  and the terminal wherever a sandbox exists, keeps its own app home. Callers
  *  keep `PI_CODING_AGENT_DIR` in the app home either way. */
 export declare function appProcessHome(app: string): string;
+/** The marker's byte length and an escaped, truncated preview, safe to print: a
+ *  corrupt marker (empty, truncated, NUL-filled by a lost write) is otherwise
+ *  indistinguishable from an intentional newer layout in a crash log. */
+export declare function describeLayoutMarker(bytes: Uint8Array): string;
+/** Refuse any marker other than the supported version. A non-matching marker is
+ *  never rewritten: an empty or damaged one means the volume lost a write, and
+ *  stamping the current version over it would assert a layout nobody verified. */
+export declare function assertSupportedLayoutMarker(path: string): void;
 /** A missing version on an occupied volume is never initialized by daemon startup. */
 export declare function layoutNeedsMigration(): boolean;
 export declare function initializeEmptyLayout(): void;

package/dist/core/layout.js

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir, userInfo } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { envHomeOverride } from '../shared/env.js';
 import { readConfig } from './config.js';
+import { publishFileExclusive, syncDirectory } from './fs-utils.js';
 export const LAYOUT_VERSION = '1';
 /** CRTR_HOME names the volume root, not the canvas records directory. */
 export function layoutRoot() {
@@ -81,13 +82,29 @@ export function appProcessHome(app) {
         return space.home;
     return basename(space.root) === 'terminal' ? userFilesRoot() : space.home;
 }
+/** The marker's byte length and an escaped, truncated preview, safe to print: a
+ *  corrupt marker (empty, truncated, NUL-filled by a lost write) is otherwise
+ *  indistinguishable from an intentional newer layout in a crash log. */
+export function describeLayoutMarker(bytes) {
+    const preview = Array.from(bytes.subarray(0, 32), (byte) => byte === 0x5c ? '\\\\' : byte === 0x22 ? '\\"' : byte === 0x0a ? '\\n' : byte === 0x0d ? '\\r' : byte === 0x09 ? '\\t'
+        : byte >= 0x20 && byte < 0x7f ? String.fromCharCode(byte) : `\\x${byte.toString(16).padStart(2, '0')}`).join('');
+    return `${bytes.length} bytes, preview "${preview}"${bytes.length > 32 ? '…' : ''}`;
+}
+/** Refuse any marker other than the supported version. A non-matching marker is
+ *  never rewritten: an empty or damaged one means the volume lost a write, and
+ *  stamping the current version over it would assert a layout nobody verified. */
+export function assertSupportedLayoutMarker(path) {
+    const bytes = readFileSync(path);
+    if (bytes.toString('utf8').trim() !== LAYOUT_VERSION) {
+        throw new Error(`unsupported runtime layout version: ${path} holds ${describeLayoutMarker(bytes)}; expected "${LAYOUT_VERSION}"`);
+    }
+}
 /** A missing version on an occupied volume is never initialized by daemon startup. */
 export function layoutNeedsMigration() {
     if (process.env['CRTR_LAYOUT_REFUSE'] === '1')
         return true;
     if (existsSync(layoutVersionFile())) {
-        if (readFileSync(layoutVersionFile(), 'utf8').trim() !== LAYOUT_VERSION)
-            throw new Error('unsupported runtime layout version');
+        assertSupportedLayoutMarker(layoutVersionFile());
         return false;
     }
     const root = layoutRoot();
@@ -102,11 +119,22 @@ export function layoutNeedsMigration() {
 export function initializeEmptyLayout() {
     if (layoutNeedsMigration())
         throw new Error('layout_migration_required');
-    for (const dir of [runtimeRoot(), userRoot(), appsRoot(), secretsDir()])
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    for (const dir of [runtimeRoot(), userRoot(), appsRoot(), secretsDir()]) {
+        // mkdir returns the first directory it had to create; every entry from there down to
+        // `dir` is new, and so is the entry for the first one in its (existing) parent.
+        const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (created === undefined)
+            continue;
+        for (let entry = dir;; entry = dirname(entry)) {
+            syncDirectory(entry);
+            if (entry === created)
+                break;
+        }
+        syncDirectory(dirname(created));
+    }
     mkdirSync(socketDir(), { recursive: true, mode: 0o755 });
     if (process.platform === 'linux' && (statSync(socketDir()).mode & 0o777) !== 0o755)
         throw new Error('launcher socket directory must be mode 0755');
     if (!existsSync(layoutVersionFile()))
-        writeFileSync(layoutVersionFile(), `${LAYOUT_VERSION}\n`, { flag: 'wx', mode: 0o600 });
+        publishFileExclusive(layoutVersionFile(), `${LAYOUT_VERSION}\n`, 0o600);
 }

package/dist/core/locked-file.js

@@ -15,6 +15,7 @@
 import { chmodSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, closeSync } from 'node:fs';
 import { dirname } from 'node:path';
 import lockfile from 'proper-lockfile';
+import { publishFileExclusive } from './fs-utils.js';
 const WRITE_OPTIONS = { encoding: 'utf-8', mode: 0o600 };
 // proper-lockfile decides a held lock is abandoned when its lockdir mtime is older than
 // the acquirer's `stale`, and refreshes the mtime on the holder's `update` timer. The holder
@@ -39,7 +40,9 @@ export class LockedJsonFile {
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true, mode: 0o700 });
         if (!existsSync(this.path)) {
-            writeFileSync(this.path, this.initialContent, WRITE_OPTIONS);
+            // Published whole and exclusively: another process may be creating it too, and a
+            // reader (or a lost write) must never see the empty file a plain create leaves.
+            publishFileExclusive(this.path, this.initialContent, 0o600);
             chmodSync(this.path, 0o600);
         }
     }

package/dist/core/scoped-state/db.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import lockfile from 'proper-lockfile';
 import { CONFIG_FILE, PROFILE_DIR, STATE_FILE } from '../../types.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
+import { syncDirectory, syncFile } from '../fs-utils.js';
 import { layoutNeedsMigration } from '../layout.js';
 import { providerStore, projectStore, userStore } from './paths.js';
 import { createScopedSchema, ensureProviderModelCooldowns, PROVIDER_SCHEMA_VERSION, SCOPED_SCHEMA_VERSION } from './schema.js';
@@ -218,6 +219,11 @@ export function createScopedStore(store, create) {
         secure(store.path);
         db.close();
     }
+    // Closing checkpoints the WAL into the database file. Force the finished file and its
+    // directory entry to stable storage so a volume handed off right after first boot never
+    // comes back with the empty, schema-less file that `scoped SQL store is uninitialized` names.
+    syncFile(store.path);
+    syncDirectory(store.root);
 }
 export function withScopedWrite(store, run) {
     const db = openScopedStore(store);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.441",
+  "version": "0.3.442",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",