@intactfile/engines 0.1.0

package/dist/png/repair.js

@@ -0,0 +1,335 @@
+/**
+ * PNG repair by deterministic byte surgery plus row-level salvage.
+ *
+ * The engine is pure TypeScript: pako (MIT) does the incremental inflate and
+ * fast-png (MIT) re-encodes salvaged rasters. There is no wasm in the import
+ * chain, so this can ship in the browser bundle behind the `./png` subpath.
+ *
+ * What it does, per damage class:
+ *   - signature-damage / newline-mangling → rewrite/undo, then decode normally;
+ *   - garbage-prefix → strip everything before the signature;
+ *   - crc-error → recompute the corrupt chunk CRC(s) once the data is verified;
+ *   - zeroed/corrupt IHDR dimensions → brute-force against the stored IHDR CRC,
+ *     falling back to factorizing the inflated IDAT size;
+ *   - truncated / mid-IDAT corruption → inflate what survives (pako chunked,
+ *     Z_SYNC_FLUSH), unfilter the complete scanlines and re-emit a shorter but
+ *     valid PNG.
+ *
+ * Honesty rules (docs/03 §4, docs/14): a truncated or mid-stream-corrupted file
+ * is never reported as full success — the rows below the damage are physically
+ * gone because deflate cannot resync, and the report says exactly that.
+ * Decompression bombs are refused before any large allocation.
+ */
+import { Inflate, Z_SYNC_FLUSH } from 'pako';
+import { encode as encodePng, decode as decodePng } from 'fast-png';
+import { crc32 } from '../crc32.js';
+import { diagnosePng } from './diagnose.js';
+import { DEFAULT_PNG_CAPS, PNG_SIGNATURE, channelsForColorType, hasSignatureAt, looksLikePngAt, parseIhdr, reconstructDimensions, scanlineStride, unfilterScanlines8, unmangleNewlines, walkChunksInMemory, writeU32BE, } from './format.js';
+const INFLATE_OUTPUT_CHUNK = 32 * 1024;
+/**
+ * Compressed input is pushed in small slices, each followed by Z_SYNC_FLUSH, so
+ * pako emits the output decoded so far. This is what makes mid-stream salvage
+ * work: when a later slice hits corruption, the rows decoded from earlier
+ * slices have already been captured. A larger slice would leave that prefix
+ * un-flushed inside pako and lost when the stream errors.
+ */
+const INFLATE_INPUT_SLICE = 1024;
+/**
+ * Inflate an IDAT stream defensively. Uses pako in streaming mode with
+ * Z_SYNC_FLUSH so that, when the stream is truncated or corrupt, the bytes
+ * decoded before the break are still emitted (that prefix is the salvage). The
+ * kept output is capped to guard against decompression bombs.
+ */
+function safeInflate(idat, cap) {
+    const inflator = new Inflate({ chunkSize: INFLATE_OUTPUT_CHUNK });
+    const chunks = [];
+    let total = 0;
+    let capped = false;
+    inflator.onData = (chunk) => {
+        if (capped)
+            return;
+        if (total + chunk.length > cap) {
+            const room = cap - total;
+            if (room > 0) {
+                chunks.push(chunk.subarray(0, room));
+                total += room;
+            }
+            capped = true;
+            return;
+        }
+        chunks.push(chunk);
+        total += chunk.length;
+    };
+    // A corrupt stream makes pako set `err`; it does not throw, but guard anyway.
+    try {
+        for (let i = 0; i < idat.length; i += INFLATE_INPUT_SLICE) {
+            inflator.push(idat.subarray(i, Math.min(i + INFLATE_INPUT_SLICE, idat.length)), Z_SYNC_FLUSH);
+            if (inflator.ended || inflator.err !== 0 || capped)
+                break;
+        }
+    }
+    catch {
+        /* fall through with whatever was decoded */
+    }
+    const output = concat(chunks);
+    return { output, err: inflator.err, clean: inflator.err === 0 && inflator.ended, capped };
+}
+function concat(parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.length;
+    const out = new Uint8Array(total);
+    let pos = 0;
+    for (const p of parts) {
+        out.set(p, pos);
+        pos += p.length;
+    }
+    return out;
+}
+/** Concatenate all IDAT payloads, including the available bytes of a cut chunk. */
+function assembleIdat(work, chunks) {
+    const parts = [];
+    for (const c of chunks) {
+        if (c.type !== 'IDAT')
+            continue;
+        const end = c.truncated ? c.dataOffset + c.availableData : c.crcOffset;
+        if (end > c.dataOffset)
+            parts.push(work.subarray(c.dataOffset, end));
+    }
+    return concat(parts);
+}
+/** Recompute and rewrite a chunk's CRC in place (over its current type+data). */
+function recomputeChunkCrc(work, chunk) {
+    const crc = crc32(work.subarray(chunk.offset + 4, chunk.crcOffset));
+    writeU32BE(work, chunk.crcOffset, crc);
+}
+const IEND_CHUNK = Uint8Array.of(0x00, 0x00, 0x00, 0x00, // length 0
+0x49, 0x45, 0x4e, 0x44, // "IEND"
+0xae, 0x42, 0x60, 0x82);
+/**
+ * Rebuild a canonical PNG from the complete chunks parsed out of `work`,
+ * dropping any truncated trailing chunk and trailing junk, and appending IEND
+ * when it is missing.
+ */
+function rebuildFromChunks(work, chunks) {
+    const parts = [PNG_SIGNATURE];
+    let sawIend = false;
+    for (const c of chunks) {
+        if (c.truncated)
+            continue;
+        parts.push(work.subarray(c.offset, c.crcOffset + 4));
+        if (c.type === 'IEND')
+            sawIend = true;
+    }
+    if (!sawIend)
+        parts.push(IEND_CHUNK);
+    return concat(parts);
+}
+function tryDecode(image) {
+    try {
+        decodePng(image, { checkCrc: false });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function repairPng(src, opts) {
+    const caps = opts?.caps ?? DEFAULT_PNG_CAPS;
+    const diagnosis = await diagnosePng(src, caps);
+    const original = await src.read(0, src.size);
+    const actions = [];
+    const notes = [...diagnosis.notes];
+    const build = (outcome, image, extra) => ({
+        image,
+        report: {
+            outcome,
+            damageClass: diagnosis.damageClass,
+            actions,
+            notes,
+            bytesIn: src.size,
+            bytesOut: image?.length ?? 0,
+            width: extra.width ?? null,
+            height: extra.height ?? null,
+            rowsRecovered: extra.rowsRecovered ?? null,
+            rowsExpected: extra.rowsExpected ?? null,
+            verified: extra.verified ?? false,
+        },
+    });
+    if (diagnosis.damageClass === 'not-png') {
+        notes.push('input is not recognizable as a PNG; nothing to repair');
+        return build('failed', undefined, {});
+    }
+    // --- 1. Working buffer with a valid signature at offset 0. ---
+    let work;
+    if (diagnosis.newlineMangled) {
+        work = unmangleNewlines(original);
+        actions.push('reversed FTP/ASCII newline mangling (removed the CR inserted before every LF)');
+    }
+    else if (diagnosis.signatureOffset !== null && diagnosis.signatureOffset > 0) {
+        work = original.slice(diagnosis.signatureOffset);
+        actions.push(`stripped a ${diagnosis.signatureOffset}-byte garbage prefix`);
+    }
+    else {
+        work = original.slice();
+    }
+    if (!hasSignatureAt(work, 0)) {
+        if (work.length >= 8 && (looksLikePngAt(work, 0) || diagnosis.damageClass === 'signature-damage')) {
+            work.set(PNG_SIGNATURE, 0);
+            actions.push('rewrote the 8-byte PNG signature');
+        }
+        else {
+            notes.push('could not establish a valid PNG signature at the start of the file');
+            return build('failed', undefined, {});
+        }
+    }
+    // --- 2. Locate and parse IHDR. ---
+    const walk = walkChunksInMemory(work, 8);
+    const ihdrChunk = walk.chunks.find((c) => c.type === 'IHDR' && !c.truncated);
+    if (!ihdrChunk) {
+        notes.push('IHDR chunk is missing or truncated; geometry and pixel format cannot be reconstructed reliably');
+        return build('failed', undefined, {});
+    }
+    const ihdr = parseIhdr(work.subarray(ihdrChunk.dataOffset, ihdrChunk.dataOffset + 13));
+    if (!ihdr) {
+        notes.push('IHDR data is too short to parse');
+        return build('failed', undefined, {});
+    }
+    const channels = channelsForColorType(ihdr.colorType);
+    const ihdrCrcOk = ihdrChunk.crcOk === true;
+    // --- 3. Bomb guard: refuse sane-but-oversized declared geometry up front. ---
+    if (ihdr.width > 0 &&
+        ihdr.height > 0 &&
+        (ihdr.width > caps.maxWidth || ihdr.height > caps.maxHeight || ihdr.width * ihdr.height > caps.maxPixels)) {
+        notes.push(`refusing to process ${ihdr.width}x${ihdr.height}: exceeds the safety cap (possible decompression bomb)`);
+        return build('failed', undefined, { width: ihdr.width, height: ihdr.height });
+    }
+    // --- 4. Assemble and inflate the IDAT stream (capped). ---
+    const idat = assembleIdat(work, walk.chunks);
+    if (idat.length === 0) {
+        notes.push('no IDAT image data is present; pixels cannot be reconstructed');
+        return build('failed', undefined, { width: ihdr.width || null, height: ihdr.height || null });
+    }
+    const inflated = safeInflate(idat, caps.maxInflatedBytes);
+    if (inflated.capped) {
+        notes.push('inflated output hit the safety cap; refusing (possible decompression bomb)');
+        return build('failed', undefined, {});
+    }
+    // --- 5. Resolve dimensions. ---
+    let width = ihdr.width;
+    let height = ihdr.height;
+    let dimsRecovered = false;
+    let dimsExact = true;
+    if (channels !== null) {
+        const dimsSane = width > 0 && height > 0 && width <= caps.maxWidth && height <= caps.maxHeight && width * height <= caps.maxPixels;
+        const strideNow = dimsSane ? scanlineStride(width, channels, ihdr.bitDepth) : 0;
+        const dimsMatchInflate = dimsSane && inflated.clean && inflated.output.length % strideNow === 0 && inflated.output.length / strideNow === height;
+        const dimsTrusted = (ihdrCrcOk && dimsSane) || dimsMatchInflate;
+        if (!dimsTrusted) {
+            if (inflated.clean) {
+                const rec = reconstructDimensions({
+                    tail: ihdr,
+                    inflatedSize: inflated.output.length,
+                    storedCrc: ihdrChunk.crcStored,
+                    caps,
+                });
+                if (rec) {
+                    width = rec.width;
+                    height = rec.height;
+                    dimsRecovered = true;
+                    dimsExact = rec.exact;
+                    writeU32BE(work, ihdrChunk.dataOffset, width);
+                    writeU32BE(work, ihdrChunk.dataOffset + 4, height);
+                    actions.push(rec.exact
+                        ? `reconstructed dimensions ${width}x${height} (matched the stored IHDR CRC)`
+                        : `reconstructed dimensions ${width}x${height} by factorizing the inflated size ` +
+                            `(${rec.candidates} candidate(s); the CRC could not disambiguate)`);
+                }
+                else if (!dimsSane) {
+                    notes.push('IHDR dimensions are unreadable and could not be reconstructed from the image data');
+                    return build('failed', undefined, {});
+                }
+            }
+            else if (!dimsSane) {
+                notes.push('IHDR dimensions are unreadable and the image data is too damaged to reconstruct them');
+                return build('failed', undefined, {});
+            }
+        }
+    }
+    if (width <= 0 || height <= 0 || width > caps.maxWidth || height > caps.maxHeight || width * height > caps.maxPixels) {
+        notes.push('final dimensions are out of the safe range; refusing to allocate');
+        return build('failed', undefined, { width: width || null, height: height || null });
+    }
+    // --- 6. Decide full recovery vs. row salvage. ---
+    const strideFinal = channels !== null ? scanlineStride(width, channels, ihdr.bitDepth) : 0;
+    const expected = channels !== null ? height * strideFinal : 0;
+    const fullData = channels === null ? inflated.clean : inflated.clean && inflated.output.length === expected;
+    // Fix IHDR CRC when we changed the dimensions, or when the CRC field alone
+    // was corrupt but the data has proven itself by inflating cleanly and fully.
+    if (dimsRecovered) {
+        recomputeChunkCrc(work, ihdrChunk);
+    }
+    else if (!ihdrCrcOk && fullData) {
+        recomputeChunkCrc(work, ihdrChunk);
+        actions.push('recomputed the IHDR CRC (its CRC field was corrupt; dimensions verified against the image data)');
+    }
+    if (fullData) {
+        // All image data survived: recompute any remaining bad CRCs (the data is
+        // proven intact) and re-emit a canonical file.
+        let fixed = 0;
+        for (const c of walk.chunks) {
+            if (c.truncated || c.type === 'IHDR')
+                continue;
+            if (c.crcOk === false) {
+                recomputeChunkCrc(work, c);
+                fixed += 1;
+            }
+        }
+        if (fixed > 0)
+            actions.push(`recomputed ${fixed} corrupt chunk CRC(s)`);
+        const image = rebuildFromChunks(work, walk.chunks);
+        const verified = tryDecode(image);
+        if (!verified) {
+            notes.push('re-emitted file failed to re-decode; not claiming success');
+            return build('failed', image, { width, height, rowsRecovered: height, rowsExpected: height, verified });
+        }
+        if (dimsRecovered && !dimsExact) {
+            notes.push('dimensions were reconstructed without CRC confirmation; the aspect ratio is a best guess');
+            return build('partial', image, { width, height, rowsRecovered: height, rowsExpected: height, verified });
+        }
+        return build('success', image, { width, height, rowsRecovered: height, rowsExpected: height, verified });
+    }
+    // --- 7. Salvage path: only complete 8-bit non-interlaced scanlines. ---
+    if (channels === null || ihdr.bitDepth !== 8 || ihdr.interlace !== 0 || ihdr.colorType === 3) {
+        notes.push('the surviving image data cannot be safely re-encoded: row salvage supports 8-bit, ' +
+            'non-interlaced, non-indexed images only');
+        return build('failed', undefined, { width, height, rowsExpected: height });
+    }
+    const rows = Math.floor(inflated.output.length / strideFinal);
+    if (rows <= 0) {
+        notes.push('no complete scanline survived before the damage; nothing to salvage');
+        return build('failed', undefined, { width, height, rowsRecovered: 0, rowsExpected: height });
+    }
+    const samples = unfilterScanlines8(inflated.output, rows, width, channels);
+    let image;
+    try {
+        image = encodePng({ width, height: rows, data: samples, channels, depth: 8 });
+    }
+    catch {
+        notes.push('failed to re-encode the salvaged rows');
+        return build('failed', undefined, { width, height, rowsRecovered: rows, rowsExpected: height });
+    }
+    const verified = tryDecode(image);
+    if (inflated.err !== 0 && inflated.output.length >= expected) {
+        // Structurally decoded to full size but the zlib checksum failed: pixels
+        // near the corruption may be wrong even though every row is present.
+        notes.push('the image data decoded to full size but its zlib checksum failed: pixels near the ' +
+            'corruption may be wrong. Reported as partial rather than clean.');
+    }
+    else {
+        notes.push(`${rows} of ${height} rows recovered. Rows below the damage are physically gone — ` +
+            'deflate cannot resync past a truncation or a mid-stream corruption.');
+    }
+    return build('partial', image, { width, height, rowsRecovered: rows, rowsExpected: height, verified });
+}
+//# sourceMappingURL=repair.js.map

package/dist/png/repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repair.js","sourceRoot":"","sources":["../../src/png/repair.ts"],"names":[],"mappings":"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"}

package/dist/sqlite/diagnose.d.ts

@@ -0,0 +1,31 @@
+import type { ByteSource } from '../byte-source.js';
+import type { Confidence } from '../types.js';
+import { decodePageSize, readU32 } from './format.js';
+export type SqliteDamageClass = 'none' | 'malformed' | 'header-damage' | 'truncated' | 'not-sqlite' | 'encrypted' | 'unknown';
+export interface SqliteDiagnosis {
+    damageClass: SqliteDamageClass;
+    confidence: Confidence;
+    notes: string[];
+    /** Page size in bytes, when the header is readable. */
+    pageSize: number | null;
+    /** In-header database size in pages (offset 28), when present. */
+    headerPageCount: number | null;
+    /** Page count implied by the file size (floor(size / pageSize)). */
+    filePageCount: number | null;
+    textEncoding: number | null;
+    /** True when a `-wal` sidecar was flagged in opts. */
+    walPresent: boolean;
+}
+export interface DiagnoseSqliteOptions {
+    /** Pass true when a sibling `-wal` file exists next to the database. */
+    walPresent?: boolean;
+}
+/**
+ * Structural SQLite diagnosis via own byte parsing: header magic, page size,
+ * in-header page count vs file size, freelist sanity, text encoding and a light
+ * b-tree spot-check of page 1 and the declared table roots. Never opens the
+ * database with a real engine, so it is safe on arbitrarily damaged input.
+ */
+export declare function diagnoseSqlite(src: ByteSource, opts?: DiagnoseSqliteOptions): Promise<SqliteDiagnosis>;
+export { decodePageSize, readU32 };
+//# sourceMappingURL=diagnose.d.ts.map

package/dist/sqlite/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/sqlite/diagnose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAGL,cAAc,EAMd,OAAO,EACR,MAAM,aAAa,CAAC;AAGrB,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,WAAW,GACX,eAAe,GACf,WAAW,GACX,YAAY,GACZ,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kEAAkE;IAClE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oEAAoE;IACpE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sDAAsD;IACtD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAKD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,UAAU,EACf,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,eAAe,CAAC,CA4G1B;AA6ED,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC"}

package/dist/sqlite/diagnose.js

@@ -0,0 +1,169 @@
+import { HEADER_SIZE, SQLITE_MAGIC, decodePageSize, hasMagic, isValidPageSize, parseBtreePageHeader, parseHeader, readU16, readU32, } from './format.js';
+import { PageReader, parseSchema } from './scan.js';
+/** First page read window — enough for the header and a light page-1 check. */
+const PROBE_WINDOW = 4096;
+/**
+ * Structural SQLite diagnosis via own byte parsing: header magic, page size,
+ * in-header page count vs file size, freelist sanity, text encoding and a light
+ * b-tree spot-check of page 1 and the declared table roots. Never opens the
+ * database with a real engine, so it is safe on arbitrarily damaged input.
+ */
+export async function diagnoseSqlite(src, opts = {}) {
+    const notes = [];
+    const walPresent = opts.walPresent === true;
+    const base = {
+        notes,
+        pageSize: null,
+        headerPageCount: null,
+        filePageCount: null,
+        textEncoding: null,
+        walPresent,
+    };
+    const done = (damageClass, confidence) => {
+        if (walPresent)
+            notes.push('a -wal sidecar was flagged; uncheckpointed changes may exist and will be overlaid during recovery');
+        return { damageClass, confidence, ...base };
+    };
+    if (src.size === 0) {
+        notes.push('file is empty');
+        return done('not-sqlite', 'high');
+    }
+    const probe = await src.read(0, Math.min(src.size, PROBE_WINDOW));
+    if (!hasMagic(probe)) {
+        return classifyNoMagic(probe, src.size, notes, done);
+    }
+    if (src.size < HEADER_SIZE) {
+        notes.push(`file has the SQLite magic but is only ${src.size} bytes (< 100-byte header)`);
+        return done('truncated', 'high');
+    }
+    const rawPageSize = readU16(probe, 16);
+    if (!isValidPageSize(rawPageSize)) {
+        notes.push(`header page-size field is invalid (raw value ${rawPageSize})`);
+        base.pageSize = null;
+        return done('header-damage', 'high');
+    }
+    const header = parseHeader(probe);
+    if (!header) {
+        notes.push('header magic present but the 100-byte header could not be parsed');
+        return done('header-damage', 'high');
+    }
+    base.pageSize = header.pageSize;
+    base.headerPageCount = header.pageCount;
+    base.textEncoding = header.textEncoding;
+    base.filePageCount = Math.floor(src.size / header.pageSize);
+    if (header.textEncoding < 1 || header.textEncoding > 3) {
+        notes.push(`header text-encoding field is out of range (${header.textEncoding})`);
+        return done('header-damage', 'medium');
+    }
+    // Truncation: a clean database file size is an exact multiple of the page size.
+    if (src.size % header.pageSize !== 0) {
+        notes.push(`file size (${src.size}) is not a multiple of the page size (${header.pageSize}): last page is cut`);
+        return done('truncated', 'high');
+    }
+    // In-header page count vs actual file size.
+    if (header.pageCountValid && header.pageCount !== base.filePageCount) {
+        if (header.pageCount > base.filePageCount) {
+            notes.push(`header declares ${header.pageCount} pages but the file holds ${base.filePageCount}: pages are missing (truncated)`);
+            return done('truncated', 'high');
+        }
+        notes.push(`header declares ${header.pageCount} pages but the file holds ${base.filePageCount}: header page-count is wrong`);
+        return done('header-damage', 'high');
+    }
+    // Freelist sanity.
+    const pageCount = base.filePageCount;
+    if (header.freelistTrunkPage < 0 || header.freelistTrunkPage > pageCount) {
+        notes.push(`freelist trunk page (${header.freelistTrunkPage}) is out of range`);
+        return done('header-damage', 'medium');
+    }
+    if (header.freelistPageCount > pageCount) {
+        notes.push(`freelist page count (${header.freelistPageCount}) exceeds the file's page count`);
+        return done('header-damage', 'medium');
+    }
+    // Light b-tree spot-check: page 1 must be a table b-tree, and declared table
+    // roots must point at real b-tree pages. Catches zeroed interior/root pages.
+    const structural = await checkStructure(src, header, notes);
+    if (structural === 'page1-bad') {
+        notes.push('page 1 is not a valid b-tree page (schema page damaged)');
+        return done('malformed', 'high');
+    }
+    if (structural === 'roots-bad') {
+        notes.push('one or more table root pages are damaged; some rows are only recoverable by raw scan');
+        return done('malformed', 'medium');
+    }
+    if (structural === 'schema-unreadable') {
+        notes.push('schema table could not be read; database structure is damaged');
+        return done('malformed', 'medium');
+    }
+    if (header.readVersion > 2 || header.writeVersion > 2) {
+        notes.push(`header read/write format version is newer than expected (${header.readVersion}/${header.writeVersion})`);
+        return done('unknown', 'low');
+    }
+    return done('none', 'high');
+}
+async function checkStructure(src, header, notes) {
+    if (!header)
+        return 'schema-unreadable';
+    const page1 = await src.read(0, Math.min(src.size, header.pageSize));
+    const p1hdr = parseBtreePageHeader(page1, 1);
+    if (!p1hdr)
+        return 'page1-bad';
+    // Read the whole file to spot-check table roots (databases are small here).
+    const bytes = await src.read(0, src.size);
+    const reader = new PageReader(bytes, header.pageSize, header.reservedBytes);
+    const schema = parseSchema(reader, header.textEncoding);
+    if (!schema.ok)
+        return 'schema-unreadable';
+    let rootsBad = 0;
+    let tables = 0;
+    for (const entry of schema.entries) {
+        if (entry.type !== 'table')
+            continue;
+        if (entry.name.startsWith('sqlite_'))
+            continue;
+        tables++;
+        const page = reader.page(entry.rootpage);
+        if (!page || !parseBtreePageHeader(page, entry.rootpage))
+            rootsBad++;
+    }
+    if (tables > 0 && rootsBad > 0) {
+        notes.push(`${rootsBad} of ${tables} table root page(s) are unreadable`);
+        return 'roots-bad';
+    }
+    return 'ok';
+}
+/**
+ * No magic: decide between plain "not a SQLite file" and "possibly encrypted".
+ * SQLCipher/SEE databases have no plaintext magic — their first page is
+ * ciphertext — so the best we can do is a high-entropy heuristic, reported with
+ * low confidence and an honest note.
+ */
+function classifyNoMagic(probe, size, notes, done) {
+    // How many leading magic bytes survived (partial header damage vs unrelated file).
+    let matched = 0;
+    for (let i = 0; i < SQLITE_MAGIC.length && i < probe.length; i++) {
+        if (probe[i] === SQLITE_MAGIC[i])
+            matched++;
+        else
+            break;
+    }
+    if (matched >= 8) {
+        notes.push(`header magic is partially corrupted (${matched}/16 bytes match)`);
+        return done('header-damage', 'medium');
+    }
+    const window = probe.subarray(0, Math.min(probe.length, 256));
+    const distinct = new Set(window).size;
+    let zeros = 0;
+    for (const b of window)
+        if (b === 0)
+            zeros++;
+    const looksEncrypted = size >= 512 && size % 512 === 0 && distinct > 200 && zeros <= window.length / 32;
+    if (looksEncrypted) {
+        notes.push('no SQLite magic, but the file is page-aligned with high-entropy content: it may be an encrypted (SQLCipher/SEE) database, which cannot be recovered without the key');
+        return done('encrypted', 'low');
+    }
+    notes.push('no "SQLite format 3" magic in the first bytes: not a SQLite database');
+    return done('not-sqlite', size > PROBE_WINDOW ? 'medium' : 'high');
+}
+// Re-export a couple of helpers used elsewhere so callers need only this module.
+export { decodePageSize, readU32 };
+//# sourceMappingURL=diagnose.js.map

package/dist/sqlite/diagnose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.js","sourceRoot":"","sources":["../../src/sqlite/diagnose.ts"],"names":[],"mappings":"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"}