@hraness/sponge 0.2.6 → 0.3.0

package/dist/src/service/launch-agent.js

@@ -4,86 +4,201 @@ import { homedir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { realpathSync, readdirSync, lstatSync, readFileSync, existsSync, unlinkSync } from 'node:fs';
-import { StoreError } from '../store/types.js';
-import { digest, safeDirectory, regularFile, syncDirectory } from '../store/files.js';
+import { safeDirectory, regularFile } from '../store/files.js';
+import { sha256 } from '../util/hash.js';
+import { syncDirectory } from '../util/fsync.js';
 import { describe, exact, readExact, openRead, writePrivateExclusive } from '../portability/files.js';
 import { fstatSync, closeSync } from 'node:fs';
 import { identityAlive } from '../worker/identity.js';
 import { recoverServiceLifetime } from './lifetime.js';
+import { SpongeError } from '../errors.js';
 const exec = promisify(execFile);
-export function serviceEnvironment(version) { return { platform: process.platform, uid: process.getuid?.() ?? -1, home: realpathSync(homedir()), node: realpathSync(process.execPath), cli: realpathSync(process.argv[1]), version, launchctl: async (args) => { try {
-        const r = await exec('/bin/launchctl', args, { timeout: 30000, maxBuffer: 65536, env: { HOME: homedir(), PATH: '/usr/bin:/bin', LANG: 'en_US.UTF-8' } });
-        return { code: 0, stdout: r.stdout };
+export function serviceEnvironment(version) {
+    return {
+        platform: process.platform,
+        uid: process.getuid?.() ?? -1,
+        home: realpathSync(homedir()),
+        node: realpathSync(process.execPath),
+        cli: realpathSync(process.argv[1]),
+        version,
+        launchctl: async (args) => {
+            try {
+                const r = await exec('/bin/launchctl', args, {
+                    timeout: 30000,
+                    maxBuffer: 65536,
+                    env: { HOME: homedir(), PATH: '/usr/bin:/bin', LANG: 'en_US.UTF-8' },
+                });
+                return { code: 0, stdout: r.stdout };
+            }
+            catch (error) {
+                const e = error;
+                if (typeof e.code === 'number')
+                    return { code: e.code, stdout: e.stdout ?? '' };
+                throw new SpongeError('unavailable');
+            }
+        },
+        alive: identityAlive,
+        pause: (ms) => new Promise((r) => setTimeout(r, ms)),
+    };
+}
+function paths(store, env) {
+    if (env.platform !== 'darwin')
+        throw new SpongeError('unavailable');
+    if (!Number.isSafeInteger(env.uid) || env.uid <= 0)
+        throw new SpongeError('invalid-input');
+    const root = join(store.root, 'runtime', 'service'), agents = join(env.home, 'Library', 'LaunchAgents');
+    const label = 'computer.sponge.worker.' + sha256(store.root).slice(0, 20);
+    return {
+        root,
+        agents,
+        label,
+        log: join(root, 'launchd.log'),
+        record: join(root, 'installation.json'),
+        plist: join(agents, label + '.plist'),
+        target: `gui/${env.uid}/${label}`,
+    };
+}
+function readJson(path) {
+    const fd = openRead(path);
+    try {
+        const size = fstatSync(fd).size;
+        if (size > 4 * 1024 * 1024)
+            throw new SpongeError('limit-exceeded');
+        return JSON.parse(readExact(fd, size).toString());
     }
-    catch (error) {
-        const e = error;
-        if (typeof e.code === 'number')
-            return { code: e.code, stdout: e.stdout ?? '' };
-        throw new StoreError('unavailable');
-    } }, alive: identityAlive, pause: ms => new Promise(r => setTimeout(r, ms)) }; }
-function paths(store, env) { if (env.platform !== 'darwin')
-    throw new StoreError('unavailable'); if (!Number.isSafeInteger(env.uid) || env.uid <= 0)
-    throw new StoreError('invalid-input'); const root = join(store.root, 'runtime', 'service'), agents = join(env.home, 'Library', 'LaunchAgents'); const label = 'computer.sponge.worker.' + digest(store.root).slice(0, 20); return { root, agents, label, record: join(root, 'installation.json'), plist: join(agents, label + '.plist'), target: `gui/${env.uid}/${label}` }; }
-function readJson(path) { const fd = openRead(path); try {
-    const size = fstatSync(fd).size;
-    if (size > 4 * 1024 * 1024)
-        throw new StoreError('limit-exceeded');
-    return JSON.parse(readExact(fd, size).toString());
-}
-finally {
-    closeSync(fd);
-} }
+    finally {
+        closeSync(fd);
+    }
+}
 function installation(store, env) {
     const p = paths(store, env);
     if (!existsSync(p.record))
         return null;
-    const r = exact(readJson(p.record), ['language', 'schemaVersion', 'id', 'label', 'uid', 'version', 'node', 'cli', 'library', 'plist', 'plistHash', 'launcher', 'launcherHash', 'pins']);
-    if ((r.language !== null && r.language !== 'en') || r.schemaVersion !== 1 || typeof r.id !== 'string' || !/^[a-f0-9-]{36}$/u.test(r.id) || r.label !== p.label || r.uid !== env.uid || r.library !== store.root || r.plist !== p.plist || typeof r.version !== 'string' || !/^\d+\.\d+\.\d+$/u.test(r.version) || typeof r.node !== 'string' || typeof r.cli !== 'string' || typeof r.launcher !== 'string' || typeof r.plistHash !== 'string' || typeof r.launcherHash !== 'string' || !Array.isArray(r.pins) || r.pins.length > 10000)
-        throw new StoreError('integrity');
-    if (r.launcher !== join(p.root, 'launchers', r.version + '-' + r.id, 'run.mjs') || !/^\/[\s\S]+/u.test(r.node) || !/^\/[\s\S]+/u.test(r.cli))
-        throw new StoreError('integrity');
+    const r = exact(readJson(p.record), [
+        'language',
+        'schemaVersion',
+        'id',
+        'label',
+        'uid',
+        'version',
+        'node',
+        'cli',
+        'library',
+        'plist',
+        'plistHash',
+        'launcher',
+        'launcherHash',
+        'pins',
+    ]);
+    if ((r.language !== null && r.language !== 'en') ||
+        r.schemaVersion !== 1 ||
+        typeof r.id !== 'string' ||
+        !/^[a-f0-9-]{36}$/u.test(r.id) ||
+        r.label !== p.label ||
+        r.uid !== env.uid ||
+        r.library !== store.root ||
+        r.plist !== p.plist ||
+        typeof r.version !== 'string' ||
+        !/^\d+\.\d+\.\d+$/u.test(r.version) ||
+        typeof r.node !== 'string' ||
+        typeof r.cli !== 'string' ||
+        typeof r.launcher !== 'string' ||
+        typeof r.plistHash !== 'string' ||
+        typeof r.launcherHash !== 'string' ||
+        !Array.isArray(r.pins) ||
+        r.pins.length > 10000)
+        throw new SpongeError('integrity');
+    if (r.launcher !== join(p.root, 'launchers', r.version + '-' + r.id, 'run.mjs') ||
+        !/^\/[\s\S]+/u.test(r.node) ||
+        !/^\/[\s\S]+/u.test(r.cli))
+        throw new SpongeError('integrity');
     for (const pin of r.pins) {
         const f = exact(pin, ['path', 'bytes', 'sha256']);
-        if (typeof f.path !== 'string' || resolve(f.path) !== f.path || typeof f.bytes !== 'number' || !Number.isSafeInteger(f.bytes) || f.bytes < 0 || typeof f.sha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(f.sha256))
-            throw new StoreError('integrity');
+        if (typeof f.path !== 'string' ||
+            resolve(f.path) !== f.path ||
+            typeof f.bytes !== 'number' ||
+            !Number.isSafeInteger(f.bytes) ||
+            f.bytes < 0 ||
+            typeof f.sha256 !== 'string' ||
+            !/^[a-f0-9]{64}$/u.test(f.sha256))
+            throw new SpongeError('integrity');
     }
     return r;
 }
-function verifyOwnedFiles(record) { for (const [path, sha] of [[record.plist, record.plistHash], [record.launcher, record.launcherHash]]) {
-    if (describe(path, path, 4 * 1024 * 1024).sha256 !== sha)
-        throw new StoreError('integrity');
-} }
-function current(record) { try {
-    return record.pins.every(p => { const r = describe(p.path, p.path, 512 * 1024 ** 2); return r.bytes === p.bytes && r.sha256 === p.sha256; });
-}
-catch {
-    return false;
-} }
-function xml(value) { return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;'); }
-export function agentPlist(record) { return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${xml(record.label)}</string><key>ProgramArguments</key><array><string>${xml(record.node)}</string><string>${xml(record.launcher)}</string></array><key>RunAtLoad</key><true/><key>StartInterval</key><integer>30</integer><key>ProcessType</key><string>Background</string><key>ExitTimeOut</key><integer>60</integer><key>Umask</key><integer>63</integer><key>EnvironmentVariables</key><dict><key>PATH</key><string>/usr/bin:/bin</string><key>LANG</key><string>en_US.UTF-8</string><key>HRANESS_NO_UPDATE</key><string>1</string></dict><key>StandardOutPath</key><string>/dev/null</string><key>StandardErrorPath</key><string>/dev/null</string></dict></plist>\n`; }
+function verifyOwnedFiles(record) {
+    for (const [path, sha] of [
+        [record.plist, record.plistHash],
+        [record.launcher, record.launcherHash],
+    ]) {
+        if (describe(path, path, 4 * 1024 * 1024).sha256 !== sha)
+            throw new SpongeError('integrity');
+    }
+}
+function pinCurrent(p) {
+    try {
+        const r = describe(p.path, p.path, 512 * 1024 ** 2);
+        return r.bytes === p.bytes && r.sha256 === p.sha256;
+    }
+    catch {
+        return false;
+    }
+}
+function current(record) {
+    return record.pins.every(pinCurrent);
+}
+/** Why the registered worker no longer matches this installed Sponge. Any entry means it cannot (or should not) start;
+ * `worker install` repairs every one of them by reinstalling from the current package. */
+function drift(record, env, log) {
+    const result = new Set();
+    for (const pin of record.pins)
+        if (!pinCurrent(pin))
+            result.add(pin.path === record.node ? 'node-changed' : 'package-changed');
+    if (record.version !== env.version)
+        result.add('version-changed');
+    if (record.cli !== env.cli)
+        result.add('cli-moved');
+    if (sha256(agentPlist({ ...record, log })) !== record.plistHash)
+        result.add('plist-outdated');
+    return [...result];
+}
+const driftRepair = 'Run sponge worker install to reinstall the worker for the current installed package and Node.';
+function xml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+export function agentPlist(record) {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${xml(record.label)}</string><key>ProgramArguments</key><array><string>${xml(record.node)}</string><string>${xml(record.launcher)}</string></array><key>RunAtLoad</key><true/><key>StartInterval</key><integer>30</integer><key>ProcessType</key><string>Background</string><key>ExitTimeOut</key><integer>60</integer><key>Umask</key><integer>63</integer><key>EnvironmentVariables</key><dict><key>PATH</key><string>/usr/bin:/bin</string><key>LANG</key><string>en_US.UTF-8</string><key>HRANESS_NO_UPDATE</key><string>1</string></dict><key>StandardOutPath</key><string>${xml(record.log)}</string><key>StandardErrorPath</key><string>${xml(record.log)}</string></dict></plist>\n`;
+}
 function pinPackage(env) {
     const cli = realpathSync(env.cli), root = dirname(dirname(cli));
     if (cli !== join(root, 'bin', 'sponge.js'))
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
     const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
     if (pkg.name !== '@hraness/sponge' || pkg.version !== env.version || !/^\d+\.\d+\.\d+$/u.test(env.version))
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
     const paths = [env.node, cli, join(root, 'package.json')];
     let total = 0;
-    const visit = (directory) => { safeDirectory(directory); for (const name of readdirSync(directory).sort()) {
-        const path = join(directory, name), stat = lstatSync(path);
-        if (stat.isSymbolicLink())
-            throw new StoreError('integrity');
-        if (stat.isDirectory())
-            visit(path);
-        else {
-            regularFile(path);
-            if (paths.length >= 10000 || total + stat.size > 64 * 1024 * 1024)
-                throw new StoreError('limit-exceeded');
-            total += stat.size;
-            paths.push(path);
+    const visit = (directory) => {
+        safeDirectory(directory);
+        for (const name of readdirSync(directory).sort()) {
+            const path = join(directory, name), stat = lstatSync(path);
+            if (stat.isSymbolicLink())
+                throw new SpongeError('integrity');
+            if (stat.isDirectory())
+                visit(path);
+            else {
+                regularFile(path);
+                if (paths.length >= 10000 || total + stat.size > 64 * 1024 * 1024)
+                    throw new SpongeError('limit-exceeded');
+                total += stat.size;
+                paths.push(path);
+            }
         }
-    } };
+    };
     visit(join(root, 'dist'));
     const catalog = join(root, 'native', 'runtime-manifest.json');
     let catalogPresent = false;
@@ -99,44 +214,98 @@ function pinPackage(env) {
         safeDirectory(dirname(catalog));
         regularFile(catalog);
         if (lstatSync(catalog).size > 16384 || paths.length >= 10000)
-            throw new StoreError('limit-exceeded');
+            throw new SpongeError('limit-exceeded');
         paths.push(catalog);
     }
-    return paths.map(path => { const record = describe(path, path, 512 * 1024 ** 2); return { path, bytes: record.bytes, sha256: record.sha256 }; });
-}
-function launcher(record) { return `// Sponge pinned service launcher. Reinstall the worker after upgrading its package.\nimport {openSync,readSync,closeSync,fstatSync,constants} from 'node:fs';\nimport {createHash} from 'node:crypto';\nimport {pathToFileURL} from 'node:url';\nconst pins=${JSON.stringify(record.pins)};\nfor(const p of pins){let fd;try{fd=openSync(p.path,constants.O_RDONLY|constants.O_NOFOLLOW);const s=fstatSync(fd);if(!s.isFile()||s.nlink!==1||s.size!==p.bytes)throw Error();const h=createHash('sha256'),b=Buffer.alloc(65536);let n;while((n=readSync(fd,b,0,b.length,null)))h.update(b.subarray(0,n));if(h.digest('hex')!==p.sha256)throw Error();}catch{process.stderr.write('Sponge worker installation changed. Run sponge worker uninstall, then sponge worker install.\\n');process.exit(78);}finally{if(fd!==undefined)closeSync(fd);}}\nprocess.env.SPONGE_SERVICE_INSTALLATION=${JSON.stringify(record.id)};process.env.HRANESS_NO_UPDATE='1';process.argv=[process.execPath,${JSON.stringify(record.cli)},'--library',${JSON.stringify(record.library)},'worker','serve',...${JSON.stringify(record.language ? ['--language', record.language] : [])}];\nawait import(pathToFileURL(${JSON.stringify(record.cli)}).href);\n`; }
-async function loaded(env, target) { const result = await env.launchctl(['print', target]); if (result.code === 0)
-    return true; if (result.code === 113)
-    return false; throw new StoreError('unavailable'); }
-export async function serviceStatus(store, env) { const p = paths(store, env), record = installation(store, env); if (!record)
-    return { installed: false }; verifyOwnedFiles(record); const stale = !current(record); return { installed: true, loaded: await loaded(env, p.target), version: record.version, language: record.language, stale, ...(stale ? { repair: 'Run sponge worker uninstall, then sponge worker install from the current installed package.' } : {}) }; }
+    return paths.map((path) => {
+        const record = describe(path, path, 512 * 1024 ** 2);
+        return { path, bytes: record.bytes, sha256: record.sha256 };
+    });
+}
+function launcher(record) {
+    return `// Sponge pinned service launcher. Reinstall the worker after upgrading its package.\nimport {openSync,readSync,closeSync,fstatSync,lstatSync,renameSync,constants} from 'node:fs';\nimport {createHash} from 'node:crypto';\nimport {pathToFileURL} from 'node:url';\nconst log=${JSON.stringify(record.log)};\ntry{const s=lstatSync(log);if(s.isFile()&&s.size>=1048576)renameSync(log,log+'.1');}catch{}\nconst pins=${JSON.stringify(record.pins)};\nfor(const p of pins){let fd;try{fd=openSync(p.path,constants.O_RDONLY|constants.O_NOFOLLOW);const s=fstatSync(fd);if(!s.isFile()||s.nlink!==1||s.size!==p.bytes)throw Error();const h=createHash('sha256'),b=Buffer.alloc(65536);let n;while((n=readSync(fd,b,0,b.length,null)))h.update(b.subarray(0,n));if(h.digest('hex')!==p.sha256)throw Error();}catch{process.stderr.write(new Date().toISOString()+' Sponge worker installation changed: '+(p===pins[0]?'Node executable':'package files')+'. Run sponge worker install to repair.\\n');process.exit(78);}finally{if(fd!==undefined)closeSync(fd);}}\nprocess.env.SPONGE_SERVICE_INSTALLATION=${JSON.stringify(record.id)};process.env.HRANESS_NO_UPDATE='1';process.argv=[process.execPath,${JSON.stringify(record.cli)},'--library',${JSON.stringify(record.library)},'worker','serve',...${JSON.stringify(record.language ? ['--language', record.language] : [])}];\nawait import(pathToFileURL(${JSON.stringify(record.cli)}).href);\n`;
+}
+async function loaded(env, target) {
+    const result = await env.launchctl(['print', target]);
+    if (result.code === 0)
+        return true;
+    if (result.code === 113)
+        return false;
+    throw new SpongeError('unavailable');
+}
+async function launchState(env, target) {
+    const result = await env.launchctl(['print', target]);
+    if (result.code === 113)
+        return { loaded: false };
+    if (result.code !== 0)
+        throw new SpongeError('unavailable');
+    const exit = /^\s*last exit code = (-?\d{1,5})\b/mu.exec(result.stdout);
+    return { loaded: true, ...(exit ? { lastExit: Number(exit[1]) } : {}) };
+}
+export async function serviceStatus(store, env) {
+    const p = paths(store, env), record = installation(store, env);
+    if (!record)
+        return { installed: false };
+    verifyOwnedFiles(record);
+    const found = drift(record, env, p.log);
+    return {
+        installed: true,
+        ...(await launchState(env, p.target)),
+        version: record.version,
+        language: record.language,
+        stale: found.length > 0,
+        ...(found.length ? { drift: found, repair: driftRepair } : {}),
+        log: p.log,
+    };
+}
 export async function installService(store, env, options = {}) {
     if (options.language !== undefined && options.language !== 'en')
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
     const p = paths(store, env);
     safeDirectory(p.root, true);
     const previous = installation(store, env);
+    // Idempotent: a current registration is kept (and reloaded if it was booted out); a drifted one is uninstalled through
+    // the verified path (a foreign plist still fails closed) and installed again from the current package and Node.
     if (previous) {
         if (previous.language !== (options.language ?? null))
-            throw new StoreError('invalid-input');
-        return serviceStatus(store, env);
+            throw new SpongeError('invalid-input');
+        verifyOwnedFiles(previous);
+        if (!drift(previous, env, p.log).length) {
+            if (!(await loaded(env, p.target)) && (await env.launchctl(['bootstrap', `gui/${env.uid}`, p.plist])).code !== 0)
+                throw new SpongeError('unavailable');
+            return serviceStatus(store, env);
+        }
+        await uninstallService(store, env);
     }
     if (await loaded(env, p.target))
-        throw new StoreError('owner-busy');
+        throw new SpongeError('owner-busy');
     safeDirectory(p.agents, true);
     if (existsSync(p.plist))
-        throw new StoreError('integrity');
+        throw new SpongeError('integrity');
     const id = randomUUID(), pins = pinPackage(env), launcherPath = join(p.root, 'launchers', env.version + '-' + id, 'run.mjs');
     safeDirectory(dirname(launcherPath), true);
-    const base = { language: options.language ?? null, schemaVersion: 1, id, label: p.label, uid: env.uid, version: env.version, node: env.node, cli: env.cli, library: store.root, plist: p.plist, launcher: launcherPath, pins };
-    const code = launcher(base), plist = agentPlist(base);
+    const base = {
+        language: options.language ?? null,
+        schemaVersion: 1,
+        id,
+        label: p.label,
+        uid: env.uid,
+        version: env.version,
+        node: env.node,
+        cli: env.cli,
+        library: store.root,
+        plist: p.plist,
+        launcher: launcherPath,
+        pins,
+    };
+    const code = launcher({ ...base, log: p.log }), plist = agentPlist({ ...base, log: p.log });
     writePrivateExclusive(launcherPath, code);
     writePrivateExclusive(p.plist, plist);
-    const record = { ...base, launcherHash: digest(code), plistHash: digest(plist) };
+    const record = { ...base, launcherHash: sha256(code), plistHash: sha256(plist) };
     writePrivateExclusive(p.record, JSON.stringify(record) + '\n');
     const result = await env.launchctl(['bootstrap', `gui/${env.uid}`, p.plist]);
     if (result.code !== 0)
-        throw new StoreError('unavailable');
+        throw new SpongeError('unavailable');
     return serviceStatus(store, env);
 }
 export async function uninstallService(store, env) {
@@ -147,18 +316,32 @@ export async function uninstallService(store, env) {
     if (await loaded(env, p.target)) {
         const result = await env.launchctl(['bootout', p.target]);
         if (result.code !== 0 && result.code !== 113)
-            throw new StoreError('unavailable');
+            throw new SpongeError('unavailable');
     }
     for (let attempt = 0; attempt < 50; attempt++) {
         let alive = false;
         const run = join(p.root, 'run.json');
         if (existsSync(run)) {
             const r = exact(readJson(run), ['schemaVersion', 'installationId', 'runId', 'identity', 'state']), identity = exact(r.identity, ['pid', 'uid', 'started']);
-            if (r.schemaVersion !== 1 || r.installationId !== record.id || typeof r.runId !== 'string' || !/^[a-f0-9-]{36}$/u.test(r.runId) || !['running', 'stopped', 'cleanup-required'].includes(String(r.state)) || !Number.isSafeInteger(identity.pid) || Number(identity.pid) <= 1 || identity.uid !== env.uid || typeof identity.started !== 'string' || !identity.started || identity.started.length > 256)
-                throw new StoreError('integrity');
+            if (r.schemaVersion !== 1 ||
+                r.installationId !== record.id ||
+                typeof r.runId !== 'string' ||
+                !/^[a-f0-9-]{36}$/u.test(r.runId) ||
+                !['running', 'stopped', 'cleanup-required'].includes(String(r.state)) ||
+                !Number.isSafeInteger(identity.pid) ||
+                Number(identity.pid) <= 1 ||
+                identity.uid !== env.uid ||
+                typeof identity.started !== 'string' ||
+                !identity.started ||
+                identity.started.length > 256)
+                throw new SpongeError('integrity');
             alive = await env.alive(identity);
         }
-        if (!await loaded(env, p.target) && !alive && store.ownerSnapshot() === null && store.pendingCleanupCount() === 0 && await recoverServiceLifetime(store, record.id, env.alive)) {
+        if (!(await loaded(env, p.target)) &&
+            !alive &&
+            store.queue.ownerSnapshot() === null &&
+            store.queue.pendingCleanup() === 0 &&
+            (await recoverServiceLifetime(store, record.id, env.alive))) {
             verifyOwnedFiles(record);
             unlinkSync(record.plist);
             unlinkSync(record.launcher);
@@ -172,8 +355,14 @@ export async function uninstallService(store, env) {
         }
         await env.pause(100);
     }
-    throw Object.assign(new StoreError('owner-busy'), { reason: 'worker-cleanup-required' });
+    throw Object.assign(new SpongeError('owner-busy'), { reason: 'worker-cleanup-required' });
+}
+export function installedServiceId(store, env) {
+    const record = installation(store, env);
+    if (!record || process.env.SPONGE_SERVICE_INSTALLATION !== record.id)
+        throw new SpongeError('invalid-input');
+    verifyOwnedFiles(record);
+    if (!current(record))
+        throw new SpongeError('unavailable');
+    return record.id;
 }
-export function installedServiceId(store, env) { const record = installation(store, env); if (!record || process.env.SPONGE_SERVICE_INSTALLATION !== record.id)
-    throw new StoreError('invalid-input'); verifyOwnedFiles(record); if (!current(record))
-    throw new StoreError('unavailable'); return record.id; }

package/dist/src/service/lifetime.js

@@ -1,20 +1,46 @@
 import { join } from 'node:path';
 import { lstat, link, unlink } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
-import { readJournal, writeJournal, syncDir } from '../worker/journal.js';
-import { StoreError } from '../store/index.js';
-const pending = () => new StoreError('owner-busy');
-function id(value) { return typeof value === 'string' && /^[a-f0-9-]{36}$/u.test(value); }
-async function same(a, b) { const [x, y] = await Promise.all([lstat(a), lstat(b)]); if (!x.isFile() || x.isSymbolicLink() || !y.isFile() || y.isSymbolicLink() || x.dev !== y.dev || x.ino !== y.ino)
-    throw pending(); }
-async function read(path) { const r = await readJournal(path); if (!r || Object.keys(r).sort().join(',') !== 'id,identity,installationId,schemaVersion' || r.schemaVersion !== 1 || !id(r.id) || !id(r.installationId) || !r.identity || Object.keys(r.identity).sort().join(',') !== 'pid,started,uid' || !Number.isSafeInteger(r.identity.pid) || r.identity.pid <= 1 || !Number.isSafeInteger(r.identity.uid) || r.identity.uid < 0 || typeof r.identity.started !== 'string' || !r.identity.started || r.identity.started.length > 256)
-    throw pending(); return r; }
+import { readJournal, writeJournal } from '../worker/journal.js';
+import { syncDirectoryAsync } from '../util/fsync.js';
+import { exactKeys } from '../util/exact.js';
+import { SpongeError } from '../errors.js';
+const pending = () => new SpongeError('owner-busy');
+function id(value) {
+    return typeof value === 'string' && /^[a-f0-9-]{36}$/u.test(value);
+}
+async function same(a, b) {
+    const [x, y] = await Promise.all([lstat(a), lstat(b)]).catch((error) => {
+        if (error.code === 'ENOENT')
+            throw pending();
+        throw error;
+    });
+    if (!x.isFile() || x.isSymbolicLink() || !y.isFile() || y.isSymbolicLink() || x.dev !== y.dev || x.ino !== y.ino)
+        throw pending();
+}
+async function read(path) {
+    const busy = () => {
+        throw pending();
+    }, r = exactKeys(await readJournal(path), ['id', 'identity', 'installationId', 'schemaVersion'], busy), p = exactKeys(r.identity, ['pid', 'started', 'uid'], busy);
+    if (r.schemaVersion !== 1 ||
+        !id(r.id) ||
+        !id(r.installationId) ||
+        !Number.isSafeInteger(p.pid) ||
+        p.pid <= 1 ||
+        !Number.isSafeInteger(p.uid) ||
+        p.uid < 0 ||
+        typeof p.started !== 'string' ||
+        !p.started ||
+        p.started.length > 256)
+        throw pending();
+    return r;
+}
 export async function acquireServiceLifetime(root, installationId, identity) {
     const value = { schemaVersion: 1, id: randomUUID(), installationId, identity }, file = join(root, `lifetime-${value.id}.json`), lock = join(root, 'lifetime.lock');
     await writeJournal(file, value);
     try {
         await link(file, lock);
-        await syncDir(root);
+        await syncDirectoryAsync(root);
     }
     catch (error) {
         await unlink(file);
@@ -22,7 +48,14 @@ export async function acquireServiceLifetime(root, installationId, identity) {
             throw pending();
         throw error;
     }
-    return { release: async () => { await same(file, lock); await unlink(lock); await unlink(file); await syncDir(root); } };
+    return {
+        release: async () => {
+            await same(file, lock);
+            await unlink(lock);
+            await unlink(file);
+            await syncDirectoryAsync(root);
+        },
+    };
 }
 /** Called only after bootout or a failed prior run; never signal a recorded PID. */
 export async function recoverServiceLifetime(store, installationId, alive) {
@@ -36,7 +69,7 @@ export async function recoverServiceLifetime(store, installationId, alive) {
             return true;
         throw error;
     }
-    if (value.installationId !== installationId || await alive(value.identity))
+    if (value.installationId !== installationId || (await alive(value.identity)))
         return false;
     const file = join(root, `lifetime-${value.id}.json`), guard = join(root, 'lifetime-recovery.lock');
     await same(file, lock);
@@ -50,10 +83,10 @@ export async function recoverServiceLifetime(store, installationId, alive) {
     }
     try {
         await same(file, lock);
-        if (await alive(value.identity) || store.ownerSnapshot() !== null || store.pendingCleanupCount() > 0)
+        if ((await alive(value.identity)) || store.queue.ownerSnapshot() !== null || store.queue.pendingCleanup() > 0)
             return false;
         await unlink(lock);
-        await syncDir(root);
+        await syncDirectoryAsync(root);
         return true;
     }
     finally {
@@ -68,6 +101,6 @@ export async function recoverServiceLifetime(store, installationId, alive) {
             else
                 throw error;
         }
-        await syncDir(root);
+        await syncDirectoryAsync(root);
     }
 }

package/dist/src/service/loop.d.ts

@@ -1,8 +1,8 @@
 import type { LibraryStore } from '../store/index.js';
 import { type ProcessIdentity } from '../worker/identity.js';
 export type ServiceEvent = 'started' | 'idle' | 'drained' | 'busy' | 'repair-required' | 'stopped';
-/** Fixed event vocabulary; source URLs, credentials, content and raw errors never enter logs. */
-export declare function serviceLog(root: string, event: ServiceEvent): void;
+/** Fixed event vocabulary plus a stable error code token; source URLs, credentials, content and raw errors never enter logs. */
+export declare function serviceLog(root: string, event: ServiceEvent, code?: unknown): void;
 export declare function idleWait(ms: number, signal: AbortSignal): Promise<void>;
 export interface ServiceLoopOptions {
     signal: AbortSignal;
@@ -10,7 +10,7 @@ export interface ServiceLoopOptions {
     drain: (signal: AbortSignal) => Promise<readonly unknown[]>;
     idleMs?: number;
     wait?: (ms: number, signal: AbortSignal) => Promise<void>;
-    log?: (event: ServiceEvent) => void;
+    log?: (event: ServiceEvent, code?: unknown) => void;
     onIdle?: () => Promise<void>;
     identity?: () => Promise<ProcessIdentity | null>;
 }