@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/materialized-views/index.d.cts

@@ -1,19 +1,20 @@
-export { w as withMaterializedView } from '../with-materialized-view-BbEPFIIJ.cjs';
-import { aH as Collection, at as TxContext, bi as MVQueryContext, bj as RegisteredMV, bk as MaterializedViewRegistry } from '../types-DJG8HG6F.cjs';
-export { bl as MaterializedFromMeta, bm as MaterializedViewOutput, aE as MaterializedViewStrategy, aF as MaterializedViewStrategyHandle, bn as UnionSource } from '../types-DJG8HG6F.cjs';
-import { Q as Query } from '../index-BMjrzNZr.cjs';
-export { t as MaterializedViewConfigError, u as MaterializedViewCycleError, v as MaterializedViewSourceUnknownError, w as MaterializedViewTooLargeError } from '../index-BMjrzNZr.cjs';
-import '../lazy-builder-C-rPfWG0.cjs';
-import '../predicate-Dnu81tsS.cjs';
-import '../strategy-DSTrsZ8t.cjs';
+export { w as withMaterializedView } from '../with-materialized-view-CeZYGJVf.cjs';
+import { aN as Collection, bk as TxContext, bl as MVQueryContext, bm as RegisteredMV, bn as MaterializedViewRegistry } from '../types-DyOI6XZ_.cjs';
+export { bo as MaterializedFromMeta, bp as MaterializedViewOutput, aK as MaterializedViewStrategy, aL as MaterializedViewStrategyHandle, bq as UnionArmJoin, br as UnionSource } from '../types-DyOI6XZ_.cjs';
+import { Q as Query } from '../index-tZqVB9g5.cjs';
+export { z as MaterializedViewConfigError, C as MaterializedViewCycleError, E as MaterializedViewSourceUnknownError, G as MaterializedViewTooLargeError } from '../errors-Dkc_fi-S.cjs';
+import '../lazy-builder-eYZzLEL1.cjs';
+import '../predicate-BmhBSPCH.cjs';
+import '../strategy-WtB-jXYv.cjs';
 import '../strategy-BSxFXGzb.cjs';
