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

package/dist/vault-diff-B5fYNBL7.d.ts

@@ -0,0 +1,147 @@
+import { V as Vault, cE as DiffEntry } from './index-BzUo1B6n.js';
+
+/**
+ * Vault-level diff orchestrator.
+ *
+ * Compares a live `Vault`'s plaintext state against a candidate state
+ * (another vault, a plain `{ collection: records[] }` map, or a vault
+ * dump JSON) and returns a structured `VaultDiff` plan listing the
+ * records that would be added, modified, or deleted to bring the live
+ * vault into the candidate's shape.
+ *
+ * Builds on two existing record-level helpers:
+ *
+ *   1. `diff(a, b)` from `./history/diff.ts` — emits dot-pathed
+ *      `DiffEntry[]` with `type: 'added' | 'removed' | 'changed'` for
+ *      each changed field of two records. Used here for the
+ *      `fieldDiffs` of every `modified` entry, and (with empty result)
+ *      as the default deep-equal check.
+ *
+ *   2. `Vault.exportStream()` from `./vault.ts` — the canonical
+ *      decrypt-and-stream-records iterator. Used to walk both sides
+ *      when the candidate is itself a `Vault`. ACL-scoped: collections
+ *      the caller can't read silently drop out, the same way every
+ *      other plaintext-emitting export pipeline filters them.
+ *
+ * The new orchestration is the **vault-level** enumeration: bucket
+ * each record id into added (only in candidate), deleted (only in
+ * vault), or modified (in both with field changes); leave the
+ * field-level granularity to the existing `diff()`.
+ *
+ * Use cases:
+ *
+ *   - Import preview (`@noy-db/as-*` `fromString` returns a plan
+ *     whose body is a `VaultDiff`).
+ *   - Backup verification ("does this `.noydb` bundle from yesterday
+ *     match the current vault?").
+ *   - Two-vault reconciliation ("what's different between Office A
+ *     and Office B before we sync?").
+ *   - Test assertions (golden-file testing with one-liner
+ *     `expect(plan.summary).toEqual(...)`).
+ *
+ * @module
+ */
+
+/** Per-record entry shape — added and deleted records carry only the record value. */
+interface VaultDiffEntry<T = unknown> {
+    readonly collection: string;
+    readonly id: string;
+    readonly record: T;
+    /**
+     * Unencrypted envelope metadata for the RECEIVER-side record.
+     * Populated only when `diffVault` is called with `{includeMetadata: true}`.
+     * Default: `undefined` (zero extra reads, no behavior change).
+     *
+     * Populated for `modified` (the CURRENT receiver state, before the candidate
+     * is applied) and `deleted` (the receiver envelope of the record being
+     * removed). `added` entries have no receiver envelope at diff time, so their
+     * `metadata` is always absent.
+     */
+    readonly metadata?: {
+        readonly version: number;
+        readonly timestamp: string;
+        readonly by?: string;
+        readonly source?: string;
+        readonly sourceTs?: string;
+    };
+}
+/** Modified records carry both halves of the diff plus the field-level breakdown. */
+interface VaultDiffModifiedEntry<T = unknown> extends VaultDiffEntry<T> {
+    /** The record as it stands in the live vault. */
+    readonly before: T;
+    /** Top-level keys whose values differ between `before` and `record`. */
+    readonly fieldsChanged: readonly string[];
+    /**
+     * Field-level diff entries from `diff(before, record)`. Reuses the
+     * existing per-record diff helper so consumers can render git-style
+     * `path: from → to` rows without re-walking the records.
+     */
+    readonly fieldDiffs: readonly DiffEntry[];
+}
+interface VaultDiff<T = unknown> {
+    readonly added: readonly VaultDiffEntry<T>[];
+    readonly modified: readonly VaultDiffModifiedEntry<T>[];
+    readonly deleted: readonly VaultDiffEntry<T>[];
+    /** Only populated when `options.includeUnchanged: true`. */
+    readonly unchanged: readonly VaultDiffEntry<T>[] | undefined;
+    readonly summary: {
+        readonly add: number;
+        readonly modify: number;
+        readonly delete: number;
+        readonly total: number;
+    };
+    /**
+     * Format the diff as a human-readable string.
+     *
+     *   - `'count'`   — one line, just the numbers (`12 added · 3 modified · 0 deleted`)
+     *   - `'one-line'` — count plus a single overview line
+     *   - `'full'`    — count + one row per added/modified/deleted record (default)
+     */
+    format(opts?: {
+        detail?: 'count' | 'one-line' | 'full';
+    }): string;
+}
+interface DiffOptions {
+    /** Restrict the diff to a subset of collections. */
+    readonly collections?: readonly string[];
+    /** Field on each record that carries its id. Defaults to `'id'`. */
+    readonly idKey?: string;
+    /** Override the default deep-equal check for "modified vs unchanged". */
+    readonly compareFn?: (a: unknown, b: unknown) => boolean;
+    /** If true, include unchanged records in the diff (off by default to save memory). */
+    readonly includeUnchanged?: boolean;
+    /**
+     * When `true`, each entry in `added`, `modified`, and `deleted` will carry a
+     * `metadata` field with the RECEIVER-side envelope metadata
+     * (`version`, `timestamp`, `by?`, `source?`, `sourceTs?`).
+     *
+     * Off by default — no extra adapter reads, no behavior change for existing callers.
+     */
+    readonly includeMetadata?: boolean;
+}
+/**
+ * Candidate state to diff the vault against:
+ *
+ *   - A `Vault` instance — both sides are walked via `exportStream()`.
+ *   - A `Record<collection, records[]>` map — same shape `as-json.toObject()`
+ *     produces. Useful for diffing parsed file content against the live vault.
+ *   - A `VaultDump` (output of `vault.dump()`) — a JSON string carrying the
+ *     full vault state. Parsed and reduced to the map shape above.
+ */
+type DiffCandidate<T = unknown> = Vault | Record<string, readonly T[]> | string;
+/**
+ * Compute the diff between a live vault and a candidate state.
+ *
+ * Ungated shared import/merge infrastructure: the `as-*` exporters call this
+ * internally from their `fromString`/import merge logic, so it is always
+ * available (not behind `withCargo()`). Only `extractPartition` is a gated
+ * cargo capability.
+ *
+ * Returns a fully buffered `VaultDiff` — no streaming. Memory cost is
+ * O(n + m) in the row count of vault + candidate. For documented
+ * 1K-50K-record vaults this is fine; a streaming variant lands as a
+ * follow-up if a > 100K-record consumer arrives.
+ */
+declare function diffVault<T = unknown>(vault: Vault, candidate: DiffCandidate<T>, options?: DiffOptions): Promise<VaultDiff<T>>;
+
+export { type DiffCandidate as D, type VaultDiff as V, type DiffOptions as a, type VaultDiffEntry as b, type VaultDiffModifiedEntry as c, diffVault as d };

