@noy-db/hub 0.2.0-pre.3 → 0.2.0-pre.31

package/dist/chunk-KYKMKLJ6.js

@@ -1,340 +0,0 @@
-import {
-  readPath
-} from "./chunk-MRIBLZL3.js";
-import {
-  GroupCardinalityError
-} from "./chunk-YDLAFP36.js";
-
-// src/aggregate/aggregation.ts
-function reduceRecords(records, spec) {
-  const state = {};
-  for (const key of Object.keys(spec)) {
-    state[key] = spec[key].init();
-  }
-  for (const record of records) {
-    for (const key of Object.keys(spec)) {
-      state[key] = spec[key].step(state[key], record);
-    }
-  }
-  const result = {};
-  for (const key of Object.keys(spec)) {
-    result[key] = spec[key].finalize(state[key]);
-  }
-  return result;
-}
-var LiveAggregationImpl = class {
-  constructor(recompute, upstreams) {
-    this.recompute = recompute;
-    try {
-      this.value = recompute();
-      this.error = void 0;
-    } catch (err) {
-      this.value = void 0;
-      this.error = err;
-    }
-    for (const upstream of upstreams) {
-      const unsub = upstream.subscribe(() => this.refresh());
-      this.unsubscribes.push(unsub);
-    }
-  }
-  recompute;
-  value;
-  error;
-  listeners = /* @__PURE__ */ new Set();
-  unsubscribes = [];
-  stopped = false;
-  refresh() {
-    if (this.stopped) return;
-    try {
-      this.value = this.recompute();
-      this.error = void 0;
-    } catch (err) {
-      this.error = err;
-    }
-    for (const listener of this.listeners) {
-      try {
-        listener();
-      } catch (err) {
-        console.warn("[noy-db] LiveAggregation listener threw:", err);
-      }
-    }
-  }
-  subscribe(cb) {
-    if (this.stopped) {
-      return () => {
-      };
-    }
-    this.listeners.add(cb);
-    return () => {
-      this.listeners.delete(cb);
-    };
-  }
-  stop() {
-    if (this.stopped) return;
-    this.stopped = true;
-    for (const unsub of this.unsubscribes) {
-      try {
-        unsub();
-      } catch (err) {
-        console.warn("[noy-db] LiveAggregation upstream unsubscribe threw:", err);
-      }
-    }
-    this.unsubscribes.length = 0;
-    this.listeners.clear();
-  }
-};
-var Aggregation = class {
-  constructor(executeRecords, spec, upstreams) {
-    this.executeRecords = executeRecords;
-    this.spec = spec;
-    this.upstreams = upstreams;
-  }
-  executeRecords;
-  spec;
-  upstreams;
-  /**
-   * Execute the query and reduce the results synchronously.
-   * Returns the reduced shape matching the spec — e.g. a spec of
-   * `{ total: sum('amount'), n: count() }` returns
-   * `{ total: number, n: number }`.
-   */
-  run() {
-    return reduceRecords(this.executeRecords(), this.spec);
-  }
-  /**
-   * Build a reactive `LiveAggregation<R>` that re-runs the reduction
-   * whenever any upstream source notifies of a change. The initial
-   * value is computed eagerly in the constructor, so consumers can
-   * read `live.value` immediately after calling `.live()`.
-   *
-   * Always call `live.stop()` when finished — it tears down the
-   * upstream subscriptions. Vue's `onUnmounted` is the canonical
-   * place.
-   *
-   * **Implementation note:** every upstream change triggers a full
-   * re-reduction. Incremental maintenance (O(1) per delta for
-   * sum/count/avg via the reducer protocol's `remove()` method) is a
-   * planned follow-up optimization — the protocol already supports
-   * it, but the executor doesn't drive it yet. Consumers get
-   * correct, reactive values today; future PRs can switch to
-   * delta-based maintenance without changing this API.
-   */
-  live() {
-    const recompute = () => reduceRecords(this.executeRecords(), this.spec);
-    return new LiveAggregationImpl(recompute, this.upstreams);
-  }
-};
-function buildLiveAggregation(recompute, upstreams) {
-  return new LiveAggregationImpl(recompute, upstreams);
-}
-
-// src/aggregate/canonical-key.ts
-function canonicalGroupKey(fields, row) {
-  const sorted = [...fields].sort();
-  const parts = [];
-  for (const name of sorted) {
-    const v = row[name];
-    const serialised = v === void 0 ? "undefined" : JSON.stringify(v);
-    parts.push(`${name}=${serialised}`);
-  }
-  return parts.join("|");
-}
-
-// src/aggregate/groupby.ts
-var GROUPBY_WARN_CARDINALITY = 1e4;
-var GROUPBY_MAX_CARDINALITY = 1e5;
-var warnedCardinalityFields = /* @__PURE__ */ new Set();
-function warnCardinalityApproaching(fields, observed) {
-  const key = JSON.stringify([...fields].sort());
-  if (warnedCardinalityFields.has(key)) return;
-  warnedCardinalityFields.add(key);
-  const label = `[${fields.join(", ")}]`;
-  console.warn(
-    `[noy-db] .groupBy(${label}) produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
-  );
-}
-function resetGroupByWarnings() {
-  warnedCardinalityFields.clear();
-}
-var GroupedQueryBase = class {
-  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-    this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
-  }
-  executeRecords;
-  upstreams;
-  dictLabelResolver;
-  /**
-   * Field set this grouped query buckets on. Stored in declaration
-   * order — the same order is preserved on every result row by
-   * `groupAndReduce`. For the single-field constructor, this is
-   * `[field]`.
-   */
-  fields;
-};
-var GroupedQuery = class extends GroupedQueryBase {
-  /**
-   * Build a grouped aggregation. Returns a `GroupedAggregation`
-   * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
-   * as the non-grouped `.aggregate()` wrapper, just with an array
-   * result (one row per bucket) instead of a single reduced object.
-   */
-  aggregate(spec) {
-    return new GroupedAggregation(
-      this.executeRecords,
-      this.fields,
-      spec,
-      this.upstreams,
-      this.dictLabelResolver
-    );
-  }
-};
-var GroupedQueryN = class extends GroupedQueryBase {
-  aggregate(spec) {
-    return new GroupedAggregation(
-      this.executeRecords,
-      this.fields,
-      spec,
-      this.upstreams,
-      this.dictLabelResolver
-    );
-  }
-};
-function groupAndReduce(records, fieldOrFields, spec) {
-  const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
-  if (fields.length === 0) {
-    throw new Error(".groupBy() requires at least one field");
-  }
-  const buckets = /* @__PURE__ */ new Map();
-  const fieldLabel = fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
-  for (const record of records) {
-    const keyValues = {};
-    for (const f of fields) {
-      keyValues[f] = readPath(record, f);
-    }
-    const dedupKey = canonicalGroupKey(fields, keyValues);
-    let bucket = buckets.get(dedupKey);
-    if (bucket === void 0) {
-      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
-        throw new GroupCardinalityError(
-          fieldLabel,
-          buckets.size + 1,
-          GROUPBY_MAX_CARDINALITY
-        );
-      }
-      bucket = { keyValues, records: [] };
-      buckets.set(dedupKey, bucket);
-    }
-    bucket.records.push(record);
-  }
-  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
-    warnCardinalityApproaching(fields, buckets.size);
-  }
-  const reducerKeys = Object.keys(spec);
-  const out = [];
-  for (const bucket of buckets.values()) {
-    const state = {};
-    for (const rk of reducerKeys) {
-      state[rk] = spec[rk].init();
-    }
-    for (const record of bucket.records) {
-      for (const rk of reducerKeys) {
-        state[rk] = spec[rk].step(state[rk], record);
-      }
-    }
-    const row = {};
-    for (const f of fields) {
-      row[f] = bucket.keyValues[f];
-    }
-    for (const rk of reducerKeys) {
-      row[rk] = spec[rk].finalize(state[rk]);
-    }
-    out.push(row);
-  }
-  return out;
-}
-var GroupedAggregation = class {
-  constructor(executeRecords, fields, spec, upstreams, dictLabelResolver) {
-    this.executeRecords = executeRecords;
-    this.spec = spec;
-    this.upstreams = upstreams;
-    this.dictLabelResolver = dictLabelResolver;
-    this.fields = typeof fields === "string" ? [fields] : [...fields];
-  }
-  executeRecords;
-  spec;
-  upstreams;
-  dictLabelResolver;
-  fields;
-  /** Execute the query, group, reduce, and return an array of rows. */
-  run() {
-    return groupAndReduce(this.executeRecords(), this.fields, this.spec);
-  }
-  /**
-   * Execute the query, group, reduce, and resolve `<field>Label` for
-   * each result row when the grouping field is a `dictKey` and a
-   * `locale` is provided. Returns `R[]` synchronously when
-   * no locale is specified (identical to `.run()`).
-   *
-   * The `<field>Label` field is appended to each row. Rows whose group
-   * key has no dictionary entry get `<field>Label: undefined`.
-   *
-   * Dict-label resolution is single-field only — multi-key groupings
-   * do not produce a `<field>Label`. The resolver is only attached
-   * by the builder when `fields.length === 1`.
-   */
-  async runAsync(opts) {
-    const rows = groupAndReduce(this.executeRecords(), this.fields, this.spec);
-    if (!opts?.locale || !this.dictLabelResolver || this.fields.length !== 1) return rows;
-    const resolve = this.dictLabelResolver;
-    const locale = opts.locale;
-    const fallback = opts.fallback;
-    const field = this.fields[0];
-    const labelKey = `${field}Label`;
-    return Promise.all(
-      rows.map(async (row) => {
-        const key = row[field];
-        if (typeof key !== "string") return row;
-        const label = await resolve(key, locale, fallback);
-        return { ...row, [labelKey]: label };
-      })
-    );
-  }
-  /**
-   * Build a reactive `LiveAggregation<R[]>` that re-runs the full
-   * group-and-reduce pipeline whenever any upstream source notifies
-   * of a change. Same error-isolation and idempotent-stop contract
-   * as `Aggregation.live()` — the implementation delegates to the
-   * same `LiveAggregationImpl` class by threading a fresh
-   * recompute closure through the existing constructor.
-   *
-   * uses naive full re-run on every change. Incremental
-   * per-bucket maintenance (apply `step` on inserted records,
-   * `remove` on deleted records, route by bucket key) is a future
-   * optimization — the reducer protocol admits it, but wiring
-   * delta-aware source subscriptions is a separate PR.
-   *
-   * Always call `live.stop()` when finished.
-   */
-  live() {
-    const recompute = () => groupAndReduce(this.executeRecords(), this.fields, this.spec);
-    return buildLiveAggregation(recompute, this.upstreams);
-  }
-};
-
-export {
-  reduceRecords,
-  Aggregation,
-  buildLiveAggregation,
-  canonicalGroupKey,
-  GROUPBY_WARN_CARDINALITY,
-  GROUPBY_MAX_CARDINALITY,
-  resetGroupByWarnings,
-  GroupedQuery,
-  GroupedQueryN,
-  groupAndReduce,
-  GroupedAggregation
-};
-//# sourceMappingURL=chunk-KYKMKLJ6.js.map

package/dist/chunk-KYKMKLJ6.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/aggregate/aggregation.ts","../src/aggregate/canonical-key.ts","../src/aggregate/groupby.ts"],"sourcesContent":["/**\n * Aggregate execution — the runtime behind `Query.aggregate()`.\n *\n * takes an `AggregateSpec` (a record of named reducers\n * built from `reducers.ts`) and runs every reducer over the records\n * produced by the underlying query. Two terminal surfaces:\n *\n *   - `.run(): R` — synchronous one-shot reduction. Matches the\n *     existing `Query.toArray()` / `.first()` / `.count()` style.\n *   - `.live(): LiveAggregation<R>` — reactive primitive that\n *     re-runs the reduction whenever the query's source notifies of\n *     a change. uses naive full re-run; incremental delta\n *     maintenance is admitted by the reducer protocol (`remove()`)\n *     but not wired to the executor yet — a follow-up optimization\n *     can switch from full re-run to delta-based without breaking\n *     the public API. Consumers get correct, reactive values today.\n *\n * The `Aggregation<R>` wrapper is deliberately tiny — it exists so\n * `.aggregate(spec)` can be chained with either `.run()` or `.live()`\n * without the builder needing two separate terminal methods. It\n * holds the closure over the query execution (produces the current\n * matching record set) and the spec, and stitches them together in\n * either mode.\n *\n * This file depends ONLY on `reducers.ts` — it has no knowledge of\n * the `Query` class. Tests can therefore exercise the reduction\n * surface with plain record arrays, without spinning up a Collection.\n */\n\nimport type { Reducer } from './reducers.js'\n\n/**\n * A named set of reducers, keyed by output field name. Each key\n * becomes a field on the aggregated result.\n *\n * ```ts\n * const spec = {\n *   total: sum('amount'),\n *   n:     count(),\n *   avgAmount: avg('amount'),\n * }\n * ```\n */\nexport type AggregateSpec = Readonly<Record<string, Reducer<unknown, unknown>>>\n\n/**\n * Map an `AggregateSpec` to its reduced result shape — each key\n * carries the finalized result type from its reducer. A spec built\n * from `{ total: sum('amount'), n: count() }` yields a result of\n * `{ total: number, n: number }`.\n *\n * This uses a mapped type with a conditional to extract `R` from\n * each `Reducer<R, _>`. The `infer` captures the user-visible result\n * type, discarding the internal state type `S`.\n */\nexport type AggregateResult<Spec extends AggregateSpec> = {\n  [K in keyof Spec]: Spec[K] extends Reducer<infer R, unknown> ? R : never\n}\n\n/**\n * Pure reduction over a record array. Runs every reducer's\n * `init → step* → finalize` pipeline exactly once over the records.\n *\n * Called by `Aggregation.run()` and by the live-mode refresh path.\n * Exported for tests and for future `scan().aggregate()` reuse\n * — the streaming path will call the same reducer protocol with a\n * per-page loop instead of a single array.\n */\nexport function reduceRecords<Spec extends AggregateSpec>(\n  records: readonly unknown[],\n  spec: Spec,\n): AggregateResult<Spec> {\n  // Per-slot state, keyed by the spec's output field name.\n  const state: Record<string, unknown> = {}\n  for (const key of Object.keys(spec)) {\n    state[key] = spec[key]!.init()\n  }\n  for (const record of records) {\n    for (const key of Object.keys(spec)) {\n      state[key] = spec[key]!.step(state[key], record)\n    }\n  }\n  const result: Record<string, unknown> = {}\n  for (const key of Object.keys(spec)) {\n    result[key] = spec[key]!.finalize(state[key])\n  }\n  return result as AggregateResult<Spec>\n}\n\n/**\n * A minimal reactive primitive for aggregation results.\n *\n * Same spirit as the `LiveQuery` in : frame-agnostic, a plain\n * object with `value` / `error` fields and a `subscribe(cb)`\n * notification channel that Vue / React / Solid adapters wrap in\n * their own primitive. Intentionally NOT a Promise — aggregations\n * have a well-defined \"current value\" at every instant, and the\n * reactive consumer wants to read that value synchronously.\n *\n * Error semantics mirror `LiveQuery`: if a re-run throws, the\n * previous successful `value` is preserved and the error is stored\n * in `error` so consumers can render an error state without losing\n * the last-known-good result. The throw does NOT propagate out of\n * the source's change handler (which would tear down the upstream\n * emitter).\n *\n * `stop()` tears down the upstream subscription. It is idempotent —\n * calling it multiple times is safe — and subscribe calls after\n * stop are no-ops (they immediately return a no-op unsubscribe).\n * Always call `stop()` when done; Vue's `onUnmounted` is the\n * canonical place. Raw consumers must do it themselves.\n */\nexport interface LiveAggregation<R> {\n  /** Current reduced value. Undefined only if the first compute threw. */\n  readonly value: R | undefined\n  /** Last execution error, if any. Cleared on the next successful run. */\n  readonly error: unknown\n  /** Notify on every recomputation (success or error). Returns unsubscribe. */\n  subscribe(cb: () => void): () => void\n  /** Tear down the upstream subscription. Idempotent. */\n  stop(): void\n}\n\n/**\n * Upstream change-notification hook for live aggregation.\n *\n * Matches the shape that `QuerySource.subscribe` already uses — a\n * single method that accepts a callback and returns an unsubscribe\n * function. The `Aggregation` wrapper collects upstreams from the\n * query's source and wires them into a single re-run trigger.\n */\nexport interface AggregationUpstream {\n  subscribe(cb: () => void): () => void\n}\n\n/**\n * Internal implementation of `LiveAggregation`. Not exported —\n * consumers get the interface only. The class wraps a `recompute`\n * closure (which runs the full reduction and returns the new value)\n * and a list of upstreams (sources whose changes should trigger a\n * re-run).\n *\n * Error isolation: if an individual listener callback throws, the\n * other listeners still fire and the error is logged to the warn\n * channel. This matches `LiveQuery` from  and keeps one misbehaving\n * consumer from tearing down the whole live aggregation.\n */\nclass LiveAggregationImpl<R> implements LiveAggregation<R> {\n  public value: R | undefined\n  public error: unknown\n  private readonly listeners = new Set<() => void>()\n  private readonly unsubscribes: Array<() => void> = []\n  private stopped = false\n\n  constructor(\n    private readonly recompute: () => R,\n    upstreams: readonly AggregationUpstream[],\n  ) {\n    // Initial computation — surface any error through the `error`\n    // field rather than letting the constructor throw, so consumers\n    // can always construct a LiveAggregation and check its state\n    // afterwards. Throwing from a constructor would force every\n    // caller to wrap in try/catch, which is the opposite of the\n    // \"reactive value with error state\" ergonomics we want.\n    try {\n      this.value = recompute()\n      this.error = undefined\n    } catch (err) {\n      this.value = undefined\n      this.error = err\n    }\n\n    // Wire up upstream subscriptions. Each one triggers a full\n    // recomputation; we don't attempt incremental updates in.\n    for (const upstream of upstreams) {\n      const unsub = upstream.subscribe(() => this.refresh())\n      this.unsubscribes.push(unsub)\n    }\n  }\n\n  private refresh(): void {\n    if (this.stopped) return\n    try {\n      this.value = this.recompute()\n      this.error = undefined\n    } catch (err) {\n      // Preserve the previous successful value — consumers render an\n      // error state using `error` without losing the last-known-good\n      // number. This matches LiveQuery's error-preservation contract.\n      this.error = err\n    }\n    for (const listener of this.listeners) {\n      try {\n        listener()\n      } catch (err) {\n        // Isolate listener errors so one bad consumer can't tear\n        // down every other subscriber on the same aggregation.\n        console.warn('[noy-db] LiveAggregation listener threw:', err)\n      }\n    }\n  }\n\n  subscribe(cb: () => void): () => void {\n    if (this.stopped) {\n      // No-op after stop. Returning a harmless unsubscribe lets\n      // consumers use the same teardown pattern unconditionally.\n      return () => {}\n    }\n    this.listeners.add(cb)\n    return () => {\n      this.listeners.delete(cb)\n    }\n  }\n\n  stop(): void {\n    if (this.stopped) return\n    this.stopped = true\n    for (const unsub of this.unsubscribes) {\n      try {\n        unsub()\n      } catch (err) {\n        console.warn('[noy-db] LiveAggregation upstream unsubscribe threw:', err)\n      }\n    }\n    this.unsubscribes.length = 0\n    this.listeners.clear()\n  }\n}\n\n/**\n * Chainable wrapper returned by `Query.aggregate(spec)`. Holds the\n * execute-records closure and the spec; terminal methods (`run`,\n * `live`) stitch them together in either mode.\n *\n * Why a wrapper instead of two terminal methods on `Query` directly?\n *\n * The `.aggregate(spec)` call is where the spec is bound — both\n * `.run()` and `.live()` need the same spec, and the consumer's\n * fluent style is `query.where(...).aggregate(spec).run()` or\n * `.aggregate(spec).live()`. Wrapping lets the spec be named once\n * and reused for either terminal, and keeps the `Query` class\n * from growing a pair of near-duplicate method overloads\n * (`aggregateRun` / `aggregateLive`) that would be harder to\n * discover.\n */\nexport class Aggregation<R> {\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    private readonly spec: AggregateSpec,\n    private readonly upstreams: readonly AggregationUpstream[],\n  ) {}\n\n  /**\n   * Execute the query and reduce the results synchronously.\n   * Returns the reduced shape matching the spec — e.g. a spec of\n   * `{ total: sum('amount'), n: count() }` returns\n   * `{ total: number, n: number }`.\n   */\n  run(): R {\n    return reduceRecords(this.executeRecords(), this.spec) as unknown as R\n  }\n\n  /**\n   * Build a reactive `LiveAggregation<R>` that re-runs the reduction\n   * whenever any upstream source notifies of a change. The initial\n   * value is computed eagerly in the constructor, so consumers can\n   * read `live.value` immediately after calling `.live()`.\n   *\n   * Always call `live.stop()` when finished — it tears down the\n   * upstream subscriptions. Vue's `onUnmounted` is the canonical\n   * place.\n   *\n   * **Implementation note:** every upstream change triggers a full\n   * re-reduction. Incremental maintenance (O(1) per delta for\n   * sum/count/avg via the reducer protocol's `remove()` method) is a\n   * planned follow-up optimization — the protocol already supports\n   * it, but the executor doesn't drive it yet. Consumers get\n   * correct, reactive values today; future PRs can switch to\n   * delta-based maintenance without changing this API.\n   */\n  live(): LiveAggregation<R> {\n    const recompute = (): R =>\n      reduceRecords(this.executeRecords(), this.spec) as unknown as R\n    return new LiveAggregationImpl<R>(recompute, this.upstreams)\n  }\n}\n\n/**\n * Build a `LiveAggregation<V>` from a recompute closure and a list\n * of upstreams. Exposed so sibling files in the query DSL\n * (currently `groupby.ts`) can reuse the reactive primitive\n * without reaching into `LiveAggregationImpl` directly. This keeps\n * the implementation class private while still allowing planned\n * composition with `.groupBy().aggregate().live()`.\n */\nexport function buildLiveAggregation<V>(\n  recompute: () => V,\n  upstreams: readonly AggregationUpstream[],\n): LiveAggregation<V> {\n  return new LiveAggregationImpl<V>(recompute, upstreams)\n}\n","/**\n * Canonicalise a group-key tuple to a stable string for dedup hashing.\n *\n * Sorts field names lexicographically before serialising, so that\n * `.groupBy('a', 'b')` and `.groupBy('b', 'a')` produce identical\n * keys for the same logical group. Values are JSON-stringified;\n * `undefined` and `null` are distinguished (matching the Map-key\n * semantics in `groupAndReduce`).\n *\n * NOT part of the public API. Used by:\n *   - `groupAndReduce` for the dedup Map's key\n *   - `materialized-views/query-hash` for UNION MV cross-arm row-key dedup (PR 2)\n *\n * Pure: same input → same output, no side effects.\n */\nexport function canonicalGroupKey(\n  fields: readonly string[],\n  row: Record<string, unknown>,\n): string {\n  const sorted = [...fields].sort()\n  const parts: string[] = []\n  for (const name of sorted) {\n    const v = row[name]\n    const serialised =\n      v === undefined ? 'undefined' : JSON.stringify(v)\n    parts.push(`${name}=${serialised}`)\n  }\n  return parts.join('|')\n}\n","/**\n * Query DSL `.groupBy()` —.\n *\n * Chains after `.where()` / `.filter()` / `.or()` / `.and()` on a\n * Query and before a reducer spec, so consumers can compute\n * per-bucket aggregates without folding in userland:\n *\n * ```ts\n * const byClient = invoices.query()\n *   .where('status', '==', 'open')\n *   .groupBy('clientId')\n *   .aggregate({ total: sum('amount'), n: count() })\n *   .run()\n * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]\n * ```\n *\n * Execution pipeline:\n *\n *   1. Run the query's where/filter clauses (same candidate /\n *      filter pipeline as `.aggregate()` directly on Query).\n *   2. Partition the matching records into buckets keyed by\n *      `readPath(record, field)`. JS `Map` preserves insertion\n *      order, so the first-seen key for a bucket determines its\n *      position in the result array — consumers who want a\n *      specific ordering should `.sort()` downstream.\n *   3. Enforce cardinality: warn once per field at 10% of the cap\n *      (10_000 buckets), throw `GroupCardinalityError` at 100% of\n *      the cap (100_000 buckets).\n *   4. For each bucket, build a per-group reducer state and\n *      step every record in the bucket through it.\n *   5. Emit one result row per bucket, shaped as\n *      `{ [field]: key, ...reduced }`.\n *\n * **Null / undefined keys:** `Map` distinguishes `null` from\n * `undefined`, so records with a missing group field get their own\n * bucket, and records with an explicit `null` value get a separate\n * bucket from that. Consumers who want them merged can coalesce\n * upstream with `.filter()`.\n *\n * **Live mode:** `.groupBy().aggregate().live()` re-runs the full\n * grouping pipeline on every source change. Per-bucket incremental\n * delta maintenance is a future optimization — the reducer\n * protocol's `remove()` hook admits it, but ships naive\n * re-grouping for simplicity.\n *\n * **Type-level stable-key narrowing:** when\n * `dictKey` lands, `groupBy<DictField>()` will narrow the group key\n * type to the stable dictionary key rather than the resolved locale\n * label. That prevents grouping by the locale-resolved label,\n * which would produce different buckets per reader. types the\n * key as `unknown` at the result shape; the dictKey narrowing\n * layers on top without an API break.\n *\n * Partition-awareness seam: when partitioned collections land,\n * per-partition grouping will need to merge sub-results across\n * partitions. The reducer protocol's `{ seed }` parameter\n * (already plumbed through in `reducers.ts`) is the mechanism —\n * groupBy doesn't need its own seam for the moment, because it\n * delegates to the reducer protocol for all per-bucket state.\n */\n\nimport { readPath } from '../query/predicate.js'\nimport type {\n  AggregateSpec,\n  AggregateResult,\n  AggregationUpstream,\n  LiveAggregation,\n} from './aggregation.js'\nimport { buildLiveAggregation } from './aggregation.js'\nimport { canonicalGroupKey } from './canonical-key.js'\nimport { GroupCardinalityError } from '../errors.js'\n\n/**\n * Cardinality thresholds for `.groupBy()`. The warn threshold gives\n * consumers a heads-up before the hard error; the cap is a fixed\n * constant in (not overridable). A `{ maxGroups }` override\n * can be added later without a break if a real consumer asks.\n */\nexport const GROUPBY_WARN_CARDINALITY = 10_000\nexport const GROUPBY_MAX_CARDINALITY = 100_000\n\n/**\n * One-shot warning dedup per-field-set — reactive dashboards\n * re-executing the same grouped query should produce the warning\n * once, not once per re-fire. Keyed on the sorted JSON of grouping\n * field names so `.groupBy('a', 'b')` and `.groupBy('b', 'a')`\n * share the same dedup slot (their result tuples are isomorphic).\n */\nconst warnedCardinalityFields = new Set<string>()\nfunction warnCardinalityApproaching(\n  fields: readonly string[],\n  observed: number,\n): void {\n  const key = JSON.stringify([...fields].sort())\n  if (warnedCardinalityFields.has(key)) return\n  warnedCardinalityFields.add(key)\n  const label = `[${fields.join(', ')}]`\n  console.warn(\n    `[noy-db] .groupBy(${label}) produced ${observed} distinct groups, ` +\n      `${Math.round((observed / GROUPBY_MAX_CARDINALITY) * 100)}% of the ` +\n      `${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with ` +\n      `.where() before grouping, or switch to a lower-cardinality field.`,\n  )\n}\n\n/**\n * Test-only: clear the per-field cardinality warning dedup between\n * tests. Production code never calls this — matching the\n * `resetJoinWarnings` pattern in `join.ts`.\n */\nexport function resetGroupByWarnings(): void {\n  warnedCardinalityFields.clear()\n}\n\n/**\n * Result row shape for a grouped aggregation. Each row carries the\n * group key value under the grouping field name plus every reducer\n * output from the spec.\n *\n * types the group key as `unknown` at the result shape — the\n * runtime read via `readPath` can return any value, and narrowing\n * to a specific type would require the caller to assert at the\n * call site. `dictKey` narrowing layers on top of this by\n * adding an overload that constrains `F` when the grouping field\n * is a `dictKey`.\n */\nexport type GroupedRow<F extends string, R> = { [K in F]: unknown } & R\n\n/**\n * Multi-key variant — result-row shape for variadic\n * `.groupBy(...fields)`. Every grouped field name appears on the row\n * (typed as `unknown` for the same reason as `GroupedRow`), plus the\n * reducer outputs from the spec.\n */\nexport type GroupedRowN<F extends readonly string[], R> =\n  { [K in F[number]]: unknown } & R\n\n/**\n * Shared base class for the chainable grouped-query wrappers. Holds\n * the constructor + protected fields that both single-key\n * `GroupedQuery<T, F>` and variadic `GroupedQueryN<T, F>` need; each\n * subclass only overrides `aggregate()` with its own result-row\n * generic.\n *\n * Not exported — implementation detail. Adding `.having()` /\n * `.live()` / `.orderByGroup()` etc. in the future lands here once\n * and both subclasses pick it up automatically.\n *\n * @internal\n */\nabstract class GroupedQueryBase {\n  /**\n   * Field set this grouped query buckets on. Stored in declaration\n   * order — the same order is preserved on every result row by\n   * `groupAndReduce`. For the single-field constructor, this is\n   * `[field]`.\n   */\n  protected readonly fields: readonly string[]\n\n  constructor(\n    protected readonly executeRecords: () => readonly unknown[],\n    fieldOrFields: string | readonly string[],\n    protected readonly upstreams: readonly AggregationUpstream[],\n    /**\n     * Optional dict label resolver attached by the query builder when\n     * the grouping field is a dictKey. Variadic groupings always pass\n     * `undefined` — `<field>Label` projection has no meaningful shape\n     * for composite keys.\n     */\n    protected readonly dictLabelResolver?: (\n      key: string,\n      locale: string,\n      fallback?: string | readonly string[],\n    ) => Promise<string | undefined>,\n  ) {\n    this.fields =\n      typeof fieldOrFields === 'string' ? [fieldOrFields] : [...fieldOrFields]\n  }\n}\n\n/**\n * Chainable wrapper returned by `Query.groupBy(field)`. Terminates\n * with `.aggregate(spec)` which returns a `GroupedAggregation`.\n *\n * Kept minimal — the only operation on a grouped query is\n * aggregation. Ordering, limiting, and further filtering belong on\n * the underlying `Query` before `.groupBy()` is called; applying\n * them post-group would be a different operation (`having` /\n * `groupOrderBy`), out of scope for.\n */\nexport class GroupedQuery<T, F extends string> extends GroupedQueryBase {\n  /**\n   * Build a grouped aggregation. Returns a `GroupedAggregation`\n   * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape\n   * as the non-grouped `.aggregate()` wrapper, just with an array\n   * result (one row per bucket) instead of a single reduced object.\n   */\n  aggregate<Spec extends AggregateSpec>(\n    spec: Spec,\n  ): GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>> {\n    // T is phantom on the wrapper so consumers can still see the\n    // source row type on hover. Reference it to keep lint quiet.\n    void undefined as T | undefined\n    return new GroupedAggregation<GroupedRow<F, AggregateResult<Spec>>>(\n      this.executeRecords,\n      this.fields,\n      spec,\n      this.upstreams,\n      this.dictLabelResolver,\n    )\n  }\n}\n\n/**\n * Variadic-keyed sibling of `GroupedQuery<T, F>`. Constructed by the\n * multi-arg `Query.groupBy(...fields)` overload. The runtime shape is\n * identical — only the type-level result-row narrowing differs.\n */\nexport class GroupedQueryN<T, F extends readonly string[]> extends GroupedQueryBase {\n  aggregate<Spec extends AggregateSpec>(\n    spec: Spec,\n  ): GroupedAggregation<GroupedRowN<F, AggregateResult<Spec>>> {\n    void undefined as T | undefined\n    return new GroupedAggregation<GroupedRowN<F, AggregateResult<Spec>>>(\n      this.executeRecords,\n      this.fields,\n      spec,\n      this.upstreams,\n      this.dictLabelResolver,\n    )\n  }\n}\n\n/**\n * Execute the group-and-reduce pipeline. Pure function over a\n * record array and a spec — shared by `GroupedAggregation.run()`\n * and the live-mode refresh path. Exported for tests and for any\n * future `scan().groupBy().aggregate()` reuse.\n *\n * Enforces the cardinality cap incrementally during the partition\n * loop, so a runaway grouping throws at the moment the 100_001st\n * bucket would be created — the consumer doesn't have to wait for\n * the full partition to materialize before the error fires.\n */\nexport function groupAndReduce<R>(\n  records: readonly unknown[],\n  fieldOrFields: string | readonly string[],\n  spec: AggregateSpec,\n): R[] {\n  const fields: readonly string[] =\n    typeof fieldOrFields === 'string' ? [fieldOrFields] : fieldOrFields\n  if (fields.length === 0) {\n    throw new Error('.groupBy() requires at least one field')\n  }\n\n  // Bucket value is { keyValues, records } so the output row can stamp\n  // every grouped field in DECLARATION ORDER. Map preserves insertion\n  // order natively (ES2015), so first-seen keys determine ordering.\n  interface Bucket {\n    keyValues: Record<string, unknown>\n    records: unknown[]\n  }\n  const buckets = new Map<string, Bucket>()\n  // Field-label string for error messages — matches the variadic\n  // surface (`[a, b]` for multi-key, `\"k\"` for single-key back-compat).\n  const fieldLabel = fields.length === 1 ? fields[0]! : `[${fields.join(', ')}]`\n\n  for (const record of records) {\n    // Read each field's value into a row object, then canonicalise.\n    const keyValues: Record<string, unknown> = {}\n    for (const f of fields) {\n      keyValues[f] = readPath(record, f)\n    }\n    const dedupKey = canonicalGroupKey(fields, keyValues)\n    let bucket = buckets.get(dedupKey)\n    if (bucket === undefined) {\n      if (buckets.size >= GROUPBY_MAX_CARDINALITY) {\n        throw new GroupCardinalityError(\n          fieldLabel,\n          buckets.size + 1,\n          GROUPBY_MAX_CARDINALITY,\n        )\n      }\n      bucket = { keyValues, records: [] }\n      buckets.set(dedupKey, bucket)\n    }\n    bucket.records.push(record)\n  }\n\n  if (buckets.size >= GROUPBY_WARN_CARDINALITY) {\n    warnCardinalityApproaching(fields, buckets.size)\n  }\n\n  // Reduce each bucket through the spec. Same init/step/finalize\n  // pipeline as `reduceRecords` in aggregate.ts, but one state per\n  // bucket. Inlining the loop here keeps the per-bucket path tight\n  // — calling `reduceRecords` per bucket would recompute\n  // `Object.keys(spec)` once per bucket unnecessarily.\n  const reducerKeys = Object.keys(spec)\n  const out: R[] = []\n  for (const bucket of buckets.values()) {\n    const state: Record<string, unknown> = {}\n    for (const rk of reducerKeys) {\n      state[rk] = spec[rk]!.init()\n    }\n    for (const record of bucket.records) {\n      for (const rk of reducerKeys) {\n        state[rk] = spec[rk]!.step(state[rk], record)\n      }\n    }\n    // Stamp grouped fields FIRST, in declaration order — this is\n    // tested via `Object.keys(row).slice(0, fields.length)`.\n    const row: Record<string, unknown> = {}\n    for (const f of fields) {\n      row[f] = bucket.keyValues[f]\n    }\n    for (const rk of reducerKeys) {\n      row[rk] = spec[rk]!.finalize(state[rk])\n    }\n    out.push(row as unknown as R)\n  }\n  return out\n}\n\n/**\n * Grouped aggregation wrapper — the `.groupBy(field).aggregate(spec)`\n * terminal. Shape mirrors `Aggregation<R>` from aggregate.ts: two\n * terminals (`.run()` and `.live()`), spec bound at construction\n * time, upstreams collected for live mode.\n *\n * The generic `R` is the per-row result shape (i.e. a single\n * grouped row), and the terminals return `R[]` — one row per\n * bucket.\n */\nexport class GroupedAggregation<R> {\n  private readonly fields: readonly string[]\n\n  constructor(\n    private readonly executeRecords: () => readonly unknown[],\n    fields: string | readonly string[],\n    private readonly spec: AggregateSpec,\n    private readonly upstreams: readonly AggregationUpstream[],\n    /**\n     * Optional dict label resolver for `<field>Label` projection\n     *. Present when the grouping field is a dictKey.\n     */\n    private readonly dictLabelResolver?: (\n      key: string,\n      locale: string,\n      fallback?: string | readonly string[],\n    ) => Promise<string | undefined>,\n  ) {\n    this.fields = typeof fields === 'string' ? [fields] : [...fields]\n  }\n\n  /** Execute the query, group, reduce, and return an array of rows. */\n  run(): R[] {\n    return groupAndReduce<R>(this.executeRecords(), this.fields, this.spec)\n  }\n\n  /**\n   * Execute the query, group, reduce, and resolve `<field>Label` for\n   * each result row when the grouping field is a `dictKey` and a\n   * `locale` is provided. Returns `R[]` synchronously when\n   * no locale is specified (identical to `.run()`).\n   *\n   * The `<field>Label` field is appended to each row. Rows whose group\n   * key has no dictionary entry get `<field>Label: undefined`.\n   *\n   * Dict-label resolution is single-field only — multi-key groupings\n   * do not produce a `<field>Label`. The resolver is only attached\n   * by the builder when `fields.length === 1`.\n   */\n  async runAsync(opts?: {\n    locale?: string\n    fallback?: string | readonly string[]\n  }): Promise<R[]> {\n    const rows = groupAndReduce<R>(this.executeRecords(), this.fields, this.spec)\n    if (!opts?.locale || !this.dictLabelResolver || this.fields.length !== 1) return rows\n\n    const resolve = this.dictLabelResolver\n    const locale = opts.locale\n    const fallback = opts.fallback\n    const field = this.fields[0]!\n    const labelKey = `${field}Label`\n\n    return Promise.all(\n      rows.map(async (row) => {\n        const key = (row as Record<string, unknown>)[field]\n        if (typeof key !== 'string') return row\n        const label = await resolve(key, locale, fallback)\n        return { ...(row as Record<string, unknown>), [labelKey]: label } as unknown as R\n      }),\n    )\n  }\n\n  /**\n   * Build a reactive `LiveAggregation<R[]>` that re-runs the full\n   * group-and-reduce pipeline whenever any upstream source notifies\n   * of a change. Same error-isolation and idempotent-stop contract\n   * as `Aggregation.live()` — the implementation delegates to the\n   * same `LiveAggregationImpl` class by threading a fresh\n   * recompute closure through the existing constructor.\n   *\n   * uses naive full re-run on every change. Incremental\n   * per-bucket maintenance (apply `step` on inserted records,\n   * `remove` on deleted records, route by bucket key) is a future\n   * optimization — the reducer protocol admits it, but wiring\n   * delta-aware source subscriptions is a separate PR.\n   *\n   * Always call `live.stop()` when finished.\n   */\n  live(): LiveAggregation<R[]> {\n    const recompute = (): R[] =>\n      groupAndReduce<R>(this.executeRecords(), this.fields, this.spec)\n    return buildLiveAggregation<R[]>(recompute, this.upstreams)\n  }\n}\n"],"mappings":";;;;;;;;AAoEO,SAAS,cACd,SACA,MACuB;AAEvB,QAAM,QAAiC,CAAC;AACxC,aAAW,OAAO,OAAO,KAAK,IAAI,GAAG;AACnC,UAAM,GAAG,IAAI,KAAK,GAAG,EAAG,KAAK;AAAA,EAC/B;AACA,aAAW,UAAU,SAAS;AAC5B,eAAW,OAAO,OAAO,KAAK,IAAI,GAAG;AACnC,YAAM,GAAG,IAAI,KAAK,GAAG,EAAG,KAAK,MAAM,GAAG,GAAG,MAAM;AAAA,IACjD;AAAA,EACF;AACA,QAAM,SAAkC,CAAC;AACzC,aAAW,OAAO,OAAO,KAAK,IAAI,GAAG;AACnC,WAAO,GAAG,IAAI,KAAK,GAAG,EAAG,SAAS,MAAM,GAAG,CAAC;AAAA,EAC9C;AACA,SAAO;AACT;AA4DA,IAAM,sBAAN,MAA2D;AAAA,EAOzD,YACmB,WACjB,WACA;AAFiB;AASjB,QAAI;AACF,WAAK,QAAQ,UAAU;AACvB,WAAK,QAAQ;AAAA,IACf,SAAS,KAAK;AACZ,WAAK,QAAQ;AACb,WAAK,QAAQ;AAAA,IACf;AAIA,eAAW,YAAY,WAAW;AAChC,YAAM,QAAQ,SAAS,UAAU,MAAM,KAAK,QAAQ,CAAC;AACrD,WAAK,aAAa,KAAK,KAAK;AAAA,IAC9B;AAAA,EACF;AAAA,EAvBmB;AAAA,EAPZ;AAAA,EACA;AAAA,EACU,YAAY,oBAAI,IAAgB;AAAA,EAChC,eAAkC,CAAC;AAAA,EAC5C,UAAU;AAAA,EA4BV,UAAgB;AACtB,QAAI,KAAK,QAAS;AAClB,QAAI;AACF,WAAK,QAAQ,KAAK,UAAU;AAC5B,WAAK,QAAQ;AAAA,IACf,SAAS,KAAK;AAIZ,WAAK,QAAQ;AAAA,IACf;AACA,eAAW,YAAY,KAAK,WAAW;AACrC,UAAI;AACF,iBAAS;AAAA,MACX,SAAS,KAAK;AAGZ,gBAAQ,KAAK,4CAA4C,GAAG;AAAA,MAC9D;AAAA,IACF;AAAA,EACF;AAAA,EAEA,UAAU,IAA4B;AACpC,QAAI,KAAK,SAAS;AAGhB,aAAO,MAAM;AAAA,MAAC;AAAA,IAChB;AACA,SAAK,UAAU,IAAI,EAAE;AACrB,WAAO,MAAM;AACX,WAAK,UAAU,OAAO,EAAE;AAAA,IAC1B;AAAA,EACF;AAAA,EAEA,OAAa;AACX,QAAI,KAAK,QAAS;AAClB,SAAK,UAAU;AACf,eAAW,SAAS,KAAK,cAAc;AACrC,UAAI;AACF,cAAM;AAAA,MACR,SAAS,KAAK;AACZ,gBAAQ,KAAK,wDAAwD,GAAG;AAAA,MAC1E;AAAA,IACF;AACA,SAAK,aAAa,SAAS;AAC3B,SAAK,UAAU,MAAM;AAAA,EACvB;AACF;AAkBO,IAAM,cAAN,MAAqB;AAAA,EAC1B,YACmB,gBACA,MACA,WACjB;AAHiB;AACA;AACA;AAAA,EAChB;AAAA,EAHgB;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASnB,MAAS;AACP,WAAO,cAAc,KAAK,eAAe,GAAG,KAAK,IAAI;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAoBA,OAA2B;AACzB,UAAM,YAAY,MAChB,cAAc,KAAK,eAAe,GAAG,KAAK,IAAI;AAChD,WAAO,IAAI,oBAAuB,WAAW,KAAK,SAAS;AAAA,EAC7D;AACF;AAUO,SAAS,qBACd,WACA,WACoB;AACpB,SAAO,IAAI,oBAAuB,WAAW,SAAS;AACxD;;;AC7RO,SAAS,kBACd,QACA,KACQ;AACR,QAAM,SAAS,CAAC,GAAG,MAAM,EAAE,KAAK;AAChC,QAAM,QAAkB,CAAC;AACzB,aAAW,QAAQ,QAAQ;AACzB,UAAM,IAAI,IAAI,IAAI;AAClB,UAAM,aACJ,MAAM,SAAY,cAAc,KAAK,UAAU,CAAC;AAClD,UAAM,KAAK,GAAG,IAAI,IAAI,UAAU,EAAE;AAAA,EACpC;AACA,SAAO,MAAM,KAAK,GAAG;AACvB;;;ACkDO,IAAM,2BAA2B;AACjC,IAAM,0BAA0B;AASvC,IAAM,0BAA0B,oBAAI,IAAY;AAChD,SAAS,2BACP,QACA,UACM;AACN,QAAM,MAAM,KAAK,UAAU,CAAC,GAAG,MAAM,EAAE,KAAK,CAAC;AAC7C,MAAI,wBAAwB,IAAI,GAAG,EAAG;AACtC,0BAAwB,IAAI,GAAG;AAC/B,QAAM,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC;AACnC,UAAQ;AAAA,IACN,qBAAqB,KAAK,cAAc,QAAQ,qBAC3C,KAAK,MAAO,WAAW,0BAA2B,GAAG,CAAC,YACtD,uBAAuB;AAAA,EAE9B;AACF;AAOO,SAAS,uBAA6B;AAC3C,0BAAwB,MAAM;AAChC;AAsCA,IAAe,mBAAf,MAAgC;AAAA,EAS9B,YACqB,gBACnB,eACmB,WAOA,mBAKnB;AAdmB;AAEA;AAOA;AAMnB,SAAK,SACH,OAAO,kBAAkB,WAAW,CAAC,aAAa,IAAI,CAAC,GAAG,aAAa;AAAA,EAC3E;AAAA,EAjBqB;AAAA,EAEA;AAAA,EAOA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAZF;AAqBrB;AAYO,IAAM,eAAN,cAAgD,iBAAiB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOtE,UACE,MAC0D;AAI1D,WAAO,IAAI;AAAA,MACT,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,MACA,KAAK;AAAA,MACL,KAAK;AAAA,IACP;AAAA,EACF;AACF;AAOO,IAAM,gBAAN,cAA4D,iBAAiB;AAAA,EAClF,UACE,MAC2D;AAE3D,WAAO,IAAI;AAAA,MACT,KAAK;AAAA,MACL,KAAK;AAAA,MACL;AAAA,MACA,KAAK;AAAA,MACL,KAAK;AAAA,IACP;AAAA,EACF;AACF;AAaO,SAAS,eACd,SACA,eACA,MACK;AACL,QAAM,SACJ,OAAO,kBAAkB,WAAW,CAAC,aAAa,IAAI;AACxD,MAAI,OAAO,WAAW,GAAG;AACvB,UAAM,IAAI,MAAM,wCAAwC;AAAA,EAC1D;AASA,QAAM,UAAU,oBAAI,IAAoB;AAGxC,QAAM,aAAa,OAAO,WAAW,IAAI,OAAO,CAAC,IAAK,IAAI,OAAO,KAAK,IAAI,CAAC;AAE3E,aAAW,UAAU,SAAS;AAE5B,UAAM,YAAqC,CAAC;AAC5C,eAAW,KAAK,QAAQ;AACtB,gBAAU,CAAC,IAAI,SAAS,QAAQ,CAAC;AAAA,IACnC;AACA,UAAM,WAAW,kBAAkB,QAAQ,SAAS;AACpD,QAAI,SAAS,QAAQ,IAAI,QAAQ;AACjC,QAAI,WAAW,QAAW;AACxB,UAAI,QAAQ,QAAQ,yBAAyB;AAC3C,cAAM,IAAI;AAAA,UACR;AAAA,UACA,QAAQ,OAAO;AAAA,UACf;AAAA,QACF;AAAA,MACF;AACA,eAAS,EAAE,WAAW,SAAS,CAAC,EAAE;AAClC,cAAQ,IAAI,UAAU,MAAM;AAAA,IAC9B;AACA,WAAO,QAAQ,KAAK,MAAM;AAAA,EAC5B;AAEA,MAAI,QAAQ,QAAQ,0BAA0B;AAC5C,+BAA2B,QAAQ,QAAQ,IAAI;AAAA,EACjD;AAOA,QAAM,cAAc,OAAO,KAAK,IAAI;AACpC,QAAM,MAAW,CAAC;AAClB,aAAW,UAAU,QAAQ,OAAO,GAAG;AACrC,UAAM,QAAiC,CAAC;AACxC,eAAW,MAAM,aAAa;AAC5B,YAAM,EAAE,IAAI,KAAK,EAAE,EAAG,KAAK;AAAA,IAC7B;AACA,eAAW,UAAU,OAAO,SAAS;AACnC,iBAAW,MAAM,aAAa;AAC5B,cAAM,EAAE,IAAI,KAAK,EAAE,EAAG,KAAK,MAAM,EAAE,GAAG,MAAM;AAAA,MAC9C;AAAA,IACF;AAGA,UAAM,MAA+B,CAAC;AACtC,eAAW,KAAK,QAAQ;AACtB,UAAI,CAAC,IAAI,OAAO,UAAU,CAAC;AAAA,IAC7B;AACA,eAAW,MAAM,aAAa;AAC5B,UAAI,EAAE,IAAI,KAAK,EAAE,EAAG,SAAS,MAAM,EAAE,CAAC;AAAA,IACxC;AACA,QAAI,KAAK,GAAmB;AAAA,EAC9B;AACA,SAAO;AACT;AAYO,IAAM,qBAAN,MAA4B;AAAA,EAGjC,YACmB,gBACjB,QACiB,MACA,WAKA,mBAKjB;AAbiB;AAEA;AACA;AAKA;AAMjB,SAAK,SAAS,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI,CAAC,GAAG,MAAM;AAAA,EAClE;AAAA,EAfmB;AAAA,EAEA;AAAA,EACA;AAAA,EAKA;AAAA,EAXF;AAAA;AAAA,EAqBjB,MAAW;AACT,WAAO,eAAkB,KAAK,eAAe,GAAG,KAAK,QAAQ,KAAK,IAAI;AAAA,EACxE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAeA,MAAM,SAAS,MAGE;AACf,UAAM,OAAO,eAAkB,KAAK,eAAe,GAAG,KAAK,QAAQ,KAAK,IAAI;AAC5E,QAAI,CAAC,MAAM,UAAU,CAAC,KAAK,qBAAqB,KAAK,OAAO,WAAW,EAAG,QAAO;AAEjF,UAAM,UAAU,KAAK;AACrB,UAAM,SAAS,KAAK;AACpB,UAAM,WAAW,KAAK;AACtB,UAAM,QAAQ,KAAK,OAAO,CAAC;AAC3B,UAAM,WAAW,GAAG,KAAK;AAEzB,WAAO,QAAQ;AAAA,MACb,KAAK,IAAI,OAAO,QAAQ;AACtB,cAAM,MAAO,IAAgC,KAAK;AAClD,YAAI,OAAO,QAAQ,SAAU,QAAO;AACpC,cAAM,QAAQ,MAAM,QAAQ,KAAK,QAAQ,QAAQ;AACjD,eAAO,EAAE,GAAI,KAAiC,CAAC,QAAQ,GAAG,MAAM;AAAA,MAClE,CAAC;AAAA,IACH;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,OAA6B;AAC3B,UAAM,YAAY,MAChB,eAAkB,KAAK,eAAe,GAAG,KAAK,QAAQ,KAAK,IAAI;AACjE,WAAO,qBAA0B,WAAW,KAAK,SAAS;AAAA,EAC5D;AACF;","names":[]}