+import '../index-BMmajblo.cjs';
 import '@noy-db/attestation';
 
 /**
  * Accessor shape passed in from the owning Vault. Mirrors v1's
  * `DerivationStaleAccessor` — provides the per-collection resolver
  * and the active TxContext so refresh writes/tombstones register on
- * `_executed` for #133-style rollback symmetry.
+ * `_executed` for rollback symmetry.
  */
 interface MVExecutorAccessor {
     getCollection(name: string): Collection<any>;
@@ -44,22 +45,22 @@ interface RefreshResult {
  *
  * Stamps `_materializedFrom` onto every emitted row.
  *
- * **Tombstoning** (#152): when `spec.onEmpty: 'delete'` (default), rows
+ * **Tombstoning:** when `spec.onEmpty: 'delete'` (default), rows
  * that existed in a prior refresh but no longer appear in the new
  * materialized result are deleted via `Collection._internalDelete` —
- * the housekeeping bypass primitive added in PR #148 prevents user
+ * the housekeeping bypass primitive prevents user
  * `onDelete` guards on the output collection from firing on these
  * system-internal deletes. `onEmpty: 'keep'` opts out (rows from
  * prior refreshes linger even when the new result lacks them).
  *
- * **Cost ceiling** (#152): if the materialized row count exceeds
+ * **Cost ceiling:** if the materialized row count exceeds
  * `spec.maxRows` (default 100k), throws `MaterializedViewTooLargeError`
  * before any writes hit the store — so strict-mode rollback is
  * clean.
  *
- * **Strict mode** (#152): `spec.strict === true` re-throws on any
+ * **Strict mode:** `spec.strict === true` re-throws on any
  * row-write failure; the active TxContext registration means the
- * source-write rolls back atomically via `revertExecuted` (#133).
+ * source-write rolls back atomically via `revertExecuted`.
  *
  * @internal
  */
@@ -71,14 +72,16 @@ declare const MaterializedViewExecutor: {
  * Walks a `Query<T>` plan and returns the set of source collection
  * names that any source-write should trigger a refresh on.
  *
- * Foundation sub-issue (#150) handles:
+ * Handles:
  *   - root collection (the one the query was built from)
  *   - FK join targets (`.join(field, { as })`)
  *
- * Deferred to later sub-issues:
- *   - `.crossJoin()` — v3 cross-join spec (separate primitive)
- *   - `.wherePredicate(name)` — v2 predicate primitive, sub-issue #153
- *   - Overlay-name expansion to {base, overlay} — sub-issue #154
+ * Also handles:
+ *   - cross-join targets (`.crossJoin(target, { as })`) — v3
+ *
+ * Deferred:
+ *   - `.wherePredicate(name)` — v2 predicate primitive
+ *   - Overlay-name expansion to {base, overlay}
  *
  * The set is materialized at MV registration time. The MV registry
  * uses it to (a) dispatch `onSourceWrite` only to MVs that actually
@@ -167,7 +170,7 @@ declare function isMVStale(registry: MaterializedViewRegistry, mvName: string):
  *
  * Dynamic-imports the executor only when a stale flag actually fires
  * (the floor-bundle isolation pattern v1 derivations established in
- * #130).
+ * floor-bundle isolation pattern).
  */
 declare function resolveStaleMVOnRead(accessor: MVStaleAccessor, outputCollection: string): Promise<void>;
 /**

package/dist/materialized-views/index.d.ts

@@ -1,19 +1,20 @@
-export { w as withMaterializedView } from '../with-materialized-view-CqnRwI2S.js';
-import { aH as Collection, at as TxContext, bi as MVQueryContext, bj as RegisteredMV, bk as MaterializedViewRegistry } from '../types-BoFFiskX.js';
-export { bl as MaterializedFromMeta, bm as MaterializedViewOutput, aE as MaterializedViewStrategy, aF as MaterializedViewStrategyHandle, bn as UnionSource } from '../types-BoFFiskX.js';
-import { Q as Query } from '../index-BCKdioeh.js';
-export { t as MaterializedViewConfigError, u as MaterializedViewCycleError, v as MaterializedViewSourceUnknownError, w as MaterializedViewTooLargeError } from '../index-BCKdioeh.js';
-import '../lazy-builder-Rpd-V3jP.js';
-import '../predicate-Dnu81tsS.js';
-import '../strategy-DSTrsZ8t.js';
+export { w as withMaterializedView } from '../with-materialized-view-DNULSxoP.js';
+import { aN as Collection, bk as TxContext, bl as MVQueryContext, bm as RegisteredMV, bn as MaterializedViewRegistry } from '../types-DLfWFr6U.js';
+export { bo as MaterializedFromMeta, bp as MaterializedViewOutput, aK as MaterializedViewStrategy, aL as MaterializedViewStrategyHandle, bq as UnionArmJoin, br as UnionSource } from '../types-DLfWFr6U.js';
+import { Q as Query } from '../index-Bm9hIY7t.js';
+export { z as MaterializedViewConfigError, C as MaterializedViewCycleError, E as MaterializedViewSourceUnknownError, G as MaterializedViewTooLargeError } from '../errors-Dkc_fi-S.js';
+import '../lazy-builder-ChSqcF5t.js';
+import '../predicate-BmhBSPCH.js';
+import '../strategy-54eIwox5.js';
 import '../strategy-BSxFXGzb.js';
+import '../index-BMmajblo.js';
 import '@noy-db/attestation';
 
 /**
  * Accessor shape passed in from the owning Vault. Mirrors v1's
  * `DerivationStaleAccessor` — provides the per-collection resolver
  * and the active TxContext so refresh writes/tombstones register on
- * `_executed` for #133-style rollback symmetry.
+ * `_executed` for rollback symmetry.
  */
 interface MVExecutorAccessor {
     getCollection(name: string): Collection<any>;
@@ -44,22 +45,22 @@ interface RefreshResult {
  *
  * Stamps `_materializedFrom` onto every emitted row.
  *
- * **Tombstoning** (#152): when `spec.onEmpty: 'delete'` (default), rows
+ * **Tombstoning:** when `spec.onEmpty: 'delete'` (default), rows
  * that existed in a prior refresh but no longer appear in the new
  * materialized result are deleted via `Collection._internalDelete` —
- * the housekeeping bypass primitive added in PR #148 prevents user
+ * the housekeeping bypass primitive prevents user
  * `onDelete` guards on the output collection from firing on these
  * system-internal deletes. `onEmpty: 'keep'` opts out (rows from
  * prior refreshes linger even when the new result lacks them).
  *
- * **Cost ceiling** (#152): if the materialized row count exceeds
+ * **Cost ceiling:** if the materialized row count exceeds
  * `spec.maxRows` (default 100k), throws `MaterializedViewTooLargeError`
  * before any writes hit the store — so strict-mode rollback is
  * clean.
  *
- * **Strict mode** (#152): `spec.strict === true` re-throws on any
+ * **Strict mode:** `spec.strict === true` re-throws on any
  * row-write failure; the active TxContext registration means the
- * source-write rolls back atomically via `revertExecuted` (#133).
+ * source-write rolls back atomically via `revertExecuted`.
  *
  * @internal
  */
@@ -71,14 +72,16 @@ declare const MaterializedViewExecutor: {
  * Walks a `Query<T>` plan and returns the set of source collection
  * names that any source-write should trigger a refresh on.
  *
- * Foundation sub-issue (#150) handles:
+ * Handles:
  *   - root collection (the one the query was built from)
  *   - FK join targets (`.join(field, { as })`)
  *
- * Deferred to later sub-issues:
- *   - `.crossJoin()` — v3 cross-join spec (separate primitive)
- *   - `.wherePredicate(name)` — v2 predicate primitive, sub-issue #153
- *   - Overlay-name expansion to {base, overlay} — sub-issue #154
+ * Also handles:
+ *   - cross-join targets (`.crossJoin(target, { as })`) — v3
+ *
+ * Deferred:
+ *   - `.wherePredicate(name)` — v2 predicate primitive
+ *   - Overlay-name expansion to {base, overlay}
  *
  * The set is materialized at MV registration time. The MV registry
  * uses it to (a) dispatch `onSourceWrite` only to MVs that actually
@@ -167,7 +170,7 @@ declare function isMVStale(registry: MaterializedViewRegistry, mvName: string):
  *
  * Dynamic-imports the executor only when a stale flag actually fires
  * (the floor-bundle isolation pattern v1 derivations established in
- * #130).
+ * floor-bundle isolation pattern).
  */
 declare function resolveStaleMVOnRead(accessor: MVStaleAccessor, outputCollection: string): Promise<void>;
 /**

package/dist/materialized-views/index.js

@@ -1,30 +1,31 @@
 import {
   withMaterializedView
-} from "../chunk-RTZVQAJ7.js";
+} from "../chunk-6QE4DUYC.js";
 import {
   MaterializedViewExecutor
-} from "../chunk-Y2RKOPNC.js";
+} from "../chunk-5YTXYPES.js";
 import {
   MaterializedViewRegistry,
   analyzeDependencies,
   canonicalizeQueryPlan,
   computeQueryHash,
   summarizeQueryPlan
-} from "../chunk-TBKOGSYR.js";
+} from "../chunk-KOAJ3TZM.js";
 import {
   clearMVStale,
   isMVStale,
   markMVStale,
   resolveStaleMVOnRead
-} from "../chunk-PLI5TV7N.js";
-import "../chunk-VRBCTEKQ.js";
-import "../chunk-MRIBLZL3.js";
+} from "../chunk-IW4L4X65.js";
+import "../chunk-JYNH4FIM.js";
+import "../chunk-U2XSUCDF.js";
+import "../chunk-TNH5SLCD.js";
 import {
   MaterializedViewConfigError,
   MaterializedViewCycleError,
   MaterializedViewSourceUnknownError,
   MaterializedViewTooLargeError
-} from "../chunk-W3XXT26A.js";
+} from "../chunk-OTWT6BAJ.js";
 export {
   MaterializedViewConfigError,
   MaterializedViewCycleError,

package/dist/mime-magic-BnJCGJzB.d.cts

@@ -0,0 +1,103 @@
+import { V as ObjectProjection } from './types-DyOI6XZ_.cjs';
+
+/**
+ * Import / bootstrap (reverse projection) — walk an existing bucket/prefix in an
+ * {@link ObjectProjection} and build a master collection where each record
+ * anchors one object, restoring the record-anchoring invariant for objects that
+ * pre-date noy-db (or were written by another system). See as-aws-s3 §3.8.
+ *
+ * Idempotent: re-running re-adopts the same objects under the same record ids.
+ */
+
+/** Minimal collection surface this utility needs (avoids importing the kernel). */
+interface ImportableCollection {
+    get(id: string): Promise<unknown>;
+    put(id: string, record: unknown): Promise<unknown>;
+    blob(id: string): {
+        adoptExternal(slot: string, ref: {
+            key: string;
+            size?: number;
+            contentType?: string;
+            public?: boolean;
+            backlink?: string;
+        }): Promise<void>;
+    };
+}
+interface ImportExternalOptions {
+    /** Only consider objects under this key prefix. Default `''` (all). */
+    prefix?: string;
+    /**
+     * Derive the record id for an object key. Default: the path segment before
+     * the last — i.e. `{collection}/{recordId}/{field}` → `recordId`. Return
+     * `null` to skip the object.
+     */
+    deriveRecordId?: (key: string) => string | null;
+    /** Build the anchor record for a new id. Default `{ id }`. */
+    makeRecord?: (id: string) => unknown;
+}
+interface ImportExternalResult {
+    imported: number;
+    skipped: number;
+    recordIds: string[];
+}
+/**
+ * Build/extend `collection` from the objects under `prefix` in `objectStore`,
+ * adopting each as the `field` blob on its derived record.
+ */
+declare function importExternalObjects(args: {
+    collection: ImportableCollection;
+    objectStore: ObjectProjection;
+    field: string;
+    options?: ImportExternalOptions;
+}): Promise<ImportExternalResult>;
+
+/**
+ * Lightweight MIME type detection from magic bytes (file signatures).
+ *
+ * Designed for the blob store's auto-detection feature. Operates on the first 16 bytes of
+ * plaintext — no filesystem access, no filename guessing.
+ *
+ * ## Detection strategies
+ *
+ * 1. **Prefix match** — magic bytes at offset 0 (most formats).
+ * 2. **Offset match** — magic bytes at a fixed offset > 0 (ISOBMFF: offset 4).
+ * 3. **Compound match** — two separate byte sequences at different offsets
+ *    (RIFF-based: bytes 0-3 + bytes 8-11).
+ *
+ * ## Formats excluded (require offset > 16 bytes)
+ *
+ * - TAR (`ustar` at offset 257)
+ * - ISO 9660 (`CD001` at offset 32769)
+ *
+ * @module
+ */
+/**
+ * Detect MIME type from the first bytes of a file.
+ *
+ * @param header - The first 16 bytes (or more) of the plaintext. Passing
+ *   fewer than 16 bytes may miss compound and offset-based matches.
+ * @returns Detected MIME type, or `'application/octet-stream'` if unknown.
+ */
+declare function detectMimeType(header: Uint8Array): string;
+/**
+ * Detect MIME type and whether the format is already compressed.
+ *
+ * Used by `BlobSet.put()` to decide whether to skip gzip compression.
+ *
+ * @param header - The first 16 bytes (or more) of the plaintext.
+ * @returns `{ mime, preCompressed }` or `null` if no match.
+ */
+declare function detectMagic(header: Uint8Array): {
+    mime: string;
+    format: string;
+    preCompressed: boolean;
+} | null;
+/**
+ * Check whether a format is already compressed (should skip gzip).
+ *
+ * @param mimeType - A MIME type string.
+ * @returns `true` if the format is known to be pre-compressed.
+ */
+declare function isPreCompressed(mimeType: string): boolean;
+
+export { type ImportExternalOptions as I, type ImportExternalResult as a, type ImportableCollection as b, detectMimeType as c, detectMagic as d, isPreCompressed as e, importExternalObjects as i };

package/dist/mime-magic-CjSyakO4.d.ts

@@ -0,0 +1,103 @@
+import { V as ObjectProjection } from './types-DLfWFr6U.js';
+
+/**
+ * Import / bootstrap (reverse projection) — walk an existing bucket/prefix in an
+ * {@link ObjectProjection} and build a master collection where each record
+ * anchors one object, restoring the record-anchoring invariant for objects that
+ * pre-date noy-db (or were written by another system). See as-aws-s3 §3.8.
+ *
+ * Idempotent: re-running re-adopts the same objects under the same record ids.
+ */
+
+/** Minimal collection surface this utility needs (avoids importing the kernel). */
+interface ImportableCollection {
+    get(id: string): Promise<unknown>;
+    put(id: string, record: unknown): Promise<unknown>;
+    blob(id: string): {
+        adoptExternal(slot: string, ref: {
+            key: string;
+            size?: number;
+            contentType?: string;
+            public?: boolean;
+            backlink?: string;
+        }): Promise<void>;
+    };
+}
+interface ImportExternalOptions {
+    /** Only consider objects under this key prefix. Default `''` (all). */
+    prefix?: string;
+    /**
+     * Derive the record id for an object key. Default: the path segment before
+     * the last — i.e. `{collection}/{recordId}/{field}` → `recordId`. Return
+     * `null` to skip the object.
+     */
+    deriveRecordId?: (key: string) => string | null;
+    /** Build the anchor record for a new id. Default `{ id }`. */
+    makeRecord?: (id: string) => unknown;
+}
+interface ImportExternalResult {
+    imported: number;
+    skipped: number;
+    recordIds: string[];
+}
+/**
+ * Build/extend `collection` from the objects under `prefix` in `objectStore`,
+ * adopting each as the `field` blob on its derived record.
+ */
+declare function importExternalObjects(args: {
+    collection: ImportableCollection;
+    objectStore: ObjectProjection;
+    field: string;
+    options?: ImportExternalOptions;
+}): Promise<ImportExternalResult>;
+
+/**
+ * Lightweight MIME type detection from magic bytes (file signatures).
+ *
+ * Designed for the blob store's auto-detection feature. Operates on the first 16 bytes of
+ * plaintext — no filesystem access, no filename guessing.
+ *
+ * ## Detection strategies
+ *
+ * 1. **Prefix match** — magic bytes at offset 0 (most formats).
+ * 2. **Offset match** — magic bytes at a fixed offset > 0 (ISOBMFF: offset 4).
+ * 3. **Compound match** — two separate byte sequences at different offsets
+ *    (RIFF-based: bytes 0-3 + bytes 8-11).
+ *
+ * ## Formats excluded (require offset > 16 bytes)
+ *
+ * - TAR (`ustar` at offset 257)
+ * - ISO 9660 (`CD001` at offset 32769)
+ *
+ * @module
+ */
+/**
+ * Detect MIME type from the first bytes of a file.
+ *
+ * @param header - The first 16 bytes (or more) of the plaintext. Passing
+ *   fewer than 16 bytes may miss compound and offset-based matches.
+ * @returns Detected MIME type, or `'application/octet-stream'` if unknown.
+ */
+declare function detectMimeType(header: Uint8Array): string;
+/**
+ * Detect MIME type and whether the format is already compressed.
+ *
+ * Used by `BlobSet.put()` to decide whether to skip gzip compression.
+ *
+ * @param header - The first 16 bytes (or more) of the plaintext.
+ * @returns `{ mime, preCompressed }` or `null` if no match.
+ */
+declare function detectMagic(header: Uint8Array): {
+    mime: string;
+    format: string;
+    preCompressed: boolean;
+} | null;
+/**
+ * Check whether a format is already compressed (should skip gzip).
+ *
+ * @param mimeType - A MIME type string.
+ * @returns `true` if the format is known to be pre-compressed.
+ */
+declare function isPreCompressed(mimeType: string): boolean;
+
+export { type ImportExternalOptions as I, type ImportExternalResult as a, type ImportableCollection as b, detectMimeType as c, detectMagic as d, isPreCompressed as e, importExternalObjects as i };

package/dist/noydb-ZZCRF6TE.js

@@ -0,0 +1,38 @@
+import {
+  Noydb,
+  createNoydb
+} from "./chunk-7PH4OPBZ.js";
+import "./chunk-ZC7J6ZYV.js";
+import "./chunk-EMIGCR7X.js";
+import "./chunk-IY24WS2P.js";
+import "./chunk-MBXKRHSS.js";
+import "./chunk-NV4IHBZS.js";
+import "./chunk-2XA2ZML4.js";
+import "./chunk-3HNKR65T.js";
+import "./chunk-GJTKMME7.js";
+import "./chunk-ZONKSLF2.js";
+import "./chunk-JYNH4FIM.js";
+import "./chunk-U2XSUCDF.js";
+import "./chunk-C6W5KVDV.js";
+import "./chunk-JOK73NDT.js";
+import "./chunk-BZW5IL43.js";
+import "./chunk-I3IYTUUI.js";
+import "./chunk-UF3BUNQZ.js";
+import "./chunk-O5XKZCUD.js";
+import "./chunk-TNH5SLCD.js";
+import "./chunk-HYJMAV53.js";
+import "./chunk-F5GWNSE2.js";
+import "./chunk-FRRJIUSI.js";
+import "./chunk-2QR2PQTT.js";
+import "./chunk-FZU343FL.js";
+import "./chunk-JDCPRJVS.js";
+import "./chunk-PDVP3C2I.js";
+import "./chunk-CQYEDODS.js";
+import "./chunk-TA6HPKWQ.js";
+import "./chunk-37VGJM3T.js";
+import "./chunk-OTWT6BAJ.js";
+export {
+  Noydb,
+  createNoydb
+};
+//# sourceMappingURL=noydb-ZZCRF6TE.js.map

package/dist/overlay-views/index.cjs

@@ -158,6 +158,16 @@ var OverlayedViewRegistry = class {
   isOverlay(name) {
     return this._byName.has(name);
   }
+  /**
+   * All registered overlay strategies as a flat array.
+   * Each strategy carries `name`, `base`, and `overlay` fields that
+   * `describeOverlays()` in the introspection walker reads directly.
+   *
+   * Used by `dumpSchema()` to populate the `overlayViews` map.
+   */
+  all() {
+    return [...this._byName.values()];
+  }
   /**
    * Resolve the `rowKey` function for an overlay's base MV. Returns
    * `undefined` if the base isn't an MV (raw source collection) or
@@ -207,37 +217,34 @@ var OverlayedCollection = class {
   /** Get the merged row by id. */
   async get(id) {
     const overlayRow = await this.overlayCollection.get(id);
-    if (overlayRow !== null && this.shadowPredicateApplies(overlayRow)) {
-      return overlayRow;
-    }
     const baseRow = await this.baseCollection.get(id);
-    if (baseRow !== null) return baseRow;
-    return null;
+    return this.mergeRows(overlayRow, baseRow);
   }
   /** List union of base + overlay ids, applying the merge per row. */
   async list() {
     const baseRows = await this.baseCollection.list();
     const overlayRows = await this.overlayCollection.list();
-    const merged = /* @__PURE__ */ new Map();
     const idOf = (row) => {
       if (this.baseRowKey) return this.baseRowKey(row);
       const idField = row.id;
       return typeof idField === "string" ? idField : "";
     };
+    const baseById = /* @__PURE__ */ new Map();
+    const overlayById = /* @__PURE__ */ new Map();
     for (const row of baseRows) {
       const id = idOf(row);
-      if (id) merged.set(id, row);
+      if (id) baseById.set(id, row);
     }
     for (const row of overlayRows) {
       const id = idOf(row);
-      if (!id) continue;
-      if (this.shadowPredicateApplies(row)) {
-        merged.set(id, row);
-      } else if (!merged.has(id)) {
-        continue;
-      }
+      if (id) overlayById.set(id, row);
+    }
+    const out = [];
+    for (const id of /* @__PURE__ */ new Set([...baseById.keys(), ...overlayById.keys()])) {
+      const merged = this.mergeRows(overlayById.get(id) ?? null, baseById.get(id) ?? null);
+      if (merged !== null) out.push(merged);
     }
-    return [...merged.values()];
+    return out;
   }
   /**
    * Write to the overlay. Two forms:
@@ -277,9 +284,42 @@ var OverlayedCollection = class {
   async delete(id) {
     await this.overlayCollection.delete(id);
   }
-  /** True when `overlay[shadowField] === shadowValue`. */
-  shadowPredicateApplies(row) {
-    return row[this.spec.shadowField] === this.spec.shadowValue;
+  /**
+   * Merge a single id's overlay + base rows into the visible row.
+   *
+   * Priority (first match wins):
+   *  1. Binary shadow win — overlay present AND
+   *     `overlay[shadowField] === shadowValue` → return the overlay row
+   *     entirely. This stays FIRST so the original binary behaviour is
+   *     unchanged whether or not `mergeMode` is configured.
+   *  2. Field-level merge — overlay present, `mergeMode` configured,
+   *     and a rule whose `whenStatus` equals `overlay[shadowField]`.
+   *     The matched rule pulls its `overlayFields` (those present on
+   *     the overlay row) on top of the base row. With no base row, the
+   *     overlay row is returned as-is.
+   *  3. Fallback — return the base row (possibly `null`). An
+   *     overlay-only row that qualifies under neither (1) nor (2) and
+   *     has no base is therefore NOT surfaced.
+   */
+  mergeRows(overlayRow, baseRow) {
+    const shadowField = this.spec.shadowField;
+    if (overlayRow !== null && overlayRow[shadowField] === this.spec.shadowValue) {
+      return overlayRow;
+    }
+    if (overlayRow !== null && this.spec.mergeMode) {
+      const status = overlayRow[shadowField];
+      const rule = this.spec.mergeMode.rules.find((r) => r.whenStatus === status);
+      if (rule) {
+        if (baseRow === null) return overlayRow;
+        const overlaySrc = overlayRow;
+        const picked = {};
+        for (const field of rule.overlayFields) {
+          if (field in overlaySrc) picked[field] = overlaySrc[field];
+        }
+        return { ...baseRow, ...picked };
+      }
+    }
+    return baseRow;
   }
   // ─── Throw-stubs for the unimplemented Collection<T> surface ───────
   //
@@ -290,7 +330,7 @@ var OverlayedCollection = class {
   // error pointing at the relevant issue — so consumers don't hit a
   // cryptic `undefined is not a function` runtime crash.
   //
-  // Closes niwat-review of PR #160.
+  // Throw-stubs so consumers get actionable errors rather than cryptic crashes.
   /** @throws — chainable Query<T> over a virtual collection is deferred. */
   query() {
     throw new Error(