@hraness/sponge 0.2.6 → 0.3.1

package/dist/src/worker/lock.js

@@ -0,0 +1,196 @@
+import { constants } from 'node:fs';
+import { open, link, lstat, rename, unlink, readdir, rm } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readJournal } from './journal.js';
+import { syncDirectoryAsync } from '../util/fsync.js';
+import { processIdentity, identityAlive } from './identity.js';
+import { SpongeError } from '../errors.js';
+const code = (error) => error.code;
+const busy = () => new SpongeError('owner-busy');
+const ownerName = (lock, pid, incarnation) => `.${basename(lock)}.${pid}.${incarnation}.owner`;
+const ownerPattern = (lock) => new RegExp(`^\\.${basename(lock).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.(\\d{1,10})\\.([0-9a-f-]{36})\\.owner$`);
+function record(value) {
+    return value?.schemaVersion === 1 &&
+        value.kind === 'identity-lock' &&
+        typeof value.incarnation === 'string' &&
+        /^[0-9a-f-]{36}$/.test(value.incarnation) &&
+        Number.isSafeInteger(value.identity?.pid) &&
+        value.identity.pid > 0 &&
+        value.identity.uid === process.getuid?.() &&
+        typeof value.identity.started === 'string' &&
+        value.identity.started.trim()
+        ? value
+        : null;
+}
+/** Exact death proof, or false: an unavailable process table means unknown, never dead. */
+async function provablyDead(identity) {
+    try {
+        return !(await identityAlive(identity));
+    }
+    catch {
+        return false;
+    }
+}
+/** The recorded holder of `path`, when it is a well-formed identity lock; null for legacy, foreign or unreadable locks. */
+export async function lockHolder(path) {
+    try {
+        return record(await readJournal(path));
+    }
+    catch {
+        return null;
+    }
+}
+/** Remove one stale lock, compare-and-swap style: rename it aside and keep it removed only if it is the exact inode
+ * judged dead. Anything else is relinked (if the slot is still free) and reported busy. */
+async function takeOver(path) {
+    const dir = dirname(path);
+    let before;
+    try {
+        before = await lstat(path);
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return true;
+        throw error;
+    }
+    if (!before.isFile() || before.isSymbolicLink())
+        return false;
+    const holder = await lockHolder(path);
+    if (!holder)
+        return false;
+    try {
+        const again = await lstat(path);
+        if (again.ino !== before.ino || again.dev !== before.dev)
+            return false;
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return true;
+        throw error;
+    }
+    if (!(await provablyDead(holder.identity)))
+        return false;
+    const aside = join(dir, `.${basename(path)}.stale-${randomUUID()}`);
+    try {
+        await rename(path, aside);
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return true;
+        throw error;
+    }
+    const moved = await lstat(aside);
+    if (moved.ino !== before.ino || moved.dev !== before.dev) {
+        try {
+            await link(aside, path);
+        }
+        catch {
+            /* the slot was taken again; its holder keeps it */
+        }
+        await unlink(aside);
+        await syncDirectoryAsync(dir);
+        return false;
+    }
+    await unlink(aside);
+    const owner = join(dir, ownerName(path, holder.identity.pid, holder.incarnation));
+    try {
+        const s = await lstat(owner);
+        if (s.isFile() && s.ino === before.ino && s.dev === before.dev)
+            await unlink(owner);
+    }
+    catch (error) {
+        if (code(error) !== 'ENOENT')
+            throw error;
+    }
+    await syncDirectoryAsync(dir);
+    return true;
+}
+/** Owner files that never became (or no longer are) a lock, written by a process that is provably dead. */
+async function sweepOwners(path, keep) {
+    const dir = dirname(path), pattern = ownerPattern(path);
+    let removed = false;
+    for (const name of await readdir(dir)) {
+        const match = pattern.exec(name);
+        if (!match || name === keep)
+            continue;
+        const file = join(dir, name);
+        try {
+            const s = await lstat(file);
+            if (!s.isFile() || s.nlink !== 1 || s.uid !== process.getuid?.())
+                continue;
+            const holder = await lockHolder(file);
+            // A torn write has no readable identity: only a pid with no process at all proves its writer is gone.
+            if (holder
+                ? await provablyDead(holder.identity)
+                : await processIdentity(Number(match[1])).then((x) => x === null, () => false)) {
+                const again = await lstat(file);
+                if (again.nlink === 1 && again.ino === s.ino) {
+                    await unlink(file);
+                    removed = true;
+                }
+            }
+        }
+        catch (error) {
+            if (code(error) !== 'ENOENT')
+                throw error;
+        }
+    }
+    if (removed)
+        await syncDirectoryAsync(dir);
+}
+export async function acquireIdentityLock(path) {
+    const dir = dirname(path), identity = await processIdentity(process.pid);
+    if (!identity)
+        throw new SpongeError('unavailable');
+    const incarnation = randomUUID(), file = join(dir, ownerName(path, identity.pid, incarnation));
+    const handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        try {
+            await handle.writeFile(JSON.stringify({ schemaVersion: 1, kind: 'identity-lock', incarnation, identity }));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        for (let attempt = 0;; attempt++) {
+            try {
+                await link(file, path);
+                await syncDirectoryAsync(dir);
+                break;
+            }
+            catch (error) {
+                if (code(error) !== 'EEXIST')
+                    throw error;
+            }
+            if (attempt > 1 || !(await takeOver(path)))
+                throw busy();
+        }
+    }
+    catch (error) {
+        await rm(file, { force: true });
+        await syncDirectoryAsync(dir);
+        throw error;
+    }
+    await sweepOwners(path, basename(file));
+    return {
+        path,
+        release: async () => {
+            let held = false;
+            try {
+                const [a, b] = await Promise.all([lstat(file), lstat(path)]);
+                held = a.ino === b.ino && a.dev === b.dev;
+            }
+            catch (error) {
+                if (code(error) !== 'ENOENT')
+                    throw error;
+            }
+            if (held)
+                await unlink(path);
+            await unlink(file);
+            await syncDirectoryAsync(dir);
+            if (!held)
+                throw new SpongeError('integrity');
+        },
+    };
+}

