@hraness/sponge 0.3.5 → 0.4.1

package/dist/src/worker/custody.js

@@ -116,6 +116,9 @@ async function sweepTemps(path, depth = 2) {
     if (removed)
         await syncDirectoryAsync(path);
 }
+/** Attempts outside the job tables: a search query, an import verification, a digest server. Each writes `KIND.json`
+ * under its attempt and `staging/KIND-ID/ownership.json`. */
+const transientKinds = ['query', 'import-verification', 'digest-server'];
 export async function recoverWorker(store, options = {}) {
     const lock = join(store.root, 'runtime', 'worker.lock');
     let record;
@@ -171,7 +174,7 @@ export async function recoverWorker(store, options = {}) {
             identifier(id);
             if (!attemptIds.has(id)) {
                 let marker;
-                for (const kind of ['query', 'import-verification']) {
+                for (const kind of transientKinds) {
                     try {
                         const candidate = await readJournal(join(ownerDirectory, 'attempts', id, kind + '.json'));
                         if (marker || candidate.kind !== kind)
@@ -189,7 +192,7 @@ export async function recoverWorker(store, options = {}) {
                 }
                 else {
                     if (marker.schemaVersion !== 1 ||
-                        !['query', 'import-verification'].includes(marker.kind) ||
+                        !transientKinds.includes(marker.kind) ||
                         marker.attemptId !== id ||
                         marker.ownerIncarnation !== record.incarnation)
                         throw pending();
@@ -201,7 +204,7 @@ export async function recoverWorker(store, options = {}) {
         }
         const staging = join(store.root, 'staging');
         for (const entry of await readdir(staging)) {
-            if (entry.startsWith('query-') || entry.startsWith('import-verification-')) {
+            if (transientKinds.some((kind) => entry.startsWith(kind + '-'))) {
                 const path = join(staging, entry);
                 await directory(path);
                 let marker;
@@ -212,7 +215,7 @@ export async function recoverWorker(store, options = {}) {
                     throw pending();
                 }
                 if (marker.schemaVersion !== 1 ||
-                    !['query', 'import-verification'].includes(marker.kind) ||
+                    !transientKinds.includes(marker.kind) ||
                     typeof marker.requestId !== 'string' ||
                     entry !== marker.kind + '-' + marker.requestId ||
                     typeof marker.ownerIncarnation !== 'string')

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

@@ -0,0 +1,17 @@
+import { type TransientKind } from './custody.js';
+import { type ProcessRunner } from './supervisor.js';
+export interface TransientAttempt {
+    attemptId: string;
+    /** The custody incarnation, for `queue.acquireOwner` when the attempt also claims jobs. */
+    incarnation: string;
+    ownerDirectory: string;
+    scratchRoot: string;
+    /** Runs helpers under the worker supervisor, so their process groups are proved collected. */
+    runProcess: ProcessRunner;
+}
+/**
+ * One custody-held attempt outside the job tables. It writes `KIND.json` under the attempt and an ownership marker in
+ * `staging/KIND-ID` (what `recoverWorker` expects), proves every helper collected, removes the scratch root and
+ * releases custody. Unproven cleanup keeps custody and throws `cleanup-required`. Mutates coordination journals only.
+ */
+export declare function withTransientAttempt<T>(libraryRoot: string, kind: TransientKind, fn: (attempt: TransientAttempt) => Promise<T>): Promise<T>;

package/dist/src/worker/transient.js

@@ -0,0 +1,60 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { rm } from 'node:fs/promises';
+import { acquireWorkerCustody, proveAttemptCleanup } from './custody.js';
+import { directory, writeJournal, readJournal } from './journal.js';
+import { supervisedRunner } from './supervisor.js';
+import { syncDirectoryAsync } from '../util/fsync.js';
+import { SpongeError, codeOf } from '../errors.js';
+/**
+ * One custody-held attempt outside the job tables. It writes `KIND.json` under the attempt and an ownership marker in
+ * `staging/KIND-ID` (what `recoverWorker` expects), proves every helper collected, removes the scratch root and
+ * releases custody. Unproven cleanup keeps custody and throws `cleanup-required`. Mutates coordination journals only.
+ */
+export async function withTransientAttempt(libraryRoot, kind, fn) {
+    const custody = await acquireWorkerCustody(libraryRoot), attemptId = randomUUID();
+    let scratchRoot, cleanupUnknown = false;
+    try {
+        const attempts = await directory(join(custody.directory, 'attempts', attemptId));
+        await writeJournal(join(attempts, kind + '.json'), {
+            schemaVersion: 1,
+            kind,
+            attemptId,
+            ownerIncarnation: custody.incarnation,
+        });
+        scratchRoot = await directory(join(libraryRoot, 'staging', `${kind}-${attemptId}`));
+        await writeJournal(join(scratchRoot, 'ownership.json'), {
+            schemaVersion: 1,
+            kind,
+            requestId: attemptId,
+            ownerIncarnation: custody.incarnation,
+        });
+        return await fn({
+            attemptId,
+            incarnation: custody.incarnation,
+            ownerDirectory: custody.directory,
+            scratchRoot,
+            runProcess: supervisedRunner(custody.directory, custody.incarnation, attemptId),
+        });
+    }
+    catch (error) {
+        cleanupUnknown = codeOf(error) === 'cleanup-required';
+        throw error;
+    }
+    finally {
+        const proved = !cleanupUnknown && (await proveAttemptCleanup(custody.directory, custody.incarnation, attemptId));
+        if (!proved)
+            throw new SpongeError('cleanup-required');
+        if (scratchRoot) {
+            const marker = await readJournal(join(scratchRoot, 'ownership.json'));
+            if (marker.schemaVersion !== 1 ||
+                marker.kind !== kind ||
+                marker.requestId !== attemptId ||
+                marker.ownerIncarnation !== custody.incarnation)
+                throw new SpongeError('cleanup-required');
+            await rm(scratchRoot, { recursive: true });
+            await syncDirectoryAsync(join(libraryRoot, 'staging'));
+        }
+        await custody.release();
+    }
+}

package/native/runtime-manifest.json

@@ -27,14 +27,14 @@
     }
   ],
   "build": {
-    "asrSourceSha256": "3b32718d4626aff97f2c3e043c9fd020f237adc7f7e5508e7d7b99a555762982",
+    "asrSourceSha256": "6a84b1b2040f17cb510a71548c1453442df15f820ceb0ac8cec3086b4ccefbdc",
     "clangVersion": "Apple clang version 21.0.0 (clang-2100.1.1.101)",
-    "embeddingSourceSha256": "66f008ea29050d114b0df74337124bac8f6cdba9732e257cc70ad85eb9ebee6f",
+    "embeddingSourceSha256": "b029dadccaeba029fb9ef302daaefc6a134e8d46440c1e8c227f374d97202ce3",
     "swiftVersion": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)"
   },
   "minimumMacOS": "26.0",
-  "packageVersion": "0.3.5",
+  "packageVersion": "0.4.1",
   "platform": "darwin",
   "schemaVersion": 1,
-  "sourceCommit": "49b3f7f100cdbcbf5f52418d28c53dc13f198424"
+  "sourceCommit": "82fefa4ca18700e2e7390e1372c7c672ddac11fa"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/sponge",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "A local library for captured articles and verified offline assets.",
   "repository": {
     "type": "git",