@hraness/sponge 0.1.0 → 0.2.0

package/dist/src/store/types.d.ts

@@ -0,0 +1,90 @@
+import type { MetadataClaim, MetadataWarning } from '../../contracts/index.js';
+export type ItemKind = 'article' | 'pdf' | 'media';
+export type FaultPoint = 'staged' | 'published' | 'transaction' | 'committed';
+export interface StoreOptions {
+    fault?: (point: FaultPoint) => void;
+    appVersion?: string;
+}
+export interface OwnerToken {
+    ownerIncarnation: string;
+    fence: number;
+}
+export interface AttemptToken extends OwnerToken {
+    attemptId: string;
+    jobId: string;
+}
+export interface OwnedAttempt extends AttemptToken {
+    kind?: 'capture' | 'index';
+    stage: string;
+    cleanup: 'pending' | 'settled';
+    finished: boolean;
+    jobState: string;
+    cancelRequested: boolean;
+}
+export interface SourceSubmission {
+    sourceKey: string;
+    locator: string;
+    realm?: string;
+    kind: ItemKind;
+    idempotencyKey: string;
+    intent?: 'save' | 'refresh';
+}
+export interface Submission {
+    itemId: string;
+    jobId: string;
+    submissionId: string;
+    duplicate: boolean;
+}
+export interface BlobReference {
+    sha256: string;
+    bytes: number;
+    relativePath: string;
+}
+export interface RevisionAsset extends BlobReference {
+    mediaType: string;
+    relationship?: string;
+    alt?: string;
+    caption?: string;
+}
+export interface CommitRevision extends AttemptToken {
+    importedState?: {
+        namespace: string;
+        sourceKey: string;
+        sourceHash: string;
+        importerVersion: string;
+        notes: {
+            id: string;
+            body: string;
+        }[];
+        readingState?: Record<string, unknown>;
+        privacy: 'private' | 'published';
+    };
+    itemId: string;
+    bundleHash: string;
+    markdown: string;
+    title?: string;
+    extractor: {
+        name: string;
+        version: string;
+    };
+    status: 'complete' | 'partial';
+    metadata?: MetadataClaim[];
+    metadataWarnings?: MetadataWarning[];
+    assets: RevisionAsset[];
+    warnings?: string[];
+}
+export interface ReadableItem {
+    itemId: string;
+    kind: ItemKind;
+    title: string;
+    revisionId: string;
+    markdown: string;
+    status: 'complete' | 'partial';
+    assets: RevisionAsset[];
+    metadata: MetadataClaim[];
+    metadataWarnings: MetadataWarning[];
+}
+export declare class StoreError extends Error {
+    readonly code: 'invalid-input' | 'integrity' | 'limit-exceeded' | 'schema-newer' | 'owner-busy' | 'cancelled' | 'unavailable';
+    constructor(code: 'invalid-input' | 'integrity' | 'limit-exceeded' | 'schema-newer' | 'owner-busy' | 'cancelled' | 'unavailable', message?: "unavailable" | "cancelled" | "invalid-input" | "integrity" | "limit-exceeded" | "schema-newer" | "owner-busy");
+}

package/dist/src/store/types.js

@@ -0,0 +1,8 @@
+export class StoreError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = 'StoreError';
+    }
+}

package/dist/src/worker/basic.d.ts

@@ -0,0 +1,10 @@
+import type { LibraryStore } from '../store/index.js';
+import { type ArticleOptions, type ArticleOutcome } from '../app/article.js';
+import { type MediaOptions } from '../media/handler.js';
+/** Content handlers over the durable sequential worker and its process supervisor. */
+export declare function drainLibrary(store: LibraryStore, options: ArticleOptions & Pick<MediaOptions, 'asrRuntime' | 'language' | 'forceLocal'> & {
+    jobId?: string;
+    resolveConnection?: (realm: string) => ArticleOptions['connection'];
+    onResult?: (result: ArticleOutcome) => void;
+}): Promise<ArticleOutcome[]>;
+export declare const drainArticles: typeof drainLibrary;

package/dist/src/worker/basic.js