package/dist/with/index.d.ts

@@ -0,0 +1,38 @@
+export { U as Unsubscribe, W as WriteEvent, a as WriteHook, b as WriteHookRegistry } from '../index-B9QdHytu.js';
+import { cF as UnlockedKeyring, cG as ExportFormat } from '../index-BzUo1B6n.js';
+export { cH as BusHandler, cI as GateDeleteEvent, cJ as GateEventMap, cK as GateHandler, cL as GatePoint, cM as GatePutEvent, cN as LifecycleEventMap, cO as LifecyclePoint, cP as ServiceBus, cQ as SubsystemBus } from '../index-BzUo1B6n.js';
+import '../subject-index-O75wKshW.js';
+import '../describe-aBkJR2sd.js';
+import '@noy-db/attestation';
+
+/**
+ * Authorize an `@noy-db/as-*` export against the keyring's `exportCapability`.
+ * Throws `ExportCapabilityError` if the keyring is not authorised.
+ *
+ * - plaintext tier requires a `format`; defaults to empty for every role.
+ * - bundle tier defaults to on for owner/admin, off for others.
+ */
+declare function assertCanExport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): void;
+/**
+ * Authorize an `@noy-db/as-*` import against the keyring's `importCapability`.
+ * Throws `ImportCapabilityError` if the keyring is not authorised.
+ *
+ * - plaintext tier requires a `format`; default-closed for every role.
+ * - bundle tier is default-closed for every role, including owner — import is
+ *   more dangerous than export (corrupts vs leaks).
+ */
+declare function assertCanImport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): void;
+/**
+ * Read-only accessor for the keyring's export capability, with role-based
+ * defaults resolved. Useful for UI affordances (grey out the export button if
+ * no capability) without throwing.
+ */
+declare function canExport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): boolean;
+/**
+ * Read-only accessor for the keyring's import capability. UI affordance —
+ * returns false in every default-closed case (every role with no explicit
+ * `importCapability` grant).
+ */
+declare function canImport(keyring: UnlockedKeyring, tier: 'plaintext' | 'bundle', format?: ExportFormat): boolean;
+
+export { assertCanExport, assertCanImport, canExport, canImport };

package/dist/with/index.js

@@ -0,0 +1,25 @@
+import {
+  ServiceBus,
+  SubsystemBus,
+  WriteHookRegistry,
+  assertCanExport,
+  assertCanImport,
+  canExport,
+  canImport
+} from "../chunk-5R3ERCDH.js";
+import "../chunk-WWGT2MDV.js";
+import "../chunk-ITNUCOXM.js";
+import "../chunk-5O3AOPDT.js";
+import "../chunk-5TDJ56JE.js";
+import "../chunk-ZYUC53LT.js";
+import "../chunk-PZ5AY32C.js";
+export {
+  ServiceBus,
+  SubsystemBus,
+  WriteHookRegistry,
+  assertCanExport,
+  assertCanImport,
+  canExport,
+  canImport
+};
+//# sourceMappingURL=index.js.map

