@hraness/sponge 0.1.2 → 0.2.0

package/dist/src/models/runtime.js

@@ -0,0 +1,37 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { privateRoot } from '../acquisition/files.js';
+import { nativeArtifactFetch } from './download.js';
+import { inspectModelPackage, provisionModelPackage, recoverModelPackage, modelSetupPlan, ModelSetupError } from './artifacts.js';
+import { nativePlatformSupported, nativeModelPackage, NativeCatalogError, loadNativeCatalog } from './catalog.js';
+export async function nativeSetupPlan(kind, version) { const catalog = await loadNativeCatalog(version); return { ...modelSetupPlan(nativeModelPackage(catalog, kind)), supported: nativePlatformSupported(), minimumMacOS: '26.0' }; }
+function supported() { if (!nativePlatformSupported())
+    throw new NativeCatalogError('unsupported'); }
+function asr(c, p) { return { helper: p['sponge-speech'], helperSha256: c.artifacts.find(a => a.role === 'asr-helper').sha256, model: p['whistle.cact'] }; }
+function embedding(c, p) { return { helper: p['sponge-embedding'], helperSha256: c.artifacts.find(a => a.role === 'embedding-helper').sha256, library: p['libCLiteRTLM_mac.dylib'], model: p['embeddinggemma-2-text-vision-440m.litertlm'] }; }
+export async function setupNativeRuntime(cacheRoot, catalog, kind, options = {}) { supported(); if (options.signal?.aborted)
+    throw new ModelSetupError('cancelled'); const manifest = nativeModelPackage(catalog, kind); await privateRoot(dirname(cacheRoot)); try {
+    await mkdir(cacheRoot, { mode: 0o700 });
+}
+catch (error) {
+    if (error.code !== 'EEXIST')
+        throw error;
+} await privateRoot(cacheRoot); await recoverModelPackage(cacheRoot, manifest); const paths = await provisionModelPackage(cacheRoot, manifest, { ...options, fetch: nativeArtifactFetch(manifest) }); return kind === 'asr' ? asr(catalog, paths) : embedding(catalog, paths); }
+export async function inspectAsrRuntime(cacheRoot, catalog) { supported(); try {
+    return asr(catalog, await inspectModelPackage(cacheRoot, nativeModelPackage(catalog, 'asr')));
+}
+catch (error) {
+    if (error.code === 'ENOENT')
+        throw new NativeCatalogError('runtime-missing');
+    throw error;
+} }
+export async function inspectEmbeddingRuntime(cacheRoot, catalog) { supported(); try {
+    return embedding(catalog, await inspectModelPackage(cacheRoot, nativeModelPackage(catalog, 'embedding')));
+}
+catch (error) {
+    if (error.code === 'ENOENT')
+        throw new NativeCatalogError('runtime-missing');
+    throw error;
+} }
+export async function provisionNative(kind, cacheRoot, version, signal) { return setupNativeRuntime(cacheRoot, await loadNativeCatalog(version), kind, { signal }); }
+export async function inspectNative(kind, cacheRoot, version) { const catalog = await loadNativeCatalog(version); return kind === 'asr' ? inspectAsrRuntime(cacheRoot, catalog) : inspectEmbeddingRuntime(cacheRoot, catalog); }

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

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

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

@@ -0,0 +1,12 @@
+// Pinned public SDK bridge. Native subprocesses inherit the supervisor's group.
+const runtime = process.argv[2], args = process.argv.slice(3);
+try {
+    const { runPdfAcquisition } = await import(import.meta.resolve('@hraness/ghostget/pdf-acquisition', `${runtime}/package.json`));
+    const { runPdfToolCommand } = await import(import.meta.resolve('@hraness/wordcell/pdf', `${runtime}/package.json`));
+    process.exitCode = await runPdfAcquisition(args, process.env, { stdout: (value) => process.stdout.write(value), stderr: (value) => process.stderr.write(value) }, { runTool: (specification) => runPdfToolCommand({ ...specification, processGroup: 'inherit' }) });
+}
+catch {
+    process.stdout.write(JSON.stringify({ ok: false, code: 'unknown' }));
+    process.exitCode = 1;
+}
+export {};

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

