@dreamlake/dreamdb 0.5.0 → 0.5.2

package/node/dreamdb.d.cts

@@ -8,6 +8,14 @@ export class Authoring {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Add one fixed-shape typed-array Constant.
+     *
+     * `field` is the same `{name, kind:'array', ...}` descriptor accepted by
+     * `create`, with `trackKind:'constant'` and `objectKind:'constant'`.
+     * `payload` is a raw or NPY payload matching that declaration.
+     */
+    addArrayConstant(field: any, payload: Uint8Array): Promise<void>;
     /**
      * Add an embedding column whose index artifacts already exist.
      *
@@ -112,6 +120,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.
@@ -127,6 +144,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
@@ -206,18 +249,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.
      */
@@ -230,6 +310,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).
@@ -274,6 +364,43 @@ export class Writer {
      * Tombstone records by anchor. Returns the new manifest hash.
      */
     deleteRecords(anchors: BigUint64Array, reason?: string | null): Promise<string>;
+    /**
+     * 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
+     * time-seekable and MSE-playable rather than one opaque blob.
+     *
+     * ```js
+     * const out = await writer.ingestCmaf('video', initBytes, [
+     *   [frag0, 0n, 2_000_000_000n],
+     *   [frag1, 2_000_000_000n, 4_000_000_000n],
+     * ])
+     * ```
+     *
+     * - `init` is the initialization segment (`ftyp`+`moov`).
+     * - each fragment is `[Uint8Array, tStartNs, tEndNs]`, half-open, already
+     *   offset to the timeline anchor the caller wants. Pass `bigint`s:
+     *   wall-clock nanosecond anchors are far past `Number.MAX_SAFE_INTEGER`
+     *   and a rounded `tStart` writes the fragment into a 60 s bucket that
+     *   does not match the address it is indexed at.
+     *
+     * Calling it again on the SAME field APPENDS (one episode per call on a
+     * shared timeline) and reuses the track's existing init segment; a clip
+     * whose init differs — different codec, resolution, fps or audio config —
+     * is refused, because a Track carries exactly one init segment and the
+     * mismatch would produce fragments that decode against the wrong one.
+     *
+     * Returns `{field, modality, initHash, fragmentCount, coverage: [bigint,
+     * bigint], trackHash, manifestHash}`. `coverage` is `bigint` for the
+     * reason above; `fragmentCount` is the track's total after the append,
+     * not the number passed in.
+     *
+     * **Node only** (`write-full`). This takes every fragment's bytes as an
+     * argument, so peak memory is the whole clip; the native path form streams
+     * fragment-by-fragment off disk, which wasm32 cannot do because it has no
+     * filesystem. Fragmenting a multi-GB source inside a browser tab's 32-bit
+     * address space is not a workflow worth pretending to support.
+     */
+    ingestCmaf(field: string, init: Uint8Array, fragments: Array<any>): Promise<any>;
     /**
      * Open a ref for writing.
      *
@@ -413,6 +540,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/node/dreamdb_bg.wasm.d.ts

@@ -6,6 +6,7 @@ export const __wbg_s3backend_free: (a: number, b: number) => void;
 export const __wbg_space_free: (a: number, b: number) => void;
 export const addressRoundTrip: (a: number, b: number) => [number, number, number, number];
 export const addressVariant: (a: number, b: number) => [number, number, number, number];
+export const authoring_addArrayConstant: (a: number, b: any, c: any) => any;
 export const authoring_addEmbeddingLayer: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: any) => any;
 export const authoring_addField: (a: number, b: any) => any;
 export const authoring_addImageLayer: (a: number, b: number, c: number, d: number, e: number, f: any, g: number, h: number) => any;
@@ -28,9 +29,11 @@ export const multihashBase32: (a: number, b: number) => [number, number];
 export const multihashHex: (a: number, b: number) => [number, number];
 export const rangeHeader: (a: bigint, b: bigint) => [number, number, number, number];
 export const s3backend_get: (a: number, b: number, c: number, d: any) => any;
+export const s3backend_getStream: (a: number, b: number, c: number) => any;
 export const s3backend_list: (a: number, b: number, c: number) => any;
 export const s3backend_new: (a: number, b: number) => number;
 export const space_connectorBase: (a: number) => [number, number];
+export const space_description: (a: number) => any;
 export const space_fromUri: (a: number, b: number, c: any) => any;
 export const space_history: (a: number, b: number) => any;
 export const space_manifestHash: (a: number) => [number, number];
@@ -38,19 +41,29 @@ export const space_queryHybrid: (a: number, b: number, c: number, d: any) => any
 export const space_queryScalar: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
 export const space_queryText: (a: number, b: number, c: number, d: number, e: number, f: number) => any;
 export const space_queryVector: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
+export const space_readArrayColumn: (a: number, b: number, c: number) => any;
+export const space_readArrayConstant: (a: number, b: number, c: number) => any;
 export const space_readScalarColumn: (a: number, b: any, c: any) => any;
+export const space_readVideoItemRange: (a: number, b: number, c: number, d: any, e: any, f: any) => any;
 export const space_resolveObjectIndex: (a: number, b: any) => any;
+export const space_semanticCacheCapacity: (a: number) => any;
+export const space_semanticCacheStats: (a: number) => any;
+export const space_setSemanticCacheCapacity: (a: number, b: number) => any;
 export const space_timelineId: (a: number) => [number, number, number, number];
-export const space_trackFor: (a: number, b: number, c: number) => any;
-export const space_tracks: (a: number) => any;
+export const space_trackFor: (a: number, b: number, c: number) => [number, number, number];
+export const space_tracks: (a: number) => [number, number, number];
+export const space_videoItemAt: (a: number, b: number, c: number, d: any) => any;
+export const space_videoItemByKey: (a: number, b: number, c: number, d: any) => any;
 export const spatialKeyRoundTrip: (a: number, b: number) => [number, number, number, number];
 export const timeAnchorFromHex: (a: number, b: number) => [bigint, number, number];
 export const timeAnchorHex: (a: bigint) => [number, number];
 export const timeBucket: (a: bigint, b: number, c: number) => [bigint, number, number];
+export const typedArrayDecode: (a: any, b: number, c: number) => [number, number, number];
 export const version: () => [number, number];
 export const writer_appendMany: (a: number, b: any) => any;
 export const writer_commit: (a: number) => any;
 export const writer_deleteRecords: (a: number, b: number, c: number, d: number, e: number) => any;
+export const writer_ingestCmaf: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
 export const writer_manifestHash: (a: number) => [number, number, number, number];
 export const writer_open: (a: number, b: number, c: any) => any;
 export const writer_snapshot: (a: number, b: number, c: number) => any;

package/node.mjs

@@ -11,7 +11,7 @@ export const {
   Authoring, S3Backend, Space, Writer, addressRoundTrip,
   addressVariant, bytesToBase32, decodeCbor, encodeCbor, modalityParse,
   multihashBase32, multihashHex, rangeHeader, spatialKeyRoundTrip, timeAnchorFromHex,
-  timeAnchorHex, timeBucket, version, zeroSpatialKey,
+  timeAnchorHex, timeBucket, typedArrayDecode, version, zeroSpatialKey,
 } = mod
 
 /** Zero spatial-key path segment for non-spatial (fragment) object addresses. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamlake/dreamdb",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "DreamDB SDK — isomorphic (browser + Node) read and write, compiled from the Rust core",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -36,7 +36,9 @@
     "node.cjs",
     "browser-extras.mjs",
     "index.d.ts",
-    "README.md"
+    "README.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "sideEffects": [
     "./browser/dreamdb.js",

package/web/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.
  */
@@ -342,9 +431,11 @@ export interface InitOutput {
     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_connectorBase: (a: number) => [number, number];
+    readonly space_description: (a: number) => any;
     readonly space_fromUri: (a: number, b: number, c: any) => any;
     readonly space_history: (a: number, b: number) => any;
     readonly space_manifestHash: (a: number) => [number, number];
@@ -352,15 +443,24 @@ export interface InitOutput {
     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_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_appendMany: (a: number, b: any) => any;
     readonly writer_commit: (a: number) => any;