@hraness/sponge 0.2.6 → 0.3.0

package/dist/src/identity/uri.js

@@ -6,21 +6,27 @@ export function shareableWebUri(locator) {
     const url = new URL(normalizeWebLocator(locator));
     url.hash = '';
     if (url.search)
-        url.search = filterQuery(url.search, key => clickTrackers.has(key) || isSecretField(key));
+        url.search = filterQuery(url.search, (key) => clickTrackers.has(key) || isSecretField(key));
     return url.href;
 }
 const youtubeId = /^[A-Za-z0-9_-]{11}$/;
-const decoded = (value) => { try {
-    return decodeURIComponent(value);
-}
-catch {
-    return undefined;
-} };
+const decoded = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+};
 /** Provider identifiers name the same work across URL spellings, hosts and mirrors. */
-export function providerUris(href) {
+function providerUris(href) {
     const url = new URL(href), host = url.hostname.replace(/^(www|m|mobile)\./, ''), parts = url.pathname.split('/').filter(Boolean), out = [];
     if (host === 'youtube.com' || host === 'music.youtube.com') {
-        const id = url.pathname === '/watch' ? url.searchParams.get('v') : ['shorts', 'live', 'embed'].includes(parts[0]) ? parts[1] : undefined;
+        const id = url.pathname === '/watch'
+            ? url.searchParams.get('v')
+            : ['shorts', 'live', 'embed'].includes(parts[0])
+                ? parts[1]
+                : undefined;
         if (id && youtubeId.test(id))
             out.push('youtube:' + id);
     }
@@ -29,7 +35,11 @@ export function providerUris(href) {
     if ((host === 'x.com' || host === 'twitter.com') && parts[1] === 'status' && /^\d{1,25}$/.test(parts[2] ?? ''))
         out.push('x:status/' + parts[2]);
     if (host === 'arxiv.org' && ['abs', 'pdf'].includes(parts[0]) && parts[1]) {
-        const id = parts.slice(1).join('/').replace(/\.pdf$/, '').replace(/v\d+$/, '');
+        const id = parts
+            .slice(1)
+            .join('/')
+            .replace(/\.pdf$/, '')
+            .replace(/v\d+$/, '');
         if (/^(\d{4}\.\d{4,5}|[a-z-]+(\.[A-Z]{2})?\/\d{7})$/.test(id))
             out.push('arxiv:' + id);
     }
@@ -40,7 +50,9 @@ export function providerUris(href) {
     }
     return out;
 }
-export function isResolvable(uri) { return /^(https?:|doi:|arxiv:|isbn:|youtube:|x:)/.test(uri); }
+export function isResolvable(uri) {
+    return /^(https?:|doi:|arxiv:|isbn:|youtube:|x:)/.test(uri);
+}
 /**
  * Derive an item's URIs from its first source and, once captured, its source PDF. Total: a
  * locator that cannot be parsed, carries userinfo or is too long yields only `sponge:item/<id>`.
@@ -48,8 +60,10 @@ export function isResolvable(uri) { return /^(https?:|doi:|arxiv:|isbn:|youtube:
  * `urn:sha256:<file hash>`, which matches the same file anywhere but is not resolvable.
  */
 export function deriveUris(input) {
-    const out = [], add = (uri, origin) => { if (uri.length >= 3 && Buffer.byteLength(uri) <= maxUriBytes && !out.some(u => u.uri === uri))
-        out.push({ uri, role: out.length ? 'alias' : 'primary', resolvable: isResolvable(uri), origin }); };
+    const out = [], add = (uri, origin) => {
+        if (uri.length >= 3 && Buffer.byteLength(uri) <= maxUriBytes && !out.some((u) => u.uri === uri))
+            out.push({ uri, role: out.length ? 'alias' : 'primary', resolvable: isResolvable(uri), origin });
+    };
     if (/^https?:/i.test(input.locator)) {
         let web;
         try {
@@ -64,7 +78,9 @@ export function deriveUris(input) {
                 for (const uri of providerUris(web))
                     add(uri, 'locator');
             }
-            catch { /* a provider alias is optional */ }
+            catch {
+                /* a provider alias is optional */
+            }
         }
     }
     if (input.sourcePdfSha256)
@@ -73,10 +89,13 @@ export function deriveUris(input) {
         add('sponge:item/' + input.itemId, 'locator');
     return out;
 }
-/** How the first source was reached decides the default visibility; see docs/decisions/sync-and-publishing.md. */
-export function accessClass(realm, locator) {
-    if (locator.startsWith('file:'))
-        return 'local';
+/**
+ * How the first source was reached decides the default visibility; see docs/decisions/sync-and-publishing.md.
+ * An imported local file with a recorded web address (`webUri`, origin 'metadata') is classed by that address instead.
+ */
+export function accessClass(realm, locator, webUri) {
+    if (/^(file|local):/i.test(locator))
+        return realm.startsWith('import:') && webUri && /^https?:/i.test(webUri) ? accessClass(realm, webUri) : 'local';
     if (realm.startsWith('connection:'))
         return 'account';
     // A guard on top of the source rule: a link that is itself a credential is never public by default.

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

@@ -1,6 +1,15 @@
 import type { DatabaseSync } from 'node:sqlite';
 import { type AccessClass, type ItemUri } from './uri.js';
 export type Visibility = 'public' | 'private';
+/** The recorded web address of a capture that has none of its own (origin 'metadata', primary), if any. */
+export declare function metadataUri(db: DatabaseSync, itemId: string): string | undefined;
+/** Whether the capture itself (its locator or revision) yields a web URI. */
+export declare function hasWebUri(db: DatabaseSync, itemId: string): boolean;
+/**
+ * Record `uri` (already a shareable web URI) as the primary of a capture without a web URI of its own; derived URIs become
+ * aliases and a previously recorded primary is replaced. Idempotent. Derived state like every item URI, not a logged field.
+ */
+export declare function setMetadataUri(db: DatabaseSync, itemId: string, uri: string): void;
 /** Recompute derived URIs; metadata and user URIs are left alone. Idempotent. */
 export declare function syncUris(db: DatabaseSync, itemId: string): void;
 /**
@@ -20,5 +29,6 @@ export interface VisibilityState {
     override: Visibility | null;
     effective: Visibility;
 }
-export declare function visibility(db: DatabaseSync, itemId: string): VisibilityState;
+/** `webUri` previews a metadata URI not yet recorded; by default the recorded one counts. */
+export declare function visibility(db: DatabaseSync, itemId: string, webUri?: string | undefined): VisibilityState;
 export declare function setVisibility(db: DatabaseSync, itemId: string, value: Visibility | null): VisibilityState;

package/dist/src/identity/visibility.js

@@ -1,24 +1,71 @@
-import { accessClass, defaultVisibility, deriveUris } from './uri.js';
+import { accessClass, defaultVisibility, deriveUris, maxUriBytes } from './uri.js';
 import { mutate } from '../store/changes.js';
-import { StoreError } from '../store/types.js';
 import { text } from '../store/files.js';
-const fail = (code = 'invalid-input') => { throw new StoreError(code); };
-function firstSource(db, itemId) { return db.prepare('SELECT realm_key,locator FROM source_refs WHERE item_id=? ORDER BY rowid LIMIT 1').get(itemId); }
+import { SpongeError } from '../errors.js';
+const fail = (code = 'invalid-input') => {
+    throw new SpongeError(code);
+};
+function firstSource(db, itemId) {
+    return db.prepare('SELECT realm_key,locator FROM source_refs WHERE item_id=? ORDER BY rowid LIMIT 1').get(itemId);
+}
+/** The recorded web address of a capture that has none of its own (origin 'metadata', primary), if any. */
+export function metadataUri(db, itemId) {
+    const r = db
+        .prepare("SELECT uri FROM item_uris WHERE item_id=? AND origin='metadata' AND role='primary'")
+        .get(itemId);
+    return r && /^https?:/.test(String(r.uri)) ? String(r.uri) : undefined;
+}
+/** Whether the capture itself (its locator or revision) yields a web URI. */
+export function hasWebUri(db, itemId) {
+    return !!db
+        .prepare("SELECT 1 FROM item_uris WHERE item_id=? AND origin IN ('locator','revision') AND (uri LIKE 'http:%' OR uri LIKE 'https:%')")
+        .get(itemId);
+}
+/**
+ * Record `uri` (already a shareable web URI) as the primary of a capture without a web URI of its own; derived URIs become
+ * aliases and a previously recorded primary is replaced. Idempotent. Derived state like every item URI, not a logged field.
+ */
+export function setMetadataUri(db, itemId, uri) {
+    text(uri, maxUriBytes);
+    if (!/^https?:/.test(uri) || hasWebUri(db, itemId))
+        fail();
+    if (metadataUri(db, itemId) === uri)
+        return;
+    db.prepare("DELETE FROM item_uris WHERE item_id=? AND origin='metadata' AND role='primary'").run(itemId);
+    db.prepare("UPDATE item_uris SET role='alias' WHERE item_id=?").run(itemId);
+    db.prepare("INSERT INTO item_uris VALUES(?,?,'primary',1,'metadata') ON CONFLICT(item_id,uri) DO UPDATE SET role='primary',resolvable=1,origin='metadata'").run(itemId, uri);
+}
 /** Recompute derived URIs; metadata and user URIs are left alone. Idempotent. */
 export function syncUris(db, itemId) {
     const source = firstSource(db, itemId);
     if (!source)
         return;
-    const pdf = db.prepare("SELECT ra.sha256 FROM items i JOIN revision_assets ra ON ra.revision_id=i.current_revision WHERE i.id=? AND ra.relationship='source-pdf' ORDER BY ra.ordinal LIMIT 1").get(itemId);
-    const uris = deriveUris({ itemId, locator: String(source.locator), ...(pdf ? { sourcePdfSha256: String(pdf.sha256) } : {}) });
-    const current = db.prepare("SELECT uri,role,resolvable,origin FROM item_uris WHERE item_id=? AND origin IN ('locator','revision') ORDER BY uri").all(itemId).map(r => `${r.uri}|${r.role}|${r.resolvable}|${r.origin}`).join('\n');
-    const next = uris.map(u => `${u.uri}|${u.role}|${Number(u.resolvable)}|${u.origin}`).sort().join('\n');
+    const pdf = db
+        .prepare("SELECT ra.sha256 FROM items i JOIN revision_assets ra ON ra.revision_id=i.current_revision WHERE i.id=? AND ra.relationship='source-pdf' ORDER BY ra.ordinal LIMIT 1")
+        .get(itemId);
+    const uris = deriveUris({
+        itemId,
+        locator: String(source.locator),
+        ...(pdf ? { sourcePdfSha256: String(pdf.sha256) } : {}),
+    });
+    // A capture without a web URI keeps a recorded web address as its primary; its derived URIs are then aliases.
+    const kept = !uris.some((u) => /^https?:/.test(u.uri)) && metadataUri(db, itemId), rows = kept ? uris.map((u) => ({ ...u, role: 'alias' })) : uris;
+    const current = db
+        .prepare("SELECT uri,role,resolvable,origin FROM item_uris WHERE item_id=? AND origin IN ('locator','revision') ORDER BY uri")
+        .all(itemId)
+        .map((r) => `${r.uri}|${r.role}|${r.resolvable}|${r.origin}`)
+        .join('\n');
+    const next = rows
+        .map((u) => `${u.uri}|${u.role}|${Number(u.resolvable)}|${u.origin}`)
+        .sort()
+        .join('\n');
     if (current === next)
         return;
     db.prepare("DELETE FROM item_uris WHERE item_id=? AND origin IN ('locator','revision')").run(itemId);
     // A derived primary replaces any other primary; keep later metadata/user URIs as aliases.
-    db.prepare("UPDATE item_uris SET role='alias' WHERE item_id=?").run(itemId);
-    for (const u of uris)
+    if (!kept)
+        db.prepare("UPDATE item_uris SET role='alias' WHERE item_id=?").run(itemId);
+    for (const u of rows)
         db.prepare('INSERT INTO item_uris VALUES(?,?,?,?,?) ON CONFLICT(item_id,uri) DO UPDATE SET role=excluded.role,resolvable=excluded.resolvable,origin=excluded.origin').run(itemId, u.uri, u.role, Number(u.resolvable), u.origin);
 }
 /**
@@ -26,7 +73,10 @@ export function syncUris(db, itemId) {
  * one hostile locator leaves that item without URIs instead of making the library unopenable.
  */
 export function backfillUris(db) {
-    const missing = db.prepare("SELECT i.id FROM items i WHERE NOT EXISTS (SELECT 1 FROM item_uris u WHERE u.item_id=i.id AND u.role='primary') AND EXISTS (SELECT 1 FROM source_refs r WHERE r.item_id=i.id)").all().map(r => String(r.id));
+    const missing = db
+        .prepare("SELECT i.id FROM items i WHERE NOT EXISTS (SELECT 1 FROM item_uris u WHERE u.item_id=i.id AND u.role='primary') AND EXISTS (SELECT 1 FROM source_refs r WHERE r.item_id=i.id)")
+        .all()
+        .map((r) => String(r.id));
     let skipped = 0;
     for (const id of missing) {
         db.exec('SAVEPOINT backfill_uri');
@@ -42,26 +92,40 @@ export function backfillUris(db) {
     return { filled: missing.length - skipped, skipped };
 }
 export function itemUris(db, itemId) {
-    return db.prepare("SELECT uri,role,resolvable,origin FROM item_uris WHERE item_id=? ORDER BY role='alias',uri").all(itemId).map(r => ({ uri: String(r.uri), role: r.role, resolvable: !!r.resolvable, origin: r.origin }));
+    return db
+        .prepare("SELECT uri,role,resolvable,origin FROM item_uris WHERE item_id=? ORDER BY role='alias',uri")
+        .all(itemId)
+        .map((r) => ({
+        uri: String(r.uri),
+        role: r.role,
+        resolvable: !!r.resolvable,
+        origin: r.origin,
+    }));
 }
 /** Items sharing any URI with `uri`: the local half of "who else is reading this". */
 export function itemsForUri(db, uri) {
     text(uri, 8192);
-    return db.prepare('SELECT DISTINCT u.item_id FROM item_uris u JOIN items i ON i.id=u.item_id WHERE u.uri=? AND i.deleted_at IS NULL ORDER BY u.item_id').all(uri).map(r => String(r.item_id));
+    return db
+        .prepare('SELECT DISTINCT u.item_id FROM item_uris u JOIN items i ON i.id=u.item_id WHERE u.uri=? AND i.deleted_at IS NULL ORDER BY u.item_id')
+        .all(uri)
+        .map((r) => String(r.item_id));
 }
-export function visibility(db, itemId) {
+/** `webUri` previews a metadata URI not yet recorded; by default the recorded one counts. */
+export function visibility(db, itemId, webUri = metadataUri(db, itemId)) {
     const item = db.prepare('SELECT visibility,deleted_at FROM items WHERE id=?').get(itemId) ?? fail('unavailable'), source = firstSource(db, itemId);
-    const access = source ? accessClass(String(source.realm_key), String(source.locator)) : 'local';
+    const access = source ? accessClass(String(source.realm_key), String(source.locator), webUri) : 'local';
     const reading = db.prepare('SELECT state_json FROM reading_state WHERE item_id=?').get(itemId);
     let importedPrivacy;
     try {
-        importedPrivacy = reading ? JSON.parse(String(reading.state_json))?.sourcePrivacy : undefined;
+        importedPrivacy = reading
+            ? JSON.parse(String(reading.state_json))?.sourcePrivacy
+            : undefined;
     }
     catch {
         importedPrivacy = undefined;
     }
     const base = defaultVisibility(access, importedPrivacy), override = (item.visibility ?? null);
-    return { access, default: base, override, effective: item.deleted_at ? 'private' : override ?? base };
+    return { access, default: base, override, effective: item.deleted_at ? 'private' : (override ?? base) };
 }
 export function setVisibility(db, itemId, value) {
     if (value !== null && value !== 'public' && value !== 'private')

package/dist/src/importers/apply.js

@@ -1,62 +1,108 @@
-import { hash } from '../acquisition/files.js';
-import { failure } from '../acquisition/errors.js';
+import { sha256 as hash } from '../util/hash.js';
+import { runAttempt } from '../ingest/attempt.js';
 import { bundleBytes, bundleText } from '../app/bundle-files.js';
 import { localizeMarkdown } from '../app/markdown.js';
 import { selectedMetadata } from '../metadata/article.js';
 import { drainQueue } from '../worker/engine.js';
 import { readImportManifest, importBundleRoot } from './manifest.js';
 import { inspectImportBundle, releasedBundleVerifier } from './inspect.js';
-const errorCode = (error) => { const code = error?.code ?? (error instanceof Error ? error.message : ''); return ['unsupported', 'invalid-input', 'integrity', 'limit-exceeded', 'cancelled', 'cleanup-required', 'runtime-missing', 'owner-busy', 'unavailable'].includes(code) ? code : 'unclassified'; };
-async function promote(context, bundle, namespace, entry, sourceHash) {
+import { SpongeError, publicCode } from '../errors.js';
+const errorCode = (error) => {
+    const code = publicCode(error);
+    return [
+        'unsupported',
+        'invalid-input',
+        'integrity',
+        'limit-exceeded',
+        'cancelled',
+        'cleanup-required',
+        'runtime-missing',
+        'owner-busy',
+        'unavailable',
+    ].includes(code)
+        ? code
+        : 'unclassified';
+};
+function promote(context, bundle, namespace, entry, sourceHash) {
     const { store, attempt, signal, checkpoint } = context;
-    let committed = false;
-    let result = failure(attempt.attemptId, 'unclassified');
-    try {
-        const source = store.sourceForJob(attempt.jobId);
+    return runAttempt(store, attempt, errorCode, async () => {
+        const source = store.queue.source(attempt.jobId);
         if (!source)
-            throw Error('integrity');
+            throw new SpongeError('integrity');
         await checkpoint('extracting');
         const markdown = await bundleText(bundle.root, bundle.markdown), localized = localizeMarkdown(bundle.kind === 'pdf' ? markdown.replace(/^<!-- pdf-page: ([1-9][0-9]*) -->$/gm, '## Page $1') : markdown, bundle.assets), assets = [];
         for (const asset of bundle.assets) {
             if (signal.aborted)
-                throw Error('cancelled');
-            const stored = await store.putBlob(attempt, asset.sha256, asset.bytes, bundleBytes(bundle.root, asset));
+                throw new SpongeError('cancelled');
+            const stored = await store.blobs.put(attempt, asset.sha256, asset.bytes, bundleBytes(bundle.root, asset));
             assets.push({ ...stored, mediaType: asset.mediaType, relationship: asset.relationship });
         }
         if (signal.aborted)
-            throw Error('cancelled');
+            throw new SpongeError('cancelled');
         await checkpoint('promoting');
         const title = selectedMetadata(bundle.metadata, 'title')?.value;
-        store.commitRevision({ ...attempt, itemId: source.itemId, bundleHash: importBundleHash(sourceHash), markdown: localized.markdown, title: typeof title === 'string' ? title : undefined, extractor: { name: 'sponge-wordcell-import', version: '1' }, status: bundle.status === 'partial' || localized.missingImages ? 'partial' : 'complete', metadata: [...bundle.metadata, ...Object.entries({ importNamespace: namespace, externalSourceId: entry.id, sourcePrivacy: entry.privacy }).map(([field, value]) => ({ field, value, source: bundle.kind === 'pdf' ? 'pdf' : 'html', observedAt: new Date().toISOString(), rule: 'sponge-import-v1' }))], assets, warnings: bundle.status === 'partial' || localized.missingImages ? ['partial'] : [], importedState: { namespace, sourceKey: entry.id, sourceHash, importerVersion: '1', notes: entry.notes, readingState: entry.readingState, privacy: entry.privacy } });
-        committed = true;
-        result = { ok: true, itemId: source.itemId };
-    }
-    catch (error) {
-        result = failure(attempt.attemptId, errorCode(error), 'storage');
-    }
-    if (!committed)
-        store.failAttempt(attempt, result.ok ? 'unclassified' : result.code);
-    store.settleAttempt(attempt);
-    return { ...result, cleanup: 'settled' };
+        store.revisions.commit({
+            ...attempt,
+            itemId: source.itemId,
+            bundleHash: importBundleHash(sourceHash),
+            markdown: localized.markdown,
+            title: typeof title === 'string' ? title : undefined,
+            extractor: { name: 'sponge-wordcell-import', version: '1' },
+            status: bundle.status === 'partial' || localized.missingImages ? 'partial' : 'complete',
+            metadata: [
+                ...bundle.metadata,
+                ...Object.entries({ importNamespace: namespace, externalSourceId: entry.id, sourcePrivacy: entry.privacy }).map(([field, value]) => ({
+                    field,
+                    value,
+                    source: bundle.kind === 'pdf' ? 'pdf' : 'html',
+                    observedAt: new Date().toISOString(),
+                    rule: 'sponge-import-v1',
+                })),
+            ],
+            assets,
+            warnings: bundle.status === 'partial' || localized.missingImages ? ['partial'] : [],
+            importedState: {
+                namespace,
+                sourceKey: entry.id,
+                sourceHash,
+                importerVersion: '1',
+                notes: entry.notes,
+                readingState: entry.readingState,
+                privacy: entry.privacy,
+            },
+        });
+        return { ok: true, itemId: source.itemId };
+    });
 }
 /** One verified bundle: a receipt short-circuits, a dry run stops after verification, otherwise the capture is promoted through the queue. */
 export async function importBundleEntry(store, root, namespace, entry, verify, dryRun, signal) {
-    const bundle = await inspectImportBundle(await importBundleRoot(root, entry), verify), sourceHash = hash(JSON.stringify([bundle.importHash, entry])), receipt = store.lookupImportReceipt(namespace, entry.id, sourceHash);
+    const bundle = await inspectImportBundle(await importBundleRoot(root, entry), verify), sourceHash = hash(JSON.stringify([bundle.importHash, entry])), receipt = store.imports.receipt(namespace, entry.id, sourceHash);
     if (signal?.aborted)
-        throw Object.assign(Error('cancelled'), { code: 'cancelled' });
+        throw new SpongeError('cancelled');
     const base = { sourceHash, historicalIntegrity: bundle.historicalIntegrity };
     if (receipt)
         return { ...base, status: 'duplicate', itemId: receipt.itemId };
     if (dryRun)
         return { ...base, status: 'ready' };
-    const submission = store.submitSource({ kind: bundle.kind, sourceKey: hash(JSON.stringify([namespace, entry.id])), locator: bundle.sourceUrl, realm: 'import:' + namespace, idempotencyKey: 'import:' + hash(JSON.stringify([namespace, entry.id, sourceHash])), intent: 'refresh' });
-    const job = store.listJobs().find(row => row.id === submission.jobId);
+    const submission = store.queue.submit({
+        kind: bundle.kind,
+        sourceKey: hash(JSON.stringify([namespace, entry.id])),
+        locator: bundle.sourceUrl,
+        realm: 'import:' + namespace,
+        idempotencyKey: 'import:' + hash(JSON.stringify([namespace, entry.id, sourceHash])),
+        intent: 'refresh',
+    });
+    const job = store.queue.list().find((row) => row.id === submission.jobId);
     if (job && ['failed', 'needs-auth', 'needs-permission', 'unsupported'].includes(String(job.state)))
-        store.retryJob(submission.jobId, { automatic: false });
-    const results = await drainQueue(store, { jobId: submission.jobId, signal, handlers: { [bundle.kind]: context => promote(context, bundle, namespace, entry, sourceHash) } });
+        store.queue.retry(submission.jobId, { automatic: false });
+    const results = await drainQueue(store, {
+        jobId: submission.jobId,
+        signal,
+        handlers: { [bundle.kind]: (context) => promote(context, bundle, namespace, entry, sourceHash) },
+    });
     const result = results[0];
     if (!result || !result.ok)
-        throw Object.assign(Error(result && !result.ok ? result.code : 'integrity'), { code: result && !result.ok ? result.code : 'integrity' });
+        throw new SpongeError(result && !result.ok ? result.code : 'integrity');
     return { ...base, status: 'imported', itemId: submission.itemId };
 }
 /** The revision a bundle import committed: content-addressed by its source hash. */
@@ -64,20 +110,42 @@ export const importBundleHash = (sourceHash) => hash(JSON.stringify(['wordcell-i
 /** Additive bounded batches. Every applied entry is reverified; source bundles are read-only. */
 export async function importManifest(store, path, options) {
     const { root, manifest, sha256 } = await readImportManifest(path), limit = options.limit ?? 20, offset = options.offset ?? 0;
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100 || !Number.isSafeInteger(offset) || offset < 0 || offset > manifest.entries.length)
-        throw Error('invalid-input');
-    const dryRun = options.dryRun !== false, report = { schemaVersion: 1, manifestSha256: sha256, namespace: manifest.namespace, dryRun, entries: [], nextOffset: offset + limit < manifest.entries.length ? offset + limit : null };
+    if (!Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > 100 ||
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        offset > manifest.entries.length)
+        throw new SpongeError('invalid-input');
+    const dryRun = options.dryRun !== false, report = {
+        schemaVersion: 1,
+        manifestSha256: sha256,
+        namespace: manifest.namespace,
+        dryRun,
+        entries: [],
+        nextOffset: offset + limit < manifest.entries.length ? offset + limit : null,
+    };
     const verify = options.verify ?? releasedBundleVerifier(options.runtime, store.root, options.signal);
     for (const entry of manifest.entries.slice(offset, offset + limit)) {
         if (options.signal?.aborted)
-            throw Object.assign(Error('cancelled'), { code: 'cancelled' });
+            throw new SpongeError('cancelled');
         try {
-            const result = await importBundleEntry(store, root, manifest.namespace, entry, verify, dryRun, options.signal), base = { id: entry.id, sourceHash: result.sourceHash, historicalIntegrity: result.historicalIntegrity, privacy: entry.privacy };
+            const result = await importBundleEntry(store, root, manifest.namespace, entry, verify, dryRun, options.signal), base = {
+                id: entry.id,
+                sourceHash: result.sourceHash,
+                historicalIntegrity: result.historicalIntegrity,
+                privacy: entry.privacy,
+            };
             report.entries.push({ ...base, status: result.status, ...(result.itemId ? { itemId: result.itemId } : {}) });
         }
         catch (error) {
             const code = errorCode(error);
-            report.entries.push({ id: entry.id, status: code === 'unsupported' ? 'unsupported' : 'failed', code, privacy: entry.privacy });
+            report.entries.push({
+                id: entry.id,
+                status: code === 'unsupported' ? 'unsupported' : 'failed',
+                code,
+                privacy: entry.privacy,
+            });
             if (code === 'cleanup-required' || code === 'owner-busy' || code === 'cancelled') {
                 report.nextOffset = offset + report.entries.length - 1;
                 break;

package/dist/src/importers/custody.js

@@ -2,33 +2,51 @@ 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 { directory, writeJournal, readJournal } from '../worker/journal.js';
+import { syncDirectoryAsync } from '../util/fsync.js';
 import { supervisedRunner } from '../worker/supervisor.js';
-const pending = () => Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+import { SpongeError, codeOf } from '../errors.js';
+const pending = () => new SpongeError('cleanup-required');
 /** Read-only verification still owns subprocesses, including during an import preview. */
 export async function withImportVerification(libraryRoot, verify) {
     const custody = await acquireWorkerCustody(libraryRoot), attemptId = randomUUID();
     let scratchRoot, unknown = false;
     try {
         const attempt = await directory(join(custody.directory, 'attempts', attemptId));
-        await writeJournal(join(attempt, 'import-verification.json'), { schemaVersion: 1, kind: 'import-verification', attemptId, ownerIncarnation: custody.incarnation });
+        await writeJournal(join(attempt, 'import-verification.json'), {
+            schemaVersion: 1,
+            kind: 'import-verification',
+            attemptId,
+            ownerIncarnation: custody.incarnation,
+        });
         scratchRoot = await directory(join(libraryRoot, 'staging', 'import-verification-' + attemptId));
-        await writeJournal(join(scratchRoot, 'ownership.json'), { schemaVersion: 1, kind: 'import-verification', requestId: attemptId, ownerIncarnation: custody.incarnation });
-        return await verify({ scratchRoot, runProcess: supervisedRunner(custody.directory, custody.incarnation, attemptId) });
+        await writeJournal(join(scratchRoot, 'ownership.json'), {
+            schemaVersion: 1,
+            kind: 'import-verification',
+            requestId: attemptId,
+            ownerIncarnation: custody.incarnation,
+        });
+        return await verify({
+            scratchRoot,
+            runProcess: supervisedRunner(custody.directory, custody.incarnation, attemptId),
+        });
     }
     catch (error) {
-        unknown = error?.code === 'cleanup-required' || (error instanceof Error && error.message === 'cleanup-required');
+        unknown = codeOf(error) === 'cleanup-required';
         throw error;
     }
     finally {
-        if (unknown || !await proveAttemptCleanup(custody.directory, custody.incarnation, attemptId))
+        if (unknown || !(await proveAttemptCleanup(custody.directory, custody.incarnation, attemptId)))
             throw pending();
         if (scratchRoot) {
             const marker = await readJournal(join(scratchRoot, 'ownership.json'));
-            if (marker.schemaVersion !== 1 || marker.kind !== 'import-verification' || marker.requestId !== attemptId || marker.ownerIncarnation !== custody.incarnation)
+            if (marker.schemaVersion !== 1 ||
+                marker.kind !== 'import-verification' ||
+                marker.requestId !== attemptId ||
+                marker.ownerIncarnation !== custody.incarnation)
                 throw pending();
             await rm(scratchRoot, { recursive: true });
-            await syncDir(join(libraryRoot, 'staging'));
+            await syncDirectoryAsync(join(libraryRoot, 'staging'));
         }
         await custody.release();
     }