package/dist/chunk-LOL725S4.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/blobs/export-blobs.ts","../src/blobs/blob-compaction.ts"],"sourcesContent":["/**\n * `vault.exportBlobs()` — bulk blob extraction primitive.\n *\n * Async-iterable handle over every blob attached to records in a\n * vault, optionally filtered by collection allowlist and per-record\n * predicate. Emits tuples of `{ blobId, recordRef, bytes, meta }` so\n * the consumer can pipe into any sink (zip stream, S3 multipart, USB\n * copy, cold-storage tape) without pulling the whole export into\n * memory.\n *\n * ## Auth + audit\n *\n * - Capability check runs **once** at handle creation via\n *   `Vault.assertCanExport('plaintext', 'blob')`. An operator whose\n *   keyring lacks that bit fails before a single byte of ciphertext\n *   is decrypted.\n * - Audit entry lands in `_export_audit` at handle creation: the\n *   actor, start timestamp, target collections, predicate presence,\n *   and batch mechanism. **No content hashes** — per the spec\n *   non-correlation invariant.\n *\n * ## Abort + resume\n *\n * - `handle.abort()` flips the internal signal; the next iteration\n *   boundary throws `AbortError`. Consumers already in `for await`\n *   can catch and exit cleanly.\n * - Restart after a partial failure with `{ afterBlobId }` — the\n *   iterator skips tuples up to (and including) that blob id before\n *   yielding again. Combined with a blob-count ceiling it supports\n *   idempotent batch re-runs.\n *\n * @module\n */\n\nimport type { Collection } from '../collection.js'\nimport type { SlotInfo } from '../types.js'\n\n// ─── Types ──────────────────────────────────────────────────────────────\n\nexport interface ExportBlobsOptions {\n  /**\n   * Collection allowlist. Omit to export blobs from every collection\n   * the caller has read access to.\n   */\n  readonly collections?: readonly string[]\n  /**\n   * Per-record predicate. Called on the decrypted record BEFORE any\n   * blob bytes are read for that record — returning false skips the\n   * record and all its slots without touching their chunks.\n   */\n  readonly where?: (record: unknown, context: { collection: string; id: string }) => boolean\n  /**\n   * Resume after a specific blob id. The iterator skips tuples up to\n   * and including this id, then yields. Format of the id is the same\n   * as `ExportedBlob.blobId` (the HMAC-keyed eTag).\n   */\n  readonly afterBlobId?: string\n  /**\n   * External abort signal. When fired, the next iterator tick throws\n   * `ExportBlobsAbortedError`. Honored alongside `handle.abort()`.\n   */\n  readonly signal?: AbortSignal\n}\n\nexport interface ExportedBlob {\n  /** Opaque blob identifier — HMAC-keyed eTag, stable across vaults. */\n  readonly blobId: string\n  /** Where this blob came from in the vault. */\n  readonly recordRef: {\n    readonly collection: string\n    readonly id: string\n    readonly slot: string\n  }\n  /** Decrypted plaintext bytes. */\n  readonly bytes: Uint8Array\n  /** Best-effort metadata (from the blob slot record). */\n  readonly meta: {\n    readonly size: number\n    /**\n     * User-visible filename stored on the slot. Often equal to the\n     * slot name; differs when the caller supplied an explicit\n     * `filename` to `BlobSet.put()`.\n     */\n    readonly filename: string\n    readonly mimeType?: string\n    readonly createdAt?: string\n  }\n}\n\nexport interface ExportBlobsHandle extends AsyncIterable<ExportedBlob> {\n  /** Abort the export. Safe to call multiple times. */\n  abort(): void\n  /** True once `abort()` has fired or the external signal aborted. */\n  readonly aborted: boolean\n}\n\nexport class ExportBlobsAbortedError extends Error {\n  constructor(reason: string) {\n    super(`exportBlobs aborted: ${reason}`)\n    this.name = 'ExportBlobsAbortedError'\n  }\n}\n\n// ─── Audit ──────────────────────────────────────────────────────────────\n\nexport const EXPORT_AUDIT_COLLECTION = '_export_audit'\n\nexport interface ExportBlobsAuditEntry {\n  readonly id: string\n  readonly mechanism: 'exportBlobs'\n  readonly actor: string\n  readonly startedAt: string\n  readonly collections: readonly string[] | null\n  readonly predicate: boolean\n  readonly afterBlobId: string | null\n}\n\n// ─── Implementation ─────────────────────────────────────────────────────\n\n/**\n * Build the handle. Factored out of `Vault.exportBlobs` so the\n * implementation can be unit-tested without going through the\n * compartment lifecycle.\n */\nexport function createExportBlobsHandle(\n  actor: string,\n  listAccessibleCollections: () => Promise<string[]>,\n  getCollection: <T>(name: string) => Collection<T>,\n  writeAudit: (entry: ExportBlobsAuditEntry) => Promise<void>,\n  options: ExportBlobsOptions,\n): ExportBlobsHandle {\n  let aborted = false\n\n  const abort = (): void => {\n    aborted = true\n  }\n\n  if (options.signal) {\n    if (options.signal.aborted) aborted = true\n    options.signal.addEventListener('abort', () => { aborted = true })\n  }\n\n  function assertLive(): void {\n    if (aborted) throw new ExportBlobsAbortedError('aborted by caller')\n  }\n\n  const allowlist = options.collections ? new Set(options.collections) : null\n\n  // Write the audit entry BEFORE the first yield so a blocked\n  // iteration still leaves an audit trail that the export started.\n  let auditPromise: Promise<void> | null = null\n  function writeAuditOnce(): Promise<void> {\n    if (!auditPromise) {\n      auditPromise = writeAudit({\n        id: generateBatchId(),\n        mechanism: 'exportBlobs',\n        actor,\n        startedAt: new Date().toISOString(),\n        collections: options.collections ?? null,\n        predicate: Boolean(options.where),\n        afterBlobId: options.afterBlobId ?? null,\n      })\n    }\n    return auditPromise\n  }\n\n  async function* generate(): AsyncGenerator<ExportedBlob> {\n    await writeAuditOnce()\n    assertLive()\n\n    // Resolve target collections lazily — also keeps the call async.\n    const allCollections = await listAccessibleCollections()\n    const targets = allCollections.filter(name => {\n      if (name.startsWith('_')) return false\n      if (allowlist && !allowlist.has(name)) return false\n      return true\n    })\n\n    let resumeCursorHit = options.afterBlobId === undefined\n\n    for (const collectionName of targets) {\n      if (aborted) return\n\n      const coll = getCollection<Record<string, unknown>>(collectionName)\n      const records = await coll.list().catch(() => [])\n      for (const record of records) {\n        if (aborted) return\n        assertLive()\n\n        const idField = (record as { id?: unknown }).id\n        if (typeof idField !== 'string') continue\n\n        if (options.where && !options.where(record, { collection: collectionName, id: idField })) continue\n\n        const blobSet = coll.blob(idField)\n        const slots = await blobSet.list().catch(() => [] as SlotInfo[])\n        for (const slot of slots) {\n          if (aborted) return\n\n          if (!resumeCursorHit) {\n            if (slot.eTag === options.afterBlobId) {\n              resumeCursorHit = true\n            }\n            continue\n          }\n\n          const bytes = await blobSet.get(slot.name)\n          if (!bytes) continue\n\n          const item: ExportedBlob = {\n            blobId: slot.eTag,\n            recordRef: { collection: collectionName, id: idField, slot: slot.name },\n            bytes,\n            meta: {\n              size: slot.size,\n              filename: slot.filename,\n              ...(slot.mimeType !== undefined && { mimeType: slot.mimeType }),\n              ...(slot.uploadedAt !== undefined && { createdAt: slot.uploadedAt }),\n            },\n          }\n          yield item\n        }\n      }\n    }\n  }\n\n  const handle: ExportBlobsHandle = {\n    abort,\n    get aborted() { return aborted },\n    [Symbol.asyncIterator]: () => generate(),\n  }\n  return handle\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────\n\nfunction generateBatchId(): string {\n  // 16 bytes of crypto randomness, URL-safe base64, no padding.\n  const raw = globalThis.crypto.getRandomValues(new Uint8Array(16))\n  let s = ''\n  for (const b of raw) s += b.toString(16).padStart(2, '0')\n  return `batch-${Date.now().toString(36)}-${s.slice(0, 12)}`\n}\n","/**\n * Blob retention + compaction.\n *\n * Declarative per-collection / per-slot eviction policy. Two\n * triggers:\n *\n *   - **`retainDays`** — age-based TTL. A slot uploaded more than N\n *     days ago is evicted.\n *   - **`evictWhen(record)`** — predicate over the **decrypted**\n *     record. Lets consumers express \"the image is safe to drop once\n *     the structured invoice has been reviewed and confirmed.\"\n *\n * Either trigger (or both) causes the slot to evict. Eviction removes\n * the slot entry from `_blob_slots_{collection}`, decrements the\n * blob's refCount (so unreferenced chunks can be GC'd by the next\n * sweep), and writes one entry to the `_blob_eviction_audit`\n * collection for tamper-evident record-keeping.\n *\n * The audit entry carries the eTag of the evicted blob (opaque HMAC\n * of plaintext under the vault's `_blob` DEK) — no plaintext leakage,\n * per the SPEC non-correlation invariant. Consumers reconstructing\n * \"what used to be attached\" can look up the audit entry by record\n * id.\n *\n * Compaction is **consumer-scheduled** — noy-db never runs a\n * background daemon. Call `vault.compact()` whenever your workflow\n * allows (cron, manual \"tidy\" button, cold-storage export prep, …).\n *\n * @module\n */\n\nimport type { NoydbStore, EncryptedEnvelope, SlotInfo } from '../types.js'\nimport { NOYDB_FORMAT_VERSION } from '../types.js'\nimport { encrypt } from '../crypto.js'\n\n// ─── Config types ───────────────────────────────────────────────────────\n\nexport interface BlobFieldPolicy<T = unknown> {\n  /**\n   * Age-based TTL in days. A slot whose `uploadedAt` is older than\n   * `now - retainDays × 86400s` evicts on the next `vault.compact()`.\n   * Omit to disable age-based eviction.\n   */\n  readonly retainDays?: number\n  /**\n   * Predicate evaluated against the decrypted record. When it returns\n   * `true`, every matching slot on that record evicts. Omit to\n   * disable predicate-based eviction.\n   */\n  readonly evictWhen?: (record: T) => boolean\n}\n\nexport type BlobFieldsConfig<T = unknown> = Record<string, BlobFieldPolicy<T>>\n\n// ─── Audit collection ──────────────────────────────────────────────────\n\nexport const BLOB_EVICTION_AUDIT_COLLECTION = '_blob_eviction_audit'\n\nexport interface BlobEvictionEntry {\n  readonly id: string\n  readonly collection: string\n  readonly recordId: string\n  readonly slotName: string\n  readonly blobHash: string\n  readonly reason: 'ttl' | 'predicate' | 'both'\n  readonly evictedAt: string\n  readonly actor: string\n}\n\n// ─── Compaction result ──────────────────────────────────────────────────\n\nexport interface CompactionResult {\n  /** Number of blob slots evicted across all collections. */\n  readonly evicted: number\n  /** Number of records touched (iterated + policy checked). */\n  readonly records: number\n  /** Number of collections with `blobFields` configured. */\n  readonly collections: number\n  /** Number of audit entries written. Equal to `evicted`. */\n  readonly auditEntries: number\n  /** Per-collection breakdown for diagnostics. */\n  readonly byCollection: Record<string, { records: number; evicted: number }>\n}\n\n// ─── Core ──────────────────────────────────────────────────────────────\n\nexport interface CompactRunOptions {\n  /** Override \"now\" for deterministic testing. */\n  readonly now?: Date\n  /**\n   * Stop after this many evictions. Useful for capped batches / cron\n   * jobs that need to fit in a time window. `undefined` = unbounded.\n   */\n  readonly maxEvictions?: number\n  /**\n   * Dry-run — evaluate policies and return the counts, but do NOT\n   * delete slots or write audit entries. Lets a consumer preview\n   * what would happen.\n   */\n  readonly dryRun?: boolean\n}\n\nexport interface CompactionContext {\n  readonly adapter: NoydbStore\n  readonly vault: string\n  readonly actor: string\n  readonly encrypted: boolean\n  readonly getDEK: (collection: string) => Promise<CryptoKey>\n  /**\n   * Resolve a collection's declared `blobFields` config. Returns an\n   * empty map for collections without the config — the walk skips\n   * those.\n   */\n  readonly getBlobFields: <T>(collection: string) => BlobFieldsConfig<T> | null\n  /** List collection names in the vault. */\n  readonly listCollections: () => Promise<string[]>\n  /** List record ids in a collection. */\n  readonly listRecords: (collection: string) => Promise<string[]>\n  /** Decrypt and return the record. Null when absent. */\n  readonly getRecord: <T>(collection: string, id: string) => Promise<T | null>\n  /** Return the BlobSet-like handle for a record's slots. */\n  readonly listSlots: (collection: string, id: string) => Promise<SlotInfo[]>\n  /** Delete a slot and decrement its blob's refCount. */\n  readonly deleteSlot: (collection: string, id: string, slotName: string) => Promise<void>\n}\n\nexport async function runCompaction(\n  ctx: CompactionContext,\n  options: CompactRunOptions = {},\n): Promise<CompactionResult> {\n  const now = options.now ?? new Date()\n  const maxEvictions = options.maxEvictions ?? Infinity\n  const dryRun = options.dryRun === true\n\n  const allCollections = await ctx.listCollections()\n  const byCollection: Record<string, { records: number; evicted: number }> = {}\n  let evicted = 0\n  let records = 0\n  let auditEntries = 0\n  let collectionsWithPolicy = 0\n\n  outer: for (const collectionName of allCollections) {\n    if (collectionName.startsWith('_')) continue\n    const config = ctx.getBlobFields(collectionName)\n    if (!config) continue\n    const configuredSlots = Object.keys(config)\n    if (configuredSlots.length === 0) continue\n    collectionsWithPolicy += 1\n    byCollection[collectionName] = { records: 0, evicted: 0 }\n\n    const ids = await ctx.listRecords(collectionName)\n    for (const recordId of ids) {\n      if (evicted >= maxEvictions) break outer\n\n      const record = await ctx.getRecord(collectionName, recordId).catch(() => null)\n      if (record === null) continue\n      records += 1\n      byCollection[collectionName].records += 1\n\n      const slots = await ctx.listSlots(collectionName, recordId).catch(() => [])\n      for (const slot of slots) {\n        if (evicted >= maxEvictions) break outer\n        const policy = config[slot.name]\n        if (!policy) continue\n\n        const reason = evaluatePolicy(policy, record, slot, now)\n        if (!reason) continue\n\n        if (!dryRun) {\n          await ctx.deleteSlot(collectionName, recordId, slot.name)\n          await writeAuditEntry(ctx, {\n            id: generateEvictionId(collectionName, recordId, slot.name),\n            collection: collectionName,\n            recordId,\n            slotName: slot.name,\n            blobHash: slot.eTag,\n            reason,\n            evictedAt: now.toISOString(),\n            actor: ctx.actor,\n          })\n          auditEntries += 1\n        }\n        evicted += 1\n        byCollection[collectionName].evicted += 1\n      }\n    }\n  }\n\n  return {\n    evicted,\n    records,\n    collections: collectionsWithPolicy,\n    auditEntries,\n    byCollection,\n  }\n}\n\nfunction evaluatePolicy<T>(\n  policy: BlobFieldPolicy<T>,\n  record: T,\n  slot: SlotInfo,\n  now: Date,\n): 'ttl' | 'predicate' | 'both' | null {\n  let ttlTriggered = false\n  let predicateTriggered = false\n\n  if (policy.retainDays !== undefined && policy.retainDays > 0) {\n    const uploadedAt = Date.parse(slot.uploadedAt)\n    if (Number.isFinite(uploadedAt)) {\n      const ageMs = now.getTime() - uploadedAt\n      const limitMs = policy.retainDays * 86_400_000\n      if (ageMs > limitMs) ttlTriggered = true\n    }\n  }\n\n  if (policy.evictWhen) {\n    try {\n      if (policy.evictWhen(record)) predicateTriggered = true\n    } catch {\n      // Predicate error → do NOT evict. Fail closed.\n    }\n  }\n\n  if (ttlTriggered && predicateTriggered) return 'both'\n  if (ttlTriggered) return 'ttl'\n  if (predicateTriggered) return 'predicate'\n  return null\n}\n\nfunction generateEvictionId(collection: string, recordId: string, slotName: string): string {\n  const rand = globalThis.crypto.getRandomValues(new Uint8Array(8))\n  let suffix = ''\n  for (const b of rand) suffix += b.toString(16).padStart(2, '0')\n  return `${collection}__${recordId}__${slotName}__${suffix}`\n}\n\nasync function writeAuditEntry(ctx: CompactionContext, entry: BlobEvictionEntry): Promise<void> {\n  const json = JSON.stringify(entry)\n  let envelope: EncryptedEnvelope\n  if (ctx.encrypted) {\n    const dek = await ctx.getDEK(BLOB_EVICTION_AUDIT_COLLECTION)\n    const { iv, data } = await encrypt(json, dek)\n    envelope = {\n      _noydb: NOYDB_FORMAT_VERSION,\n      _v: 1,\n      _ts: entry.evictedAt,\n      _iv: iv,\n      _data: data,\n      _by: entry.actor,\n    }\n  } else {\n    envelope = {\n      _noydb: NOYDB_FORMAT_VERSION,\n      _v: 1,\n      _ts: entry.evictedAt,\n      _iv: '',\n      _data: json,\n      _by: entry.actor,\n    }\n  }\n  await ctx.adapter.put(ctx.vault, BLOB_EVICTION_AUDIT_COLLECTION, entry.id, envelope)\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-MRIBLZL3.js

