@dreamlake/dreamdb 0.5.1 → 0.5.3

package/web/dreamdb.d.ts

@@ -1,6 +1,22 @@
 /* tslint:disable */
 /* eslint-disable */
 
+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.
  */
@@ -13,6 +29,15 @@ export class S3Backend {
      * content is hash-addressed; refs are read fresh each page load anyway).
      */
     get(path: string, _opts: any): Promise<Uint8Array>;
+    /**
+     * Stream `path` without first aggregating the response in wasm memory.
+     *
+     * Returning the length beside the browser stream satisfies the optional
+     * `Backend.getStream` contract. Older injected backends that implement
+     * only [`Self::get`] remain compatible, but cannot claim bounded memory
+     * for historical oversized inline Track reads.
+     */
+    getStream(path: string): Promise<any>;
     /**
      * List object paths under `prefix`. Stub (returns empty); the current
      * consumer read paths don't require listing.
@@ -28,6 +53,41 @@ 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.
+     *
+     * The read half of `Authoring.setDescription` (#129). It lives here rather
+     * than on `Authoring` because that type is `write-full` and so exists only
+     * in the Node build — a description is metadata a READER wants, and
+     * `Space` is the surface all three build targets share.
+     *
+     * `async` although `Dataset::description` is not: the value comes from the
+     * Dataset this Space opens lazily at the Manifest hash already pinned by
+     * this Space, so the first call may perform that open without re-resolving
+     * a source Ref.
+     *
+     * Deliberately routed through `Dataset::description` rather than read out
+     * of `self.manifest`'s registry, which would be shorter and would also
+     * serve the cached decoded Manifest. `Dataset::recover_meta` is not a prefix
+     * filter: it accepts the legacy `vortex.*` namespace as well as
+     * `dreamdb.*`, canonicalises, and drops structural keys. Matching
+     * `dreamdb.description` here would silently return nothing for a legacy
+     * Space whose description is on disk and readable from Rust — the exact
+     * defect `recover_meta`'s own comment records.
+     *
+     * `Option<String>` marshals to `string | undefined`, NOT to `""`. An unset
+     * description and an empty one stay distinguishable across the boundary.
+     */
+    description(): Promise<string | undefined>;
     /**
      * Open a Space from a `.../refs/<name>` or `.../manifests/<hash>` URI,
      * resolving the ref (if any) and loading the manifest. If `backend` is
@@ -36,11 +96,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 }]`
@@ -63,10 +133,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,
@@ -107,18 +184,60 @@ export class Space {
      * two-pass rerank + HotShard merge + tombstone suppression.
      */
     queryVector(field: string, query: Float32Array, opts: any): Promise<Array<any>>;
+    /**
+     * Read an Event/Unbucketed or Continuous/TimeBatch typed-array field as
+     * `Map<anchorString, {values, shape, ...}>`.
+     */
+    readArrayColumn(field: string): Promise<Map<any, any>>;
+    /**
+     * Read a typed-array Constant and decode it to a JS TypedArray plus its
+     * 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
      * de-dupe) their bucket and roaring-decode the anchor set.
      */
     readScalarColumn(track: any, _opts: any): Promise<Map<any, any>>;
+    /**
+     * Fetch verified initialization and complete Fragments overlapping one
+     * item-relative half-open range. This materializes the selected bytes; it
+     * is not a streaming API.
+     */
+    readVideoItemRange(field: string, item_key: Uint8Array, relative_start_ns: any, relative_end_ns: any): Promise<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>>;
+    /**
+     * Semantic-cache capacity in bytes (spec/0006 §3.6). Default 1 GiB.
+     */
+    semanticCacheCapacity(): Promise<number>;
+    /**
+     * Semantic-cache occupancy as `{ entries, bytesUsed, maxBytes }`.
+     */
+    semanticCacheStats(): Promise<object>;
+    /**
+     * Set the semantic-cache capacity in bytes, evicting down to it before
+     * returning. Returns the bytes evicted. `0` disables the cache.
+     *
+     * An index whose accounted size exceeds the cap is not cached and is
+     * re-fetched on every query, reported honestly as a miss. The default is
+     * not raised globally to suit one corpus.
+     *
+     * Sizing is workload- and architecture-dependent, and figures measured on
+     * a 64-bit host do NOT carry over here: `usize` is 32 bits on `wasm32`, so
+     * every offset and length inside a decoded index accounts differently.
+     */
+    setSemanticCacheCapacity(n_bytes: number): Promise<number>;
     /**
      * Base32 hash of the manifest's first timeline.
      */