@@ -0,0 +1,27 @@
+import { failure } from '../acquisition/errors.js';
+import { ingestArticle } from '../app/article.js';
+import { ingestPdf } from '../pdf/index.js';
+import { ingestMedia } from '../media/handler.js';
+import { drainQueue } from './engine.js';
+/** Content handlers over the durable sequential worker and its process supervisor. */
+export async function drainLibrary(store, options) {
+    const handler = async (context) => {
+        const source = store.sourceForJob(context.attempt.jobId);
+        let connection;
+        try {
+            connection = options.resolveConnection?.(source?.realm ?? 'public') ?? options.connection;
+        }
+        catch {
+            store.failAttempt(context.attempt, 'repair-auth');
+            store.settleAttempt(context.attempt);
+            return { ...failure(context.attempt.attemptId, 'repair-auth', 'acquisition'), cleanup: 'settled' };
+        }
+        if (source?.kind === 'media') {
+            const { capture: _articleCapture, ...mediaOptions } = options;
+            return ingestMedia(store, context.attempt, { ...mediaOptions, connection, signal: context.signal, runProcess: context.runProcess, checkpoint: context.checkpoint });
+        }
+        return (source?.kind === 'pdf' ? ingestPdf : ingestArticle)(store, context.attempt, { ...options, connection, signal: context.signal, runProcess: context.runProcess, checkpoint: context.checkpoint });
+    };
+    return drainQueue(store, { signal: options.signal, jobId: options.jobId, onResult: options.onResult, handlers: { article: handler, pdf: handler, media: handler } });
+}
+export const drainArticles = drainLibrary;

package/dist/src/worker/custody.d.ts

@@ -0,0 +1,13 @@
+import { type LibraryStore } from '../store/index.js';
+export interface WorkerCustody {
+    incarnation: string;
+    directory: string;
+    release: () => Promise<void>;
+}
+export declare function acquireWorkerCustody(root: string): Promise<WorkerCustody>;
+/** Receipts are specific to every pre-launch ticket. Missing receipts never mean absent children. */
+export declare function proveAttemptCleanup(ownerDirectory: string, incarnation: string, attemptId: string): Promise<boolean>;
+export declare function recoverWorker(store: LibraryStore): Promise<{
+    recovered: boolean;
+    attempts: number;
+}>;

package/dist/src/worker/custody.js

