@hraness/sponge 0.1.2 → 0.2.1

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

@@ -0,0 +1,47 @@
+import { runOwned } from '../../acquisition/process.js';
+export declare const embeddingIdentity: {
+    readonly modelSha256: "92dcbea108899e5d6e30d919b0744f90d9967e80c67a4ab5503ac16d54f62eb0";
+    readonly librarySha256: "9526db9ee35e7eb4a5a58ac1e53330032f22a13890bd4ee01818fb380a57a362";
+    readonly runtime: "LiteRT-LM@0.18.0";
+    readonly dimensions: 768;
+    readonly normalization: "unit-l2";
+    readonly preprocessing: "sips-max512-png-litert-v1";
+    readonly prompt: "search-result-query-title-none-v1";
+    readonly protocol: 1;
+    readonly backend: "cpu-2threads-f32";
+};
+export type EmbeddingInput = {
+    kind: 'query' | 'document';
+    text: string;
+} | {
+    kind: 'image';
+    png: Uint8Array;
+};
+export interface EmbeddingRuntime {
+    helper: string;
+    helperSha256: string;
+    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;
+/** Versioned length-delimited bytes. No user content or image pathname enters argv. */
+export declare function encodeEmbeddingRequest(inputs: readonly EmbeddingInput[]): {
+    bytes: Buffer;
+    inputHashes: string[];
+};
+export declare function parseEmbeddingOutput(stdout: string, count: number): number[][];
+export declare function embedBatch(inputs: readonly EmbeddingInput[], options: {
+    runtime: EmbeddingRuntime;
+    scratchRoot: string;
+    signal?: AbortSignal;
+    runProcess?: typeof runOwned;
+}): Promise<{
+    fingerprint: string;
+    inputHashes: string[];
+    vectors: number[][];
+}>;

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

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+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' };
+export class EmbeddingError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+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 }); }
+/** Versioned length-delimited bytes. No user content or image pathname enters argv. */
+export function encodeEmbeddingRequest(inputs) {
+    if (!inputs.length || inputs.length > 16)
+        fail('limit-exceeded');
+    const parts = [Buffer.from('SPGEMB01'), Buffer.from([inputs.length])], inputHashes = [];
+    for (const input of inputs) {
+        let payload, kind;
+        if (input.kind === 'image') {
+            payload = Buffer.from(input.png);
+            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)
+                fail('unsupported');
+            const w = payload.readUInt32BE(16), h = payload.readUInt32BE(20);
+            if (!w || !h || w * h > 262144)
+                fail('limit-exceeded');
+        }
+        else {
+            if (input.kind !== 'query' && input.kind !== 'document')
+                fail('unsupported');
+            if (typeof input.text !== 'string' || !input.text.trim() || input.text.includes('\0'))
+                fail();
+            payload = Buffer.from((input.kind === 'query' ? 'task: search result | query: ' : 'title: none | text: ') + input.text);
+            kind = 1;
+            if (payload.length > 8192)
+                fail('limit-exceeded');
+        }
+        const header = Buffer.alloc(5);
+        header[0] = kind;
+        header.writeUInt32BE(payload.length, 1);
+        parts.push(header, payload);
+        inputHashes.push(hash(Buffer.concat([header, payload])));
+    }
+    return { bytes: Buffer.concat(parts), inputHashes };
+}
+export function parseEmbeddingOutput(stdout, count) {
+    if (Buffer.byteLength(stdout) > 512 * 1024)
+        fail('limit-exceeded');
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        fail();
+    }
+    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; });
+}
+async function verify(path, expected) {
+    if (!isAbsolute(path) || !/^[a-f0-9]{64}$/.test(expected))
+        fail();
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await file.stat();
+        if (!before.isFile())
+            fail();
+        const digest = createHash('sha256');
+        for await (const chunk of file.createReadStream({ autoClose: false }))
+            digest.update(chunk);
+        const after = await file.stat();
+        if (digest.digest('hex') !== expected || before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+            fail();
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function embedBatch(inputs, options) {
+    const request = encodeEmbeddingRequest(inputs), r = options.runtime, fingerprint = embeddingFingerprint(r.helperSha256);
+    if (options.signal?.aborted)
+        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'))
+        fail();
+    const scratch = await mkdtemp(join(options.scratchRoot, 'embedding-'));
+    await chmod(scratch, 0o700);
+    let settled = true;
+    try {
+        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 });
+        settled = result.cleanup === 'settled';
+        if (!settled)
+            fail('cleanup-required');
+        if (result.stopped)
+            fail(result.stopped);
+        if (result.code !== 0)
+            fail('unavailable');
+        return { fingerprint, inputHashes: request.inputHashes, vectors: parseEmbeddingOutput(result.stdout, inputs.length) };
+    }
+    finally {
+        if (settled)
+            await rm(scratch, { recursive: true, force: true });
+    }
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+/** Public Ghostget SDK bridge; its complete inherited group belongs to the caller. */
+import { readFile } from 'node:fs/promises';
+import { processIdentity } from '../worker/identity.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 } });
+    process.stdout.write(JSON.stringify(result));
+}
+catch {
+    process.stdout.write(JSON.stringify({ ok: false, code: 'unavailable', cleanup: 'settled' }));
+    process.exitCode = 1;
+}

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

