@the_library/public 1.0.0 → 2.0.1

package/dist/enriched-index-T0sDG7JR.d.ts

@@ -0,0 +1,209 @@
+import { S as SidecarType, I as InstanceData, B as BridgeDefinition } from './orm-MJTHCG9E.js';
+
+/**
+ * Sidecar binary wire format — parser and writer (SPEC §4).
+ *
+ * Every sidecar file begins with a 10-byte header (all multi-byte integers
+ * are big-endian):
+ *
+ *   Offset  Size  Field
+ *   0       4     Magic number: 0x44504D31 ("DPM1")
+ *   4       1     Format version (currently 0x04)
+ *   5       3     recordCount (uint24, big-endian, max 16,777,215)
+ *   8       1     columnCount (uint8)
+ *   9       1     sidecarType (0x00 = Slim, 0x01 = Extended, 0x02 = Provenance)
+ *
+ * Format version history:
+ *   0x01 — uint16 recordCount + uint16 relation UIDs (max 65,535 records/UIDs)
+ *   0x02 — uint24 recordCount + uint24 relation UIDs (max 16.7M records/UIDs)
+ *           BUG: uint24 UIDs silently truncated high-bit user-created IDs (> 0xFFFFFF).
+ *   0x03 — uint24 recordCount + uint32 relation UIDs (full 32-bit UID space, no truncation).
+ *           Parsers accept 0x01/0x02/0x03; 0x02 files are treated as 0x03 on read
+ *           (best-effort — low UIDs in those files were stored correctly).
+ *   0x04 — Adds hasBridges flag to Provenance sidecars (breaking change for PROV files).
+ *           Provenance sidecars now include: [columns] [hasBridges: u8] [bridges...]
+ *           Slim/Extended sidecars unchanged. Parsers accept 0x01/0x02/0x03/0x04.
+ *           v0x03 Provenance files parsed as if hasBridges=0 (legacy, no bridges).
+ *   0x05 — Widens the top-level "ids" column and the Extended relations-tail UIDs
+ *           (authorIds/tags/books, etc.) from Uint32 to Uint64 (optmized-uid/
+ *           11-wireId-64bits-refactor.md §5) — canonical wireIds now embed a
+ *           19-bit libraryAccountId above the 44-bit counter, so they routinely
+ *           exceed 2^32. Columns are self-describing (a type byte per column),
+ *           so a v0x05 writer just declares `ColumnType.Uint64` for "ids" and any
+ *           reader handles it from that byte alone. The relations tail is NOT
+ *           self-describing per-UID-width — it's version-dispatched, same as the
+ *           v0x01/v0x02/v0x03 history below — so v0x05 files read/write relation
+ *           UIDs at u64 unconditionally. Parsers accept 0x01/0x02/0x03/0x04/0x05.
+ *           Ids/relation UIDs are `bigint` (BigUint64Array-backed) from the
+ *           reader/writer outward; JSON boundaries above this layer must use the
+ *           toJsonId/fromJsonId decimal-string convention (§3), not raw
+ *           JSON.stringify.
+ *   0x06 — Provenance bridge conversion link ids (equivalentWith/childOf/parentOf's
+ *           `id` field) switch from a fixed uint32 to a length-prefixed string
+ *           (the same `varString` already used for `original`/system names).
+ *           BUG this fixes: `BridgeLink.id` is `number | string` — a bridge
+ *           target is EITHER a real Tag wireId OR a raw external classification
+ *           notation (DDC/LCC/UDC/etc. call number — see book-manager's
+ *           NOTATION_ONLY_SYSTEMS, api/bridges.ts), and most built-in
+ *           classification systems are notation-only. `w.u32(Number(id))`
+ *           mishandled BOTH: a numeric id above 0xFFFFFFFF silently wrapped
+ *           (`>>> 0`), and a non-numeric notation (e.g. an LCC call number like
+ *           "PZ73") coerced to NaN, which `>>> 0` turns into 0 — indistinguishable
+ *           from a genuinely different bridge whose real target id is 0. A
+ *           varString has neither failure mode: it stores whatever was there
+ *           exactly. Parsers accept 0x01 through 0x06; v0x05-and-earlier
+ *           Provenance files still read bridge ids as the u32 they were
+ *           actually written as (already-corrupted values in those files are
+ *           read-only history, same policy as the v0x02 relations bug above —
+ *           this doesn't retroactively repair already-published sidecars, a
+ *           v0x06 writer just stops producing new ones). Bridge link ids
+ *           decode as `number` from legacy files, `string` from v0x06+ —
+ *           `BridgeLink.id`'s existing `number | string` type already expects
+ *           either, and every consumer already normalizes via String()/BigInt()
+ *           with a fallback (orm.ts's getBridgedRelationIdsSync).
+ *
+ * Columns follow sequentially: columnType (u8), nameLen (u8), name (UTF-8),
+ * then the column data block. Extended sidecars carry two structured tail
+ * sections after the columns: relations (self-describing) and instances.
+ * Provenance sidecars (v0x04+) carry a hasBridges flag, followed by per-record
+ * bridge definitions (if hasBridges=1).
+ */
+
+declare const SIDECAR_MAGIC = 1146113329;
+declare const SIDECAR_FORMAT_VERSION = 6;
+/** Column type codes (SPEC §4.1). */
+declare enum ColumnType {
+    Uint8 = 1,
+    Uint16 = 2,
+    NullableString = 3,
+    Relation = 4,// structured tail — flat uint32 stream
+    InstanceArray = 5,// structured tail — self-describing instance section
+    Uint32 = 6,
+    Bool = 7,// stored as u8 0/1, decoded as boolean
+    Uint64 = 8
+}
+/** Picks the narrowest column type for a prop's bit width (versions.json). */
+declare const columnTypeForBits: (bits: number) => ColumnType;
+/**
+ * One entry of the instance field descriptor embedded in Extended sidecars.
+ *
+ * The instances tail is SELF-DESCRIBING: the writer embeds
+ * `fieldCount + (typeCode, name)*` once per file, and instances are encoded
+ * in descriptor order. The parser never consults any model schema, so:
+ *   - old files keep parsing correctly after instanceFields change,
+ *   - any model with `multipleInstances: true` works with zero new code,
+ *   - files written under an older schema simply yield InstanceData objects
+ *     missing the newer fields.
+ */
+interface InstanceFieldSpec {
+    name: string;
+    type: ColumnType;
+}
+/**
+ * Derives the writer's field spec from schema instanceFields
+ * (generated-src JSON shape) plus optional per-index bit layouts from
+ * versions.json (`layout.instanceFields[objectTypeId]`).
+ * The writer appends `isDefault` automatically — do not include it here.
+ */
+declare const instanceSpecFromFields: (fields: Array<{
+    name: string;
+    type: string;
+    bits?: number;
+}>, fieldLayouts?: Record<number, {
+    bits: number;
+}>) => InstanceFieldSpec[];
+type ColumnData = Uint8Array | Uint16Array | Uint32Array | BigUint64Array | Array<string | null>;
+interface SidecarHeader {
+    formatVersion: number;
+    recordCount: number;
+    columnCount: number;
+    sidecarType: SidecarType;
+}
+interface ParsedSidecar {
+    header: SidecarHeader;
+    columns: Map<string, ColumnData>;
+    /**
+     * Per-record target-UID arrays for every `has`-direction relation, keyed by
+     * the schema relation name (Extended sidecars only). Self-describing: the
+     * writer embeds the relation names in the file, so the parser needs no
+     * schema and new relations parse with zero code change.
+     *
+     * `bigint` — relation UIDs are real wireIds (v0x05+ reads them at u64;
+     * earlier versions' narrower values are widened to bigint here too, so
+     * every caller sees one consistent type regardless of source format).
+     */
+    relations?: Map<string, bigint[][]>;
+    /** Back-compat alias for `relations.get('authors')`. */
+    authorIds?: bigint[][];
+    /** Field descriptor the instances were encoded with (Extended only). */
+    instanceFields?: InstanceFieldSpec[];
+    /** Per-record instance objects, keyed by field name (Extended only). */
+    instances?: InstanceData[][];
+    /** Per-record bridges definitions (Provenance sidecar only, if hasBridges) */
+    bridges?: (BridgeDefinition | undefined)[];
+}
+declare const parseSidecar: (buf: ArrayBuffer) => ParsedSidecar;
+/**
+ * Flattens a parsed sidecar into the generated `<Model>SlimCols` /
+ * `<Model>ExtendedCols` / `<Model>ProvCols` object shape.
+ * Provenance sidecars nest their uint8 columns under `fields`
+ * (`{ ids, fields: Record<name, Uint8Array> }`), matching `mergeProv`.
+ */
+declare const colsFromSidecar: (parsed: ParsedSidecar) => Record<string, any>;
+/**
+ * Extracts a single record as a cols object whose arrays have exactly one
+ * entry (index 0). Used by the worker's GetRecord command so the main thread
+ * can re-hydrate an evicted record with `merge*(cols, 0, lang)` without the
+ * worker knowing any model schema.
+ */
+declare const extractRecordCols: (parsed: ParsedSidecar, index: number) => Record<string, any>;
+interface SidecarColumn {
+    name: string;
+    type: ColumnType;
+    data: ColumnData;
+}
+/** One `has`-direction relation serialized into the Extended tail. */
+interface SidecarRelationInput {
+    /** Schema relation name (e.g. 'authors', 'tags', 'books'). */
+    name: string;
+    /** Per-record arrays of target UIDs — real wireIds, written at u64 (v0x05+). */
+    data: bigint[][];
+}
+interface SidecarInput {
+    sidecarType: SidecarType;
+    recordCount: number;
+    columns: SidecarColumn[];
+    /** `has`-direction relation tails (Extended only). */
+    relations?: SidecarRelationInput[];
+    /** Back-compat sugar — serialized as the `authors` relation. */
+    authorIds?: bigint[][];
+    /**
+     * Encode order + types of the instance fields, derived from the schema
+     * via `instanceSpecFromFields`. `isDefault` is appended automatically.
+     * Required when `instances` is provided.
+     */
+    instanceFields?: InstanceFieldSpec[];
+    instances?: InstanceData[][];
+    /** Per-record bridge definition (Provenance only). */
+    bridges?: (BridgeDefinition | undefined)[];
+}
+declare const writeSidecar: (input: SidecarInput) => ArrayBuffer;
+interface AiResultEntry {
+    ts: number;
+    value: any;
+    format: string;
+}
+/**
+ * AI sidecar payload — deliberately plain JSON, not the columnar binary format
+ * slim/extended/prov use. Each result's `value` is arbitrary/free-form JSON
+ * (the whole point of the format), so a fixed-width binary layout has nothing
+ * structural to encode beyond what gzip's own dictionary compression already
+ * reclaims from the repeated company/model/format strings — a custom format
+ * here would only add complexity and a second, undocumented versioning scheme
+ * alongside SIDECAR_FORMAT_VERSION/SidecarType. Gzip is applied at the file
+ * layer, the same as every other sidecar tier — not inside this function.
+ */
+declare const serializeAiSidecar: (results: Map<bigint, Map<string, Map<string, Set<AiResultEntry>>>>) => ArrayBuffer;
+declare const deserializeAiSidecar: (buf: ArrayBuffer) => Map<bigint, Map<string, Map<string, Set<AiResultEntry>>>>;
+
+export { type AiResultEntry as A, ColumnType as C, type InstanceFieldSpec as I, type ParsedSidecar as P, SIDECAR_MAGIC as S, SIDECAR_FORMAT_VERSION as a, type ColumnData as b, columnTypeForBits as c, type SidecarHeader as d, colsFromSidecar as e, extractRecordCols as f, type SidecarColumn as g, type SidecarRelationInput as h, instanceSpecFromFields as i, type SidecarInput as j, deserializeAiSidecar as k, parseSidecar as p, serializeAiSidecar as s, writeSidecar as w };