@the_library/public 1.0.0 → 2.0.0

package/dist/models/index.d.ts

@@ -1,10 +1,12 @@
-export { BOOK_PROP_IDS, Book, BookExtendedCols, BookInput, BookInstance, BookProvCols, BookSlimCols, ModelClass, ModelTypes, NewBookWithId, NewPersonWithId, NewTagWithId, PERSON_PROP_IDS, Person, PersonExtendedCols, PersonInput, PersonProvCols, PersonSlimCols, TAG_PROP_IDS, Tag, TagExtendedCols, TagInput, TagProvCols, TagSlimCols, serializeBookExtended, serializeBookProv, serializeBookSlim, serializePersonExtended, serializePersonProv, serializePersonSlim, serializeTagExtended, serializeTagProv, serializeTagSlim } from './models.js';
-import { V as VersionsFile, c as VersionLayout, u as uid, O as Orm, Q as QueueItem, d as IThread, E as EvmPayload, A as AnyPatch, F as FileRecord, B as BookData } from '../orm-BvkX0aBT.js';
-export { e as ActionTypes, a8 as AddInstanceObj, i as BaseLocalOp, a0 as BasePatch, C as CommonOrmJson, a7 as CreateRecordObj, D as DownloadState, ad as DownloadsByType, a4 as EditInstanceFieldNumberObj, a3 as EditInstanceFieldStringObj, a2 as EditPropertyNumberObj, a1 as EditPropertyStringObj, a5 as EditRelationObj, aa as EnumLayout, af as FavoritesByTypes, G as GetRecordPayload, q as InitPayload, I as InstanceData, h as LANG_AGNOSTIC, $ as LANG_ID_DECODE, _ as LANG_ID_ENCODE, L as Lang, s as LoadLanguagePayload, o as LocalOp, M as ModelDefinition, k as PartOp, N as PatchAction, K as PatchOperation, ac as PopulateStatsStore, ab as PropLayout, P as PropertyType, j as RateOp, l as RatePartOp, f as Rating, R as RecordIdentityCluster, J as Registry, r as SavePatchesPayload, x as SchemaInstanceField, w as SchemaProp, H as SchemaRegistry, y as SchemaRelation, b as SerializedCommonOrmJson, a6 as SetAliasObj, m as ShareOp, n as SharePartOp, S as SidecarType, a as SidecarUrls, v as StatSummary, ag as Stats, a9 as VersionEntry, ae as VisitsByType, W as WorkerCommands, g as WorkerEvent, t as WorkerPayload, Z as evmToPatch, p as isEvmPatch, T as packPatch, Y as patchToEvm, z as relationColName, X as resolveLayout, U as unpackPatch } from '../orm-BvkX0aBT.js';
-export { L as LevelState, g as getLevel, s as subscribeLevel } from '../level-state-J3pj64Tr.js';
+export { CLASSIFICATIONSYSTEM_PROP_IDS, ClassificationSystem, ClassificationSystemExtendedCols, ClassificationSystemInput, ClassificationSystemProvCols, ClassificationSystemSlimCols, ModelClass, ModelTypes, NewClassificationSystemWithId, NewPostWithId, POST_PROP_IDS, Post, PostExtendedCols, PostInput, PostProvCols, PostSlimCols, deserializeClassificationSystemExtended, deserializeClassificationSystemProv, deserializeClassificationSystemSlim, deserializePostExtended, deserializePostProv, deserializePostSlim, serializeClassificationSystemExtended, serializeClassificationSystemProv, serializeClassificationSystemSlim, serializePostExtended, serializePostProv, serializePostSlim } from './models.js';
+import { V as VersionsFile, c as VersionLayout, u as uid, O as Orm, Q as QueueItem, d as IThread, e as LocalOp, A as AnyActionPatch, E as EvmPayload, f as AnyPatch, F as FileRecord, g as BookData, L as Lang } from '../orm-MJTHCG9E.js';
+export { aT as AGE_GRADE_BAND_PROP, a9 as ActionOperation, h as ActionTypes, ak as AddInstanceObj, aq as BaseActionPatch, n as BaseLocalOp, ad as BasePatch, B as BridgeDefinition, K as BridgeLink, J as BridgeRelation, M as BridgeSystemConversions, C as CommonOrmJson, aI as Config, aj as CreateRecordObj, aF as CryptoRandomUidFactory, aW as DELETED_PROP, aR as DESCRIPTION_PROP, D as DeepCollectOptions, am as DeleteBridgeObj, as as DownloadActionObj, k as DownloadState, az as DownloadsByType, ah as EditInstanceFieldNumberObj, ag as EditInstanceFieldStringObj, af as EditPropertyNumberObj, ae as EditPropertyStringObj, ai as EditRelationObj, ao as EnumLayout, aB as FavoritesByTypes, G as GetRecordPayload, b1 as INSTANCE_REMAPS_COLUMN, w as InitPayload, I as InstanceData, m as LANG_AGNOSTIC, a8 as LANG_ID_DECODE, a7 as LANG_ID_ENCODE, aX as LIFECYCLE_STATUS_PROP, aH as LifecycleStatus, y as LoadLanguagePayload, al as MergeProposalObj, Z as ModelDefinition, aS as ORIGINAL_LANG_PROP, aU as PREVIEW_TX_ID_PROP, b0 as PROPERTY_SLOTS_COLUMN, aN as PROVENANCE_AI, aP as PROVENANCE_CONSENSUS, aO as PROVENANCE_MANUAL_LOCAL, aM as PROVENANCE_UNSET, p as PartOp, a1 as PatchAction, a0 as PatchOperation, ay as PopulateStatsStore, ap as PropLayout, a$ as PropertySlots, P as PropertyType, b2 as REPLAY_METADATA_COLUMNS, at as RateActionObj, o as RateOp, au as RatePartActionObj, q as RatePartOp, i as Rating, R as RecordIdentityCluster, $ as Registry, aV as SAFE_PROP, x as SavePatchesPayload, Y as SchemaIndex, T as SchemaInstanceField, N as SchemaProp, _ as SchemaRegistry, U as SchemaRelation, b as SerializedCommonOrmJson, av as ShareActionObj, r as ShareOp, aw as SharePartActionObj, s as SharePartOp, S as SidecarType, a as SidecarUrls, H as StatSummary, aC as Stats, aQ as TITLE_PROP, aD as UidFactory, an as VersionEntry, ar as VisitActionObj, aA as VisitsByType, W as WorkerCommands, j as WorkerEvent, z as WorkerPayload, a6 as evmToPatch, l as fromJsonId, a_ as inflateOrmJson, aa as isActionOperation, v as isEvmPatch, aE as isUserCreated, aG as loadOrInitUidFactory, ab as packActionPatch, a2 as packPatch, a5 as patchToEvm, X as relationColName, a4 as resolveLayout, b3 as scalarProperties, aZ as serializeMapOfMaps, aY as serializeMapOfSets, aJ as setDefaultLanguage, aK as setDefaultProvenance, aL as setLoadAiSidecars, ax as subscribeStats, t as toJsonId, ac as unpackActionPatch, a3 as unpackPatch } from '../orm-MJTHCG9E.js';
+export { C as COIN_LEDGER_POST_TITLE_PREFIX, L as LevelState, P as POINTS_PER_LEVEL, a as POINTS_PER_SILVER_COIN, S as SILVER_COINS_PER_LEVEL, g as getLevel, s as subscribeLevel } from '../level-state-DXqglpAX.js';
+import { T as Tag, B as Book, e as BookInput, D as TagInput, o as PersonInput } from '../Book-K86JRm42.js';
+export { a as BOOK_PROP_IDS, c as BookExtendedCols, k as BookInstance, d as BookProvCols, b as BookSlimCols, N as NewBookWithId, x as NewPersonWithId, K as NewTagWithId, P as PERSON_PROP_IDS, w as Person, m as PersonExtendedCols, n as PersonProvCols, l as PersonSlimCols, y as TAG_PROP_IDS, A as TagExtendedCols, C as TagProvCols, z as TagSlimCols, h as deserializeBookExtended, j as deserializeBookProv, f as deserializeBookSlim, t as deserializePersonExtended, v as deserializePersonProv, q as deserializePersonSlim, H as deserializeTagExtended, J as deserializeTagProv, F as deserializeTagSlim, g as serializeBookExtended, i as serializeBookProv, s as serializeBookSlim, r as serializePersonExtended, u as serializePersonProv, p as serializePersonSlim, G as serializeTagExtended, I as serializeTagProv, E as serializeTagSlim } from '../Book-K86JRm42.js';
+export { A as AiResultEntry, b as ColumnData, C as ColumnType, I as InstanceFieldSpec, P as ParsedSidecar, a as SIDECAR_FORMAT_VERSION, S as SIDECAR_MAGIC, g as SidecarColumn, d as SidecarHeader, j as SidecarInput, h as SidecarRelationInput, e as colsFromSidecar, c as columnTypeForBits, k as deserializeAiSidecar, f as extractRecordCols, i as instanceSpecFromFields, p as parseSidecar, s as serializeAiSidecar, w as writeSidecar } from '../enriched-index-T0sDG7JR.js';
+export { A as AiResultsMap, o as BOOK_CURATABLE_PRESETS, p as BOOK_FIELD_WEIGHTS, n as BOOK_SEARCH_SCHEMA, B as BookSearchLangState, D as BookSearchService, t as BookSearchSource, z as BookSearchStatus, P as PresetFilter, c as SEARCH_SHARD_FORMAT_VERSION, b as SEARCH_SHARD_MAGIC, g as SearchDocInput, S as SearchFilters, x as SearchHit, y as SearchIndex, w as SearchIndexOptions, d as SearchPresetKind, e as SearchPresetSpec, v as SearchQuery, a as SearchResult, j as SearchShard, i as SearchShardPreset, h as SearchShardRelation, f as SearchShardSchema, F as bookSearch, u as bookSearchDoc, q as bookSearchPresets, C as bookSearchSourceFromRecord, l as buildSearchShard, k as compareBigint, m as deserializeSearchShard, E as expandTopics, r as latestAiValue, s as serializeSearchShard } from '../bookSearchService-BmFHrvsv.js';
 import '@the_library/db_schemas/enums';