@@ -1,86 +0,0 @@
-// src/query/predicate.ts
-function readPath(record, path) {
-  if (record === null || record === void 0) return void 0;
-  if (!path.includes(".")) {
-    return record[path];
-  }
-  const segments = path.split(".");
-  let cursor = record;
-  for (const segment of segments) {
-    if (cursor === null || cursor === void 0) return void 0;
-    cursor = cursor[segment];
-  }
-  return cursor;
-}
-function evaluateFieldClause(record, clause) {
-  const actual = readPath(record, clause.field);
-  const { op, value } = clause;
-  switch (op) {
-    case "==":
-      return actual === value;
-    case "!=":
-      return actual !== value;
-    case "<":
-      return isComparable(actual, value) && actual < value;
-    case "<=":
-      return isComparable(actual, value) && actual <= value;
-    case ">":
-      return isComparable(actual, value) && actual > value;
-    case ">=":
-      return isComparable(actual, value) && actual >= value;
-    case "in":
-      return Array.isArray(value) && value.includes(actual);
-    case "contains":
-      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
-      if (Array.isArray(actual)) return actual.includes(value);
-      return false;
-    case "startsWith":
-      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
-    case "between": {
-      if (!Array.isArray(value) || value.length !== 2) return false;
-      const [lo, hi] = value;
-      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
-      return actual >= lo && actual <= hi;
-    }
-    default: {
-      const _exhaustive = op;
-      void _exhaustive;
-      return false;
-    }
-  }
-}
-function isComparable(a, b) {
-  if (typeof a === "number" && typeof b === "number") return true;
-  if (typeof a === "string" && typeof b === "string") return true;
-  if (a instanceof Date && b instanceof Date) return true;
-  return false;
-}
-function evaluateClause(record, clause) {
-  switch (clause.type) {
-    case "field":
-      return evaluateFieldClause(record, clause);
-    case "filter":
-      return clause.fn(record);
-    case "wherePredicate":
-      return clause.fn(record, clause.ctx);
-    case "group":
-      if (clause.op === "and") {
-        for (const child of clause.clauses) {
-          if (!evaluateClause(record, child)) return false;
-        }
-        return true;
-      } else {
-        for (const child of clause.clauses) {
-          if (evaluateClause(record, child)) return true;
-        }
-        return false;
-      }
-  }
-}
-
-export {
-  readPath,
-  evaluateFieldClause,
-  evaluateClause
-};
-//# sourceMappingURL=chunk-MRIBLZL3.js.map

