@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/chunk-MLPHLJIQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-formula/overlay-views/virtual-collection.ts"],"sourcesContent":["import { OverlayIdMismatchError } from '../../kernel/errors.js'\nimport type { Collection } from '../../kernel/collection.js'\nimport type { OverlayedViewSpec } from './types.js'\n\n/**\n * Virtual-collection proxy returned by `vault.collection(overlayName)`\n * when `overlayName` is a registered `withOverlayedView`.\n *\n * Implements the core `Collection<T>`-shaped read/write surface with\n * merge-on-read semantics:\n *   - `get(id)`: overlay row wins iff `overlay[shadowField] === shadowValue`;\n *     when `spec.mergeMode` is set, an intermediate status may instead pull\n *     a declared subset of fields from the overlay over the base\n *   - `list()`: union of ids, per-id merge applied\n *   - `put(record)` / `put(id, record)`: routes to overlay; id derived\n *     via the base MV's `rowKey` (validated on the two-arg form)\n *   - `delete(id)`: removes the overlay row only; base stays\n *\n * ⚠️ **`query()` THROWS** — it is not implemented for overlay views (#154);\n * use `list()` + filter, or read the base / overlay collections directly.\n * This paragraph used to list `.query()` beside `list()` as working, while\n * naming only `query().live()` among the deferrals — so the header\n * over-claimed the one method on this class that throws, and the deferral\n * list quietly omitted it. Corrected 2026-09-04; the throw-stubs below are\n * the authority, and a doc comment that disagrees with an adjacent `never`\n * return type is worth more scepticism than one that disagrees with distant\n * code.\n *\n * Also deferred, same issue, same shape: `live`, `subscribe`,\n * `query().live()`.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport class OverlayedCollection<T extends Record<string, unknown> = any> {\n  constructor(\n    private readonly spec: OverlayedViewSpec,\n    private readonly baseCollection: Collection<T>,\n    private readonly overlayCollection: Collection<T>,\n    private readonly baseRowKey: ((row: Record<string, unknown>) => string) | undefined,\n  ) {}\n\n  /**\n   * Convenience accessors for advanced callers that need to bypass the\n   * virtual layer (bulk imports, direct overlay queries). Mirrors the\n   * spec's \"direct writes to the underlying overlay collection skip\n   * the validation\" escape hatch.\n   */\n  readonly overlay = {\n    rowKey: (row: Record<string, unknown>): string => {\n      if (!this.baseRowKey) {\n        throw new Error(\n          `Overlay \"${this.spec.name}\": base \"${this.spec.base}\" is not an MV — ` +\n            `cannot auto-derive id from the row. Use \\`put(id, record)\\` instead.`,\n        )\n      }\n      return this.baseRowKey(row)\n    },\n  }\n\n  /** Get the merged row by id. */\n  async get(id: string): Promise<T | null> {\n    const overlayRow = await this.overlayCollection.get(id)\n    const baseRow = await this.baseCollection.get(id)\n    return this.mergeRows(overlayRow, baseRow)\n  }\n\n  /** List union of base + overlay ids, applying the merge per row. */\n  async list(): Promise<T[]> {\n    const baseRows = await this.baseCollection.list()\n    const overlayRows = await this.overlayCollection.list()\n    const idOf = (row: T): string => {\n      // Best-effort: use baseRowKey if available, else assume the row\n      // has a `.id` field (common pattern). The spec requires every\n      // base MV to declare `rowKey`, so the first branch is the\n      // canonical path.\n      if (this.baseRowKey) return this.baseRowKey(row as Record<string, unknown>)\n      const idField = (row as Record<string, unknown>).id\n      return typeof idField === 'string' ? idField : ''\n    }\n    // Key base + overlay rows by id, then union the id sets and run the\n    // same per-id merge `get()` uses. Nulls (overlay-only rows that\n    // don't qualify and have no base) are filtered out.\n    const baseById = new Map<string, T>()\n    const overlayById = new Map<string, T>()\n    for (const row of baseRows) {\n      const id = idOf(row)\n      if (id) baseById.set(id, row)\n    }\n    for (const row of overlayRows) {\n      const id = idOf(row)\n      if (id) overlayById.set(id, row)\n    }\n    const out: T[] = []\n    for (const id of new Set([...baseById.keys(), ...overlayById.keys()])) {\n      const merged = this.mergeRows(overlayById.get(id) ?? null, baseById.get(id) ?? null)\n      if (merged !== null) out.push(merged)\n    }\n    return out\n  }\n\n  /**\n   * Write to the overlay. Two forms:\n   * - `put(record)`: id is derived via the base MV's `rowKey(record)`.\n   *   Throws if the base isn't an MV.\n   * - `put(id, record)`: validates `id === rowKey(record)`; throws\n   *   `OverlayIdMismatchError` on mismatch.\n   */\n  async put(idOrRecord: string | T, maybeRecord?: T): Promise<void> {\n    let id: string\n    let record: T\n    if (maybeRecord === undefined) {\n      // Single-arg form: put(record). Derive id via base rowKey.\n      record = idOrRecord as T\n      if (!this.baseRowKey) {\n        throw new Error(\n          `Overlay \"${this.spec.name}\".put(record): base \"${this.spec.base}\" is not an MV. ` +\n            `Use put(id, record) explicitly.`,\n        )\n      }\n      id = this.baseRowKey(record as Record<string, unknown>)\n    } else {\n      // Two-arg form: put(id, record). Validate against rowKey.\n      id = idOrRecord as string\n      record = maybeRecord\n      if (this.baseRowKey) {\n        const expected = this.baseRowKey(record as Record<string, unknown>)\n        if (id !== expected) {\n          throw new OverlayIdMismatchError(id, expected)\n        }\n      }\n    }\n    await this.overlayCollection.put(id, record)\n  }\n\n  /**\n   * Remove the overlay row only. Idempotent (no-op on absent).\n   * The base row is untouched — if a base row exists for `id`,\n   * subsequent reads return it.\n   */\n  async delete(id: string): Promise<void> {\n    await this.overlayCollection.delete(id)\n  }\n\n  /**\n   * Merge a single id's overlay + base rows into the visible row.\n   *\n   * Priority (first match wins):\n   *  1. Binary shadow win — overlay present AND\n   *     `overlay[shadowField] === shadowValue` → return the overlay row\n   *     entirely. This stays FIRST so the original binary behaviour is\n   *     unchanged whether or not `mergeMode` is configured.\n   *  2. Field-level merge — overlay present, `mergeMode` configured,\n   *     and a rule whose `whenStatus` equals `overlay[shadowField]`.\n   *     The matched rule pulls its `overlayFields` (those present on\n   *     the overlay row) on top of the base row. With no base row, the\n   *     overlay row is returned as-is.\n   *  3. Fallback — return the base row (possibly `null`). An\n   *     overlay-only row that qualifies under neither (1) nor (2) and\n   *     has no base is therefore NOT surfaced.\n   */\n  private mergeRows(overlayRow: T | null, baseRow: T | null): T | null {\n    const shadowField = this.spec.shadowField\n    if (\n      overlayRow !== null &&\n      (overlayRow as Record<string, unknown>)[shadowField] === this.spec.shadowValue\n    ) {\n      return overlayRow\n    }\n    if (overlayRow !== null && this.spec.mergeMode) {\n      const status = (overlayRow as Record<string, unknown>)[shadowField]\n      const rule = this.spec.mergeMode.rules.find((r) => r.whenStatus === status)\n      if (rule) {\n        if (baseRow === null) return overlayRow\n        const overlaySrc = overlayRow as Record<string, unknown>\n        const picked: Record<string, unknown> = {}\n        for (const field of rule.overlayFields) {\n          if (field in overlaySrc) picked[field] = overlaySrc[field]\n        }\n        return { ...(baseRow as Record<string, unknown>), ...picked } as T\n      }\n    }\n    return baseRow\n  }\n\n  // ─── Throw-stubs for the unimplemented Collection<T> surface ───────\n  //\n  // `Vault.collection(name)` widens the return type to `Collection<T>`\n  // for the overlay intercept, but `OverlayedCollection` doesn't\n  // implement the full surface. These stubs catch the common\n  // reactive / chainable APIs with a clear \"not yet implemented\"\n  // error pointing at the relevant issue — so consumers don't hit a\n  // cryptic `undefined is not a function` runtime crash.\n  //\n  // Throw-stubs so consumers get actionable errors rather than cryptic crashes.\n\n  /** @throws — chainable Query<T> over a virtual collection is deferred. */\n  query(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".query() is not yet implemented for overlay views (#154). ` +\n        `Use \\`list()\\` + filter for now, or read from the underlying \\`${this.spec.base}\\` / \\`${this.spec.overlay}\\` collections directly. ` +\n        `Reactive APIs land in a future MV sub-issue.`,\n    )\n  }\n\n  /** @throws — change-stream subscription over a virtual collection is deferred. */\n  subscribe(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".subscribe() is not yet implemented for overlay views (#154). ` +\n        `Subscribe to the underlying \\`${this.spec.base}\\` / \\`${this.spec.overlay}\\` collections individually for now. ` +\n        `Merged change-stream lands in a future MV sub-issue.`,\n    )\n  }\n\n  /** @throws — live query over a virtual collection is deferred. */\n  live(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".live() is not yet implemented for overlay views (#154). ` +\n        `Reactive APIs land in a future MV sub-issue.`,\n    )\n  }\n\n  /** @throws — async iteration over a virtual collection is deferred. */\n  scan(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".scan() is not yet implemented for overlay views (#154). ` +\n        `Use \\`list()\\` for now (no row-count ceiling at pilot1 scale), or scan the underlying collections directly.`,\n    )\n  }\n\n  /** @throws — lazy-mode query is not applicable to virtual collections. */\n  lazyQuery(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".lazyQuery() is not supported. ` +\n        `Virtual collections always materialize through base + overlay reads — lazy-mode indexed lookups don't apply.`,\n    )\n  }\n\n  /** @throws — bulk-atomic put is deferred to a future MV sub-issue. */\n  putManyAtomic(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".putManyAtomic() is not yet implemented for overlay views (#154). ` +\n        `Use sequential \\`.put(record)\\` calls for now, or write to \\`${this.spec.overlay}\\` directly.`,\n    )\n  }\n\n  /** @throws — bulk delete is deferred to a future MV sub-issue. */\n  deleteMany(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".deleteMany() is not yet implemented for overlay views (#154). ` +\n        `Use sequential \\`.delete(id)\\` calls for now, or operate on \\`${this.spec.overlay}\\` directly.`,\n    )\n  }\n\n  /** @throws — `.first()` over a virtual collection is deferred. */\n  first(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".first() is not yet implemented for overlay views (#154). ` +\n        `Use \\`(await list())[0]\\` for now.`,\n    )\n  }\n\n  /** @throws — `.count()` over a virtual collection is deferred. */\n  count(): never {\n    throw new Error(\n      `OverlayedCollection \"${this.spec.name}\".count() is not yet implemented for overlay views (#154). ` +\n        `Use \\`(await list()).length\\` for now.`,\n    )\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-2N4GY74U.js → chunk-MTL7MXGR.js}

@@ -1,22 +1,22 @@
 import {
   ATTESTATIONS_COLLECTION,
   loadOrCreateSigner
-} from "./chunk-ANATMFIO.js";
+} from "./chunk-QWFHIOD2.js";
 import {
   generateULID
 } from "./chunk-4AOERLTV.js";
 import {
   buildRecordAad
-} from "./chunk-77K4PG6P.js";
+} from "./chunk-KJFW62P4.js";
 import {
   buildRecordEnvelope
-} from "./chunk-SZJ3DLZA.js";
+} from "./chunk-SEE332EV.js";
 import {
   encrypt
-} from "./chunk-SL3JAAKN.js";
+} from "./chunk-UYB234ZR.js";
 import {
   AttestationError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-audit/attestation/issue.ts
 import {
@@ -63,4 +63,4 @@ async function issueAttestationCore(ctx, args) {
 export {
   issueAttestationCore
 };
-//# sourceMappingURL=chunk-2N4GY74U.js.map
+//# sourceMappingURL=chunk-MTL7MXGR.js.map

package/dist/{chunk-TFR7DSOV.js → chunk-MVZ2TPVP.js}

@@ -1,7 +1,7 @@
 import {
   DerivationCapExceededError,
   DerivationOutputShapeError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-formula/derivations/executor.ts
 var DerivationExecutor = {
@@ -121,4 +121,4 @@ var DerivationExecutor = {
 export {
   DerivationExecutor
 };
-//# sourceMappingURL=chunk-TFR7DSOV.js.map
+//# sourceMappingURL=chunk-MVZ2TPVP.js.map

package/dist/{chunk-CPWQB3N5.js → chunk-N5DNADLQ.js}

@@ -7,27 +7,27 @@ import {
   PERIOD_FREEZES_COLLECTION,
   PERIOD_TARGET_PURGES_COLLECTION,
   periodExclusiveUpperBound
-} from "./chunk-FAHMLERK.js";
+} from "./chunk-FW22ZCXT.js";
 import {
   envelopeBodySize
-} from "./chunk-77K4PG6P.js";
+} from "./chunk-KJFW62P4.js";
 import {
   buildRecordEnvelope,
   isDeleteMarker,
   isTombstoneShape
-} from "./chunk-SZJ3DLZA.js";
+} from "./chunk-SEE332EV.js";
 import {
   decrypt,
   derivePresenceKey,
   encrypt
-} from "./chunk-SL3JAAKN.js";
+} from "./chunk-UYB234ZR.js";
 import {
   NOYDB_SYNC_VERSION
-} from "./chunk-7MG7SJT7.js";
+} from "./chunk-ODVPTDPK.js";
 import {
   ValidationError,
   isConflictError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-sync/presence.ts
 var subtle = globalThis.crypto.subtle;
@@ -1213,4 +1213,4 @@ export {
   SyncEngine,
   SyncTransaction
 };
-//# sourceMappingURL=chunk-CPWQB3N5.js.map
+//# sourceMappingURL=chunk-N5DNADLQ.js.map

package/dist/{chunk-ELNXJMGB.js → chunk-NNARWO72.js}

@@ -2,21 +2,21 @@ import {
   ATTESTATIONS_COLLECTION,
   REVOKED_RECORD_ID,
   loadOrCreateSigner
-} from "./chunk-ANATMFIO.js";
+} from "./chunk-QWFHIOD2.js";
 import {
   buildRecordAad,
   openEnvelopeJson
-} from "./chunk-77K4PG6P.js";
+} from "./chunk-KJFW62P4.js";
 import {
   buildRecordEnvelope
-} from "./chunk-SZJ3DLZA.js";
+} from "./chunk-SEE332EV.js";
 import {
   encrypt
-} from "./chunk-SL3JAAKN.js";
+} from "./chunk-UYB234ZR.js";
 import {
   AttestationError,
   ConflictError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-audit/attestation/revoke.ts
 import { signRevocationList } from "@noy-db/attestation";
@@ -81,4 +81,4 @@ export {
   getRevokedDocIdsCore,
   publishRevocationListCore
 };
-//# sourceMappingURL=chunk-ELNXJMGB.js.map
+//# sourceMappingURL=chunk-NNARWO72.js.map

package/dist/{chunk-PT43Y56J.js → chunk-NRT6QZQB.js}

@@ -1,17 +1,18 @@
 import {
   PERIODS_COLLECTION
-} from "./chunk-FAHMLERK.js";
+} from "./chunk-FW22ZCXT.js";
 import {
   canonicalJson,
   sha256Hex
-} from "./chunk-BOET4NA4.js";
+} from "./chunk-CKNGS5MH.js";
 import {
   isDeleteMarker
-} from "./chunk-SZJ3DLZA.js";
+} from "./chunk-SEE332EV.js";
 import {
+  PeriodChainError,
   PeriodClosedError,
   ValidationError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-audit/periods/periods.ts
 function resolveReopenState(events) {
@@ -71,15 +72,78 @@ async function loadPeriods(adapter, vault, decrypt) {
     if (env) records.push(await decrypt(id, env));
   }
   records.sort((a, b) => a.closedAt.localeCompare(b.closedAt));
+  await verifyPeriodChain(records);
   return records;
 }
+var RETURN_ONLY_FIELDS = [
+  "frozenAt",
+  "frozenBy",
+  "purgedMarkerCount",
+  "archivedAt",
+  "archivedBy",
+  "archivedRecordCount",
+  "targetsPurgedAt",
+  "targetsPurgedBy",
+  "targetsPurged",
+  "reopenedAt",
+  "reopenedBy",
+  "reopenedUntil",
+  "reopenReason",
+  "reclosedAt",
+  "reopenCount"
+];
+async function hashStoredPeriod(period) {
+  const stored = { ...period };
+  for (const f of RETURN_ONLY_FIELDS) delete stored[f];
+  return sha256Hex(canonicalJson(stored));
+}
+async function verifyPeriodChain(records) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const r of records) byKey.set(resolvePeriodKey(r.name, r.partition), r);
+  for (const r of records) {
+    if (r.priorPeriodName === void 0) {
+      if (r.priorPeriodHash !== "") {
+        throw new PeriodChainError(r.name, "it names no predecessor but carries a non-empty priorPeriodHash", r.partition);
+      }
+      continue;
+    }
+    const prior = byKey.get(resolvePeriodKey(r.priorPeriodName, r.partition));
+    if (!prior) {
+      throw new PeriodChainError(r.name, `its predecessor "${r.priorPeriodName}" is missing from the store`, r.partition);
+    }
+    if (await hashStoredPeriod(prior) !== r.priorPeriodHash) {
+      throw new PeriodChainError(r.name, `its predecessor "${r.priorPeriodName}" no longer hashes to the recorded priorPeriodHash`, r.partition);
+    }
+  }
+}
 async function chainAnchor(records, partition) {
   const inTimeline = records.filter((p) => samePartition(p.partition, partition));
   const last = inTimeline[inTimeline.length - 1];
   if (!last) return { priorPeriodHash: "" };
-  const hash = await sha256Hex(canonicalJson(last));
+  const hash = await hashStoredPeriod(last);
   return { priorPeriodName: last.name, priorPeriodHash: hash };
 }