@@ -0,0 +1,185 @@
+import { lstat, link, unlink, readdir, rm, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { StoreError } from '../store/index.js';
+import { directory, identifier, readJournal, writeJournal, syncDir } from './journal.js';
+import { processIdentity, identityAlive } from './identity.js';
+const pending = () => Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+async function ownerRecord(path) { const record = await readJournal(path); if (record.schemaVersion !== 1 || typeof record.incarnation !== 'string' || !record.identity || !Number.isSafeInteger(record.identity.pid) || record.identity.uid !== process.getuid?.() || typeof record.identity.started !== 'string')
+    throw pending(); identifier(record.incarnation); return record; }
+async function sameFile(a, b) { const [x, y] = await Promise.all([lstat(a), lstat(b)]); if (!x.isFile() || !y.isFile() || x.ino !== y.ino || x.dev !== y.dev)
+    throw pending(); }
+export async function acquireWorkerCustody(root) {
+    const workers = await directory(join(root, 'runtime', 'workers')), incarnation = randomUUID(), ownerDirectory = await directory(join(workers, incarnation));
+    const identity = await processIdentity(process.pid);
+    if (!identity)
+        throw pending();
+    const file = join(ownerDirectory, 'owner.json'), lock = join(root, 'runtime', 'worker.lock');
+    await writeJournal(file, { schemaVersion: 1, incarnation, identity });
+    try {
+        await link(file, lock);
+        await syncDir(join(root, 'runtime'));
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new StoreError('owner-busy');
+        throw error;
+    }
+    return { incarnation, directory: ownerDirectory, release: async () => { await sameFile(file, lock); await unlink(lock); await syncDir(join(root, 'runtime')); } };
+}
+/** Receipts are specific to every pre-launch ticket. Missing receipts never mean absent children. */
+export async function proveAttemptCleanup(ownerDirectory, incarnation, attemptId) {
+    identifier(attemptId);
+    let entries;
+    const root = join(ownerDirectory, 'attempts', attemptId);
+    try {
+        const stat = await lstat(root);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(root) !== root || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
+            return false;
+        entries = await readdir(root);
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries.filter(name => /\.(settled|supervisor)\.json$/.test(name)))
+        if (!entries.includes(entry.replace(/\.(settled|supervisor)\.json$/, '.pending.json')))
+            return false;
+    for (const entry of entries.filter(name => name.endsWith('.pending.json'))) {
+        try {
+            const ticket = await readJournal(join(root, entry)), receipt = await readJournal(join(root, entry.replace('.pending.', '.settled.')));
+            if (typeof ticket.ticket !== 'string' || entry !== ticket.ticket + '.pending.json')
+                return false;
+            identifier(ticket.ticket);
+            if (ticket.schemaVersion !== 1 || ticket.attemptId !== attemptId || ticket.ownerIncarnation !== incarnation || receipt.schemaVersion !== 1 || receipt.ticket !== ticket.ticket || receipt.attemptId !== attemptId || receipt.ownerIncarnation !== incarnation || receipt.cleanup !== 'settled')
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+export async function recoverWorker(store) {
+    const lock = join(store.root, 'runtime', 'worker.lock');
+    let record;
+    try {
+        record = await ownerRecord(lock);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            if (store.ownerSnapshot())
+                throw pending();
+            return { recovered: false, attempts: 0 };
+        }
+        throw pending();
+    }
+    if (await identityAlive(record.identity))
+        throw new StoreError('owner-busy');
+    const ownerDirectory = join(store.root, 'runtime', 'workers', record.incarnation), file = join(ownerDirectory, 'owner.json');
+    await sameFile(file, lock);
+    // Serialize recovery. No timeout, PID disappearance or age can steal this guard.
+    const recovery = join(store.root, 'runtime', 'worker-recovery.lock');
+    try {
+        await link(file, recovery);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw pending();
+        throw error;
+    }
+    try {
+        await sameFile(file, lock);
+        if (await identityAlive(record.identity))
+            throw new StoreError('owner-busy');
+        const owner = store.ownerSnapshot();
+        if (owner && owner.ownerIncarnation !== record.incarnation)
+            throw pending();
+        const attempts = owner ? store.ownerAttempts(owner) : [];
+        for (const attempt of attempts)
+            if (attempt.cleanup === 'pending' && !await proveAttemptCleanup(ownerDirectory, record.incarnation, attempt.attemptId))
+                throw pending();
+        const attemptIds = new Set(attempts.map(a => a.attemptId)), transientIds = new Map();
+        let journals = [];
+        try {
+            journals = await readdir(join(ownerDirectory, 'attempts'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw pending();
+        }
+        for (const id of journals) {
+            identifier(id);
+            if (!attemptIds.has(id)) {
+                let marker;
+                for (const kind of ['query', 'import-verification']) {
+                    try {
+                        const candidate = await readJournal(join(ownerDirectory, 'attempts', id, kind + '.json'));
+                        if (marker || candidate.kind !== kind)
+                            throw pending();
+                        marker = candidate;
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw pending();
+                    }
+                }
+                if (!marker || marker.schemaVersion !== 1 || !['query', 'import-verification'].includes(marker.kind) || marker.attemptId !== id || marker.ownerIncarnation !== record.incarnation)
+                    throw pending();
+                transientIds.set(id, marker.kind);
+            }
+            if (!await proveAttemptCleanup(ownerDirectory, record.incarnation, id))
+                throw pending();
+        }
+        const staging = join(store.root, 'staging');
+        for (const entry of await readdir(staging)) {
+            if (entry.startsWith('query-') || entry.startsWith('import-verification-')) {
+                const path = join(staging, entry);
+                await directory(path);
+                let marker;
+                try {
+                    marker = await readJournal(join(path, 'ownership.json'));
+                }
+                catch {
+                    throw pending();
+                }
+                if (marker.schemaVersion !== 1 || !['query', 'import-verification'].includes(marker.kind) || typeof marker.requestId !== 'string' || entry !== marker.kind + '-' + marker.requestId || typeof marker.ownerIncarnation !== 'string')
+                    throw pending();
+                if (marker.ownerIncarnation === record.incarnation) {
+                    if (transientIds.get(marker.requestId) !== marker.kind)
+                        throw pending();
+                    await rm(path, { recursive: true });
+                    await syncDir(staging);
+                }
+                continue;
+            }
+            if (!entry.startsWith('capture-'))
+                continue;
+            const path = join(staging, entry);
+            await directory(path);
+            let marker;
+            try {
+                marker = await readJournal(join(path, 'ownership.json'));
+            }
+            catch {
+                throw pending();
+            }
+            if (marker.schemaVersion !== 1 || typeof marker.requestId !== 'string')
+                throw pending();
+            if (attemptIds.has(marker.requestId)) {
+                await rm(path, { recursive: true });
+                await syncDir(staging);
+            }
+        }
+        if (owner)
+            store.recoverOwner(owner, attempts.filter(a => a.cleanup === 'pending').map(a => a.attemptId));
+        await sameFile(file, lock);
+        await unlink(lock);
+        await syncDir(join(store.root, 'runtime'));
+        return { recovered: true, attempts: attempts.length };
+    }
+    finally {
+        await sameFile(file, recovery);
+        await unlink(recovery);
+        await syncDir(join(store.root, 'runtime'));
+    }
+}

package/dist/src/worker/engine.d.ts

@@ -0,0 +1,28 @@
+import type { ErrorEnvelope, JobCheckpoint } from '../../contracts/index.js';
+import type { LibraryStore, AttemptToken } from '../store/index.js';
+import { type ProcessRunner } from './supervisor.js';
+export type WorkerFailure = ErrorEnvelope & {
+    cleanup: 'settled' | 'pending';
+};
+export type WorkerOutcome = ({
+    ok: true;
+} | ErrorEnvelope) & {
+    cleanup: 'settled' | 'pending';
+};
+export interface HandlerContext {
+    store: LibraryStore;
+    attempt: AttemptToken;
+    signal: AbortSignal;
+    runProcess: ProcessRunner;
+    checkpoint: (stage: JobCheckpoint['stage']) => Promise<void>;
+}
+/** Handlers finish and settle storage only after all process and artifact cleanup is established. */
+export type JobHandler<T extends WorkerOutcome = WorkerOutcome> = (context: HandlerContext) => Promise<T>;
+export interface QueueOptions<T extends WorkerOutcome> {
+    handlers: Readonly<Record<string, JobHandler<T>>>;
+    signal?: AbortSignal;
+    jobId?: string;
+    onResult?: (result: T | WorkerFailure) => void;
+    onCheckpoint?: (attempt: AttemptToken, stage: JobCheckpoint['stage']) => Promise<void>;
+}
+export declare function drainQueue<T extends WorkerOutcome>(store: LibraryStore, options: QueueOptions<T>): Promise<Array<T | WorkerFailure>>;

package/dist/src/worker/engine.js

@@ -0,0 +1,78 @@
+import { join } from 'node:path';
+import { failure } from '../acquisition/errors.js';
+import { acquireWorkerCustody, proveAttemptCleanup } from './custody.js';
+import { supervisedRunner } from './supervisor.js';
+import { writeJournal, directory } from './journal.js';
+export async function drainQueue(store, options) {
+    const custody = await acquireWorkerCustody(store.root);
+    let owner, settled = true;
+    const results = [];
+    try {
+        owner = store.acquireOwner(custody.incarnation);
+        while (!options.signal?.aborted) {
+            const attempt = options.jobId ? store.claimJob(owner, options.jobId) : store.claimNext(owner);
+            if (!attempt)
+                break;
+            settled = false;
+            const attemptDirectory = await directory(join(custody.directory, 'attempts', attempt.attemptId));
+            const checkpoint = async (stage) => { store.checkpointAttempt(attempt, stage); await writeJournal(join(attemptDirectory, 'checkpoint.json'), { schemaVersion: 1, ...attempt, stage }); await options.onCheckpoint?.(attempt, stage); };
+            await checkpoint('acquiring');
+            const controller = new AbortController(), cancel = () => { store.requestCancellation(attempt.jobId); controller.abort(); };
+            options.signal?.addEventListener('abort', cancel, { once: true });
+            const poll = setInterval(() => { try {
+                if (store.jobCancellationRequested(attempt.jobId))
+                    controller.abort();
+            }
+            catch {
+                controller.abort();
+            } }, 100);
+            try {
+                if (options.signal?.aborted)
+                    cancel();
+                const source = store.sourceForJob(attempt.jobId), handler = source && options.handlers[source.kind];
+                if (!handler) {
+                    store.failAttempt(attempt, 'unsupported');
+                    store.settleAttempt(attempt);
+                    settled = true;
+                    const result = { ...failure(attempt.attemptId, 'unsupported'), cleanup: 'settled' };
+                    results.push(result);
+                    options.onResult?.(result);
+                    if (options.jobId)
+                        break;
+                    continue;
+                }
+                const result = await handler({ store, attempt, signal: controller.signal, runProcess: supervisedRunner(custody.directory, custody.incarnation, attempt.attemptId), checkpoint });
+                results.push(result);
+                options.onResult?.(result);
+                const state = store.ownerAttempts(owner).find(a => a.attemptId === attempt.attemptId);
+                settled = result.cleanup === 'settled' && state?.cleanup === 'settled' && await proveAttemptCleanup(custody.directory, custody.incarnation, attempt.attemptId);
+                if (!settled || options.jobId)
+                    break;
+                if (!result.ok && result.retryable && ['unavailable', 'rate-limited'].includes(result.code)) {
+                    const job = store.listJobs().find(j => j.id === attempt.jobId), count = Number(job?.attempt_count ?? 3);
+                    if (count < 3)
+                        store.retryJob(attempt.jobId, { automatic: true, notBefore: new Date(Date.now() + Math.min(60000, 1000 * 2 ** count)).toISOString() });
+                }
+            }
+            finally {
+                clearInterval(poll);
+                options.signal?.removeEventListener('abort', cancel);
+            }
+        }
+        if (!settled)
+            throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+        return results;
+    }
+    finally {
+        if (owner && settled) {
+            try {
+                store.releaseOwner(owner);
+            }
+            catch {
+                settled = false;
+            }
+        }
+        if (settled)
+            await custody.release();
+    }
+}

package/dist/src/worker/identity.d.ts

@@ -0,0 +1,7 @@
+export interface ProcessIdentity {
+    pid: number;
+    uid: number;
+    started: string;
+}
+export declare function processIdentity(pid: number): Promise<ProcessIdentity | null>;
+export declare function identityAlive(identity: ProcessIdentity): Promise<boolean>;

package/dist/src/worker/identity.js

@@ -0,0 +1,27 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+export async function processIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw Error('invalid-input');
+    try {
+        const { stdout } = await exec('/bin/ps', ['-p', String(pid), '-o', 'uid=', '-o', 'lstart='], { timeout: 3000, maxBuffer: 4096, env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' } });
+        const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(stdout);
+        if (!match)
+            throw Error('unavailable');
+        return { pid, uid: Number(match[1]), started: match[2] };
+    }
+    catch (error) {
+        if (error.code === 1) {
+            try {
+                process.kill(pid, 0);
+            }
+            catch (e) {
+                if (e.code === 'ESRCH')
+                    return null;
+            }
+        }
+        throw Object.assign(Error('unavailable'), { code: 'unavailable' });
+    }
+}
+export async function identityAlive(identity) { const current = await processIdentity(identity.pid); return current !== null && current.uid === identity.uid && current.started === identity.started; }

package/dist/src/worker/journal.d.ts

@@ -0,0 +1,5 @@
+export declare const identifier: (value: string) => string;
+export declare function syncDir(path: string): Promise<void>;
+export declare function directory(path: string): Promise<string>;
+export declare function writeJournal(path: string, value: unknown): Promise<void>;
+export declare function readJournal(path: string): Promise<any>;

package/dist/src/worker/journal.js

@@ -0,0 +1,30 @@
+import { constants } from 'node:fs';
+import { open, mkdir, rename, lstat, realpath } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export const identifier = (value) => { if (!/^[a-zA-Z0-9_-]{1,128}$/.test(value))
+    throw Object.assign(Error('invalid-input'), { code: 'invalid-input' }); return value; };
+export async function syncDir(path) { const f = await open(path, constants.O_RDONLY); try {
+    await f.sync();
+}
+finally {
+    await f.close();
+} }
+export async function directory(path) { await mkdir(path, { recursive: true, mode: 0o700 }); const stat = await lstat(path); if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(path) !== path || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
+    throw Object.assign(Error('integrity'), { code: 'integrity' }); return path; }
+export async function writeJournal(path, value) { const temp = join(dirname(path), '.' + randomUUID() + '.tmp'); const file = await open(temp, 'wx', 0o600); try {
+    await file.writeFile(JSON.stringify(value));
+    await file.sync();
+}
+finally {
+    await file.close();
+} await rename(temp, path); await syncDir(dirname(path)); }
+export async function readJournal(path) { const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); try {
+    const s = await file.stat();
+    if (!s.isFile() || s.uid !== process.getuid?.() || (s.mode & 0o077) !== 0 || s.size > 65536)
+        throw Error('integrity');
+    return JSON.parse(await file.readFile('utf8'));
+}
+finally {
+    await file.close();
+} }

package/dist/src/worker/supervisor-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/worker/supervisor-child.js

@@ -0,0 +1,33 @@
+import { join } from 'node:path';
+import { runOwned } from '../acquisition/process.js';
+import { readJournal, writeJournal } from './journal.js';
+import { processIdentity } from './identity.js';
+// This process owns collection even when its requesting worker is killed.
+const [root, ticketId] = process.argv.slice(2);
+if (!root || !ticketId || !process.send)
+    process.exit(2);
+const pending = await readJournal(join(root, ticketId + '.pending.json'));
+const controller = new AbortController();
+let started = false;
+const abort = () => controller.abort();
+process.on('disconnect', abort);
+process.on('SIGTERM', abort);
+process.on('SIGINT', abort);
+await writeJournal(join(root, ticketId + '.supervisor.json'), { ...pending, identity: await processIdentity(process.pid) });
+const deadline = setTimeout(() => { if (!started)
+    process.exit(2); }, 10000);
+process.once('message', async (message) => {
+    if (message?.type !== 'run' || message.ticket !== pending.ticket || message.attemptId !== pending.attemptId)
+        process.exit(2);
+    started = true;
+    clearTimeout(deadline);
+    const result = await runOwned(message.executable, message.args, { ...message.options, signal: controller.signal });
+    if (result.cleanup === 'settled')
+        await writeJournal(join(root, ticketId + '.settled.json'), { schemaVersion: 1, ticket: pending.ticket, attemptId: pending.attemptId, ownerIncarnation: pending.ownerIncarnation, cleanup: 'settled' });
+    if (process.connected)
+        process.send?.({ type: 'result', result }, undefined, undefined, () => process.disconnect());
+});
+process.on('message', (message) => { if (message?.type === 'cancel')
+    abort(); });
+if (process.connected)
+    process.send({ type: 'ready', ticket: pending.ticket });

package/dist/src/worker/supervisor.d.ts

@@ -0,0 +1,3 @@
+import type { runOwned } from '../acquisition/process.js';
+export type ProcessRunner = typeof runOwned;
+export declare function supervisedRunner(ownerDirectory: string, ownerIncarnation: string, attemptId: string): ProcessRunner;

package/dist/src/worker/supervisor.js

@@ -0,0 +1,47 @@
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { directory, identifier, readJournal, writeJournal } from './journal.js';
+export function supervisedRunner(ownerDirectory, ownerIncarnation, attemptId) {
+    identifier(ownerIncarnation);
+    identifier(attemptId);
+    return async (executable, args, options) => {
+        if (options.signal?.aborted)
+            return { code: null, stdout: '', stopped: 'cancelled', cleanup: 'settled' };
+        const root = await directory(join(ownerDirectory, 'attempts', attemptId)), ticket = randomUUID();
+        await writeJournal(join(root, ticket + '.pending.json'), { schemaVersion: 1, ticket, attemptId, ownerIncarnation });
+        const source = import.meta.url.endsWith('.ts'), entry = fileURLToPath(new URL(source ? './supervisor-child.ts' : './supervisor-child.js', import.meta.url));
+        return new Promise(resolve => {
+            const child = fork(entry, [root, ticket], { detached: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'], execArgv: source ? ['--import', import.meta.resolve('tsx')] : [], env: { PATH: '/usr/bin:/bin', LANG: 'en_US.UTF-8' } });
+            let result, finished = false, dispatched = false;
+            const cancel = () => { if (dispatched && child.connected)
+                child.send({ type: 'cancel' }, () => { }); };
+            options.signal?.addEventListener('abort', cancel, { once: true });
+            child.on('message', (message) => {
+                if (message?.type === 'result' && dispatched)
+                    result = message.result;
+                if (message?.type === 'ready' && message.ticket === ticket && !dispatched) {
+                    dispatched = true;
+                    child.send({ type: 'run', ticket, attemptId, executable, args, options: { cwd: options.cwd, env: options.env, deadlineMs: options.deadlineMs, maxOutputBytes: options.maxOutputBytes, graceMs: options.graceMs } }, () => { if (options.signal?.aborted)
+                        cancel(); });
+                }
+            });
+            const finish = async () => {
+                if (finished)
+                    return;
+                finished = true;
+                options.signal?.removeEventListener('abort', cancel);
+                let settled = false;
+                try {
+                    const receipt = await readJournal(join(root, ticket + '.settled.json'));
+                    settled = receipt.ticket === ticket && receipt.attemptId === attemptId && receipt.ownerIncarnation === ownerIncarnation && receipt.cleanup === 'settled';
+                }
+                catch { }
+                resolve(result && settled ? result : { code: null, stdout: '', stopped: options.signal?.aborted ? 'cancelled' : 'unavailable', cleanup: 'pending' });
+            };
+            child.once('error', () => void finish());
+            child.once('exit', () => void finish());
+        });
+    };
+}

package/native/runtime-manifest.json

@@ -0,0 +1,40 @@
+{
+  "architecture": "arm64",
+  "artifacts": [
+    {
+      "bytes": 1421832,
+      "name": "sponge-speech-macos26-arm64",
+      "role": "asr-helper",
+      "sha256": "aee98a6f8f3273237e1ec3c899021a2e3d826a14af843e96a770db25f7b1d7ce"
+    },
+    {
+      "bytes": 35920,
+      "name": "sponge-embedding-macos26-arm64",
+      "role": "embedding-helper",
+      "sha256": "aa5a1bffb45ff2a8823a7c7dd013400ce447d6f080c716eae3f1aba9e9ab7489"
+    },
+    {
+      "bytes": 137802416,
+      "name": "libCLiteRTLM_mac.dylib",
+      "role": "embedding-library",
+      "sha256": "9526db9ee35e7eb4a5a58ac1e53330032f22a13890bd4ee01818fb380a57a362"
+    },
+    {
+      "bytes": 23486,
+      "name": "native-NOTICES.txt",
+      "role": "notices",
+      "sha256": "6e62f14bd094001b8da42af6fc42877e51b0d5616ae960917ef214fc45767088"
+    }
+  ],
+  "build": {
+    "asrSourceSha256": "945667d78c598c30293f666d6605c9af26818b8d313c2219ac95985807c00ffc",
+    "clangVersion": "Apple clang version 21.0.0 (clang-2100.1.1.101)",
+    "embeddingSourceSha256": "e31b9a70865c3c7195d201233a2a240fc7ef2aa40b4ae63291d1277262456c69",
+    "swiftVersion": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)"
+  },
+  "minimumMacOS": "26.0",
+  "packageVersion": "0.2.0",
+  "platform": "darwin",
+  "schemaVersion": 1,
+  "sourceCommit": "439d0bd72f834a26a248ce2e9fee1a6a6bffaf57"
+}