@hraness/sponge 0.2.6 → 0.3.1

package/dist/src/inference/embedding/index.d.ts

@@ -26,14 +26,10 @@ export interface EmbeddingRuntime {
     model: string;
     library: string;
 }
-export declare class EmbeddingError extends Error {
-    code: 'integrity' | 'unsupported' | 'limit-exceeded' | 'cancelled' | 'unavailable' | 'cleanup-required';
-    constructor(code: 'integrity' | 'unsupported' | 'limit-exceeded' | 'cancelled' | 'unavailable' | 'cleanup-required');
-}
 export declare function spaceFingerprint(identity: Record<string, string | number>): string;
 export declare function embeddingFingerprint(helperSha256: string): string;
 /** Stored index spaces over the fixed 768-dim helper output. `f32-768` is the legacy identity and keeps its original fingerprint so existing generations stay readable; `int8-768` (default) stores symmetric per-vector max-abs int8 codes of the full vector; `int8-512` also keeps only the renormalized Matryoshka prefix. Quantization alone was near-lossless on real queries while the 512 prefix moved chunk top-1 on a quarter of them (docs/decisions/storage-diet.md), so the default keeps all 768 dimensions for 256 more bytes per row. */
-export declare const indexEncodings: {
+declare const indexEncodings: {
     readonly 'f32-768': {};
     readonly 'int8-768': {
         readonly quantization: "int8-symmetric-maxabs-v1";
@@ -45,7 +41,6 @@ export declare const indexEncodings: {
     };
 };
 export type IndexEncoding = keyof typeof indexEncodings;
-export declare const defaultIndexEncoding: IndexEncoding;
 export interface IndexSpace {
     encoding: IndexEncoding;
     identity: Record<string, string | number>;
@@ -73,3 +68,4 @@ export declare function embedBatch(inputs: readonly EmbeddingInput[], options: {
     inputHashes: string[];
     vectors: number[][];
 }>;
+export {};

package/dist/src/inference/embedding/index.js

@@ -1,35 +1,75 @@
 import { createHash } from 'node:crypto';
+import { sha256 as hash } from '../../util/hash.js';
 import { constants } from 'node:fs';
 import { open, mkdtemp, chmod, writeFile, rm, realpath } from 'node:fs/promises';
 import { dirname, join, isAbsolute } from 'node:path';
 import { runOwned } from '../../acquisition/process.js';
-export const embeddingIdentity = { modelSha256: '92dcbea108899e5d6e30d919b0744f90d9967e80c67a4ab5503ac16d54f62eb0', librarySha256: '9526db9ee35e7eb4a5a58ac1e53330032f22a13890bd4ee01818fb380a57a362', runtime: 'LiteRT-LM@0.18.0', dimensions: 768, normalization: 'unit-l2', preprocessing: 'sips-max512-png-litert-v1', prompt: 'search-result-query-title-none-v1', protocol: 1, backend: 'cpu-2threads-f32', textBudget: 'utf8-1016-v1' };
+import { SpongeError } from '../../errors.js';
+export const embeddingIdentity = {
+    modelSha256: '92dcbea108899e5d6e30d919b0744f90d9967e80c67a4ab5503ac16d54f62eb0',
+    librarySha256: '9526db9ee35e7eb4a5a58ac1e53330032f22a13890bd4ee01818fb380a57a362',
+    runtime: 'LiteRT-LM@0.18.0',
+    dimensions: 768,
+    normalization: 'unit-l2',
+    preprocessing: 'sips-max512-png-litert-v1',
+    prompt: 'search-result-query-title-none-v1',
+    protocol: 1,
+    backend: 'cpu-2threads-f32',
+    textBudget: 'utf8-1016-v1',
+};
 /** The model's largest text signature is 1024 tokens; byte-fallback tokenization never yields more tokens than UTF-8 bytes. */
 export const embeddingTextBytes = 1016;
-export class EmbeddingError extends Error {
-    code;
-    constructor(code) {
-        super(code);
-        this.code = code;
-    }
+const fail = (code = 'integrity') => {
+    throw new SpongeError(code);
+};
+export function spaceFingerprint(identity) {
+    const keys = Object.keys(identity).sort();
+    if (!keys.length ||
+        keys.some((k) => !['string', 'number'].includes(typeof identity[k]) ||
+            (typeof identity[k] === 'number' && !Number.isFinite(identity[k]))))
+        fail();
+    return hash(JSON.stringify(Object.fromEntries(keys.map((k) => [k, identity[k]]))));
+}
+export function embeddingFingerprint(helperSha256) {
+    if (!/^[a-f0-9]{64}$/.test(helperSha256))
+        fail();
+    return spaceFingerprint({ ...embeddingIdentity, helperSha256 });
 }
-const fail = (code = 'integrity') => { throw new EmbeddingError(code); };
-const hash = (b) => createHash('sha256').update(b).digest('hex');
-export function spaceFingerprint(identity) { const keys = Object.keys(identity).sort(); if (!keys.length || keys.some(k => !['string', 'number'].includes(typeof identity[k]) || (typeof identity[k] === 'number' && !Number.isFinite(identity[k]))))
-    fail(); return hash(JSON.stringify(Object.fromEntries(keys.map(k => [k, identity[k]])))); }
-export function embeddingFingerprint(helperSha256) { if (!/^[a-f0-9]{64}$/.test(helperSha256))
-    fail(); return spaceFingerprint({ ...embeddingIdentity, helperSha256 }); }
 /** Stored index spaces over the fixed 768-dim helper output. `f32-768` is the legacy identity and keeps its original fingerprint so existing generations stay readable; `int8-768` (default) stores symmetric per-vector max-abs int8 codes of the full vector; `int8-512` also keeps only the renormalized Matryoshka prefix. Quantization alone was near-lossless on real queries while the 512 prefix moved chunk top-1 on a quarter of them (docs/decisions/storage-diet.md), so the default keeps all 768 dimensions for 256 more bytes per row. */
-export const indexEncodings = { 'f32-768': {}, 'int8-768': { quantization: 'int8-symmetric-maxabs-v1' }, 'int8-512': { dimensions: 512, truncation: 'matryoshka-prefix-renormalized-v1', quantization: 'int8-symmetric-maxabs-v1' } };
-export const defaultIndexEncoding = 'int8-768';
-export function indexSpace(helperSha256, encoding = defaultIndexEncoding) { if (!/^[a-f0-9]{64}$/.test(helperSha256) || !Object.hasOwn(indexEncodings, encoding))
-    fail(); const identity = { ...embeddingIdentity, helperSha256, ...indexEncodings[encoding] }; return { encoding, identity, fingerprint: spaceFingerprint(identity), dimensions: Number(identity.dimensions) }; }
+const indexEncodings = {
+    'f32-768': {},
+    'int8-768': { quantization: 'int8-symmetric-maxabs-v1' },
+    'int8-512': {
+        dimensions: 512,
+        truncation: 'matryoshka-prefix-renormalized-v1',
+        quantization: 'int8-symmetric-maxabs-v1',
+    },
+};
+const defaultIndexEncoding = 'int8-768';
+export function indexSpace(helperSha256, encoding = defaultIndexEncoding) {
+    if (!/^[a-f0-9]{64}$/.test(helperSha256) || !Object.hasOwn(indexEncodings, encoding))
+        fail();
+    const identity = { ...embeddingIdentity, helperSha256, ...indexEncodings[encoding] };
+    return { encoding, identity, fingerprint: spaceFingerprint(identity), dimensions: Number(identity.dimensions) };
+}
 /** The stored space for a generation fingerprint built from this helper, if any. */
-export function resolveIndexSpace(helperSha256, fingerprint) { return Object.keys(indexEncodings).map(e => indexSpace(helperSha256, e)).find(s => s.fingerprint === fingerprint); }
+export function resolveIndexSpace(helperSha256, fingerprint) {
+    return Object.keys(indexEncodings)
+        .map((e) => indexSpace(helperSha256, e))
+        .find((s) => s.fingerprint === fingerprint);
+}
 /** Matryoshka prefix truncation of a unit helper vector, renormalized to unit L2. */
-export function projectVector(vector, dimensions) { if (!Number.isSafeInteger(dimensions) || dimensions < 1 || dimensions > vector.length || vector.some(n => !Number.isFinite(n)))
-    fail(); const prefix = vector.slice(0, dimensions), norm = Math.hypot(...prefix); if (!(norm > 0))
-    fail(); return dimensions === vector.length ? [...vector] : prefix.map(n => n / norm); }
+export function projectVector(vector, dimensions) {
+    if (!Number.isSafeInteger(dimensions) ||
+        dimensions < 1 ||
+        dimensions > vector.length ||
+        vector.some((n) => !Number.isFinite(n)))
+        fail();
+    const prefix = vector.slice(0, dimensions), norm = Math.hypot(...prefix);
+    if (!(norm > 0))
+        fail();
+    return dimensions === vector.length ? [...vector] : prefix.map((n) => n / norm);
+}
 /** Versioned length-delimited bytes. No user content or image pathname enters argv. */
 export function encodeEmbeddingRequest(inputs) {
     if (!inputs.length || inputs.length > 16)
@@ -42,7 +82,9 @@ export function encodeEmbeddingRequest(inputs) {
             kind = 2;
             if (payload.length < 33 || payload.length > 2 * 1024 * 1024)
                 fail('limit-exceeded');
-            if (!payload.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) || payload.toString('ascii', 12, 16) !== 'IHDR' || payload.readUInt32BE(8) !== 13)
+            if (!payload.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ||
+                payload.toString('ascii', 12, 16) !== 'IHDR' ||
+                payload.readUInt32BE(8) !== 13)
                 fail('unsupported');
             const w = payload.readUInt32BE(16), h = payload.readUInt32BE(20);
             if (!w || !h || w * h > 262144)
@@ -79,9 +121,14 @@ export function parseEmbeddingOutput(stdout, count) {
     const p = parsed;
     if (!p || p.protocol !== 1 || !Array.isArray(p.vectors) || p.vectors.length !== count)
         fail();
-    return p.vectors.map((v) => { if (!Array.isArray(v) || v.length !== 768 || v.some(n => typeof n !== 'number' || !Number.isFinite(n)))
-        fail(); const vector = v; if (Math.abs(Math.hypot(...vector) - 1) > .001)
-        fail(); return vector; });
+    return p.vectors.map((v) => {
+        if (!Array.isArray(v) || v.length !== 768 || v.some((n) => typeof n !== 'number' || !Number.isFinite(n)))
+            fail();
+        const vector = v;
+        if (Math.abs(Math.hypot(...vector) - 1) > 0.001)
+            fail();
+        return vector;
+    });
 }
 async function verify(path, expected) {
     if (!isAbsolute(path) || !/^[a-f0-9]{64}$/.test(expected))
@@ -108,8 +155,12 @@ export async function embedBatch(inputs, options) {
         fail('cancelled');
     if (process.platform !== 'darwin' || process.arch !== 'arm64')
         fail('unsupported');
-    await Promise.all([verify(r.helper, r.helperSha256), verify(r.model, embeddingIdentity.modelSha256), verify(r.library, embeddingIdentity.librarySha256)]);
-    if (await realpath(r.library) !== join(await realpath(dirname(r.helper)), 'libCLiteRTLM_mac.dylib'))
+    await Promise.all([
+        verify(r.helper, r.helperSha256),
+        verify(r.model, embeddingIdentity.modelSha256),
+        verify(r.library, embeddingIdentity.librarySha256),
+    ]);
+    if ((await realpath(r.library)) !== join(await realpath(dirname(r.helper)), 'libCLiteRTLM_mac.dylib'))
         fail();
     const scratch = await mkdtemp(join(options.scratchRoot, 'embedding-'));
     await chmod(scratch, 0o700);
@@ -118,7 +169,12 @@ export async function embedBatch(inputs, options) {
         const path = join(scratch, 'request.bin');
         await writeFile(path, request.bytes, { mode: 0o600, flag: 'wx' });
         settled = false;
-        const result = await (options.runProcess ?? runOwned)('/usr/bin/sandbox-exec', ['-p', '(version 1) (allow default) (deny network*)', r.helper, r.model, path], { env: { PATH: '/usr/bin:/bin', HOME: scratch, TMPDIR: scratch, LANG: 'C' }, signal: options.signal, deadlineMs: 120000, maxOutputBytes: 512 * 1024 });
+        const result = await (options.runProcess ?? runOwned)('/usr/bin/sandbox-exec', ['-p', '(version 1) (allow default) (deny network*)', r.helper, r.model, path], {
+            env: { PATH: '/usr/bin:/bin', HOME: scratch, TMPDIR: scratch, LANG: 'C' },
+            signal: options.signal,
+            deadlineMs: 120000,
+            maxOutputBytes: 512 * 1024,
+        });
         settled = result.cleanup === 'settled';
         if (!settled)
             fail('cleanup-required');
@@ -126,7 +182,11 @@ export async function embedBatch(inputs, options) {
             fail(result.stopped);
         if (result.code !== 0)
             fail('unavailable');
-        return { fingerprint, inputHashes: request.inputHashes, vectors: parseEmbeddingOutput(result.stdout, inputs.length) };
+        return {
+            fingerprint,
+            inputHashes: request.inputHashes,
+            vectors: parseEmbeddingOutput(result.stdout, inputs.length),
+        };
     }
     finally {
         if (settled)

package/dist/src/ingest/attempt.d.ts

@@ -0,0 +1,29 @@
+import type { ErrorCode, ErrorEnvelope } from '../../contracts/index.js';
+import type { LibraryStore, AttemptToken } from '../store/index.js';
+type Cleanup = 'settled' | 'pending';
+export type AttemptOutcome<T extends {
+    ok: true;
+}> = (T | ErrorEnvelope) & {
+    cleanup: Cleanup;
+};
+/** A body's view of its attempt: the cleanup verdict of its owned children, and the one capture it holds. */
+export interface Attempt {
+    cleanup: Cleanup;
+    hold(capture: {
+        dispose(): Promise<void>;
+    }): void;
+}
+/** Maps a thrown value to one of `codes` by its public code; anything else is unclassified. */
+export declare function classifyErrors(codes: readonly ErrorCode[]): (error: unknown) => ErrorCode;
+/**
+ * One ingest attempt. The body captures, stores blobs and commits; it returns ok only after revisions.commit.
+ * Afterwards, in order: dispose the held capture (only while every child is settled: an uncertain process may
+ * still read its bytes), fail an uncommitted attempt, settle storage staging when clean. Any bookkeeping failure
+ * leaves ownership pending, reported as cleanup-required.
+ */
+export declare function runAttempt<T extends {
+    ok: true;
+}>(store: {
+    queue: Pick<LibraryStore['queue'], 'fail' | 'settle'>;
+}, token: AttemptToken, classify: (error: unknown, attempt: Attempt) => ErrorCode, body: (attempt: Attempt) => Promise<T | ErrorEnvelope>): Promise<AttemptOutcome<T>>;
+export {};

package/dist/src/ingest/attempt.js

@@ -0,0 +1,55 @@
+import { failure } from '../acquisition/errors.js';
+import { publicCode } from '../errors.js';
+/** Maps a thrown value to one of `codes` by its public code; anything else is unclassified. */
+export function classifyErrors(codes) {
+    const known = new Set(codes);
+    return (error) => {
+        const code = publicCode(error);
+        return known.has(code) ? code : 'unclassified';
+    };
+}
+/**
+ * One ingest attempt. The body captures, stores blobs and commits; it returns ok only after revisions.commit.
+ * Afterwards, in order: dispose the held capture (only while every child is settled: an uncertain process may
+ * still read its bytes), fail an uncommitted attempt, settle storage staging when clean. Any bookkeeping failure
+ * leaves ownership pending, reported as cleanup-required.
+ */
+export async function runAttempt(store, token, classify, body) {
+    let held, outcome;
+    const attempt = {
+        cleanup: 'settled',
+        hold: (capture) => {
+            held = capture;
+        },
+    };
+    try {
+        outcome = await body(attempt);
+    }
+    catch (error) {
+        outcome = failure(token.attemptId, classify(error, attempt), 'storage');
+    }
+    if (held && attempt.cleanup === 'settled')
+        try {
+            await held.dispose();
+        }
+        catch {
+            attempt.cleanup = 'pending';
+        }
+    if (!outcome.ok)
+        try {
+            store.queue.fail(token, outcome.code, { retryable: outcome.retryable, retryAfterMs: outcome.retryAfterMs });
+        }
+        catch {
+            attempt.cleanup = 'pending';
+        }
+    if (attempt.cleanup === 'settled')
+        try {
+            store.queue.settle(token);
+        }
+        catch {
+            attempt.cleanup = 'pending';
+        }
+    return attempt.cleanup === 'pending'
+        ? { ...failure(token.attemptId, 'cleanup-required', 'cleanup'), cleanup: 'pending' }
+        : { ...outcome, cleanup: 'settled' };
+}

package/dist/src/media/capture-helper.js

@@ -1,13 +1,18 @@
 /** Public Ghostget SDK bridge; its complete inherited group belongs to the caller. */
 import { readFile } from 'node:fs/promises';
 import { processIdentity } from '../worker/identity.js';
+import { SpongeError } from '../errors.js';
 try {
     const config = JSON.parse(await readFile(process.argv[2], 'utf8'));
     const sdk = await import(import.meta.resolve('@hraness/ghostget/media-acquisition', `${config.runtimeRoot}/package.json`));
     const identity = await processIdentity(process.pid);
     if (!identity)
-        throw Error('identity');
-    const result = await sdk.acquireEphemeralMedia({ ...config.request, processGroup: 'inherit', supervisor: { requestId: config.requestId, processGroupId: process.pid, processStartIdentity: identity.started } });
+        throw new SpongeError('unavailable');
+    const result = await sdk.acquireEphemeralMedia({
+        ...config.request,
+        processGroup: 'inherit',
+        supervisor: { requestId: config.requestId, processGroupId: process.pid, processStartIdentity: identity.started },
+    });
     process.stdout.write(JSON.stringify(result));
 }
 catch {

package/dist/src/media/capture.d.ts

@@ -15,7 +15,7 @@ export interface MediaCaptureRequest {
     signal?: AbortSignal;
     runProcess?: typeof runOwned;
 }
-export interface CapturedMedia {
+interface CapturedMedia {
     ok: true;
     root: string;
     audio?: AudioInput;
@@ -30,3 +30,4 @@ export interface CapturedMedia {
 export type MediaCaptureOutcome = CapturedMedia | ErrorEnvelope;
 /** All ephemeral bytes remain below one capture owner; deletion requires a settled process tree. */
 export declare function captureMedia(request: MediaCaptureRequest): Promise<MediaCaptureOutcome>;
+export {};

package/dist/src/media/capture.js

@@ -4,13 +4,14 @@ import { join, relative, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
+import { sha256 as hash } from '../util/hash.js';
 import { limits } from '../../contracts/index.js';
 import { failure } from '../acquisition/errors.js';
-import { inspectCaptureRuntime, CaptureSetupError } from '../acquisition/runtime.js';
+import { inspectCaptureRuntime } from '../acquisition/runtime.js';
 import { privateRoot, physicalBytes, readConfined } from '../acquisition/files.js';
 import { runOwned, isolatedEnvironment } from '../acquisition/process.js';
-import { settleCaptureRoot, CaptureCleanupError } from '../acquisition/cleanup.js';
-const hash = (value) => createHash('sha256').update(value).digest('hex');
+import { settleCaptureRoot } from '../acquisition/cleanup.js';
+import { SpongeError, publicCode, codeOf } from '../errors.js';
 /** All ephemeral bytes remain below one capture owner; deletion requires a settled process tree. */
 export async function captureMedia(request) {
     const { requestId, signal } = request;
@@ -39,7 +40,7 @@ export async function captureMedia(request) {
             return failure(requestId, 'limit-exceeded');
     }
     catch (error) {
-        return failure(requestId, error instanceof CaptureSetupError ? error.code : 'invalid-input');
+        return failure(requestId, publicCode(error, 'invalid-input'));
     }
     let selectedState;
     if (request.connection?.kind === 'account') {
@@ -58,25 +59,44 @@ export async function captureMedia(request) {
     signal?.addEventListener('abort', abort, { once: true });
     if (signal?.aborted)
         abort();
-    const monitor = setInterval(async () => { if (checking)
-        return; checking = true; try {
-        if (await physicalBytes(root) > limits.stagingBytes) {
+    const monitor = setInterval(async () => {
+        if (checking)
+            return;
+        checking = true;
+        try {
+            if ((await physicalBytes(root)) > limits.stagingBytes) {
+                quota = true;
+                controller.abort();
+            }
+        }
+        catch {
             quota = true;
             controller.abort();
         }
-    }
-    catch {
-        quota = true;
-        controller.abort();
-    }
-    finally {
-        checking = false;
-    } }, 100);
+        finally {
+            checking = false;
+        }
+    }, 100);
     try {
         await mkdir(home, { mode: 0o700 });
-        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'acquiring' }), { mode: 0o600 });
+        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'acquiring' }), {
+            mode: 0o600,
+        });
         const requestFile = join(root, 'request.json');
-        await writeFile(requestFile, JSON.stringify({ runtimeRoot: runtime.root, requestId, request: { url: request.sourceUrl, stagingParent: root, accountId: request.connection?.kind === 'account' ? request.connection.accountId : undefined, language: request.language ?? 'en', preferAudio: request.forceLocal === true, maxBytes: 512 * 1024 ** 2, maxDurationSeconds: 3600, timeoutMs: limits.captureDeadlineMs } }), { mode: 0o600, flag: 'wx' });
+        await writeFile(requestFile, JSON.stringify({
+            runtimeRoot: runtime.root,
+            requestId,
+            request: {
+                url: request.sourceUrl,
+                stagingParent: root,
+                accountId: request.connection?.kind === 'account' ? request.connection.accountId : undefined,
+                language: request.language ?? 'en',
+                preferAudio: request.forceLocal === true,
+                maxBytes: 512 * 1024 ** 2,
+                maxDurationSeconds: 3600,
+                timeoutMs: limits.captureDeadlineMs,
+            },
+        }), { mode: 0o600, flag: 'wx' });
         const entry = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './capture-helper.ts' : './capture-helper.js', import.meta.url));
         const environment = isolatedEnvironment(home, home, selectedState ?? join(home, 'state'));
         environment.XDG_CACHE_HOME = home;
@@ -85,7 +105,13 @@ export async function captureMedia(request) {
         if (selectedState)
             environment.HOME = homedir();
         cleanup = 'pending';
-        const result = await (request.runProcess ?? runOwned)(runtime.bun, [entry, requestFile], { cwd: root, env: environment, signal: controller.signal, deadlineMs: limits.captureDeadlineMs, maxOutputBytes: limits.metadataBytes });
+        const result = await (request.runProcess ?? runOwned)(runtime.bun, [entry, requestFile], {
+            cwd: root,
+            env: environment,
+            signal: controller.signal,
+            deadlineMs: limits.captureDeadlineMs,
+            maxOutputBytes: limits.metadataBytes,
+        });
         cleanup = result.cleanup;
         if (cleanup === 'pending')
             return failure(requestId, 'cleanup-required', 'cleanup');
@@ -97,42 +123,80 @@ export async function captureMedia(request) {
         if (parsed.ok !== true) {
             if (parsed.code === 'cleanup-required')
                 cleanup = 'pending';
-            const mapping = { 'permission-or-provider-failure': 'grant-permission', timeout: 'unavailable', 'cleanup-required': 'cleanup-required', 'invalid-input': 'invalid-input', unsupported: 'unsupported', unavailable: 'unavailable', 'limit-exceeded': 'limit-exceeded', cancelled: 'cancelled', integrity: 'integrity' };
+            const mapping = {
+                'permission-or-provider-failure': 'grant-permission',
+                timeout: 'unavailable',
+                'cleanup-required': 'cleanup-required',
+                'invalid-input': 'invalid-input',
+                unsupported: 'unsupported',
+                unavailable: 'unavailable',
+                'limit-exceeded': 'limit-exceeded',
+                cancelled: 'cancelled',
+                integrity: 'integrity',
+            };
             return failure(requestId, mapping[parsed.code] ?? 'unclassified');
         }
         const manifest = parsed.manifest, mediaRoot = parsed.receipt?.root;
-        if (result.code !== 0 || typeof mediaRoot !== 'string' || !mediaRoot.startsWith(root + '/media-') || await realpath(mediaRoot) !== mediaRoot || manifest?.schemaVersion !== 1 || manifest.kind !== 'ephemeral-media' || manifest.retainedSourceArchive !== false || manifest.source?.requestedUrlSha256 !== hash(url.href) || !Number.isFinite(manifest.source.durationSeconds) || manifest.source.durationSeconds <= 0 || manifest.source.durationSeconds > 3600 || !Array.isArray(manifest.files) || manifest.files.length > 3)
-            throw Error('integrity');
-        const captured = { ok: true, root: mediaRoot, manifestSha256: hash(JSON.stringify(manifest)), warnings: Array.isArray(manifest.warnings) ? manifest.warnings.map(() => 'partial') : [], dispose: async () => { if (await settleCaptureRoot(root, requestId) === 'pending')
-                throw new CaptureCleanupError(); } };
+        if (result.code !== 0 ||
+            typeof mediaRoot !== 'string' ||
+            !mediaRoot.startsWith(root + '/media-') ||
+            (await realpath(mediaRoot)) !== mediaRoot ||
+            manifest?.schemaVersion !== 1 ||
+            manifest.kind !== 'ephemeral-media' ||
+            manifest.retainedSourceArchive !== false ||
+            manifest.source?.requestedUrlSha256 !== hash(url.href) ||
+            !Number.isFinite(manifest.source.durationSeconds) ||
+            manifest.source.durationSeconds <= 0 ||
+            manifest.source.durationSeconds > 3600 ||
+            !Array.isArray(manifest.files) ||
+            manifest.files.length > 3)
+            throw new SpongeError('integrity');
+        const captured = {
+            ok: true,
+            root: mediaRoot,
+            manifestSha256: hash(JSON.stringify(manifest)),
+            warnings: Array.isArray(manifest.warnings) ? manifest.warnings.map(() => 'partial') : [],
+            dispose: async () => {
+                if ((await settleCaptureRoot(root, requestId)) === 'pending')
+                    throw new SpongeError('cleanup-required');
+            },
+        };
         for (const field of ['title', 'author']) {
             const value = manifest.source[field];
             if (value !== undefined) {
                 if (typeof value !== 'string' || Buffer.byteLength(value) > 16384)
-                    throw Error('integrity');
+                    throw new SpongeError('integrity');
                 captured[field] = value;
             }
         }
         const roles = new Set();
         for (const file of manifest.files) {
-            if (!['audio', 'captions', 'thumbnail'].includes(file.role) || roles.has(file.role) || typeof file.path !== 'string' || !Number.isSafeInteger(file.bytes) || file.bytes < 1 || !/^[a-f0-9]{64}$/.test(file.sha256))
-                throw Error('integrity');
+            if (!['audio', 'captions', 'thumbnail'].includes(file.role) ||
+                roles.has(file.role) ||
+                typeof file.path !== 'string' ||
+                !Number.isSafeInteger(file.bytes) ||
+                file.bytes < 1 ||
+                !/^[a-f0-9]{64}$/.test(file.sha256))
+                throw new SpongeError('integrity');
             roles.add(file.role);
             const relativePath = isAbsolute(file.path) ? relative(mediaRoot, file.path) : file.path;
             const maximum = file.role === 'audio' ? 512 * 1024 ** 2 : file.role === 'captions' ? 4 * 1024 ** 2 : limits.imageBytes;
             // Bounded confined byte verification before handing anything to native code.
             let data = Buffer.alloc(0);
             if (file.role === 'audio') {
-                if (!relativePath || relativePath.split('/').some((part) => !part || part === '.' || part === '..') || relativePath.includes('\\') || file.bytes > maximum)
-                    throw Error('integrity');
+                if (!relativePath ||
+                    relativePath.split('/').some((part) => !part || part === '.' || part === '..') ||
+                    relativePath.includes('\\') ||
+                    file.bytes > maximum)
+                    throw new SpongeError('integrity');
                 const path = join(mediaRoot, relativePath);
-                if (await realpath(path) !== path)
-                    throw Error('integrity');
+                if ((await realpath(path)) !== path)
+                    throw new SpongeError('integrity');
                 const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
                 try {
                     const stat = await handle.stat();
                     if (!stat.isFile() || stat.nlink !== 1 || stat.size !== file.bytes)
-                        throw Error('integrity');
+                        throw new SpongeError('integrity');
                     const digest = createHash('sha256'), buffer = Buffer.alloc(65536);
                     let bytes = 0;
                     for (;;) {
@@ -141,11 +205,11 @@ export async function captureMedia(request) {
                             break;
                         bytes += bytesRead;
                         if (bytes > file.bytes)
-                            throw Error('limit-exceeded');
+                            throw new SpongeError('limit-exceeded');
                         digest.update(buffer.subarray(0, bytesRead));
                     }
                     if (bytes !== file.bytes || digest.digest('hex') !== file.sha256)
-                        throw Error('integrity');
+                        throw new SpongeError('integrity');
                 }
                 finally {
                     await handle.close();
@@ -154,24 +218,41 @@ export async function captureMedia(request) {
             else {
                 data = await readConfined(mediaRoot, relativePath, maximum);
                 if (data.length !== file.bytes || hash(data) !== file.sha256)
-                    throw Error('integrity');
+                    throw new SpongeError('integrity');
             }
             if (file.role === 'audio')
-                captured.audio = { path: join(mediaRoot, relativePath), sha256: file.sha256, bytes: file.bytes, durationMs: manifest.source.durationSeconds * 1000 };
+                captured.audio = {
+                    path: join(mediaRoot, relativePath),
+                    sha256: file.sha256,
+                    bytes: file.bytes,
+                    durationMs: manifest.source.durationSeconds * 1000,
+                };
             else if (file.role === 'captions') {
                 if (!manifest.caption || !['manual', 'automatic'].includes(manifest.caption.source))
-                    throw Error('integrity');
-                captured.captions = { text: new TextDecoder('utf8', { fatal: true, ignoreBOM: true }).decode(data), sha256: file.sha256, source: manifest.caption.source, language: manifest.caption.language, durationMs: manifest.source.durationSeconds * 1000 };
+                    throw new SpongeError('integrity');
+                captured.captions = {
+                    text: new TextDecoder('utf8', { fatal: true, ignoreBOM: true }).decode(data),
+                    sha256: file.sha256,
+                    source: manifest.caption.source,
+                    language: manifest.caption.language,
+                    durationMs: manifest.source.durationSeconds * 1000,
+                };
             }
             else {
-                const mediaType = data[0] === 0xff && data[1] === 0xd8 ? 'image/jpeg' : data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ? 'image/png' : data.toString('ascii', 0, 4) === 'RIFF' && data.toString('ascii', 8, 12) === 'WEBP' ? 'image/webp' : undefined;
+                const mediaType = data[0] === 0xff && data[1] === 0xd8
+                    ? 'image/jpeg'
+                    : data.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+                        ? 'image/png'
+                        : data.toString('ascii', 0, 4) === 'RIFF' && data.toString('ascii', 8, 12) === 'WEBP'
+                            ? 'image/webp'
+                            : undefined;
                 if (!mediaType)
-                    throw Error('integrity');
+                    throw new SpongeError('integrity');
                 captured.thumbnail = { relativePath, bytes: file.bytes, sha256: file.sha256, mediaType };
             }
         }
         if (!captured.audio && !captured.captions)
-            throw Error('integrity');
+            throw new SpongeError('integrity');
         if (controller.signal.aborted)
             return failure(requestId, quota ? 'limit-exceeded' : 'cancelled');
         keep = true;
@@ -180,14 +261,14 @@ export async function captureMedia(request) {
     catch (error) {
         if (cleanup === 'pending')
             return failure(requestId, 'cleanup-required', 'cleanup');
-        return failure(requestId, error instanceof Error && error.message === 'limit-exceeded' ? 'limit-exceeded' : 'integrity', 'verification');
+        return failure(requestId, codeOf(error) === 'limit-exceeded' ? 'limit-exceeded' : 'integrity', 'verification');
     }
     finally {
         clearInterval(monitor);
         while (checking)
-            await new Promise(r => setTimeout(r, 5));
+            await new Promise((r) => setTimeout(r, 5));
         signal?.removeEventListener('abort', abort);
-        if (!keep && cleanup === 'settled' && await settleCaptureRoot(root, requestId) === 'pending')
+        if (!keep && cleanup === 'settled' && (await settleCaptureRoot(root, requestId)) === 'pending')
             return failure(requestId, 'cleanup-required', 'cleanup');
     }
 }

package/dist/src/media/handler.d.ts

@@ -10,13 +10,15 @@ export interface MediaOptions extends Omit<MediaCaptureRequest, 'requestId' | 's
     capture?: (request: MediaCaptureRequest) => Promise<MediaCaptureOutcome>;
     transcribe?: typeof transcribeMedia;
 }
-export type MediaOutcome = ({
+interface MediaResult {
     ok: true;
     itemId: string;
     revisionId: string;
     status: 'complete' | 'partial';
-} | ErrorEnvelope) & {
+}
+export type MediaOutcome = (MediaResult | ErrorEnvelope) & {
     cleanup: 'settled' | 'pending';
 };
 /** Only a transcript and thumbnail enter durable storage; acquisition owns all source media. */
 export declare function ingestMedia(store: LibraryStore, token: AttemptToken, options: MediaOptions): Promise<MediaOutcome>;
+export {};