package/dist/chunk-MRIBLZL3.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/query/predicate.ts"],"sourcesContent":["/**\n * Operator implementations for the query DSL.\n *\n * All predicates run client-side, AFTER decryption — they never see ciphertext.\n * This file is dependency-free and tree-shakeable.\n */\n\n/** Comparison operators supported by the where() builder. */\nexport type Operator =\n  | '=='\n  | '!='\n  | '<'\n  | '<='\n  | '>'\n  | '>='\n  | 'in'\n  | 'contains'\n  | 'startsWith'\n  | 'between'\n\n/**\n * A single field comparison clause inside a query plan.\n * Plans are JSON-serializable, so this type uses primitives only.\n */\nexport interface FieldClause {\n  readonly type: 'field'\n  readonly field: string\n  readonly op: Operator\n  readonly value: unknown\n}\n\n/**\n * A user-supplied predicate function escape hatch. Not serializable.\n *\n * The predicate accepts `unknown` at the type level so the surrounding\n * Clause type can stay non-parametric — this keeps Collection<T> covariant\n * in T at the public API surface. Builder methods cast user predicates\n * (typed `(record: T) => boolean`) into this shape on the way in.\n */\nexport interface FilterClause {\n  readonly type: 'filter'\n  readonly fn: (record: unknown) => boolean\n}\n\n/**\n * A declared deterministic predicate reference (#153). The query\n * builder produces this via `.wherePredicate(name, ctx?)` when a\n * Query has been augmented with a predicates map (typically by the\n * materialized-view registry — see MV v2 spec § Function-based\n * source-row predicates).\n *\n * `predicateHash` is the consumer-supplied stable hash for the\n * function body; `ctxHash` is the canonical-JSON SHA-256 of `ctx`.\n * Both fold into the MV's `queryHash` so a function or ctx change\n * forces refresh on next visit.\n *\n * `fn` is resolved at builder time from the predicates map and\n * embedded directly — so `evaluateClause` can fire it without a\n * runtime lookup.\n */\nexport interface WherePredicateClause {\n  readonly type: 'wherePredicate'\n  readonly name: string\n  readonly ctx: unknown\n  readonly predicateHash: string\n  readonly ctxHash: string\n  readonly fn: (record: unknown, ctx?: unknown) => boolean\n}\n\n/** A logical group of clauses combined by AND or OR. */\nexport interface GroupClause {\n  readonly type: 'group'\n  readonly op: 'and' | 'or'\n  readonly clauses: readonly Clause[]\n}\n\nexport type Clause = FieldClause | FilterClause | WherePredicateClause | GroupClause\n\n/**\n * Read a possibly nested field path like \"address.city\" from a record.\n * Returns undefined if any segment is missing.\n */\nexport function readPath(record: unknown, path: string): unknown {\n  if (record === null || record === undefined) return undefined\n  if (!path.includes('.')) {\n    return (record as Record<string, unknown>)[path]\n  }\n  const segments = path.split('.')\n  let cursor: unknown = record\n  for (const segment of segments) {\n    if (cursor === null || cursor === undefined) return undefined\n    cursor = (cursor as Record<string, unknown>)[segment]\n  }\n  return cursor\n}\n\n/**\n * Evaluate a single field clause against a record.\n * Returns false on type mismatches rather than throwing — query results\n * exclude non-matching records by definition.\n */\nexport function evaluateFieldClause(record: unknown, clause: FieldClause): boolean {\n  const actual = readPath(record, clause.field)\n  const { op, value } = clause\n\n  switch (op) {\n    case '==':\n      return actual === value\n    case '!=':\n      return actual !== value\n    case '<':\n      return isComparable(actual, value) && (actual as number) < (value as number)\n    case '<=':\n      return isComparable(actual, value) && (actual as number) <= (value as number)\n    case '>':\n      return isComparable(actual, value) && (actual as number) > (value as number)\n    case '>=':\n      return isComparable(actual, value) && (actual as number) >= (value as number)\n    case 'in':\n      return Array.isArray(value) && value.includes(actual)\n    case 'contains':\n      if (typeof actual === 'string') return typeof value === 'string' && actual.includes(value)\n      if (Array.isArray(actual)) return actual.includes(value)\n      return false\n    case 'startsWith':\n      return typeof actual === 'string' && typeof value === 'string' && actual.startsWith(value)\n    case 'between': {\n      if (!Array.isArray(value) || value.length !== 2) return false\n      const [lo, hi] = value\n      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false\n      return (actual as number) >= (lo as number) && (actual as number) <= (hi as number)\n    }\n    default: {\n      // Exhaustiveness — TS will error if a new operator is added without a case.\n      const _exhaustive: never = op\n      void _exhaustive\n      return false\n    }\n  }\n}\n\n/**\n * Two values are \"comparable\" if they share an order-defined runtime type.\n * Strings compare lexicographically; numbers and Dates numerically; otherwise false.\n */\nfunction isComparable(a: unknown, b: unknown): boolean {\n  if (typeof a === 'number' && typeof b === 'number') return true\n  if (typeof a === 'string' && typeof b === 'string') return true\n  if (a instanceof Date && b instanceof Date) return true\n  return false\n}\n\n/**\n * Evaluate any clause (field / filter / group) against a record.\n * The recursion depth is bounded by the user's query expression — no risk of\n * blowing the stack on a 50K-record collection.\n */\nexport function evaluateClause(record: unknown, clause: Clause): boolean {\n  switch (clause.type) {\n    case 'field':\n      return evaluateFieldClause(record, clause)\n    case 'filter':\n      return clause.fn(record)\n    case 'wherePredicate':\n      return clause.fn(record, clause.ctx)\n    case 'group':\n      if (clause.op === 'and') {\n        for (const child of clause.clauses) {\n          if (!evaluateClause(record, child)) return false\n        }\n        return true\n      } else {\n        for (const child of clause.clauses) {\n          if (evaluateClause(record, child)) return true\n        }\n        return false\n      }\n  }\n}\n"],"mappings":";AAkFO,SAAS,SAAS,QAAiB,MAAuB;AAC/D,MAAI,WAAW,QAAQ,WAAW,OAAW,QAAO;AACpD,MAAI,CAAC,KAAK,SAAS,GAAG,GAAG;AACvB,WAAQ,OAAmC,IAAI;AAAA,EACjD;AACA,QAAM,WAAW,KAAK,MAAM,GAAG;AAC/B,MAAI,SAAkB;AACtB,aAAW,WAAW,UAAU;AAC9B,QAAI,WAAW,QAAQ,WAAW,OAAW,QAAO;AACpD,aAAU,OAAmC,OAAO;AAAA,EACtD;AACA,SAAO;AACT;AAOO,SAAS,oBAAoB,QAAiB,QAA8B;AACjF,QAAM,SAAS,SAAS,QAAQ,OAAO,KAAK;AAC5C,QAAM,EAAE,IAAI,MAAM,IAAI;AAEtB,UAAQ,IAAI;AAAA,IACV,KAAK;AACH,aAAO,WAAW;AAAA,IACpB,KAAK;AACH,aAAO,WAAW;AAAA,IACpB,KAAK;AACH,aAAO,aAAa,QAAQ,KAAK,KAAM,SAAqB;AAAA,IAC9D,KAAK;AACH,aAAO,aAAa,QAAQ,KAAK,KAAM,UAAsB;AAAA,IAC/D,KAAK;AACH,aAAO,aAAa,QAAQ,KAAK,KAAM,SAAqB;AAAA,IAC9D,KAAK;AACH,aAAO,aAAa,QAAQ,KAAK,KAAM,UAAsB;AAAA,IAC/D,KAAK;AACH,aAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,SAAS,MAAM;AAAA,IACtD,KAAK;AACH,UAAI,OAAO,WAAW,SAAU,QAAO,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK;AACzF,UAAI,MAAM,QAAQ,MAAM,EAAG,QAAO,OAAO,SAAS,KAAK;AACvD,aAAO;AAAA,IACT,KAAK;AACH,aAAO,OAAO,WAAW,YAAY,OAAO,UAAU,YAAY,OAAO,WAAW,KAAK;AAAA,IAC3F,KAAK,WAAW;AACd,UAAI,CAAC,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,EAAG,QAAO;AACxD,YAAM,CAAC,IAAI,EAAE,IAAI;AACjB,UAAI,CAAC,aAAa,QAAQ,EAAE,KAAK,CAAC,aAAa,QAAQ,EAAE,EAAG,QAAO;AACnE,aAAQ,UAAsB,MAAkB,UAAsB;AAAA,IACxE;AAAA,IACA,SAAS;AAEP,YAAM,cAAqB;AAC3B,WAAK;AACL,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAMA,SAAS,aAAa,GAAY,GAAqB;AACrD,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,SAAU,QAAO;AAC3D,MAAI,OAAO,MAAM,YAAY,OAAO,MAAM,SAAU,QAAO;AAC3D,MAAI,aAAa,QAAQ,aAAa,KAAM,QAAO;AACnD,SAAO;AACT;AAOO,SAAS,eAAe,QAAiB,QAAyB;AACvE,UAAQ,OAAO,MAAM;AAAA,IACnB,KAAK;AACH,aAAO,oBAAoB,QAAQ,MAAM;AAAA,IAC3C,KAAK;AACH,aAAO,OAAO,GAAG,MAAM;AAAA,IACzB,KAAK;AACH,aAAO,OAAO,GAAG,QAAQ,OAAO,GAAG;AAAA,IACrC,KAAK;AACH,UAAI,OAAO,OAAO,OAAO;AACvB,mBAAW,SAAS,OAAO,SAAS;AAClC,cAAI,CAAC,eAAe,QAAQ,KAAK,EAAG,QAAO;AAAA,QAC7C;AACA,eAAO;AAAA,MACT,OAAO;AACL,mBAAW,SAAS,OAAO,SAAS;AAClC,cAAI,eAAe,QAAQ,KAAK,EAAG,QAAO;AAAA,QAC5C;AACA,eAAO;AAAA,MACT;AAAA,EACJ;AACF;","names":[]}

package/dist/chunk-NCO2JGKK.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/history/ledger/entry.ts","../src/history/ledger/hash.ts"],"sourcesContent":["/**\n * Ledger entry shape + canonical JSON + sha256 helpers.\n *\n * This file holds the PURE primitives used by the hash-chained ledger:\n * the entry type, the deterministic (sort-stable) JSON encoder, and\n * the sha256 hasher that produces `prevHash` and `ledger.head()`.\n *\n * Everything here is validator-free and side-effect free — the only\n * runtime dep is Web Crypto's `subtle.digest` for the sha256 call,\n * which we already use for every other hashing operation in the core.\n *\n * The hash chain property works like this:\n *\n *   hash(entry[i])       = sha256(canonicalJSON(entry[i]))\n *   entry[i+1].prevHash  = hash(entry[i])\n *\n * Any modification to `entry[i]` (field values, field order, whitespace)\n * produces a different `hash(entry[i])`, which means `entry[i+1]`'s\n * stored `prevHash` no longer matches the recomputed hash, which means\n * `verify()` returns `{ ok: false, divergedAt: i + 1 }`. The chain is\n * append-only and tamper-evident without external anchoring.\n */\n\n/**\n * A single ledger entry in its plaintext form — what gets serialized,\n * hashed, and then encrypted with the ledger DEK before being written\n * to the `_ledger/` adapter collection.\n *\n * ## Why hash the ciphertext, not the plaintext?\n *\n * `payloadHash` is the sha256 of the record's ENCRYPTED envelope bytes,\n * not its plaintext. This matters:\n *\n *   1. **Zero-knowledge preserved.** A user (or a third party) can\n *      verify the ledger against the stored envelopes without any\n *      decryption keys. The adapter layer already holds only\n *      ciphertext, so hashing the ciphertext keeps the ledger at the\n *      same privacy level as the adapter.\n *\n *   2. **Determinism.** Plaintext → ciphertext is randomized by the\n *      fresh per-write IV, so `hash(plaintext)` would need extra\n *      normalization. `hash(ciphertext)` is already deterministic and\n *      unique per write.\n *\n *   3. **Detection property.** If an attacker modifies even one byte of\n *      the stored ciphertext (trying to flip a record), the hash\n *      changes, the ledger's recorded `payloadHash` no longer matches,\n *      and a data-integrity check fails. We don't do that check in\n *      `verify()` today, but the\n *      hook is there for a future `verifyIntegrity()` follow-up.\n *\n * Fields marked `op`, `collection`, `id`, `version`, `ts`, `actor` are\n * plaintext METADATA about the operation — NOT the record itself. The\n * entry is still encrypted at rest via the ledger DEK, but adapters\n * could theoretically infer operation patterns from the sizes and\n * timestamps. This is an accepted trade-off for the tamper-evidence\n * property; full ORAM-level privacy is out of scope for noy-db.\n */\nexport interface LedgerEntry {\n  /**\n   * Zero-based sequential position of this entry in the chain. The\n   * canonical adapter key is this number zero-padded to 10 digits\n   * (`\"0000000001\"`) so lexicographic ordering matches numeric order.\n   */\n  readonly index: number\n\n  /**\n   * Hex-encoded sha256 of the canonical JSON of the PREVIOUS entry.\n   * The genesis entry (index 0) has `prevHash === ''` — the first\n   * entry in a fresh vault has nothing to point back to.\n   */\n  readonly prevHash: string\n\n  /**\n   * Which kind of mutation this entry records. only supports\n   * data operations (`put`, `delete`, `amendment`). Access-control\n   * operations (`grant`, `revoke`, `rotate`) will be added in a\n   * follow-up once the keyring write path is instrumented — that's\n   * tracked in the epic issue.\n   *\n   * `'amendment'` is the multi-record audit entry written by the\n   * guards subsystem when an admin/owner uses `withTransactions(...)`\n   * to repair a constraint-violating state. See `amendment` field\n   * below for the structured payload.\n   *\n   * `'lifecycle'` records a non-data audit event (e.g. partition\n   * handover, #226) — `collection`/`id` are empty and the event detail\n   * lives in `reason` (e.g. `'partition-handed-over:<sealId>'`). Like\n   * `amendment`, it carries no data envelope, so `verifyBackupIntegrity`\n   * skips it in the data cross-check (it still participates in the\n   * tamper-evident chain).\n   */\n  readonly op: 'put' | 'delete' | 'amendment' | 'lifecycle' | 'migration'\n\n  /** The collection the mutation targeted. */\n  readonly collection: string\n\n  /** The record id the mutation targeted. */\n  readonly id: string\n\n  /**\n   * The record version AFTER this mutation. For `put` this is the\n   * newly assigned version; for `delete` this is the version that\n   * was deleted (the last version visible to reads).\n   */\n  readonly version: number\n\n  /** ISO timestamp of the mutation. */\n  readonly ts: string\n\n  /** User id of the actor who performed the mutation. */\n  readonly actor: string\n\n  /**\n   * Hex-encoded sha256 of the encrypted envelope's `_data` field.\n   * For `put`, this is the hash of the new ciphertext. For `delete`,\n   * it's the hash of the last visible ciphertext at deletion time,\n   * or the empty string if nothing was there to delete. Hashing the\n   * ciphertext (not the plaintext) preserves zero-knowledge — see\n   * the file docstring.\n   */\n  readonly payloadHash: string\n\n  /**\n   * Optional human-readable tag describing why this mutation happened\n   * (#1). Threaded through `collection.put(_, _, { reason })`. Common\n   * values include `'import:csv'`, `'import:json'`, `'import:xlsx'` from\n   * `as-*` ImportPlan.apply(), but consumers can use any string for\n   * domain-specific audit filtering. Auto-strip via `canonicalJson` —\n   * absent on the wire, never serialized as `null`.\n   *\n   * Audit consumers filter: `entries.filter(e => e.reason?.startsWith('import:'))`.\n   */\n  readonly reason?: string\n\n  /**\n   * Optional hex-encoded sha256 of the encrypted JSON Patch delta\n   * blob stored alongside this entry in `_ledger_deltas/`. Present\n   * only for `put` operations that had a previous version — the\n   * genesis put of a new record, and every `delete`, leave this\n   * field undefined.\n   *\n   * The delta payload itself lives in a sibling internal collection\n   * (`_ledger_deltas/<paddedIndex>`) and is encrypted with the\n   * ledger DEK. Callers use `ledger.loadDelta(index)` to decrypt and\n   * deserialize it when reconstructing a historical version.\n   *\n   * Why optional instead of always-present: the first put of a\n   * record has no previous version to diff against, so storing an\n   * empty patch would be noise. For deletes there's no \"next\" state\n   * to describe with a delta. Both cases set this field to undefined.\n   *\n   * Note: the canonical-JSON hasher treats `undefined` as invalid\n   * (it's one of the guard rails), so on the wire this field is\n   * either `{ deltaHash: '<hex>' }` or absent from the JSON\n   * entirely — never `{ deltaHash: undefined }`.\n   */\n  readonly deltaHash?: string\n\n  /**\n   * Present only when `op === 'amendment'`. Records the human reason,\n   * the role of the actor, the (collection, id, vBefore, vAfter) tuple\n   * for every record touched, and which guard invariants passed.\n   *\n   * See docs/superpowers/specs/2026-05-18-guards-design.md.\n   */\n  readonly amendment?: {\n    readonly reason: string\n    readonly role: 'admin' | 'owner'\n    readonly changes: ReadonlyArray<{\n      readonly collection: string\n      readonly id: string\n      readonly vBefore: number\n      readonly vAfter: number\n    }>\n    readonly invariantsPassed: ReadonlyArray<string>\n  }\n}\n\n/**\n * Canonical (sort-stable) JSON encoder.\n *\n * This function is the load-bearing primitive of the hash chain:\n * `sha256(canonicalJSON(entry))` must produce the same hex string\n * every time, on every machine, for the same logical entry — otherwise\n * `verify()` would return `{ ok: false }` on cross-platform reads.\n *\n * JavaScript's `JSON.stringify` is almost canonical, but NOT quite:\n * it preserves the insertion order of object keys, which means\n * `{a:1,b:2}` and `{b:2,a:1}` serialize differently. We fix this by\n * recursively walking objects and sorting their keys before\n * concatenation.\n *\n * Arrays keep their original order (reordering them would change\n * semantics). Numbers, strings, booleans, and `null` use the default\n * JSON encoding. `undefined` and functions are rejected — ledger\n * entries are plain data, and silently dropping `undefined` would\n * break the \"same input → same hash\" property if a caller forgot to\n * omit a field.\n *\n * Performance: one pass per nesting level; O(n log n) for key sorting\n * at each object. Entries are small (< 1 KB) so this is negligible\n * compared to the sha256 call.\n */\nexport function canonicalJson(value: unknown): string {\n  if (value === null) return 'null'\n  if (typeof value === 'boolean') return value ? 'true' : 'false'\n  if (typeof value === 'number') {\n    if (!Number.isFinite(value)) {\n      throw new Error(\n        `canonicalJson: refusing to encode non-finite number ${String(value)}`,\n      )\n    }\n    return JSON.stringify(value)\n  }\n  if (typeof value === 'string') return JSON.stringify(value)\n  if (typeof value === 'bigint') {\n    throw new Error('canonicalJson: BigInt is not JSON-serializable')\n  }\n  if (typeof value === 'undefined' || typeof value === 'function') {\n    throw new Error(\n      `canonicalJson: refusing to encode ${typeof value} — include all fields explicitly`,\n    )\n  }\n  if (Array.isArray(value)) {\n    return '[' + value.map((v) => canonicalJson(v)).join(',') + ']'\n  }\n  if (typeof value === 'object') {\n    const obj = value as Record<string, unknown>\n    const keys = Object.keys(obj).sort()\n    const parts: string[] = []\n    for (const key of keys) {\n      parts.push(JSON.stringify(key) + ':' + canonicalJson(obj[key]))\n    }\n    return '{' + parts.join(',') + '}'\n  }\n  throw new Error(`canonicalJson: unexpected value type: ${typeof value}`)\n}\n\n/**\n * Compute a hex-encoded sha256 of a string via Web Crypto's subtle API.\n *\n * We use hex (not base64) for hashes because hex is case-insensitive,\n * fixed-length (64 chars), and easier to compare visually in debug\n * output. Base64 would save a few bytes in storage but every encrypted\n * ledger entry is already much larger than the hash itself.\n */\nexport async function sha256Hex(input: string): Promise<string> {\n  const bytes = new TextEncoder().encode(input)\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)\n  return bytesToHex(new Uint8Array(digest))\n}\n\n/**\n * Compute the canonical hash of a ledger entry. Short wrapper around\n * `canonicalJson` + `sha256Hex`; callers use this instead of composing\n * the two functions every time, so any future change to the hashing\n * pipeline (e.g., adding a domain-separation prefix) lives in one place.\n */\nexport async function hashEntry(entry: LedgerEntry): Promise<string> {\n  return sha256Hex(canonicalJson(entry))\n}\n\n/** Convert a Uint8Array to a lowercase hex string. */\nfunction bytesToHex(bytes: Uint8Array): string {\n  const hex = new Array<string>(bytes.length)\n  for (let i = 0; i < bytes.length; i++) {\n    // Non-null assertion: indexing a Uint8Array within bounds always\n    // returns a number, but the compiler's noUncheckedIndexedAccess\n    // flag widens it to `number | undefined`. Safe here by construction.\n    hex[i] = (bytes[i] ?? 0).toString(16).padStart(2, '0')\n  }\n  return hex.join('')\n}\n\n/**\n * Pad an index to the canonical 10-digit form used as the adapter key.\n * Ten digits is enough for ~10 billion ledger entries per vault\n * — far beyond any realistic use case, but cheap enough that the extra\n * digits don't hurt storage.\n */\nexport function paddedIndex(index: number): string {\n  return String(index).padStart(10, '0')\n}\n\n/** Parse a padded adapter key back into a number. Returns NaN on malformed input. */\nexport function parseIndex(key: string): number {\n  return Number.parseInt(key, 10)\n}\n","/**\n * Envelope payload hash — pinned in its own leaf module so consumers\n * (DictionaryHandle, the active history strategy) can import it\n * without dragging in the `LedgerStore` class.\n *\n * see `constants.ts` for the broader rationale.\n *\n * @internal\n */\n\nimport type { EncryptedEnvelope } from '../../types.js'\nimport { sha256Hex } from './entry.js'\n\n/**\n * Compute the `payloadHash` value for an encrypted envelope. Used by\n * `LedgerStore.append` for both put (hash the new envelope) and\n * delete (hash the previous envelope) paths, and by\n * `DictionaryHandle` so its ledger entries match the same contract.\n *\n * Returns the empty string when there is no envelope (delete of a\n * never-existed record). The empty string tolerated by the ledger\n * entry's `payloadHash` field as the canonical \"nothing here\" value.\n */\nexport async function envelopePayloadHash(\n  envelope: EncryptedEnvelope | null,\n): Promise<string> {\n  if (!envelope) return ''\n  // `_data` is a base64 string for encrypted envelopes and the raw\n  // JSON for plaintext ones. Both are strings, so a single sha256Hex\n  // call works for both modes — the hash value differs between\n  // encrypted/plaintext compartments because the bytes on disk\n  // differ.\n  return sha256Hex(envelope._data)\n}\n"],"mappings":";AA4MO,SAAS,cAAc,OAAwB;AACpD,MAAI,UAAU,KAAM,QAAO;AAC3B,MAAI,OAAO,UAAU,UAAW,QAAO,QAAQ,SAAS;AACxD,MAAI,OAAO,UAAU,UAAU;AAC7B,QAAI,CAAC,OAAO,SAAS,KAAK,GAAG;AAC3B,YAAM,IAAI;AAAA,QACR,uDAAuD,OAAO,KAAK,CAAC;AAAA,MACtE;AAAA,IACF;AACA,WAAO,KAAK,UAAU,KAAK;AAAA,EAC7B;AACA,MAAI,OAAO,UAAU,SAAU,QAAO,KAAK,UAAU,KAAK;AAC1D,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,MAAI,OAAO,UAAU,eAAe,OAAO,UAAU,YAAY;AAC/D,UAAM,IAAI;AAAA,MACR,qCAAqC,OAAO,KAAK;AAAA,IACnD;AAAA,EACF;AACA,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,MAAM,MAAM,IAAI,CAAC,MAAM,cAAc,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI;AAAA,EAC9D;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,MAAM;AACZ,UAAM,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK;AACnC,UAAM,QAAkB,CAAC;AACzB,eAAW,OAAO,MAAM;AACtB,YAAM,KAAK,KAAK,UAAU,GAAG,IAAI,MAAM,cAAc,IAAI,GAAG,CAAC,CAAC;AAAA,IAChE;AACA,WAAO,MAAM,MAAM,KAAK,GAAG,IAAI;AAAA,EACjC;AACA,QAAM,IAAI,MAAM,yCAAyC,OAAO,KAAK,EAAE;AACzE;AAUA,eAAsB,UAAU,OAAgC;AAC9D,QAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,KAAK;AAC5C,QAAM,SAAS,MAAM,WAAW,OAAO,OAAO,OAAO,WAAW,KAAK;AACrE,SAAO,WAAW,IAAI,WAAW,MAAM,CAAC;AAC1C;AAQA,eAAsB,UAAU,OAAqC;AACnE,SAAO,UAAU,cAAc,KAAK,CAAC;AACvC;AAGA,SAAS,WAAW,OAA2B;AAC7C,QAAM,MAAM,IAAI,MAAc,MAAM,MAAM;AAC1C,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AAIrC,QAAI,CAAC,KAAK,MAAM,CAAC,KAAK,GAAG,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG;AAAA,EACvD;AACA,SAAO,IAAI,KAAK,EAAE;AACpB;AAQO,SAAS,YAAY,OAAuB;AACjD,SAAO,OAAO,KAAK,EAAE,SAAS,IAAI,GAAG;AACvC;AAGO,SAAS,WAAW,KAAqB;AAC9C,SAAO,OAAO,SAAS,KAAK,EAAE;AAChC;;;ACzQA,eAAsB,oBACpB,UACiB;AACjB,MAAI,CAAC,SAAU,QAAO;AAMtB,SAAO,UAAU,SAAS,KAAK;AACjC;","names":[]}