@noy-db/hub 0.2.0-pre.9 → 0.3.0-pre.10

package/dist/{chunk-T7JEBOGN.js → chunk-3QSIU3UT.js}

@@ -1,9 +1,11 @@
 import {
-  MaterializedViewCycleError,
+  sha256Hex
+} from "./chunk-3OPY6MK2.js";
+import {
   MaterializedViewSourceUnknownError
-} from "./chunk-B6PB7JLN.js";
+} from "./chunk-S7VFUQM2.js";
 
-// src/materialized-views/dependency-analyzer.ts
+// src/with-formula/materialized-views/dependency-analyzer.ts
 function analyzeDependencies(query) {
   const deps = /* @__PURE__ */ new Set();
   const plan = query._plan();
@@ -54,13 +56,17 @@ function summarizeQueryPlan(query) {
   });
 }
 function summarizeUnionPlan(spec) {
-  const arms = (spec.unionSources ?? []).map((s) => s.collection).join(",");
+  const arms = (spec.unionSources ?? []).map((s) => {
+    const joins = s.join?.length ? `[${s.join.map((j) => `${j.field}\u2192${j.as}`).join(";")}]` : "";
+    return `${s.collection}${joins}`;
+  }).join(",");
   const groupBy = Array.isArray(spec.groupBy) ? [...spec.groupBy].sort().join(",") : typeof spec.groupBy === "string" ? spec.groupBy : "";
   const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(",") : "";
-  return `union(${arms})|groupBy(${groupBy})|aggregate(${aggKeys})`;
+  const moneyKeys = spec.moneyFields ? Object.keys(spec.moneyFields).sort().join(",") : "";
+  return `union(${arms})|groupBy(${groupBy})|aggregate(${aggKeys})|money(${moneyKeys})`;
 }
 