-import '@the_library/standard-adapters/isni';
-import '@the_library/standard-adapters/orcid';
 import '@the_library/standard-adapters/lcc';
 import '@the_library/standard-adapters/ddc';
 import '@the_library/standard-adapters/udc';
@@ -13,6 +15,8 @@ import '@the_library/standard-adapters/bbk';
 import '@the_library/standard-adapters/tlc';
 import '@the_library/standard-adapters/cc';
 import '@the_library/standard-adapters/isbn';
+import '@the_library/standard-adapters/isni';
+import '@the_library/standard-adapters/orcid';
 
 /** The compiled layout dictionary shipped with @the_library/db_schemas. */
 declare const versionsFile: VersionsFile;
@@ -45,13 +49,14 @@ declare class LruCache<K, V> {
     limit: number;
     private map;
     private _pinned;
+    private pinReasons;
     private _warnedOverflow;
     constructor(limit: number);
     get size(): number;
     get(key: K): V | undefined;
     set(key: K, val: V): void;
-    pin(key: K): void;
-    unpin(key: K): void;
+    pin(key: K, reason?: string): void;
+    unpin(key: K, reason?: string): void;
     has(key: K): boolean;
     delete(key: K): void;
     clear(): void;
@@ -64,7 +69,12 @@ declare const configureDb: (opts: {
 }) => void;
 declare const clear: () => void;
 declare const dump: () => Map<number, LruCache<string, any>>;
-declare function getRecordKey(wireId: number, creatorUsername?: string): string;
+declare function setDefaultCreatorUsername(username: string | undefined): void;
+/** Current ambient default, so a caller that temporarily overrides it (e.g.
+ *  hydrateAll()) can restore the previous value afterward instead of
+ *  clobbering a session-wide default a host app already set. */
+declare function getDefaultCreatorUsername(): string | undefined;
+declare function getRecordKey(wireId: uid, creatorUsername?: string): string;
 declare const hasRecord: (objectType: number, id: uid, creatorUsername?: string) => boolean;
 /** Synchronous read. Throws on LRU miss — use the model's LoadAsync for re-hydration. */
 declare const getRecord: (objectType: number, id: uid, creatorUsername?: string) => any;
@@ -72,8 +82,32 @@ declare const addRecord: (objectType: number, obj: {
     id: uid;
 }, creatorUsername?: string) => void;
 declare const removeRecord: (objectType: number, id: uid, creatorUsername?: string) => void;
-declare const pinRecord: (objectType: number, id: uid, creatorUsername?: string) => void;
-declare const unpinRecord: (objectType: number, id: uid, creatorUsername?: string) => void;
+declare const pinRecord: (objectType: number, id: uid, creatorUsername?: string, reason?: string) => void;
+/**
+ * Resolve a batch of ids to records, re-hydrating any that were evicted from
+ * the LRU cache instead of treating a `Has() === false` miss as nonexistence
+ * (SPEC §2.5 — eviction is not deletion). A `.catch()` on each `LoadAsync`
+ * isolates a genuinely-missing/stale id so it can't fail the whole batch; the
+ * `Has()` re-check after hydration drops exactly those ids before the
+ * synchronous `Load()` (which throws on a still-absent id).
+ *
+ * Shared by every generated relation-object getter and index-query method —
+ * the single place this pattern is implemented.
+ */
+type LoadAsyncCapable<T = any> = {
+    Has(id: uid): boolean;
+    Load(id: uid): T;
+    LoadAsync(id: uid): Promise<T>;
+};
+declare function loadManyAsync<T>(ModelClass: LoadAsyncCapable<T>, ids: uid[]): Promise<T[]>;
+/**
+ * Resolve a single id to a record, re-hydrating it if it was evicted from the
+ * LRU cache. Returns null when the record cannot be resolved.
+ */
+declare function loadOneAsync<T>(ModelClass: LoadAsyncCapable<T>, id: uid): Promise<T | null>;
+declare function registerModelClass(objectType: number, cls: LoadAsyncCapable): void;
+declare function getModelClass(objectType: number): LoadAsyncCapable | undefined;
+declare const unpinRecord: (objectType: number, id: uid, creatorUsername?: string, reason?: string) => void;
 
 declare const inceptionDate: number;
 declare const DateUtils: {
@@ -110,9 +144,28 @@ declare const proResolver: <A>() => ProResolver<A>;
  * with the result of the ultimate single execution.
  */
 declare function debouncePromise<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+type SyncStatus = 'idle' | 'pending' | 'error';
 declare class Patches {
     username: string;
     protected _patches: Array<QueueItem>;
+    private pendingPins;
+    private pendingEvents;
+    private authorshipListeners;
+    private syncStatusListeners;
+    private activeSync?;
+    private _syncStatus;
+    private _retryAttempt;
+    private _retryTimer;
+    private static readonly MAX_SYNC_RETRIES;
+    private static readonly SYNC_RETRY_BASE_MS;
+    /** Durable/pending/error state of the last sync() attempt — for UI (e.g. a save indicator). */
+    get syncStatus(): SyncStatus;
+    private setSyncStatus;
+    /** Subscribe to syncStatus transitions. Returns an unsubscribe function. */
+    onSyncStatus(listener: (status: SyncStatus) => void): () => void;
+    /** Capture optimistic edits while a cache-miss request is in flight. */
+    observePending(listener: (op: QueueItem) => void): () => void;
+    private releasePins;
     protected thread: IThread;
     static _replaying: boolean;
     get patches(): Array<QueueItem>;
@@ -124,6 +177,18 @@ declare class Patches {
     static setReplay(replay: boolean): void;
     /** Drops all queued (not yet persisted) patches. Test/reset helper. */
     clearQueue(): void;
+    private cancelRetry;
+    /**
+     * Retries a failed sync automatically instead of waiting for the next
+     * edit to trigger one — a queue that fails while nothing else is being
+     * edited would otherwise sit on unsent data indefinitely. Calls the raw
+     * (undebounced) prototype method directly: `this.sync` is the debounced
+     * wrapper `initThread` installs, and calling that here would let a
+     * steady stream of incoming edits keep pushing the retry itself further
+     * out — compounding the exact "can be indefinitely postponed" problem
+     * this is fixing, instead of fixing it.
+     */
+    private scheduleRetry;
     addPatch(op: QueueItem): void;
     /**
      * Last-Writer-Wins consolidation. Walks the queue from the newest entry
@@ -139,21 +204,42 @@ declare class Patches {
      * Syncs the queued patches to the worker (IndexedDB persistence).
      * Before initThread, patches are retained in the queue (never dropped);
      * initThread flushes them as soon as the worker is available.
+     *
+     * A failed attempt schedules its own retry (see scheduleRetry) instead of
+     * only relying on the next edit to trigger one — a queue that fails while
+     * the user makes no further edits would otherwise sit on unsent,
+     * non-durable data indefinitely.
      */
     sync(): Promise<any>;
+    private persistQueued;
+    static contributionScore(data: Array<QueueItem>): number;
     static calculateLevel(username: string): Promise<number>;
 }
 declare const PatchInstance: Patches;
+/**
+ * Translates a local analytics op to its EVM wire form. Returns null for
+ * VisitPart — the 4-bit opcode nibble is fully exhausted (see ActionOperation's
+ * warning comment in patchCodecs.ts) and VisitPart lost the draw, so it stays
+ * local-only, same as every ActionTypes op was before this.
+ */
+declare const localOpToActionPatch: (op: LocalOp) => AnyActionPatch | null;
+/** Reverses localOpToActionPatch, for restored patches landing back in IndexedDB. */
+declare const actionPatchToLocalOp: (patch: AnyActionPatch) => LocalOp;
 /**
  * Restores patches received from the blockchain into IndexedDB.
  * Decoding is layout-driven: the payload's `version` selects the codec
  * layout from versions.json (delta-merged via resolveLayout).
  */
-declare const deserializePatches: (username: string, payload: EvmPayload) => Promise<void>;
-/**
- * Serializes locally stored EVM-bound patches into the BackupStorage.sol
- * payload format. Local analytics ops (ActionTypes) are skipped.
- */
+interface PatchSource {
+    /** Stable deployment/account stream identity, supplied by the chain reader. */
+    streamId: string;
+    /** Absolute wire-word position of the first item in this payload. */
+    fromIndex: number;
+}
+declare const deserializePatches: (username: string, payload: EvmPayload, source?: PatchSource) => Promise<void>;
+/** Encode a captured source window. Compaction never changes its acknowledgement boundary. */
+declare const serializePatchRows: (rows: Array<QueueItem>) => EvmPayload;
+/** Exclusive saved-through / inclusive captured-through sequence window. */
 declare const serializePatches: (fromIndex: number, toIndex: number) => Promise<EvmPayload>;
 declare const getPatchInstanceByAccount: (account: string) => Patches;
 
@@ -174,9 +260,8 @@ declare const getPatchInstanceByAccount: (account: string) => Patches;
  * Local analytics ops carry no object edit and are ignored here (they feed the
  * stats store on boot).
  *
- * `setReplay(true)` brackets the loop so no apply is mistaken for user
- * authoring (defensive: `record.patch()` does not itself queue, but inverse
- * propagation and future code paths might).
+ * Replay uses non-emitting application methods. No global flag is held across
+ * asynchronous hydration or IndexedDB work: concurrent setters still persist.
  *
  * Idempotent: re-applying the same ops converges to the same state
  * (`patch()` is a last-writer-wins assignment / Set add-remove).
@@ -190,7 +275,7 @@ declare const applyRestoredPatches: (ops: Array<AnyPatch>, creatorUsername?: str
 
 interface TrashStore {
     /** Merge ids across a set of usernames. Empty array (default) = every known username. */
-    list(objectType: number, usernames?: string[]): number[];
+    list(objectType: number, usernames?: string[]): uid[];
     count(objectType: number, usernames?: string[]): number;
     /** Usernames currently bucketed for this objectType (e.g. to populate a picker). */
     usernames(objectType: number): string[];
@@ -211,7 +296,64 @@ declare function scanTrash(): void;
 declare function _resetForTest(): void;
 declare const trashStore: TrashStore;
 
-declare const version = 4;
+interface Trashable {
+    deleted: boolean;
+    safe: boolean;
+}
+type TreeNode = Tag | Book;
+declare function isIndependentlyTrashed(record: Trashable): boolean;
+/** Inverse of trash.ts's `isTrashed` OR — clears both possible causes. */
+declare function untrashRecord(record: Trashable): void;
+/**
+ * Freezes a record's current (inherited) hidden state as its own trash entry.
+ * No-op if the record already carries independent flags — pinning something
+ * already independently trashed would be redundant.
+ */
+declare function pinAsTrashed(record: Trashable): void;
+declare function childrenOf(node: TreeNode): Promise<TreeNode[]>;
+/**
+ * restore=false (default): pin `node` in place — it and everything below it
+ * stays exactly as hidden as it was, just via its own flag now instead of
+ * inheritance. restore=true: fully open `node` and keep walking down.
+ * Either way, a node that's already independently trashed is left alone and
+ * recursion stops there.
+ */
+declare function cascadeRestore(node: TreeNode, restore: boolean): Promise<void>;
+/**
+ * Given the mandatory restore path (the record being restored + every
+ * ancestor/container standing between it and visibility, ordered leaf to
+ * root), collects every sibling hanging off that path — at every level, plus
+ * the leaf's own children — that a restore would otherwise silently expose.
+ * The node one step closer to the leaf is excluded at each level (that's the
+ * path itself, not a "sibling").
+ */
+declare function buildCascadeCandidates(path: TreeNode[]): Promise<TreeNode[]>;
+/**
+ * Executes a complex restore from the UI selection.
+ * @param target The target item to restore.
+ * @param ancestors The required ancestors (highest deleted ancestor is last).
+ * @param selectedIds The set of string IDs that the user opted to restore.
+ * @param rootNode The node being used as the tree root (usually the highest deleted ancestor, or the target itself if destination was changed).
+ * @param applyDestinationChange Optional callback to apply reparenting if destination changed.
+ */
+declare function executeComplexRestore(target: Tag | Book, ancestors: Tag[], selectedIds: Set<string>, rootNode: Tag | Book, applyDestinationChange?: () => void): Promise<void>;
+/** Collect ancestors of tag up to Level 1 (tags with no inTags). */
+declare function collectAncestors(tag: Tag, visited?: Set<bigint>): Promise<Tag[]>;
+/**
+ * Ancestors of `tag`, stopping at (and excluding) the first ancestor that is
+ * not itself independently trashed. This — not the unfiltered
+ * `collectAncestors` above — is the correct input for a restore's mandatory
+ * path / `buildCascadeCandidates`: an ancestor that was never hiding
+ * anything has no "newly exposed" subtree, so walking past it and pinning
+ * *its* other children (via `cascadeRestore`) marks unrelated, never-trashed
+ * siblings as deleted as a side effect. `collectAncestors` stays as-is for
+ * display/breadcrumb callers that genuinely want the full chain to the root.
+ */
+declare function collectTrashedAncestors(tag: Tag, visited?: Set<bigint>): Promise<Tag[]>;
+/** Recursive count of every descendant tag under `tag` (not including itself). */
+declare function countRecursiveSubfolders(tag: Tag, visited?: Set<bigint>): Promise<number>;
+
+declare const version = 5;
 declare const dbName = "the_world_library";
 declare const patchStoreName = "patches";
 declare const jsonStoreName = "catalog_json";
@@ -241,4 +383,289 @@ declare const hasBookData: (fileId: string) => Promise<boolean>;
 declare const loadBookData: (fileId: string) => Promise<BookData | undefined>;
 declare const storeBookData: (record: BookData) => Promise<boolean>;
 
-export { AnyPatch, BookData, CURRENT_VERSION, ClearDbData, DSafeCheck, DateUtils, Db, EvmPayload, FileRecord, IThread, LruCache, PatchInstance, Patches, type ProResolver, QueueItem, type ReactivitySystem, type TrashStore, VersionLayout, VersionsFile, _resetForTest, addReactivitySystem, addRecord, applyRestoredPatches, clear, configureDb, currentLayout, dbName, dbReactivity, debouncePromise, delay, deserializePatches, deviceStateStoreName, dump, fileStore, getPatchInstanceByAccount, getRecord, getRecordKey, hasBookData, hasFile, hasRecord, inceptionDate, instanceRemapsStoreName, jsonStoreName, keyValStoreName, loadBookData, loadFile, localRecordsStoreName, patchStoreName, pdfDataStoreName, pinRecord, proResolver, removeRecord, scanTrash, serializePatches, setReactivitySystem, storeBookData, storeFile, trashStore, uid, unpinRecord, version, versionsFile };
+interface LocalRecordEntry {
+    wireId: uid;
+    creatorUsername: string;
+    objectType: number;
+    createdAt: number;
+    status: 'active' | 'submitted' | 'community_pending' | 'canonical';
+    canonicalId?: number;
+}
+declare class LocalRecordTable {
+    private db;
+    instanceRemaps: IDBInstanceRemapStore;
+    constructor();
+    /** Called once at app startup, before any createNew() call — mirrors PatchInstance.initThread(). */
+    init(db: IDBDatabase): void;
+    get idb(): IDBDatabase;
+    put(entry: LocalRecordEntry): Promise<void>;
+    putIfAbsent(entry: LocalRecordEntry): Promise<void>;
+    get(creatorUsername: string, wireId: uid): Promise<LocalRecordEntry | undefined>;
+    getByCreator(creatorUsername: string): Promise<LocalRecordEntry[]>;
+    setStatus(creatorUsername: string, wireId: uid, status: LocalRecordEntry['status']): Promise<void>;
+    setCanonicalId(creatorUsername: string, wireId: uid, canonicalId: number): Promise<void>;
+}
+declare class IDBInstanceRemapStore {
+    private table;
+    constructor(table: LocalRecordTable);
+    get(objectId: uid, langId: number, creatorUsername: string, originalIndex: number): Promise<number | undefined>;
+    put(objectId: uid, langId: number, creatorUsername: string, originalIndex: number, realIndex: number): Promise<void>;
+}
+/** Module-level singleton — import and call directly from generated model files. */
+declare const localRecordTable: LocalRecordTable;
+
+declare function mergeBookTiers(slimBuf: ArrayBuffer, extBuf: ArrayBuffer, provBuf: ArrayBuffer): BookInput[];
+declare function mergeTagTiers(slimBuf: ArrayBuffer, extBuf: ArrayBuffer, provBuf: ArrayBuffer): TagInput[];
+declare function mergePersonTiers(slimBuf: ArrayBuffer, extBuf: ArrayBuffer, provBuf: ArrayBuffer): PersonInput[];
+
+declare class IndexDependencyNode {
+    readonly objectType: number;
+    readonly indexName: string;
+    readonly keyPath: string;
+    constructor(objectType: number, indexName: string, keyPath: string);
+}
+declare function classifyValue(classifier: any, value: any): any[];
+declare class ModelIndex {
+    readonly objectType: number;
+    readonly name: string;
+    readonly keys: string[];
+    readonly classifier?: any | undefined;
+    private langIndex;
+    private reverseMap;
+    private depNodes;
+    constructor(objectType: number, name: string, keys: string[], classifier?: any | undefined);
+    private getOrCreateDepNode;
+    /** Helper to traverse the index tree to add a UID */
+    private addToTree;
+    /** Helper to traverse the index tree to remove a UID */
+    private removeFromTree;
+    /**
+     * Trigger reactivity for a mutated key path: the exact-path node plus any
+     * existing nodes registered on its prefixes (partial-path queries such as
+     * byNotationPrefix, and getAvailableKeys/getAvailableRawValues listeners).
+     * Prefix nodes are only triggered when they already exist — a node is only
+     * created by a query, so a missing node has no subscribers.
+     */
+    private triggerPath;
+    /** Ingestion/mutation tracking via raw values (used during sidecar boot) */
+    trackRaw(id: uid, lang: Lang, rawValues: any[]): void;
+    /** Ingestion/mutation tracking via Orm record instance */
+    trackRecord(record: Orm, lang: Lang): void;
+    /** Untrack record (used on deletion) */
+    untrack(id: uid, lang: Lang): void;
+    /** Languages under which this uid currently has an index entry. */
+    getTrackedLangs(id: uid): Lang[];
+    /** Query UIDs by resolved composite key path */
+    getUids(keysPath: any[], lang: Lang): Set<uid>;
+    /** Query UIDs by raw string value (runs the classifier if present) */
+    getUidsByRawValue(value: any, lang: Lang): Set<uid>;
+    /** Get available sub-keys under a partial path prefix */
+    getAvailableKeys(prefixPath: any[], lang: Lang): string[];
+    /** Get all raw top-level values currently indexed (e.g. including partition prefix if classified) */
+    getAvailableRawValues(lang: Lang): string[];
+}
+declare class IndexRegistryClass {
+    private indexes;
+    registerIndex(objectType: number, index: ModelIndex): void;
+    getIndex(objectType: number, name: string): ModelIndex;
+    hasIndexForProperty(objectType: number, propId: number): boolean;
+    /**
+     * Manually (re-)index a fully populated record across its loaded languages.
+     * NOT called from db.addRecord — records self-register before their values
+     * are merged, so hooking ingestion would index empty keys. Normal feeds are
+     * bootstrapSidecars (boot) and updateIndex via Orm.patch (mutations).
+     */
+    trackRecord(objectType: number, record: Orm): void;
+    /**
+     * Intercept individual property patches to update index tree paths.
+     *
+     * Re-tracks every language the record participates in, not just the
+     * patch's language: a lang-agnostic edit (langId 0) changes the resolved
+     * value for *every* language via the ORM fallback chain (exact → agnostic
+     * → single-value), and queries always read a concrete-language bucket.
+     */
+    updateIndex(objectType: number, propId: number, record: Orm): void;
+    /** Get available raw string keys loaded in this index for the given language */
+    getAvailableRawValues(objectType: number, name: string, lang: Lang): string[];
+    /** Bootstrap all registered indexes directly from parsed sidecar columns */
+    bootstrapSidecars(sets: any[]): void;
+    clear(): void;
+}
+declare const IndexRegistry: IndexRegistryClass;
+
+/**
+ * Recursively calculates the total number of unique books in a topic and all its subtopics.
+ * Yields to the event loop periodically to avoid blocking the main thread (Background Worker Aggregation).
+ */
+declare function calculateTopicBookCount(tagId: bigint): Promise<number>;
+
+interface NewSubscriptionsClient {
+    getNewSubscriptionsSince(targetUserId: number, since: number): Promise<number[]>;
+    countNewSubscriptionsSince(targetUserId: number, since: number): Promise<number>;
+}
+interface UsernameResolver {
+    userIdToUsername(userId: number): Promise<string>;
+}
+interface RelationshipSubscriptionOptions {
+    targetUserId: number;
+    indexer: NewSubscriptionsClient;
+    usernameResolver: UsernameResolver;
+    /** Polling interval in milliseconds when online (default: 30_000). */
+    pollIntervalMs?: number;
+    /** Optional key for persisting the last-read timestamp in localStorage. */
+    cursorKey?: string;
+}
+interface NewSubscription {
+    userId: number;
+    username: string | null;
+    timestamp: number;
+}
+type NewSubscriptionHandler = (subscriptions: NewSubscription[]) => void | Promise<void>;
+/**
+ * ORM-native subscription helper for the on-chain relationship indexer.
+ *
+ * Instead of polling per object or per tag, the targeted user makes a single
+ * RPC call: `getNewSubscriptionsSince(timestamp)`. The contract returns the
+ * userIds of everyone who interacted with that user's content since the cursor.
+ * This class resolves those userIds to usernames, persists the cursor for
+ * offline catch-up, and emits one event per batch.
+ */
+declare class RelationshipSubscription {
+    private targetUserId;
+    private indexer;
+    private usernameResolver;
+    private pollIntervalMs;
+    private cursorKey;
+    private handlers;
+    private timer;
+    private isPolling;
+    private inMemorySince;
+    private inMemoryDelivered;
+    constructor(opts: RelationshipSubscriptionOptions);
+    onSubscriptions(handler: NewSubscriptionHandler): () => void;
+    start(): void;
+    stop(): void;
+    getLastSeenTimestamp(): number;
+    private readSince;
+    private writeSince;
+    private deliveredKey;
+    private readDelivered;
+    private writeDelivered;
+    /**
+     * Guarded against overlapping polls ON THIS INSTANCE: this does sequential
+     * async work (an RPC call, then a per-actor username-resolution loop)
+     * before ever touching the handlers. Without the guard, a poll slow enough
+     * to still be in flight when the next setInterval tick fires — or a
+     * manually triggered poll() racing the timer — would let two polls both
+     * read the same cursor before either writes it back. A later,
+     * non-overlapping poll() is unaffected: the guard always releases in
+     * `finally`, including when the indexer call throws.
+     *
+     * Two more things this guards against that a same-instance flag alone
+     * can't:
+     *
+     * 1. Cross-instance double-delivery (e.g. two open browser tabs sharing one
+     *    cursorKey): the cursor is a wall-clock timestamp, not an ordered chain
+     *    position, so `since` alone can't tell two concurrent pollers "the
+     *    other one already claimed this batch." `readDelivered()`/
+     *    `writeDelivered()` add a small de-duplication record (just the most
+     *    recently delivered actorIds, not an ever-growing history — since
+     *    `since` only ever advances, a well-behaved indexer stops returning an
+     *    old actorId once `since` passes its timestamp, so remembering only the
+     *    latest batch is enough to cover the narrow overlap window this
+     *    creates) that's re-read fresh AFTER the indexer call resolves — not
+     *    cached from before it — and written immediately, before the
+     *    async username-resolution/handler-dispatch step below. That ordering
+     *    is what lets a second, concurrently-resolving poll() (own instance or
+     *    another tab sharing the same cursorKey) observe "already claimed" and
+     *    skip, instead of only finding out after the first poll fully finishes.
+     *
+     * 2. The cursor is advanced to when THIS request was dispatched, not when
+     *    it resolved. An interaction that lands on-chain while the RPC is still
+     *    in flight has a timestamp before "now at completion" but the query
+     *    that's already in flight can't have asked about it — a
+     *    completion-time cursor would skip it forever once persisted. A
+     *    dispatch-time cursor instead makes the next poll's window
+     *    conservative (it may re-ask about a narrow already-covered slice),
+     *    which `readDelivered()` exists to de-duplicate.
+     */
+    poll(): Promise<void>;
+}
+
+type ReplayDelivery = AnyPatch & {
+    username?: string;
+    creatorUsername?: string;
+};
+/**
+ * The ONE shared mutation path for applying an ordered batch of patches to a
+ * detached (uncached, no reactivity, no lifecycle side effects) `Orm`
+ * instance. Both the worker's LRU-eviction rehydration
+ * (`worker/libs/reconstructRecord.ts`) and the corpus baker
+ * (`@the_library/corpus-builder`'s `apply-patches-plain.ts`) call this
+ * instead of maintaining their own copies of patch-application logic — see
+ * reviews/2026-09-07/assessment.md's "Architectural direction" section,
+ * which specifically named this kind of duplication ("one logical edit
+ * currently acquires subtly different meanings in the setter, queue
+ * compactor, IDB deduplicator, restore loop, cache reloader, Node baker, and
+ * contract transport") as the root cause of several P1 findings, including
+ * #5 (the baker not implementing every patch operation) and the
+ * instance-collision bug documented in
+ * reviews/2026-09-07/implementation-p1-5-through-p1-6.md.
+ *
+ * This function does NOT reimplement mutation semantics — it delegates every
+ * actual state change to `applyPatchWithContext` (patchContext.ts), which is
+ * the same function the live subscription-sync/replay path already used.
+ * What this function DOES own is the orchestration `applyPatchWithContext`
+ * needs but a caller-supplied `Orm` instance can't provide on its own:
+ *
+ *  - `own`/`author`: a detached record has no ambient "which record/which
+ *    user session is this" context the way a live cached record does, so
+ *    every patch must be explicitly checked against the target record's
+ *    identity, and grouped by author, before being applied.
+ *  - `batchRemainder`: `resolveAddInstanceConflict` (patchContext.ts) needs
+ *    to see the field edits that follow an `AddInstance` in the SAME
+ *    author's stream to compare the incoming edition against existing slots
+ *    — this slices exactly that lookahead per patch, scoped to patches for
+ *    the same record from the same author (a different author's patches
+ *    interleaved in the same `input` array must not be mistaken for fields
+ *    of this AddInstance).
+ *  - `instanceRemapStore`: `applyPatchWithContext` expects an async
+ *    key-value interface (matching the live app's IndexedDB-backed store —
+ *    see patchContext.ts's `InstanceRemapStore`), but a detached `Orm`
+ *    instance only has `record.instanceRemaps`, a plain array (chosen so it
+ *    round-trips through `JSON.stringify` for persistence — see orm.ts's
+ *    `instanceRemaps` field doc). This wraps that array in a `Map` for O(1)
+ *    lookup during this call, and — critically — writes the accumulated
+ *    result back onto `record.instanceRemaps` at the end, so whichever
+ *    caller persists the record afterward (the baker writing
+ *    `_instanceRemaps` back onto the plain corpus object, or the worker
+ *    keeping the reconstructed record) carries any NEW remap forward.
+ *    Without that final write-back, a remap created during this call would
+ *    exist only for the duration of this function and be lost the moment it
+ *    returned — silently reopening the exact "remap lost after binary
+ *    bake/reload" bug the regression suite guards against.
+ */
+declare function applyDetachedPatches(record: Orm, input: ReplayDelivery[]): Promise<void>;
+
+/**
+ * Word splitter shared by the search-tier builder (corpus-builder, Node) and
+ * the query engine (browser) — next/metadata_search.md §5. Index and query can
+ * only agree if both sides run this exact function, so it must stay
+ * deterministic across runtimes: no Intl.Segmenter (its dictionary
+ * segmentation follows the ICU version), no locale-dependent lowercasing.
+ * Changing its output changes every published shard — bump
+ * SEARCH_SHARD_FORMAT_VERSION when it does.
+ */
+/** Longest word kept; longer runs are cut, not dropped. */
+declare const MAX_TOKEN_LENGTH = 40;
+/** é → e, Ä → a; recomposes Hangul and keeps Indic vowel signs (they aren't accents). */
+declare function normalizeText(text: string): string;
+/** Split `text` into index/query tokens, in order (duplicates kept — callers count tf). */
+declare function tokenize(text: string | null | undefined): string[];
+
+/** Opt-in publisher delivery. Worker patch commits read this flag in their own transaction. */
+declare function enablePublisherOutbox(): Promise<void>;
+declare function getPublisherOutbox(): Promise<QueueItem[]>;
+declare function acknowledgePublisherOutbox(ids: string[]): Promise<void>;
+
+export { AnyActionPatch, AnyPatch, Book, BookData, BookInput, CURRENT_VERSION, ClearDbData, DSafeCheck, DateUtils, Db, EvmPayload, FileRecord, IDBInstanceRemapStore, IThread, IndexDependencyNode, IndexRegistry, IndexRegistryClass, Lang, type LoadAsyncCapable, LocalOp, type LocalRecordEntry, LocalRecordTable, LruCache, MAX_TOKEN_LENGTH, ModelIndex, type NewSubscription, type NewSubscriptionHandler, type NewSubscriptionsClient, Orm, PatchInstance, type PatchSource, Patches, PersonInput, type ProResolver, QueueItem, type ReactivitySystem, RelationshipSubscription, type RelationshipSubscriptionOptions, type ReplayDelivery, type SyncStatus, Tag, TagInput, type TrashStore, type Trashable, type TreeNode, type UsernameResolver, VersionLayout, VersionsFile, _resetForTest, acknowledgePublisherOutbox, actionPatchToLocalOp, addReactivitySystem, addRecord, applyDetachedPatches, applyRestoredPatches, buildCascadeCandidates, calculateTopicBookCount, cascadeRestore, childrenOf, classifyValue, clear, collectAncestors, collectTrashedAncestors, configureDb, countRecursiveSubfolders, currentLayout, dbName, dbReactivity, debouncePromise, delay, deserializePatches, deviceStateStoreName, dump, enablePublisherOutbox, executeComplexRestore, fileStore, getDefaultCreatorUsername, getModelClass, getPatchInstanceByAccount, getPublisherOutbox, getRecord, getRecordKey, hasBookData, hasFile, hasRecord, inceptionDate, instanceRemapsStoreName, isIndependentlyTrashed, jsonStoreName, keyValStoreName, loadBookData, loadFile, loadManyAsync, loadOneAsync, localOpToActionPatch, localRecordTable, localRecordsStoreName, mergeBookTiers, mergePersonTiers, mergeTagTiers, normalizeText, patchStoreName, pdfDataStoreName, pinAsTrashed, pinRecord, proResolver, registerModelClass, removeRecord, scanTrash, serializePatchRows, serializePatches, setDefaultCreatorUsername, setReactivitySystem, storeBookData, storeFile, tokenize, trashStore, uid, unpinRecord, untrashRecord, version, versionsFile };