@hraness/sponge 0.2.5 → 0.3.0

package/dist/src/media/handler.js

@@ -1,82 +1,100 @@
-import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { failure } from '../acquisition/errors.js';
+import { runAttempt, classifyErrors } from '../ingest/attempt.js';
+import { sha256 } from '../util/hash.js';
 import { bundleBytes } from '../app/bundle-files.js';
 import { runOwned } from '../acquisition/process.js';
 import { captureMedia } from './capture.js';
 import { transcribeMedia } from './transcribe.js';
+import { SpongeError } from '../errors.js';
+const mediaCode = classifyErrors([
+    'cleanup-required',
+    'integrity',
+    'invalid-input',
+    'limit-exceeded',
+    'cancelled',
+    'owner-busy',
+]);
 /** Only a transcript and thumbnail enter durable storage; acquisition owns all source media. */
-export async function ingestMedia(store, token, options) {
-    let captured, committed = false, cleanup = 'settled';
-    let outcome = failure(token.attemptId, 'unclassified');
-    try {
-        const source = store.sourceForJob(token.jobId);
+export function ingestMedia(store, token, options) {
+    // An uncertain native process may still be reading source bytes: runAttempt then preserves ownership.
+    return runAttempt(store, token, (error, attempt) => {
+        const code = mediaCode(error);
+        if (code === 'cleanup-required')
+            attempt.cleanup = 'pending';
+        return code;
+    }, async (attempt) => {
+        const source = store.queue.source(token.jobId);
         if (!source || source.kind !== 'media')
-            throw Error('invalid-input');
-        const result = await (options.capture ?? captureMedia)({ ...options, stagingRoot: join(store.root, 'staging'), requestId: token.attemptId, sourceUrl: source.locator });
+            throw new SpongeError('invalid-input');
+        const result = await (options.capture ?? captureMedia)({
+            ...options,
+            stagingRoot: join(store.root, 'staging'),
+            requestId: token.attemptId,
+            sourceUrl: source.locator,
+        });
         if (!result.ok) {
-            outcome = result;
-            cleanup = result.code === 'cleanup-required' ? 'pending' : 'settled';
+            if (result.code === 'cleanup-required')
+                attempt.cleanup = 'pending';
+            return result;
         }
-        else {
-            captured = result;
-            await options.checkpoint?.('extracting');
-            const transcription = await (options.transcribe ?? transcribeMedia)({ requestId: token.attemptId, audio: result.audio, captions: result.captions, language: options.language, forceLocal: options.forceLocal }, { scratchRoot: result.root, runtime: options.asrRuntime, signal: options.signal, runProcess: options.runProcess ?? runOwned });
-            cleanup = transcription.cleanup;
-            if (!transcription.ok)
-                outcome = transcription;
-            else {
-                const transcriptBytes = Buffer.from(JSON.stringify(transcription.transcript)), transcriptHash = createHash('sha256').update(transcriptBytes).digest('hex');
-                const transcriptBlob = await store.putBlob(token, transcriptHash, transcriptBytes.length, (async function* () { yield transcriptBytes; })());
-                const assets = [{ ...transcriptBlob, mediaType: 'application/json', relationship: 'transcript' }];
-                if (result.thumbnail) {
-                    const blob = await store.putBlob(token, result.thumbnail.sha256, result.thumbnail.bytes, bundleBytes(result.root, result.thumbnail));
-                    assets.push({ ...blob, mediaType: result.thumbnail.mediaType, relationship: 'thumbnail' });
-                }
-                if (options.signal?.aborted) {
-                    store.requestCancellation(token.jobId);
-                    throw Error('cancelled');
-                }
-                const observedAt = new Date().toISOString(), metadata = [{ field: 'transcriptSource', value: transcription.transcript.source, source: 'media', observedAt }, { field: 'language', value: transcription.transcript.language, source: 'media', observedAt }, { field: 'durationMs', value: String(transcription.transcript.durationMs), source: 'media', observedAt }];
-                for (const field of ['title', 'author'])
-                    if (result[field])
-                        metadata.push({ field: field === 'author' ? 'authors' : field, value: field === 'author' ? [result[field]] : result[field], source: 'media', observedAt, selected: true });
-                const status = result.warnings.length ? 'partial' : 'complete';
-                await options.checkpoint?.('promoting');
-                const revision = store.commitRevision({ ...token, itemId: source.itemId, bundleHash: createHash('sha256').update(JSON.stringify(['media-transcript-v1', result.manifestSha256, transcriptHash])).digest('hex'), markdown: transcription.markdown, title: result.title, extractor: { name: 'sponge-media', version: '1' }, status, metadata, assets, warnings: result.warnings.length ? ['partial'] : [] });
-                committed = true;
-                outcome = { ok: true, itemId: source.itemId, revisionId: revision.revisionId, status };
-            }
+        attempt.hold(result);
+        await options.checkpoint?.('extracting');
+        const transcription = await (options.transcribe ?? transcribeMedia)({
+            requestId: token.attemptId,
+            audio: result.audio,
+            captions: result.captions,
+            language: options.language,
+            forceLocal: options.forceLocal,
+        }, {
+            scratchRoot: result.root,
+            runtime: options.asrRuntime,
+            signal: options.signal,
+            runProcess: options.runProcess ?? runOwned,
+        });
+        attempt.cleanup = transcription.cleanup;
+        if (!transcription.ok)
+            return transcription;
+        const transcriptBytes = Buffer.from(JSON.stringify(transcription.transcript)), transcriptHash = sha256(transcriptBytes);
+        const transcriptBlob = await store.blobs.put(token, transcriptHash, transcriptBytes.length, (async function* () {
+            yield transcriptBytes;
+        })());
+        const assets = [{ ...transcriptBlob, mediaType: 'application/json', relationship: 'transcript' }];
+        if (result.thumbnail) {
+            const blob = await store.blobs.put(token, result.thumbnail.sha256, result.thumbnail.bytes, bundleBytes(result.root, result.thumbnail));
+            assets.push({ ...blob, mediaType: result.thumbnail.mediaType, relationship: 'thumbnail' });
         }
-    }
-    catch (error) {
-        const raw = error?.code ?? (error instanceof Error ? error.message : '');
-        if (raw === 'cleanup-required')
-            cleanup = 'pending';
-        const code = ['cleanup-required', 'integrity', 'invalid-input', 'limit-exceeded', 'cancelled', 'owner-busy'].includes(raw) ? raw : 'unclassified';
-        outcome = failure(token.attemptId, code, 'storage');
-    }
-    // An uncertain native process may still be reading source bytes: preserve ownership.
-    if (captured && cleanup === 'settled')
-        try {
-            await captured.dispose();
+        if (options.signal?.aborted) {
+            store.queue.cancel(token.jobId);
+            throw new SpongeError('cancelled');
         }
-        catch {
-            cleanup = 'pending';
-        }
-    if (!committed)
-        try {
-            store.failAttempt(token, outcome.ok ? 'unclassified' : outcome.code, outcome.ok ? {} : { retryable: outcome.retryable, retryAfterMs: outcome.retryAfterMs });
-        }
-        catch {
-            cleanup = 'pending';
-        }
-    if (cleanup === 'settled')
-        try {
-            store.settleAttempt(token);
-        }
-        catch {
-            cleanup = 'pending';
-        }
-    return cleanup === 'pending' ? { ...failure(token.attemptId, 'cleanup-required', 'cleanup'), cleanup } : { ...outcome, cleanup };
+        const observedAt = new Date().toISOString(), metadata = [
+            { field: 'transcriptSource', value: transcription.transcript.source, source: 'media', observedAt },
+            { field: 'language', value: transcription.transcript.language, source: 'media', observedAt },
+            { field: 'durationMs', value: String(transcription.transcript.durationMs), source: 'media', observedAt },
+        ];
+        for (const field of ['title', 'author'])
+            if (result[field])
+                metadata.push({
+                    field: field === 'author' ? 'authors' : field,
+                    value: field === 'author' ? [result[field]] : result[field],
+                    source: 'media',
+                    observedAt,
+                    selected: true,
+                });
+        const status = result.warnings.length ? 'partial' : 'complete';
+        await options.checkpoint?.('promoting');
+        const revision = store.revisions.commit({
+            ...token,
+            itemId: source.itemId,
+            bundleHash: sha256(JSON.stringify(['media-transcript-v1', result.manifestSha256, transcriptHash])),
+            markdown: transcription.markdown,
+            title: result.title,
+            extractor: { name: 'sponge-media', version: '1' },
+            status,
+            metadata,
+            assets,
+            warnings: result.warnings.length ? ['partial'] : [],
+        });
+        return { ok: true, itemId: source.itemId, revisionId: revision.revisionId, status };
+    });
 }

package/dist/src/media/transcribe.js

@@ -1,17 +1,36 @@
-import { createHash } from 'node:crypto';
+import { sha256 } from '../util/hash.js';
 import { failure } from '../acquisition/errors.js';
 import { transcribeAudio } from '../inference/asr/runtime.js';
-const timestamp = (s) => { const m = /^(?:(\d{2,}):)?(\d{2}):(\d{2})\.(\d{3})$/.exec(s); if (!m || Number(m[2]) > 59 || Number(m[3]) > 59)
-    throw Error('integrity'); const n = ((Number(m[1] ?? 0) * 60 + Number(m[2])) * 60 + Number(m[3])) * 1000 + Number(m[4]); if (n > 86400000)
-    throw Error('limit-exceeded'); return n; };
-function plain(text) { return text.replace(/<[^>]*>/g, '').replace(/&(?:amp|lt|gt|quot|apos|nbsp);/g, s => ({ '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&nbsp;': ' ' })[s]).replace(/\s+/g, ' ').trim(); }
+import { SpongeError, codeOf } from '../errors.js';
+const timestamp = (s) => {
+    const m = /^(?:(\d{2,}):)?(\d{2}):(\d{2})\.(\d{3})$/.exec(s);
+    if (!m || Number(m[2]) > 59 || Number(m[3]) > 59)
+        throw new SpongeError('integrity');
+    const n = ((Number(m[1] ?? 0) * 60 + Number(m[2])) * 60 + Number(m[3])) * 1000 + Number(m[4]);
+    if (n > 86400000)
+        throw new SpongeError('limit-exceeded');
+    return n;
+};
+function plain(text) {
+    return text
+        .replace(/<[^>]*>/g, '')
+        .replace(/&(?:amp|lt|gt|quot|apos|nbsp);/g, (s) => ({ '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&nbsp;': ' ' })[s])
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 /** Strict, bounded timed WebVTT. Rolling captions only deduplicate already-overlapping text. */
 export function parseWebVtt(captions, requestId) {
-    if (Buffer.byteLength(captions.text) > 4 * 1024 ** 2 || createHash('sha256').update(captions.text).digest('hex') !== captions.sha256 || !['manual', 'automatic'].includes(captions.source) || !/^[a-zA-Z]{2,8}(?:-[a-zA-Z0-9]{1,8})*$/.test(captions.language) || !Number.isFinite(captions.durationMs) || captions.durationMs <= 0 || captions.durationMs > 86400000)
-        throw Error('integrity');
+    if (Buffer.byteLength(captions.text) > 4 * 1024 ** 2 ||
+        sha256(captions.text) !== captions.sha256 ||
+        !['manual', 'automatic'].includes(captions.source) ||
+        !/^[a-zA-Z]{2,8}(?:-[a-zA-Z0-9]{1,8})*$/.test(captions.language) ||
+        !Number.isFinite(captions.durationMs) ||
+        captions.durationMs <= 0 ||
+        captions.durationMs > 86400000)
+        throw new SpongeError('integrity');
     const text = captions.text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
     if (!/^WEBVTT(?:[ \t][^\n]*)?\n/.test(text) || text.includes('\0'))
-        throw Error('integrity');
+        throw new SpongeError('integrity');
     const segments = [];
     let lastStart = 0;
     let previousCue;
@@ -21,17 +40,17 @@ export function parseWebVtt(captions, requestId) {
             continue;
         const index = lines[0].includes('-->') ? 0 : 1, line = lines[index];
         if (!line)
-            throw Error('integrity');
+            throw new SpongeError('integrity');
         const match = /^(\S+)\s+-->\s+(\S+)(?:\s+.*)?$/.exec(line);
         if (!match)
-            throw Error('integrity');
+            throw new SpongeError('integrity');
         const startMs = timestamp(match[1]), endMs = timestamp(match[2]);
         if (startMs < lastStart || endMs <= startMs || endMs > captions.durationMs + 1000)
-            throw Error('integrity');
+            throw new SpongeError('integrity');
         lastStart = startMs;
         let cue = plain(lines.slice(index + 1).join(' '));
         if (Buffer.byteLength(cue) > 16384)
-            throw Error('limit-exceeded');
+            throw new SpongeError('limit-exceeded');
         if (!cue)
             continue;
         const previous = segments.at(-1), rawCue = cue;
@@ -51,29 +70,52 @@ export function parseWebVtt(captions, requestId) {
         }
         segments.push({ startMs, endMs, text: cue });
         if (segments.length > 30000)
-            throw Error('limit-exceeded');
+            throw new SpongeError('limit-exceeded');
     }
     if (!segments.length)
-        throw Error('unsupported');
-    return { schemaVersion: 1, requestId, source: captions.source === 'manual' ? 'human-captions' : 'automatic-captions', language: captions.language, segments, cleanup: 'settled', sourceSha256: captions.sha256, timing: 'source-captions', durationMs: captions.durationMs };
+        throw new SpongeError('unsupported');
+    return {
+        schemaVersion: 1,
+        requestId,
+        source: captions.source === 'manual' ? 'human-captions' : 'automatic-captions',
+        language: captions.language,
+        segments,
+        cleanup: 'settled',
+        sourceSha256: captions.sha256,
+        timing: 'source-captions',
+        durationMs: captions.durationMs,
+    };
 }
-const stamp = (ms) => { const seconds = Math.floor(ms / 1000); return [Math.floor(seconds / 3600), Math.floor(seconds / 60) % 60, seconds % 60].map(n => String(n).padStart(2, '0')).join(':'); };
+const stamp = (ms) => {
+    const seconds = Math.floor(ms / 1000);
+    return [Math.floor(seconds / 3600), Math.floor(seconds / 60) % 60, seconds % 60]
+        .map((n) => String(n).padStart(2, '0'))
+        .join(':');
+};
 export function transcriptMarkdown(transcript) {
     const paragraphs = [];
     for (const segment of transcript.segments) {
         const prior = paragraphs.at(-1);
-        if (transcript.source === 'local-asr' && prior && segment.startMs - prior.endMs <= 2000 && segment.endMs - prior.startMs <= 15000 && !/[.!?]["')]*$/.test(prior.text)) {
+        if (transcript.source === 'local-asr' &&
+            prior &&
+            segment.startMs - prior.endMs <= 2000 &&
+            segment.endMs - prior.startMs <= 15000 &&
+            !/[.!?]["')]*$/.test(prior.text)) {
             prior.text += ' ' + segment.text;
             prior.endMs = segment.endMs;
         }
         else
             paragraphs.push({ ...segment });
     }
-    return paragraphs.map(s => `[${stamp(s.startMs)}] ${s.text.replace(/[\\`*_{}\[\]()<>!#|]/g, '\\$&')}`).join('\n\n') + '\n';
+    return (paragraphs.map((s) => `[${stamp(s.startMs)}] ${s.text.replace(/[\\`*_{}\[\]()<>!#|]/g, '\\$&')}`).join('\n\n') +
+        '\n');
 }
 /** Acquisition owns media lifetime; transcription never deletes or mutates caller source files. */
 export async function transcribeMedia(input, options) {
-    const failed = (code) => ({ ...failure(input.requestId, code, 'inference'), cleanup: 'settled' });
+    const failed = (code) => ({
+        ...failure(input.requestId, code, 'inference'),
+        cleanup: 'settled',
+    });
     if (options.signal?.aborted)
         return failed('cancelled');
     if (input.captions && !input.forceLocal) {
@@ -82,8 +124,8 @@ export async function transcribeMedia(input, options) {
             return { ok: true, transcript, markdown: transcriptMarkdown(transcript), cleanup: 'settled' };
         }
         catch (e) {
-            if (!(e instanceof Error) || e.message !== 'unsupported' || !input.audio)
-                return failed(e instanceof Error && e.message === 'limit-exceeded' ? 'limit-exceeded' : 'integrity');
+            if (codeOf(e) !== 'unsupported' || !input.audio)
+                return failed(codeOf(e) === 'limit-exceeded' ? 'limit-exceeded' : 'integrity');
         }
     }
     if (!input.audio)

package/dist/src/metadata/article.js

@@ -1,26 +1,58 @@
 import { limits } from '../../contracts/index.js';
 import { validateMetadataClaim, validateMetadataWarnings } from '../../contracts/validate.js';
-function object(v) { if (!v || typeof v !== 'object' || Array.isArray(v))
-    throw Error('integrity'); return v; }
+import { SpongeError } from '../errors.js';
+function object(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        throw new SpongeError('integrity');
+    return v;
+}
 /** Consume bounded observed Wordcell evidence without fetching linked JSON-LD contexts. */
 export function articleMetadata(input, observedAt) {
     const envelope = object(input);
     articleMetadataWarnings(input);
     if (envelope.schemaVersion !== 1 || envelope.extractorVersion !== 'wordcell-metadata-v1')
-        throw Error('schema-newer');
-    if (!Array.isArray(envelope.claims) || envelope.claims.length > limits.metadataClaims || Buffer.byteLength(JSON.stringify(input)) > limits.metadataBytes)
-        throw Error('limit-exceeded');
-    const claims = envelope.claims.map(raw => {
+        throw new SpongeError('schema-newer');
+    if (!Array.isArray(envelope.claims) ||
+        envelope.claims.length > limits.metadataClaims ||
+        Buffer.byteLength(JSON.stringify(input)) > limits.metadataBytes)
+        throw new SpongeError('limit-exceeded');
+    const claims = envelope.claims.map((raw) => {
         const claim = object(raw), locator = claim.locator;
         if (typeof locator !== 'string' || typeof claim.selected !== 'boolean')
-            throw Error('integrity');
-        const sources = { 'html-title': 'html', 'html-meta': 'html', 'html-link': 'html', 'html-language': 'html', 'json-ld': 'jsonld', extractor: 'html' };
+            throw new SpongeError('integrity');
+        const sources = {
+            'html-title': 'html',
+            'html-meta': 'html',
+            'html-link': 'html',
+            'html-language': 'html',
+            'json-ld': 'jsonld',
+            extractor: 'html',
+        };
         if (typeof claim.source !== 'string' || !Object.hasOwn(sources, claim.source))
-            throw Error('integrity');
-        const source = /^meta\[(?:property|name)=og:/.test(locator) ? 'opengraph' : /^meta\[(?:property|name)=twitter:/.test(locator) ? 'twitter' : sources[claim.source];
-        if (claim.timezone !== undefined && (typeof claim.timezone !== 'string' || !['explicit', 'unknown', 'not-applicable'].includes(claim.timezone)))
-            throw Error('integrity');
-        const result = { field: claim.field, value: claim.value, observed: claim.observed, source, locator, selected: claim.selected, observedAt, rule: claim.rule, extractionVersion: envelope.extractorVersion, ...(claim.datePrecision !== undefined ? { datePrecision: claim.datePrecision } : {}), ...(claim.timezone === 'explicit' || claim.timezone === 'unknown' ? { timezoneKnown: claim.timezone === 'explicit' } : {}) };
+            throw new SpongeError('integrity');
+        const source = /^meta\[(?:property|name)=og:/.test(locator)
+            ? 'opengraph'
+            : /^meta\[(?:property|name)=twitter:/.test(locator)
+                ? 'twitter'
+                : sources[claim.source];
+        if (claim.timezone !== undefined &&
+            (typeof claim.timezone !== 'string' || !['explicit', 'unknown', 'not-applicable'].includes(claim.timezone)))
+            throw new SpongeError('integrity');
+        const result = {
+            field: claim.field,
+            value: claim.value,
+            observed: claim.observed,
+            source,
+            locator,
+            selected: claim.selected,
+            observedAt,
+            rule: claim.rule,
+            extractionVersion: envelope.extractorVersion,
+            ...(claim.datePrecision !== undefined ? { datePrecision: claim.datePrecision } : {}),
+            ...(claim.timezone === 'explicit' || claim.timezone === 'unknown'
+                ? { timezoneKnown: claim.timezone === 'explicit' }
+                : {}),
+        };
         validateMetadataClaim(result);
         return result;
     });
@@ -30,14 +62,14 @@ export function articleMetadata(input, observedAt) {
         if (!claim.selected)
             continue;
         if (selected.has(claim.field) && !['authors', 'tags', 'alternate'].includes(claim.field))
-            throw Error('integrity');
+            throw new SpongeError('integrity');
         selected.add(claim.field);
     }
     return claims;
 }
 export function selectedMetadata(claims, field) {
-    const matches = claims.filter(claim => claim.field === field);
-    return matches.find(claim => claim.selected === true) ?? matches.find(claim => claim.selected === undefined);
+    const matches = claims.filter((claim) => claim.field === field);
+    return matches.find((claim) => claim.selected === true) ?? matches.find((claim) => claim.selected === undefined);
 }
 export function articleMetadataWarnings(input) {
     const envelope = object(input);
@@ -45,7 +77,7 @@ export function articleMetadataWarnings(input) {
         validateMetadataWarnings(envelope.warnings);
     }
     catch {
-        throw Error('integrity');
+        throw new SpongeError('integrity');
     }
     return [...envelope.warnings];
 }

package/dist/src/models/artifacts.d.ts

@@ -10,10 +10,6 @@ export interface ModelPackage {
     license: string;
     artifacts: readonly ModelArtifact[];
 }
-export declare class ModelSetupError extends Error {
-    readonly code: 'invalid-input' | 'integrity' | 'unavailable' | 'cancelled' | 'owner-busy' | 'limit-exceeded' | 'cleanup-required' | 'repair-auth';
-    constructor(code: 'invalid-input' | 'integrity' | 'unavailable' | 'cancelled' | 'owner-busy' | 'limit-exceeded' | 'cleanup-required' | 'repair-auth');
-}
 export declare function modelSetupPlan(manifest: ModelPackage): {
     id: string;
     license: string;
@@ -23,14 +19,20 @@ export declare function modelSetupPlan(manifest: ModelPackage): {
     artifacts: readonly ModelArtifact[];
 };
 export declare function inspectModelPackage(cacheRoot: string, manifest: ModelPackage): Promise<Record<string, string>>;
-/** Explicit recovery only: an absent or different process birth identity proves the downloader is gone.
- * Downloading is in-process fetch; no native child can outlive this owner. A missing or
- * foreign stage receipt remains pending, as does an interrupted recovery guard. */
 export declare function recoverModelPackage(cacheRoot: string, manifest: ModelPackage): Promise<{
     recovered: boolean;
 }>;
-/** Explicit setup only. Never called by install hooks or by inference fallback. */
+/** Explicit setup only. Never called by install hooks or by inference fallback, except `reuseOnly`: that adopts an
+ * installed package from verified local artifacts under the same setup lock and never reaches the network. */
 export declare function provisionModelPackage(cacheRoot: string, manifest: ModelPackage, options?: {
     signal?: AbortSignal;
     fetch?: typeof fetch;
+    reuseOnly?: boolean;
 }): Promise<Record<string, string>>;
+/** The installed package for this manifest, by content, or null when none is. A package installed under an earlier
+ * URL-bound fingerprint is adopted once: its verified artifacts are hard-linked into the content-named directory under
+ * the setup lock (no network; the old directory stays intact for any process holding its paths until runtime GC
+ * supersedes it). Anything short of a fully verified adoption is reported as not installed, as before. */
+export declare function inspectInstalledModelPackage(cacheRoot: string, manifest: ModelPackage, options?: {
+    pause?: (ms: number) => Promise<void>;
+}): Promise<Record<string, string> | null>;