-// src/materialized-views/query-hash.ts
+// src/with-formula/materialized-views/query-hash.ts
 async function computeQueryHash(mvName, dependencies, queryPlanSummary) {
   const canonical = JSON.stringify({
     mvName,
@@ -68,8 +74,7 @@ async function computeQueryHash(mvName, dependencies, queryPlanSummary) {
     queryPlanSummary
   });
   const bytes = new TextEncoder().encode(canonical);
-  const digest = await crypto.subtle.digest("SHA-256", bytes);
-  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return sha256Hex(bytes);
 }
 function canonicalizeQueryPlan(plan) {
   return JSON.stringify(plan, (_key, value) => {
@@ -84,7 +89,8 @@ function canonicalizeQueryPlan(plan) {
   });
 }
 
-// src/materialized-views/registry.ts
+// src/with-formula/materialized-views/registry.ts
+var WHOLE_RECORD = "*";
 var MaterializedViewRegistry = class {
   /** Keyed by `spec.name`. */
   _byName = /* @__PURE__ */ new Map();
@@ -109,14 +115,15 @@ var MaterializedViewRegistry = class {
     let isQuery = false;
     if (spec.unionSources) {
       dependencies = new Set(spec.unionSources.map((s) => s.collection));
+      if (spec.sources) for (const s of spec.sources) dependencies.add(s);
       queryPlanSummary = summarizeUnionPlan(spec);
     } else {
       const q = spec.query(dbForQuery);
       qAny = q;
       isQuery = typeof qAny._plan === "function";
       if (isQuery) {
-        dependencies = analyzeDependencies(q);
-        queryPlanSummary = summarizeQueryPlan(q);
+        dependencies = analyzeDependencies(qAny);
+        queryPlanSummary = summarizeQueryPlan(qAny);
         const predicateRefs = extractPredicateRefs(qAny._plan());
         if (predicateRefs.length > 0) {
           queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs });
@@ -149,7 +156,8 @@ var MaterializedViewRegistry = class {
         if (isFieldClauseOnField(clause, partitionField)) partitionClauses.push(clause);
       }
     }
-    const reg = { spec, outputCollection, dependencies, queryHash, partitionClauses };
+    const grain = spec.unionSources || isQuery ? "record" : "aggregate";
+    const reg = { spec, outputCollection, dependencies, queryHash, partitionClauses, grain };
     this._byName.set(spec.name, reg);
     for (const dep of dependencies) {
       const arr = this._bySource.get(dep);
@@ -170,70 +178,40 @@ var MaterializedViewRegistry = class {
     return [...this._byName.values()];
   }
   /**
-   * Cycle detection over the combined derivation + MV graph. Edges:
-   *   - Derivation: derivation.source → output.collection (each output)
-   *   - MV: every dep in MV.dependencies → MV.outputCollection
-   *
-   * Throws `MaterializedViewCycleError` if the cycle's terminal node
-   * is an MV output collection; otherwise (a pure-derivation cycle)
-   * the caller's `DerivationRegistry.validate()` will surface
-   * `DerivationCycleError` separately at vault open.
-   *
-   * Call AFTER all `register()` calls complete.
+   * Graph edges for #638 Task 2: one `'mv'` edge per registered MV — target
+   * = the output collection (a `WHOLE_RECORD` artifact node), sources =
+   * every dependency (also `WHOLE_RECORD` nodes). Same-collection edges
+   * (`dep === outputCollection`) are skipped IFF the MV declares an
+   * `output.partition` discriminator AND the query has a where-clause that
+   * provably excludes the partition value (`partitionDisjoint`) — the SAME
+   * condition the old local DFS used. Grain comes from the registration-time
+   * `RegisteredMV.grain`.
    */
-  validate(derivationRegistry) {
-    const visited = /* @__PURE__ */ new Set();
-    const stack = [];
-    const mvOutputs = /* @__PURE__ */ new Set();
-    for (const reg of this._byName.values()) mvOutputs.add(reg.outputCollection);
-    const edges = /* @__PURE__ */ new Map();
+  edges() {
+    const out = [];
     for (const reg of this._byName.values()) {
+      const sources = [];
       for (const dep of reg.dependencies) {
         if (dep === reg.outputCollection && partitionDisjoint(reg)) continue;
-        const arr = edges.get(dep);
-        if (arr) arr.push(reg.outputCollection);
-        else edges.set(dep, [reg.outputCollection]);
-      }
-    }
-    if (derivationRegistry) {
-      for (const reg of this._byName.values()) {
-        void reg;
-      }
-      const sourcesToScan = /* @__PURE__ */ new Set();
-      for (const reg of this._byName.values()) {
-        for (const dep of reg.dependencies) sourcesToScan.add(dep);
-        sourcesToScan.add(reg.outputCollection);
-      }
-      for (const src of sourcesToScan) {
-        const strategies = derivationRegistry.strategiesForSource(src);
-        if (strategies.length === 0) continue;
-        for (const s of strategies) {
-          for (const key of Object.keys(s.spec.outputs)) {
-            const o = s.spec.outputs[key];
-            if (!o) continue;
-            const arr = edges.get(src);
-            if (arr) arr.push(o.collection);
-            else edges.set(src, [o.collection]);
-          }
-        }
+        sources.push({ collection: dep, field: WHOLE_RECORD });
       }
+      if (sources.length === 0) continue;
+      out.push({ target: { collection: reg.outputCollection, field: WHOLE_RECORD }, sources, kind: "mv", grain: reg.grain });
     }
-    const visit = (node) => {
-      if (stack.includes(node)) {
-        const cycle = stack.slice(stack.indexOf(node)).concat(node);
-        if (cycle.some((n) => mvOutputs.has(n))) {
-          throw new MaterializedViewCycleError(cycle);
-        }
-        return;
-      }
-      if (visited.has(node)) return;
-      stack.push(node);
-      const outs = edges.get(node);
-      if (outs) for (const o of outs) visit(o);
-      stack.pop();
-      visited.add(node);
-    };
-    for (const node of edges.keys()) visit(node);
+    return out;
+  }
+  /**
+   * Cycle detection, delegated to `ViaGraph.assertAcyclic()` (#638 Task 2 —
+   * retires the local DFS). `graph` is the caller's shared per-vault graph,
+   * ALREADY carrying this registry's `edges()` AND `DerivationRegistry`'s
+   * (registered by the caller — see `Vault._initMaterializedViews`, which
+   * runs after `_initDerivations`, so a pure-derivation cycle already threw
+   * `DerivationCycleError` there; any cycle surfacing here necessarily
+   * touches an MV edge). Throws `MaterializedViewCycleError` — SAME class as
+   * before.
+   */
+  validate(graph) {
+    graph.assertAcyclic();
   }
 };
 function isFieldClauseOnField(clause, field) {
@@ -310,4 +288,4 @@ export {
   MaterializedViewRegistry,
   wrapDbWithPredicates
 };
-//# sourceMappingURL=chunk-T7JEBOGN.js.map
+//# sourceMappingURL=chunk-3QSIU3UT.js.map

package/dist/chunk-3QSIU3UT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-formula/materialized-views/dependency-analyzer.ts","../src/with-formula/materialized-views/query-hash.ts","../src/with-formula/materialized-views/registry.ts"],"sourcesContent":["import type { Query, QueryPlan } from '../../kernel/query/builder.js'\nimport type { JoinContext } from '../../kernel/query/join.js'\nimport type { MaterializedViewStrategy } from './types.js'\n\n/**\n * Walks a `Query<T>` plan and returns the set of source collection\n * names that any source-write should trigger a refresh on.\n *\n * Handles:\n *   - root collection (the one the query was built from)\n *   - FK join targets (`.join(field, { as })`)\n *\n * Also handles:\n *   - cross-join targets (`.crossJoin(target, { as })`) — v3\n *\n * Deferred:\n *   - `.wherePredicate(name)` — v2 predicate primitive\n *   - Overlay-name expansion to {base, overlay}\n *\n * The set is materialized at MV registration time. The MV registry\n * uses it to (a) dispatch `onSourceWrite` only to MVs that actually\n * care, and (b) contribute edges to the shared cycle-detection graph.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function analyzeDependencies(query: Query<any>): Set<string> {\n  const deps = new Set<string>()\n  const plan = query._plan()\n  const ctx = query._joinContext()\n\n  // The root collection is always a dependency.\n  if (ctx?.leftCollection) {\n    deps.add(ctx.leftCollection)\n  }\n\n  // FK join targets contribute additional sources.\n  for (const leg of plan.joins) {\n    deps.add(leg.target)\n  }\n\n  // Cross-join targets are also dependency sources — writes to either side\n  // must trigger MV refresh. Symmetric with FK-join target handling above.\n  for (const clause of plan.clauses) {\n    if (clause.type === 'crossJoin') {\n      deps.add(clause.target)\n    }\n  }\n\n  // Sub-plans inside OR clauses can carry nested joins. Walk them.\n  // (Today only top-level `.join()` populates `plan.joins`, but the\n  // OR-group machinery permits sub-plans, so we recurse defensively.)\n  walkClausesForJoins(plan, deps, ctx)\n\n  return deps\n}\n\nfunction walkClausesForJoins(\n  plan: QueryPlan,\n  deps: Set<string>,\n  ctx: JoinContext | undefined,\n): void {\n  void ctx\n  // Today `plan.joins` carries all join legs at top level. Sub-plans\n  // inside OR groups don't currently support nested joins, so the loop\n  // below is a no-op safety net for future builder extensions.\n  for (const clause of plan.clauses) {\n    if (clause.type === 'group') {\n      // Group clauses don't (yet) carry their own joins; this is a\n      // forward-compat anchor for when OR-groups support nested\n      // sources.\n    }\n  }\n}\n\n/**\n * Convenience: produce a stable string summary of the query plan\n * suitable for `queryHash` derivation. Captures everything the\n * dependency analyzer reads + the where/orderBy/limit/offset\n * structure that affects materialized rows.\n *\n * `joinContext` is intentionally NOT included — the join-resolution\n * function references would defeat hash determinism. The set of join\n * TARGETS (collection names) IS included via the plan.joins legs.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function summarizeQueryPlan(query: Query<any>): string {\n  const plan = query._plan()\n  const ctx = query._joinContext()\n  return JSON.stringify({\n    root: ctx?.leftCollection ?? null,\n    clauses: plan.clauses.map(c => {\n      if (c.type === 'crossJoin') {\n        return {\n          type: 'crossJoin',\n          target: c.target,\n          as: c.as,\n          // Inline on: callback: use sentinel — drift detection disabled for this MV\n          onPredicateName: c.onPredicateName ?? (c.on ? '[inline]' : null),\n          maxRows: c.maxRows ?? null,\n        }\n      }\n      return c\n    }),\n    orderBy: plan.orderBy,\n    limit: plan.limit ?? null,\n    offset: plan.offset,\n    joins: plan.joins.map(j => ({ field: j.field, as: j.as, target: j.target, mode: j.mode })),\n  })\n}\n\n/**\n * Canonical string description of a UNION MV's plan, used as input to\n * `computeQueryHash`.\n *\n * Asymmetry note:\n *   - Arm collection names are NOT sorted. Declaration order is\n *     semantically meaningful for the dedup-only UNION path —\n *     `materializeUnionResult` iterates `spec.unionSources` in\n *     declaration order and keeps the first-seen row per composite key\n *     (tie-break precedence). If we sorted arms here, a consumer who\n *     reordered `unionSources` to change precedence would compute the\n *     same `queryHash`, refresh would be a no-op, and stale MV rows\n *     would persist. Hashing in declaration order makes any reorder\n *     trigger a refresh.\n *   - `groupBy` fields ARE sorted. Multi-key groupBy buckets are\n *     commutative (`canonicalGroupKey` produces the same composite key\n *     regardless of field order in the input spec).\n *   - `aggregate` keys ARE sorted. Reducer-spec keys are independent\n *     of each other — order of declaration doesn't change output.\n *\n * Per-arm `map` functions are NOT fingerprinted; consumers must bump\n * the MV's `name` (or rely on application-level cache busting) when\n * `map` semantics change non-equivalently.\n */\nexport function summarizeUnionPlan<T extends Record<string, unknown>>(\n  spec: MaterializedViewStrategy<T>,\n): string {\n  const arms = (spec.unionSources ?? [])\n    .map(s => {\n      // Fold each arm's join legs into the summary so adding or\n      // reordering joins (which changes the materialized rows) bumps\n      // queryHash. Leg order is declaration-significant (legs chain), so\n      // it is NOT sorted — same rationale as arm declaration order.\n      const joins = s.join?.length\n        ? `[${s.join.map(j => `${j.field}→${j.as}`).join(';')}]`\n        : ''\n      return `${s.collection}${joins}`\n    })\n    .join(',')\n  const groupBy: string = Array.isArray(spec.groupBy)\n    ? [...spec.groupBy].sort().join(',')\n    : typeof spec.groupBy === 'string'\n      ? spec.groupBy\n      : ''\n  const aggKeys = spec.aggregate ? Object.keys(spec.aggregate).sort().join(',') : ''\n  // `moneyFields` changes reducer semantics (float → exact BigInt), so\n  // declaring / removing / re-keying it must bump queryHash. Keys are\n  // sorted — they're independent of each other (one descriptor per\n  // output field), same rationale as aggregate keys.\n  const moneyKeys = spec.moneyFields ? Object.keys(spec.moneyFields).sort().join(',') : ''\n  return `union(${arms})|groupBy(${groupBy})|aggregate(${aggKeys})|money(${moneyKeys})`\n}\n","/**\n * Deterministic hash of a materialized view strategy's \"shape\": MV\n * name + canonical query-plan summary + sorted dependency-set.\n *\n * Used to detect strategy drift: a row whose `_materializedFrom.queryHash`\n * doesn't match the current strategy is considered stale.\n *\n * Web Crypto SHA-256 — no extra deps. Mirrors the v1\n * `computeStrategyHash` pattern.\n */\nimport { sha256Hex } from '../../kernel/enclave/index.js'\n\nexport async function computeQueryHash(\n  mvName: string,\n  /**\n   * Source-collection set the query depends on. Sorted before\n   * canonicalization so set iteration order doesn't affect the hash.\n   */\n  dependencies: ReadonlySet<string>,\n  /**\n   * Stringified query-plan summary. The caller produces this from the\n   * `Query<T>` builder — concretely: a JSON serialization of clauses +\n   * orderBy + limit + offset + joins. Function bodies inside\n   * `wherePredicate` are NOT included here (those carry their own\n   * `predicateHash` to be folded in by a later sub-issue).\n   */\n  queryPlanSummary: string,\n): Promise<string> {\n  const canonical = JSON.stringify({\n    mvName,\n    dependencies: [...dependencies].sort(),\n    queryPlanSummary,\n  })\n  const bytes = new TextEncoder().encode(canonical)\n  return sha256Hex(bytes)\n}\n\n/**\n * Canonicalize a query plan for hashing. Walks the plan structure\n * with sorted keys so insertion order doesn't perturb the result.\n * Lives here rather than in `query/builder.ts` to keep that module\n * stable across MV-specific evolutions.\n *\n * @internal exported for testing\n */\nexport function canonicalizeQueryPlan(plan: unknown): string {\n  return JSON.stringify(plan, (_key, value) => {\n    if (value && typeof value === 'object' && !Array.isArray(value)) {\n      const sorted: Record<string, unknown> = {}\n      for (const k of Object.keys(value as Record<string, unknown>).sort()) {\n        sorted[k] = (value as Record<string, unknown>)[k]\n      }\n      return sorted\n    }\n    return value\n  })\n}\n","import { MaterializedViewSourceUnknownError } from '../../kernel/errors.js'\nimport type { ViaGraph, FieldRef, EdgeKind, Grain } from '../../kernel/via/graph.js'\nimport type { Clause, FieldClause } from '../../kernel/query/predicate.js'\nimport type { DeclaredPredicate } from '../../kernel/query/builder.js'\nimport { analyzeDependencies, summarizeQueryPlan, summarizeUnionPlan } from './dependency-analyzer.js'\nimport { computeQueryHash } from './query-hash.js'\nimport type { MaterializedViewStrategy, MVQueryContext } from './types.js'\n\n/**\n * Whole-record artifact-grain field marker (#638 Task 2) — MUST match\n * `derivations/registry.ts`'s and `vault.ts`'s overlay-edge marker so\n * cross-registry edges (a derivation feeding an MV, or vice versa) resolve\n * to the SAME graph node. See that file's `WHOLE_RECORD` doc comment.\n */\nconst WHOLE_RECORD = '*'\n\n/**\n * One registered MV strategy alongside its derived metadata. Stored\n * type-erased on `TRow` so the registry can hold heterogeneous MVs.\n */\nexport interface RegisteredMV {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  readonly spec: MaterializedViewStrategy<any>\n  /** Output collection name (`spec.output?.collection ?? spec.name`). */\n  readonly outputCollection: string\n  /** Set of source collections; populated at registration via the analyzer. */\n  readonly dependencies: ReadonlySet<string>\n  /** Canonical `queryHash` — `_materializedFrom.queryHash` for every emitted row. */\n  readonly queryHash: string\n  /**\n   * Top-level FieldClauses on the partition field, captured at\n   * registration time. Used by the cycle detector to resolve\n   * same-collection-as-source edges via the partition-discriminator\n   * check. Empty when `spec.output?.partition` is undefined.\n   */\n  readonly partitionClauses: readonly FieldClause[]\n  /**\n   * #638 Task 2 — `'record'` for a row-per-source-row Query<T> or\n   * `unionSources` MV, `'aggregate'` for a `.groupBy().aggregate()` MV\n   * (the shape that requires explicit `sources`, since the dependency\n   * analyzer can't walk an aggregate plan). Feeds `edges()`'s grain.\n   */\n  readonly grain: Grain\n}\n\n/**\n * Vault-internal registry of MV strategies. Owned by `Vault`; not\n * exported. Parallel to v1's `DerivationRegistry`; the two graphs share\n * a single cycle-detection pass at vault open (see `validate`).\n *\n * @internal\n */\nexport class MaterializedViewRegistry {\n  /** Keyed by `spec.name`. */\n  private readonly _byName = new Map<string, RegisteredMV>()\n  /** Keyed by dependency source-collection → MVs that depend on it. */\n  private readonly _bySource = new Map<string, RegisteredMV[]>()\n\n  /**\n   * Register an MV. Invokes `spec.query()` once at registration time to\n   * read the plan + join context; the resulting `Query<T>` is discarded\n   * after dependency extraction. `vault.collection(...)` must therefore\n   * be functional by the time this runs — typically wired from\n   * `Vault._initMaterializedViews` after collection bootstrap.\n   *\n   * Throws `MaterializedViewSourceUnknownError` if the analyzer\n   * surfaces a dependency the vault doesn't know about (when a\n   * `knownCollections` checker is supplied).\n   */\n  async register(\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    spec: MaterializedViewStrategy<any>,\n    db: MVQueryContext,\n    options?: { knownCollections?: (name: string) => boolean },\n  ): Promise<void> {\n    // Build a predicate-aware db wrapper. If `spec.predicates` is\n    // declared, the wrapper intercepts `.collection().query()` and\n    // attaches the predicates map to the resulting Query<T>. With no\n    // predicates declared, the wrapper is the original db unchanged.\n    const dbForQuery = spec.predicates ? wrapDbWithPredicates(db, spec.predicates) : db\n\n    // Invoke the query callback once to inspect its plan / dependencies.\n    // For Query<T> shapes the analyzer extracts deps + plan summary\n    // automatically. Aggregation / GroupedAggregation shapes don't\n    // expose the underlying Query, so the spec must declare `sources`\n    // explicitly. `partitionClauses` are only populated for Query<T>\n    // since same-collection-partition is a non-aggregate concern.\n    // UNION-form strategies: dependencies and plan summary come\n    // straight off the strategy — no `query` callback to introspect.\n    // The dependency-analyzer + summarizer are bypassed entirely; the\n    // executor handles materialization via `materializeUnionResult`.\n    let dependencies: Set<string>\n    let queryPlanSummary: string\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let qAny: any = null\n    let isQuery = false\n    if (spec.unionSources) {\n      dependencies = new Set(spec.unionSources.map(s => s.collection))\n      // Per-arm joins resolve right-side collections that aren't among\n      // the arm `collection`s. The consumer lists those in `sources`;\n      // fold them into the dependency set so a write to a join-target\n      // collection triggers MV refresh (and contributes a cycle edge).\n      if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      queryPlanSummary = summarizeUnionPlan(spec)\n    } else {\n      const q = spec.query!(dbForQuery)\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      qAny = q as any\n      isQuery = typeof qAny._plan === 'function'\n      if (isQuery) {\n        // `q` is the `Query` arm of the union here (runtime-confirmed via\n        // `qAny._plan` above); reuse the already-`any` `qAny` the block uses\n        // for `_plan()` rather than re-narrowing.\n        dependencies = analyzeDependencies(qAny)\n        queryPlanSummary = summarizeQueryPlan(qAny)\n        // Fold `.wherePredicate(name, ctx)` references into the plan\n        // summary so predicate function or ctx changes (signalled by\n        // bumping `hash` or supplying a different ctx) propagate into\n        // `queryHash` and force refresh on next visit.\n        const predicateRefs = extractPredicateRefs(qAny._plan())\n        if (predicateRefs.length > 0) {\n          queryPlanSummary = JSON.stringify({ plan: queryPlanSummary, predicates: predicateRefs })\n        }\n        // If `sources` is ALSO declared, take the union (consumer's\n        // explicit list extends the auto-analyzed set).\n        if (spec.sources) for (const s of spec.sources) dependencies.add(s)\n      } else {\n        // Aggregate shape: require explicit `sources`.\n        if (!spec.sources || spec.sources.length === 0) {\n          throw new Error(\n            `withMaterializedView \"${spec.name}\": query() returned an aggregate ` +\n              `(Aggregation or GroupedAggregation) but no \\`sources\\` field is declared. ` +\n              `The dependency analyzer cannot walk through groupBy().aggregate() ` +\n              `back to the source — declare sources: [...] explicitly.`,\n          )\n        }\n        dependencies = new Set(spec.sources)\n        // Aggregate plans don't carry a chainable query plan for summary\n        // purposes; the dep-set + spec.name serve as the queryHash inputs.\n        queryPlanSummary = JSON.stringify({ aggregate: true, sources: [...spec.sources].sort() })\n      }\n    }\n\n    // Sanity-check declared dependencies against the vault's known\n    // collections. Optional — when the checker isn't supplied (test\n    // wiring, in-process composition) the registration succeeds and\n    // any typo surfaces at first onSourceWrite as a no-op.\n    if (options?.knownCollections) {\n      for (const dep of dependencies) {\n        if (!options.knownCollections(dep)) {\n          throw new MaterializedViewSourceUnknownError(spec.name, dep)\n        }\n      }\n    }\n\n    const outputCollection = spec.output?.collection ?? spec.name\n    const queryHash = await computeQueryHash(spec.name, dependencies, queryPlanSummary)\n    // For same-collection-as-source MVs, capture the where-clauses on\n    // the partition field so cycle detection can prove disjointness.\n    // Only applicable to Query<T> shapes — aggregate MVs don't carry\n    // a chainable plan to inspect (and same-collection aggregation\n    // doesn't make sense for same-collection aggregation).\n    const partitionClauses: FieldClause[] = []\n    const partitionField = spec.output?.partition?.field\n    if (partitionField !== undefined && isQuery) {\n      const plan = qAny._plan()\n      for (const clause of plan.clauses) {\n        if (isFieldClauseOnField(clause, partitionField)) partitionClauses.push(clause)\n      }\n    }\n    // #638 Task 2 — 'aggregate' only for the explicit-sources aggregate shape\n    // (groupBy().aggregate() with no chainable plan); a row-per-source-row\n    // Query<T> or a unionSources MV is 'record'.\n    const grain: Grain = spec.unionSources || isQuery ? 'record' : 'aggregate'\n    const reg: RegisteredMV = { spec, outputCollection, dependencies, queryHash, partitionClauses, grain }\n\n    this._byName.set(spec.name, reg)\n    for (const dep of dependencies) {\n      const arr = this._bySource.get(dep)\n      if (arr) arr.push(reg)\n      else this._bySource.set(dep, [reg])\n    }\n  }\n\n  /** All MVs that depend on `source`, in registration order. */\n  mvsForSource(source: string): ReadonlyArray<RegisteredMV> {\n    return this._bySource.get(source) ?? []\n  }\n\n  /** Single MV by name, or `undefined`. */\n  byName(name: string): RegisteredMV | undefined {\n    return this._byName.get(name)\n  }\n\n  /** Iterate over every registered MV. */\n  all(): ReadonlyArray<RegisteredMV> {\n    return [...this._byName.values()]\n  }\n\n  /**\n   * Graph edges for #638 Task 2: one `'mv'` edge per registered MV — target\n   * = the output collection (a `WHOLE_RECORD` artifact node), sources =\n   * every dependency (also `WHOLE_RECORD` nodes). Same-collection edges\n   * (`dep === outputCollection`) are skipped IFF the MV declares an\n   * `output.partition` discriminator AND the query has a where-clause that\n   * provably excludes the partition value (`partitionDisjoint`) — the SAME\n   * condition the old local DFS used. Grain comes from the registration-time\n   * `RegisteredMV.grain`.\n   */\n  edges(): ReadonlyArray<{ readonly target: FieldRef; readonly sources: readonly FieldRef[]; readonly kind: EdgeKind; readonly grain: Grain }> {\n    const out: Array<{ target: FieldRef; sources: FieldRef[]; kind: EdgeKind; grain: Grain }> = []\n    for (const reg of this._byName.values()) {\n      const sources: FieldRef[] = []\n      for (const dep of reg.dependencies) {\n        if (dep === reg.outputCollection && partitionDisjoint(reg)) continue\n        sources.push({ collection: dep, field: WHOLE_RECORD })\n      }\n      if (sources.length === 0) continue\n      out.push({ target: { collection: reg.outputCollection, field: WHOLE_RECORD }, sources, kind: 'mv', grain: reg.grain })\n    }\n    return out\n  }\n\n  /**\n   * Cycle detection, delegated to `ViaGraph.assertAcyclic()` (#638 Task 2 —\n   * retires the local DFS). `graph` is the caller's shared per-vault graph,\n   * ALREADY carrying this registry's `edges()` AND `DerivationRegistry`'s\n   * (registered by the caller — see `Vault._initMaterializedViews`, which\n   * runs after `_initDerivations`, so a pure-derivation cycle already threw\n   * `DerivationCycleError` there; any cycle surfacing here necessarily\n   * touches an MV edge). Throws `MaterializedViewCycleError` — SAME class as\n   * before.\n   */\n  validate(graph: ViaGraph): void {\n    graph.assertAcyclic()\n  }\n}\n\n/**\n * Type guard: is the clause a top-level `FieldClause` on the given\n * field? Used by the partition-disjoint check.\n *\n * @internal\n */\nfunction isFieldClauseOnField(clause: Clause, field: string): clause is FieldClause {\n  return clause.type === 'field' && clause.field === field\n}\n\n/**\n * Wrap an `MVQueryContext` so its `.collection().query()` returns a\n * Query<T> with the MV's declared predicates attached. Bare Queries\n * (outside of any MV) don't gain `.wherePredicate()` — only Queries\n * obtained through this wrapped db do.\n *\n * @internal\n */\nexport function wrapDbWithPredicates(\n  db: MVQueryContext,\n  predicates: NonNullable<MaterializedViewStrategy<Record<string, unknown>>['predicates']>,\n): MVQueryContext {\n  // Build the predicate map once — the fn signature in the MV spec\n  // is row-typed but the QueryBuilder casts to unknown, so we widen\n  // here for the Map.\n  const map = new Map<string, DeclaredPredicate>()\n  for (const [name, decl] of Object.entries(predicates)) {\n    map.set(name, {\n      hash: decl.hash,\n      fn: decl.fn as (record: unknown, ctx?: unknown) => boolean,\n    })\n  }\n  return {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    collection<T extends Record<string, unknown>>(name: string): any {\n      const c = db.collection<T>(name)\n      // Return an object that delegates everything to `c` but\n      // overrides `.query()` to attach predicates via the new\n      // `Query._withPredicates()` accessor.\n      return new Proxy(c, {\n        get(target, prop, receiver) {\n          if (prop === 'query') {\n            return (...args: unknown[]) => {\n              // eslint-disable-next-line @typescript-eslint/no-explicit-any\n              const q = (target.query as any)(...args)\n              // For non-aggregate Query<T>, attach predicates. For\n              // legacy predicate-arg overload that returns T[] (sync\n              // filter), pass through unchanged.\n               \n              if (q && typeof q._withPredicates === 'function') {\n                return q._withPredicates(map)\n              }\n              return q\n            }\n          }\n          return Reflect.get(target, prop, receiver)\n        },\n      })\n    },\n  }\n}\n\n/**\n * Walk a QueryPlan's clauses and collect predicate-reference markers\n * for `queryHash` derivation. Returns a sorted array (deterministic\n * order) of `{ name, predicateHash, ctxHash }` tuples — these are the\n * hashable identity of each `.wherePredicate()` call site.\n *\n * @internal\n */\nfunction extractPredicateRefs(\n  plan: { clauses: readonly Clause[] },\n): Array<{ name: string; predicateHash: string; ctxHash: string }> {\n  const refs: Array<{ name: string; predicateHash: string; ctxHash: string }> = []\n  const walk = (clauses: readonly Clause[]): void => {\n    for (const c of clauses) {\n      if (c.type === 'wherePredicate') {\n        refs.push({ name: c.name, predicateHash: c.predicateHash, ctxHash: c.ctxHash })\n      } else if (c.type === 'group') {\n        walk(c.clauses)\n      }\n    }\n  }\n  walk(plan.clauses)\n  // Stable-sort by (name, predicateHash, ctxHash) — same predicate\n  // appearing twice with different ctx hashes both flow through.\n  refs.sort((a, b) => {\n    if (a.name !== b.name) return a.name < b.name ? -1 : 1\n    if (a.predicateHash !== b.predicateHash) return a.predicateHash < b.predicateHash ? -1 : 1\n    return a.ctxHash < b.ctxHash ? -1 : a.ctxHash > b.ctxHash ? 1 : 0\n  })\n  return refs\n}\n\n/**\n * Provability check for the same-collection partition-discriminator.\n * Returns `true` when\n * the captured partition clauses on the MV's query provably exclude\n * the partition's value — meaning the input filter and the output\n * partition are disjoint and the same-collection edge isn't really a\n * cycle.\n *\n * Supported provability shapes (narrow on purpose — DERIV-PP30-001\n * is the load-bearing case):\n *\n * - `.where(field, '==', X)` where X !== partition.value → disjoint\n * - `.where(field, '!=', partition.value)` → disjoint\n * - `.where(field, 'in', [...])` where partition.value NOT in list → disjoint\n *\n * Anything else (no clause on the partition field, an 'in' list that\n * contains partition.value, unsupported operators) → not disjoint,\n * the cycle detector surfaces `MaterializedViewCycleError`.\n *\n * @internal\n */\nfunction partitionDisjoint(reg: RegisteredMV): boolean {\n  const partition = reg.spec.output?.partition\n  if (partition === undefined) return false\n  const value = partition.value\n  // The OR-semantics of multiple where-clauses on the same field\n  // would muddy this check. v2 only treats AND-chained clauses;\n  // any clause that proves disjoint is sufficient.\n  for (const c of reg.partitionClauses) {\n    if (c.op === '==' && c.value !== value) return true\n    if (c.op === '!=' && c.value === value) return true\n    if (c.op === 'in' && Array.isArray(c.value)) {\n      const list = c.value as readonly unknown[]\n      if (!list.includes(value)) return true\n    }\n  }\n  return false\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-ZYWZWG6G.js → chunk-4OMCIY6F.js}

@@ -1,19 +1,39 @@
 import {
-  ensureCollectionDEK
-} from "./chunk-DONMZAD2.js";
+  SYNC_CREDENTIALS_COLLECTION,
+  ensureCollectionDEK,
+  grant,
+  revoke,
+  rotateKeys
+} from "./chunk-J4LPNIGK.js";
 import {
-  NOYDB_FORMAT_VERSION
-} from "./chunk-WIRRPTFH.js";
+  openEnvelopeJson
+} from "./chunk-MCHVVJIA.js";
 import {
-  decrypt,
   encrypt
-} from "./chunk-PP6W64Y3.js";
+} from "./chunk-3OPY6MK2.js";
+import {
+  NOYDB_FORMAT_VERSION
+} from "./chunk-YN5IAHN6.js";
 import {
   PermissionDeniedError
-} from "./chunk-B6PB7JLN.js";
+} from "./chunk-S7VFUQM2.js";
 
-// src/team/sync-credentials.ts
-var SYNC_CREDENTIALS_COLLECTION = "_sync_credentials";
+// src/with-party/team/active.ts
+function withTeam() {
+  return {
+    async grant(team, vault, options, factors) {
+      return team.runGrant(grant, vault, options, factors);
+    },
+    async revoke(team, vault, options, factors) {
+      return team.runRevoke(revoke, vault, options, factors);
+    },
+    async rotate(team, vault, collections) {
+      return team.runRotate(rotateKeys, vault, collections);
+    }
+  };
+}
+
+// src/with-party/team/sync-credentials.ts
 function requireAdminAccess(keyring) {
   if (keyring.role !== "owner" && keyring.role !== "admin") {
     throw new PermissionDeniedError(
@@ -50,7 +70,7 @@ async function getCredential(adapter, vault, keyring, adapterId) {
   const dek = await getDek(SYNC_CREDENTIALS_COLLECTION);
   const envelope = await adapter.get(vault, SYNC_CREDENTIALS_COLLECTION, adapterId);
   if (!envelope) return null;
-  const plaintext = await decrypt(envelope._iv, envelope._data, dek);
+  const plaintext = await openEnvelopeJson(envelope, dek);
   return JSON.parse(plaintext);
 }
 async function deleteCredential(adapter, vault, keyring, adapterId) {
@@ -69,11 +89,11 @@ async function credentialStatus(adapter, vault, keyring, adapterId) {
 }
 
 export {
-  SYNC_CREDENTIALS_COLLECTION,
+  withTeam,
   putCredential,
   getCredential,
   deleteCredential,
   listCredentials,
   credentialStatus
 };
-//# sourceMappingURL=chunk-ZYWZWG6G.js.map
+//# sourceMappingURL=chunk-4OMCIY6F.js.map

package/dist/chunk-4OMCIY6F.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-party/team/active.ts","../src/with-party/team/sync-credentials.ts"],"sourcesContent":["/**\n * Enable the multi-user team capability (#267 Track A tail).\n *\n * Pass to `createNoydb({ teamStrategy: withTeam() })` to make `db.grant` /\n * `db.revoke` / `db.rotate` live. The keyring grant/revoke/rotate engines\n * are statically imported HERE — this module is reachable only through the\n * `@noy-db/hub/team` subpath (and the root barrel's tree-shakeable\n * re-export), so a single-user floor bundle never carries them. The facade\n * (`TeamFacade.runGrant` / `runRevoke` / `runRotate`) owns the policy-gate +\n * keyring plumbing and receives the engine as an argument.\n */\nimport type { TeamStrategy } from './strategy.js'\nimport { grant as grantEngine, revoke as revokeEngine, rotateKeys as rotateEngine } from './keyring.js'\n\nexport function withTeam(): TeamStrategy {\n  return {\n    async grant(team, vault, options, factors) {\n      return team.runGrant(grantEngine, vault, options, factors)\n    },\n    async revoke(team, vault, options, factors) {\n      return team.runRevoke(revokeEngine, vault, options, factors)\n    },\n    async rotate(team, vault, collections) {\n      return team.runRotate(rotateEngine, vault, collections)\n    },\n  }\n}\n","/**\n * _sync_credentials reserved collection —\n *\n * Stores per-adapter OAuth tokens (and any other long-lived sync secrets) as\n * encrypted records inside the vault itself. Tokens are wrapped with the\n * compartment's own DEK, live on disk as ciphertext like any other record, and\n * are accessed only through the dedicated API in this module — never via\n * `vault.collection('_sync_credentials')`.\n *\n * Design decisions\n * ────────────────\n *\n * **Why a reserved collection, not a separate store?**\n * The compartment's existing encryption stack (AES-256-GCM + collection DEK)\n * is exactly the right primitive for protecting OAuth tokens at rest. Using a\n * separate store would require a new encryption surface, new adapter calls,\n * and a new backup/restore path — all of which already exist for collections.\n *\n * **Why not exposed as a regular collection?**\n * The same reason `_keyring` and `_ledger` aren't: they have invariants that\n * must be enforced (naming scheme, no cross-user leakage, no schema\n * validation, no history/ledger writes for privacy). Routing through a\n * dedicated API enforces those invariants.\n *\n * **Token lifecycle:**\n * - `putCredential(vault, adapterId, token)` — store or overwrite\n * - `getCredential(vault, adapterId)` — load and decrypt\n * - `deleteCredential(vault, adapterId)` — remove\n * - `listCredentials(vault)` — enumerate adapter IDs (not tokens)\n *\n * The `adapterId` is the record ID within the `_sync_credentials` collection.\n * It should be a stable, human-readable identifier for the adapter instance\n * (e.g. `'google-drive'`, `'dropbox'`, `'s3-prod'`).\n *\n * **ACL:** only `owner` and `admin` roles can read/write sync credentials.\n * Operators, viewers, and clients cannot call this API. The check is made\n * against the caller's keyring role at call time.\n */\n\nimport type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js'\nimport { NOYDB_FORMAT_VERSION } from '../../kernel/types.js'\nimport type { UnlockedKeyring } from './keyring.js'\nimport { encrypt, openEnvelopeJson } from '../../kernel/enclave/index.js'\nimport { ensureCollectionDEK } from './keyring.js'\nimport { PermissionDeniedError } from '../../kernel/errors.js'\n\n/**\n * The reserved collection name. Never collides with user collections.\n * Canonical definition lives in `reserved-secret-collections.ts` (shared with\n * the `vault.collection()` guard and grant DEK-propagation); re-exported here\n * for existing consumers.\n */\nexport { SYNC_CREDENTIALS_COLLECTION } from './reserved-secret-collections.js'\nimport { SYNC_CREDENTIALS_COLLECTION } from './reserved-secret-collections.js'\n\n// ─── Token types ──────────────────────────────────────────────────────\n\n/**\n * An OAuth/auth token stored in `_sync_credentials`.\n *\n * Fields mirror the OAuth2 token response shape. `customData` is an escape\n * hatch for adapter-specific secrets (API keys, connection strings, etc.)\n * that don't fit the OAuth2 shape.\n */\nexport interface SyncCredential {\n  /** Stable identifier for the adapter instance (e.g. 'google-drive'). */\n  readonly adapterId: string\n  /** OAuth token type, usually 'Bearer'. */\n  readonly tokenType: string\n  /** The access token. Expires at `expiresAt` if set. */\n  readonly accessToken: string\n  /** Long-lived refresh token for renewing the access token. */\n  readonly refreshToken?: string\n  /** ISO timestamp when `accessToken` expires. Absent means \"no expiry\". */\n  readonly expiresAt?: string\n  /** Space-separated OAuth scopes. */\n  readonly scopes?: string\n  /** Adapter-specific opaque data (API keys, endpoints, etc.). */\n  readonly customData?: Record<string, string>\n}\n\n// ─── Access check ─────────────────────────────────────────────────────\n\nfunction requireAdminAccess(keyring: UnlockedKeyring): void {\n  // FR-6: custodian is INTENTIONALLY excluded. Sync credentials are the\n  // firm's hosting/infrastructure secrets (OAuth tokens, connection strings) —\n  // not the custodian's operational scope. A custodian operates the DATA but\n  // must never mint or read transport credentials that could be used to\n  // re-home or impersonate the firm's vault. Do NOT add 'custodian' here.\n  if (keyring.role !== 'owner' && keyring.role !== 'admin') {\n    throw new PermissionDeniedError(\n      `Sync credentials require owner or admin role. Current role: \"${keyring.role}\"`,\n    )\n  }\n}\n\n// ─── Public API ────────────────────────────────────────────────────────\n\n/**\n * Store or overwrite a sync credential for the given adapter.\n *\n * The credential is encrypted with the `_sync_credentials` collection DEK\n * (auto-generated on first use). The record ID is the `adapterId`.\n *\n * Requires owner or admin role.\n */\nexport async function putCredential(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n  credential: SyncCredential,\n): Promise<void> {\n  requireAdminAccess(keyring)\n\n  const getDek = await ensureCollectionDEK(adapter, vault, keyring)\n  const dek = await getDek(SYNC_CREDENTIALS_COLLECTION)\n\n  const { iv, data } = await encrypt(JSON.stringify(credential), dek)\n\n  const existing = await adapter.get(vault, SYNC_CREDENTIALS_COLLECTION, credential.adapterId)\n  const version = existing ? existing._v + 1 : 1\n\n  const envelope: EncryptedEnvelope = {\n    _noydb: NOYDB_FORMAT_VERSION,\n    _v: version,\n    _ts: new Date().toISOString(),\n    _iv: iv,\n    _data: data,\n    _by: keyring.userId,\n  }\n\n  await adapter.put(\n    vault,\n    SYNC_CREDENTIALS_COLLECTION,\n    credential.adapterId,\n    envelope,\n    existing ? existing._v : undefined,\n  )\n}\n\n/**\n * Load and decrypt a sync credential for the given adapter ID.\n *\n * Returns `null` if no credential exists for this adapter.\n * Requires owner or admin role.\n */\nexport async function getCredential(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n  adapterId: string,\n): Promise<SyncCredential | null> {\n  requireAdminAccess(keyring)\n\n  const getDek = await ensureCollectionDEK(adapter, vault, keyring)\n  const dek = await getDek(SYNC_CREDENTIALS_COLLECTION)\n\n  const envelope = await adapter.get(vault, SYNC_CREDENTIALS_COLLECTION, adapterId)\n  if (!envelope) return null\n\n  const plaintext = await openEnvelopeJson(envelope, dek)\n  return JSON.parse(plaintext) as SyncCredential\n}\n\n/**\n * Delete a sync credential by adapter ID.\n *\n * No-op if the credential doesn't exist. Requires owner or admin role.\n */\nexport async function deleteCredential(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n  adapterId: string,\n): Promise<void> {\n  requireAdminAccess(keyring)\n  await adapter.delete(vault, SYNC_CREDENTIALS_COLLECTION, adapterId)\n}\n\n/**\n * List all adapter IDs that have stored credentials.\n *\n * Returns only the IDs, never the credential payloads. Useful for\n * displaying \"connected adapters\" in UI without decrypting tokens.\n * Requires owner or admin role.\n */\nexport async function listCredentials(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n): Promise<string[]> {\n  requireAdminAccess(keyring)\n  return adapter.list(vault, SYNC_CREDENTIALS_COLLECTION)\n}\n\n/**\n * Check whether a credential exists and whether its access token has expired.\n *\n * Returns `{ exists: false }` if no credential is stored, or\n * `{ exists: true, expired: boolean }` based on the `expiresAt` field.\n * Requires owner or admin role.\n */\nexport async function credentialStatus(\n  adapter: NoydbStore,\n  vault: string,\n  keyring: UnlockedKeyring,\n  adapterId: string,\n): Promise<{ exists: false } | { exists: true; expired: boolean }> {\n  const credential = await getCredential(adapter, vault, keyring, adapterId)\n  if (!credential) return { exists: false }\n\n  const expired = credential.expiresAt\n    ? Date.now() > new Date(credential.expiresAt).getTime()\n    : false\n\n  return { exists: true, expired }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAcO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL,MAAM,MAAM,MAAM,OAAO,SAAS,SAAS;AACzC,aAAO,KAAK,SAAS,OAAa,OAAO,SAAS,OAAO;AAAA,IAC3D;AAAA,IACA,MAAM,OAAO,MAAM,OAAO,SAAS,SAAS;AAC1C,aAAO,KAAK,UAAU,QAAc,OAAO,SAAS,OAAO;AAAA,IAC7D;AAAA,IACA,MAAM,OAAO,MAAM,OAAO,aAAa;AACrC,aAAO,KAAK,UAAU,YAAc,OAAO,WAAW;AAAA,IACxD;AAAA,EACF;AACF;;;ACyDA,SAAS,mBAAmB,SAAgC;AAM1D,MAAI,QAAQ,SAAS,WAAW,QAAQ,SAAS,SAAS;AACxD,UAAM,IAAI;AAAA,MACR,gEAAgE,QAAQ,IAAI;AAAA,IAC9E;AAAA,EACF;AACF;AAYA,eAAsB,cACpB,SACA,OACA,SACA,YACe;AACf,qBAAmB,OAAO;AAE1B,QAAM,SAAS,MAAM,oBAAoB,SAAS,OAAO,OAAO;AAChE,QAAM,MAAM,MAAM,OAAO,2BAA2B;AAEpD,QAAM,EAAE,IAAI,KAAK,IAAI,MAAM,QAAQ,KAAK,UAAU,UAAU,GAAG,GAAG;AAElE,QAAM,WAAW,MAAM,QAAQ,IAAI,OAAO,6BAA6B,WAAW,SAAS;AAC3F,QAAM,UAAU,WAAW,SAAS,KAAK,IAAI;AAE7C,QAAM,WAA8B;AAAA,IAClC,QAAQ;AAAA,IACR,IAAI;AAAA,IACJ,MAAK,oBAAI,KAAK,GAAE,YAAY;AAAA,IAC5B,KAAK;AAAA,IACL,OAAO;AAAA,IACP,KAAK,QAAQ;AAAA,EACf;AAEA,QAAM,QAAQ;AAAA,IACZ;AAAA,IACA;AAAA,IACA,WAAW;AAAA,IACX;AAAA,IACA,WAAW,SAAS,KAAK;AAAA,EAC3B;AACF;AAQA,eAAsB,cACpB,SACA,OACA,SACA,WACgC;AAChC,qBAAmB,OAAO;AAE1B,QAAM,SAAS,MAAM,oBAAoB,SAAS,OAAO,OAAO;AAChE,QAAM,MAAM,MAAM,OAAO,2BAA2B;AAEpD,QAAM,WAAW,MAAM,QAAQ,IAAI,OAAO,6BAA6B,SAAS;AAChF,MAAI,CAAC,SAAU,QAAO;AAEtB,QAAM,YAAY,MAAM,iBAAiB,UAAU,GAAG;AACtD,SAAO,KAAK,MAAM,SAAS;AAC7B;AAOA,eAAsB,iBACpB,SACA,OACA,SACA,WACe;AACf,qBAAmB,OAAO;AAC1B,QAAM,QAAQ,OAAO,OAAO,6BAA6B,SAAS;AACpE;AASA,eAAsB,gBACpB,SACA,OACA,SACmB;AACnB,qBAAmB,OAAO;AAC1B,SAAO,QAAQ,KAAK,OAAO,2BAA2B;AACxD;AASA,eAAsB,iBACpB,SACA,OACA,SACA,WACiE;AACjE,QAAM,aAAa,MAAM,cAAc,SAAS,OAAO,SAAS,SAAS;AACzE,MAAI,CAAC,WAAY,QAAO,EAAE,QAAQ,MAAM;AAExC,QAAM,UAAU,WAAW,YACvB,KAAK,IAAI,IAAI,IAAI,KAAK,WAAW,SAAS,EAAE,QAAQ,IACpD;AAEJ,SAAO,EAAE,QAAQ,MAAM,QAAQ;AACjC;","names":[]}

package/dist/chunk-4Q6HSHHL.js

@@ -0,0 +1,90 @@
+// src/with-shape/blobs/object-projection.ts
+function memoryObjectProjection(opts = {}) {
+  const base = opts.baseUrl ?? "memory://objects";
+  const store = /* @__PURE__ */ new Map();
+  return {
+    name: "memory",
+    async putObject(key, bytes, o) {
+      store.set(key, {
+        bytes,
+        contentType: o.contentType,
+        public: o.public === true,
+        ...o.userMeta ? { userMeta: o.userMeta } : {}
+      });
+    },
+    async getObject(key) {
+      return store.get(key)?.bytes ?? null;
+    },
+    async deleteObject(key) {
+      store.delete(key);
+    },
+    async headObject(key) {
+      const e = store.get(key);
+      if (!e) return null;
+      return {
+        size: e.bytes.byteLength,
+        contentType: e.contentType,
+        ...e.userMeta ? { userMeta: e.userMeta } : {}
+      };
+    },
+    async objectUrl(key, o) {
+      const e = store.get(key);
+      if (e?.public) return `${base}/${key}`;
+      return `${base}/${key}?sig=memory&expires=${o?.expiresInSeconds ?? 900}`;
+    },
+    async putUrl(key, o) {
+      return `${base}/${key}?upload=memory&ct=${encodeURIComponent(o.contentType)}`;
+    },
+    async listPrefix(prefix) {
+      const out = [];
+      for (const [key, e] of store) {
+        if (!key.startsWith(prefix)) continue;
+        out.push({
+          key,
+          meta: { size: e.bytes.byteLength, contentType: e.contentType, ...e.userMeta ? { userMeta: e.userMeta } : {} }
+        });
+      }
+      return out;
+    }
+  };
+}
+
+// src/with-shape/blobs/import-external.ts
+function defaultDeriveRecordId(key) {
+  const parts = key.split("/");
+  return parts.length >= 2 ? parts[parts.length - 2] ?? null : null;
+}
+async function importExternalObjects(args) {
+  const { collection, objectStore, field } = args;
+  const opts = args.options ?? {};
+  const derive = opts.deriveRecordId ?? defaultDeriveRecordId;
+  const makeRecord = opts.makeRecord ?? ((id) => ({ id }));
+  const objects = await objectStore.listPrefix(opts.prefix ?? "");
+  const recordIds = [];
+  let imported = 0;
+  let skipped = 0;
+  for (const { key, meta } of objects) {
+    const recordId = derive(key);
+    if (!recordId) {
+      skipped++;
+      continue;
+    }
+    if (await collection.get(recordId) == null) {
+      await collection.put(recordId, makeRecord(recordId));
+    }
+    await collection.blob(recordId).adoptExternal(field, {
+      key,
+      ...meta.size !== void 0 ? { size: meta.size } : {},
+      ...meta.contentType ? { contentType: meta.contentType } : {}
+    });
+    recordIds.push(recordId);
+    imported++;
+  }
+  return { imported, skipped, recordIds };
+}
+
+export {
+  memoryObjectProjection,
+  importExternalObjects
+};
+//# sourceMappingURL=chunk-4Q6HSHHL.js.map

package/dist/chunk-4Q6HSHHL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-shape/blobs/object-projection.ts","../src/with-shape/blobs/import-external.ts"],"sourcesContent":["/**\n * `ObjectProjection` — the capability an `as-*` projection store implements to\n * hold blob bytes as native, directly-consumable objects (e.g. servable S3\n * objects) rather than the encrypted-envelope chunks a `NoydbStore` holds.\n *\n * This is the shared seam behind **direct-serve blobs** and the\n * **debug raw-object path**: \"write these bytes as one real object and\n * give me a URL to it.\" See the as-aws-s3 design spec.\n *\n * Unlike `NoydbStore` (ciphertext in / ciphertext out), an `ObjectProjection`\n * sees **raw bytes** — it is `as-*`, not `to-*`, and lives **outside** the\n * zero-knowledge guarantee. Wiring it up is a deliberate, per-field opt-in.\n */\n\n/** Metadata about a stored object, without its body. */\nexport interface ObjectMeta {\n  readonly size: number\n  readonly contentType?: string\n  readonly etag?: string\n  readonly lastModified?: string\n  /** S3-style user metadata (`x-amz-meta-*`). Small; see the design's\n   *  plain / encrypted / opaque-token modes. */\n  readonly userMeta?: Record<string, string>\n}\n\nexport interface PutObjectOptions {\n  readonly contentType: string\n  /** World-readable object (CDN origin) vs private (presigned-only). Default false. */\n  readonly public?: boolean\n  /** User metadata mirrored onto the object (the \"secondary store\"). */\n  readonly userMeta?: Record<string, string>\n}\n\nexport interface ObjectUrlOptions {\n  /** TTL for a presigned URL (ignored for a public object). */\n  readonly expiresInSeconds?: number\n}\n\nexport interface PutUrlOptions {\n  readonly contentType: string\n  readonly expiresInSeconds?: number\n}\n\n/** One entry returned by {@link ObjectProjection.listPrefix}. */\nexport interface ObjectListEntry {\n  readonly key: string\n  readonly meta: ObjectMeta\n}\n\nexport interface ObjectProjection {\n  /** Diagnostic name (e.g. `'aws-s3'`, `'memory'`). */\n  readonly name?: string\n  /** Write raw bytes as a single native object with a real content type. */\n  putObject(key: string, bytes: Uint8Array, opts: PutObjectOptions): Promise<void>\n  /** Read the raw bytes back; `null` if absent. */\n  getObject(key: string): Promise<Uint8Array | null>\n  /** Delete the object. Idempotent — absent is not an error. */\n  deleteObject(key: string): Promise<void>\n  /** Object metadata without the body; `null` if absent. */\n  headObject(key: string): Promise<ObjectMeta | null>\n  /** A URL to GET the object — presigned (time-limited) or stable public. */\n  objectUrl(key: string, opts?: ObjectUrlOptions): Promise<string>\n  /** A presigned URL the client PUTs bytes to directly (large-file upload,\n   *  bytes bypass the hub). */\n  putUrl(key: string, opts: PutUrlOptions): Promise<string>\n  /** List objects under a key prefix — for import / reconcile. */\n  listPrefix(prefix: string): Promise<ObjectListEntry[]>\n}\n\n/**\n * In-memory {@link ObjectProjection} — a reference implementation for tests,\n * local development, and the hub's blob-wiring conformance. Holds bytes in a\n * `Map`; URLs are synthetic (`memory://…`). Not for production.\n */\nexport function memoryObjectProjection(opts: { baseUrl?: string } = {}): ObjectProjection {\n  const base = opts.baseUrl ?? 'memory://objects'\n  const store = new Map<\n    string,\n    { bytes: Uint8Array; contentType: string; userMeta?: Record<string, string>; public: boolean }\n  >()\n  return {\n    name: 'memory',\n    async putObject(key, bytes, o) {\n      store.set(key, {\n        bytes,\n        contentType: o.contentType,\n        public: o.public === true,\n        ...(o.userMeta ? { userMeta: o.userMeta } : {}),\n      })\n    },\n    async getObject(key) {\n      return store.get(key)?.bytes ?? null\n    },\n    async deleteObject(key) {\n      store.delete(key)\n    },\n    async headObject(key) {\n      const e = store.get(key)\n      if (!e) return null\n      return {\n        size: e.bytes.byteLength,\n        contentType: e.contentType,\n        ...(e.userMeta ? { userMeta: e.userMeta } : {}),\n      }\n    },\n    async objectUrl(key, o) {\n      const e = store.get(key)\n      if (e?.public) return `${base}/${key}`\n      return `${base}/${key}?sig=memory&expires=${o?.expiresInSeconds ?? 900}`\n    },\n    async putUrl(key, o) {\n      return `${base}/${key}?upload=memory&ct=${encodeURIComponent(o.contentType)}`\n    },\n    async listPrefix(prefix) {\n      const out: ObjectListEntry[] = []\n      for (const [key, e] of store) {\n        if (!key.startsWith(prefix)) continue\n        out.push({\n          key,\n          meta: { size: e.bytes.byteLength, contentType: e.contentType, ...(e.userMeta ? { userMeta: e.userMeta } : {}) },\n        })\n      }\n      return out\n    },\n  }\n}\n","/**\n * Import / bootstrap (reverse projection) — walk an existing bucket/prefix in an\n * {@link ObjectProjection} and build a master collection where each record\n * anchors one object, restoring the record-anchoring invariant for objects that\n * pre-date noy-db (or were written by another system). See as-aws-s3 §3.8.\n *\n * Idempotent: re-running re-adopts the same objects under the same record ids.\n */\nimport type { ObjectProjection } from './object-projection.js'\n\n/** Minimal collection surface this utility needs (avoids importing the kernel). */\nexport interface ImportableCollection {\n  get(id: string): Promise<unknown>\n  put(id: string, record: unknown): Promise<unknown>\n  blob(id: string): {\n    adoptExternal(\n      slot: string,\n      ref: { key: string; size?: number; contentType?: string; public?: boolean; backlink?: string },\n    ): Promise<void>\n  }\n}\n\nexport interface ImportExternalOptions {\n  /** Only consider objects under this key prefix. Default `''` (all). */\n  prefix?: string\n  /**\n   * Derive the record id for an object key. Default: the path segment before\n   * the last — i.e. `{collection}/{recordId}/{field}` → `recordId`. Return\n   * `null` to skip the object.\n   */\n  deriveRecordId?: (key: string) => string | null\n  /** Build the anchor record for a new id. Default `{ id }`. */\n  makeRecord?: (id: string) => unknown\n}\n\nexport interface ImportExternalResult {\n  imported: number\n  skipped: number\n  recordIds: string[]\n}\n\nfunction defaultDeriveRecordId(key: string): string | null {\n  const parts = key.split('/')\n  return parts.length >= 2 ? (parts[parts.length - 2] ?? null) : null\n}\n\n/**\n * Build/extend `collection` from the objects under `prefix` in `objectStore`,\n * adopting each as the `field` blob on its derived record.\n */\nexport async function importExternalObjects(args: {\n  collection: ImportableCollection\n  objectStore: ObjectProjection\n  field: string\n  options?: ImportExternalOptions\n}): Promise<ImportExternalResult> {\n  const { collection, objectStore, field } = args\n  const opts = args.options ?? {}\n  const derive = opts.deriveRecordId ?? defaultDeriveRecordId\n  const makeRecord = opts.makeRecord ?? ((id: string) => ({ id }))\n\n  const objects = await objectStore.listPrefix(opts.prefix ?? '')\n  const recordIds: string[] = []\n  let imported = 0\n  let skipped = 0\n\n  for (const { key, meta } of objects) {\n    const recordId = derive(key)\n    if (!recordId) {\n      skipped++\n      continue\n    }\n    if ((await collection.get(recordId)) == null) {\n      await collection.put(recordId, makeRecord(recordId))\n    }\n    await collection.blob(recordId).adoptExternal(field, {\n      key,\n      ...(meta.size !== undefined ? { size: meta.size } : {}),\n      ...(meta.contentType ? { contentType: meta.contentType } : {}),\n    })\n    recordIds.push(recordId)\n    imported++\n  }\n\n  return { imported, skipped, recordIds }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-5I35DOHK.js

@@ -0,0 +1,94 @@
+import {
+  sha256Hex
+} from "./chunk-3OPY6MK2.js";
+
+// src/with-shape/persisted-schemas/canonicalize.ts
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const parts = keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]));
+  return "{" + parts.join(",") + "}";
+}
+
+// src/with-shape/persisted-schemas/derive.ts
+function isZodSchema(value) {
+  if (value === null || typeof value !== "object") return false;
+  const std = value["~standard"];
+  if (std && typeof std === "object" && std.vendor === "zod") return true;
+  const def = value._def;
+  if (!def || typeof def !== "object") return false;
+  return typeof def.typeName === "string" && def.typeName.startsWith("Zod");
+}
+function detectKind(validator) {
+  if (isZodSchema(validator)) return "Zod";
+  return "Unknown";
+}
+function isZod4Schema(value) {
+  if (value === null || typeof value !== "object") return false;
+  return "_zod" in value;
+}
+async function loadZodToJsonSchemaConverter() {
+  try {
+    const mod = await import("zod-to-json-schema");
+    if (!mod.zodToJsonSchema) {
+      throw new Error("zod-to-json-schema export missing");
+    }
+    return mod.zodToJsonSchema;
+  } catch (err) {
+    throw new Error(
+      `persistJsonSchema requires the optional peer-dep \`zod-to-json-schema\`. Install it: \`pnpm add zod-to-json-schema\` (or npm/yarn equivalent). Original error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function loadZodV4Converter() {
+  try {
+    const mod = await import("./zod-HAJM7LMS.js");
+    if (typeof mod.toJSONSchema !== "function") {
+      throw new Error("zod.toJSONSchema not available (zod v4 required)");
+    }
+    return mod.toJSONSchema;
+  } catch (err) {
+    throw new Error(
+      `persistJsonSchema with a Zod v4 schema requires zod@4 with toJSONSchema. Original error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function derivePersistedSchema(validator) {
+  const kind = detectKind(validator);
+  const derivedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (kind === "Zod") {
+    let jsonSchema;
+    if (isZod4Schema(validator)) {
+      const convert = await loadZodV4Converter();
+      jsonSchema = convert(validator);
+    } else {
+      const convert = await loadZodToJsonSchemaConverter();
+      jsonSchema = convert(validator);
+    }
+    const canonical = canonicalize(jsonSchema);
+    const hash = await sha256Hex(new TextEncoder().encode(canonical));
+    return { _noydb_schema: 1, kind, jsonSchema, hash, derivedAt };
+  }
+  return {
+    _noydb_schema: 1,
+    kind,
+    jsonSchema: null,
+    hash: null,
+    reason: `derivation not yet supported for kind=${kind} (v0 supports Zod only)`,
+    derivedAt
+  };
+}
+
+export {
+  canonicalize,
+  isZodSchema,
+  isZod4Schema,
+  derivePersistedSchema
+};
+//# sourceMappingURL=chunk-5I35DOHK.js.map

package/dist/chunk-5I35DOHK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-shape/persisted-schemas/canonicalize.ts","../src/with-shape/persisted-schemas/derive.ts"],"sourcesContent":["/**\n * Deterministic JSON serializer: sorts object keys lexicographically at every\n * depth so structurally-equivalent objects produce identical strings. Array\n * order is preserved (arrays are semantically ordered).\n *\n * Used by {@link sha256Hex} to fingerprint a derived JSON Schema for\n * hash-based skip on persisted-schema writes.\n *\n * @module\n */\n\nexport function canonicalize(value: unknown): string {\n  if (value === null || typeof value !== 'object') {\n    return JSON.stringify(value)\n  }\n  if (Array.isArray(value)) {\n    return '[' + value.map(canonicalize).join(',') + ']'\n  }\n  const obj = value as Record<string, unknown>\n  const keys = Object.keys(obj).sort()\n  const parts = keys.map((k) => JSON.stringify(k) + ':' + canonicalize(obj[k]))\n  return '{' + parts.join(',') + '}'\n}\n","/**\n * Derive a {@link PersistedSchemaEnvelope} from a Standard Schema v1\n * validator. Supports zod 3 (via the optional `zod-to-json-schema` peer-dep)\n * and zod 4 (via its native `z.toJSONSchema()`); both are loaded lazily so\n * hub never statically imports zod. Other validator families write a stub\n * envelope flagging the kind.\n *\n * @see docs/superpowers/specs/2026-05-22-schema-dump-design.md\n *\n * @module\n */\n\nimport { canonicalize } from './canonicalize.js'\nimport { sha256Hex } from '../../kernel/enclave/index.js'\nimport type { PersistedSchemaEnvelope, PersistedSchemaKind } from './types.js'\n\n/**\n * Heuristic Zod detection — uses the Standard Schema v1 `~standard.vendor`\n * property (present in Zod v3.23+ and Zod v4+). Falls back to the\n * `_def.typeName` heuristic for older Zod v3 builds that predate Standard\n * Schema support.\n */\nexport function isZodSchema(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false\n  // Standard Schema v1 vendor tag — most reliable across Zod majors\n  const std = (value as { '~standard'?: { vendor?: unknown } })['~standard']\n  if (std && typeof std === 'object' && (std as { vendor?: unknown }).vendor === 'zod') return true\n  // Zod v3 fallback: _def.typeName starts with 'Zod' (e.g. 'ZodObject')\n  const def = (value as { _def?: { typeName?: unknown } })._def\n  if (!def || typeof def !== 'object') return false\n  return typeof (def as { typeName?: unknown }).typeName === 'string'\n    && ((def as { typeName: string }).typeName).startsWith('Zod')\n}\n\nfunction detectKind(validator: unknown): PersistedSchemaKind {\n  if (isZodSchema(validator)) return 'Zod'\n  return 'Unknown'\n}\n\n/**\n * Returns `true` when the validator was created with the Zod v4 native API\n * (i.e. `import { z } from 'zod'` where zod resolves to v4). Zod v4 native\n * schemas carry a `_zod` property whereas Zod v3 schemas (and the v3-compat\n * shim shipped inside zod@4 at `zod/v3`) use `_def.typeName`.\n *\n * Kept duck-typed so hub never statically imports zod.\n */\nexport function isZod4Schema(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false\n  return '_zod' in value\n}\n\n/**\n * Lazy-require `zod-to-json-schema`. Returns the converter, or throws a\n * clear error if the peer-dep isn't installed.\n */\nasync function loadZodToJsonSchemaConverter(): Promise<(s: unknown) => object> {\n  try {\n    const mod = (await import('zod-to-json-schema')) as { zodToJsonSchema?: (s: unknown) => object }\n    if (!mod.zodToJsonSchema) {\n      throw new Error('zod-to-json-schema export missing')\n    }\n    return mod.zodToJsonSchema\n  } catch (err) {\n    throw new Error(\n      'persistJsonSchema requires the optional peer-dep `zod-to-json-schema`. '\n      + 'Install it: `pnpm add zod-to-json-schema` (or npm/yarn equivalent). '\n      + `Original error: ${err instanceof Error ? err.message : String(err)}`,\n    )\n  }\n}\n\n/**\n * Lazy-require Zod v4's built-in `toJSONSchema`. Used when the validator is a\n * Zod v4 native schema and `zod-to-json-schema` is absent or cannot handle it.\n * This is a dynamic import so it does not add a static zod dependency to hub.\n */\nasync function loadZodV4Converter(): Promise<(s: unknown) => object> {\n  try {\n    const mod = (await import('zod')) as { toJSONSchema?: (s: unknown) => object }\n    if (typeof mod.toJSONSchema !== 'function') {\n      throw new Error('zod.toJSONSchema not available (zod v4 required)')\n    }\n    return mod.toJSONSchema\n  } catch (err) {\n    throw new Error(\n      'persistJsonSchema with a Zod v4 schema requires zod@4 with toJSONSchema. '\n      + `Original error: ${err instanceof Error ? err.message : String(err)}`,\n    )\n  }\n}\n\nexport async function derivePersistedSchema(\n  validator: unknown,\n): Promise<PersistedSchemaEnvelope> {\n  const kind = detectKind(validator)\n  const derivedAt = new Date().toISOString()\n\n  if (kind === 'Zod') {\n    let jsonSchema: object\n\n    if (isZod4Schema(validator)) {\n      // Zod v4 native schemas: use zod's built-in toJSONSchema (available in\n      // zod@4) because zod-to-json-schema@3.x parses _def.typeName which is\n      // absent in native v4 schemas.\n      const convert = await loadZodV4Converter()\n      jsonSchema = convert(validator)\n    } else {\n      // Zod v3 schemas (or v3-compat shim): use the optional peer-dep\n      // zod-to-json-schema for backward compatibility.\n      const convert = await loadZodToJsonSchemaConverter()\n      jsonSchema = convert(validator)\n    }\n\n    const canonical = canonicalize(jsonSchema)\n    const hash = await sha256Hex(new TextEncoder().encode(canonical))\n    return { _noydb_schema: 1, kind, jsonSchema, hash, derivedAt }\n  }\n\n  return {\n    _noydb_schema: 1,\n    kind,\n    jsonSchema: null,\n    hash: null,\n    reason: `derivation not yet supported for kind=${kind} (v0 supports Zod only)`,\n    derivedAt,\n  }\n}\n"],"mappings":";;;;;AAWO,SAAS,aAAa,OAAwB;AACnD,MAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;AAC/C,WAAO,KAAK,UAAU,KAAK;AAAA,EAC7B;AACA,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,MAAM,MAAM,IAAI,YAAY,EAAE,KAAK,GAAG,IAAI;AAAA,EACnD;AACA,QAAM,MAAM;AACZ,QAAM,OAAO,OAAO,KAAK,GAAG,EAAE,KAAK;AACnC,QAAM,QAAQ,KAAK,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,IAAI,MAAM,aAAa,IAAI,CAAC,CAAC,CAAC;AAC5E,SAAO,MAAM,MAAM,KAAK,GAAG,IAAI;AACjC;;;ACAO,SAAS,YAAY,OAAyB;AACnD,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AAExD,QAAM,MAAO,MAAiD,WAAW;AACzE,MAAI,OAAO,OAAO,QAAQ,YAAa,IAA6B,WAAW,MAAO,QAAO;AAE7F,QAAM,MAAO,MAA4C;AACzD,MAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO;AAC5C,SAAO,OAAQ,IAA+B,aAAa,YACpD,IAA6B,SAAU,WAAW,KAAK;AAChE;AAEA,SAAS,WAAW,WAAyC;AAC3D,MAAI,YAAY,SAAS,EAAG,QAAO;AACnC,SAAO;AACT;AAUO,SAAS,aAAa,OAAyB;AACpD,MAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AACxD,SAAO,UAAU;AACnB;AAMA,eAAe,+BAAgE;AAC7E,MAAI;AACF,UAAM,MAAO,MAAM,OAAO,oBAAoB;AAC9C,QAAI,CAAC,IAAI,iBAAiB;AACxB,YAAM,IAAI,MAAM,mCAAmC;AAAA,IACrD;AACA,WAAO,IAAI;AAAA,EACb,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,kKAEqB,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IACvE;AAAA,EACF;AACF;AAOA,eAAe,qBAAsD;AACnE,MAAI;AACF,UAAM,MAAO,MAAM,OAAO,mBAAK;AAC/B,QAAI,OAAO,IAAI,iBAAiB,YAAY;AAC1C,YAAM,IAAI,MAAM,kDAAkD;AAAA,IACpE;AACA,WAAO,IAAI;AAAA,EACb,SAAS,KAAK;AACZ,UAAM,IAAI;AAAA,MACR,4FACqB,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IACvE;AAAA,EACF;AACF;AAEA,eAAsB,sBACpB,WACkC;AAClC,QAAM,OAAO,WAAW,SAAS;AACjC,QAAM,aAAY,oBAAI,KAAK,GAAE,YAAY;AAEzC,MAAI,SAAS,OAAO;AAClB,QAAI;AAEJ,QAAI,aAAa,SAAS,GAAG;AAI3B,YAAM,UAAU,MAAM,mBAAmB;AACzC,mBAAa,QAAQ,SAAS;AAAA,IAChC,OAAO;AAGL,YAAM,UAAU,MAAM,6BAA6B;AACnD,mBAAa,QAAQ,SAAS;AAAA,IAChC;AAEA,UAAM,YAAY,aAAa,UAAU;AACzC,UAAM,OAAO,MAAM,UAAU,IAAI,YAAY,EAAE,OAAO,SAAS,CAAC;AAChE,WAAO,EAAE,eAAe,GAAG,MAAM,YAAY,MAAM,UAAU;AAAA,EAC/D;AAEA,SAAO;AAAA,IACL,eAAe;AAAA,IACf;AAAA,IACA,YAAY;AAAA,IACZ,MAAM;AAAA,IACN,QAAQ,yCAAyC,IAAI;AAAA,IACrD;AAAA,EACF;AACF;","names":[]}