@dreamlake/dreamdb 0.5.0 → 0.5.2

package/LICENSE-APACHE

@@ -0,0 +1,20 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright (c) 2026 DreamLake AI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+The full text of the Apache License, Version 2.0 is available at the URL
+above and is incorporated here by reference.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DreamLake AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -114,13 +114,21 @@ trained index as a layer, or build it with the CLI.
 ## Implementing a Backend
 
 Only `get` is required; a `get`-only backend is the read-only v1 shape and
-still works for reading. Write entry points check for `put` up front and refuse
-with a message naming what is missing.
+still works for reading. Implement `getStream` to keep full-object reads bounded
+when DreamDB must scan a historical oversized inline Track. Write entry points
+check for `put` up front and refuse with a message naming what is missing.
 
 ```ts
 interface Backend {
+  // `range` is half-open: start is included, end is excluded.
   get(path: string, range?: { start: number; end: number })
-    : Promise<Uint8Array | { bytes: Uint8Array; etag?: string }>
+    : Promise<Uint8Array | { bytes: Uint8Array; etag?: string; totalLength?: number }>
+  getStream?(path: string)
+    : Promise<ReadableStream<Uint8Array> | {
+        stream: ReadableStream<Uint8Array>
+        etag?: string
+        totalLength?: number
+      }>
   head?(path: string): Promise<{ exists?: boolean; etag?: string; size?: number }>
   put?(path: string, bytes: Uint8Array,
        opts?: { ifMatch?: string; ifNoneMatchStar?: boolean })
@@ -130,6 +138,13 @@ interface Backend {
 }
 ```
 
+`getStream` chunks must themselves be bounded; returning one object-sized
+`Uint8Array` is functionally valid but does not provide the bounded-memory
+profile. The SDK hashes every chunk and exposes no decoded result until the
+complete response matches its content address. Existing backends without
+`getStream` continue through `get` and are intentionally classified as the
+unbounded compatibility profile.
+
 ### Two things that will bite you
 
 **Your bucket's CORS rule must include `ExposeHeaders: ["ETag"]`.**

package/browser/dreamdb.d.ts

@@ -13,6 +13,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 +37,32 @@ export class Space {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * 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
@@ -107,18 +142,55 @@ 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>;
     /**
      * 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 +203,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).
@@ -314,6 +396,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.
  */

package/browser/dreamdb.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./dreamdb_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    S3Backend, Space, Writer, __wasm_init, addressRoundTrip, addressVariant, bytesToBase32, decodeCbor, encodeCbor, modalityParse, multihashBase32, multihashHex, rangeHeader, spatialKeyRoundTrip, timeAnchorFromHex, timeAnchorHex, timeBucket, version, zeroSpatialKey
+    S3Backend, Space, Writer, __wasm_init, addressRoundTrip, addressVariant, bytesToBase32, decodeCbor, encodeCbor, modalityParse, multihashBase32, multihashHex, rangeHeader, spatialKeyRoundTrip, timeAnchorFromHex, timeAnchorHex, timeBucket, typedArrayDecode, version, zeroSpatialKey
 } from "./dreamdb_bg.js";