@the_library/public 1.0.0 → 2.0.0

package/dist/orm-MJTHCG9E.d.ts

@@ -0,0 +1,1003 @@
+/**
+ * Local-only, non-EVM operations (analytics, local state).
+ * EVM-bound mutations use `PatchOperation` from `@the_library/db_schemas`
+ * (re-exported in `binary.ts`) — do not add EVM operation variants here.
+ */
+declare enum ActionTypes {
+    Visit = 0,
+    VisitPart = 1,
+    Download = 2,
+    Rate = 3,
+    RatePart = 4,
+    Share = 5,
+    SharePart = 6
+}
+declare enum WorkerCommands {
+    Init = "init",// Initial load: fetch sidecars + local patches
+    SavePatches = "savePatches",
+    GetRecord = "getRecord",// LRU on-demand re-hydration (SPEC §2.5)
+    LoadLanguage = "loadLanguage"
+}
+declare enum Rating {
+    None = 0,
+    New = 1,
+    Keep = 2,
+    Trash = 3,
+    Shared = 4
+}
+declare enum WorkerEvent {
+    WorkerReady = "workerready",
+    WorkerLoadingError = "workerLoadingError",
+    DownloadStarted = "downloadStarted",
+    DownloadFinished = "downloadFinished",
+    DownloadError = "downloadError",
+    LevelUpdated = "levelUpdated"
+}
+declare enum DownloadState {
+    Unknown = 0,
+    Pending = 1,
+    InProgress = 2,
+    Done = 3,
+    Error = 4
+}
+/** Sidecar type byte in the DPM1 wire header (SPEC §4.1). */
+declare enum SidecarType {
+    Slim = 0,
+    Extended = 1,
+    Provenance = 2
+}
+
+declare enum PatchOperation {
+    EditPropertyString = 1,
+    EditPropertyNumber = 2,
+    EditInstanceFieldString = 3,
+    EditInstanceFieldNumber = 4,
+    EditRelation = 5,
+    CreateRecord = 7,
+    AddInstance = 8,
+    MergeProposal = 9,
+    DeleteBridge = 10
+}
+declare enum PatchAction {
+    Remove = 0,
+    Add = 1
+}
+interface BasePatch {
+    operation: PatchOperation;
+    objectType: number;
+    objectId: bigint;
+    langId: number;
+}
+interface EditPropertyNumberObj extends BasePatch {
+    operation: PatchOperation.EditPropertyNumber;
+    propertyId: number;
+    value: number;
+    /**
+     * 2-bit origin code: 0=unset, 1=AI, 2=human, 3=consensus (see orm.ts's
+     * Config.defaultProvenance). Optional because a patch decoded from a
+     * pre-provenance on-chain word (WIRE_FORMAT_LEGACY, or any WIDE-format word
+     * written before this field existed) has no genuine value to report —
+     * those decode with `provenance` absent, not fabricated as 0. A WIDE-format
+     * word encoded by the current packPatch always carries an explicit value
+     * (0 if the author didn't set one).
+     */
+    provenance?: number;
+}
+interface EditPropertyStringObj extends BasePatch {
+    operation: PatchOperation.EditPropertyString;
+    propertyId: number;
+    value: string;
+    /** See EditPropertyNumberObj.provenance. */
+    provenance?: number;
+}
+interface EditInstanceFieldNumberObj extends BasePatch {
+    operation: PatchOperation.EditInstanceFieldNumber;
+    instanceIndex: number;
+    propertyId: number;
+    value: number;
+}
+interface EditInstanceFieldStringObj extends BasePatch {
+    operation: PatchOperation.EditInstanceFieldString;
+    instanceIndex: number;
+    propertyId: number;
+    value: string;
+}
+interface EditRelationObj extends BasePatch {
+    operation: PatchOperation.EditRelation;
+    relationId: number;
+    action: PatchAction;
+    targetId: bigint;
+}
+interface CreateRecordObj extends BasePatch {
+    operation: PatchOperation.CreateRecord;
+    objectType: number;
+    objectId: bigint;
+    langId: number;
+}
+interface AddInstanceObj extends BasePatch {
+    operation: PatchOperation.AddInstance;
+    objectType: number;
+    objectId: bigint;
+    langId: number;
+    instanceIndex: number;
+}
+interface MergeProposalObj extends BasePatch {
+    operation: PatchOperation.MergeProposal;
+    original: string;
+    destSystem: string;
+    relationType: 'equivalentWith' | 'childOf' | 'parentOf';
+    targetId: number | string;
+    confidence: number;
+}
+interface DeleteBridgeObj extends BasePatch {
+    operation: PatchOperation.DeleteBridge;
+    original: string;
+    destinationSystem: string;
+    bridgeTypeToDelete: 'equivalentWith' | 'childOf' | 'parentOf';
+    targetTagId: number | bigint | string;
+}
+type AnyPatch = EditPropertyNumberObj | EditPropertyStringObj | EditInstanceFieldNumberObj | EditInstanceFieldStringObj | EditRelationObj | CreateRecordObj | AddInstanceObj | MergeProposalObj | DeleteBridgeObj;
+declare enum ActionOperation {
+    Download = 6,
+    Visit = 11,
+    Rate = 12,
+    RatePart = 13,
+    Share = 14,
+    SharePart = 15
+}
+declare const isActionOperation: (op: number) => op is ActionOperation;
+interface BaseActionPatch {
+    operation: ActionOperation;
+    objectType: number;
+    objectId: bigint;
+    ts: number;
+}
+interface VisitActionObj extends BaseActionPatch {
+    operation: ActionOperation.Visit;
+}
+interface DownloadActionObj extends BaseActionPatch {
+    operation: ActionOperation.Download;
+}
+interface RateActionObj extends BaseActionPatch {
+    operation: ActionOperation.Rate;
+    rate: number;
+}
+interface RatePartActionObj extends BaseActionPatch {
+    operation: ActionOperation.RatePart;
+    part: number;
+    rate: number;
+}
+interface ShareActionObj extends BaseActionPatch {
+    operation: ActionOperation.Share;
+    socialMediaId: number;
+}
+interface SharePartActionObj extends BaseActionPatch {
+    operation: ActionOperation.SharePart;
+    part: number;
+    socialMediaId: number;
+}
+type AnyActionPatch = VisitActionObj | DownloadActionObj | RateActionObj | RatePartActionObj | ShareActionObj | SharePartActionObj;
+interface EnumLayout {
+    bits: number;
+    values: string[];
+}
+interface PropLayout {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'enum';
+    bits: number;
+    enum?: string;
+}
+interface VersionEntry {
+    hash: string;
+    enums: Record<string, EnumLayout>;
+    props: Record<number, PropLayout>;
+    instanceFields: Record<number, number[]>;
+}
+interface VersionsFile {
+    current: number;
+    versions: Record<number, VersionEntry>;
+}
+interface VersionLayout {
+    hash: string;
+    enums: Record<string, EnumLayout>;
+    props: Record<number, PropLayout>;
+    instanceFields: Record<number, number[]>;
+}
+interface EvmPayload {
+    version: number;
+    patches: bigint[];
+    textIndex: number[];
+    textData: string[];
+}
+declare const LANG_ID_ENCODE: Record<string, number>;
+declare const LANG_ID_DECODE: Record<number, string>;
+
+/**
+ * Merges all version delta entries up to and including `version`.
+ *
+ * WARNING: COUPLING CONTRACT
+ * \`resolveLayout\` relies on \`computeVersionDelta\` emitting the FULL \`instanceFields\`
+ * array for any model that changed. It blindly overwrites the merged layout with the
+ * delta entry's array (\`merged.instanceFields[ot] = [...fields]\`). If future
+ * optimizations shrink \`versions.json\` by emitting only newly added fields, this
+ * function will silently corrupt the field layout by deleting historical fields.
+ */
+declare function resolveLayout(version: number, versionsFile: VersionsFile): VersionLayout;
+declare function packPatch(patch: AnyPatch, layout: VersionLayout): bigint;
+declare function unpackPatch(packed: bigint, layout: VersionLayout): AnyPatch;
+declare function packActionPatch(patch: AnyActionPatch): bigint;
+declare function unpackActionPatch(packed: bigint): AnyActionPatch;
+declare function patchToEvm(patches: (AnyPatch | AnyActionPatch)[], layout: VersionLayout, version: number): EvmPayload;
+declare function evmToPatch(payload: EvmPayload, versionsFile: VersionsFile): (AnyPatch | AnyActionPatch)[];
+
+type Lang = string;
+type uid = bigint;
+/**
+ * Canonical bigint<->string boundary for wireIds crossing a surface that
+ * can't carry bigint natively — JSON (`JSON.stringify` throws on bigint) and
+ * IndexedDB keys (bigint isn't a valid IDB key type). Every such boundary
+ * should use these two primitives via its own explicit typed transform
+ * function, not a generic JSON reviver/replacer or an inline `.toString()` —
+ * see optmized-uid/11-wireId-64bits-refactor.md §3 for why a generic reviver
+ * breaks on arrays like `authorIds` (a reviver sees the array index as the
+ * key, never the field name).
+ */
+declare const toJsonId: (id: uid) => string;
+declare const fromJsonId: (s: string) => uid;
+interface RecordIdentityCluster {
+    sfcuid: string;
+    native: string;
+    aliases: string[];
+    wireId: uid;
+}
+/**
+ * Key used in per-language value maps when a value is language-agnostic
+ * (patches with langId 0).
+ */
+declare const LANG_AGNOSTIC: Lang;
+/**
+ * One embedded instance (e.g. a PDF variant of a Book). Keys are the
+ * instanceField names from the schema; `isDefault` is appended by the
+ * sidecar writer and is not an instanceField.
+ */
+type InstanceData = Record<string, string | number | boolean | null>;
+/**
+ * V2 in-memory ORM tuple. All value maps are per-language (perLang defaults
+ * to true in the V2 schema); language-agnostic values use LANG_AGNOSTIC ("").
+ */
+type CommonOrmJson = [
+    uid,
+    Map<number, Set<uid>>,
+    Map<number, Set<uid>>,
+    Map<number, Map<Lang, number>>,
+    Map<number, Map<Lang, boolean>>,
+    Map<number, Map<Lang, string>>,
+    Map<Lang, InstanceData[]>
+];
+/**
+ * True JSON-text-safe serialization of CommonOrmJson — every uid slot is
+ * decimal-string-encoded (the toJsonId convention above) since bigint isn't
+ * JSON-serializable. This is what `Orm.toJSON()` emits, and therefore what
+ * `JSON.stringify(someRecord)` actually produces (JSON.stringify calls a
+ * `toJSON` method before applying any replacer). It is NOT a
+ * structured-clone/postMessage format — `CommonOrmJson` itself already
+ * survives structured clone natively (bigint is structured-clone-safe), so
+ * there's no separate bigint-native "serialized" form needed for that case.
+ */
+type SerializedCommonOrmJson = [
+    string,
+    Array<[number, Array<string>]>,
+    Array<[number, Array<string>]>,
+    Array<[number, Array<[Lang, number]>]>,
+    Array<[number, Array<[Lang, boolean]>]>,
+    Array<[number, Array<[Lang, string]>]>,
+    Array<[Lang, InstanceData[]]>
+];
+type PropertyType = 'string' | 'number' | 'boolean' | 'enum';
+interface BaseLocalOp {
+    ts: number;
+    action: ActionTypes;
+    objectType: number;
+    objectId: uid;
+}
+interface RateOp extends BaseLocalOp {
+    rate: Rating;
+}
+interface PartOp extends BaseLocalOp {
+    part: number;
+}
+interface RatePartOp extends PartOp {
+    rate: Rating;
+}
+interface ShareOp extends BaseLocalOp {
+    socialMediaId: number;
+}
+interface SharePartOp extends PartOp {
+    socialMediaId: number;
+}
+type LocalOp = RateOp | RatePartOp | PartOp | ShareOp | SharePartOp | BaseLocalOp;
+/**
+ * Anything the patcher queue can hold: EVM-bound V2 patches (`AnyPatch`,
+ * discriminated by `operation`) or local analytics ops (discriminated by `action`).
+ * Local delivery metadata is never encoded into a wire patch.
+ */
+type QueueItem = (AnyPatch | LocalOp) & {
+    eventId?: string;
+    sourceStream?: string;
+    provenance?: number;
+};
+declare const isEvmPatch: (item: QueueItem) => item is AnyPatch;
+type SidecarUrls = {
+    objectType: number;
+    lang: Lang;
+    slimUrl?: string;
+    extendedUrl?: string;
+    provUrl?: string;
+    aiUrl?: string;
+};
+type InitPayload = {
+    cmd: WorkerCommands.Init;
+    payload: {
+        /** Flattened sidecar URLs for all selected languages. */
+        sidecars: Array<SidecarUrls>;
+        selectedLangs: Lang[];
+    };
+};
+type SavePatchesPayload = {
+    cmd: WorkerCommands.SavePatches;
+    payload: {
+        username: string;
+        patches: Array<QueueItem>;
+    };
+};
+type GetRecordPayload = {
+    cmd: WorkerCommands.GetRecord;
+    payload: {
+        objectType: number;
+        id: uid;
+        creatorUsername?: string;
+    };
+};
+type LoadLanguagePayload = {
+    cmd: WorkerCommands.LoadLanguage;
+    payload: {
+        lang: Lang;
+        sidecars: Array<SidecarUrls>;
+    };
+};
+type WorkerPayload = InitPayload | SavePatchesPayload | GetRecordPayload | LoadLanguagePayload;
+interface IThread {
+    sendRequest(payload: WorkerPayload, transferables?: Array<any>): Promise<any>;
+}
+type StatSummary = {
+    visits: Array<number>;
+    rating: Rating;
+    socialMediaId: Array<number>;
+    downloads: Array<number>;
+    parts: {
+        [partId: string]: {
+            rating: Rating;
+            socialMediaId: Array<number>;
+            visits: Array<number>;
+        };
+    };
+};
+interface BookData {
+    fileId: string;
+    parsed: boolean;
+    author: string;
+    title: string;
+    dimensions: Array<{
+        width: number;
+        height: number;
+    } | null>;
+}
+interface FileRecord {
+    id: string;
+    creationTime: number;
+    sizeKb: number;
+    content: Uint8Array;
+    local: boolean;
+}
+declare enum BridgeRelation {
+    EquivalentWith = 0,
+    ChildOf = 1,
+    ParentOf = 2
+}
+interface BridgeLink {
+    id: number | string;
+    confidence: number;
+}
+interface BridgeSystemConversions {
+    equivalentWith?: BridgeLink[];
+    childOf?: BridgeLink[];
+    parentOf?: BridgeLink[];
+}
+interface BridgeDefinition {
+    original: string;
+    conversions?: Record<string, BridgeSystemConversions>;
+}
+
+/**
+ * V2 model definition — the shape of the enriched JSON files in
+ * `@the_library/db_schemas/generated-src/*.json` (frozen numeric IDs).
+ */
+interface SchemaProp {
+    name: string;
+    type: PropertyType;
+    source: 'slim' | 'extended';
+    propId: number;
+    enum?: string;
+    bits?: number;
+    nullable?: boolean;
+}
+interface SchemaInstanceField {
+    name: string;
+    type: PropertyType;
+    propId: number;
+    enum?: string;
+    bits?: number;
+    nullable?: boolean;
+    identityComponent?: boolean;
+    source?: 'slim' | 'extended';
+}
+interface SchemaRelation {
+    name: string;
+    targetType: string;
+    direction: 'has' | 'in';
+    cardinality: '1to1' | '1toN';
+    inverted: string;
+    relationId: number;
+}
+/**
+ * Cols field name for a `has`-relation tail. The `authors` relation keeps its
+ * historical `authorIds` name for back-compat; every other relation uses its
+ * schema name directly (e.g. Tag.tags, Tag.books). Single source of truth for
+ * both the codegen (schemaGenerator.ts, which emits `${relationColName(rel)}`
+ * as the ExtendedCols field name) and the runtime reader (orm.ts's
+ * mergeExtended, which must look up that same field name on the incoming cols
+ * object) — they must never drift apart.
+ */
+declare const relationColName: (rel: SchemaRelation) => string;
+interface SchemaIndex {
+    name: string;
+    keys: string[];
+    linkToUidStrategy?: boolean;
+    classifier?: {
+        type: 'prefix';
+        separator: string;
+        fallback: string;
+        customMappings?: Record<string, string>;
+    };
+}
+interface ModelDefinition {
+    name: string;
+    typePrefix: string;
+    objectId: number;
+    multipleInstances: boolean;
+    uidStrategy?: string | string[];
+    instanceUidStrategy?: string | string[];
+    isPrivate?: boolean;
+    standardPks?: Record<string, string>;
+    props: SchemaProp[];
+    instanceFields: SchemaInstanceField[];
+    relations: SchemaRelation[];
+    indexes?: SchemaIndex[];
+}
+declare class SchemaRegistry {
+    private static instance;
+    private schemas;
+    private byName;
+    private constructor();
+    static getInstance(): SchemaRegistry;
+    register(schema: ModelDefinition): void;
+    get(id: number): ModelDefinition;
+    /** Lookup by model name (relation targetType resolution). */
+    getByName(name: string): ModelDefinition | undefined;
+    clear(): void;
+}
+declare const Registry: SchemaRegistry;
+
+/**
+ * Replay/baking metadata: real per-language "was this actually set" state,
+ * carried alongside the corpus's flattened display values so both the corpus
+ * baker (`@the_library/corpus-builder`) and worker/browser LRU rehydration
+ * (`orm.ts`'s `mergeProv`, `reconstructRecord.ts`) can reuse the exact same
+ * fallback-resolution rules the live ORM already implements for setters/
+ * getters (`resolveLangValue` in orm.ts), instead of each reimplementing an
+ * approximation of it.
+ *
+ * BACKGROUND — why this exists at all (2026-09-08, findings #5/#6 in
+ * reviews/2026-09-07/assessment.md, and the follow-up probe documented in
+ * reviews/2026-09-07/implementation-p1-5-through-p1-6.md):
+ *
+ * The published corpus (`BookInput`/`TagInput`/`PersonInput`, see
+ * generated-src/*.ts) stores exactly ONE flattened value per property per
+ * per-language corpus build (e.g. `book.title` in the `fra` corpus is a
+ * single string). The corpus baker (`apply-patches-plain.ts`) runs
+ * incrementally: each build call receives only the patches accumulated since
+ * the last build (`data/patches.jsonl` is truncated after every successful
+ * publish — see apps/book-manager/CLAUDE.md's "Publishing the models_v2
+ * corpus" section), plus the PREVIOUS build's already-flattened output as its
+ * starting point. That flattened single value is fundamentally ambiguous:
+ * given `book.title === 'Arbre'` for the `fra` build, there is no way to tell
+ * whether "Arbre" is a genuine, deliberately-authored French title, or
+ * whether it is itself a fallback value that leaked in from an English edit
+ * because French had never been set yet. The same ambiguity applies to
+ * `false`/`0`/`""`: a nullable field's `""` might mean "explicitly cleared"
+ * or "never set"; a non-nullable boolean/number's `false`/`0` is completely
+ * indistinguishable from "never set" once flattened.
+ *
+ * A first fix attempt tried to paper over this with a heuristic (checking
+ * whether the flattened value was "nullable and non-empty" before allowing a
+ * fallback edit to overwrite it). That heuristic could not protect
+ * non-nullable fields (`safe`, `deleted`, every `QualityScore`) at all, and
+ * could not tell a real translation from a previously-baked fallback either
+ * — see the git history of apply-patches-plain.ts around that date for what
+ * NOT to reintroduce.
+ *
+ * The actual fix: export the ORM's REAL internal per-(propId, lang) storage
+ * (`Orm._stringValues`/`_numberValues`/`_boolValues`, via `Orm.propertySlots()`)
+ * as a small, JSON-serializable side-channel, persist it in the corpus's
+ * existing binary "prov" sidecar tier (see serializer.ts's
+ * `commonSerializeProv`/`commonDeserializeProv` and this file's
+ * `REPLAY_METADATA_COLUMNS`), and restore it into a real headless `Orm`
+ * instance before each incremental bake (`apply-patches-plain.ts`). Because
+ * `Map.has(lang)` is a real presence check independent of the stored value,
+ * `false`/`0`/`""` are now indistinguishable from nothing ONLY when they
+ * really are nothing — solving both the cross-language-overwrite bug and the
+ * non-nullable-field blind spot structurally, not via a guess.
+ *
+ * Compatibility limit (documented in implementation-p1-5-through-p1-6.md):
+ * a corpus built BEFORE this change has no slots at all. The first time such
+ * a record is baked under the new code (`apply-patches-plain.ts`'s
+ * `!fresh.has(rec)` bootstrap branch), every one of its current non-null
+ * flattened values is conservatively treated as an explicit slot for the
+ * CURRENT build's language — including any prior English-fallback-into-French
+ * corruption from before this fix existed. This stops the bug from
+ * recurring; it cannot retroactively repair history that's already wrong.
+ * Only a rebuild from the original patch log (not the already-flattened
+ * corpus) can recover genuinely lost translation intent.
+ */
+type PropertySlots = Array<[number, Array<[Lang, string | number | boolean]>]>;
+/**
+ * Sidecar column names (as written into the binary "prov" tier — see
+ * `serializer.ts`) vs. the in-memory field names used on plain
+ * `BookInput`/`TagInput`/`PersonInput` objects while baking. Deliberately
+ * DOUBLE-underscored on the wire (`__propertySlots`/`__instanceRemaps`) to
+ * keep them visually distinct from the existing single-underscore `_prov`/
+ * `_createSeq` bookkeeping fields these plain objects already carry
+ * informally (neither of those is declared in the generated `BookInput`
+ * etc. interfaces either — this follows the same, pre-existing convention).
+ *
+ * These are genuinely NEW named columns in the prov sidecar's binary format,
+ * not a new sidecar file/tier and not a `SIDECAR_FORMAT_VERSION` bump: the
+ * sidecar column format is self-describing (each column writes its own type
+ * byte + name string ahead of its data — see enriched-index.ts's
+ * `writeSidecar`/`parseSidecar`), so an old reader parsing a new sidecar
+ * still parses these columns without error (it just won't know what to do
+ * with the data), and a new reader parsing an old sidecar (without these
+ * columns) simply sees them as absent — see `commonDeserializeProv`'s
+ * `REPLAY_METADATA_COLUMNS` branch in serializer.ts.
+ */
+declare const PROPERTY_SLOTS_COLUMN = "__propertySlots";
+declare const INSTANCE_REMAPS_COLUMN = "__instanceRemaps";
+/** [sidecar column name, in-memory field name] pairs — see the doc comment above. */
+declare const REPLAY_METADATA_COLUMNS: readonly [readonly ["__propertySlots", "_propertySlots"], readonly ["__instanceRemaps", "_instanceRemaps"]];
+/** Base properties (propId 0-7) plus a schema's own `props`, keyed by propId
+ *  so a schema can override a base entry if it ever needs to (Map dedup keeps
+ *  the last write per propId — schema.props is spread after baseProperties). */
+declare function scalarProperties(schema: ModelDefinition): SchemaProp[];
+
+declare enum LifecycleStatus {
+    Provisional = 0,
+    Submitted = 1,
+    CommunityPending = 2,
+    Canonical = 3
+}
+
+/** Called after every StatsStore change (a local action, or restored rows added). */
+declare const subscribeStats: (listener: () => void) => (() => void);
+declare const PopulateStatsStore: (operations: Array<LocalOp>) => void;
+declare const DownloadsByType: (objectType: number) => Array<uid>;
+declare const VisitsByType: (objectType: number) => Array<uid>;
+declare const FavoritesByTypes: (objectType: number) => Array<{
+    id: uid;
+    nbVisits: number;
+    rating: Rating;
+}>;
+declare class Stats {
+    private objectId;
+    protected objectType: number;
+    constructor(objectId: uid, objectType: number);
+    favoriteParts(): Array<{
+        partId: number;
+        nbVisits: number;
+        rating: Rating;
+    }>;
+    check(): void;
+    visit(): void;
+    download(): void;
+    get rating(): Rating;
+    set rating(rating: Rating);
+    share(socialMediaId: number): void;
+    ratePart(partId: number, rating: Rating): void;
+    visitPart(partId: number): void;
+}
+
+interface UidFactory {
+    next(): Promise<{
+        wireId: bigint;
+    }>;
+    isUserCreated(wireId: bigint): boolean;
+}
+/**
+ * Bit 63 is the user-created scope flag (see optmized-uid/11-wireId-64bits-refactor.md §0).
+ * scope(1) + random(63). 0 = canonical, 1 = user-created.
+ */
+declare function isUserCreated(wireId: bigint | number | string): boolean;
+declare class CryptoRandomUidFactory implements UidFactory {
+    next(): Promise<{
+        wireId: bigint;
+    }>;
+    isUserCreated(wireId: bigint): boolean;
+}
+declare function loadOrInitUidFactory(db: IDBDatabase): Promise<UidFactory>;
+
+declare const Config: {
+    readonly userLang: Lang;
+    readonly commonLang: Lang;
+    readonly defaultProvenance: number | undefined;
+    readonly loadAiSidecars: boolean;
+};
+declare function setDefaultLanguage(lang: Lang): void;
+declare function setDefaultProvenance(provenance: number): void;
+declare function setLoadAiSidecars(enabled: boolean): void;
+declare const PROVENANCE_UNSET = 0;
+declare const PROVENANCE_AI = 1;
+declare const PROVENANCE_MANUAL_LOCAL = 2;
+declare const PROVENANCE_CONSENSUS = 3;
+declare const TITLE_PROP = 0;
+declare const DESCRIPTION_PROP = 1;
+declare const ORIGINAL_LANG_PROP = 2;
+declare const AGE_GRADE_BAND_PROP = 3;
+declare const PREVIEW_TX_ID_PROP = 4;
+declare const SAFE_PROP = 5;
+declare const DELETED_PROP = 6;
+declare const LIFECYCLE_STATUS_PROP = 7;
+
+/** Decimal-string-encodes every uid — see SerializedCommonOrmJson's own doc comment for why. */
+declare function serializeMapOfSets(map: Map<number, Set<uid>>): Array<[number, Array<string>]>;
+declare function serializeMapOfMaps<V>(mapOfMaps: Map<number, Map<Lang, V>>): Array<[number, Array<[Lang, V]>]>;
+declare const inflateOrmJson: (v2: SerializedCommonOrmJson) => CommonOrmJson;
+interface DeepCollectOptions {
+    /** Include deleted/unsafe records — both as final result items and as
+     *  pass-through nodes during traversal. Default false: a deleted/unsafe
+     *  node discovered via the hierarchy or a bridge is a dead end (neither
+     *  its own contributions nor anything beyond it is included). The
+     *  query's own starting record is exempt from this — it is always
+     *  processed regardless of its own deleted/safe flags, since the caller
+     *  explicitly chose it. */
+    includeDeleted?: boolean;
+    /** Which BridgeRelation types to follow when expanding across bridges.
+     *  Default [EquivalentWith, ParentOf] — "broader absorbs narrower", the
+     *  same rule the has-direction hierarchy relation already follows.
+     *  ChildOf points to something BROADER than the caller and is excluded
+     *  by default (following it would balloon every leaf query to include
+     *  an entire foreign classification system) — pass it explicitly to
+     *  opt in. Pass [] to disable bridge-following entirely. */
+    bridgeTypes?: BridgeRelation[];
+}
+declare class Orm extends Stats {
+    /** Persisted delivery boundary already included by worker reconstruction. */
+    hydratedThrough: number;
+    readonly _id: uid;
+    protected _boolValues: Map<number, Map<string, boolean>>;
+    protected _stringValues: Map<number, Map<string, string>>;
+    protected _numberValues: Map<number, Map<string, number>>;
+    protected _has: Map<number, Set<bigint>>;
+    protected _in: Map<number, Set<bigint>>;
+    /** lang -> instance array (BookInstanceData structs, not ORM objects). */
+    protected _instances: Map<string, InstanceData[]>;
+    /** lang -> propId -> provenance code (2-bit: unset/AI/human/consensus). */
+    protected _provenance: Map<string, Map<number, number>>;
+    protected _aiResults: Map<string, Map<string, Map<string, Set<{
+        ts: number;
+        value: any;
+        format: string;
+    }>>>>;
+    /** Bridges to other taxonomy systems */
+    bridges?: BridgeDefinition;
+    schema: ModelDefinition;
+    /**
+     * Safe relation accessor for generated model getters. For each relation ID:
+     * - If the target record is resident in the LRU cache, it is loaded and included.
+     * - If the target record is missing (never loaded, evicted, or a stale sidecar
+     *   reference), a detailed console warning is emitted and the ID is skipped.
+     *   The application never crashes from an unresolved relation.
+     *
+     * Warning format:
+     *   [ORM] Tag with Id=123 and name="General" has a relationship not met:
+     *   tags to Id=4718593. With id=4718593 not defined.
+     *
+     * @param owner       The record that owns the relation (used for the log message).
+     * @param ids         The set of target IDs stored in the relation.
+     * @param checker     `ModelClass.Has` — returns true when the record is in cache.
+     * @param loader      `ModelClass.Load` — retrieves the record from cache.
+     * @param relationName Human-readable relation name, e.g. `"tags"` or `"inTags"`.
+     */
+    protected static _safeRelation<T>(owner: Orm, ids: uid[], checker: (id: uid) => boolean, loader: (id: uid) => T, relationName: string): T[];
+    static createNewRequest(id: uid): CommonOrmJson;
+    static createNewRecord<T extends Orm>(this: {
+        new (json: any, creatorUsername?: string): T;
+        type: number;
+    }, uidFactory: UidFactory, creatorUsername: string): Promise<T>;
+    protected _creatorUsername?: string;
+    get creatorUsername(): string;
+    constructor(objectType: number, json: CommonOrmJson | SerializedCommonOrmJson, creatorUsername?: string);
+    /**
+     * `(user:objectId:langId:originalIndex) -> realIndex` pairs, produced by
+     * `patchContext.ts`'s `resolveAddInstanceConflict` whenever an incoming
+     * `AddInstance` collides with an index another author/device already
+     * populated with a genuinely different edition (different `downloadTxId`
+     * etc. — see `areInstancesEqual`). Kept as a plain array of tuples, not a
+     * `Map`, purely so it round-trips through `JSON.stringify`/`JSON.parse`
+     * unchanged for persistence (a `Map` doesn't survive that). Persisted two
+     * ways, both consumed the same way:
+     *  - Live app: `patchContext.ts`'s `InstanceRemapStore` (backed by an
+     *    IndexedDB `instanceRemaps` object store — see
+     *    apps/book-manager/specifications/done/record_creation_flow_v2.md
+     *    §3.3) durably remembers a remap so a device's LATER patches
+     *    addressed to the old index get silently redirected.
+     *  - Corpus baking / worker rehydration: this field itself is the
+     *    durable copy, serialized into the `__instanceRemaps` sidecar column
+     *    (see propertySlots.ts) so a remap made during one incremental
+     *    corpus build survives into the next one, even though
+     *    `data/patches.jsonl` (the source patches) is cleared after every
+     *    build. Without this, a field-only edit in a LATER build that still
+     *    referenced the pre-remap index would silently corrupt whichever
+     *    edition now legitimately occupies that slot — this is exactly what
+     *    reviews/2026-09-07/implementation-p1-5-through-p1-6.md's "a remap
+     *    was lost after binary bake/reload" regression test guards against.
+     *  - `patchContext.ts`'s remap lookup checks BOTH sources (live
+     *    `instanceRemapStore` first, then this field) so a corpus-restored
+     *    mapping can inform live replay when local IndexedDB has none yet.
+     */
+    instanceRemaps: Array<[string, number]>;
+    /**
+     * Export the REAL per-(propId, lang) storage — not resolved/flattened
+     * values — as a JSON-serializable array. This is the read side of the
+     * property-slots mechanism documented in propertySlots.ts: it lets a
+     * caller (the corpus baker, or worker rehydration via `mergeProv`)
+     * persist "which languages actually have an explicit value for this
+     * property" across a serialize/deserialize round trip, so a later
+     * `restorePropertySlots()` call can reconstruct a record whose
+     * `resolveLangValue`-based fallback behaves identically to a record that
+     * was never detached at all.
+     */
+    propertySlots(): PropertySlots;
+    /**
+     * Restore real per-language property state (the inverse of
+     * `propertySlots()`), for a headless/detached `Orm` instance that has no
+     * other way to acquire it (the corpus baker constructs one from scratch
+     * for every record it bakes — see apply-patches-plain.ts).
+     *
+     * `scope` exists because the corpus baker's restore is asymmetric: for
+     * the language it is CURRENTLY building (e.g. baking the `fra` corpus),
+     * the persisted `fra` slots must be treated as the complete, authoritative
+     * truth for that language — anything not explicitly there really is
+     * unset. But OTHER languages' slots (e.g. `eng`) are only useful as
+     * fallback data if `fra` turns out to have nothing at all for a given
+     * property; they must not silently overwrite anything already restored
+     * for the target language. `scope === undefined` is the simpler
+     * unscoped case (restoring a complete detached snapshot with no
+     * asymmetry, e.g. worker rehydration in `mergeProv`) and clears
+     * everything first. With a `scope`, only that language's existing slots
+     * are cleared before restoring (so a stale `fra` value from a PRIOR
+     * build doesn't linger if bootstrapping fresh state), and the
+     * `!values.get(id)?.has(lang)` check on the fallback path guarantees an
+     * already-restored `scope` value is never clobbered by another
+     * language's slot processed later in the same `slots` array.
+     *
+     * Why this can't be approximated by checking whether the corpus's
+     * flattened value is falsy/empty: see propertySlots.ts's module doc —
+     * `false`/`0`/`""` are legitimate explicit values that a heuristic
+     * cannot tell apart from "never set". Only replaying the real slots data
+     * (a genuine Map keyed by language) preserves that distinction.
+     */
+    restorePropertySlots(slots: PropertySlots, scope?: Lang): void;
+    /** Complete worker hydration state; unlike toJSON, includes auxiliary tiers. */
+    snapshot(): {
+        json: SerializedCommonOrmJson;
+        instanceRemaps: [string, number][];
+        patchOrder: number;
+        provenance: Map<string, Map<number, number>>;
+        bridges: BridgeDefinition | undefined;
+        ai: Map<string, Map<string, Map<string, Set<{
+            ts: number;
+            value: any;
+            format: string;
+        }>>>>;
+    };
+    /** Replace materialized state in place so existing UI references remain valid. */
+    replaceSnapshot(state: ReturnType<Orm['snapshot']>): void;
+    restoreSnapshot(state: ReturnType<Orm['snapshot']>): void;
+    toJSON(): SerializedCommonOrmJson;
+    /** Raw cross-language view: company -> model -> lang -> results. */
+    getAiResultsAllLangs(): Map<string, Map<string, Map<Lang, Set<{
+        ts: number;
+        value: any;
+        format: string;
+    }>>>>;
+    /** Per-language view: company -> model -> results, resolved for `lang`
+     *  (falls back to the session's default language when omitted/null). */
+    getAiResults(lang?: Lang | null): Map<string, Map<string, Set<{
+        ts: number;
+        value: any;
+        format: string;
+    }>>>;
+    /** AI results are per-language: the same record can carry a different assessment per translation. */
+    attachAiResult(company: string, modelName: string, lang: Lang, result: any): void;
+    get id(): uid;
+    protected langOf(langId: number): Lang;
+    protected langIdOf(lang?: Lang): number;
+    getLoadedLanguages(): Lang[];
+    /**
+     * Get the uidStrategy array defined in this model's schema.
+     * Used to determine which classification systems are supported.
+     */
+    protected getUidStrategies(): string[];
+    /**
+     * Detect which classification system (uidStrategy) this record belongs to.
+     * Works by checking which notation/classification fields are populated.
+     *
+     * Field name mapping uses a convention: "lcc" -> "lccNotation" or special
+     * names like "lcc" -> "locCallNumber" for Book. The mapping is determined
+     * by the MODEL_CLASSIFICATION_FIELD_MAP in classification-utils.
+     *
+     * @param fieldMap Optional override mapping of strategy -> field name
+     * @returns The detected strategy, or 'unclassified' if none found
+     */
+    getClassificationType(fieldMap?: Record<string, string>): string;
+    /**
+     * Get the default field name mapping for this model's classification systems.
+     * Override in subclasses or provide via fieldMap parameter if needed.
+     *
+     * Default convention: strategy "X" maps to field "xNotation" (e.g., "lcc" -> "lccNotation")
+     */
+    protected getDefaultClassificationFieldMap(): Record<string, string>;
+    get title(): string;
+    set title(value: string);
+    getTitle(lang: Lang): string;
+    setTitle(value: string, lang: Lang): void;
+    get description(): string;
+    set description(value: string);
+    getDescription(lang: Lang): string;
+    setDescription(value: string, lang: Lang): void;
+    get originalLang(): string;
+    set originalLang(value: string);
+    getOriginalLang(lang: Lang): string;
+    setOriginalLang(value: string, lang: Lang): void;
+    get ageGradeBand(): number;
+    set ageGradeBand(value: number);
+    get previewTxId(): string;
+    set previewTxId(value: string);
+    get safe(): boolean;
+    set safe(value: boolean);
+    get deleted(): boolean;
+    set deleted(value: boolean);
+    get lifecycleStatus(): LifecycleStatus;
+    set lifecycleStatus(value: LifecycleStatus);
+    protected dispatchString(propertyId: number, value: string, lang?: Lang): void;
+    protected dispatchNumber(propertyId: number, value: number, lang?: Lang): void;
+    protected dispatchRelation(relationId: number, action: PatchAction, targetId: uid): void;
+    /**
+     * Raw in-memory relation mutation: no patch is emitted. Used by the
+     * generic inverse propagation in patch() and by generated in-side
+     * relation helpers. Idempotent (Set semantics).
+     */
+    protected applyRelationRaw(direction: 'has' | 'in', relationId: number, action: PatchAction, targetId: uid, effects?: boolean): void;
+    /**
+     * Bulk-restores the inverse (`in`) edges implied by this record's forward
+     * (`has`) relations onto their target records. The sidecar serializes only
+     * the `has` direction (§3.7.1); `mergeExtended` fills `_has`, but the inverse
+     * side (`Person.authorOf`, `Tag.inTags`, …) stays empty until this runs.
+     *
+     * No patch emitted, no reactivity fired (bulk boot path). Idempotent (Set
+     * add). Targets must already be materialized — call after a full
+     * `hydrateAll` pass (see `rebuildInverseRelations`).
+     */
+    restoreInverses(): void;
+    /**
+     * Looks up an existing child of the `has`-side relation `relationId`
+     * whose title (base prop 0) matches `title` after trim + case-fold.
+     * Children not materialized in the LRU are skipped — same tolerance as
+     * `_safeRelation`. Returns null when no materialized child matches.
+     */
+    findChildByTitle(relationId: number, title: string): Orm | null;
+    /**
+     * Re-hydrates any children of `relationId` evicted from the LRU cache.
+     * Without this, `findChildByTitle` silently skips evicted-but-real
+     * children (it can only see what's resident), so `getOrCreateChildByTitle`
+     * would mint a duplicate instead of finding the existing match — the
+     * eviction-driven dup-tag bug. A no-op if the target class was never
+     * registered (registerModelClass runs at generated-module load) or
+     * nothing is actually missing.
+     */
+    private hydrateChildren;
+    /**
+     * Find-or-create keyed on child title, scoped to this parent. The
+     * relation Set already guarantees a child id can only appear once; this
+     * extends the uniqueness to titles: if a child titled `title` already
+     * exists in `relationId`, it is returned untouched and nothing is
+     * created or linked. Otherwise `create` mints the record, its title is
+     * set and it is linked to this parent. Titles may still repeat under
+     * OTHER parents (e.g. many taxonomy branches each own a "General") —
+     * that is deliberate; uniqueness is per parent, not global.
+     */
+    getOrCreateChildByTitle<T extends Orm>(relationId: number, title: string, create: () => Promise<T>): Promise<T>;
+    /**
+     * Generic recursive collector for any "has"/"in" relation, declaratively
+     * driven by the schema — no model needs its own copy of this logic (it
+     * used to be hand-rolled three separate times in apps/book-manager:
+     * topic-actions.ts's collectTopicDownloadTxIds, TopicTree.tsx's
+     * countBooksRecursive, ClassificationTree.tsx's countBooks).
+     */
+    getBridgedRelationIdsSync(relationId: number, direction: 'has' | 'in', visitedBridges?: Set<string>): Array<uid>;
+    /**
+     * Walks two axes from `this`, unioning `relationName`'s targets at every
+     * node reached on either axis, recursively:
+     *   - the has-direction self-referential hierarchy relation (e.g.
+     *     Tag.tags) — UNLESS relationName itself IS that self-referential
+     *     relation's in-direction counterpart (e.g. Tag.inTags), in which
+     *     case structural expansion ascends via that relation instead of
+     *     descending via the has side;
+     *   - this.bridges (cross-classification-system links), following only
+     *     the BridgeRelation types in opts.bridgeTypes and resolving each
+     *     link's id against this record's OWN model type (bridges carry no
+     *     target-type field — the data model only supports same-type links,
+     *     e.g. Tag-to-Tag — a non-numeric or unresolvable id is skipped, not
+     *     thrown, since it may be an external standard's notation with no
+     *     local record backing it).
+     *
+     * One visited-node Set spans both axes, so any cycle — pure hierarchy,
+     * pure bridge, or mixed — terminates and each node contributes once.
+     * See bridgeDeepRelations.test.ts for the full behavioral spec this
+     * implements.
+     */
+    collectDeepIds(relationName: string, opts?: DeepCollectOptions): Promise<uid[]>;
+    /**
+     * Applies a V2 patch to the in-memory state. Triggers reactivity.
+     */
+    patch(patch: AnyPatch, _isMine?: boolean, effects?: boolean): void;
+    protected applyInstancePatch(p: EditInstanceFieldStringObj | EditInstanceFieldNumberObj): void;
+    protected getPropType(propId: number): 'string' | 'number' | 'boolean';
+    /**
+     * Resolve stored values without adding a UI default for an absent
+     * string. `getProp` (below) exists for live UI code, which wants an
+     * absent string coerced to `''` for convenient rendering. The corpus
+     * baker needs the RAW resolved value — including a genuine `undefined`
+     * when nothing at all applies — so it can tell "this property resolved
+     * to a value" apart from "this property has no applicable slot yet" when
+     * deciding whether an edit actually changed anything (see
+     * apply-patches-plain.ts's `applied++` bookkeeping, which compares this
+     * against the corpus's previous flattened value).
+     */
+    resolvedPropertyValue(propId: number, lang: Lang): any;
+    getProp(propId: number, lang?: Lang): any;
+    /** Direct state write — no patch emitted (used by merge methods). */
+    protected setRaw(propId: number, value: any, lang?: Lang): void;
+    getInstancesData(lang?: Lang): InstanceData[];
+    getDefaultInstanceData(lang?: Lang): InstanceData | undefined;
+    /** Direct state write — no patch emitted (used by mergeExtended/mergeSlim). */
+    setInstancesRaw(lang: Lang, instances: InstanceData[]): void;
+    growInstances(lang: Lang, toIndex: number): void;
+    addInstance(lang?: Lang): number;
+    getProvenance(propId: number, lang?: Lang): number;
+    setProvenanceRaw(lang: Lang, propId: number, value: number): void;
+    mergeSlim(cols: any, index: number, lang?: Lang): void;
+    mergeExtended(cols: any, index: number, lang?: Lang): void;
+    mergeProv(cols: any, index: number, lang?: Lang): void;
+}
+
+export { Registry as $, type AnyActionPatch as A, type BridgeDefinition as B, type CommonOrmJson as C, type DeepCollectOptions as D, type EvmPayload as E, type FileRecord as F, type GetRecordPayload as G, type StatSummary as H, type InstanceData as I, BridgeRelation as J, type BridgeLink as K, type Lang as L, type BridgeSystemConversions as M, type SchemaProp as N, Orm as O, type PropertyType as P, type QueueItem as Q, type RecordIdentityCluster as R, SidecarType as S, type SchemaInstanceField as T, type SchemaRelation as U, type VersionsFile as V, WorkerCommands as W, relationColName as X, type SchemaIndex as Y, type ModelDefinition as Z, SchemaRegistry as _, type SidecarUrls as a, type PropertySlots as a$, PatchOperation as a0, PatchAction as a1, packPatch as a2, unpackPatch as a3, resolveLayout as a4, patchToEvm as a5, evmToPatch as a6, LANG_ID_ENCODE as a7, LANG_ID_DECODE as a8, ActionOperation as a9, VisitsByType as aA, FavoritesByTypes as aB, Stats as aC, type UidFactory as aD, isUserCreated as aE, CryptoRandomUidFactory as aF, loadOrInitUidFactory as aG, LifecycleStatus as aH, Config as aI, setDefaultLanguage as aJ, setDefaultProvenance as aK, setLoadAiSidecars as aL, PROVENANCE_UNSET as aM, PROVENANCE_AI as aN, PROVENANCE_MANUAL_LOCAL as aO, PROVENANCE_CONSENSUS as aP, TITLE_PROP as aQ, DESCRIPTION_PROP as aR, ORIGINAL_LANG_PROP as aS, AGE_GRADE_BAND_PROP as aT, PREVIEW_TX_ID_PROP as aU, SAFE_PROP as aV, DELETED_PROP as aW, LIFECYCLE_STATUS_PROP as aX, serializeMapOfSets as aY, serializeMapOfMaps as aZ, inflateOrmJson as a_, isActionOperation as aa, packActionPatch as ab, unpackActionPatch as ac, type BasePatch as ad, type EditPropertyStringObj as ae, type EditPropertyNumberObj as af, type EditInstanceFieldStringObj as ag, type EditInstanceFieldNumberObj as ah, type EditRelationObj as ai, type CreateRecordObj as aj, type AddInstanceObj as ak, type MergeProposalObj as al, type DeleteBridgeObj as am, type VersionEntry as an, type EnumLayout as ao, type PropLayout as ap, type BaseActionPatch as aq, type VisitActionObj as ar, type DownloadActionObj as as, type RateActionObj as at, type RatePartActionObj as au, type ShareActionObj as av, type SharePartActionObj as aw, subscribeStats as ax, PopulateStatsStore as ay, DownloadsByType as az, type SerializedCommonOrmJson as b, PROPERTY_SLOTS_COLUMN as b0, INSTANCE_REMAPS_COLUMN as b1, REPLAY_METADATA_COLUMNS as b2, scalarProperties as b3, type VersionLayout as c, type IThread as d, type LocalOp as e, type AnyPatch as f, type BookData as g, ActionTypes as h, Rating as i, WorkerEvent as j, DownloadState as k, fromJsonId as l, LANG_AGNOSTIC as m, type BaseLocalOp as n, type RateOp as o, type PartOp as p, type RatePartOp as q, type ShareOp as r, type SharePartOp as s, toJsonId as t, type uid as u, isEvmPatch as v, type InitPayload as w, type SavePatchesPayload as x, type LoadLanguagePayload as y, type WorkerPayload as z };