@@ -131,6 +250,16 @@ export class Space {
      * List resolved tracks from this manifest.
      */
     tracks(): Array<any>;
+    /**
+     * Look up the logical VideoItem containing one absolute Timeline anchor
+     * without fetching media. Exact nanosecond values are returned as bigint.
+     */
+    videoItemAt(field: string, anchor_ns: any): Promise<any>;
+    /**
+     * Look up one logical VideoItem by its stable opaque key without fetching
+     * initialization or Fragment bytes.
+     */
+    videoItemByKey(field: string, item_key: Uint8Array): Promise<any>;
     /**
      * The base URL objects are fetched relative to (consumers build their own
      * object URLs from this — e.g. `dreamdb-demo`'s track readers).
@@ -149,6 +278,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.
      *
@@ -162,6 +296,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.
      *
@@ -171,10 +310,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>;
     /**
      * Open a ref for writing.
      *
@@ -189,10 +348,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.
      */
@@ -314,6 +490,13 @@ export function timeAnchorHex(value: bigint): string;
  */
 export function timeBucket(t_start: bigint, duration: string): bigint;
 
+/**
+ * Decode one spec/0025 item using the same declaration and payload path as
+ * `Space.readArrayColumn`, without requiring storage IO. This is the SDK's
+ * pure conformance entry point for language-neutral vectors.
+ */
+export function typedArrayDecode(item_type: any, payload: Uint8Array): any;
+
 /**
  * Package version — useful for consumers to confirm which build is loaded.
  */
@@ -329,6 +512,7 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_geometryreader_free: (a: number, b: number) => void;
     readonly __wbg_s3backend_free: (a: number, b: number) => void;
     readonly __wbg_space_free: (a: number, b: number) => void;
     readonly __wbg_writer_free: (a: number, b: number) => void;
@@ -337,38 +521,70 @@ export interface InitOutput {
     readonly bytesToBase32: (a: number, b: number) => [number, number];
     readonly decodeCbor: (a: number, b: number) => [number, number, number];
     readonly encodeCbor: (a: any) => [number, number, number, number];
+    readonly geometryreader_extendCellPrefix: (a: number, b: any, c: any) => any;
+    readonly geometryreader_metadata: (a: number) => [number, number, number];
+    readonly geometryreader_readMeshLod: (a: number, b: any) => any;
+    readonly geometryreader_selectCells: (a: number, b: any, c: any) => [number, number, number];
     readonly modalityParse: (a: number, b: number) => [number, number, number];
     readonly multihashBase32: (a: number, b: number) => [number, number];
     readonly multihashHex: (a: number, b: number) => [number, number];
     readonly rangeHeader: (a: bigint, b: bigint) => [number, number, number, number];
     readonly s3backend_get: (a: number, b: number, c: number, d: any) => any;
+    readonly s3backend_getStream: (a: number, b: number, c: number) => any;
     readonly s3backend_list: (a: number, b: number, c: number) => any;
     readonly s3backend_new: (a: number, b: number) => number;
+    readonly space_auditArrayField: (a: number, b: number, c: number) => any;
+    readonly space_auditGraphIndex: (a: number, b: number, c: number) => any;
     readonly space_connectorBase: (a: number) => [number, number];
+    readonly space_description: (a: number) => any;
     readonly space_fromUri: (a: number, b: number, c: any) => any;
+    readonly space_getEntity: (a: number, b: any) => any;
     readonly space_history: (a: number, b: number) => any;
     readonly space_manifestHash: (a: number) => [number, number];
+    readonly space_openGeometryItem: (a: number, b: number, c: number, d: any) => any;
     readonly space_queryHybrid: (a: number, b: number, c: number, d: any) => any;
+    readonly space_queryHybridPlanned: (a: number, b: number, c: number, d: any) => any;
     readonly space_queryScalar: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
     readonly space_queryText: (a: number, b: number, c: number, d: number, e: number, f: number) => any;
     readonly space_queryVector: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
+    readonly space_readArrayColumn: (a: number, b: number, c: number) => any;
+    readonly space_readArrayConstant: (a: number, b: number, c: number) => any;
+    readonly space_readArrayItem: (a: number, b: number, c: number, d: any) => any;
     readonly space_readScalarColumn: (a: number, b: any, c: any) => any;
+    readonly space_readVideoItemRange: (a: number, b: number, c: number, d: any, e: any, f: any) => any;
     readonly space_resolveObjectIndex: (a: number, b: any) => any;
+    readonly space_semanticCacheCapacity: (a: number) => any;
+    readonly space_semanticCacheStats: (a: number) => any;
+    readonly space_setSemanticCacheCapacity: (a: number, b: number) => any;
     readonly space_timelineId: (a: number) => [number, number, number, number];
-    readonly space_trackFor: (a: number, b: number, c: number) => any;
-    readonly space_tracks: (a: number) => any;
+    readonly space_trackFor: (a: number, b: number, c: number) => [number, number, number];
+    readonly space_tracks: (a: number) => [number, number, number];
+    readonly space_videoItemAt: (a: number, b: number, c: number, d: any) => any;
+    readonly space_videoItemByKey: (a: number, b: number, c: number, d: any) => any;
     readonly spatialKeyRoundTrip: (a: number, b: number) => [number, number, number, number];
     readonly timeAnchorFromHex: (a: number, b: number) => [bigint, number, number];
     readonly timeAnchorHex: (a: bigint) => [number, number];
     readonly timeBucket: (a: bigint, b: number, c: number) => [bigint, number, number];
+    readonly typedArrayDecode: (a: any, b: number, c: number) => [number, number, number];
     readonly version: () => [number, number];
+    readonly writer_appendHot: (a: number, b: any, c: number) => any;
     readonly writer_appendMany: (a: number, b: any) => any;
+    readonly writer_appendManyWithSpecs: (a: number, b: any, c: any) => any;
     readonly writer_commit: (a: number) => any;
+    readonly writer_configureHotShard: (a: number, b: number, c: number) => [number, number];
+    readonly writer_createEntity: (a: number, b: any, c: any, d: number) => any;
+    readonly writer_deleteEntity: (a: number, b: any, c: any) => any;
     readonly writer_deleteRecords: (a: number, b: number, c: number, d: number, e: number) => any;
+    readonly writer_enableEntityKeys: (a: number, b: number, c: number) => any;
+    readonly writer_flushHot: (a: number) => any;
     readonly writer_manifestHash: (a: number) => [number, number, number, number];
     readonly writer_open: (a: number, b: number, c: any) => any;
+    readonly writer_publishGeometryCells: (a: number, b: number, c: number, d: any, e: any, f: any, g: any) => any;
+    readonly writer_publishGeometryMesh: (a: number, b: number, c: number, d: any, e: any, f: any) => any;
     readonly writer_refName: (a: number) => [number, number];
     readonly writer_snapshot: (a: number, b: number, c: number) => any;
+    readonly writer_supersedeEntity: (a: number, b: any, c: any, d: any, e: number) => any;
+    readonly writer_upsertEntity: (a: number, b: any, c: any, d: number, e: number) => any;
     readonly zeroSpatialKey: () => [number, number];
     readonly __wasm_init: () => void;
     readonly wasm_bindgen_f7c54996eb9137d9___convert__closures_____invoke___wasm_bindgen_f7c54996eb9137d9___JsValue__core_7d5f0a2ba6a62c33___result__Result_____wasm_bindgen_f7c54996eb9137d9___JsError___true_: (a: number, b: number, c: any) => [number, number];