@bitcobblers/wod-wiki-storage 0.0.0-stage → 0.35.2115

package/dist/wire-C7ZtlBKe.d.cts

@@ -0,0 +1,489 @@
+import { ScriptBlock, EventRecord, FieldCatalogEntry, FieldSourceRecord, FieldValueRecord, CatalogBackfillState } from '@bitcobblers/wod-wiki-core';
+import { IEffort } from '@bitcobblers/wod-wiki-lang';
+
+/**
+ * Storage Types — V4 Multi-Source Data Lens
+ *
+ * Defines the data model for the hierarchical IndexedDB storage.
+ * V4 replaces the old scripts + section_history stores with a unified
+ * `segments` store and adds `attachments` + `analytics` stores.
+ *
+ * Canonical home of the entity model (moved verbatim from
+ * apps/playground/src/types/storage.ts).
+ */
+
+type SegmentDataType = 'script' | 'youtube' | 'markdown' | 'header' | 'frontmatter' | 'wod' | 'title' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+/**
+ * Note: the slim V11 container. Identity + routing + grouping only.
+ * Content lives in `segments` (ordered by position, reconstructed at read);
+ * journal grouping lives on the `page` store via pageId; tags live in
+ * `tags`/`note_tags`. Legacy fields (rawContent, segmentIds, journalDate,
+ * clonedIds, createdFrom, updatedAt, targetDate, templateId) were removed in
+ * V11 — see indexeddb-storage-and-page-queries.md.
+ */
+type NoteKind = 'journal' | 'template' | 'playground' | 'feed' | 'dashboard' | 'page' | (string & {});
+interface Note {
+    id: string;
+    title: string;
+    /** Domain date of the record (e.g. workout date, publish date) */
+    date?: number;
+    createdAt: number;
+    tags?: string[];
+    type?: NoteKind;
+    /** N-10 — the note this one was created from (template/collection source).
+     *  Renamed from templateId. */
+    sourceId?: string;
+    /** Catalog id for static notes (the directory under markdown/collections
+     *  or markdown/feeds, with the `feeds/` wrapper stripped). Synthesised by
+     *  QueryService.staticNotesFromBlocks; undefined for journal notes. */
+    catalog?: string;
+    /** Set on rows the Seed Import owns. Absent ≡ user-owned: the importer
+     *  only ever overwrites or deletes rows with seedOrigin === 'seed'. The
+     *  edit path flips this to 'user' on first user change (phase 3). */
+    seedOrigin?: 'seed' | 'user';
+    /** manifest.version of the last seed write (seed rows only). */
+    seedVersion?: number;
+    /** The seed chunk this row came from (seed rows only). */
+    seedChunkId?: string;
+    /** Original seed file path (e.g. `markdown/collections/girls/fran.md`) — the
+     *  deterministic UUID is derived from this path; retained for seed content
+     *  reconstruction (canvas routes, collection READMEs, block-index lookup). */
+    sourcePath?: string;
+}
+/**
+ * Page: a grouped collection of notes. Two flavors:
+ *   - calendar page: `date` set (YYYY-MM-DD) — one per journal date.
+ *   - custom page: `slug` set — name/slug lookup for grouped collections.
+ */
+interface Page {
+    id: string;
+    date?: string;
+    slug?: string;
+    title?: string;
+    createdAt: number;
+}
+interface PageNote {
+    id: string;
+    pageId: string;
+    noteId: string;
+    position?: number;
+    createdAt: number;
+}
+type TagType = 'template' | 'playground' | 'qualification' | 'notebook' | 'general' | (string & {});
+interface TagTypeRecord {
+    id: string;
+    name: string;
+    label: string;
+    color?: string;
+    createdAt: number;
+}
+interface Tag {
+    id: string;
+    label: string;
+    type?: TagType;
+    createdAt: number;
+}
+interface NoteTag {
+    id: string;
+    noteId: string;
+    tagId: string;
+}
+/**
+ * NoteSegment: A versioned chunk of note content.
+ * The compound key is [id, version] so every edit creates a new row.
+ */
+interface NoteSegment {
+    id: string;
+    version: number;
+    noteId: string;
+    /** V11 — ordinal within the parent note (document order). Backfilled from
+     *  the removed note.segmentIds array. */
+    position?: number;
+    /** @deprecated V10 legacy placement field. Placements are owned exclusively by `page_notes`. */
+    pageId?: string;
+    dataType: SegmentDataType;
+    data: ScriptBlock | null;
+    rawContent: string;
+    /** Exact document fragment, including its following line separator. Absent on legacy rows. */
+    sourceContent?: string;
+    createdAt: number;
+    /** V10 — last time this incarnation was touched (defaults to createdAt). */
+    updatedAt?: number;
+    /** V10 — true for superseded versions; false for the latest per id. */
+    isHistory?: boolean;
+}
+/**
+ * Derived projection of a NoteSegment into queryable block-index fields.
+ * Canonical source is the `segments` store; this store is disposable and can
+ * be rebuilt by backfillV14. One row per non-history segment.
+ */
+interface BlockIndexRow {
+    /** Composite key: `${noteId}:${segmentId}:${segmentVersion}` */
+    id: string;
+    noteId: string;
+    segmentId: string;
+    segmentVersion: number;
+    /** Ordinal within the parent note (document order). */
+    position?: number;
+    /** Segment data type: 'wod' | 'h1'..'h6' | 'markdown' | 'frontmatter'. */
+    dataType: string;
+    /** Content-stable identity for wod blocks (FNV-1a hash); undefined for prose. */
+    blockContentId?: string;
+    /** Searchable snippet — the segment's raw markdown text. */
+    rawContent: string;
+    /** Denormalized note title for display. */
+    noteTitle: string;
+    /** When the segment version was saved. */
+    createdAt: number;
+    /** True for bundled static content (collections, feeds); false for user journal. */
+    isStatic?: boolean;
+    /** Original source identifier for static files. */
+    sourceId?: string;
+    /** Full corpus source path (e.g. `markdown/collections/girls/fran.md`) —
+     *  the exact join key to `Note.sourcePath`. The seed importer maps
+     *  `noteId` to the imported note UUID through it; missing or ambiguous
+     *  mappings abort the import. */
+    sourcePath?: string;
+    /** Legacy route identity the compiler used before noteId became a real
+     *  note UUID (path stem, feed route, canvas route). Retained as route
+     *  sugar for deep links — never a storage join key. */
+    routeId?: string;
+}
+/**
+ * Relational junction linking blocks to the exercises they contain.
+ * Populated by `rebuildBlockIndexForNote` (user notes) and the seed compiler.
+ * Enables O(1) bidirectional lookups without scanning raw markdown.
+ */
+interface BlockEffort {
+    /** Compound key: `${noteId}:${segmentId}:${effortSlug}` or `static:${noteId}:${segmentId}:${effortSlug}` */
+    id: string;
+    /** Parent note UUID */
+    noteId: string;
+    /** Positional block ID within the note (NoteSegment.id) */
+    blockId: string;
+    /** Content-stable hash of the block (SHA-256/FNV-1a) */
+    blockContentId?: string;
+    /** Canonical exercise slug (e.g. 'thruster', 'pull-up', 'clean-and-jerk') */
+    effortSlug: string;
+    /** True for bundled static content (collections, feeds); false for user journal. */
+    isStatic?: boolean;
+    /** Full corpus source path of the containing block's file — the seed
+     *  importer maps `noteId` to the imported note UUID through it. */
+    sourcePath?: string;
+    /** When the row was saved. */
+    createdAt: number;
+}
+/**
+ * ResultOrigin: which app surface produced a Session / AnalyticsDataPoint.
+ * 'playground' rows are recorded and viewable but excluded from default
+ * journal/progress list filters. Absent on legacy rows — treated as 'journal'.
+ */
+type ResultOrigin = 'journal' | 'playground' | 'user';
+/**
+ * Session: A pure execution metadata record (renamed from Session; table results -> sessions in DB V20, flattened in V21).
+ * Statements and metrics stream directly to `EventRecord` rows in the `events` table.
+ */
+interface Session {
+    id: string;
+    /** Positional identity — FK to NoteSegment.id (the section id of the block run). */
+    segmentId?: string;
+    /** Version of the NoteSegment at record time. Undefined on legacy rows. */
+    segmentVersion?: number;
+    noteId: string;
+    /** Section position identity — which block in the note this result belongs to. */
+    blockId?: string;
+    /** Content-stable identity — hash of the fenced content at recording time. */
+    blockContentId?: string;
+    /** LEGACY — content generation from the retired computeVersion() path.
+     *  New rows carry segmentVersion instead; retained for pre-existing rows. */
+    version?: number;
+    /** Which surface produced this result; default filters exclude 'playground'. */
+    origin?: ResultOrigin;
+    /** Write-path lifecycle (unified event store): row born 'in-progress' at
+     *  workout start, flipped to 'completed' at finalize. Absent = 'completed'
+     *  (legacy rows predate streaming). */
+    status?: 'in-progress' | 'completed';
+    /** @deprecated V10 legacy placement field. Note placements are owned exclusively by `page_notes`. */
+    pageId?: string;
+    /** When workout started */
+    startTime: number;
+    /** When workout ended */
+    endTime: number;
+    /** Total elapsed time (ms) */
+    duration: number;
+    /** Rounds completed (for rounds-based workouts) */
+    roundsCompleted?: number;
+    /** Total rounds (for rounds-based workouts) */
+    totalRounds?: number;
+    /** Reps completed (for rep-based workouts) */
+    repsCompleted?: number;
+    /** Whether workout was completed or stopped early */
+    completed: boolean;
+    createdAt: number;
+}
+/**
+ * Attachment: Temporal blob data attached to a workout (HR, GPS, etc.).
+ */
+interface Attachment {
+    id: string;
+    noteId: string;
+    /** @deprecated V10 legacy placement field. Note placements are owned exclusively by `page_notes`. */
+    pageId?: string;
+    /** V10 — the Session this blob belongs to, when known. */
+    resultId?: string;
+    mimeType: string;
+    label: string;
+    data: ArrayBuffer | string;
+    timeSpan: {
+        start: number;
+        end: number;
+    };
+    createdAt: number;
+}
+
+/**
+ * Membership: the account/profile row behind user-owned records. In
+ * IndexedDB mode there is exactly one membership (id DEFAULT_MEMBERSHIP_ID)
+ * and its source of truth is localStorage — this store exists for schema
+ * parity and API mode, where the server keeps the membership table (and
+ * wipe() must never destroy it — StoreDef.system). Body metrics are stored
+ * as entered (unit-tagged, no normalization); age is derived from birthDate
+ * at display time.
+ */
+interface Membership {
+    id: string;
+    displayName: string;
+    /** Profile picture: client-resized JPEG data URL (≤256px, ~tens of KB). */
+    picture?: string;
+    weight?: number;
+    weightUnit?: 'kg' | 'lb';
+    height?: number;
+    heightUnit?: 'cm' | 'in';
+    /** ISO date (YYYY-MM-DD). */
+    birthDate?: string;
+    createdAt: number;
+    updatedAt?: number;
+}
+
+declare const DOMAIN_PROJECTION_VERSION = 1;
+type DomainPredicate = {
+    field: 'id' | 'noteId' | 'type' | 'catalog' | 'source' | 'tags' | 'effort';
+    values: string[];
+    negate?: boolean;
+} | {
+    field: 'text';
+    value: string;
+} | {
+    field: 'date';
+    start: number;
+    end: number;
+    endExclusive?: boolean;
+} | {
+    field: 'page';
+    value: boolean;
+} | {
+    field: 'defaultNotes';
+    feeds: boolean;
+} | {
+    field: 'sourceFence';
+};
+type DomainOrder = {
+    field: 'id' | 'createdAt' | 'date' | 'title' | 'noteTitle' | 'dataType' | 'position';
+    direction: 'asc' | 'desc';
+};
+type DomainQuery = {
+    plan: 'notes' | 'blocks' | 'entries';
+    selection?: DomainPredicate[];
+    filters?: DomainPredicate[];
+    order?: DomainOrder[];
+    offset?: number;
+    limit?: number;
+};
+interface DomainEntry {
+    note: Note;
+    segments: NoteSegment[];
+    tags: Tag[];
+    links: PageNote[];
+    pages: Page[];
+}
+type DomainQueryResult = {
+    projectionVersion: typeof DOMAIN_PROJECTION_VERSION;
+    selectedCount: number;
+    matchedCount: number;
+} & ({
+    plan: 'notes';
+    rows: Note[];
+} | {
+    plan: 'blocks';
+    rows: BlockIndexRow[];
+} | {
+    plan: 'entries';
+    rows: DomainEntry[];
+});
+declare function parseDomainQueryResult(value: unknown, plan: DomainQuery['plan']): DomainQueryResult;
+
+/**
+ * IStorage — backend-neutral storage contract (moved verbatim from
+ * apps/playground/src/services/storage/IStorage.ts). Implemented by
+ * IndexedDBStorage / InMemoryStorage in the app and ApiStorage here.
+ */
+
+interface StorageSchema {
+    notes: Note;
+    page: Page;
+    page_notes: PageNote;
+    tags: Tag;
+    tag_types: TagTypeRecord;
+    note_tags: NoteTag;
+    segments: NoteSegment;
+    sessions: Session;
+    attachments: Attachment;
+    events: EventRecord;
+    field_catalog: FieldCatalogEntry;
+    field_sources: FieldSourceRecord;
+    field_values: FieldValueRecord;
+    field_catalog_meta: CatalogBackfillState;
+    efforts: IEffort;
+    block_index: BlockIndexRow;
+    block_efforts: BlockEffort;
+    meta: unknown;
+    memberships: Membership;
+}
+type StoreName = keyof StorageSchema;
+type StoreType<K extends StoreName> = StorageSchema[K];
+interface IReadOnlyStore<T> {
+    get(key: IDBValidKey): Promise<T | undefined>;
+    getAll(query?: IDBValidKey | IDBKeyRange, count?: number): Promise<T[]>;
+    getAllFromIndex(indexName: string, query?: IDBValidKey | IDBKeyRange, count?: number): Promise<T[]>;
+    count(query?: IDBValidKey | IDBKeyRange): Promise<number>;
+    countFromIndex(indexName: string, query?: IDBValidKey | IDBKeyRange): Promise<number>;
+}
+interface IReadWriteStore<T> extends IReadOnlyStore<T> {
+    put(value: T, key?: IDBValidKey): Promise<IDBValidKey>;
+    delete(key: IDBValidKey | IDBKeyRange): Promise<void>;
+    clear(): Promise<void>;
+}
+interface IStorageTransaction {
+    readonly<K extends StoreName>(store: K): IReadOnlyStore<StoreType<K>>;
+    readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
+}
+interface IStorage {
+    queryDomain?(query: DomainQuery): Promise<DomainQueryResult | undefined>;
+    readonly<K extends StoreName>(store: K): IReadOnlyStore<StoreType<K>>;
+    readwrite<K extends StoreName>(store: K): IReadWriteStore<StoreType<K>>;
+    transaction<K extends StoreName, R>(stores: K[], mode: 'readonly' | 'readwrite', fn: (tx: IStorageTransaction) => Promise<R>): Promise<R>;
+    wipe(): Promise<void>;
+    close(): Promise<void>;
+}
+
+/**
+ * STORE_DEFS — runtime store/index spec for the wodwiki database, derived
+ * verbatim from IndexedDBStorage.open()'s upgrade callback (DB_VERSION 25,
+ * apps/playground/src/services/storage/IndexedDBStorage.ts). The API server
+ * builds its SQL schema from this spec.
+ *
+ * V25 adds the memberships store (system) and the by-user ownership index
+ * on every store that can hold user-created rows (see USER_OWNED_STORES in
+ * membership.ts — the ownership crosswalk).
+ *
+ * keyPath convention: array of property paths in key order. A single-element
+ * array is a simple (scalar) key; multiple elements form a compound key.
+ * Dotted paths ('baseAttributes.discipline') address nested properties.
+ */
+
+/**
+ * Shared IndexedDB schema version — the browser database opens at exactly
+ * this version (apps/playground/src/services/storage/IndexedDBStorage.ts
+ * imports it), so store/index drift between the app and this spec is a type
+ * error, not a runtime surprise. Bump on every store/index change and add
+ * the matching guarded upgrade step.
+ *
+ * 27 supersedes 26: real databases already upgraded to the first 26 cut
+ * (before by-source / by-created / the unique note-tag pair) exist in the
+ * wild, so "version 26" is ambiguous — 27's presence-guarded repairs bring
+ * every mixed DB to the same shape.
+ */
+declare const DB_VERSION = 28;
+/**
+ * Typed field metadata — column type per extracted field path, shared with
+ * the API so its SQL DDL derives DOUBLE PRECISION / INTEGER / BOOLEAN /
+ * TEXT from this table instead of a hardcoded per-index allowlist.
+ *
+ * Extraction rule (API side): a primary-key column `k<i>` takes the type of
+ * STORE_DEFS store's keyPath[i]; an index column `i_<index>_<part>` takes the
+ * type of that index's keyPath[part] here. Anything absent defaults to TEXT.
+ * Civil-date strings stay TEXT on purpose (page.date is 'YYYY-MM-DD');
+ * instants are epoch-ms numbers (notes.date, createdAt, timestamp).
+ */
+type StorageColumnType = 'number' | 'text' | 'boolean';
+declare const COLUMN_TYPES: Record<StoreName, Record<string, StorageColumnType>>;
+interface IndexDef {
+    name: string;
+    keyPath: string[];
+    unique?: boolean;
+    multiEntry?: boolean;
+}
+interface StoreDef {
+    name: StoreName;
+    keyPath: string[];
+    indexes: IndexDef[];
+    /** System stores survive wipe() (identity must not be reset with data). */
+    system?: boolean;
+}
+declare const STORE_DEFS: StoreDef[];
+
+/**
+ * Wire DTOs + key helpers shared by the storage client (ApiStorage) and the
+ * API server. Keys are scalars or scalar tuples (keyPath order); ranges bound
+ * them. Over HTTP, keys/ranges travel as urlencoded JSON query params.
+ *
+ * Range-typed helpers accept real IDBKeyRange instances AND plain RangeDTO
+ * literals — non-IDB runtimes (Bun, node, tests) have no IDBKeyRange global,
+ * so everything duck-types on field shape.
+ */
+
+type Scalar = string | number;
+/** Primary key: scalar for single-property keyPaths, tuple for compound. */
+type KeyDTO = Scalar | Scalar[];
+interface RangeDTO {
+    only?: KeyDTO;
+    /** Inclusive lower bound unless lowerOpen. Scalar or tuple (keyPath order). */
+    lower?: KeyDTO;
+    /** Inclusive upper bound unless upperOpen. Scalar or tuple (keyPath order). */
+    upper?: KeyDTO;
+    lowerOpen?: boolean;
+    upperOpen?: boolean;
+}
+type TxOp = {
+    op: 'put';
+    store: StoreName;
+    value: unknown;
+} | {
+    op: 'delete';
+    store: StoreName;
+    key: KeyDTO;
+} | {
+    op: 'clear';
+    store: StoreName;
+};
+/** Anything shaped like a range: real IDBKeyRange or a plain RangeDTO literal. */
+declare function isRange(arg: unknown): arg is RangeDTO;
+/** Reads one dotted property path ('a.b.c') off a row. */
+declare function extractKeyPart(value: unknown, dottedPath: string): Scalar | undefined;
+/** Extracts a row's primary key per the store's inline keyPath. */
+declare function keyFromValue(def: StoreDef, value: unknown): KeyDTO;
+/** Canonical url-safe string form of a key (also the buffer/tx match key). */
+declare function encodeKey(key: KeyDTO): string;
+/**
+ * Converts an IndexedDB query — bare key, IDBKeyRange, or an already-wire
+ * RangeDTO — to its wire form. Duck-types: objects with lower/upper/
+ * lowerOpen/upperOpen fields (real ranges or plain literals) pass through;
+ * scalars and tuple arrays become {only}.
+ */
+declare function rangeFromIDB(query?: IDBValidKey | IDBKeyRange | RangeDTO): RangeDTO | undefined;
+/** IndexedDB key ordering: numbers < strings < tuples; tuples lexicographic. */
+declare function compareKeys(a: KeyDTO, b: KeyDTO): number;
+/** True when a key matches a wire range (IDB bound semantics). */
+declare function keyInRange(key: KeyDTO, range: RangeDTO): boolean;
+
+export { type Attachment as A, type BlockEffort as B, COLUMN_TYPES as C, type DomainQuery as D, type TxOp as E, compareKeys as F, encodeKey as G, extractKeyPart as H, type IStorage as I, isRange as J, type KeyDTO as K, keyFromValue as L, type Membership as M, type Note as N, keyInRange as O, type Page as P, parseDomainQueryResult as Q, type RangeDTO as R, type StoreName as S, type Tag as T, rangeFromIDB as U, type StoreDef as a, type IReadOnlyStore as b, type StoreType as c, type IReadWriteStore as d, type DomainQueryResult as e, type IStorageTransaction as f, type BlockIndexRow as g, DB_VERSION as h, DOMAIN_PROJECTION_VERSION as i, type DomainEntry as j, type DomainOrder as k, type DomainPredicate as l, type IndexDef as m, type NoteKind as n, type NoteSegment as o, type NoteTag as p, type PageNote as q, type ResultOrigin as r, STORE_DEFS as s, type Scalar as t, type SegmentDataType as u, type Session as v, type StorageColumnType as w, type StorageSchema as x, type TagType as y, type TagTypeRecord as z };