+var ORDERABLE_ISO = /^(\d{4})(?:-(\d{2})(?:-(\d{2})(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})?)?)?)?$/;
+function daysInPeriodMonth(y, m) {
+  if (m === 2) return y % 4 === 0 && y % 100 !== 0 || y % 400 === 0 ? 29 : 28;
+  return m === 4 || m === 6 || m === 9 || m === 11 ? 30 : 31;
+}
+function isOrderableBusinessDate(value) {
+  const m = ORDERABLE_ISO.exec(value);
+  if (m === null) return false;
+  const year = Number(m[1]);
+  if (m[2] === void 0) return true;
+  const month = Number(m[2]);
+  if (month < 1 || month > 12) return false;
+  if (m[3] === void 0) return true;
+  const day = Number(m[3]);
+  return day >= 1 && day <= daysInPeriodMonth(year, month);
+}
+function malformedBusinessDate(where, value) {
+  return new ValidationError(
+    `${where} is not an orderable business date: ${JSON.stringify(value)}. Period membership compares strings, so a date must be zero-padded ISO-8601 \u2014 "YYYY", "YYYY-MM" or "YYYY-MM-DD", optionally with a time ("2026-06-30T23:59:59Z"). Coarser is fine; unpadded is not. "2026-6-15" is refused although it names a real day: as text it sorts above "2026-06-30", so it would slip past a June close.`
+  );
+}
 function assertTsWritable(existing, incomingRecord, closedPeriods, scope) {
   const partitionOf = (r) => {
     if (!r || !scope?.resolve) return void 0;
@@ -88,17 +152,38 @@ function assertTsWritable(existing, incomingRecord, closedPeriods, scope) {
   const existingRecord = existing?.record ?? null;
   const existingPartition = partitionOf(existingRecord);
   const incomingPartition = partitionOf(incomingRecord);
+  const existingTs = existing?.ts ?? null;
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  for (const p of closedPeriods) {
-    if (p.kind !== "closed") continue;
+  const closed = closedPeriods.filter((p) => p.kind === "closed");
+  const ownerReopened = (value, partition) => {
+    let owner;
+    for (const p of closed) {
+      if (!samePartition(p.partition, partition)) continue;
+      if (value <= p.endDate && (owner === void 0 || p.endDate < owner.endDate)) owner = p;
+    }
+    return owner !== void 0 && isEffectivelyReopened(owner, now);
+  };
+  const readDate = (p, r, side) => {
+    const v = r[p.dateField];
+    if (v === void 0 || v === null) return null;
+    if (typeof v === "string") {
+      if (!isOrderableBusinessDate(v)) throw malformedBusinessDate(`${side}[${p.dateField}]`, v);
+      return v;
+    }
+    if (v instanceof Date && !Number.isNaN(v.getTime())) return v.toISOString();
+    throw new ValidationError(
+      `Period guard cannot evaluate ${side}[${p.dateField}] (${v instanceof Date ? "invalid Date" : typeof v}) against closed period "${p.name}" \u2014 a business date must be an ISO-8601 string or a Date. Refusing rather than admitting the record into a sealed timeline.`
+    );
+  };
+  for (const p of closed) {
     if (isEffectivelyReopened(p, now)) continue;
     if (p.dateField) {
-      const checkRecord = (label, r, recordPartition) => {
+      const checkRecord = (side, r, recordPartition) => {
         if (!r) return;
         if (!samePartition(recordPartition, p.partition)) return;
-        const v = r[p.dateField];
-        if (typeof v === "string" && v <= p.endDate) {
-          throw new PeriodClosedError(p.name, p.endDate, `${label}[${p.dateField}]=${v}`);
+        const v = readDate(p, r, side);
+        if (v !== null && v <= p.endDate && !ownerReopened(v, recordPartition)) {
+          throw new PeriodClosedError(p.name, p.endDate, `${side}[${p.dateField}]=${v}`, { dateField: p.dateField, side });
         }
       };
       checkRecord("existing", existingRecord, existingPartition);
@@ -106,9 +191,8 @@ function assertTsWritable(existing, incomingRecord, closedPeriods, scope) {
       continue;
     }
     if (!samePartition(existingPartition, p.partition)) continue;
-    const existingTs = existing?.ts ?? null;
-    if (existingTs !== null && existingTs <= p.endDate) {
-      throw new PeriodClosedError(p.name, p.endDate, existingTs);
+    if (existingTs !== null && existingTs <= p.endDate && !ownerReopened(existingTs, existingPartition)) {
+      throw new PeriodClosedError(p.name, p.endDate, existingTs, { side: "existing" });
     }
   }
 }
@@ -124,7 +208,7 @@ function validatePeriodName(name, existing, partition) {
 }
 async function appendPeriodLedgerEntry(ledger, actor, envelope, name, collection = PERIODS_COLLECTION) {
   if (!ledger) return;
-  const { envelopePayloadHash } = await import("./ledger-F33ZVMTK.js");
+  const { envelopePayloadHash } = await import("./ledger-KZPCMVZY.js");
   await ledger.append({
     op: "put",
     collection,
@@ -192,10 +276,12 @@ export {
   samePartition,
   loadPeriods,
   chainAnchor,
+  isOrderableBusinessDate,
+  malformedBusinessDate,
   assertTsWritable,
   validatePeriodName,
   appendPeriodLedgerEntry,
   purgeMarkersOn,
   withPeriods
 };
-//# sourceMappingURL=chunk-PT43Y56J.js.map
+//# sourceMappingURL=chunk-NRT6QZQB.js.map

package/dist/chunk-NRT6QZQB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-audit/periods/periods.ts","../src/with-audit/periods/active.ts","../src/with-audit/periods/strategy.ts"],"sourcesContent":["/**\n * Accounting-period closure + opening.\n *\n * A closed period seals every record whose envelope `_ts` is at or\n * before the period's `endDate`: further writes (`put` / `delete`)\n * against such records throw {@link PeriodClosedError}. The period\n * itself is stored as a record in the reserved `_periods` collection\n * and written through the normal ledger-instrumented path, so every\n * closure appends a tamper-evident entry to the vault's hash chain.\n *\n * ## Closure model\n *\n * ```\n * vault.closePeriod({ name: 'FY2026-Q1', endDate: '2026-03-31' })\n *   └─► PeriodRecord written to _periods/<name>\n *         ├─ priorPeriodName / priorPeriodHash — chain to last close\n *         ├─ closedAt / closedBy — provenance\n *         └─ normal ledger append fires (LedgerStore.append)\n * ```\n *\n * Enforcement (`assertTsWritable`) is vault-local: the Vault caches\n * the list of closed periods on first read and consults that cache in\n * the `Collection.put` / `.delete` path via the `periodGuard` hook.\n *\n * ## Opening model\n *\n * ```\n * vault.openPeriod({\n *   name: 'FY2026-Q2',\n *   startDate: '2026-04-01',\n *   fromPeriod: 'FY2026-Q1',\n *   carryForward: async (priorView) => Record<string, Record<string, unknown>>,\n * })\n * ```\n *\n * `carryForward` receives a read-only `VaultInstant` anchored at the\n * prior period's `endDate` (built via `vault.at(endDate)`) so the\n * callback can compute closing aggregates from the sealed state. The\n * returned `{ [collectionName]: { [id]: record } }` map is written\n * before the new `PeriodRecord` lands — opening balances materialise\n * as normal records with fresh timestamps that fall outside every\n * closed period.\n *\n * ## Freeze\n *\n * ```\n * vault.freezePeriod('FY2026-Q1')\n *   └─► physically purges delete markers whose write-time falls inside\n *       the closed period's window (via the #589 `_purgeDeleteMarkers`\n *       seam), then records the fact:\n *         ├─ PeriodFreezeRecord written to _period_freezes/<name>\n *         └─ normal ledger append fires (LedgerStore.append)\n * ```\n *\n * The chained `_periods/<name>` record is never mutated — `frozenAt` /\n * `frozenBy` / `purgedMarkerCount` are merged onto the returned\n * `PeriodRecord` at read time from the companion, so a tamper with the\n * freeze can never break the inter-period hash chain. Freezing is\n * terminal (a closed period, once frozen, stays frozen) and idempotent\n * (a second call is a no-op that returns the same merged record without\n * re-purging or re-appending a ledger entry). Freeze does NOT purge\n * forget-tombstones (GDPR crypto-shred erasure evidence), `_history`\n * versions, or live records — the delete-markers-only seam leaves all\n * three untouched by construction.\n *\n * Freeze purges the LOCAL adapter only. On a synced vault, markers already\n * pushed to sync targets survive there, and a later pull re-imports them\n * (benign — they still read deleted, but the space isn't reclaimed). A\n * re-imported marker keeps its original `_ts` (inside the already-frozen\n * period's window), so — like any late-booked delete — it is reclaimed by\n * the NEXT period's freeze, whose window covers it; freeze stays terminal\n * and does NOT re-purge an already-frozen period (#611). Sweeping the sync\n * targets themselves is a cross-target-purge concern deferred to the\n * cold-archival spec. Purging re-opens the #589 resurrection window for a\n * peer offline since before the cutoff, which is why the closed period is\n * the operator-asserted safe-point that gates the call.\n *\n * A period whose purge window has not fully elapsed cannot be frozen —\n * `freezePeriod` throws rather than purge markers for deletes that may not\n * have converged yet (#610).\n *\n * ## Archive\n *\n * ```\n * vault.archivePeriod('FY2026-Q1')\n *   └─► relocates the closed period's in-window records (those with\n *       `_ts < periodExclusiveUpperBound(endDate)`) from the hot store to\n *       the configured cold tier (routeStore's `cold` route), then records:\n *         ├─ PeriodArchiveRecord written to _period_archives/<name>\n *         └─ a ledger entry attributed to _period_archives\n * ```\n *\n * Archival is NON-DESTRUCTIVE: routeStore reads fall through to the cold\n * tier on a hot miss, so an archived record still reads normally. It is\n * therefore gated only on `closed` (not `frozen`) — it does not re-open the\n * #589 resurrection window and needs no convergence safe-point. Freeze\n * (purge markers) and archive (relocate records) are independent and compose\n * in either order. Like freeze, archival keeps the chained `_periods/<name>`\n * record byte-immutable (state lives in the companion) and is idempotent.\n *\n * Bounds by write-time `_ts`, NOT business date: the store tier sees only\n * encrypted envelopes. A record with an in-period business date but a later\n * `_ts` (late-booked) archives at the NEXT period's archive — the same rule\n * freeze uses for late-booked delete markers. Requires a `routeStore` with a\n * cold route (`age: { cold }`); throws otherwise.\n *\n * Read cost: with `withLazy()` (per-id reads) archived records are truly\n * cold — fetched from cold only on access. In the default hydrated mode,\n * `loadAll` merges the cold store, so archived records still load into RAM\n * on vault open (hot-tier STORAGE is reclaimed; RAM is not). Summaries\n * (`_`-prefixed) always stay hot.\n *\n * ## Target-purge\n *\n * ```\n * vault.purgePeriodTargets('FY2026-Q1')\n *   └─► sweeps delete markers (`_ts < periodExclusiveUpperBound(endDate)`) off\n *       the vault's PUSH-ONLY sync targets (backup/archive roles), then records:\n *         ├─ PeriodTargetPurgeRecord written to _period_target_purges/<name>\n *         └─ a ledger entry attributed to _period_target_purges\n * ```\n *\n * Extends freeze's local marker purge to the vault's own remote sinks.\n * `sync-peer` (bidirectional) targets are SKIPPED: purging a marker there\n * re-opens the #589 resurrection window for a client offline before the\n * cutoff, an assertion no single vault can verify. Backup/archive targets are\n * push-only — never pulled from into convergence — so sweeping their markers\n * is safe. Requires the period be frozen first (closed → frozen →\n * target-purged) so the local safe-point is already established. Idempotent\n * once run; a vault with no push-only targets writes no companion and is\n * re-runnable (so a target added later is still swept). Single-vault only —\n * fleet-wide purge across sovereign vaults is klum's concern over\n * `@noy-db/hub/cargo`.\n *\n * ## Not covered\n *\n * - Partial re-opening of a closed period. If an auditor needs to\n *   make a correction inside a sealed period, the sanctioned path is\n *   a compensating entry in the NEW period, not an unlock of the\n *   old one.\n * - Automatic period rollover. `closePeriod` / `openPeriod` are\n *   deliberately explicit operator calls so the caller decides when\n *   the boundary lands.\n *\n * @module\n */\n\nimport type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js'\nimport type { LedgerStore } from '../../with-commit/history/ledger/index.js'\nimport { sha256Hex, canonicalJson } from '../../with-commit/history/ledger/index.js'\nimport { isDeleteMarker } from '../../kernel/enclave/index.js'\nimport { PeriodChainError, PeriodClosedError, ValidationError } from '../../kernel/errors.js'\n\n// The reserved collection names + `periodExclusiveUpperBound` moved to the\n// dependency-light `window.ts` so the sync engine's period-scoped pull (#807)\n// can import them without this module's ledger imports; re-exported here so\n// every existing import path keeps working.\nexport {\n  PERIODS_COLLECTION,\n  PERIOD_FREEZES_COLLECTION,\n  PERIOD_ARCHIVES_COLLECTION,\n  PERIOD_TARGET_PURGES_COLLECTION,\n  PERIOD_REOPENS_COLLECTION,\n  periodExclusiveUpperBound,\n} from './window.js'\nimport { PERIODS_COLLECTION } from './window.js'\n\n/**\n * Companion record recording that a closed period was frozen (its delete\n * markers physically purged). Stored in {@link PERIOD_FREEZES_COLLECTION},\n * keyed by period name — kept OFF the hash-chained `_periods/<name>` record so\n * freeze never alters the inter-period chain.\n */\nexport interface PeriodFreezeRecord {\n  readonly period: string\n  readonly frozenAt: string\n  readonly frozenBy: string\n  readonly purgedMarkerCount: number\n}\n\n/**\n * Companion record noting that a closed period was cold-archived (its\n * in-window records physically relocated hot → cold). Stored in\n * {@link PERIOD_ARCHIVES_COLLECTION}, keyed by period name — kept OFF the\n * hash-chained `_periods/<name>` record so archive never alters the chain.\n */\nexport interface PeriodArchiveRecord {\n  readonly period: string\n  readonly archivedAt: string\n  readonly archivedBy: string\n  readonly archivedRecordCount: number\n}\n\n/** Per-target count of delete markers purged off one push-only sync target (#615). */\nexport interface TargetPurgeCount {\n  readonly label?: string\n  readonly role: 'backup' | 'archive'\n  readonly purgedCount: number\n}\n\n/**\n * One entry in a period's append-only reopen/reclose log (#1022).\n *\n * Real accounting close is a three-state lifecycle — open / closed / reopened\n * — not a one-way door. A month gets closed, a missing invoice arrives or a\n * filing is rejected, the month is reopened, corrected, and reclosed. The audit\n * value is not the ability to write again; it is the chain being able to say\n * *closed at T1, reopened at T2 by U, reclosed at T3*.\n */\nexport interface PeriodReopenEvent {\n  readonly op: 'reopen' | 'reclose'\n  /** ISO timestamp the event was recorded. */\n  readonly at: string\n  /** userId of the keyring that performed it. */\n  readonly by: string\n  /**\n   * `reopen` only — ISO instant after which the period re-seals on its own,\n   * with nobody acting. Absent means the window stays open until an explicit\n   * `reclosePeriod`.\n   */\n  readonly until?: string\n  /** Free-text justification, carried verbatim into the audit trail. */\n  readonly reason?: string\n}\n\n/**\n * Companion holding a period's reopen/reclose history (#1022). Stored in\n * {@link PERIOD_REOPENS_COLLECTION}, keyed by the period's storage key — kept\n * OFF the hash-chained `_periods/<name>` record for the same reason freeze and\n * archive are: reopening must never rewrite the close, or the chain that proves\n * the close happened is the very thing the reopen destroys.\n *\n * `events` is APPEND-ONLY. Where the other companions are single-shot and\n * idempotent, this one accumulates, because the cycle repeats.\n */\nexport interface PeriodReopenRecord {\n  readonly period: string\n  readonly partition?: PeriodPartition\n  readonly events: readonly PeriodReopenEvent[]\n}\n\n/**\n * Collapse an append-only reopen log into the return-only fields merged onto a\n * {@link PeriodRecord} on read.\n *\n * Expiry is deliberately NOT resolved here: `reopenedUntil` is carried through\n * verbatim and compared against the clock at write-guard time, so a bounded\n * window re-seals on its own without anything having to run.\n *\n * @internal\n */\nexport function resolveReopenState(events: readonly PeriodReopenEvent[]): {\n  reopenedAt?: string\n  reopenedBy?: string\n  reopenedUntil?: string\n  reopenReason?: string\n  reclosedAt?: string\n  reopenCount: number\n} {\n  let lastReopen: PeriodReopenEvent | undefined\n  let reclosedAfter: string | undefined\n  let reopenCount = 0\n  for (const e of events) {\n    if (e.op === 'reopen') {\n      lastReopen = e\n      reclosedAfter = undefined\n      reopenCount++\n    } else if (lastReopen !== undefined) {\n      reclosedAfter = e.at\n    }\n  }\n  if (!lastReopen) return { reopenCount }\n  return {\n    reopenedAt: lastReopen.at,\n    reopenedBy: lastReopen.by,\n    ...(lastReopen.until !== undefined && { reopenedUntil: lastReopen.until }),\n    ...(lastReopen.reason !== undefined && { reopenReason: lastReopen.reason }),\n    ...(reclosedAfter !== undefined && { reclosedAt: reclosedAfter }),\n    reopenCount,\n  }\n}\n\n/**\n * Is this period writable right now on account of a reopen? (#1022)\n *\n * Three ways to be sealed again: never reopened, explicitly reclosed after the\n * last reopen, or a bounded window that has elapsed. The clock is read by the\n * caller and passed in, so the guard and any diagnostic agree on one instant.\n *\n * @internal\n */\nexport function isEffectivelyReopened(period: PeriodRecord, nowIso: string): boolean {\n  if (period.reopenedAt === undefined) return false\n  if (period.reclosedAt !== undefined && period.reclosedAt >= period.reopenedAt) return false\n  if (period.reopenedUntil !== undefined && nowIso > period.reopenedUntil) return false\n  return true\n}\n\n/**\n * Companion record noting that a closed+frozen period's delete markers were\n * swept off the vault's push-only sync targets (#615). Stored in\n * {@link PERIOD_TARGET_PURGES_COLLECTION}, keyed by period name — kept OFF the\n * hash-chained `_periods/<name>` record so target-purge never alters the chain.\n */\nexport interface PeriodTargetPurgeRecord {\n  readonly period: string\n  readonly purgedAt: string\n  readonly purgedBy: string\n  readonly targets: readonly TargetPurgeCount[]\n}\n\n/**\n * Scope tuple for a period timeline (#1005).\n *\n * Identical in shape and semantics to `SequenceOptions.partition`: a\n * partitioned timeline is always disjoint from any unpartitioned one, and from\n * every other tuple. `['acme', 'vat']` and `['acme', 'wht']` are two\n * independent close calendars for the same subject — which is the whole point,\n * since sub-ledgers for one legal entity and one month routinely close on\n * different statutory deadlines.\n */\nexport type PeriodPartition = readonly (string | number)[]\n\n/**\n * Resolve the `_periods` storage key for a (name, partition) pair.\n *\n * Deliberately the same encoding as `resolveSequenceKey`: `name` verbatim when\n * unpartitioned, else `${name}\\x00${parts}` with each component\n * `encodeURIComponent`d and `'/'`-joined. The null-byte separator cannot occur\n * in a period name, so a partitioned key never collides with an unpartitioned\n * one; URI-encoding keeps `['a/b']` distinct from `['a','b']`.\n *\n * @throws {ValidationError} on an empty component or a non-finite number.\n * @internal\n */\nexport function resolvePeriodKey(name: string, partition?: PeriodPartition): string {\n  if (!partition || partition.length === 0) return name\n  const parts = partition.map((p) => {\n    if (typeof p === 'number' && !Number.isFinite(p)) {\n      throw new ValidationError(`period partition component must be a finite number, got ${p}`)\n    }\n    const s = String(p)\n    if (s === '') {\n      throw new ValidationError('period partition component must not be empty')\n    }\n    return encodeURIComponent(s)\n  })\n  return `${name}\\x00${parts.join('/')}`\n}\n\n/**\n * Do two partitions denote the same timeline? Absent and empty both mean \"the\n * unpartitioned timeline\", so they compare equal.\n *\n * @internal\n */\nexport function samePartition(a?: PeriodPartition, b?: PeriodPartition): boolean {\n  const x = a ?? []\n  const y = b ?? []\n  if (x.length !== y.length) return false\n  return x.every((v, i) => String(v) === String(y[i]))\n}\n\n/**\n * Resolves a record to the timeline that governs it. Supplied by\n * `withPeriods({ subjects })`; returns `undefined` for any collection with no\n * mapping, which is what keeps an unconfigured vault on the single vault-wide\n * timeline it has always had.\n *\n * @internal\n */\nexport type PartitionResolver = (\n  collection: string,\n  record: Record<string, unknown>,\n) => PeriodPartition | undefined\n\n/**\n * Stored record for one closed or opened accounting period. One entry\n * per period, keyed by `name` in the reserved `_periods` collection.\n *\n * The hash chain between periods is computed at read time by\n * `loadPeriods()` — each record carries the name + hash of its\n * predecessor so a tamper with any period's record breaks the chain\n * into the next one, the same way the ledger's `prevHash` works.\n */\nexport interface PeriodRecord {\n  /**\n   * Human-readable name (e.g., `'FY2026-Q1'`). Unique per PARTITION — two\n   * timelines may each carry a `'2026-06'`, which is the normal case when one\n   * vault serves several subjects (#1005). Unique per vault when unpartitioned.\n   */\n  readonly name: string\n  /**\n   * The timeline this period belongs to. Absent = the vault-wide timeline.\n   * Two periods with the same `name` and different `partition` are unrelated:\n   * separate hash chains, separate close state, and the write guard applies\n   * each only to records that resolve to its own tuple.\n   */\n  readonly partition?: PeriodPartition\n  /**\n   * Role discriminator. A period is `'closed'` from the moment its\n   * `closedAt` is recorded; `'opened'` marks a period whose opening\n   * entries have been carried forward via {@link openPeriod}. Many\n   * workflows will produce one opened period per closed period (the\n   * opened one is the SUCCESSOR — its `startDate` equals the prior\n   * `endDate + 1 day`).\n   */\n  readonly kind: 'closed' | 'opened'\n  /** ISO date — inclusive upper bound for records belonging to this period. */\n  readonly endDate: string\n  /** ISO date — lower bound (present on opened periods only). */\n  readonly startDate?: string\n  /**\n   * Record field carrying the business date (e.g. `'date'` on an\n   * invoice, `'paidAt'` on a payment). The guard compares\n   * `record[dateField]` against `endDate` — NOT the envelope `_ts`.\n   * Accounting entries booked late (business date `2026-01-15`,\n   * write-time `2026-04-22`) still get sealed when Q1 closes at\n   * `2026-03-31` because the comparison uses the business date.\n   *\n   * Optional for backwards compat. When absent, the guard falls back\n   * to envelope `_ts` — that's a write-time seal, appropriate for\n   * content that doesn't carry a logical business date (e.g. system\n   * settings) but almost never right for accounting ledgers.\n   */\n  readonly dateField?: string\n  /** ISO timestamp recorded at `closePeriod()` / `openPeriod()` call time. */\n  readonly closedAt: string\n  /** userId of the keyring that invoked the close/open. */\n  readonly closedBy: string\n  /** Name of the prior period this one chains to, if any. */\n  readonly priorPeriodName?: string\n  /** sha256(canonicalJson(priorPeriod)) — empty for the first period. */\n  readonly priorPeriodHash: string\n  /**\n   * Opened periods only — the names of the collections whose\n   * carry-forward aggregates were written by {@link openPeriod}.\n   * Recorded for auditability so a future `verifyPeriodChain()` can\n   * cross-check the opening balances against the closing snapshot.\n   */\n  readonly openingCollections?: readonly string[]\n  /** #604 return-only — merged from the `_period_freezes/<name>` companion on\n   *  read; NEVER written into the stored `_periods/<name>` record (would break\n   *  the hash chain). Absent = not yet frozen. */\n  readonly frozenAt?: string\n  readonly frozenBy?: string\n  readonly purgedMarkerCount?: number\n  /** #613 return-only — merged from the `_period_archives/<name>` companion on\n   *  read; NEVER written into the stored `_periods/<name>` record. Absent = not\n   *  yet archived. */\n  readonly archivedAt?: string\n  readonly archivedBy?: string\n  readonly archivedRecordCount?: number\n  /** #615 return-only — merged from the `_period_target_purges/<name>` companion\n   *  on read; NEVER written into the stored `_periods/<name>` record. Absent =\n   *  target-purge not yet run (or the vault has no push-only targets). */\n  readonly targetsPurgedAt?: string\n  readonly targetsPurgedBy?: string\n  readonly targetsPurged?: readonly TargetPurgeCount[]\n  /** #1022 return-only — collapsed from the `_period_reopens/<key>` append-only\n   *  log on read; NEVER written into the stored `_periods/<name>` record, so a\n   *  reopen cannot disturb the inter-period hash chain. Absent = never reopened.\n   *  `reclosedAt` present (and >= `reopenedAt`) means the window was closed\n   *  again explicitly; `reopenedUntil` in the past means it lapsed on its own.\n   *  Use {@link isEffectivelyReopened} rather than reading these directly. */\n  readonly reopenedAt?: string\n  readonly reopenedBy?: string\n  readonly reopenedUntil?: string\n  readonly reopenReason?: string\n  readonly reclosedAt?: string\n  /** How many times this period has been reopened, ever. */\n  readonly reopenCount?: number\n}\n\n/** Options for `vault.closePeriod()`. */\nexport interface ClosePeriodOptions {\n  /** Human-readable name. Must not collide with an existing period. */\n  readonly name: string\n  /**\n   * Inclusive upper cutoff. With a `dateField`, a record is sealed when its\n   * `record[dateField]` is at or before this ISO timestamp; a record with\n   * NO value there (absent / `null`) carries no business date and belongs\n   * to no period, and a value that is neither an ISO string nor a `Date`\n   * is refused (#1455). Without a `dateField`, the envelope `_ts` of the\n   * stored record is compared instead.\n   *\n   * ⚠️ String comparison is lexicographic: keep `endDate` and the field in\n   * one ISO-8601 shape (`YYYY-MM-DD` against `YYYY-MM-DD`, or full\n   * timestamps against full timestamps).\n   *\n   * ⛔ **Zero-padding is now ENFORCED on both sides (#1459), because that\n   * warning was not enough.** `'2026-6-30'` names a real day and is refused\n   * anyway: as text it sorts BELOW every June date, so the close would seal\n   * nothing and report success — and symmetrically a record dated\n   * `'2026-6-15'` sorted ABOVE `'2026-06-30'` and was written into a sealed\n   * June. Both are `ValidationError` now, at the close and at the write,\n   * rather than a silent pass or a `PeriodClosedError` that fired for a reason\n   * unrelated to dates.\n   */\n  readonly endDate: string\n  /**\n   * Record field carrying the business date used for period\n   * membership. Recommended for accounting workflows — e.g. an\n   * invoice booked late (write-time after close) is still sealed\n   * when its `invoice.date` falls inside the closed period.\n   *\n   * Omit to use envelope `_ts` (write-time seal). This fallback\n   * rarely matches real-world accounting semantics; prefer passing\n   * an explicit `dateField`.\n   */\n  readonly dateField?: string\n  /**\n   * Close only this timeline (#1005). Omit for the vault-wide timeline.\n   *\n   * ```ts\n   * vault.closePeriod({\n   *   name: '2026-06', endDate: '2026-06-30', dateField: 'issuedAt',\n   *   partition: [clientId, 'vat'],\n   * })\n   * ```\n   *\n   * Which records the resulting seal applies to is decided by the\n   * `subjects` map passed to `withPeriods()` — without one, no record ever\n   * resolves to a partition and a partitioned close seals nothing.\n   */\n  readonly partition?: PeriodPartition\n}\n\n/** Options for `vault.openPeriod()`. */\nexport interface OpenPeriodOptions<TCollections = Record<string, Record<string, unknown>>> {\n  /** Human-readable name for the new period. Must be unique. */\n  readonly name: string\n  /**\n   * The timeline to open in. Must match the partition of `fromPeriod` — a\n   * period cannot chain across timelines, since each carries its own hash\n   * chain (#1005).\n   */\n  readonly partition?: PeriodPartition\n  /** ISO lower bound of the new period (usually prior `endDate + 1 day`). */\n  readonly startDate: string\n  /**\n   * Name of the prior CLOSED period this one chains from. The prior\n   * period's record is verified to exist and to be `kind: 'closed'`;\n   * its `endDate` is made available to the `carryForward` callback.\n   */\n  readonly fromPeriod: string\n  /**\n   * Receives a read-only facade over the vault's CURRENT state,\n   * plus the prior period's `endDate`. Accounting semantics: after\n   * a period closes, records with `record[dateField] <= endDate`\n   * are frozen — current state equals closing state, so a caller\n   * can compute closing balances by querying the live collection\n   * with a `where('date', '<=', priorEndDate)` filter.\n   *\n   * Returns opening-balance records keyed by collection name.\n   * Example:\n   *\n   * ```ts\n   * carryForward: async (ctx) => {\n   *   const closing = await ctx.collection<Journal>('journal')\n   *     .query().where('date', '<=', ctx.priorEndDate).toArray()\n   *   const opening: Record<string, Journal> = {}\n   *   for (const entry of closing) {\n   *     opening[`OB-${entry.id}`] = { ...entry, date: '2026-04-01' }\n   *   }\n   *   return { journal: opening }\n   * }\n   * ```\n   */\n  readonly carryForward: (\n    ctx: CarryForwardContext,\n  ) => Promise<TCollections> | TCollections\n}\n\n/**\n * Context passed to `OpenPeriodOptions.carryForward`. Exposes a\n * read-only subset of the live vault (`collection(name).get/list`)\n * plus the prior period's `endDate` so business-date filters can\n * be built by the caller.\n *\n * Writes go via the return value, not via the facade — the\n * `collection()` here is deliberately restricted to reads.\n */\nexport interface CarryForwardContext {\n  /** The prior period's `endDate` — the boundary of the closing snapshot. */\n  readonly priorEndDate: string\n  /** Read-only collection facade over current vault state. */\n  collection<T = unknown>(name: string): ReadOnlyCollection<T>\n}\n\n/** Minimum read surface exposed to `carryForward`. */\nexport interface ReadOnlyCollection<T> {\n  get(id: string): Promise<T | null>\n  list(): Promise<T[]>\n}\n\n/**\n * Load every period record currently stored on the adapter.\n * Decrypting is the caller's responsibility (we return plain records\n * so the vault can use its own `_periods` DEK).\n *\n * @internal — called by Vault methods that need the closed-period\n * cache. Not part of the public API surface.\n */\nexport async function loadPeriods(\n  adapter: NoydbStore,\n  vault: string,\n  decrypt: (id: string, envelope: EncryptedEnvelope) => Promise<PeriodRecord>,\n): Promise<PeriodRecord[]> {\n  const ids = await adapter.list(vault, PERIODS_COLLECTION)\n  const records: PeriodRecord[] = []\n  for (const id of ids) {\n    const env = await adapter.get(vault, PERIODS_COLLECTION, id)\n    if (env) records.push(await decrypt(id, env))\n  }\n  // Stable order by closedAt so chain verification is reproducible.\n  records.sort((a, b) => a.closedAt.localeCompare(b.closedAt))\n  await verifyPeriodChain(records)\n  return records\n}\n\n/**\n * The fields merged onto a {@link PeriodRecord} on READ and never written into\n * the stored `_periods/<key>` record. Stripped before hashing so an anchor\n * computed off a merged cache equals the one a cold loader recomputes off the\n * stored bytes (#1454 — `chainAnchor` used to hash the cache as it stood, so a\n * close following a reopen was anchored to a hash nothing could verify).\n */\nconst RETURN_ONLY_FIELDS: readonly string[] = [\n  'frozenAt', 'frozenBy', 'purgedMarkerCount',\n  'archivedAt', 'archivedBy', 'archivedRecordCount',\n  'targetsPurgedAt', 'targetsPurgedBy', 'targetsPurged',\n  'reopenedAt', 'reopenedBy', 'reopenedUntil', 'reopenReason', 'reclosedAt', 'reopenCount',\n]\n\n/** sha256(canonicalJson(record)) over the STORED shape of a period record. @internal */\nexport async function hashStoredPeriod(period: PeriodRecord): Promise<string> {\n  const stored: Record<string, unknown> = { ...(period as unknown as Record<string, unknown>) }\n  for (const f of RETURN_ONLY_FIELDS) delete stored[f]\n  return sha256Hex(canonicalJson(stored))\n}\n\n/**\n * #1454 — every record's `priorPeriodName` / `priorPeriodHash` must resolve to\n * a stored predecessor in ITS timeline whose hash matches. Followed by name,\n * not by sort position: two closes within one millisecond sort arbitrarily,\n * and a deleted predecessor must read as a break, not as a new root.\n *\n * @internal\n */\nexport async function verifyPeriodChain(records: readonly PeriodRecord[]): Promise<void> {\n  const byKey = new Map<string, PeriodRecord>()\n  for (const r of records) byKey.set(resolvePeriodKey(r.name, r.partition), r)\n  for (const r of records) {\n    if (r.priorPeriodName === undefined) {\n      if (r.priorPeriodHash !== '') {\n        throw new PeriodChainError(r.name, 'it names no predecessor but carries a non-empty priorPeriodHash', r.partition)\n      }\n      continue\n    }\n    const prior = byKey.get(resolvePeriodKey(r.priorPeriodName, r.partition))\n    if (!prior) {\n      throw new PeriodChainError(r.name, `its predecessor \"${r.priorPeriodName}\" is missing from the store`, r.partition)\n    }\n    if ((await hashStoredPeriod(prior)) !== r.priorPeriodHash) {\n      throw new PeriodChainError(r.name, `its predecessor \"${r.priorPeriodName}\" no longer hashes to the recorded priorPeriodHash`, r.partition)\n    }\n  }\n}\n\n/**\n * Given the current ordered period list, pick the last entry that\n * belongs to the hash chain — used as the `priorPeriodHash` anchor\n * for the next closure/opening.\n *\n * @internal\n */\nexport async function chainAnchor(\n  records: readonly PeriodRecord[],\n  partition?: PeriodPartition,\n): Promise<{ priorPeriodName?: string; priorPeriodHash: string }> {\n  // #1005 — each timeline carries its OWN chain. Anchoring a partitioned close\n  // to whatever happened to be written last vault-wide would interleave\n  // unrelated subjects into one chain, so verifying client A's June would\n  // depend on client B never having closed in between.\n  const inTimeline = records.filter((p) => samePartition(p.partition, partition))\n  const last = inTimeline[inTimeline.length - 1]\n  if (!last) return { priorPeriodHash: '' }\n  const hash = await hashStoredPeriod(last)\n  return { priorPeriodName: last.name, priorPeriodHash: hash }\n}\n\n/**\n * #1459 — the business-date strings that ORDER correctly against an `endDate`.\n *\n * ⭐ **This is a narrower question than \"is this a valid ISO date\", and the\n * difference is the whole point.** A period membership test is\n * `value <= endDate` on two STRINGS, so the accepted set is exactly the set\n * whose lexicographic order matches calendar order: zero-padded `YYYY-MM-DD`,\n * optionally followed by a time. `'2026-6-15'` names a real day and is refused\n * anyway, because as text it sorts ABOVE `'2026-06-30'` — a June entry waved\n * through a closed June on one missing zero.\n *\n * ⚠️ **Deliberately NOT `civilDateOf()` from `kernel/query/civil-date.ts`.**\n * That function accepts `\\d{1,2}` components on purpose: it resolves a value to\n * a real day and never compares it as text, so padding is irrelevant there and\n * load-bearing here. Two functions, two questions.\n *\n * ⭐ **A partial date is ACCEPTED — `'2026-01'` and `'2026'` are real business\n * dates, and refusing them was this fix's first draft.** The suite caught it:\n * `__tests__/1452-periods-gate-blob-writes.test.ts` seals a billing `cycle`\n * field carrying `'2026-01'`, which is exactly how a monthly cycle is written.\n * And it ORDERS correctly, which is the only thing this predicate is entitled\n * to ask: `'2026-01' <= '2026-01-31'` is true and `'2026-01' > '2025-12-31'`,\n * so a January cycle is sealed by a January close and by nothing earlier.\n *\n * So the rule is **zero-padded components**, not \"must name a day\" — padding\n * is what ordering needs; granularity is the caller's business.\n */\nconst ORDERABLE_ISO =\n  /^(\\d{4})(?:-(\\d{2})(?:-(\\d{2})(?:[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d{1,9})?)?(?:Z|[+-]\\d{2}:\\d{2})?)?)?)?$/\n\n/** Days in `m` of `y`, proleptic Gregorian. */\nfunction daysInPeriodMonth(y: number, m: number): number {\n  if (m === 2) return (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0 ? 29 : 28\n  return m === 4 || m === 6 || m === 9 || m === 11 ? 30 : 31\n}\n\n/**\n * @internal #1459 — is `value` a business date that can be compared against an\n * `endDate` and give the calendar's answer?\n */\nexport function isOrderableBusinessDate(value: string): boolean {\n  const m = ORDERABLE_ISO.exec(value)\n  if (m === null) return false\n  const year = Number(m[1])\n  // Absent components are not wrong — see the header. Only a component that IS\n  // present has to name something real: `'2026-02-30'` orders fine and means\n  // nothing, and `'2026-13'` is not a month.\n  if (m[2] === undefined) return true\n  const month = Number(m[2])\n  if (month < 1 || month > 12) return false\n  if (m[3] === undefined) return true\n  const day = Number(m[3])\n  return day >= 1 && day <= daysInPeriodMonth(year, month)\n}\n\n/**\n * @internal #1459 — the refusal, phrased once so the guard and `closePeriod()`\n * cannot drift on what \"malformed\" means or on how they say it.\n */\nexport function malformedBusinessDate(where: string, value: string): ValidationError {\n  return new ValidationError(\n    `${where} is not an orderable business date: ${JSON.stringify(value)}. ` +\n      `Period membership compares strings, so a date must be zero-padded ` +\n      `ISO-8601 — \"YYYY\", \"YYYY-MM\" or \"YYYY-MM-DD\", optionally with a time ` +\n      `(\"2026-06-30T23:59:59Z\"). Coarser is fine; unpadded is not. ` +\n      `\"2026-6-15\" is refused although it names a real day: as text it sorts ` +\n      `above \"2026-06-30\", so it would slip past a June close.`,\n  )\n}\n\n/**\n * Throw `PeriodClosedError` if the record being touched falls within\n * any closed period.\n *\n * Per period, per side (existing record / incoming record):\n *\n *  1. If the period declares a `dateField`, the guard reads\n *     `record[dateField]` on BOTH the existing (prior) record AND the\n *     incoming (new) record, each under its OWN partition. Either comparing\n *     `<= endDate` triggers the error — callers cannot slide a record into a\n *     closed period by editing its date field.\n *     #1455 — value shapes: a string is compared as-is (ISO-8601 assumed —\n *     the comparison is lexicographic); a `Date` is compared as the ISO string\n *     it will be stored as; `undefined` / `null` means the record carries no\n *     business date and belongs to NO period; anything else is REFUSED with\n *     `ValidationError` — a date the gate cannot evaluate is not a permission.\n *  2. If the period has no `dateField`, the guard falls back to the\n *     envelope `_ts` of the existing record. Fresh inserts (no\n *     existing envelope) pass.\n *  3. For a delete, only the existing side is checked.\n *\n * #1456 — a value is OWNED by the closed period in its timeline with the\n * smallest `endDate` at or after it. When that owner is effectively reopened,\n * no later close vetoes the value: reopening January frees January-dated\n * rows even with February and March closed, and February's rows stay sealed.\n *\n * @internal\n */\nexport function assertTsWritable(\n  existing: { ts: string | null; record: Record<string, unknown> | null } | null,\n  incomingRecord: Record<string, unknown> | null,\n  closedPeriods: readonly PeriodRecord[],\n  scope?: { collection: string; resolve?: PartitionResolver },\n): void {\n  // #1005 — a period only governs records that resolve to ITS timeline. With no\n  // resolver (the default `withPeriods()`), nothing resolves to a partition, so\n  // every record sits on the vault-wide timeline exactly as before and a\n  // partitioned period governs nothing.\n  const partitionOf = (r: Record<string, unknown> | null): PeriodPartition | undefined => {\n    if (!r || !scope?.resolve) return undefined\n    return scope.resolve(scope.collection, r)\n  }\n  const existingRecord = existing?.record ?? null\n  const existingPartition = partitionOf(existingRecord)\n  const incomingPartition = partitionOf(incomingRecord)\n  const existingTs = existing?.ts ?? null\n  // One instant for the whole check, so a bounded reopen window cannot expire\n  // between two periods in the same loop and seal a write half-way.\n  const now = new Date().toISOString()\n  const closed = closedPeriods.filter((p) => p.kind === 'closed')\n\n  // #1456 — is the period that OWNS `value` (in `partition`'s timeline) reopened?\n  const ownerReopened = (value: string, partition: PeriodPartition | undefined): boolean => {\n    let owner: PeriodRecord | undefined\n    for (const p of closed) {\n      if (!samePartition(p.partition, partition)) continue\n      if (value <= p.endDate && (owner === undefined || p.endDate < owner.endDate)) owner = p\n    }\n    return owner !== undefined && isEffectivelyReopened(owner, now)\n  }\n\n  // #1455 — one reading of a side's business date. `null` = no business date.\n  const readDate = (p: PeriodRecord, r: Record<string, unknown>, side: 'existing' | 'incoming'): string | null => {\n    const v = r[p.dateField!]\n    if (v === undefined || v === null) return null\n    if (typeof v === 'string') {\n      // #1459 — validate the STRING, which #1455 did not. Before this, a\n      // malformed value went straight into the comparison: `'hello'` was\n      // written, and `'2026-6-15'` was written INTO a sealed June.\n      if (!isOrderableBusinessDate(v)) throw malformedBusinessDate(`${side}[${p.dateField}]`, v)\n      return v\n    }\n    if (v instanceof Date && !Number.isNaN(v.getTime())) return v.toISOString()\n    throw new ValidationError(\n      `Period guard cannot evaluate ${side}[${p.dateField}] (${v instanceof Date ? 'invalid Date' : typeof v}) ` +\n        `against closed period \"${p.name}\" — a business date must be an ISO-8601 string or a Date. ` +\n        `Refusing rather than admitting the record into a sealed timeline.`,\n    )\n  }\n\n  for (const p of closed) {\n    // #1022 — a reopened period is writable again. This is the ONLY thing a\n    // reopen does: it withdraws the period's veto. It cannot grant a write that\n    // some other gate forbids, because the guard bus ANDs every handler and\n    // record-level guards are registered ahead of this one.\n    if (isEffectivelyReopened(p, now)) continue\n    if (p.dateField) {\n      const checkRecord = (\n        side: 'existing' | 'incoming',\n        r: Record<string, unknown> | null,\n        recordPartition: PeriodPartition | undefined,\n      ): void => {\n        if (!r) return\n        // Both sides are checked under their OWN partition, which is what stops\n        // a write from sliding a record either INTO or OUT OF a sealed\n        // timeline by rewriting the fields the subject mapping reads.\n        if (!samePartition(recordPartition, p.partition)) return\n        const v = readDate(p, r, side)\n        if (v !== null && v <= p.endDate && !ownerReopened(v, recordPartition)) {\n          throw new PeriodClosedError(p.name, p.endDate, `${side}[${p.dateField}]=${v}`, { dateField: p.dateField!, side })\n        }\n      }\n      checkRecord('existing', existingRecord, existingPartition)\n      checkRecord('incoming', incomingRecord, incomingPartition)\n      continue\n    }\n    // Fallback: write-time seal via envelope _ts. Scoped by the EXISTING\n    // record's partition — `_ts` belongs to the stored envelope, so the\n    // incoming side has no write-time of its own to compare.\n    if (!samePartition(existingPartition, p.partition)) continue\n    if (existingTs !== null && existingTs <= p.endDate && !ownerReopened(existingTs, existingPartition)) {\n      throw new PeriodClosedError(p.name, p.endDate, existingTs, { side: 'existing' })\n    }\n  }\n}\n\n/**\n * Sanity-check a proposed period name + endDate against existing\n * records. Shared by closePeriod / openPeriod so the two pathways\n * produce identical diagnostics.\n *\n * @internal\n */\nexport function validatePeriodName(\n  name: string,\n  existing: readonly PeriodRecord[],\n  partition?: PeriodPartition,\n): void {\n  if (name.length === 0) {\n    throw new ValidationError('Period name cannot be empty.')\n  }\n  // Validates the components as a side effect — an empty or non-finite\n  // component must be rejected at the call, not encoded into a storage key.\n  resolvePeriodKey(name, partition)\n  // #1005 — uniqueness is per TIMELINE. `'2026-06'` in `['A','vat']` does not\n  // collide with `'2026-06'` in `['B','vat']`.\n  if (existing.some((p) => p.name === name && samePartition(p.partition, partition))) {\n    const where = partition && partition.length > 0\n      ? ` in partition [${partition.join(', ')}]`\n      : ''\n    throw new ValidationError(`Period \"${name}\" already exists${where}.`)\n  }\n}\n\n/**\n * Wire a reserved-collection ledger append for a period record. The\n * period itself is stored via the adapter as an encrypted envelope;\n * the ledger entry is a normal `put` with the period's payloadHash,\n * so period closures inherit the chain's tamper-evidence.\n *\n * @internal\n */\nexport async function appendPeriodLedgerEntry(\n  ledger: LedgerStore | null,\n  actor: string,\n  envelope: EncryptedEnvelope,\n  name: string,\n  collection: string = PERIODS_COLLECTION,\n): Promise<void> {\n  if (!ledger) return\n  const { envelopePayloadHash } = await import('../../with-commit/history/ledger/index.js')\n  await ledger.append({\n    op: 'put',\n    collection,\n    id: name,\n    version: envelope._v,\n    actor,\n    payloadHash: await envelopePayloadHash(envelope),\n  })\n}\n\n/**\n * @internal #615. Sweep delete markers with `_ts < before` off ANY store\n * (the vault's local adapter, or a push-only sync target). Returns the count\n * removed. Shared by `vault._purgeDeleteMarkers` (local) and\n * `vault._purgePeriodTargets` (push-only targets).\n */\nexport async function purgeMarkersOn(\n  store: NoydbStore,\n  vault: string,\n  before: string,\n  collections?: string[],\n): Promise<number> {\n  const snapshot = await store.loadAll(vault)\n  let removed = 0\n  for (const [coll, records] of Object.entries(snapshot)) {\n    if (collections && !collections.includes(coll)) continue\n    for (const [id, env] of Object.entries(records)) {\n      if (isDeleteMarker(env) && env._ts < before) {\n        await store.delete(vault, coll, id)\n        removed++\n      }\n    }\n  }\n  return removed\n}\n","/**\n * Active periods strategy factory. Only reachable through the\n * `@noy-db/hub/periods` subpath.\n */\n\nimport {\n  loadPeriods,\n  chainAnchor,\n  assertTsWritable,\n  validatePeriodName,\n  appendPeriodLedgerEntry,\n} from './periods.js'\nimport type { PeriodPartition, PartitionResolver } from './periods.js'\nimport type { PeriodsStrategy } from './strategy.js'\n\n/** Options for {@link withPeriods}. */\nexport interface WithPeriodsOptions {\n  /**\n   * Maps a collection to the timeline each of its records belongs to (#1005) —\n   * the answer to \"which close calendar governs THIS record\".\n   *\n   * ```ts\n   * withPeriods({\n   *   subjects: { receipts: (r) => [r.clientId, layerOf(r)] },\n   * })\n   * ```\n   *\n   * Same shape as `withForget({ subjects })`, which answers the same question\n   * for erasure. A collection with no entry — and every collection when\n   * `subjects` is omitted entirely — stays on the vault-wide timeline, so an\n   * existing vault behaves exactly as it did before partitions existed.\n   *\n   * Return `undefined` from a mapper to put an individual record back on the\n   * vault-wide timeline (e.g. a record that predates the field the mapping\n   * reads).\n   */\n  readonly subjects?: Readonly<\n    Record<string, (record: Record<string, unknown>) => PeriodPartition | undefined>\n  >\n}\n\n/**\n * Build the default periods strategy. Pass into\n * `createNoydb({ periodsStrategy: withPeriods() })` to enable\n * `vault.closePeriod()` / `vault.openPeriod()` / write-guards.\n *\n * Pass `subjects` to run more than one close calendar in a single vault — see\n * {@link WithPeriodsOptions.subjects}.\n */\nexport function withPeriods(options?: WithPeriodsOptions): PeriodsStrategy {\n  const subjects = options?.subjects\n  const partitionOf: PartitionResolver | undefined = subjects\n    ? (collection, record) => subjects[collection]?.(record)\n    : undefined\n\n  return {\n    loadPeriods,\n    chainAnchor,\n    assertTsWritable,\n    validatePeriodName,\n    appendPeriodLedgerEntry,\n    ...(partitionOf !== undefined && { partitionOf }),\n  }\n}\n","/**\n * Strategy seam for the optional accounting-periods service. Core\n * imports `PeriodsStrategy` type-only + `NO_PERIODS` stub; the real\n * `loadPeriods` / `chainAnchor` / `assertTsWritable` /\n * `validatePeriodName` / `appendPeriodLedgerEntry` functions are\n * only reachable via `withPeriods()` in `./active.ts`.\n *\n * Applications that never call `vault.closePeriod()` /\n * `vault.openPeriod()` ship none of the ~363 LOC.\n *\n * @internal\n */\n\nimport type { EncryptedEnvelope, NoydbStore } from '../../kernel/types.js'\nimport type { LedgerStore } from '../../with-commit/history/ledger/store.js'\nimport type { PeriodRecord, PeriodPartition, PartitionResolver } from './periods.js'\n\n/**\n * @internal\n */\nexport interface PeriodsStrategy {\n  loadPeriods(\n    adapter: NoydbStore,\n    vault: string,\n    decrypt: (id: string, envelope: EncryptedEnvelope) => Promise<PeriodRecord>,\n  ): Promise<PeriodRecord[]>\n  chainAnchor(records: readonly PeriodRecord[], partition?: PeriodPartition): Promise<{\n    priorPeriodName?: string\n    priorPeriodHash: string\n  }>\n  assertTsWritable(\n    existing: { ts: string | null; record: Record<string, unknown> | null } | null,\n    incoming: Record<string, unknown> | null,\n    periods: readonly PeriodRecord[],\n    scope?: { collection: string; resolve?: PartitionResolver },\n  ): void\n  validatePeriodName(\n    name: string,\n    existing: readonly PeriodRecord[],\n    partition?: PeriodPartition,\n  ): void\n  /**\n   * Record → timeline resolver built from `withPeriods({ subjects })` (#1005).\n   * `undefined` when the caller configured no subjects, which keeps every\n   * record on the vault-wide timeline.\n   */\n  readonly partitionOf?: PartitionResolver\n  appendPeriodLedgerEntry(\n    ledger: LedgerStore | null,\n    actor: string,\n    envelope: EncryptedEnvelope,\n    periodName: string,\n    collection?: string,\n  ): Promise<void>\n}\n\n/**\n * No-periods stub. `loadPeriods` returns `[]`; the write-guards do\n * nothing (vaults without closed periods never reject writes);\n * `validatePeriodName` / `appendPeriodLedgerEntry` throw because\n * those paths are only reached when the user explicitly called\n * `closePeriod()` / `openPeriod()` — if they did that without the\n * strategy, they need to wire it.\n *\n * @internal\n */\nconst NOT_ENABLED = new Error(\n  'Accounting periods require the periods strategy. Import ' +\n  '`{ withPeriods }` from \"@noy-db/hub/periods\" and pass it to ' +\n  '`createNoydb({ periodsStrategy: withPeriods() })`.',\n)\n\nexport const NO_PERIODS: PeriodsStrategy = {\n  async loadPeriods() { return [] },\n  async chainAnchor() { return { priorPeriodHash: '' } },\n  assertTsWritable() {},\n  validatePeriodName() { throw NOT_ENABLED },\n  async appendPeriodLedgerEntry() { throw NOT_ENABLED },\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-QIBVIOXO.js → chunk-NWHBJQAL.js}

@@ -1,11 +1,17 @@
+import {
+  describeGroupKey
+} from "./chunk-XBKH4FOC.js";
+import {
+  normalizeJoinOn
+} from "./chunk-MKXXMNJH.js";
 import {
   sha256Hex
-} from "./chunk-SL3JAAKN.js";
+} from "./chunk-UYB234ZR.js";
 import {
   MaterializedViewConfigError,
   MaterializedViewSourceUnknownError,
   RefNotDeclaredError
-} from "./chunk-7O3Y4PPD.js";
+} from "./chunk-244VXYPG.js";
 
 // src/with-formula/materialized-views/dependency-analyzer.ts
 function analyzeDependencies(query) {
@@ -57,9 +63,57 @@ function summarizeQueryPlan(query) {
     orderBy: plan.orderBy,
     limit: plan.limit ?? null,
     offset: plan.offset,
-    joins: plan.joins.map((j) => ({ field: j.field, as: j.as, target: j.target, mode: j.mode }))
+    joins: plan.joins.map((j) => summarizeJoinLeg(j))
   });
 }
+function summarizeJoinLeg(j) {
+  return {
+    field: j.field,
+    as: j.as,
+    target: j.target,
+    mode: j.mode,
+    // #1339 — the declared `on` IS the join's identity: two `.joinOn()`
+    // plans differing only here select different rows, and without this key
+    // they would hash identically and neither MV would ever be seen as
+    // stale. `undefined` for every other leg, and `JSON.stringify` drops an
+    // undefined value, so a plan carrying no `joinOn` summarises
+    // byte-identically to its pre-#1339 self and no stored hash moves.
+    on: j.on,
+    // #1389 — `direction` (#1289) decides which SIDE is preserved: a right or
+    // full leg emits rows a left leg never produces. Omitted for a left leg,
+    // which is `undefined` on the leg itself, so a plain `.join()` plan is
+    // byte-identical to its pre-#1389 summary.
+    direction: j.direction,
+    // #1389 — `inner` (#1361) DROPS every unmatched left row. Only ever
+    // `true`; `undefined` on every other leg, so again nothing moves for a
+    // plan that does not use it.
+    inner: j.inner,
+    // #1389 — a dict join attaches `{ ...labels, key }` from the dictionary
+    // snapshot instead of a right-side record, and `target` names a
+    // dictionary rather than a collection. Two legs can otherwise agree on
+    // all four base keys (a dict leg's `target` IS its `field`, which a ref
+    // join to a like-named collection reproduces), so without this key they
+    // hash identically while materializing different rows. Only ever `true`.
+    isDictJoin: j.isDictJoin
+    // ── EXCLUDED, deliberately (#1389). Read before adding one. ──────────
+    //
+    // `partitionScope` — NOT emitted, and this is the load-bearing one. It is
+    //   `'all'` on every leg ever built and the executor never reads it
+    //   (#1342), so it cannot change a row. It is also present unconditionally
+    //   rather than omitted-at-default, so starting to emit it would move
+    //   EVERY joined MV's hash at once for zero semantic gain. If a future
+    //   change ever makes it narrowable, emit it only when it is not `'all'`.
+    //
+    // `strategy` — NOT emitted: a manual planner override picks HOW the same
+    //   rows are produced (hash vs lookup), never which. Emitting it would
+    //   force a full recompute for a pure performance tweak.
+    //
+    // `maxRows` — NOT emitted: a per-side ceiling that throws
+    //   `JoinTooLargeError` when crossed. A query that succeeds returns the
+    //   same rows at any ceiling above its size, so it is not part of the
+    //   plan's row identity.
+  };
+}
 function summarizeUnionPlan(spec) {
   return `union(${summarizeUnionArms(spec)})${summarizeGroupingTail(spec)}`;
 }
@@ -74,15 +128,27 @@ function summarizeProjectionPlan(spec) {
 }
 function summarizeUnionArms(spec) {
   return (spec.unionSources ?? []).map((s) => {
-    const joins = s.join?.length ? `[${s.join.map((j) => `${j.field}\u2192${j.as}`).join(";")}]` : "";
+    const joins = s.join?.length ? `[${s.join.map((j) => "on" in j ? `${j.target}?${JSON.stringify(normalizeJoinOn(j.on, j.target))}${j.mode === "inner" ? "!" : ""}\u2192${j.as}` : `${j.field}\u2192${j.as}`).join(";")}]` : "";
     return `${s.collection}${joins}`;
   }).join(",");
 }
+function summarizeWindow(spec) {
+  if (!spec.window) return "";
+  const list = (v) => {
+    if (v === void 0) return "";
+    const arr = Array.isArray(v) ? v : [v];
+    return arr.map(
+      (k) => typeof k === "object" && k !== null && "field" in k ? `${describeGroupKey(k.field)}:${String(k.direction ?? "asc")}` : describeGroupKey(k)
+    ).join(",");
+  };
+  const selectKeys = Object.keys(spec.window.select).sort().join(",");
+  return `|window(partition(${list(spec.window.partitionBy)})order(${list(spec.window.orderBy)})select(${selectKeys}))`;
+}
 function summarizeGroupingTail(spec) {
-  const groupBy = Array.isArray(spec.groupBy) ? [...spec.groupBy].sort().join(",") : typeof spec.groupBy === "string" ? spec.groupBy : "";
+  const groupBy = Array.isArray(spec.groupBy) ? spec.groupBy.map(describeGroupKey).sort().join(",") : spec.groupBy === void 0 ? "" : describeGroupKey(spec.groupBy);
   const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(",") : "";
   const moneyKeys = spec.moneyFields ? Object.keys(spec.moneyFields).sort().join(",") : "";
-  return `|groupBy(${groupBy})|aggregate(${aggKeys})|money(${moneyKeys})`;
+  return `|groupBy(${groupBy})|aggregate(${aggKeys})|money(${moneyKeys})${summarizeWindow(spec)}`;
 }
 
 // src/with-formula/materialized-views/query-hash.ts
@@ -206,7 +272,8 @@ var MaterializedViewRegistry = class {
    * `knownCollections` checker is supplied).
    */
   async register(spec, db, options) {
-    const dbForQuery = spec.predicates ? wrapDbWithPredicates(db, spec.predicates) : db;
+    const ungatedDb = ungatedMvContext(db);
+    const dbForQuery = spec.predicates ? wrapDbWithPredicates(ungatedDb, spec.predicates) : ungatedDb;
     let dependencies;
     let queryPlanSummary;
     let qAny = null;
@@ -215,6 +282,7 @@ var MaterializedViewRegistry = class {
     if (spec.unionSources) {
       dependencies = new Set(spec.unionSources.map((s) => s.collection));
       if (spec.sources) for (const s of spec.sources) dependencies.add(s);
+      for (const arm of spec.unionSources) for (const leg of arm.join ?? []) if ("on" in leg) dependencies.add(leg.target);
       queryPlanSummary = summarizeUnionPlan(spec);
     } else if (spec.projection) {
       const projection = spec.projection;
@@ -409,6 +477,28 @@ var MaterializedViewRegistry = class {
 function isFieldClauseOnField(clause, field) {
   return clause.type === "field" && clause.field === field;
 }
+function ungatedMvContext(db) {
+  return {
+    // ⚠️ Every argument is forwarded. A spec's `db.collection(name, { tiers })`
+    // supplies the options at FIRST construction (first-construction wins), so
+    // a wrapper that drops the second argument silently un-declares them.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    collection(name, ...rest) {
+      const c = db.collection(name, ...rest);
+      return new Proxy(c, {
+        get(target, prop, receiver) {
+          if (prop === "query") {
+            return (...args) => {
+              const q = target.query(...args);
+              return q && typeof q._ungated === "function" ? q._ungated() : q;
+            };
+          }
+          return Reflect.get(target, prop, receiver);
+        }
+      });
+    }
+  };
+}
 function wrapDbWithPredicates(db, predicates) {
   const map = /* @__PURE__ */ new Map();
   for (const [name, decl] of Object.entries(predicates)) {
@@ -481,6 +571,7 @@ export {
   validateProjectionLegs,
   resolveLegOwner,
   MaterializedViewRegistry,
+  ungatedMvContext,
   wrapDbWithPredicates
 };
-//# sourceMappingURL=chunk-QIBVIOXO.js.map
+//# sourceMappingURL=chunk-NWHBJQAL.js.map