package/dist/with/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{with-materialized-view-BLkQxoQN.d.ts → with-materialized-view-6p0Fk8bL.d.ts}

@@ -1,4 +1,4 @@
-import { aV as MaterializedViewStrategy, aW as MaterializedViewStrategyHandle } from './types-Df28QFKb.js';
+import { cf as MaterializedViewStrategy, cg as MaterializedViewStrategyHandle } from './index-BzUo1B6n.js';
 
 /**
  * Register a materialized view: a declared query whose result is

package/dist/{with-overlayed-view-CRsSEwHR.d.ts → with-overlayed-view-BJ6mXGMd.d.ts}

@@ -1,10 +1,9 @@
-import { aX as OverlayedViewStrategy, a_ as OverlayedViewStrategyHandle } from './types-Df28QFKb.js';
+import { ch as OverlayedViewStrategy, cq as OverlayedViewStrategyHandle } from './index-BzUo1B6n.js';
 
 /**
  * Register a read-shadow overlay: bind an MV-owned base collection to
  * a user-writable overlay so consumers can express operator-editable
- * lifecycles as one declarative block (MV v2 spec § Composition
- * with operator-editable lifecycle).
+ * lifecycles as one declarative block.
  *
  * See docs/superpowers/specs/2026-05-20-dim14-mv-v2-design.md.
  */

package/dist/with-rollup-BvQo3ROo.d.ts

@@ -0,0 +1,47 @@
+import { c2 as DerivationStrategy, cb as DerivationStrategyHandle } from './index-BzUo1B6n.js';
+
+/**
+ * Register a deterministic derivation: one source collection → one or
+ * more typed outputs, computed by the user's `derive` function on
+ * plaintext after DEK unwrap. Outputs are encrypted with the same DEK
+ * as the source and written via the standard `Collection.put` path.
+ *
+ * See docs/superpowers/specs/2026-05-01-dim14-derivation-v1-design.md.
+ */
+declare function withDerivation<TSource extends Record<string, unknown>, TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>>(spec: DerivationStrategy<TSource, TOutputs>): DerivationStrategyHandle;
+
+/**
+ * `withRollup` — aggregate many child records onto a single field of their
+ * parent. The reverse of a join: instead of reading children
+ * on demand, the parent carries a maintained summary.
+ *
+ * ```ts
+ * withRollup<Sale, Buyer>({
+ *   from: 'sales',          // child collection (the trigger)
+ *   key: 'buyerId',         // FK on the child → parent id
+ *   into: 'buyers',         // parent collection
+ *   field: 'revenueByYear', // field on the parent to maintain
+ *   compute: (sales) => groupSumByYear(sales, 'total'),
+ * })
+ * ```
+ *
+ * On every write OR delete of a `from` record, the parent at id `child[key]`
+ * is recomputed: `compute(allChildren where child[key] === parentId)` is
+ * patched onto `parent[field]`. A parent write also recomputes its own
+ * aggregate (so a parent created after its children still fills in). Only the
+ * `field` is touched — the rest of the parent record is never clobbered — and
+ * a value-equality guard suppresses no-op writes. The aggregate is gap-free
+ * with respect to child inserts, updates, and deletes.
+ *
+ * Desugars to a `withDerivation` strategy carrying a `rollup` marker; dispatch
+ * handles it without invoking the executor. Eager-only in this slice.
+ */
+declare function withRollup<TChild extends Record<string, unknown> = Record<string, unknown>, TParent extends Record<string, unknown> = Record<string, unknown>>(config: {
+    from: string;
+    key: keyof TChild & string;
+    into: string;
+    field: keyof TParent & string;
+    compute: (children: TChild[]) => unknown;
+}): DerivationStrategyHandle;
+
+export { withRollup as a, withDerivation as w };

package/dist/withdraw-accessible-FFS46EOD.js

@@ -0,0 +1,22 @@
+import {
+  FROZEN_SNAPSHOTS_COLLECTION,
+  freezeAndDeleteClosure,
+  freezeSnapshotOnly,
+  randomId,
+  withdrawAccessibleData
+} from "./chunk-PSMV73A5.js";
+import "./chunk-HCIPRAGS.js";
+import "./chunk-FISN7WE4.js";
+import "./chunk-SMXWYP24.js";
+import "./chunk-5O3AOPDT.js";
+import "./chunk-5TDJ56JE.js";
+import "./chunk-ZYUC53LT.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  FROZEN_SNAPSHOTS_COLLECTION,
+  freezeAndDeleteClosure,
+  freezeSnapshotOnly,
+  randomId,
+  withdrawAccessibleData
+};
+//# sourceMappingURL=withdraw-accessible-FFS46EOD.js.map

package/dist/withdraw-accessible-FFS46EOD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}