@hraness/sponge 0.1.2 → 0.2.1

package/dist/src/search/hybrid.js

@@ -0,0 +1,118 @@
+import { chunkDocument } from '../indexing/index.js';
+import { pinSearchGeneration, vectorSearch } from './vector.js';
+function lexical(db, query, limit) { const literal = '"' + query.replaceAll('"', '""') + '"'; return db.prepare('SELECT i.id AS itemId,i.title,i.current_revision AS revisionId FROM readable_fts f JOIN items i ON i.id=f.item_id WHERE readable_fts MATCH ? AND i.deleted_at IS NULL AND i.current_revision=f.revision_id ORDER BY rank,i.id LIMIT ?').all(literal, limit); }
+/** Reciprocal rank fusion after per-channel item collapsing; chunks cannot amplify rank. */
+export function fuse(lexicalHits, semanticHits, limit) {
+    const hits = new Map();
+    for (const [method, rows] of [['lexical', lexicalHits], ['semantic', semanticHits]]) {
+        const seen = new Set();
+        let rank = 0;
+        for (const row of rows) {
+            if (seen.has(row.itemId))
+                continue;
+            seen.add(row.itemId);
+            rank++;
+            const previous = hits.get(row.itemId), vector = method === 'semantic' ? row : undefined;
+            const anchor = vector ? { kind: vector.source.kind === 'image' ? 'image' : 'document', representationId: vector.source.representationId, chunk: vector.source.ordinal, assetSha256: vector.source.assetSha256 } : { kind: 'document' };
+            if (previous) {
+                previous.score += 1 / (60 + rank);
+                previous.methods.push(method);
+                if (vector)
+                    previous.anchor = anchor;
+            }
+            else
+                hits.set(row.itemId, { itemId: row.itemId, revisionId: row.revisionId, title: row.title, score: 1 / (60 + rank), methods: [method], anchor });
+        }
+    }
+    return [...hits.values()].sort((a, b) => b.score - a.score || a.itemId.localeCompare(b.itemId)).slice(0, limit);
+}
+/** Project only producer-authored local PDF/media markers, never remote content. */
+function projectAnchors(db, hits) {
+    for (const hit of hits) {
+        if (hit.anchor.kind !== 'document' || !hit.anchor.representationId || hit.anchor.chunk === undefined)
+            continue;
+        const row = db.prepare('SELECT p.markdown,i.kind,r.extractor_name AS extractor FROM representations p JOIN revisions r ON r.id=p.revision_id JOIN items i ON i.id=r.item_id WHERE p.id=? AND p.revision_id=?').get(hit.anchor.representationId, hit.revisionId);
+        if (!row || typeof row.markdown !== 'string')
+            continue;
+        const chunks = chunkDocument(row.markdown), chunk = chunks[hit.anchor.chunk];
+        if (chunk === undefined)
+            continue;
+        // Include the last marker preceding the chunk, including a marker split by chunking.
+        let start = 0;
+        for (let ordinal = 0; ordinal <= hit.anchor.chunk; ordinal++) {
+            start = row.markdown.indexOf(chunks[ordinal], start);
+            if (start < 0)
+                break;
+            if (ordinal < hit.anchor.chunk)
+                start += chunks[ordinal].length;
+        }
+        if (start < 0)
+            continue;
+        const end = start + chunk.length;
+        if (row.kind === 'pdf') {
+            const markers = [...row.markdown.matchAll(/^## Page ([1-9][0-9]*)$/gm)];
+            const marker = markers.filter(m => m.index <= start).at(-1) ?? markers.find(m => m.index < end);
+            if (marker)
+                hit.anchor.page = Number(marker[1]);
+        }
+        else if (row.extractor === 'sponge-media') {
+            const markers = [...row.markdown.matchAll(/^\[(\d+):(\d{2}):(\d{2})\] /gm)];
+            const marker = markers.filter(m => m.index <= start).at(-1) ?? markers.find(m => m.index < end);
+            if (marker)
+                hit.anchor.startMs = (Number(marker[1]) * 3600 + Number(marker[2]) * 60 + Number(marker[3])) * 1000;
+        }
+    }
+}
+export async function hybridSearch(db, query, options = {}) {
+    const limit = options.limit ?? 20, timeout = options.semanticTimeoutMs ?? 10000;
+    if (!query.trim() || Buffer.byteLength(query) > 4096 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(timeout) || timeout < 1 || timeout > 120000)
+        throw Error('invalid-search-query');
+    const pin = pinSearchGeneration(db, options.profileId ?? 'default'), warnings = [];
+    let encoded;
+    if (pin && options.embed) {
+        const controller = new AbortController(), abort = () => controller.abort();
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        let timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeout);
+        try {
+            const result = await options.embed(query, pin, controller.signal);
+            if (timedOut)
+                warnings.push('semantic-timeout');
+            else if (controller.signal.aborted)
+                warnings.push('semantic-unavailable');
+            else
+                encoded = result;
+        }
+        catch {
+            warnings.push(timedOut ? 'semantic-timeout' : 'semantic-unavailable');
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
+    else
+        warnings.push('semantic-unavailable');
+    db.exec('BEGIN');
+    try {
+        let semantic = [];
+        if (pin && encoded) {
+            try {
+                semantic = vectorSearch(db, pin, encoded, Math.min(500, limit * 5));
+            }
+            catch {
+                warnings.push('semantic-unavailable');
+            }
+        }
+        const result = { hits: fuse(lexical(db, query, Math.min(500, limit * 5)), semantic, limit), warnings, generation: pin };
+        projectAnchors(db, result.hits);
+        db.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}

package/dist/src/search/query.d.ts

@@ -0,0 +1,12 @@
+import type { LibraryStore } from '../store/index.js';
+import { embedBatch, type EmbeddingRuntime } from '../inference/embedding/index.js';
+import type { QueryEmbedder } from './hybrid.js';
+/** Queries mutate coordination journals only, never library content or job tables. */
+export declare function createQueryEmbedder(store: LibraryStore, runtime: EmbeddingRuntime, options?: {
+    embed?: typeof embedBatch;
+    onReady?: (context: {
+        attemptId: string;
+        ownerDirectory: string;
+        scratchRoot: string;
+    }) => Promise<void>;
+}): QueryEmbedder;

package/dist/src/search/query.js

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import { acquireWorkerCustody, proveAttemptCleanup } from '../worker/custody.js';
+import { directory, writeJournal, readJournal, syncDir } from '../worker/journal.js';
+import { supervisedRunner } from '../worker/supervisor.js';
+import { embedBatch, embeddingFingerprint, encodeEmbeddingRequest, EmbeddingError } from '../inference/embedding/index.js';
+/** Queries mutate coordination journals only, never library content or job tables. */
+export function createQueryEmbedder(store, runtime, options = {}) {
+    return async (query, pin, signal) => {
+        if (signal.aborted)
+            throw new EmbeddingError('cancelled');
+        if (pin.fingerprint !== embeddingFingerprint(runtime.helperSha256))
+            throw new EmbeddingError('integrity');
+        const custody = await acquireWorkerCustody(store.root), attemptId = randomUUID();
+        let scratchRoot, cleanupUnknown = false;
+        try {
+            const attempts = await directory(join(custody.directory, 'attempts', attemptId));
+            await writeJournal(join(attempts, 'query.json'), { schemaVersion: 1, kind: 'query', attemptId, ownerIncarnation: custody.incarnation });
+            scratchRoot = await directory(join(store.root, 'staging', 'query-' + attemptId));
+            await writeJournal(join(scratchRoot, 'ownership.json'), { schemaVersion: 1, kind: 'query', requestId: attemptId, ownerIncarnation: custody.incarnation });
+            await options.onReady?.({ attemptId, ownerDirectory: custody.directory, scratchRoot });
+            const inputs = [{ kind: 'query', text: query }], expected = encodeEmbeddingRequest(inputs).inputHashes[0];
+            const result = await (options.embed ?? embedBatch)(inputs, { runtime, scratchRoot, signal, runProcess: supervisedRunner(custody.directory, custody.incarnation, attemptId) });
+            if (result.fingerprint !== pin.fingerprint || result.inputHashes.length !== 1 || result.inputHashes[0] !== expected || result.vectors.length !== 1)
+                throw new EmbeddingError('integrity');
+            return { fingerprint: result.fingerprint, vector: result.vectors[0] };
+        }
+        catch (error) {
+            cleanupUnknown = error.code === 'cleanup-required';
+            throw error;
+        }
+        finally {
+            const proved = !cleanupUnknown && await proveAttemptCleanup(custody.directory, custody.incarnation, attemptId);
+            if (!proved)
+                throw new EmbeddingError('cleanup-required');
+            if (scratchRoot) {
+                const marker = await readJournal(join(scratchRoot, 'ownership.json'));
+                if (marker.schemaVersion !== 1 || marker.kind !== 'query' || marker.requestId !== attemptId || marker.ownerIncarnation !== custody.incarnation)
+                    throw new EmbeddingError('cleanup-required');
+                await rm(scratchRoot, { recursive: true });
+                await syncDir(join(store.root, 'staging'));
+            }
+            await custody.release();
+        }
+    };
+}

package/dist/src/search/vector.d.ts

@@ -0,0 +1,21 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { IndexInput } from '../indexing/index.js';
+export interface SearchGeneration {
+    id: string;
+    fingerprint: string;
+    dimensions: number;
+    profileId: string;
+}
+export interface VectorHit {
+    itemId: string;
+    revisionId: string;
+    title: string;
+    source: IndexInput;
+    distance: number;
+}
+export declare function pinSearchGeneration(db: DatabaseSync, profileId: string): SearchGeneration | undefined;
+/** Native scalar scan keeps vectors inside SQLite; SQL bounds materialized result rows. */
+export declare function vectorSearch(db: DatabaseSync, pin: SearchGeneration, query: {
+    fingerprint: string;
+    vector: readonly number[];
+}, limit?: number): VectorHit[];

package/dist/src/search/vector.js

@@ -0,0 +1,21 @@
+export function pinSearchGeneration(db, profileId) {
+    const row = db.prepare('SELECT g.id,g.fingerprint,s.dimensions FROM active_indexes a JOIN index_generations g ON g.id=a.generation_id JOIN embedding_spaces s ON s.fingerprint=g.fingerprint WHERE a.profile_id=?').get(profileId);
+    if (!row)
+        return undefined;
+    return { id: String(row.id), fingerprint: String(row.fingerprint), dimensions: Number(row.dimensions), profileId };
+}
+/** Native scalar scan keeps vectors inside SQLite; SQL bounds materialized result rows. */
+export function vectorSearch(db, pin, query, limit = 50) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500 || query.fingerprint !== pin.fingerprint || query.vector.length !== pin.dimensions || query.vector.some(n => !Number.isFinite(n)) || Math.abs(Math.hypot(...query.vector) - 1) > .001)
+        throw Error('invalid-search-vector');
+    if (db.prepare('SELECT vec_version() AS version').get()?.version !== 'v0.1.9')
+        throw Error('unsupported-vector-runtime');
+    const generation = db.prepare('SELECT fingerprint FROM index_generations WHERE id=?').get(pin.id);
+    if (!generation || generation.fingerprint !== pin.fingerprint)
+        throw Error('search-generation-missing');
+    const bytes = Buffer.alloc(query.vector.length * 4);
+    query.vector.forEach((v, i) => bytes.writeFloatLE(v, i * 4));
+    const rows = db.prepare('SELECT v.source_id,v.revision_id,v.derivation_hash,v.asset_sha256,i.id AS item_id,i.title,vec_distance_cosine(v.vector,?) AS distance FROM vectors v JOIN revisions r ON r.id=v.revision_id JOIN items i ON i.id=r.item_id WHERE v.generation_id=? AND i.deleted_at IS NULL AND i.current_revision=v.revision_id ORDER BY distance,v.source_id LIMIT ?').all(bytes, pin.id, limit);
+    return rows.map(row => { const descriptor = JSON.parse(String(row.source_id)), distance = Number(row.distance); if (!Array.isArray(descriptor) || descriptor[0] !== row.revision_id || !['document', 'image'].includes(String(descriptor[1])) || typeof descriptor[2] !== 'string' || !Number.isFinite(distance))
+        throw Error('invalid-search-index'); const source = { sourceId: String(row.source_id), itemId: String(row.item_id), revisionId: String(row.revision_id), derivationHash: String(row.derivation_hash), kind: descriptor[1], ...(descriptor[1] === 'image' ? { assetSha256: String(row.asset_sha256) } : { representationId: descriptor[2], ordinal: Number(descriptor[3]) }) }; return { itemId: String(row.item_id), revisionId: String(row.revision_id), title: String(row.title), source, distance }; });
+}

package/dist/src/service/launch-agent.d.ts

@@ -0,0 +1,47 @@
+import type { LibraryStore } from '../store/index.js';
+import { type ProcessIdentity } from '../worker/identity.js';
+export interface LaunchResult {
+    code: number;
+    stdout: string;
+}
+export interface ServiceEnvironment {
+    platform: NodeJS.Platform;
+    uid: number;
+    home: string;
+    node: string;
+    cli: string;
+    version: string;
+    launchctl: (args: string[]) => Promise<LaunchResult>;
+    alive: (identity: ProcessIdentity) => Promise<boolean>;
+    pause: (ms: number) => Promise<void>;
+}
+export declare function serviceEnvironment(version: string): ServiceEnvironment;
+interface Pin {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+interface Installation {
+    language: "en" | null;
+    schemaVersion: 1;
+    id: string;
+    label: string;
+    uid: number;
+    version: string;
+    node: string;
+    cli: string;
+    library: string;
+    plist: string;
+    plistHash: string;
+    launcher: string;
+    launcherHash: string;
+    pins: Pin[];
+}
+export declare function agentPlist(record: Pick<Installation, 'label' | 'node' | 'launcher'>): string;
+export declare function serviceStatus(store: LibraryStore, env: ServiceEnvironment): Promise<Record<string, unknown>>;
+export declare function installService(store: LibraryStore, env: ServiceEnvironment, options?: {
+    language?: 'en';
+}): Promise<Record<string, unknown>>;
+export declare function uninstallService(store: LibraryStore, env: ServiceEnvironment): Promise<Record<string, unknown>>;
+export declare function installedServiceId(store: LibraryStore, env: ServiceEnvironment): string;
+export {};

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

@@ -0,0 +1,179 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+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 { 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';
+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 };
+    }
+    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);
+} }
+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');
+    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');
+    }
+    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 pinPackage(env) {
+    const cli = realpathSync(env.cli), root = dirname(dirname(cli));
+    if (cli !== join(root, 'bin', 'sponge.js'))
+        throw new StoreError('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');
+    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);
+        }
+    } };
+    visit(join(root, 'dist'));
+    const catalog = join(root, 'native', 'runtime-manifest.json');
+    let catalogPresent = false;
+    try {
+        lstatSync(catalog);
+        catalogPresent = true;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (catalogPresent) {
+        safeDirectory(dirname(catalog));
+        regularFile(catalog);
+        if (lstatSync(catalog).size > 16384 || paths.length >= 10000)
+            throw new StoreError('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.' } : {}) }; }
+export async function installService(store, env, options = {}) {
+    if (options.language !== undefined && options.language !== 'en')
+        throw new StoreError('invalid-input');
+    const p = paths(store, env);
+    safeDirectory(p.root, true);
+    const previous = installation(store, env);
+    if (previous) {
+        if (previous.language !== (options.language ?? null))
+            throw new StoreError('invalid-input');
+        return serviceStatus(store, env);
+    }
+    if (await loaded(env, p.target))
+        throw new StoreError('owner-busy');
+    safeDirectory(p.agents, true);
+    if (existsSync(p.plist))
+        throw new StoreError('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);
+    writePrivateExclusive(launcherPath, code);
+    writePrivateExclusive(p.plist, plist);
+    const record = { ...base, launcherHash: digest(code), plistHash: digest(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');
+    return serviceStatus(store, env);
+}
+export async function uninstallService(store, env) {
+    const p = paths(store, env), record = installation(store, env);
+    if (!record)
+        return { installed: false };
+    verifyOwnedFiles(record);
+    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');
+    }
+    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');
+            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)) {
+            verifyOwnedFiles(record);
+            unlinkSync(record.plist);
+            unlinkSync(record.launcher);
+            if (existsSync(run))
+                unlinkSync(run);
+            unlinkSync(p.record);
+            syncDirectory(p.agents);
+            syncDirectory(dirname(record.launcher));
+            syncDirectory(p.root);
+            return { installed: false, cleanup: 'settled' };
+        }
+        await env.pause(100);
+    }
+    throw Object.assign(new StoreError('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 StoreError('invalid-input'); verifyOwnedFiles(record); if (!current(record))
+    throw new StoreError('unavailable'); return record.id; }

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

@@ -0,0 +1,7 @@
+import type { ProcessIdentity } from '../worker/identity.js';
+import { type LibraryStore } from '../store/index.js';
+export declare function acquireServiceLifetime(root: string, installationId: string, identity: ProcessIdentity): Promise<{
+    release: () => Promise<void>;
+}>;
+/** Called only after bootout or a failed prior run; never signal a recorded PID. */
+export declare function recoverServiceLifetime(store: LibraryStore, installationId: string, alive: (identity: ProcessIdentity) => Promise<boolean>): Promise<boolean>;

package/dist/src/service/lifetime.js

@@ -0,0 +1,73 @@
+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; }
+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);
+    }
+    catch (error) {
+        await unlink(file);
+        if (error.code === 'EEXIST')
+            throw pending();
+        throw error;
+    }
+    return { release: async () => { await same(file, lock); await unlink(lock); await unlink(file); await syncDir(root); } };
+}
+/** Called only after bootout or a failed prior run; never signal a recorded PID. */
+export async function recoverServiceLifetime(store, installationId, alive) {
+    const root = join(store.root, 'runtime', 'service'), lock = join(root, 'lifetime.lock');
+    let value;
+    try {
+        value = await read(lock);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        throw error;
+    }
+    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);
+    try {
+        await link(file, guard);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    try {
+        await same(file, lock);
+        if (await alive(value.identity) || store.ownerSnapshot() !== null || store.pendingCleanupCount() > 0)
+            return false;
+        await unlink(lock);
+        await syncDir(root);
+        return true;
+    }
+    finally {
+        await same(file, guard);
+        await unlink(guard);
+        try {
+            await lstat(lock);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                await unlink(file);
+            else
+                throw error;
+        }
+        await syncDir(root);
+    }
+}

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

@@ -0,0 +1,21 @@
+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;
+export declare function idleWait(ms: number, signal: AbortSignal): Promise<void>;
+export interface ServiceLoopOptions {
+    signal: AbortSignal;
+    installationId: string;
+    drain: (signal: AbortSignal) => Promise<readonly unknown[]>;
+    idleMs?: number;
+    wait?: (ms: number, signal: AbortSignal) => Promise<void>;
+    log?: (event: ServiceEvent) => void;
+    onIdle?: () => Promise<void>;
+    identity?: () => Promise<ProcessIdentity | null>;
+}
+/** Uses the existing drain engine; it owns locking, cancellation and descendant collection. */
+export declare function runWorkerService(store: LibraryStore, options: ServiceLoopOptions): Promise<{
+    cycles: number;
+    cleanup: 'settled' | 'pending';
+}>;