yom-format 0.1.0

package/dist/yom/byteSource.d.ts

@@ -0,0 +1,56 @@
+import { YOMError } from "./errors.js";
+/**
+ * Gap 1: the byte-source abstraction every reader read goes through, so the
+ * same `YOMPackfileReader` can serve a fully in-memory `.yom` or one streamed
+ * over HTTP `Range` requests without ever loading the whole file.
+ */
+export interface ByteSource {
+    /** Total file length in bytes. */
+    readonly size: number;
+    /** Reads exactly `[offset, offset+length)`; rejects if it can't. */
+    read(offset: number, length: number): Promise<Uint8Array>;
+}
+/** Raised when a `ByteSource.read` cannot return the requested extent. */
+export declare class ByteSourceError extends YOMError {
+}
+/** A `ByteSource` over an already-resident `Uint8Array` (zero-copy slices). */
+export declare class MemoryByteSource implements ByteSource {
+    readonly size: number;
+    private readonly bytes;
+    constructor(bytes: Uint8Array);
+    read(offset: number, length: number): Promise<Uint8Array>;
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface HttpRangeOptions {
+    /** Override the global `fetch` (for tests / custom transports). */
+    fetch?: FetchLike;
+    /** Extra request headers (auth, etc.). */
+    headers?: Record<string, string>;
+    /** Skip the size probe if the caller already knows `Content-Length`. */
+    size?: number;
+    /** Abort in-flight requests. */
+    signal?: AbortSignal;
+}
+/**
+ * A `ByteSource` backed by HTTP `Range` requests. `create()` learns the total
+ * size and confirms range support up front (one `Range: bytes=0-` probe, or a
+ * caller-supplied `size`); each `read()` issues `GET Range: bytes=a-b`,
+ * validates the `206` + `Content-Range`/length, and returns the slice.
+ *
+ * The server must answer `206 Partial Content` to ranged requests; a plain
+ * `200 OK` means ranges are unsupported and `create()` throws
+ * `RangeNotSupportedError`. For cross-origin use the server must expose
+ * `Content-Range`, `Accept-Ranges`, and `Content-Length` via CORS.
+ */
+export declare class HttpRangeByteSource implements ByteSource {
+    readonly size: number;
+    private readonly url;
+    private readonly fetchFn;
+    private readonly headers;
+    private readonly signal?;
+    private constructor();
+    static create(url: string, opts?: HttpRangeOptions): Promise<HttpRangeByteSource>;
+    read(offset: number, length: number): Promise<Uint8Array>;
+}
+export {};
+//# sourceMappingURL=byteSource.d.ts.map

package/dist/yom/byteSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byteSource.d.ts","sourceRoot":"","sources":["../../src/yom/byteSource.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3D;AAED,0EAA0E;AAC1E,qBAAa,eAAgB,SAAQ,QAAQ;CAAG;AAEhD,+EAA+E;AAC/E,qBAAa,gBAAiB,YAAW,UAAU;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;gBAEvB,KAAK,EAAE,UAAU;IAK7B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAM1D;AAED,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAc;IAEtC,OAAO;WAQM,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAkCrF,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAwBhE"}

package/dist/yom/byteSource.js

@@ -0,0 +1,111 @@
+import { RangeNotSupportedError, YOMError } from "./errors.js";
+/** Raised when a `ByteSource.read` cannot return the requested extent. */
+export class ByteSourceError extends YOMError {
+}
+/** A `ByteSource` over an already-resident `Uint8Array` (zero-copy slices). */
+export class MemoryByteSource {
+    size;
+    bytes;
+    constructor(bytes) {
+        this.bytes = bytes;
+        this.size = bytes.length;
+    }
+    read(offset, length) {
+        if (offset < 0 || length < 0 || offset + length > this.bytes.length) {
+            return Promise.reject(new ByteSourceError(`read [${offset}, ${offset + length}) out of bounds (size ${this.size})`));
+        }
+        return Promise.resolve(this.bytes.subarray(offset, offset + length));
+    }
+}
+/**
+ * A `ByteSource` backed by HTTP `Range` requests. `create()` learns the total
+ * size and confirms range support up front (one `Range: bytes=0-` probe, or a
+ * caller-supplied `size`); each `read()` issues `GET Range: bytes=a-b`,
+ * validates the `206` + `Content-Range`/length, and returns the slice.
+ *
+ * The server must answer `206 Partial Content` to ranged requests; a plain
+ * `200 OK` means ranges are unsupported and `create()` throws
+ * `RangeNotSupportedError`. For cross-origin use the server must expose
+ * `Content-Range`, `Accept-Ranges`, and `Content-Length` via CORS.
+ */
+export class HttpRangeByteSource {
+    size;
+    url;
+    fetchFn;
+    headers;
+    signal;
+    constructor(url, size, opts) {
+        this.url = url;
+        this.size = size;
+        this.fetchFn = opts.fetch ?? ((input, init) => fetch(input, init));
+        this.headers = opts.headers ?? {};
+        this.signal = opts.signal;
+    }
+    static async create(url, opts = {}) {
+        const fetchFn = opts.fetch ?? ((input, init) => fetch(input, init));
+        const headers = opts.headers ?? {};
+        if (typeof opts.size === "number") {
+            return new HttpRangeByteSource(url, opts.size, opts);
+        }
+        // Probe with an open-ended range: a range-capable server answers 206 with
+        // a `Content-Range: bytes 0-.../TOTAL` from which we learn the size.
+        const res = await fetchFn(url, {
+            method: "GET",
+            headers: { ...headers, Range: "bytes=0-0" },
+            signal: opts.signal,
+        });
+        if (res.status === 200) {
+            // Server ignored the range and sent the whole body.
+            throw new RangeNotSupportedError(`server does not support range requests (status 200) for ${url}`);
+        }
+        if (res.status !== 206) {
+            throw new ByteSourceError(`unexpected status ${res.status} probing ${url}`);
+        }
+        const total = parseContentRangeTotal(res.headers.get("Content-Range"));
+        if (total === null) {
+            const len = res.headers.get("Content-Length");
+            throw new ByteSourceError(`range probe missing Content-Range total for ${url} (Content-Length ${len ?? "?"})`);
+        }
+        // Drain the tiny probe body to release the connection.
+        await res.arrayBuffer().catch(() => undefined);
+        return new HttpRangeByteSource(url, total, opts);
+    }
+    async read(offset, length) {
+        if (offset < 0 || length < 0 || offset + length > this.size) {
+            throw new ByteSourceError(`read [${offset}, ${offset + length}) out of bounds (size ${this.size})`);
+        }
+        if (length === 0)
+            return new Uint8Array(0);
+        const end = offset + length - 1; // HTTP ranges are inclusive
+        const res = await this.fetchFn(this.url, {
+            method: "GET",
+            headers: { ...this.headers, Range: `bytes=${offset}-${end}` },
+            signal: this.signal,
+        });
+        if (res.status === 200) {
+            throw new RangeNotSupportedError(`server ignored range request (status 200) for ${this.url}`);
+        }
+        if (res.status !== 206) {
+            throw new ByteSourceError(`unexpected status ${res.status} reading ${this.url}`);
+        }
+        const body = new Uint8Array(await res.arrayBuffer());
+        if (body.length !== length) {
+            throw new ByteSourceError(`range read returned ${body.length} bytes, expected ${length}`);
+        }
+        return body;
+    }
+}
+/** Parses the `TOTAL` out of a `Content-Range: bytes A-B/TOTAL` header. */
+function parseContentRangeTotal(header) {
+    if (!header)
+        return null;
+    const slash = header.lastIndexOf("/");
+    if (slash < 0)
+        return null;
+    const total = header.slice(slash + 1).trim();
+    if (total === "" || total === "*")
+        return null;
+    const parsed = Number(total);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+//# sourceMappingURL=byteSource.js.map

package/dist/yom/byteSource.js.map

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

package/dist/yom/bytes.d.ts

@@ -0,0 +1,2 @@
+export declare function concatBytes(chunks: Uint8Array[]): Uint8Array;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/yom/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/yom/bytes.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAU5D"}

package/dist/yom/bytes.js

@@ -0,0 +1,13 @@
+export function concatBytes(chunks) {
+    let total = 0;
+    for (const chunk of chunks)
+        total += chunk.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+//# sourceMappingURL=bytes.js.map

package/dist/yom/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../src/yom/bytes.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAAC,MAAoB;IAC9C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/yom/constants.d.ts

@@ -0,0 +1,34 @@
+import { BlobKind } from "./generated/yomu/yom/blob-kind.js";
+import { Compression } from "./generated/yomu/yom/compression.js";
+/**
+ * YOM v1 format constants shared by the writer, reader, and validator.
+ * Mirrors the Swift implementation in `swift/Sources/YOMFormat/YOMConstants.swift`
+ * field-for-field so Web- and native-generated `.yom` packages agree on
+ * layout. See docs/format-spec.md for rationale.
+ */
+export declare const YOM_FILE_EXTENSION = "yom";
+export declare const YOM_MIME_TYPE = "application/vnd.yomu.yom";
+export declare const YOM_MAGIC: Uint8Array<ArrayBuffer>;
+export declare const YOM_HEADER_SIZE = 4096;
+export declare const YOM_FORMAT_VERSION = 1;
+export declare const YOM_HASH_LENGTH = 32;
+export declare const YOM_IMAGE_BLOB_ALIGNMENT = 16;
+export declare const YOM_DEFAULT_BLOB_ALIGNMENT = 1;
+export declare function requiredCompression(kind: BlobKind): Compression;
+export declare function requiredAlignment(kind: BlobKind): number;
+/** Per-kind cap on a blob's declared `uncompressed_length`, in bytes. */
+export declare const MAX_BLOB_UNCOMPRESSED_IMAGE: number;
+export declare const MAX_BLOB_UNCOMPRESSED_TEXT: number;
+export declare const MAX_BLOB_UNCOMPRESSED_POSTINGS: number;
+/** Cap on the sum of every blob's declared `uncompressed_length` (whole-file validation). */
+export declare const MAX_TOTAL_UNCOMPRESSED: number;
+/**
+ * Reject a blob whose declared inflation ratio
+ * (`uncompressed_length / max(compressed_length, 1)`) exceeds this -- the
+ * classic zip/zstd-bomb signature. zstd rarely exceeds ~3-5x on scanned-book
+ * text/OCR, so 1000x is a generous safety margin.
+ */
+export declare const MAX_INFLATION_RATIO = 1000;
+/** The `uncompressed_length` cap that applies to a blob of the given kind. */
+export declare function maxBlobUncompressed(kind: BlobKind): number;
+//# sourceMappingURL=constants.d.ts.map

package/dist/yom/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/yom/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,aAAa,6BAA6B,CAAC;AACxD,eAAO,MAAM,SAAS,yBAA2C,CAAC;AAClE,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,CAa/D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAQxD;AAgBD,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,QAAmB,CAAC;AAC5D,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAC3D,eAAO,MAAM,8BAA8B,QAAmB,CAAC;AAE/D,6FAA6F;AAC7F,eAAO,MAAM,sBAAsB,QAAyB,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAc1D"}

package/dist/yom/constants.js

@@ -0,0 +1,82 @@
+import { BlobKind } from "./generated/yomu/yom/blob-kind.js";
+import { Compression } from "./generated/yomu/yom/compression.js";
+/**
+ * YOM v1 format constants shared by the writer, reader, and validator.
+ * Mirrors the Swift implementation in `swift/Sources/YOMFormat/YOMConstants.swift`
+ * field-for-field so Web- and native-generated `.yom` packages agree on
+ * layout. See docs/format-spec.md for rationale.
+ */
+export const YOM_FILE_EXTENSION = "yom";
+export const YOM_MIME_TYPE = "application/vnd.yomu.yom";
+export const YOM_MAGIC = new Uint8Array([0x59, 0x4f, 0x4d, 0x31]); // "YOM1"
+export const YOM_HEADER_SIZE = 4096;
+export const YOM_FORMAT_VERSION = 1;
+export const YOM_HASH_LENGTH = 32;
+export const YOM_IMAGE_BLOB_ALIGNMENT = 16;
+export const YOM_DEFAULT_BLOB_ALIGNMENT = 1;
+export function requiredCompression(kind) {
+    switch (kind) {
+        case BlobKind.PageImage:
+        case BlobKind.ThumbnailImage:
+        case BlobKind.SearchPostings:
+            return Compression.None;
+        case BlobKind.OCRLayout:
+        case BlobKind.NormalizedText:
+        case BlobKind.SearchDictionary:
+            return Compression.Zstd;
+        default:
+            throw new Error(`unknown blob kind: ${kind}`);
+    }
+}
+export function requiredAlignment(kind) {
+    switch (kind) {
+        case BlobKind.PageImage:
+        case BlobKind.ThumbnailImage:
+            return YOM_IMAGE_BLOB_ALIGNMENT;
+        default:
+            return YOM_DEFAULT_BLOB_ALIGNMENT;
+    }
+}
+/*
+ * -------------------------------------------------------------------------
+ * Reader-side safety limits (Gap 2 hardening).
+ *
+ * IMPORTANT: these are **reader policy, NOT format requirements**. The writer
+ * MUST NOT enforce them and the on-disk format places no upper bound on blob
+ * sizes -- a conforming `.yom` may legally exceed any of these. They exist
+ * only so a *reader* can refuse to allocate unbounded memory for a malformed
+ * or hostile file (decompression bombs, forged declared sizes) before it
+ * touches the data. Values are chosen comfortably above every real-world and
+ * fixture blob size; raise them if a legitimate corpus needs more.
+ * -------------------------------------------------------------------------
+ */
+/** Per-kind cap on a blob's declared `uncompressed_length`, in bytes. */
+export const MAX_BLOB_UNCOMPRESSED_IMAGE = 64 * 1024 * 1024; // page/thumbnail AVIF
+export const MAX_BLOB_UNCOMPRESSED_TEXT = 16 * 1024 * 1024; // OCR / normalized text / dictionary
+export const MAX_BLOB_UNCOMPRESSED_POSTINGS = 64 * 1024 * 1024; // search postings scale with book size
+/** Cap on the sum of every blob's declared `uncompressed_length` (whole-file validation). */
+export const MAX_TOTAL_UNCOMPRESSED = 4 * 1024 * 1024 * 1024;
+/**
+ * Reject a blob whose declared inflation ratio
+ * (`uncompressed_length / max(compressed_length, 1)`) exceeds this -- the
+ * classic zip/zstd-bomb signature. zstd rarely exceeds ~3-5x on scanned-book
+ * text/OCR, so 1000x is a generous safety margin.
+ */
+export const MAX_INFLATION_RATIO = 1000;
+/** The `uncompressed_length` cap that applies to a blob of the given kind. */
+export function maxBlobUncompressed(kind) {
+    switch (kind) {
+        case BlobKind.PageImage:
+        case BlobKind.ThumbnailImage:
+            return MAX_BLOB_UNCOMPRESSED_IMAGE;
+        case BlobKind.SearchPostings:
+            return MAX_BLOB_UNCOMPRESSED_POSTINGS;
+        case BlobKind.OCRLayout:
+        case BlobKind.NormalizedText:
+        case BlobKind.SearchDictionary:
+            return MAX_BLOB_UNCOMPRESSED_TEXT;
+        default:
+            return MAX_BLOB_UNCOMPRESSED_TEXT;
+    }
+}
+//# sourceMappingURL=constants.js.map

package/dist/yom/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/yom/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AACxC,MAAM,CAAC,MAAM,aAAa,GAAG,0BAA0B,CAAC;AACxD,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AACpC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AACpC,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAClC,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAC3C,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAE5C,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAChD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC,SAAS,CAAC;QACxB,KAAK,QAAQ,CAAC,cAAc,CAAC;QAC7B,KAAK,QAAQ,CAAC,cAAc;YAC1B,OAAO,WAAW,CAAC,IAAI,CAAC;QAC1B,KAAK,QAAQ,CAAC,SAAS,CAAC;QACxB,KAAK,QAAQ,CAAC,cAAc,CAAC;QAC7B,KAAK,QAAQ,CAAC,gBAAgB;YAC5B,OAAO,WAAW,CAAC,IAAI,CAAC;QAC1B;YACE,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC,SAAS,CAAC;QACxB,KAAK,QAAQ,CAAC,cAAc;YAC1B,OAAO,wBAAwB,CAAC;QAClC;YACE,OAAO,0BAA0B,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,sBAAsB;AACnF,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,qCAAqC;AACjG,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,uCAAuC;AAEvG,6FAA6F;AAC7F,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAExC,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAChD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC,SAAS,CAAC;QACxB,KAAK,QAAQ,CAAC,cAAc;YAC1B,OAAO,2BAA2B,CAAC;QACrC,KAAK,QAAQ,CAAC,cAAc;YAC1B,OAAO,8BAA8B,CAAC;QACxC,KAAK,QAAQ,CAAC,SAAS,CAAC;QACxB,KAAK,QAAQ,CAAC,cAAc,CAAC;QAC7B,KAAK,QAAQ,CAAC,gBAAgB;YAC5B,OAAO,0BAA0B,CAAC;QACpC;YACE,OAAO,0BAA0B,CAAC;IACtC,CAAC;AACH,CAAC"}

package/dist/yom/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Typed error hierarchy for the YOM reader/validator hardening layers.
+ *
+ * These are all *reader-side* failures raised while opening or reading a
+ * possibly-hostile `.yom`. They exist so callers can distinguish "the input
+ * is malformed/oversized/corrupt" from ordinary programming errors, and so
+ * the size-cap / FlatBuffers-verify / HTTP-Range layers throw a stable,
+ * catchable type instead of a bare `Error`.
+ */
+/** Base class for every typed reader error added by the hardening layers. */
+export declare class YOMError extends Error {
+}
+/**
+ * A blob's declared `uncompressed_length` exceeds the reader's per-kind size
+ * cap, or its declared inflation ratio (`uncompressed / compressed`) exceeds
+ * `MAX_INFLATION_RATIO`. Raised *before* any decompression happens, so a
+ * decompression-bomb never gets to allocate memory.
+ */
+export declare class BlobTooLargeError extends YOMError {
+}
+/**
+ * A blob decompressed to a different byte length than its declared
+ * `uncompressed_length` (or decompression otherwise failed). Raised before
+ * the decompressed bytes are used, ahead of the final SHA-256 gate.
+ */
+export declare class CorruptBlobError extends YOMError {
+}
+/**
+ * The main FlatBuffers index (or an OCR layout blob) failed bounded
+ * structural verification: an offset, vtable, table, string, or vector would
+ * dereference outside the known index byte range, or a vector length is
+ * absurdly large. Raised instead of returning a booby-trapped `getRootAs*`
+ * root that could later read out of bounds.
+ */
+export declare class MalformedIndexError extends YOMError {
+}
+/**
+ * An HTTP source does not support range requests (it answered a ranged `GET`
+ * with `200 OK` / no `Accept-Ranges` instead of `206 Partial Content`).
+ * Callers may retry with `openURL(url, { fallbackToFullFetch: true })`.
+ */
+export declare class RangeNotSupportedError extends YOMError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/yom/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/yom/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,6EAA6E;AAC7E,qBAAa,QAAS,SAAQ,KAAK;CAAG;AAEtC;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;CAAG;AAElD;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;CAAG;AAEjD;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;CAAG;AAEpD;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,QAAQ;CAAG"}

package/dist/yom/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Typed error hierarchy for the YOM reader/validator hardening layers.
+ *
+ * These are all *reader-side* failures raised while opening or reading a
+ * possibly-hostile `.yom`. They exist so callers can distinguish "the input
+ * is malformed/oversized/corrupt" from ordinary programming errors, and so
+ * the size-cap / FlatBuffers-verify / HTTP-Range layers throw a stable,
+ * catchable type instead of a bare `Error`.
+ */
+/** Base class for every typed reader error added by the hardening layers. */
+export class YOMError extends Error {
+}
+/**
+ * A blob's declared `uncompressed_length` exceeds the reader's per-kind size
+ * cap, or its declared inflation ratio (`uncompressed / compressed`) exceeds
+ * `MAX_INFLATION_RATIO`. Raised *before* any decompression happens, so a
+ * decompression-bomb never gets to allocate memory.
+ */
+export class BlobTooLargeError extends YOMError {
+}
+/**
+ * A blob decompressed to a different byte length than its declared
+ * `uncompressed_length` (or decompression otherwise failed). Raised before
+ * the decompressed bytes are used, ahead of the final SHA-256 gate.
+ */
+export class CorruptBlobError extends YOMError {
+}
+/**
+ * The main FlatBuffers index (or an OCR layout blob) failed bounded
+ * structural verification: an offset, vtable, table, string, or vector would
+ * dereference outside the known index byte range, or a vector length is
+ * absurdly large. Raised instead of returning a booby-trapped `getRootAs*`
+ * root that could later read out of bounds.
+ */
+export class MalformedIndexError extends YOMError {
+}
+/**
+ * An HTTP source does not support range requests (it answered a ranged `GET`
+ * with `200 OK` / no `Accept-Ranges` instead of `206 Partial Content`).
+ * Callers may retry with `openURL(url, { fallbackToFullFetch: true })`.
+ */
+export class RangeNotSupportedError extends YOMError {
+}
+//# sourceMappingURL=errors.js.map

package/dist/yom/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/yom/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,6EAA6E;AAC7E,MAAM,OAAO,QAAS,SAAQ,KAAK;CAAG;AAEtC;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,QAAQ;CAAG;AAElD;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;CAAG;AAEjD;;;;;;GAMG;AACH,MAAM,OAAO,mBAAoB,SAAQ,QAAQ;CAAG;AAEpD;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,QAAQ;CAAG"}

package/dist/yom/flatbufferVerify.d.ts

@@ -0,0 +1,21 @@
+import { MainIndex } from "./generated/yomu/yom/main-index.js";
+/**
+ * Bounded structural verification of a raw (uncompressed) main-index byte
+ * range. `deep` controls whether sub-tables/vectors are recursed into
+ * (validator) or only their offsets/lengths bounds-checked (reader open).
+ * Throws `MalformedIndexError` on any violation.
+ */
+export declare function verifyMainIndex(indexBytes: Uint8Array, deep: boolean): void;
+/**
+ * Verify then construct the `MainIndex` root, so a malformed buffer throws
+ * `MalformedIndexError` instead of yielding a booby-trapped lazy root.
+ */
+export declare function getVerifiedRootAsMainIndex(indexBytes: Uint8Array, deep: boolean): MainIndex;
+/**
+ * True only when the index's optional `pdfExport` metadata is genuinely
+ * present and safely traversable. Because the writer emits an absent
+ * `pdfExport` via `forceDefaults(true)` (a sentinel pointing out of bounds),
+ * callers must gate any `pdfExport()`/outline read on this check.
+ */
+export declare function pdfExportPresent(indexBytes: Uint8Array): boolean;
+//# sourceMappingURL=flatbufferVerify.d.ts.map

package/dist/yom/flatbufferVerify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatbufferVerify.d.ts","sourceRoot":"","sources":["../../src/yom/flatbufferVerify.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAqQ/D;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAE3E;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,CAG3F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAUhE"}