@dreamlake/dreamdb 0.3.0 → 0.4.0

package/index.d.ts

@@ -1,4 +1,445 @@
-export * from './dreamdb'
+// @dreamlake/dreamdb — generated by build.sh from the write-full build's
+// declarations plus the hand-written additions below. Do not edit by hand.
+
+// wasm-bindgen emits `[Symbol.dispose]()` on every exported class. That symbol
+// only exists in the `esnext.disposable` lib, so without this reference the
+// package fails to type-check for anyone whose `target` is es2022 or earlier —
+// which is most people, and the error points at our .d.ts rather than at their
+// tsconfig. Referencing the lib here fixes it for the consumer.
+/// <reference lib="esnext.disposable" />
+
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Dataset creation, layers, merge, compaction and history.
+ *
+ * **Node only.** The browser build exports a stub whose every method throws:
+ * the index builders it needs cost ~123 KB gzipped and require training data
+ * that does not belong in a tab. It is typed on both ends so that code shared
+ * between server and client type-checks once.
+ */
+export class Authoring {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Add an embedding column whose index artifacts already exist.
+     *
+     * `spatialIndex` and `compressor` are base32 multihashes of objects the
+     * caller has already trained and uploaded (the CLI's `rebuild_exact` /
+     * index builders produce them). They are required rather than optional
+     * because training an IVF index inside a wasm module means holding the
+     * full training set in a 32-bit address space — the failure mode is an
+     * allocation abort that reaches JS as a bare `unreachable`.
+     *
+     * `rerank` stores exact f32 vectors alongside the compressed ones. Leave
+     * it on unless you have measured that you can live without it: with it
+     * off, reads decode 1-bit reconstructions and relevance degrades in a way
+     * no API-level check can see.
+     */
+    addEmbeddingLayer(name: string, parent_field: string, dim: number, algorithm: string, spatial_index: string, compressor: string, rerank: boolean, version: number | null | undefined, samples: Array<any>): Promise<void>;
+    /**
+     * Add a field to the schema of an existing dataset.
+     */
+    addField(field: any): Promise<void>;
+    /**
+     * Add an image column over an existing field's anchors.
+     * `samples` is `[[anchor, Uint8Array], …]`.
+     */
+    addImageLayer(name: string, parent_field: string, samples: Array<any>, mime: string): Promise<void>;
+    /**
+     * Add a scalar column over an existing field's anchors.
+     *
+     * `samples` is `[[anchor, value], …]`; anchors must already exist in the
+     * parent field. `valueType` is one of
+     * `int|float|bool|string|categorical|timestamp`.
+     */
+    addScalarLayer(name: string, parent_field: string, value_type: string, samples: Array<any>): Promise<void>;
+    /**
+     * Fork the current manifest to a new ref name.
+     */
+    branch(new_name: string): Promise<Authoring>;
+    /**
+     * Collapse per-cell fragments. Returns
+     * `{cellsExamined, cellsCompacted, fragmentsCollapsed, manifest?}`.
+     *
+     * This is the cheapest latency lever there is on a sharded ingest: on the
+     * `vision-mixed` corpus it took 32,782 buckets to 3,122 in 1m48s, for no
+     * change in results and no extra hardware. `manifest` is absent when
+     * nothing needed compacting — a no-op, not a failure.
+     */
+    compact(modality: string | null | undefined, threshold: number, max_cells: number): Promise<any>;
+    /**
+     * Create a new dataset and publish `refs/<name>`.
+     *
+     * `schema` is an array of field descriptors — see `marshal::schema_from_js`
+     * for the accepted shapes.
+     *
+     * Note the core's own constraint, surfaced rather than papered over:
+     * embedding fields declaring `dreamdb.ivf-cosine` / `dreamdb.imi-cosine`
+     * cannot be created here, because those index families need training data
+     * that does not exist yet at create time. Create with the default
+     * `dreamdb.lsh-cosine` and add a trained index as a layer once you have
+     * vectors, or build the index with the CLI.
+     */
+    static create(name: string, schema: Array<any>, base: string, backend: any): Promise<Authoring>;
+    /**
+     * Delete a ref. Does not delete the objects it pointed at — they stay
+     * reachable by manifest hash, which is what makes this recoverable.
+     */
+    deleteRef(name: string): Promise<void>;
+    /**
+     * Ref names under `refs/`. Requires a backend implementing `list`.
+     */
+    listRefs(): Promise<string[]>;
+    /**
+     * Merge one or more branches into this ref. Returns the new manifest hash.
+     */
+    mergeMany(branches: string[]): Promise<string>;
+    /**
+     * Open an existing ref for authoring.
+     */
+    static open(uri: string, backend: any): Promise<Authoring>;
+    /**
+     * Set a human-readable description on the dataset.
+     */
+    setDescription(text: string): Promise<void>;
+    /**
+     * A `Writer` sharing this handle — for append/commit/snapshot.
+     */
+    writer(): Writer;
+    /**
+     * The ref this handle writes to.
+     */
+    readonly refName: string;
+}
+
+/**
+ * A `fetch`-backed backend rooted at a base URL.
+ */
+export class S3Backend {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Fetch `path` (relative to the base URL) and resolve to its bytes.
+     * `opts.noCache` is accepted for API compatibility (currently a no-op:
+     * content is hash-addressed; refs are read fresh each page load anyway).
+     */
+    get(path: string, _opts: any): Promise<Uint8Array>;
+    /**
+     * List object paths under `prefix`. Stub (returns empty); the current
+     * consumer read paths don't require listing.
+     */
+    list(_prefix: string): Promise<Array<any>>;
+    /**
+     * Construct rooted at `base_url` (trailing slash trimmed).
+     */
+    constructor(base_url: string);
+}
+
+export class Space {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Open a Space from a `.../refs/<name>` or `.../manifests/<hash>` URI,
+     * resolving the ref (if any) and loading the manifest. If `backend` is
+     * provided it handles IO (relative paths); otherwise a direct-fetch
+     * connector rooted at the parsed base URL is used (the `dreamdb-demo`
+     * no-backend path).
+     */
+    static fromUri(uri: string, backend: any): Promise<Space>;
+    /**
+     * Walk the manifest DAG from HEAD, up to `max_depth` entries. Each entry:
+     * `{ manifestHash, ts, writer, tracks: [{modality, address}] }`.
+     */
+    history(max_depth?: number | null): Promise<Array<any>>;
+    /**
+     * Hybrid search fusing a lexical (BM25) sub-query and a dense (vector)
+     * sub-query per spec/0015 §5/§6. Returns the fused `[{ anchor, score }]`
+     * list sorted by fused score descending — the same scored shape as
+     * `queryVector`.
+     *
+     * `vector` is the dense sub-query embedding (a `Float32Array`). `opts` is a
+     * plain JS object:
+     * ```js
+     * {
+     *   textField, textQuery,        // BM25 sub-query (required)
+     *   vectorField,                 // dense field the `vector` targets (required)
+     *   topK = 10,                   // fused results to return
+     *   fusion = 'rrf',              // 'rrf' | 'linear' | 'max' | 'pareto'
+     *   rrfK = 60,                   // RRF rank constant (fusion='rrf')
+     *   textWeight = 1, vectorWeight = 1, // Linear weights (fusion='linear')
+     *   textK = topK, vectorK = topK,     // per-sub-query candidate depths
+     *   textRequired = false, vectorRequired = false, // §5.3 boolean-AND gates
+     * }
+     * ```
+     *
+     * Delegates to the real (tested) `dreamdb-dataset::Dataset::query_hybrid`.
+     * (v0 does not expose the optional scalar pre/post-filter; it runs with no
+     * scalar gate.)
+     */
+    queryHybrid(vector: Float32Array, opts: any): Promise<Array<any>>;
+    /**
+     * Scalar-index lookup: every anchor whose `field` satisfies `op value`
+     * (spec/0011). Returns a `BigUint64Array`-style `Array` of anchors,
+     * tombstone-suppressed, sorted ascending and deduped.
+     *
+     * This is the expansion half of a compact lexical index. A BM25 index
+     * built over a scalar field's DISTINCT values returns one representative
+     * anchor per matched value; resolving that value back to *every* record
+     * carrying it is a scalar-index lookup, not a text-index concern. Keeping
+     * the split this way is what lets the text index stay small enough to
+     * load in a browser — indexing one document per record instead produced a
+     * 406 MB object for ~1,700 distinct strings.
+     *
+     * `op` is one of `==`, `!=`, `<`, `<=`, `>`, `>=`. `value` may be a
+     * string, number, or boolean; strings match both `String` and
+     * `Categorical` scalar fields.
+     */
+    queryScalar(field: string, op: string, value: any): Promise<Array<any>>;
+    /**
+     * Lexical BM25 text search over a text `field` (spec/0015 §3.6).
+     *
+     * Tokenizes `query` with the built-in `dreamdb.utf8-words` tokenizer
+     * (lowercase + split on non-alphanumeric — pure Rust, compiled into the
+     * wasm; no external model needed even though the field's embeddings were
+     * produced elsewhere), scores docs with BM25, and suppresses tombstoned
+     * anchors. Returns `[{ anchor, score }]` sorted by score descending — the
+     * same scored shape as `queryVector`.
+     *
+     * Delegates to the real (tested) `dreamdb-dataset::Dataset::query_text`.
+     */
+    queryText(field: string, query: string, top_k: number): Promise<Array<any>>;
+    /**
+     * Top-K cosine vector search over an embedding `field`. `opts` may be a
+     * number (topK) or `{ topK?, probeCount? }`. Returns `[{ anchor, score }]`
+     * sorted by score descending — the shape dreamdb-ts's `queryVector` yields.
+     *
+     * Delegates to the real (tested) `dreamdb-dataset` query path: ADC cull +
+     * two-pass rerank + HotShard merge + tombstone suppression.
+     */
+    queryVector(field: string, query: Float32Array, opts: any): Promise<Array<any>>;
+    /**
+     * Read a scalar track as a `Map<anchorString, value>`. Single-anchor
+     * entries resolve from the track index; multi-anchor entries fetch (and
+     * de-dupe) their bucket and roaring-decode the anchor set.
+     */
+    readScalarColumn(track: any, _opts: any): Promise<Map<any, any>>;
+    /**
+     * Fetch a track object and return its `object_index` (array of CBOR
+     * entries). Inline indexes only — paged indexes are not resolved (matching
+     * dreamdb-ts, which also doesn't support them on this path).
+     */
+    resolveObjectIndex(track: any): Promise<Array<any>>;
+    /**
+     * Base32 hash of the manifest's first timeline.
+     */
+    timelineId(): string;
+    /**
+     * Find a track by its resolved `key` or by `modality`.
+     */
+    trackFor(key_or_modality: string): any;
+    /**
+     * List resolved tracks from this manifest.
+     */
+    tracks(): Array<any>;
+    /**
+     * The base URL objects are fetched relative to (consumers build their own
+     * object URLs from this — e.g. `dreamdb-demo`'s track readers).
+     */
+    readonly connectorBase: string;
+    /**
+     * The manifest's base32 multihash.
+     */
+    readonly manifestHash: string;
+}
+
+/**
+ * A write handle onto a ref.
+ */
+export class Writer {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Append records and commit in one call.
+     *
+     * `samples` is an array of `{ anchor?: bigint|number, <field>: value }`.
+     * See `marshal::samples_from_js` for the accepted field shapes.
+     *
+     * Committing here rather than exposing a separate staged mode is
+     * deliberate for the browser surface: a staged write that is never
+     * committed leaves uploaded objects unreferenced, and a tab can close at
+     * any moment. `appendStaged` exists on the Node surface where the process
+     * lifetime is under the caller's control.
+     */
+    appendMany(samples: Array<any>): Promise<number>;
+    /**
+     * Flush staged entries and publish a new manifest.
+     *
+     * Fails with a CAS conflict if the ref moved underneath this writer. That
+     * is not retried automatically: an automatic retry would hide a logical
+     * conflict, and the caller is the only one who knows whether re-applying
+     * its records on top of the new head is correct.
+     */
+    commit(): Promise<string>;
+    /**
+     * Tombstone records by anchor. Returns the new manifest hash.
+     */
+    deleteRecords(anchors: BigUint64Array, reason?: string | null): Promise<string>;
+    /**
+     * Open a ref for writing.
+     *
+     * `uri` is the same `.../refs/<name>` form `Space.fromUri` takes; a
+     * `.../manifests/<hash>` URI is rejected rather than silently opening
+     * something unwritable, because a manifest hash names an immutable
+     * snapshot — there is nothing for a commit to advance.
+     *
+     * `backend` must implement `put` (Backend contract v2). Passing a
+     * read-only backend fails at the first write with a clear message rather
+     * than here, since the connector cannot know what the JS object omits
+     * until it calls it.
+     */
+    static open(uri: string, backend: any): Promise<Writer>;
+    /**
+     * Tag the current manifest with an immutable label (`refs/<ref>@<label>`).
+     */
+    snapshot(label: string): Promise<string>;
+    /**
+     * Current manifest hash, base32.
+     */
+    readonly manifestHash: string;
+    /**
+     * The ref this writer advances.
+     */
+    readonly refName: string;
+}
+
+/**
+ * Install a panic hook that logs the panic message AND its `file:line:col`
+ * to the console before the wasm trap surfaces to JS.
+ *
+ * Without this, every Rust panic reaches JavaScript as a bare
+ * `RuntimeError: unreachable` with nothing but wasm frame offsets — and it is
+ * indistinguishable from an allocation failure, since Rust's alloc-error
+ * handler also aborts. That ambiguity cost real debugging time: a browser
+ * `unreachable` from exhausting wasm32's 32-bit address space on an oversized
+ * index was initially read as an integer-overflow panic.
+ *
+ * Zero new deps — uses the already-enabled `web-sys` `console` feature.
+ * Runs once at module init.
+ */
+export function __wasm_init(): void;
+
+/**
+ * Parse an object path and re-format it. Byte-identity of the result is the
+ * actual assertion: a parser that silently drops a component still "parses".
+ */
+export function addressRoundTrip(path: string): string;
+
+/**
+ * The address variant name (`Genesis`, `Manifest`, `Ref`, …) for a path.
+ *
+ * Derived from the Debug representation rather than a hand-written match.
+ * `DreamDbAddress` has seventeen variants and gains one whenever the protocol
+ * does; a match arm per variant would be a second list to keep in sync, and
+ * the vectors only ever assert the name.
+ */
+export function addressVariant(path: string): string;
+
+/**
+ * Encode arbitrary bytes as lowercase RFC-4648 base32 (no padding).
+ *
+ * Byte-identical to `dreamdb-ts`'s `bytesToBase32` (alphabet
+ * `abcdefghijklmnopqrstuvwxyz234567`) and to `dreamdb_core`'s multihash
+ * `to_base32`, which is how object addresses are spelled on disk.
+ */
+export function bytesToBase32(bytes: Uint8Array): string;
+
+/**
+ * Decode a single CBOR value from `bytes` into its JS representation.
+ */
+export function decodeCbor(bytes: Uint8Array): any;
+
+/**
+ * Canonically encode a JS value as CBOR, returning the bytes.
+ *
+ * Canonical here means what spec/0002 §3.1 means: map keys sorted by their
+ * encoded bytes, shortest-form integers, no indefinite lengths. Two writers
+ * that disagree on this produce different content hashes for the same logical
+ * object, and every address derived from them diverges.
+ */
+export function encodeCbor(value: any): Uint8Array;
+
+/**
+ * Parse a modality tag into `{class, encoding, trackKind, objectKind, params,
+ * flags}`, or throw if it is invalid.
+ *
+ * `params` is a plain object of the `key=value` segments and `flags` an array
+ * of the bare ones (`bucketed`, `graph`). They are separate because the
+ * grammar treats them differently and merging them would make a flag
+ * indistinguishable from a parameter whose value happened to be empty.
+ */
+export function modalityParse(tag: string): any;
+
+/**
+ * BLAKE3-256 multihash of `bytes`, base32 (the form used in object paths).
+ */
+export function multihashBase32(bytes: Uint8Array): string;
+
+/**
+ * BLAKE3-256 multihash of `bytes` as lowercase hex (33 bytes: tag + digest).
+ */
+export function multihashHex(bytes: Uint8Array): string;
+
+/**
+ * DreamDB's half-open `[start, end)` → an HTTP `Range` header value.
+ *
+ * The off-by-one here is worth a vector of its own: HTTP ranges are
+ * *inclusive* of the end byte. Getting it wrong reads one byte too few from
+ * every object, which corrupts decode in ways that look like anything but an
+ * off-by-one.
+ */
+export function rangeHeader(start: bigint, end: bigint): string;
+
+/**
+ * Round-trip a spatial key through its base-2 form, per spec/0002 §6.
+ *
+ * Returns the re-encoded string, so a caller can assert byte-identity rather
+ * than merely "it parsed".
+ */
+export function spatialKeyRoundTrip(bits: string): string;
+
+/**
+ * The 16-char hex address form → TimeAnchor. Throws on a malformed input
+ * (wrong length, uppercase) rather than coercing it.
+ */
+export function timeAnchorFromHex(s: string): bigint;
+
+/**
+ * TimeAnchor → the 16-char hex used in addresses.
+ */
+export function timeAnchorHex(value: bigint): string;
+
+/**
+ * Which time bucket an anchor falls in, given a duration like `"1s"`/`"60s"`.
+ */
+export function timeBucket(t_start: bigint, duration: string): bigint;
+
+/**
+ * Package version — useful for consumers to confirm which build is loaded.
+ */
+export function version(): string;
+
+/**
+ * The all-zero spatial-key path segment used for non-spatial (fragment) object
+ * addresses. Matches `dreamdb-ts`'s `ZERO_SPATIAL_KEY` constant exactly.
+ */
+export function zeroSpatialKey(): string;
+
+// ── hand-written additions ──────────────────────────────────────────────────
 
 /** Zero spatial-key path segment for non-spatial (fragment) object addresses. */
 export const ZERO_SPATIAL_KEY: string
