@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/indexing/index.js

@@ -7,12 +7,12 @@ import {
   decodeIdxId,
   encodeIdxId,
   isIdxId
-} from "../chunk-6PALJTC2.js";
+} from "../chunk-M4CV6BRT.js";
 import {
   CollectionIndexes
-} from "../chunk-C4NOLA5X.js";
-import "../chunk-6P5AJ2ZS.js";
-import "../chunk-OJ64XMPJ.js";
+} from "../chunk-KPZS5QAQ.js";
+import "../chunk-IGJCYUT5.js";
+import "../chunk-BIOUI4HL.js";
 import "../chunk-PZ5AY32C.js";
 
 // src/with-lookup/indexing/active.ts
@@ -42,10 +42,10 @@ function declareAll(persisted, defs) {
   for (const def of defs) {
     if (typeof def === "string") {
       persisted.declare(def);
-    } else if (Array.isArray(def)) {
-      persisted.declareComposite(def);
     } else {
-      persisted.declareComposite(def.fields);
+      const fields = Array.isArray(def) ? def : def.fields;
+      for (const f of fields) persisted.declare(f);
+      persisted.declareComposite(fields);
     }
   }
 }

package/dist/indexing/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/with-lookup/indexing/active.ts"],"sourcesContent":["/**\n * Active indexing strategy factory. Calling `withIndexing()` returns\n * an `IndexStrategy` whose `createState` constructs a real\n * `CollectionIndexes` (eager) or `PersistedCollectionIndex` (lazy)\n * per Collection, depending on the collection's `prefetch` mode and\n * its declared `IndexDef[]`.\n *\n * This module is only reachable through the `@noy-db/hub/indexing`\n * subpath — a consumer that never imports the subpath ships none of\n * this (ESM tree-shaking + hub's `\"sideEffects\": false`).\n */\n\nimport { CollectionIndexes } from './eager-indexes.js'\nimport type { IndexDef } from './eager-indexes.js'\nimport { PersistedCollectionIndex } from './persisted-indexes.js'\nimport type { IndexStrategy, IndexState } from './strategy.js'\n\n/**\n * Build the default indexing strategy. Pass into\n * `createNoydb({ indexStrategy: withIndexing() })` to light up the\n * eager-mode `==/in` fast-path on `.query()` and the full lazy-mode\n * `.lazyQuery()` + rebuild / reconcile / auto-reconcile surface.\n *\n * @example\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withIndexing } from '@noy-db/hub/indexing'\n *\n * const db = await createNoydb({\n *   store, user, secret,\n *   indexStrategy: withIndexing(),\n * })\n * ```\n */\nexport function withIndexing(): IndexStrategy {\n  return {\n    createState({ defs, lazy }) {\n      if (lazy) {\n        const persisted = new PersistedCollectionIndex()\n        declareAll(persisted, defs)\n        return makeLazyState(persisted)\n      }\n      const eager = new CollectionIndexes()\n      for (const def of defs) {\n        if (typeof def === 'string') {\n          eager.declare(def)\n        } else if (Array.isArray(def)) {\n          for (const f of def as readonly string[]) eager.declare(f)\n        } else {\n          for (const f of (def as { fields: readonly string[] }).fields) eager.declare(f)\n        }\n      }\n      return makeEagerState(eager)\n    },\n  }\n}\n\nfunction declareAll(persisted: PersistedCollectionIndex, defs: readonly IndexDef[]): void {\n  for (const def of defs) {\n    if (typeof def === 'string') {\n      persisted.declare(def)\n    } else if (Array.isArray(def)) {\n      persisted.declareComposite(def as readonly string[])\n    } else {\n      persisted.declareComposite((def as { fields: readonly string[] }).fields)\n    }\n  }\n}\n\nfunction makeEagerState(eager: CollectionIndexes): IndexState {\n  return {\n    isEnabled: true,\n    getEagerIndexes: () => eager,\n    getPersistedIndexes: () => null,\n  }\n}\n\nfunction makeLazyState(persisted: PersistedCollectionIndex): IndexState {\n  return {\n    isEnabled: true,\n    getEagerIndexes: () => null,\n    getPersistedIndexes: () => persisted,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkCO,SAAS,eAA8B;AAC5C,SAAO;AAAA,IACL,YAAY,EAAE,MAAM,KAAK,GAAG;AAC1B,UAAI,MAAM;AACR,cAAM,YAAY,IAAI,yBAAyB;AAC/C,mBAAW,WAAW,IAAI;AAC1B,eAAO,cAAc,SAAS;AAAA,MAChC;AACA,YAAM,QAAQ,IAAI,kBAAkB;AACpC,iBAAW,OAAO,MAAM;AACtB,YAAI,OAAO,QAAQ,UAAU;AAC3B,gBAAM,QAAQ,GAAG;AAAA,QACnB,WAAW,MAAM,QAAQ,GAAG,GAAG;AAC7B,qBAAW,KAAK,IAA0B,OAAM,QAAQ,CAAC;AAAA,QAC3D,OAAO;AACL,qBAAW,KAAM,IAAsC,OAAQ,OAAM,QAAQ,CAAC;AAAA,QAChF;AAAA,MACF;AACA,aAAO,eAAe,KAAK;AAAA,IAC7B;AAAA,EACF;AACF;AAEA,SAAS,WAAW,WAAqC,MAAiC;AACxF,aAAW,OAAO,MAAM;AACtB,QAAI,OAAO,QAAQ,UAAU;AAC3B,gBAAU,QAAQ,GAAG;AAAA,IACvB,WAAW,MAAM,QAAQ,GAAG,GAAG;AAC7B,gBAAU,iBAAiB,GAAwB;AAAA,IACrD,OAAO;AACL,gBAAU,iBAAkB,IAAsC,MAAM;AAAA,IAC1E;AAAA,EACF;AACF;AAEA,SAAS,eAAe,OAAsC;AAC5D,SAAO;AAAA,IACL,WAAW;AAAA,IACX,iBAAiB,MAAM;AAAA,IACvB,qBAAqB,MAAM;AAAA,EAC7B;AACF;AAEA,SAAS,cAAc,WAAiD;AACtE,SAAO;AAAA,IACL,WAAW;AAAA,IACX,iBAAiB,MAAM;AAAA,IACvB,qBAAqB,MAAM;AAAA,EAC7B;AACF;","names":[]}
+{"version":3,"sources":["../../src/with-lookup/indexing/active.ts"],"sourcesContent":["/**\n * Active indexing strategy factory. Calling `withIndexing()` returns\n * an `IndexStrategy` whose `createState` constructs a real\n * `CollectionIndexes` (eager) or `PersistedCollectionIndex` (lazy)\n * per Collection, depending on the collection's `prefetch` mode and\n * its declared `IndexDef[]`.\n *\n * This module is only reachable through the `@noy-db/hub/indexing`\n * subpath — a consumer that never imports the subpath ships none of\n * this (ESM tree-shaking + hub's `\"sideEffects\": false`).\n */\n\nimport { CollectionIndexes } from './eager-indexes.js'\nimport type { IndexDef } from './eager-indexes.js'\nimport { PersistedCollectionIndex } from './persisted-indexes.js'\nimport type { IndexStrategy, IndexState } from './strategy.js'\n\n/**\n * Build the default indexing strategy. Pass into\n * `createNoydb({ indexStrategy: withIndexing() })` to light up the\n * eager-mode `==/in` fast-path on `.query()` and the full lazy-mode\n * `.lazyQuery()` + rebuild / reconcile / auto-reconcile surface.\n *\n * @example\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withIndexing } from '@noy-db/hub/indexing'\n *\n * const db = await createNoydb({\n *   store, user, secret,\n *   indexStrategy: withIndexing(),\n * })\n * ```\n */\nexport function withIndexing(): IndexStrategy {\n  return {\n    createState({ defs, lazy }) {\n      if (lazy) {\n        const persisted = new PersistedCollectionIndex()\n        declareAll(persisted, defs)\n        return makeLazyState(persisted)\n      }\n      const eager = new CollectionIndexes()\n      for (const def of defs) {\n        if (typeof def === 'string') {\n          eager.declare(def)\n        } else if (Array.isArray(def)) {\n          for (const f of def as readonly string[]) eager.declare(f)\n        } else {\n          for (const f of (def as { fields: readonly string[] }).fields) eager.declare(f)\n        }\n      }\n      return makeEagerState(eager)\n    },\n  }\n}\n\nfunction declareAll(persisted: PersistedCollectionIndex, defs: readonly IndexDef[]): void {\n  for (const def of defs) {\n    if (typeof def === 'string') {\n      persisted.declare(def)\n    } else {\n      const fields = Array.isArray(def) ? (def as readonly string[]) : (def as { fields: readonly string[] }).fields\n      // #698: decompose a composite into its component single-field indexes\n      // (like the eager branch above), so a composite-only declaration still\n      // provides the single-field driver the #696 Via-covered fall-through\n      // and single-field queries need. The composite mirror is kept for the\n      // multi-field fast path.\n      for (const f of fields) persisted.declare(f)\n      persisted.declareComposite(fields)\n    }\n  }\n}\n\nfunction makeEagerState(eager: CollectionIndexes): IndexState {\n  return {\n    isEnabled: true,\n    getEagerIndexes: () => eager,\n    getPersistedIndexes: () => null,\n  }\n}\n\nfunction makeLazyState(persisted: PersistedCollectionIndex): IndexState {\n  return {\n    isEnabled: true,\n    getEagerIndexes: () => null,\n    getPersistedIndexes: () => persisted,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkCO,SAAS,eAA8B;AAC5C,SAAO;AAAA,IACL,YAAY,EAAE,MAAM,KAAK,GAAG;AAC1B,UAAI,MAAM;AACR,cAAM,YAAY,IAAI,yBAAyB;AAC/C,mBAAW,WAAW,IAAI;AAC1B,eAAO,cAAc,SAAS;AAAA,MAChC;AACA,YAAM,QAAQ,IAAI,kBAAkB;AACpC,iBAAW,OAAO,MAAM;AACtB,YAAI,OAAO,QAAQ,UAAU;AAC3B,gBAAM,QAAQ,GAAG;AAAA,QACnB,WAAW,MAAM,QAAQ,GAAG,GAAG;AAC7B,qBAAW,KAAK,IAA0B,OAAM,QAAQ,CAAC;AAAA,QAC3D,OAAO;AACL,qBAAW,KAAM,IAAsC,OAAQ,OAAM,QAAQ,CAAC;AAAA,QAChF;AAAA,MACF;AACA,aAAO,eAAe,KAAK;AAAA,IAC7B;AAAA,EACF;AACF;AAEA,SAAS,WAAW,WAAqC,MAAiC;AACxF,aAAW,OAAO,MAAM;AACtB,QAAI,OAAO,QAAQ,UAAU;AAC3B,gBAAU,QAAQ,GAAG;AAAA,IACvB,OAAO;AACL,YAAM,SAAS,MAAM,QAAQ,GAAG,IAAK,MAA6B,IAAsC;AAMxG,iBAAW,KAAK,OAAQ,WAAU,QAAQ,CAAC;AAC3C,gBAAU,iBAAiB,MAAM;AAAA,IACnC;AAAA,EACF;AACF;AAEA,SAAS,eAAe,OAAsC;AAC5D,SAAO;AAAA,IACL,WAAW;AAAA,IACX,iBAAiB,MAAM;AAAA,IACvB,qBAAqB,MAAM;AAAA,EAC7B;AACF;AAEA,SAAS,cAAc,WAAiD;AACtE,SAAO;AAAA,IACL,WAAW;AAAA,IACX,iBAAiB,MAAM;AAAA,IACvB,qBAAqB,MAAM;AAAA,EAC7B;AACF;","names":[]}

package/dist/issue-5OKB6I2R.js

@@ -0,0 +1,19 @@
+import {
+  issueAttestationCore
+} from "./chunk-GTGPO5KW.js";
+import "./chunk-EXK7QRWF.js";
+import "./chunk-ZJADGNYF.js";
+import "./chunk-XDYREZWE.js";
+import "./chunk-7DSTRQIJ.js";
+import "./chunk-HB3RFQSC.js";
+import "./chunk-JKJOGPZN.js";
+import "./chunk-5M5DVGV7.js";
+import "./chunk-LP7BEXCT.js";
+import "./chunk-CIE2BASH.js";
+import "./chunk-JNAI2HN2.js";
+import "./chunk-BIOUI4HL.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  issueAttestationCore
+};
+//# sourceMappingURL=issue-5OKB6I2R.js.map

package/dist/kernel/best-effort-revert.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Best-effort reverse-revert — the shape shared by two independent rollback
+ * paths that used to duplicate it: satellite fan-out
+ * (`with-shape/satellites/fanout.ts`'s `revertAndCompensate`) and
+ * multi-record transactions (`with-commit/tx/transaction.ts`'s
+ * `revertExecuted`). Both revert a list of already-executed writes on
+ * failure by walking them in REVERSE order and, per leg, restoring the
+ * captured prior envelope straight through the raw adapter — `put(prior)`
+ * when one existed, `delete` when the leg was a fresh insert — bypassing
+ * the Collection layer so the revert itself doesn't re-fire
+ * encryption/ledger/change-event machinery. Each leg's raw-adapter revert
+ * is best-effort: a throw is swallowed so a revert-path failure never masks
+ * the original error that triggered the rollback, and the loop moves on to
+ * the next leg.
+ *
+ * An optional per-leg `compensate` callback runs immediately after a
+ * successful raw-adapter revert (still inside the same try, so a throwing
+ * callback is swallowed the same way as a throwing raw revert). What the
+ * callback does is entirely caller-defined — satellites' fan-out fires
+ * `_compensateRevertedWrite` only for legs whose write actually landed
+ * (#596); with-commit's transaction executor invalidates the Collection
+ * cache. Neither concern belongs here: this helper only knows the generic
+ * reverse/best-effort/raw-revert shape.
+ *
+ * Lives in `kernel/` — not a `with-*` service — so both consumers (one a
+ * gated service, `with-commit`; one an always-on schema feature,
+ * `with-shape/satellites`) can import it without creating a
+ * `with-* → with-*` edge, which would force either family to always bundle
+ * the other and defeat the opt-in tree-shaking both are built around.
+ *
+ * @internal — implementation-sharing only, not part of the public surface.
+ */
+import type { EncryptedEnvelope } from './types.js';
+/** One already-executed write a revert pass needs to unwind. */
+export interface BestEffortRevertLeg {
+    readonly vaultName: string;
+    readonly collectionName: string;
+    readonly id: string;
+    /** Envelope captured before the write, or `null` if the id didn't exist yet. */
+    readonly prior: EncryptedEnvelope | null;
+}
+/** The subset of `NoydbStore` a raw-adapter revert needs. */
+export interface BestEffortRevertAdapter {
+    put(vaultName: string, collectionName: string, id: string, envelope: EncryptedEnvelope): Promise<void>;
+    delete(vaultName: string, collectionName: string, id: string): Promise<void>;
+}
+/**
+ * Revert `executed` in reverse order via the raw adapter, best-effort.
+ * `compensate`, when supplied, runs once per leg immediately after that
+ * leg's own raw revert succeeds.
+ */
+export declare function bestEffortRevert<T extends BestEffortRevertLeg>(executed: readonly T[], adapter: BestEffortRevertAdapter, compensate?: (leg: T) => Promise<void> | void): Promise<void>;

package/dist/kernel/cache/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cache module — barrel export.
+ *
+ * Tree-shakeable: importing this barrel without setting `cache:` on a
+ * Collection does not pull in the LRU runtime, since `Lru` is the only
+ * entry point.
+ */
+export { Lru } from './lru.js';
+export type { LruEntry, LruOptions, LruStats } from './lru.js';
+export { parseBytes, estimateRecordBytes } from './policy.js';

package/dist/kernel/cache/lru.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Generic LRU cache for `Collection`'s lazy hydration mode.
+ *
+ * Backed by a JavaScript `Map`, which preserves insertion order. Promotion
+ * is implemented as `delete()` + `set()` — O(1) on `Map` since both
+ * operations are constant-time. Eviction walks the iterator from the front
+ * (least recently used) until both budgets are satisfied.
+ *
+ * ships in-memory only. The cache is never persisted; on collection
+ * close every entry is dropped. Persisting cache state is a follow-up
+ * once the access patterns from real consumers tell us whether it would
+ * pay back the complexity.
+ */
+export interface LruEntry<V> {
+    /** The cached value. */
+    readonly value: V;
+    /**
+     * Approximate decrypted byte size of the entry. Used by the byte-budget
+     * eviction path. Callers compute this once at insert time and pass it
+     * in — recomputing on every access would dominate the per-record cost.
+     */
+    readonly size: number;
+}
+export interface LruOptions {
+    /** Maximum number of entries before eviction. Required if `maxBytes` is unset. */
+    maxRecords?: number;
+    /** Maximum total bytes before eviction. Computed from per-entry `size`. */
+    maxBytes?: number;
+}
+export interface LruStats {
+    /** Total cache hits since construction (or `resetStats()`). */
+    hits: number;
+    /** Total cache misses since construction (or `resetStats()`). */
+    misses: number;
+    /** Total entries evicted since construction (or `resetStats()`). */
+    evictions: number;
+    /** Current number of cached entries. */
+    size: number;
+    /** Current sum of cached entry sizes (in bytes, approximate). */
+    bytes: number;
+}
+/**
+ * O(1) LRU cache. Both `get()` and `set()` promote the touched entry to
+ * the most-recently-used end. Eviction happens after every insert and
+ * walks the front of the Map iterator dropping entries until both
+ * budgets are satisfied.
+ */
+export declare class Lru<K, V> {
+    private readonly entries;
+    private readonly maxRecords;
+    private readonly maxBytes;
+    private currentBytes;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(options: LruOptions);
+    /**
+     * Look up a key. Hits promote the entry to most-recently-used; misses
+     * return undefined. Both update the running stats counters.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Insert or update a key. If the key already exists, its size is
+     * accounted for and the entry is promoted to MRU. After insertion,
+     * eviction runs to maintain both budgets.
+     */
+    set(key: K, value: V, size: number): void;
+    /**
+     * Remove a key without affecting hit/miss stats. Used by `Collection.delete()`.
+     * Returns true if the key was present.
+     */
+    remove(key: K): boolean;
+    /** True if the cache currently holds an entry for the given key. */
+    has(key: K): boolean;
+    /**
+     * Drop every entry. Stats counters survive — call `resetStats()` if you
+     * want a clean slate. Used by `Collection.invalidate()` on key rotation.
+     */
+    clear(): void;
+    /** Reset hit/miss/eviction counters to zero. Does NOT touch entries. */
+    resetStats(): void;
+    /** Snapshot of current cache statistics. Cheap — no copying. */
+    stats(): LruStats;
+    /**
+     * Iterate over all currently-cached values. Order is least-recently-used
+     * first. Used by tests and devtools — production callers should use
+     * `Collection.scan()` instead.
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Walk the cache from the LRU end and drop entries until both budgets
+     * are satisfied. Called after every `set()`. Single pass — entries are
+     * never re-promoted during eviction.
+     */
+    private evictUntilUnderBudget;
+    private overBudget;
+}

package/dist/kernel/cache/policy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cache policy helpers — parse human-friendly byte budgets into raw numbers.
+ *
+ * Accepted shapes (case-insensitive on suffix):
+ *   number       — interpreted as raw bytes
+ *   '1024'       — string of digits, raw bytes
+ *   '50KB'       — kilobytes (×1024)
+ *   '50MB'       — megabytes (×1024²)
+ *   '1GB'        — gigabytes (×1024³)
+ *
+ * Decimals are accepted (`'1.5GB'` → 1610612736 bytes).
+ *
+ * Anything else throws — better to fail loud at construction time than
+ * to silently treat a typo as 0 bytes (which would evict everything).
+ */
+/** Parse a byte budget into a positive integer number of bytes. */
+export declare function parseBytes(input: number | string): number;
+/**
+ * Estimate the in-memory byte size of a decrypted record.
+ *
+ * Uses `JSON.stringify().length` as a stand-in for actual heap usage.
+ * It's a deliberate approximation: real V8 heap size includes pointer
+ * overhead, hidden classes, and string interning that we can't measure
+ * from JavaScript. The JSON length is a stable, monotonic proxy that
+ * costs O(record size) per insert — fine when records are typically
+ * < 1 KB and the cache eviction is the slow path anyway.
+ *
+ * Returns `0` (and the caller must treat it as 1 for accounting) if
+ * stringification throws on circular references; this is documented
+ * but in practice records always come from JSON-decoded envelopes.
+ */
+export declare function estimateRecordBytes(record: unknown): number;