@net-mesh/sdk 0.19.0

package/dist/cortex.d.ts

@@ -0,0 +1,236 @@
+/**
+ * CortEX + NetDb — typed event-sourced state with reactive watches.
+ *
+ * Wraps the native `@net-mesh/core` CortEX bindings with ergonomic
+ * TypeScript APIs: `AsyncIterable`-shaped watches (so `for await`
+ * works naturally), typed errors via `CortexError` / `NetDbError`
+ * pattern matching, and the `snapshotAndWatch` primitive whose race
+ * fix landed on v2 (see `docs/STORAGE_AND_CORTEX.md`).
+ *
+ * @example
+ * ```typescript
+ * import { NetDb, TaskStatus, CortexError } from '@net-mesh/sdk';
+ *
+ * const db = await NetDb.open({ originHash: 0xABCDEF01, withTasks: true });
+ * const tasks = db.tasks!;
+ *
+ * try {
+ *   tasks.create(1n, 'write docs', 100n);
+ *   await tasks.waitForSeq(seq);
+ * } catch (e) {
+ *   if (e instanceof CortexError) { /* handle adapter-level error *\/ }
+ *   else { throw e; }
+ * }
+ *
+ * // "Paint what's here now, then react to changes":
+ * const { snapshot, updates } = await tasks.snapshotAndWatch({
+ *   status: TaskStatus.Pending,
+ * });
+ * render(snapshot);
+ * for await (const next of updates) render(next);
+ * ```
+ */
+import { TasksAdapter as NapiTasksAdapter, MemoriesAdapter as NapiMemoriesAdapter, RedexFile as NapiRedexFile, TaskStatus, TasksOrderBy, MemoriesOrderBy } from '@net-mesh/core';
+import type { Task, Memory, TaskFilter, MemoryFilter, NetDbOpenConfig, NetDbBundle, CortexSnapshot } from '@net-mesh/core';
+export { TaskStatus, TasksOrderBy, MemoriesOrderBy, };
+export type { Task, Memory, TaskFilter, MemoryFilter, NetDbOpenConfig, NetDbBundle, CortexSnapshot, };
+export { CortexError, NetDbError } from '@net-mesh/core/errors';
+/**
+ * Raised on `redex:` prefixed failures: append / tail / read / sync /
+ * close, invalid channel names, mutually-exclusive config options.
+ * Extends `Error`; catch with `instanceof RedexError`.
+ */
+export declare class RedexError extends Error {
+    constructor(detail?: string);
+}
+/** Construction options for {@link Redex}. */
+export interface RedexOptions {
+    /**
+     * Root directory for disk-backed files. Adapters opened with
+     * `persistent: true` write to `<persistentDir>/<channel>/{idx,dat}`
+     * and replay from disk on reopen. Omit for in-memory only.
+     */
+    persistentDir?: string;
+}
+/**
+ * Local RedEX manager. Holds the set of open files on this process.
+ * Cheap to share; adapters borrow it by reference.
+ */
+export declare class Redex {
+    constructor(opts?: RedexOptions);
+    /**
+     * Open (or get) a raw RedEX file for domain-agnostic persistent
+     * logging. Returns the same handle across repeat calls with the
+     * same `name`; `config` is honored only on first open.
+     *
+     * Use this when you want an append-only event log without the
+     * CortEX fold / typed-adapter layer. Appends, tailing, and range
+     * reads work directly over the file.
+     *
+     * With `config.persistent = true`, this manager must have been
+     * constructed with a `persistentDir`.
+     */
+    openFile(name: string, config?: RedexFileConfig): RedexFile;
+}
+/** Configuration for {@link Redex.openFile}. Mirrors the core
+ *  `RedexFileConfig` field-for-field; the two fsync options are
+ *  mutually exclusive (leave both unset for the default
+ *  `FsyncPolicy::Never`). */
+export interface RedexFileConfig {
+    /** Disk-backed storage. Requires `Redex` to have been constructed
+     *  with `persistentDir`. Default: `false` (heap only). */
+    persistent?: boolean;
+    /** Fsync after every N appends (`1` fsyncs on every append).
+     *  Mutually exclusive with `fsyncIntervalMs`. Ignored unless
+     *  `persistent: true`. */
+    fsyncEveryN?: bigint;
+    /** Fsync on a timer (milliseconds). Mutually exclusive with
+     *  `fsyncEveryN`. Ignored unless `persistent: true`. */
+    fsyncIntervalMs?: number;
+    /** Retain at most N events. */
+    retentionMaxEvents?: bigint;
+    /** Retain at most N bytes of payload. */
+    retentionMaxBytes?: bigint;
+    /** Drop entries older than this many milliseconds at the next
+     *  retention sweep. */
+    retentionMaxAgeMs?: bigint;
+}
+/** A materialized RedEX event. */
+export interface RedexEvent {
+    seq: bigint;
+    payload: Buffer;
+    /** Low-28-bit xxh3 truncation stamped at append time. */
+    checksum: number;
+    /** True if stored inline in the 20-byte entry record. */
+    isInline: boolean;
+}
+/** Raw RedEX file handle. Append, tail, range-read without the
+ *  CortEX adapter layer. */
+export declare class RedexFile {
+    constructor(inner: NapiRedexFile);
+    /** Append one payload. Returns the assigned sequence number. */
+    append(payload: Buffer): bigint;
+    /** Append a batch atomically. Returns the seq of the first event
+     *  (subsequent events are `first + 0, first + 1, ...`), or `null`
+     *  for an empty batch (no seq is allocated when there's nothing to
+     *  append). */
+    appendBatch(payloads: Buffer[]): bigint | null;
+    /** Read the half-open range `[start, end)` from the in-memory
+     *  index. Only retained entries are returned. */
+    readRange(start: bigint, end: bigint): RedexEvent[];
+    /** Number of retained events (post-retention eviction). Returned
+     *  as `bigint` because event counts can exceed `Number.MAX_SAFE_INTEGER`
+     *  (~9 P) in theory — though in practice they'll fit in a `number`,
+     *  the lossless type is the safe surface. */
+    len(): bigint;
+    /** Open a live tail. Yields every event with `seq >= fromSeq`
+     *  (default `0n`) — atomically backfills the retained range and
+     *  then streams appends. Breaking out of `for await` releases the
+     *  native iterator via `return()`. */
+    tail(fromSeq?: bigint): Promise<AsyncIterable<RedexEvent>>;
+    /** Explicit fsync. Always fsyncs regardless of policy; no-op on
+     *  heap-only files. */
+    sync(): void;
+    /** Close the file. Outstanding tail iterators end cleanly on
+     *  their next emission. */
+    close(): void;
+}
+/** Return shape of `snapshotAndWatch` on every adapter. */
+export interface SnapshotAndWatch<T> {
+    /** Initial filter result captured atomically with the watcher. */
+    readonly snapshot: T[];
+    /**
+     * Subsequent filter results. Drops only leading emissions that
+     * equal `snapshot`; any divergent initial emission (caused by a
+     * mutation racing construction) is forwarded through.
+     */
+    readonly updates: AsyncIterable<T[]>;
+}
+/**
+ * Typed tasks adapter. CRUD plus `listTasks` / `watch` /
+ * `snapshotAndWatch` for reactive consumers.
+ */
+export declare class TasksAdapter {
+    constructor(inner: NapiTasksAdapter);
+    /**
+     * Open a standalone tasks adapter against a `Redex`. For bundled
+     * tasks + memories access, prefer {@link NetDb.open}.
+     */
+    static open(redex: Redex, originHash: bigint, opts?: {
+        persistent?: boolean;
+    }): Promise<TasksAdapter>;
+    /** Restore from a snapshot captured via {@link TasksAdapter.snapshot}. */
+    static openFromSnapshot(redex: Redex, originHash: bigint, snapshot: CortexSnapshot, opts?: {
+        persistent?: boolean;
+    }): Promise<TasksAdapter>;
+    create(id: bigint, title: string, nowNs: bigint): bigint;
+    rename(id: bigint, newTitle: string, nowNs: bigint): bigint;
+    complete(id: bigint, nowNs: bigint): bigint;
+    delete(id: bigint): bigint;
+    /** Total count in the materialized state (ignores any filter). */
+    count(): number;
+    /** Wait for the fold task to have applied every event up through `seq`. */
+    waitForSeq(seq: bigint): Promise<void>;
+    /** Snapshot query over the materialized state. */
+    listTasks(filter?: TaskFilter | null): Task[];
+    /** Capture a serialized state snapshot for {@link TasksAdapter.openFromSnapshot}. */
+    snapshot(): CortexSnapshot;
+    /**
+     * Reactive watch. Yields the current filter result first, then once
+     * per fold tick where the result differs from the previous emission.
+     * Breaking out of `for await` calls `close()` automatically.
+     */
+    watch(filter?: TaskFilter | null): Promise<AsyncIterable<Task[]>>;
+    /**
+     * Atomic "paint what's here now, then react to changes." Returns the
+     * snapshot and an `AsyncIterable` of subsequent filter results.
+     *
+     * Prefer this to calling `listTasks` + `watch` separately — they
+     * race each other, and a mutation landing between the two reads
+     * would be silently lost.
+     */
+    snapshotAndWatch(filter?: TaskFilter | null): Promise<SnapshotAndWatch<Task>>;
+}
+/**
+ * Typed memories adapter. CRUD plus `listMemories` / `watch` /
+ * `snapshotAndWatch`.
+ */
+export declare class MemoriesAdapter {
+    constructor(inner: NapiMemoriesAdapter);
+    static open(redex: Redex, originHash: bigint, opts?: {
+        persistent?: boolean;
+    }): Promise<MemoriesAdapter>;
+    static openFromSnapshot(redex: Redex, originHash: bigint, snapshot: CortexSnapshot, opts?: {
+        persistent?: boolean;
+    }): Promise<MemoriesAdapter>;
+    store(id: bigint, content: string, tags: string[], source: string, nowNs: bigint): bigint;
+    retag(id: bigint, tags: string[], nowNs: bigint): bigint;
+    pin(id: bigint, nowNs: bigint): bigint;
+    unpin(id: bigint, nowNs: bigint): bigint;
+    delete(id: bigint): bigint;
+    count(): number;
+    waitForSeq(seq: bigint): Promise<void>;
+    listMemories(filter?: MemoryFilter | null): Memory[];
+    snapshot(): CortexSnapshot;
+    watch(filter?: MemoryFilter | null): Promise<AsyncIterable<Memory[]>>;
+    /** Atomic snapshot + delta stream. See {@link TasksAdapter.snapshotAndWatch}. */
+    snapshotAndWatch(filter?: MemoryFilter | null): Promise<SnapshotAndWatch<Memory>>;
+}
+/**
+ * Unified NetDB handle. Bundles `TasksAdapter` + `MemoriesAdapter`
+ * under one object. Open with both models for the common case, or
+ * with only one if the other isn't needed.
+ */
+export declare class NetDb {
+    private constructor();
+    static open(config: NetDbOpenConfig): Promise<NetDb>;
+    static openFromSnapshot(config: NetDbOpenConfig, bundle: NetDbBundle): Promise<NetDb>;
+    /** The tasks adapter, or `null` if `withTasks` wasn't set at open. */
+    get tasks(): TasksAdapter | null;
+    /** The memories adapter, or `null` if `withMemories` wasn't set. */
+    get memories(): MemoriesAdapter | null;
+    /** Snapshot every enabled model into one bundle. */
+    snapshot(): NetDbBundle;
+    /** Close every enabled adapter. Idempotent. */
+    close(): void;
+}