package/dist/src/worker/runtime-gc.d.ts

@@ -1,11 +1,11 @@
 import { type LibraryStore } from '../store/index.js';
-export type RuntimeKind = 'capture' | 'model' | 'worker';
-export interface RuntimeEntry {
+type RuntimeKind = 'capture' | 'model' | 'worker';
+interface RuntimeEntry {
     kind: RuntimeKind;
     name: string;
     bytes: number;
 }
-export interface RuntimeKept {
+interface RuntimeKept {
     kind: RuntimeKind;
     name: string;
     reason: 'referenced' | 'in-use' | 'symlink' | 'foreign' | 'catalog-unavailable' | 'current-missing';
@@ -28,3 +28,4 @@ export interface RuntimeGcOptions {
  * Applying holds worker custody, so no worker, capture, import verification, index run or query
  * can start or be running; each model directory is additionally taken under its setup lock. */
 export declare function collectRuntimes(store: LibraryStore, options: RuntimeGcOptions): Promise<RuntimeGcReport>;
+export {};

package/dist/src/worker/runtime-gc.js

@@ -1,19 +1,25 @@
 import { constants } from 'node:fs';
 import { lstat, readdir, realpath, rename, rm, link, unlink, open } from 'node:fs/promises';
 import { join } from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
-import { StoreError } from '../store/index.js';
+import { randomUUID } from 'node:crypto';
+import { sha256 } from '../util/hash.js';
 import { modelSetupPlan } from '../models/artifacts.js';
 import { acquireWorkerCustody } from './custody.js';
-import { readJournal, writeJournal, syncDir } from './journal.js';
+import { readJournal, writeJournal } from './journal.js';
+import { syncDirectoryAsync } from '../util/fsync.js';
 import { processIdentity, identityAlive } from './identity.js';
+import { SpongeError } from '../errors.js';
 const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
-const patterns = { capture: /^capture-[a-z0-9][a-z0-9.-]{0,99}$/, model: /^[a-f0-9]{64}$/, worker: uuid };
+const patterns = {
+    capture: /^capture-[a-z0-9][a-z0-9.-]{0,99}$/,
+    model: /^[a-f0-9]{64}$/,
+    worker: uuid,
+};
 const helperNames = ['sponge-speech', 'sponge-embedding'];
 const trash = /^\.gc-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 // A worker writes owner.json just after creating its directory; a young unreadable directory may be mid-acquisition.
 const youngMs = 10 * 60 * 1000;
-const integrity = () => new StoreError('integrity');
+const integrity = () => new SpongeError('integrity');
 const missing = (error) => error.code === 'ENOENT';
 /** Disk blocks removing one tree frees, never following links: each inode once, and a file only when all of its
  * hard links are inside the tree (a model artifact shared with a kept package frees nothing). */
@@ -59,19 +65,25 @@ async function parent(path) {
             return null;
         throw error;
     }
-    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || await realpath(path) !== path)
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        stat.uid !== process.getuid?.() ||
+        (stat.mode & 0o077) !== 0 ||
+        (await realpath(path)) !== path)
         throw integrity();
     return path;
 }
-async function exists(path) { try {
-    await lstat(path);
-    return true;
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw error;
+    }
 }
-catch (error) {
-    if (missing(error))
-        return false;
-    throw error;
-} }
 async function fileSha256(path, maxBytes) {
     let file;
     try {
@@ -84,7 +96,7 @@ async function fileSha256(path, maxBytes) {
         const stat = await file.stat();
         if (!stat.isFile() || stat.size > maxBytes)
             return null;
-        return createHash('sha256').update(await file.readFile()).digest('hex');
+        return sha256(await file.readFile());
     }
     finally {
         await file.close();
@@ -123,9 +135,9 @@ async function remove(candidate) {
         await rename(moved, path);
         return false;
     }
-    await syncDir(candidate.dir);
+    await syncDirectoryAsync(candidate.dir);
     await rm(moved, { recursive: true });
-    await syncDir(candidate.dir);
+    await syncDirectoryAsync(candidate.dir);
     return true;
 }
 async function workerInUse(dir, name) {
@@ -151,26 +163,30 @@ async function workerInUse(dir, name) {
  * can start or be running; each model directory is additionally taken under its setup lock. */
 export async function collectRuntimes(store, options) {
     const dryRun = options.dryRun === true, base = await realpath(store.root), runtime = await parent(join(base, 'runtime'));
-    if (store.ownerSnapshot())
-        throw new StoreError('owner-busy');
-    if (store.pendingCleanupCount())
-        throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+    if (store.queue.ownerSnapshot())
+        throw new SpongeError('owner-busy');
+    if (store.queue.pendingCleanup())
+        throw new SpongeError('cleanup-required');
     const lockPath = join(base, 'runtime', 'worker.lock');
     // Checked first so a refused collection leaves no custody journal; acquisition stays the authority.
     if (await exists(lockPath))
-        throw new StoreError('owner-busy');
+        throw new SpongeError('owner-busy');
     const custody = dryRun || !runtime ? undefined : await acquireWorkerCustody(base);
     const removed = [], kept = [];
     try {
         if (!runtime)
             return { dryRun, removed, kept, bytes: 0 };
         // Recheck under custody: an owner that appeared before our lock still blocks.
-        if (store.ownerSnapshot())
-            throw new StoreError('owner-busy');
-        if (store.pendingCleanupCount())
-            throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
-        const dirs = { capture: await parent(join(runtime, 'capture')), model: await parent(join(runtime, 'models')), worker: await parent(join(runtime, 'workers')) };
-        const references = store.runtimeReferences(), models = options.models;
+        if (store.queue.ownerSnapshot())
+            throw new SpongeError('owner-busy');
+        if (store.queue.pendingCleanup())
+            throw new SpongeError('cleanup-required');
+        const dirs = {
+            capture: await parent(join(runtime, 'capture')),
+            model: await parent(join(runtime, 'models')),
+            worker: await parent(join(runtime, 'workers')),
+        };
+        const references = store.blobs.runtimeReferences(), models = options.models;
         const modelKeep = new Set(models?.fingerprints ?? []);
         for (const artifact of references.modelArtifacts) {
             if (patterns.model.test(artifact.id))
@@ -178,22 +194,24 @@ export async function collectRuntimes(store, options) {
             try {
                 modelKeep.add(modelSetupPlan(JSON.parse(artifact.manifest)).fingerprint);
             }
-            catch { /* An unparsable row still pins its id. */ }
+            catch {
+                /* An unparsable row still pins its id. */
+            }
         }
         // A generation's helper is satisfied only by an installed kept package, never by an uninstalled catalog entry.
         const helpers = new Set(references.embeddingHelpers), installed = new Set();
         for (const fp of modelKeep) {
-            if (!dirs.model || !await exists(join(dirs.model, fp)))
+            if (!dirs.model || !(await exists(join(dirs.model, fp))))
                 continue;
             for (const helper of helperNames) {
                 if (await exists(join(dirs.model, fp, helper)))
                     installed.add(helper);
             }
-            helpers.delete(await fileSha256(join(dirs.model, fp, 'sponge-embedding'), 32 * 1024 ** 2) ?? '');
+            helpers.delete((await fileSha256(join(dirs.model, fp, 'sponge-embedding'), 32 * 1024 ** 2)) ?? '');
         }
         const take = async (candidate) => {
             const bytes = await diskBytes(join(candidate.dir, candidate.name));
-            if (dryRun || await remove(candidate))
+            if (dryRun || (await remove(candidate)))
                 removed.push({ kind: candidate.kind, name: candidate.name, bytes });
             else
                 kept.push({ kind: candidate.kind, name: candidate.name, reason: 'symlink' });
@@ -219,21 +237,22 @@ export async function collectRuntimes(store, options) {
                 continue;
             }
             const helper = join(dir, name, 'sponge-embedding');
-            if ((references.unmappedSpaces && await exists(helper)) || helpers.size && helpers.has(await fileSha256(helper, 32 * 1024 ** 2) ?? '')) {
+            if ((references.unmappedSpaces && (await exists(helper))) ||
+                (helpers.size && helpers.has((await fileSha256(helper, 32 * 1024 ** 2)) ?? ''))) {
                 kept.push({ kind: 'model', name, reason: 'referenced' });
                 continue;
             }
             // Until this Sponge's package of a kind is installed, older packages of that kind are its only local copy.
             let missingKind = false;
             for (const helper of helperNames)
-                if (!installed.has(helper) && await exists(join(dir, name, helper)))
+                if (!installed.has(helper) && (await exists(join(dir, name, helper))))
                     missingKind = true;
             if (missingKind) {
                 kept.push({ kind: 'model', name, reason: 'current-missing' });
                 continue;
             }
             const lock = join(dir, `.${name}.lock`);
-            if (await exists(lock) || await exists(join(dir, `.${name}.recovery-lock`))) {
+            if ((await exists(lock)) || (await exists(join(dir, `.${name}.recovery-lock`)))) {
                 kept.push({ kind: 'model', name, reason: 'in-use' });
                 continue;
             }
@@ -246,7 +265,13 @@ export async function collectRuntimes(store, options) {
             if (!identity)
                 throw integrity();
             const incarnation = randomUUID(), ownerFile = join(dir, `.model-owner-${incarnation}.json`);
-            await writeJournal(ownerFile, { schemaVersion: 1, incarnation, fingerprint: name, stage: '.model-install-' + incarnation, identity });
+            await writeJournal(ownerFile, {
+                schemaVersion: 1,
+                incarnation,
+                fingerprint: name,
+                stage: '.model-install-' + incarnation,
+                identity,
+            });
             try {
                 try {
                     await link(ownerFile, lock);
@@ -259,7 +284,7 @@ export async function collectRuntimes(store, options) {
                     throw error;
                 }
                 try {
-                    await syncDir(dir);
+                    await syncDirectoryAsync(dir);
                     await take(candidate);
                 }
                 finally {
@@ -268,14 +293,14 @@ export async function collectRuntimes(store, options) {
             }
             finally {
                 await unlink(ownerFile);
-                await syncDir(dir);
+                await syncDirectoryAsync(dir);
             }
         }
         for (const candidate of await children('worker', dirs.worker, kept)) {
             const { name, dir } = candidate;
             if (name === custody?.incarnation)
                 continue;
-            if (!trash.test(name) && await workerInUse(dir, name)) {
+            if (!trash.test(name) && (await workerInUse(dir, name))) {
                 kept.push({ kind: 'worker', name, reason: 'in-use' });
                 continue;
             }
@@ -288,9 +313,11 @@ export async function collectRuntimes(store, options) {
             await custody.release();
             try {
                 await rm(custody.directory, { recursive: true });
-                await syncDir(join(base, 'runtime', 'workers'));
+                await syncDirectoryAsync(join(base, 'runtime', 'workers'));
+            }
+            catch {
+                /* The next collection removes this settled journal. */
             }
-            catch { /* The next collection removes this settled journal. */ }
         }
     }
 }

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

@@ -13,9 +13,14 @@ 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);
+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);
@@ -23,11 +28,19 @@ process.once('message', async (message) => {
     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' });
+        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(); });
+process.on('message', (message) => {
+    if (message?.type === 'cancel')
+        abort();
+});
 if (process.connected)
     process.send({ type: 'ready', ticket: pending.ticket });

package/dist/src/worker/supervisor.js

@@ -12,19 +12,41 @@ export function supervisedRunner(ownerDirectory, ownerIncarnation, attemptId) {
         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' } });
+        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' }, () => { }); };
+            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(); });
+                    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 () => {
@@ -35,10 +57,21 @@ export function supervisedRunner(ownerDirectory, ownerIncarnation, attemptId) {
                 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';
+                    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' });
+                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

@@ -27,14 +27,14 @@
     }
   ],
   "build": {
-    "asrSourceSha256": "e944e4e0b1c2cf571e78a83fcfbf56a91a14fd08dcc701562d32555cf090ec40",
+    "asrSourceSha256": "94b9303afcf9304e695c37411cef065e9cc45a31e0e51cd171819cbfc9ee3955",
     "clangVersion": "Apple clang version 21.0.0 (clang-2100.1.1.101)",
-    "embeddingSourceSha256": "7d58718911725b3c3dce35a09a253704b4e5e732cf1e23c12389485127534b10",
+    "embeddingSourceSha256": "eed7e110bc888af99e0d6e614275cea7a7dbaa56f88d3de9bdd04cc9ff4cfa45",
     "swiftVersion": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)"
   },
   "minimumMacOS": "26.0",
-  "packageVersion": "0.2.6",
+  "packageVersion": "0.3.1",
   "platform": "darwin",
   "schemaVersion": 1,
-  "sourceCommit": "1190f23ad793985b6934583c5d8b0957d79a4ce0"
+  "sourceCommit": "b8975aff1dc06e398c3f78811e76f4ff875729a1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/sponge",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "A local library for captured articles and verified offline assets.",
   "repository": {
     "type": "git",
@@ -30,6 +30,8 @@
     "check": "node --check bin/sponge.js",
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
+    "cycles": "madge --circular --extensions ts src",
+    "deadcode": "knip --no-progress",
     "test": "node --import tsx --test --test-isolation=none test/*/*.test.ts",
     "probe": "node --import tsx scripts/probes/cli.ts",
     "prepack": "npm run build",
@@ -38,11 +40,17 @@
     "verify:pdf": "node --import tsx scripts/verify-pdf.ts",
     "verify:import": "node --import tsx scripts/verify-import.ts",
     "verify:installed": "node --import tsx scripts/verify-installed.ts",
-    "verify:installed-native": "node --import tsx scripts/verify-installed-native.ts"
+    "verify:installed-native": "node --import tsx scripts/verify-installed-native.ts",
+    "format": "prettier --write \"{bin,contracts,migrations,scripts,src,test}/**/*.{ts,js,mjs}\"",
+    "format:check": "prettier --check \"{bin,contracts,migrations,scripts,src,test}/**/*.{ts,js,mjs}\""
   },
   "packageManager": "npm@11.19.0",
   "devDependencies": {
+    "@types/mdast": "4.0.4",
     "@types/node": "24.10.1",
+    "knip": "6.39.0",
+    "madge": "8.0.0",
+    "prettier": "3.9.10",
     "tsx": "4.20.6",
     "typescript": "5.9.3"
   },