@@ -14,3 +455,102 @@ export interface ResolvedTrack {
   timeline: string
   coverage: unknown
 }
+
+/** Outcome of a conditional write. */
+export type PutStatus = 'created' | 'exists' | 'casFailed'
+
+/**
+ * Backend contract v2 — the IO surface the SDK calls into.
+ *
+ * `get` is the only required method; a backend with just `get` is the v1
+ * read-only shape and still works for reading. Write entry points check for
+ * `put` up front and refuse with a message naming what is missing, because
+ * discovering it mid-commit leaves unreferenced objects in the bucket.
+ *
+ * The ETag is not decoration. `publish` picks `If-Match: <etag>` when it knows
+ * the ref's current version and `If-None-Match: *` when it does not — so a
+ * backend that never returns an ETag silently downgrades every ref update to
+ * create-only, and the *second* commit to a ref fails while the first
+ * succeeded. On S3 that also requires `ExposeHeaders: ["ETag"]` in the bucket's
+ * CORS rule; without it the browser cannot read the header at all.
+ */
+export interface Backend {
+  /** Inclusive byte range. Returning a bare Uint8Array is the accepted v1 shape. */
+  get(
+    path: string,
+    range?: { start: number; end: number },
+  ): Promise<Uint8Array | { bytes: Uint8Array; etag?: string }>
+
+  head?(path: string): Promise<{ exists?: boolean; etag?: string; size?: number }>
+
+  put?(
+    path: string,
+    bytes: Uint8Array,
+    opts?: { ifMatch?: string; ifNoneMatchStar?: boolean },
+  ): Promise<{ status: PutStatus; etag?: string }>
+
+  delete?(path: string): Promise<void>
+
+  list?(prefix: string): Promise<string[]>
+}
+
+/** Options for {@link PresignedBackend}. */
+export interface PresignedBackendOptions {
+  /** Base URL reads are issued against. */
+  readBase: string
+  /**
+   * Mint presigned URLs for a batch of paths. One commit writes buckets,
+   * tracks, a manifest and a ref — signing them individually turns a commit
+   * into N server round trips.
+   */
+  mintPut(
+    paths: string[],
+    opts?: { ifMatch?: string },
+  ): Promise<Record<string, { url: string; headers?: Record<string, string> }>>
+  /**
+   * Server-side conditional write of the 33-byte ref object. Required for the
+   * default `refStrategy: 'proxy'`.
+   */
+  commitRef?(
+    path: string,
+    opts: { ifMatch?: string; ifNoneMatchStar?: boolean },
+    bytes: Uint8Array,
+  ): Promise<{ status: PutStatus; etag?: string }>
+  /**
+   * `'proxy'` (default) has your server perform the ref's conditional PUT with
+   * real credentials — identical behaviour on S3, R2, MinIO and GCS.
+   * `'presign'` signs a conditional PUT and sends it from the browser: fewer
+   * moving parts, but whether `If-Match` survives presigning is
+   * provider-specific and GCS uses `x-goog-if-generation-match` instead.
+   */
+  refStrategy?: 'proxy' | 'presign'
+  /** Override read URL construction. */
+  readUrl?(path: string): string
+}
+
+/**
+ * Browser Backend that reads over `fetch` and writes through short-lived
+ * presigned URLs minted by your server. Credentials never enter the browser.
+ *
+ * Browser and web entry points only — see {@link PresignedBackendOptions}.
+ */
+export class PresignedBackend implements Backend {
+  constructor(options: PresignedBackendOptions)
+  get(path: string, range?: { start: number; end: number }): Promise<{ bytes: Uint8Array; etag?: string }>
+  head(path: string): Promise<{ exists?: boolean; etag?: string; size?: number }>
+  put(
+    path: string,
+    bytes: Uint8Array,
+    opts?: { ifMatch?: string; ifNoneMatchStar?: boolean },
+  ): Promise<{ status: PutStatus; etag?: string }>
+  // No `delete`: object deletion is not part of the browser write channel.
+  // `deleteRecords` writes tombstones, and dropping a ref is Node-only.
+}
+
+/**
+ * Fetch and instantiate the wasm module.
+ *
+ * Exported only from `@dreamlake/dreamdb/web`, the no-bundler entry point. The
+ * bundler and Node builds instantiate themselves and have nothing to await.
+ */
+export default function ready(input?: unknown): Promise<unknown>