@@ -0,0 +1,32 @@
+import type { Asset, ErrorEnvelope } from '../../contracts/index.js';
+import { type CaptureRuntime } from '../acquisition/runtime.js';
+import { runOwned } from '../acquisition/process.js';
+import type { CaptureConnection } from '../acquisition/index.js';
+import type { AudioInput } from '../inference/asr/runtime.js';
+import type { CaptionInput } from './transcribe.js';
+export interface MediaCaptureRequest {
+    requestId: string;
+    sourceUrl: string;
+    runtime: CaptureRuntime;
+    stagingRoot: string;
+    connection?: CaptureConnection;
+    language?: string;
+    forceLocal?: boolean;
+    signal?: AbortSignal;
+    runProcess?: typeof runOwned;
+}
+export interface CapturedMedia {
+    ok: true;
+    root: string;
+    audio?: AudioInput;
+    captions?: CaptionInput;
+    thumbnail?: Asset;
+    title?: string;
+    author?: string;
+    manifestSha256: string;
+    warnings: string[];
+    dispose: () => Promise<void>;
+}
+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>;

package/dist/src/media/capture.js

@@ -0,0 +1,193 @@
+import { constants } from 'node:fs';
+import { open, mkdir, mkdtemp, writeFile, statfs, realpath } from 'node:fs/promises';
+import { join, relative, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { limits } from '../../contracts/index.js';
+import { failure } from '../acquisition/errors.js';
+import { inspectCaptureRuntime, CaptureSetupError } 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');
+/** All ephemeral bytes remain below one capture owner; deletion requires a settled process tree. */
+export async function captureMedia(request) {
+    const { requestId, signal } = request;
+    if (!/^[A-Za-z0-9-]{1,128}$/.test(requestId))
+        return failure('invalid-request', 'invalid-input');
+    let url;
+    try {
+        url = new URL(request.sourceUrl);
+        if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || request.sourceUrl.length > 16384)
+            throw Error();
+    }
+    catch {
+        return failure(requestId, 'invalid-input');
+    }
+    url.hash = '';
+    if (request.connection?.kind === 'cdp')
+        return failure(requestId, 'unsupported');
+    if (signal?.aborted)
+        return failure(requestId, 'cancelled');
+    let runtime, base;
+    try {
+        runtime = await inspectCaptureRuntime(request.runtime.root, request.runtime.pins);
+        base = await privateRoot(request.stagingRoot);
+        const disk = await statfs(base);
+        if (disk.bavail * disk.bsize < limits.stagingBytes + limits.freeReserveBytes)
+            return failure(requestId, 'limit-exceeded');
+    }
+    catch (error) {
+        return failure(requestId, error instanceof CaptureSetupError ? error.code : 'invalid-input');
+    }
+    let selectedState;
+    if (request.connection?.kind === 'account') {
+        if (!/^[A-Za-z0-9_.-]{1,128}$/.test(request.connection.accountId))
+            return failure(requestId, 'invalid-input');
+        try {
+            selectedState = await privateRoot(request.connection.stateHome);
+        }
+        catch {
+            return failure(requestId, 'repair-auth');
+        }
+    }
+    const root = await realpath(await mkdtemp(join(base, 'capture-'))), home = join(root, 'home');
+    let cleanup = 'settled', keep = false, checking = false, quota = false;
+    const controller = new AbortController(), abort = () => controller.abort();
+    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) {
+            quota = true;
+            controller.abort();
+        }
+    }
+    catch {
+        quota = true;
+        controller.abort();
+    }
+    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 });
+        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' });
+        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;
+        environment.XDG_CONFIG_HOME = home;
+        environment.XDG_STATE_HOME = home;
+        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 });
+        cleanup = result.cleanup;
+        if (cleanup === 'pending')
+            return failure(requestId, 'cleanup-required', 'cleanup');
+        if (quota)
+            return failure(requestId, 'limit-exceeded');
+        if (result.stopped)
+            return failure(requestId, result.stopped);
+        const parsed = JSON.parse(result.stdout);
+        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' };
+            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(); } };
+        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');
+                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');
+            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');
+                const path = join(mediaRoot, relativePath);
+                if (await realpath(path) !== path)
+                    throw Error('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');
+                    const digest = createHash('sha256'), buffer = Buffer.alloc(65536);
+                    let bytes = 0;
+                    for (;;) {
+                        const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+                        if (!bytesRead)
+                            break;
+                        bytes += bytesRead;
+                        if (bytes > file.bytes)
+                            throw Error('limit-exceeded');
+                        digest.update(buffer.subarray(0, bytesRead));
+                    }
+                    if (bytes !== file.bytes || digest.digest('hex') !== file.sha256)
+                        throw Error('integrity');
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            else {
+                data = await readConfined(mediaRoot, relativePath, maximum);
+                if (data.length !== file.bytes || hash(data) !== file.sha256)
+                    throw Error('integrity');
+            }
+            if (file.role === 'audio')
+                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 };
+            }
+            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;
+                if (!mediaType)
+                    throw Error('integrity');
+                captured.thumbnail = { relativePath, bytes: file.bytes, sha256: file.sha256, mediaType };
+            }
+        }
+        if (!captured.audio && !captured.captions)
+            throw Error('integrity');
+        if (controller.signal.aborted)
+            return failure(requestId, quota ? 'limit-exceeded' : 'cancelled');
+        keep = true;
+        return captured;
+    }
+    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');
+    }
+    finally {
+        clearInterval(monitor);
+        while (checking)
+            await new Promise(r => setTimeout(r, 5));
+        signal?.removeEventListener('abort', abort);
+        if (!keep && cleanup === 'settled' && await settleCaptureRoot(root, requestId) === 'pending')
+            return failure(requestId, 'cleanup-required', 'cleanup');
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { ErrorEnvelope, JobCheckpoint } from '../../contracts/index.js';
+import type { LibraryStore, AttemptToken } from '../store/index.js';
+import type { AsrRuntime } from '../inference/asr/runtime.js';
+import { type MediaCaptureRequest, type MediaCaptureOutcome } from './capture.js';
+import { transcribeMedia } from './transcribe.js';
+export interface MediaOptions extends Omit<MediaCaptureRequest, 'requestId' | 'sourceUrl' | 'stagingRoot'> {
+    asrRuntime?: AsrRuntime;
+    forceLocal?: boolean;
+    checkpoint?: (stage: JobCheckpoint['stage']) => Promise<void>;
+    capture?: (request: MediaCaptureRequest) => Promise<MediaCaptureOutcome>;
+    transcribe?: typeof transcribeMedia;
+}
+export type MediaOutcome = ({
+    ok: true;
+    itemId: string;
+    revisionId: string;
+    status: 'complete' | 'partial';
+} | 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>;

package/dist/src/media/handler.js

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { failure } from '../acquisition/errors.js';
+import { bundleBytes } from '../app/bundle-files.js';
+import { runOwned } from '../acquisition/process.js';
+import { captureMedia } from './capture.js';
+import { transcribeMedia } from './transcribe.js';
+/** 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);
+        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 });
+        if (!result.ok) {
+            outcome = result;
+            cleanup = result.code === 'cleanup-required' ? 'pending' : 'settled';
+        }
+        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 };
+            }
+        }
+    }
+    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();
+        }
+        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 };
+}

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

@@ -0,0 +1,29 @@
+import type { ErrorEnvelope } from '../../contracts/index.js';
+import { type AudioInput, type AsrOptions } from '../inference/asr/runtime.js';
+import type { SourceTranscript } from '../inference/asr/protocol.js';
+export interface CaptionInput {
+    text: string;
+    sha256: string;
+    source: 'manual' | 'automatic';
+    language: string;
+    durationMs: number;
+}
+export interface TranscriptionInput {
+    requestId: string;
+    captions?: CaptionInput;
+    audio?: AudioInput;
+    language?: string;
+    forceLocal?: boolean;
+}
+export type TranscriptionOutcome = ({
+    ok: true;
+    transcript: SourceTranscript;
+    markdown: string;
+} | ErrorEnvelope) & {
+    cleanup: 'settled' | 'pending';
+};
+/** Strict, bounded timed WebVTT. Rolling captions only deduplicate already-overlapping text. */
+export declare function parseWebVtt(captions: CaptionInput, requestId: string): SourceTranscript;
+export declare function transcriptMarkdown(transcript: SourceTranscript): string;
+/** Acquisition owns media lifetime; transcription never deletes or mutates caller source files. */
+export declare function transcribeMedia(input: TranscriptionInput, options: AsrOptions): Promise<TranscriptionOutcome>;

package/dist/src/media/transcribe.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+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(); }
+/** 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');
+    const text = captions.text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+    if (!/^WEBVTT(?:[ \t][^\n]*)?\n/.test(text) || text.includes('\0'))
+        throw Error('integrity');
+    const segments = [];
+    let lastStart = 0;
+    let previousCue;
+    for (const block of text.split(/\n[ \t]*\n/).slice(1)) {
+        const lines = block.trim().split('\n');
+        if (!lines[0] || /^(NOTE(?:\s|$)|STYLE$|REGION$)/.test(lines[0]))
+            continue;
+        const index = lines[0].includes('-->') ? 0 : 1, line = lines[index];
+        if (!line)
+            throw Error('integrity');
+        const match = /^(\S+)\s+-->\s+(\S+)(?:\s+.*)?$/.exec(line);
+        if (!match)
+            throw Error('integrity');
+        const startMs = timestamp(match[1]), endMs = timestamp(match[2]);
+        if (startMs < lastStart || endMs <= startMs || endMs > captions.durationMs + 1000)
+            throw Error('integrity');
+        lastStart = startMs;
+        let cue = plain(lines.slice(index + 1).join(' '));
+        if (Buffer.byteLength(cue) > 16384)
+            throw Error('limit-exceeded');
+        if (!cue)
+            continue;
+        const previous = segments.at(-1), rawCue = cue;
+        const prior = previousCue;
+        previousCue = { text: rawCue, endMs };
+        if (previous && prior && startMs < prior.endMs) {
+            const a = prior.text.split(' '), b = cue.split(' ');
+            let overlap = 0;
+            for (let n = 1; n <= Math.min(a.length, b.length); n++)
+                if (a.slice(-n).join(' ') === b.slice(0, n).join(' '))
+                    overlap = n;
+            cue = b.slice(overlap).join(' ');
+            if (!cue) {
+                previous.endMs = Math.max(previous.endMs, endMs);
+                continue;
+            }
+        }
+        segments.push({ startMs, endMs, text: cue });
+        if (segments.length > 30000)
+            throw Error('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 };
+}
+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)) {
+            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';
+}
+/** 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' });
+    if (options.signal?.aborted)
+        return failed('cancelled');
+    if (input.captions && !input.forceLocal) {
+        try {
+            const transcript = parseWebVtt(input.captions, input.requestId);
+            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 (!input.audio)
+        return failed('unsupported');
+    const result = await transcribeAudio(input.requestId, input.audio, input.language, options);
+    return result.ok ? { ...result, markdown: transcriptMarkdown(result.transcript) } : result;
+}

package/dist/src/metadata/article.d.ts

@@ -0,0 +1,5 @@
+import type { MetadataClaim, MetadataWarning } from '../../contracts/index.js';
+/** Consume bounded observed Wordcell evidence without fetching linked JSON-LD contexts. */
+export declare function articleMetadata(input: unknown, observedAt: string): MetadataClaim[];
+export declare function selectedMetadata(claims: readonly MetadataClaim[], field: string): MetadataClaim | undefined;
+export declare function articleMetadataWarnings(input: unknown): MetadataWarning[];