@@ -0,0 +1,29 @@
+import type { CaptureResult, ErrorEnvelope } from '../../contracts/index.js';
+import { runOwned } from '../acquisition/process.js';
+import { type CaptureRuntime } from '../acquisition/runtime.js';
+export type CaptureConnection = {
+    kind: 'account';
+    stateHome: string;
+    accountId: string;
+} | {
+    kind: 'cdp';
+    endpoint: string;
+};
+export interface PdfCaptureRequest {
+    runtime: CaptureRuntime;
+    stagingRoot: string;
+    sourceUrl: string;
+    requestId: string;
+    connection?: CaptureConnection;
+    signal?: AbortSignal;
+    deadlineMs?: number;
+    allowPrivateNetwork?: boolean;
+    runProcess?: typeof runOwned;
+}
+export type CaptureOutcome = {
+    ok: true;
+    capture: CaptureResult;
+    bundleRoot: string;
+    dispose: () => Promise<void>;
+} | ErrorEnvelope;
+export declare function capturePdf(request: PdfCaptureRequest): Promise<CaptureOutcome>;

package/dist/src/pdf/capture.js

@@ -0,0 +1,156 @@
+import { mkdir, mkdtemp, writeFile, statfs, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { limits } from '../../contracts/index.js';
+import { privateRoot, physicalBytes } from '../acquisition/files.js';
+import { runOwned, isolatedEnvironment } from '../acquisition/process.js';
+import { inspectCaptureRuntime, CaptureSetupError } from '../acquisition/runtime.js';
+import { settleCaptureRoot, CaptureCleanupError } from '../acquisition/cleanup.js';
+import { failure } from '../acquisition/errors.js';
+import { object } from '../acquisition/normalize.js';
+import { normalizePdfBundle } from './normalize.js';
+import { copyPdfInput } from './input.js';
+import { pdfFailure } from './errors.js';
+export async function capturePdf(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 (!['http:', 'https:', 'file:'].includes(url.protocol) || url.username || url.password || request.sourceUrl.length > 16384)
+            throw Error();
+    }
+    catch {
+        return failure(requestId, 'invalid-input');
+    }
+    if (signal?.aborted)
+        return failure(requestId, 'cancelled');
+    let runtime;
+    try {
+        runtime = await inspectCaptureRuntime(request.runtime.root, request.runtime.pins);
+    }
+    catch (error) {
+        return failure(requestId, error instanceof CaptureSetupError ? error.code : 'runtime-missing', 'setup');
+    }
+    let base;
+    try {
+        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 {
+        return failure(requestId, 'invalid-input');
+    }
+    const deadline = request.deadlineMs ?? limits.captureDeadlineMs;
+    if (!Number.isSafeInteger(deadline) || deadline < 100 || deadline > limits.captureDeadlineMs)
+        return failure(requestId, 'invalid-input');
+    if (url.protocol === 'file:' && (url.host || url.search || url.hash || request.connection))
+        return failure(requestId, 'invalid-input');
+    if (request.connection?.kind === 'cdp' || request.allowPrivateNetwork)
+        return failure(requestId, 'unsupported');
+    const captureHelper = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './capture-helper.ts' : './capture-helper.js', import.meta.url));
+    const args = [captureHelper, runtime.root, request.sourceUrl, '--slug', 'document', '--timeout-ms', String(deadline), '--max-pdf-bytes', String(limits.pdfBytes), '--max-pages', '500', '--max-images', String(limits.imagesPerItem), '--max-asset-bytes', String(limits.imageBytes), '--max-total-asset-bytes', String(500 * 1024 ** 2), '--quiet', '--json'];
+    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');
+        }
+        args.push('--auth', request.connection.accountId);
+    }
+    const root = await realpath(await mkdtemp(join(base, 'capture-'))), home = join(root, 'home'), output = join(root, 'bundles');
+    args.push('--output', output);
+    const env = isolatedEnvironment(home, home, selectedState ?? join(home, 'state'));
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted)
+        abort();
+    let cleanup = 'settled', keep = false, quota = false, checking = false;
+    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);
+    const started = Date.now();
+    try {
+        await mkdir(home, { mode: 0o700 });
+        await mkdir(output, { mode: 0o700 });
+        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'acquiring' }), { mode: 0o600 });
+        let sourceHash;
+        if (url.protocol === 'file:') {
+            sourceHash = await copyPdfInput(fileURLToPath(url), join(root, 'input.pdf'), controller.signal);
+            args[2] = join(root, 'input.pdf');
+        }
+        cleanup = 'pending';
+        const result = await (request.runProcess ?? runOwned)(runtime.bun, args, { cwd: root, env, signal: controller.signal, deadlineMs: Math.max(1, deadline - (Date.now() - started)), maxOutputBytes: limits.metadataBytes, graceMs: 5000 });
+        cleanup = result.cleanup;
+        let summary;
+        try {
+            summary = JSON.parse(result.stdout);
+        }
+        catch {
+            summary = null;
+        }
+        const upstream = pdfFailure(summary, requestId);
+        if (upstream.code === 'cleanup-required')
+            cleanup = 'pending';
+        if (cleanup !== 'settled')
+            return failure(requestId, 'cleanup-required', 'cleanup');
+        if (quota)
+            return failure(requestId, 'limit-exceeded');
+        if (result.stopped)
+            return failure(requestId, result.stopped);
+        if (result.code !== 0 || object(summary).ok !== true)
+            return upstream;
+        const outputDirectory = object(summary).outputDirectory;
+        if (typeof outputDirectory !== 'string' || !outputDirectory.startsWith(output + '/') || await realpath(outputDirectory) !== outputDirectory)
+            return failure(requestId, 'integrity', 'verification');
+        const helper = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './verify-helper.ts' : './verify-helper.js', import.meta.url));
+        cleanup = 'pending';
+        const checked = await (request.runProcess ?? runOwned)(runtime.bun, [helper, runtime.root, outputDirectory, request.sourceUrl], { cwd: root, env, signal: controller.signal, deadlineMs: Math.max(1, deadline - (Date.now() - started)), maxOutputBytes: limits.helperFrameBytes });
+        cleanup = checked.cleanup;
+        if (cleanup !== 'settled')
+            return failure(requestId, 'cleanup-required', 'cleanup');
+        if (checked.stopped)
+            return failure(requestId, checked.stopped);
+        if (checked.code !== 0)
+            return failure(requestId, 'integrity', 'verification');
+        const capture = await normalizePdfBundle({ bundleRoot: outputDirectory, inspection: JSON.parse(checked.stdout), summary, requestId, sourceUrl: request.sourceUrl, wordcellVersion: runtime.pins.wordcell.version, ...(sourceHash ? { sourceHash } : {}) });
+        if (controller.signal.aborted)
+            return failure(requestId, quota ? 'limit-exceeded' : 'cancelled');
+        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'verified' }), { mode: 0o600 });
+        keep = true;
+        return { ok: true, capture, bundleRoot: outputDirectory, dispose: async () => { if (await settleCaptureRoot(root, requestId) === 'pending')
+                throw new CaptureCleanupError(); } };
+    }
+    catch (error) {
+        if (cleanup !== 'settled')
+            return failure(requestId, 'cleanup-required', 'cleanup');
+        const code = (error instanceof Error && ['integrity', 'limit-exceeded', 'schema-newer', 'invalid-input', 'cancelled'].includes(error.message) ? error.message : 'unclassified');
+        return failure(requestId, code, '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/pdf/errors.d.ts

@@ -0,0 +1,2 @@
+/** Wordcell's pinned PDF code field is authoritative; prose is never classified. */
+export declare function pdfFailure(value: unknown, requestId: string): import("../../contracts/index.js").ErrorEnvelope;

package/dist/src/pdf/errors.js

@@ -0,0 +1,13 @@
+import { failure, upstreamFailure } from '../acquisition/errors.js';
+/** Wordcell's pinned PDF code field is authoritative; prose is never classified. */
+export function pdfFailure(value, requestId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return failure(requestId, 'unclassified');
+    const record = value;
+    if (record.ok !== false)
+        return failure(requestId, 'unclassified');
+    if (record.captureError)
+        return upstreamFailure(value, requestId);
+    const codes = { 'invalid-input': 'invalid-input', encrypted: 'unsupported', 'limit-exceeded': 'limit-exceeded', 'tool-unavailable': 'runtime-missing', 'extraction-failed': 'unavailable', timeout: 'unavailable', cancelled: 'cancelled', integrity: 'integrity', 'unsupported-schema': 'schema-newer', unknown: 'unclassified' };
+    return failure(requestId, typeof record.code === 'string' && Object.hasOwn(codes, record.code) ? codes[record.code] : 'unclassified');
+}

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

@@ -0,0 +1,24 @@
+import type { ErrorEnvelope, JobCheckpoint } from '../../contracts/index.js';
+import { type CaptureRuntime, type CaptureConnection } from '../acquisition/index.js';
+import { type PdfCaptureRequest as CaptureRequest, type CaptureOutcome } from './capture.js';
+import type { LibraryStore, AttemptToken } from '../store/index.js';
+export interface PdfResult {
+    ok: true;
+    itemId: string;
+    revisionId: string;
+    status: 'complete' | 'partial';
+}
+export type PdfOutcome = (PdfResult | ErrorEnvelope) & {
+    cleanup: 'settled' | 'pending';
+};
+export interface PdfOptions {
+    checkpoint?: (stage: JobCheckpoint['stage']) => Promise<void>;
+    runProcess?: CaptureRequest['runProcess'];
+    runtime: CaptureRuntime;
+    connection?: CaptureConnection;
+    signal?: AbortSignal;
+    allowPrivateNetwork?: boolean;
+    capture?: (request: CaptureRequest) => Promise<CaptureOutcome>;
+}
+/** One attempt. Durable queue policy and process recovery live above this function. */
+export declare function ingestPdf(store: LibraryStore, token: AttemptToken, options: PdfOptions): Promise<PdfOutcome>;

package/dist/src/pdf/handler.js

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { validateCapture } from '../../contracts/validate.js';
+import { capturePdf } from './capture.js';
+import { failure } from '../acquisition/errors.js';
+import { bundleBytes, bundleText } from '../app/bundle-files.js';
+import { selectedMetadata } from '../metadata/article.js';
+import { localizeMarkdown } from '../app/markdown.js';
+const known = new Set(['integrity', 'limit-exceeded', 'cancelled', 'invalid-input', 'owner-busy', 'unavailable']);
+/** One attempt. Durable queue policy and process recovery live above this function. */
+export async function ingestPdf(store, token, options) {
+    let captured, committed = false;
+    let outcome = failure(token.attemptId, 'unclassified', 'storage');
+    let cleanup = 'settled';
+    try {
+        const source = store.sourceForJob(token.jobId);
+        if (!source || source.kind !== 'pdf')
+            throw Object.assign(Error('unsupported'), { code: 'invalid-input' });
+        const result = await (options.capture ?? capturePdf)({ runProcess: options.runProcess, runtime: options.runtime, stagingRoot: join(store.root, 'staging'), sourceUrl: source.locator, requestId: token.attemptId, connection: options.connection, signal: options.signal, allowPrivateNetwork: options.allowPrivateNetwork });
+        if (!result.ok) {
+            outcome = result;
+            cleanup = result.code === 'cleanup-required' ? 'pending' : 'settled';
+        }
+        else {
+            captured = result;
+            await options.checkpoint?.('extracting');
+            const capture = result.capture;
+            validateCapture(capture);
+            if (capture.kind !== 'pdf' || capture.requestId !== token.attemptId || capture.sourceUrl !== source.locator)
+                throw Object.assign(Error('integrity'), { code: 'integrity' });
+            const original = await bundleText(result.bundleRoot, capture.markdown);
+            const allAssets = [...capture.assets, capture.sourcePdf];
+            const localized = localizeMarkdown(original.replace(/^<!-- pdf-page: ([1-9][0-9]*) -->$/gm, '## Page $1'), allAssets);
+            const assets = [];
+            for (const asset of allAssets) {
+                if (options.signal?.aborted)
+                    throw Object.assign(Error('cancelled'), { code: 'cancelled' });
+                const blob = await store.putBlob(token, asset.sha256, asset.bytes, bundleBytes(result.bundleRoot, asset));
+                assets.push({ ...blob, mediaType: asset.mediaType, relationship: asset === capture.sourcePdf ? 'source-pdf' : 'image' });
+            }
+            if (options.signal?.aborted) {
+                store.requestCancellation(token.jobId);
+                throw Object.assign(Error('cancelled'), { code: 'cancelled' });
+            }
+            const selectedTitle = selectedMetadata(capture.metadata, 'title')?.value;
+            const title = typeof selectedTitle === 'string' ? selectedTitle : undefined;
+            const status = localized.missingImages ? 'partial' : capture.status;
+            // Representation algorithm participates in identity: later extraction changes cannot reuse an old payload.
+            const bundleHash = createHash('sha256').update(JSON.stringify(['pdf-local-markdown-v1', capture.manifestSha256])).digest('hex');
+            await options.checkpoint?.('promoting');
+            const revision = store.commitRevision({ ...token, itemId: source.itemId, bundleHash, markdown: localized.markdown, title, extractor: capture.extractor, status, metadata: capture.metadata, assets, warnings: [...new Set([...capture.warnings, ...(localized.missingImages ? ['partial'] : [])])] });
+            committed = true;
+            outcome = { ok: true, itemId: source.itemId, revisionId: revision.revisionId, status };
+        }
+    }
+    catch (error) {
+        const code = error?.code;
+        outcome = failure(token.attemptId, code && known.has(code) ? code : 'unclassified', 'storage');
+    }
+    if (captured)
+        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';
+        }
+    if (cleanup === 'pending')
+        return { ...failure(token.attemptId, 'cleanup-required', 'cleanup'), cleanup };
+    return { ...outcome, cleanup };
+}

package/dist/src/pdf/index.d.ts

@@ -0,0 +1,4 @@
+export { capturePdf, type PdfCaptureRequest, type CaptureOutcome } from './capture.js';
+export { ingestPdf, type PdfOptions, type PdfOutcome, type PdfResult } from './handler.js';
+export { pdfFailure } from './errors.js';
+export { pdfSource } from './source.js';

package/dist/src/pdf/index.js

@@ -0,0 +1,4 @@
+export { capturePdf } from './capture.js';
+export { ingestPdf } from './handler.js';
+export { pdfFailure } from './errors.js';
+export { pdfSource } from './source.js';

package/dist/src/pdf/input.d.ts

@@ -0,0 +1,2 @@
+/** Copy a bounded stable regular file; never pass the user's source to a converter. */
+export declare function copyPdfInput(source: string, target: string, signal?: AbortSignal): Promise<string>;

package/dist/src/pdf/input.js

@@ -0,0 +1,46 @@
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { limits } from '../../contracts/index.js';
+/** Copy a bounded stable regular file; never pass the user's source to a converter. */
+export async function copyPdfInput(source, target, signal) {
+    const input = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await input.stat();
+        if (!before.isFile())
+            throw Error('invalid-input');
+        if (before.size > limits.pdfBytes)
+            throw Error('limit-exceeded');
+        const output = await open(target, 'wx', 0o600), hash = createHash('sha256');
+        let total = 0;
+        try {
+            const buffer = Buffer.alloc(1024 ** 2);
+            for (;;) {
+                if (signal?.aborted)
+                    throw Error('cancelled');
+                const { bytesRead } = await input.read(buffer, 0, buffer.length, null);
+                if (!bytesRead)
+                    break;
+                total += bytesRead;
+                if (total > limits.pdfBytes)
+                    throw Error('limit-exceeded');
+                if (total === bytesRead && buffer.subarray(0, 5).toString() !== '%PDF-')
+                    throw Error('invalid-input');
+                const bytes = buffer.subarray(0, bytesRead);
+                hash.update(bytes);
+                await output.writeFile(bytes);
+            }
+            await output.sync();
+        }
+        finally {
+            await output.close();
+        }
+        const after = await input.stat();
+        if (total < 5 || total !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+            throw Error('integrity');
+        return hash.digest('hex');
+    }
+    finally {
+        await input.close();
+    }
+}

package/dist/src/pdf/normalize.d.ts

@@ -0,0 +1,10 @@
+import type { CaptureResult } from '../../contracts/index.js';
+export declare function normalizePdfBundle(input: {
+    bundleRoot: string;
+    inspection: unknown;
+    summary: unknown;
+    requestId: string;
+    sourceUrl: string;
+    wordcellVersion: string;
+    sourceHash?: string;
+}): Promise<CaptureResult>;

package/dist/src/pdf/normalize.js

@@ -0,0 +1,64 @@
+import { limits } from '../../contracts/index.js';
+import { validateCapture, validateAsset } from '../../contracts/validate.js';
+import { readConfined, hash } from '../acquisition/files.js';
+import { object } from '../acquisition/normalize.js';
+export async function normalizePdfBundle(input) {
+    const verified = object(input.inspection), inspection = object(verified.inspection), summary = object(input.summary);
+    if (verified.ok !== true || inspection.schemaVersion !== 1 || !Array.isArray(inspection.assets))
+        throw Error('integrity');
+    const manifestBytes = await readConfined(input.bundleRoot, 'capture.json', limits.metadataBytes), manifest = object(JSON.parse(manifestBytes.toString('utf8')));
+    if (manifest.schemaVersion !== 1 || manifest.kind !== 'pdf' || !['complete', 'partial'].includes(String(manifest.status)))
+        throw Error('integrity');
+    function asset(raw, mediaType) { const value = object(raw); const result = { relativePath: String(value.path), bytes: Number(value.bytes), sha256: String(value.sha256), mediaType }; validateAsset(result); return result; }
+    function assertVerified(value, checked) { const record = object(checked); if (record.integrity !== 'verified' || record.path !== value.relativePath || record.sha256 !== value.sha256 || record.bytes !== value.bytes)
+        throw Error('integrity'); }
+    const markdown = asset(manifest.markdown, 'text/markdown'), sourcePdf = asset(manifest.source, 'application/pdf');
+    assertVerified(markdown, inspection.markdown);
+    assertVerified(sourcePdf, inspection.source);
+    if (input.sourceHash && sourcePdf.sha256 !== input.sourceHash)
+        throw Error('integrity');
+    const source = object(manifest.source);
+    if (!input.sourceHash && (typeof verified.expectedSourceUrl !== 'string' || source.requestedUrl !== verified.expectedSourceUrl))
+        throw Error('integrity');
+    const markdownBytes = await readConfined(input.bundleRoot, markdown.relativePath, limits.markdownBytes);
+    if (hash(markdownBytes) !== markdown.sha256 || markdownBytes.length !== markdown.bytes)
+        throw Error('integrity');
+    if (!Array.isArray(manifest.images) || manifest.images.length > limits.imagesPerItem)
+        throw Error('limit-exceeded');
+    const byPath = new Map();
+    for (const raw of manifest.images) {
+        const image = object(raw), record = object(image.asset), value = asset(record, String(record.mimeType));
+        if (!value.mediaType.startsWith('image/'))
+            throw Error('integrity');
+        assertVerified(value, inspection.assets.find(raw => object(raw).path === value.relativePath));
+        const prior = byPath.get(value.relativePath);
+        if (prior && JSON.stringify(prior) !== JSON.stringify(value))
+            throw Error('integrity');
+        byPath.set(value.relativePath, value);
+    }
+    if (byPath.size !== inspection.assets.length)
+        throw Error('integrity');
+    const metadata = [], document = object(manifest.document), observedAt = String(manifest.capturedAt);
+    for (const field of ['title', 'author', 'subject', 'creator', 'producer', 'createdAt', 'modifiedAt']) {
+        const value = document[field];
+        if (typeof value === 'string' && value.length > 0 && value.length <= 16384)
+            metadata.push({ field, value, source: 'pdf', observedAt, rule: 'wordcell-pdf-v1', selected: true });
+    }
+    metadata.push({ field: 'pageCount', value: String(document.pageCount), source: 'pdf', observedAt, rule: 'wordcell-pdf-v1' });
+    if (manifest.quality) {
+        const quality = object(manifest.quality);
+        if (Array.isArray(quality.issues)) {
+            metadata.push({ field: 'pdfQualityIssueCount', value: String(quality.issues.length), source: 'pdf', observedAt, rule: 'wordcell-pdf-v1' });
+            if (quality.issues.length > 400)
+                metadata.push({ field: 'pdfQualityIssuesTruncated', value: 'true', source: 'pdf', observedAt, rule: 'wordcell-pdf-v1' });
+            for (const issue of quality.issues.slice(0, 400)) {
+                const row = object(issue);
+                metadata.push({ field: 'pdfQuality', value: JSON.stringify({ code: row.code, page: row.page }), source: 'pdf', observedAt, rule: 'wordcell-pdf-v1' });
+            }
+        }
+    }
+    const partial = manifest.status !== 'complete' || inspection.status !== 'complete' || summary.status !== 'complete';
+    const result = { schemaVersion: 1, requestId: input.requestId, kind: 'pdf', status: partial ? 'partial' : 'complete', sourceUrl: input.sourceUrl, markdown, sourcePdf, assets: [...byPath.values()], metadata, warnings: partial ? ['partial'] : [], extractor: { name: 'wordcell', version: input.wordcellVersion }, manifestSha256: hash(manifestBytes), completeness: { text: partial ? 'partial' : 'complete', images: partial ? 'partial' : 'complete' } };
+    validateCapture(result);
+    return result;
+}

package/dist/src/pdf/source-identity.d.ts

@@ -0,0 +1,4 @@
+/** Local PDFs are bound to copied bytes; only remote sources use Wordcell's URL sanitizer. */
+export declare function pdfSourceIdentity(sourceUrl: string, sanitize: (url: string) => string): {
+    expectedSourceUrl?: string;
+};

package/dist/src/pdf/source-identity.js

@@ -0,0 +1,12 @@
+/** Local PDFs are bound to copied bytes; only remote sources use Wordcell's URL sanitizer. */
+export function pdfSourceIdentity(sourceUrl, sanitize) {
+    const url = new URL(sourceUrl);
+    if (url.protocol === 'file:') {
+        if (url.host || url.username || url.password || url.search || url.hash)
+            throw Error('integrity');
+        return {};
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw Error('integrity');
+    return { expectedSourceUrl: sanitize(sourceUrl) };
+}

package/dist/src/pdf/source.d.ts

@@ -0,0 +1,6 @@
+/** PDF identity includes its kind and account realm. Local files stay separate from URLs. */
+export declare function pdfSource(input: string, realm?: string): {
+    sourceKey: string;
+    locator: string;
+    realm: string;
+};

package/dist/src/pdf/source.js

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { InputError } from '../app/source.js';
+/** PDF identity includes its kind and account realm. Local files stay separate from URLs. */
+export function pdfSource(input, realm = 'public') {
+    if (!input || Buffer.byteLength(input) > 8192 || !realm || Buffer.byteLength(realm) > 256 || /[\u0000-\u001f\u007f]/u.test(input + realm))
+        throw new InputError();
+    let url;
+    try {
+        url = /^[a-z][a-z0-9+.-]*:/i.test(input) ? new URL(input) : pathToFileURL(resolve(input));
+    }
+    catch {
+        throw new InputError();
+    }
+    if (!['file:', 'https:', 'http:'].includes(url.protocol) || url.username || url.password)
+        throw new InputError();
+    if (url.protocol === 'file:' && (url.host || url.hash || url.search || realm !== 'public'))
+        throw new InputError();
+    const locator = url.href, sourceKey = createHash('sha256').update(JSON.stringify(['pdf', realm, locator])).digest('hex');
+    return { sourceKey, locator, realm };
+}

package/dist/src/pdf/verify-helper.d.ts

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

package/dist/src/pdf/verify-helper.js

@@ -0,0 +1,17 @@
+// Public PDF verifier, executed only by the integrity-checked pinned Bun runtime.
+import { pdfSourceIdentity } from './source-identity.js';
+const runtime = process.argv[2], bundle = process.argv[3];
+try {
+    const { sanitizeArtifactUrl } = await import(import.meta.resolve('@hraness/wordcell/clip/persist', `${runtime}/package.json`));
+    const { verifyPdfCaptureBundle } = await import(import.meta.resolve('@hraness/wordcell/pdf', `${runtime}/package.json`));
+    const result = await verifyPdfCaptureBundle(bundle, { maxDocumentBytes: 16 * 1024 ** 2, maxSourceBytes: 100 * 1024 ** 2, maxVerifiedAssets: 200, maxAssetBytes: 20 * 1024 ** 2, maxTotalAssetBytes: 500 * 1024 ** 2, maxVerificationMs: 30000 });
+    const { markdown, ...document } = result.inspection.markdown;
+    const output = JSON.stringify({ ...result, ...pdfSourceIdentity(process.argv[4], sanitizeArtifactUrl), inspection: { ...result.inspection, markdown: document } });
+    if (Buffer.byteLength(output) > 65536)
+        throw Error('frame-limit');
+    process.stdout.write(output);
+}
+catch {
+    process.stdout.write(JSON.stringify({ ok: false }));
+    process.exitCode = 1;
+}

package/dist/src/portability/backup.d.ts

@@ -0,0 +1,23 @@
+import type { LibraryStore } from '../store/index.js';
+import { type FileRecord } from './files.js';
+export interface BackupManifest {
+    format: 'sponge-backup';
+    version: 1;
+    schemaVersion: number;
+    libraryId: string;
+    revisionEpoch: number;
+    files: FileRecord[];
+}
+export declare function backupLibrary(store: LibraryStore, output: string): Promise<{
+    output: string;
+    sha256: string;
+    bytes: number;
+    itemsSnapshotEpoch: number;
+}>;
+/** Versioned length-framed archive: no tar links, executable hooks or path extraction. */
+export declare function restoreLibrary(input: string, into: string): Promise<{
+    root: string;
+    libraryId: string;
+    incarnation: string;
+    heldJobs: number;
+}>;