@dreamlake/dreamdb 0.5.2 → 0.5.4

package/index.d.ts

@@ -46,7 +46,7 @@ export class Authoring {
      * 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>;
+    addEmbeddingLayer(name: string, parent_field: string, dim: number, algorithm: string, spatial_index: string, compressor: string, rerank: boolean, version: number | null | undefined, samples: Array<any>, bucket_max_bytes?: number | null, embed_spec?: Uint8Array | null): Promise<void>;
     /**
      * Add a field to the schema of an existing dataset.
      */
@@ -64,10 +64,20 @@ export class Authoring {
      * `int|float|bool|string|categorical|timestamp`.
      */
     addScalarLayer(name: string, parent_field: string, value_type: string, samples: Array<any>): Promise<void>;
+    /**
+     * Append `[anchor, vector]` pairs, adopting a raw graph as Fresh Vamana.
+     */
+    appendGraphNodes(field: string, samples: Array<any>): Promise<any>;
     /**
      * Fork the current manifest to a new ref name.
      */
     branch(new_name: string): Promise<Authoring>;
+    /**
+     * Merge one or more branches into this ref. Returns the new manifest hash.
+     * Build a raw Vamana field. Samples are `[anchor, vector]` pairs; anchors
+     * use the same lossless representation as addEmbeddingLayer.
+     */
+    buildGraphIndex(name: string, parent_field: string, dim: number, samples: Array<any>, r: number, seed: Uint8Array, embed_spec?: Uint8Array | null): Promise<void>;
     /**
      * Collapse per-cell fragments. Returns
      * `{cellsExamined, cellsCompacted, fragmentsCollapsed, manifest?}`.
@@ -78,6 +88,15 @@ export class Authoring {
      * nothing needed compacting — a no-op, not a failure.
      */
     compact(modality: string | null | undefined, threshold: number, max_cells: number): Promise<any>;
+    /**
+     * Compress a raw graph with canonical VectorCompressor CBOR. The raw
+     * lineage is retained; rerank selects exact scoring of the candidate pool.
+     */
+    compressGraphIndex(field: string, compressor: Uint8Array, rerank: boolean): Promise<void>;
+    /**
+     * Caller-driven region consolidation; does not erase tombstones or ids.
+     */
+    consolidateGraph(field: string): Promise<any>;
     /**
      * Create a new dataset and publish `refs/<name>`.
      *
@@ -101,9 +120,6 @@ export class Authoring {
      * 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.
@@ -123,6 +139,22 @@ export class Authoring {
     readonly refName: string;
 }
 
+export class GeometryReader {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Returns only the new suffix at this total logical byte budget.
+     */
+    extendCellPrefix(key: any, budget: any): Promise<Uint8Array>;
+    /**
+     * Declaration plus cells/LODs; no payload transfer. u64 values are BigInt.
+     */
+    metadata(): any;
+    readMeshLod(level: any): Promise<Uint8Array>;
+    selectCells(min: any, max: any): Array<any>;
+}
+
 /**
  * A `fetch`-backed backend rooted at a base URL.
  */
@@ -159,6 +191,15 @@ export class Space {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Validate all referenced Items, including tombstoned payloads.
+     */
+    auditArrayField(field: string): Promise<bigint>;
+    /**
+     * Validate all graph pages and, when declared, exact-source correspondence.
+     * The returned count is exactly representable (GraphIndex node_count is u32).
+     */
+    auditGraphIndex(field: string): Promise<number>;
     /**
      * The Space's human-readable description, or `undefined` when none is set.
      *
@@ -193,11 +234,21 @@ export class Space {
      * no-backend path).
      */
     static fromUri(uri: string, backend: any): Promise<Space>;
+    /**
+     * Read at this pinned Manifest. Returns null for never-created keys;
+     * deleted keys retain metadata with sample=null. Integer keys and anchors
+     * are BigInt; sample values use the Writer's tagged field shapes.
+     */
+    getEntity(key: any): Promise<any>;
     /**
      * 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>>;
+    /**
+     * Open one pinned geometry Item. Missing/deleted anchors return undefined.
+     */
+    openGeometryItem(field: string, anchor: any): Promise<GeometryReader | undefined>;
     /**
      * Hybrid search fusing a lexical (BM25) sub-query and a dense (vector)
      * sub-query per spec/0015 §5/§6. Returns the fused `[{ anchor, score }]`
@@ -220,10 +271,17 @@ export class Space {
      * ```
      *
      * 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.)
+     * Optional `scalarField` / `scalarOp` / `scalarValue` properties select
+     * the same scalar pre/post-filter planner used by the native API.
      */
     queryHybrid(vector: Float32Array, opts: any): Promise<Array<any>>;
+    /**
+     * Hybrid query with an observable `{hits, trace}` result. `opts` accepts
+     * `maxLatencyMs`, `costModel`, and the optional scalar triple
+     * `scalarField`/`scalarOp`/`scalarValue` in addition to `queryHybrid`'s
+     * existing properties.
+     */
+    queryHybridPlanned(vector: Float32Array, opts: any): Promise<any>;
     /**
      * Scalar-index lookup: every anchor whose `field` satisfies `op value`
      * (spec/0011). Returns a `BigUint64Array`-style `Array` of anchors,
@@ -257,7 +315,11 @@ export class Space {
     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 }]`
+     * number (topK) or `{ topK?, probeCount?, specId?, rerankPoolSize?, rerankMode? }`.
+     * The optional pool must be a positive integer at least topK; it changes
+     * neither probe coverage nor Schema exactness. rerankMode explicitly selects
+     * inherit (default), approximate or exact. Graphs reject explicit overrides.
+     * 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 +
@@ -274,6 +336,11 @@ export class Space {
      * authoritative shape and semantic metadata.
      */
     readArrayConstant(field: string): Promise<any>;
+    /**
+     * Point read; full-u64 BigInt anchors are supported. Returned components
+     * are owned typed arrays (one Item's bytes), never unaligned aliases.
+     */
+    readArrayItem(field: string, anchor: any): Promise<any>;
     /**
      * Read a scalar track as a `Map<anchorString, value>`. Single-anchor
      * entries resolve from the track index; multi-anchor entries fetch (and
@@ -353,6 +420,11 @@ export class Writer {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Atomically hot-append a complete Sample batch. Embeddings retain v1;
+     * scalar/text values use v2. Identified embeddings require embeddingSpecs.
+     */
+    appendHot(samples: Array<any>, embedding_specs?: object | null): Promise<number>;
     /**
      * Append records and commit in one call.
      *
@@ -366,6 +438,11 @@ export class Writer {
      * lifetime is under the caller's control.
      */
     appendMany(samples: Array<any>): Promise<number>;
+    /**
+     * Append records with a field-to-`spec_id` map for identified embeddings.
+     * Values are full canonical base32 multihashes.
+     */
+    appendManyWithSpecs(samples: Array<any>, embedding_specs: object): Promise<number>;
     /**
      * Flush staged entries and publish a new manifest.
      *
@@ -375,10 +452,30 @@ export class Writer {
      * its records on top of the new head is correct.
      */
     commit(): Promise<string>;
+    /**
+     * Producer policy only: TTL is evaluated on append, not by a timer.
+     */
+    configureHotShard(flush_threshold: number, ttl_seconds: number): void;
+    /**
+     * Create a never-used key. Sample uses appendMany's tagged fields, no anchor.
+     */
+    createEntity(key: any, sample: object, embedding_specs?: object | null): Promise<object>;
+    /**
+     * Delete exactly a live revision, retaining its key and stable identity.
+     */
+    deleteEntity(key: any, expected: Uint8Array): Promise<object>;
     /**
      * Tombstone records by anchor. Returns the new manifest hash.
      */
     deleteRecords(anchors: BigUint64Array, reason?: string | null): Promise<string>;
+    /**
+     * Enable one exact typed entity namespace: string, bytes or int.
+     */
+    enableEntityKeys(key_kind: string): Promise<void>;
+    /**
+     * Explicitly fold every pending hot field into cold Tracks in one publish.
+     */
+    flushHot(): Promise<void>;
     /**
      * Ingest a pre-fragmented CMAF (fragmented-MP4) video into a Video field
      * as a `spec/0007` §5 media Track — the thing that makes a video Track
@@ -437,10 +534,27 @@ export class Writer {
      * until it calls it.
      */
     static open(uri: string, backend: any): Promise<Writer>;
+    /**
+     * Publish prequantized fixed-stride records. Coordinates is
+     * {origin:[x,y,z],step:[x,y,z],units:string}; depth is 0..16.
+     */
+    publishGeometryCells(field: string, anchor: any, coordinates: any, depth: any, records: Uint8Array): Promise<string>;
+    /**
+     * Each level is {errorGrid,vertices,triangles,bytes:Uint8Array}.
+     */
+    publishGeometryMesh(field: string, anchor: any, coordinates: any, levels: Array<any>): Promise<string>;
     /**
      * Tag the current manifest with an immutable label (`refs/<ref>@<label>`).
      */
     snapshot(label: string): Promise<string>;
+    /**
+     * Replace only a live revision, atomically hiding its old physical row.
+     */
+    supersedeEntity(key: any, sample: object, expected: Uint8Array, embedding_specs?: object | null): Promise<object>;
+    /**
+     * Create with no expected token, or replace/restore exactly that revision.
+     */
+    upsertEntity(key: any, sample: object, expected?: Uint8Array | null, embedding_specs?: object | null): Promise<object>;
     /**
      * Current manifest hash, base32.
      */