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

package/dist/util/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/util/sanitize-filename.ts"],"sourcesContent":["/**\n * Target-profile aware filename sanitizer.\n *\n * Pure string in / string out. No filesystem access, no I/O. Use this\n * at the boundary where a user-supplied filename meets a storage\n * destination — local FS, ZIP archive, S3 key, URL path, SMB share —\n * to defuse the canonical 14-class footgun before it reaches that\n * destination.\n *\n * ## Threat model\n *\n *   1. Path injection — `..`, NUL bytes, `\\` on POSIX, absolute paths.\n *   2. Windows reserved names — `CON`, `PRN`, `AUX`, `NUL`,\n *      `COM1-9`, `LPT1-9`, with or without an extension.\n *   3. Windows reserved chars — `< > : \" / \\ | ? *` plus ASCII 0-31.\n *   4. Trailing `.` and ` ` on Windows / SMB.\n *   5. Unicode normalization drift — same display, different bytes →\n *      \"two files with the same name\" sync ghosts.\n *   6. Bidi override spoofing — U+202E reversing `harmless.exe.txt`\n *      into `harmless.txt.exe`.\n *   7. URL `+` ambiguity in S3 presigned URLs.\n *   8. ZIP general-purpose-flag bit 11 (UTF-8 filename) optional in\n *      pre-2006 readers.\n *   9-14. Length caps, leading/trailing whitespace + controls,\n *      `.DS_Store`-style hidden noise, etc.\n *\n * ## Always-on transforms (every profile)\n *\n *   - NFC normalize (`String.prototype.normalize('NFC')`).\n *   - Reject NUL — hard fail, not strip. Silent strip enables a\n *     classic truncation bypass (`safe.txt\\0.exe` → `safe.txt`).\n *   - Strip bidi overrides (`U+202A..U+202E`, `U+2066..U+2069`).\n *   - Trim leading/trailing whitespace and ASCII control chars.\n *\n * ## Non-goals (i18n boundary policy, )\n *\n *   - No transliteration.\n *   - No locale-aware slugging.\n *   - No script-specific segmentation.\n *\n * @module\n */\n\nimport { FilenameSanitizationError } from '../errors.js'\n\n/**\n * One of seven storage destinations the sanitizer knows how to defang\n * for. Pick the most restrictive that covers your write site:\n * `'macos-smb'` is the safe default for \"I don't know where these\n * files end up but they're going to a real filesystem somewhere.\"\n */\nexport type FilenameProfile =\n  | 'posix'\n  | 'windows'\n  | 'macos-smb'\n  | 'zip'\n  | 'url-path'\n  | 's3-key'\n  | 'opaque'\n\nexport interface SanitizeFilenameOptions {\n  /** Target-destination profile. */\n  readonly profile: FilenameProfile\n  /**\n   * Override the per-profile length cap. Useful when leaving headroom\n   * for a collision suffix — e.g. `maxBytes: 240` on a `posix` write\n   * site that wants 15 bytes of slack for `-1`, `-2`, …\n   */\n  readonly maxBytes?: number\n  /**\n   * Required when `profile === 'opaque'`. The opaque profile replaces\n   * the entire input with `${opaqueId}.${ext}` (extension preserved\n   * from the input when present).\n   */\n  readonly opaqueId?: string\n}\n\nconst REPLACEMENT = '_'\n\n// Bidi overrides: U+202A LRE, U+202B RLE, U+202C PDF, U+202D LRO,\n// U+202E RLO, U+2066 LRI, U+2067 RLI, U+2068 FSI, U+2069 PDI.\nconst BIDI_OVERRIDES = /[‪-‮⁦-⁩]/g\n\n// Reserved by Windows / NTFS / FAT / SMB.\nconst WINDOWS_RESERVED_CHARS = /[<>:\"/\\\\|?*]/g\n\nconst WINDOWS_RESERVED_NAMES = new Set([\n  'CON', 'PRN', 'AUX', 'NUL',\n  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',\n  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',\n])\n\n// macOS legacy hidden-noise files. Match the full name.\nconst MAC_HIDDEN_NOISE = /^(?:\\.DS_Store|\\.localized|\\.fseventsd|\\._.+)$/i\n\n// RFC 3986 unreserved set.\nconst URL_UNRESERVED = /[A-Za-z0-9\\-._~]/\n\nconst utf8 = new TextEncoder()\n\nfunction isControlCode(cp: number): boolean {\n  return (cp >= 0 && cp <= 0x1f) || cp === 0x7f\n}\n\nfunction stripControlChars(s: string): string {\n  let out = ''\n  for (let i = 0; i < s.length; i++) {\n    out += isControlCode(s.charCodeAt(i)) ? REPLACEMENT : s[i]\n  }\n  return out\n}\n\nfunction trimWhitespaceAndControls(s: string): string {\n  let start = 0\n  let end = s.length\n  while (start < end) {\n    const ch = s[start]!\n    if (!isControlCode(s.charCodeAt(start)) && ch.trim() !== '') break\n    start++\n  }\n  while (end > start) {\n    const ch = s[end - 1]!\n    if (!isControlCode(s.charCodeAt(end - 1)) && ch.trim() !== '') break\n    end--\n  }\n  return s.slice(start, end)\n}\n\n/**\n * Sanitize a filename for a target-destination profile. Pure: same\n * input + options always returns the same output, no I/O.\n *\n * Returns the sanitized name. Throws {@link FilenameSanitizationError}\n * when the input cannot be made safe at all (NUL byte, empty after\n * normalization, missing `opaqueId` for the opaque profile,\n * `..` segment that would fall out of any reasonable target).\n */\nexport function sanitizeFilename(name: string, opts: SanitizeFilenameOptions): string {\n  if (typeof name !== 'string') {\n    throw new FilenameSanitizationError('input must be a string')\n  }\n  if (name.includes('\\0')) {\n    throw new FilenameSanitizationError('NUL byte in filename')\n  }\n\n  let s = name.normalize('NFC').replace(BIDI_OVERRIDES, '')\n\n  if (opts.profile === 'opaque') {\n    return applyOpaque(s, opts)\n  }\n\n  s = trimWhitespaceAndControls(s)\n\n  switch (opts.profile) {\n    case 'posix':     return cap(applyPosix(s),     opts.maxBytes ?? 255,  'utf8')\n    case 'windows':   return cap(applyWindows(s),   opts.maxBytes ?? 255,  'utf16')\n    case 'macos-smb': return cap(applyMacosSmb(s),  opts.maxBytes ?? 240,  'utf8')\n    case 'zip':       return cap(applyZip(s),       opts.maxBytes ?? 255,  'utf8')\n    case 'url-path':  return cap(applyUrlPath(s),   opts.maxBytes ?? 1024, 'bytes-pre-encode')\n    case 's3-key':    return cap(applyS3Key(s),     opts.maxBytes ?? 1024, 'utf8')\n  }\n}\n\n// ─── Profile implementations ────────────────────────────────────────────\n\nfunction applyPosix(s: string): string {\n  // POSIX is permissive; only `/` and NUL are off-limits.\n  const cleaned = s.replace(/\\//g, REPLACEMENT)\n  return rejectDotSegments(cleaned)\n}\n\nfunction applyWindows(s: string): string {\n  let cleaned = s.replace(WINDOWS_RESERVED_CHARS, REPLACEMENT)\n  cleaned = stripControlChars(cleaned)\n  // Trailing space/dot are stripped by Win32 path resolution.\n  cleaned = cleaned.replace(/[. ]+$/g, '')\n  cleaned = rejectDotSegments(cleaned)\n  return avoidWindowsReservedName(cleaned)\n}\n\nfunction applyMacosSmb(s: string): string {\n  let cleaned = applyWindows(s)\n  if (MAC_HIDDEN_NOISE.test(cleaned)) {\n    cleaned = REPLACEMENT + cleaned\n  }\n  return cleaned\n}\n\nfunction applyZip(s: string): string {\n  let cleaned = s.replace(/^\\/+/, '')\n  cleaned = rejectDotSegments(cleaned)\n  return stripControlChars(cleaned)\n}\n\nfunction applyUrlPath(s: string): string {\n  // RFC 3986 percent-encoding for path segment. Keep `unreserved`,\n  // encode everything else. `+` is encoded as `%2B` because S3 and\n  // legacy servers treat raw `+` as space ambiguously.\n  let out = ''\n  for (const ch of s) {\n    if (URL_UNRESERVED.test(ch)) { out += ch; continue }\n    const bytes = utf8.encode(ch)\n    for (const b of bytes) {\n      out += '%' + b.toString(16).toUpperCase().padStart(2, '0')\n    }\n  }\n  return out\n}\n\nfunction applyS3Key(s: string): string {\n  // Strip leading slashes BEFORE percent-encoding — once `/` is\n  // encoded to `%2F` the leading-slash regex no longer matches.\n  return applyUrlPath(s.replace(/^\\/+/, ''))\n}\n\nfunction applyOpaque(s: string, opts: SanitizeFilenameOptions): string {\n  if (!opts.opaqueId) {\n    throw new FilenameSanitizationError('opaque profile requires opaqueId')\n  }\n  // Preserve a \"safe-looking\" extension only — alphanumeric, ≤16 bytes.\n  const dot = s.lastIndexOf('.')\n  if (dot > 0 && dot < s.length - 1) {\n    const ext = s.slice(dot + 1)\n    if (/^[A-Za-z0-9]{1,16}$/.test(ext)) {\n      return `${opts.opaqueId}.${ext.toLowerCase()}`\n    }\n  }\n  return opts.opaqueId\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────\n\nfunction rejectDotSegments(s: string): string {\n  if (s === '.' || s === '..' || s.split(/[/\\\\]/).some((seg) => seg === '..')) {\n    throw new FilenameSanitizationError('path traversal segment in filename')\n  }\n  if (s.length === 0) {\n    throw new FilenameSanitizationError('empty filename after sanitization')\n  }\n  return s\n}\n\nfunction avoidWindowsReservedName(s: string): string {\n  const dot = s.indexOf('.')\n  const base = dot === -1 ? s : s.slice(0, dot)\n  if (WINDOWS_RESERVED_NAMES.has(base.toUpperCase())) {\n    return REPLACEMENT + s\n  }\n  return s\n}\n\ntype LengthUnit = 'utf8' | 'utf16' | 'bytes-pre-encode'\n\nfunction cap(s: string, max: number, unit: LengthUnit): string {\n  if (max <= 0) {\n    throw new FilenameSanitizationError('maxBytes must be positive')\n  }\n  if (unit === 'utf16') {\n    if (s.length <= max) return s\n    return s.slice(0, max)\n  }\n  if (unit === 'bytes-pre-encode') {\n    if (utf8.encode(s).byteLength <= max) return s\n    return truncateToByteCap(s, max)\n  }\n  if (utf8.encode(s).byteLength <= max) return s\n  return truncateToByteCap(s, max)\n}\n\nfunction truncateToByteCap(s: string, max: number): string {\n  // Walk by code points so we never split a multi-byte sequence in\n  // the middle. Whole-grapheme handling (ZWJ-joined emoji) is a\n  // documented non-goal; we only protect against UTF-8 boundary\n  // splits here.\n  let out = ''\n  let used = 0\n  for (const cp of s) {\n    const n = utf8.encode(cp).byteLength\n    if (used + n > max) break\n    out += cp\n    used += n\n  }\n  if (out.length === 0) {\n    throw new FilenameSanitizationError('maxBytes too small for a single code point')\n  }\n  return out\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/kernel/util/sanitize-filename.ts"],"sourcesContent":["/**\n * Target-profile aware filename sanitizer.\n *\n * Pure string in / string out. No filesystem access, no I/O. Use this\n * at the boundary where a user-supplied filename meets a storage\n * destination — local FS, ZIP archive, S3 key, URL path, SMB share —\n * to defuse the canonical 14-class footgun before it reaches that\n * destination.\n *\n * ## Threat model\n *\n *   1. Path injection — `..`, NUL bytes, `\\` on POSIX, absolute paths.\n *   2. Windows reserved names — `CON`, `PRN`, `AUX`, `NUL`,\n *      `COM1-9`, `LPT1-9`, with or without an extension.\n *   3. Windows reserved chars — `< > : \" / \\ | ? *` plus ASCII 0-31.\n *   4. Trailing `.` and ` ` on Windows / SMB.\n *   5. Unicode normalization drift — same display, different bytes →\n *      \"two files with the same name\" sync ghosts.\n *   6. Bidi override spoofing — U+202E reversing `harmless.exe.txt`\n *      into `harmless.txt.exe`.\n *   7. URL `+` ambiguity in S3 presigned URLs.\n *   8. ZIP general-purpose-flag bit 11 (UTF-8 filename) optional in\n *      pre-2006 readers.\n *   9-14. Length caps, leading/trailing whitespace + controls,\n *      `.DS_Store`-style hidden noise, etc.\n *\n * ## Always-on transforms (every profile)\n *\n *   - NFC normalize (`String.prototype.normalize('NFC')`).\n *   - Reject NUL — hard fail, not strip. Silent strip enables a\n *     classic truncation bypass (`safe.txt\\0.exe` → `safe.txt`).\n *   - Strip bidi overrides (`U+202A..U+202E`, `U+2066..U+2069`).\n *   - Trim leading/trailing whitespace and ASCII control chars.\n *\n * ## Non-goals (i18n boundary policy, )\n *\n *   - No transliteration.\n *   - No locale-aware slugging.\n *   - No script-specific segmentation.\n *\n * @module\n */\n\nimport { FilenameSanitizationError } from '../errors.js'\n\n/**\n * One of seven storage destinations the sanitizer knows how to defang\n * for. Pick the most restrictive that covers your write site:\n * `'macos-smb'` is the safe default for \"I don't know where these\n * files end up but they're going to a real filesystem somewhere.\"\n */\nexport type FilenameProfile =\n  | 'posix'\n  | 'windows'\n  | 'macos-smb'\n  | 'zip'\n  | 'url-path'\n  | 's3-key'\n  | 'opaque'\n\nexport interface SanitizeFilenameOptions {\n  /** Target-destination profile. */\n  readonly profile: FilenameProfile\n  /**\n   * Override the per-profile length cap. Useful when leaving headroom\n   * for a collision suffix — e.g. `maxBytes: 240` on a `posix` write\n   * site that wants 15 bytes of slack for `-1`, `-2`, …\n   */\n  readonly maxBytes?: number\n  /**\n   * Required when `profile === 'opaque'`. The opaque profile replaces\n   * the entire input with `${opaqueId}.${ext}` (extension preserved\n   * from the input when present).\n   */\n  readonly opaqueId?: string\n}\n\nconst REPLACEMENT = '_'\n\n// Bidi overrides: U+202A LRE, U+202B RLE, U+202C PDF, U+202D LRO,\n// U+202E RLO, U+2066 LRI, U+2067 RLI, U+2068 FSI, U+2069 PDI.\nconst BIDI_OVERRIDES = /[‪-‮⁦-⁩]/g\n\n// Reserved by Windows / NTFS / FAT / SMB.\nconst WINDOWS_RESERVED_CHARS = /[<>:\"/\\\\|?*]/g\n\nconst WINDOWS_RESERVED_NAMES = new Set([\n  'CON', 'PRN', 'AUX', 'NUL',\n  'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',\n  'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',\n])\n\n// macOS legacy hidden-noise files. Match the full name.\nconst MAC_HIDDEN_NOISE = /^(?:\\.DS_Store|\\.localized|\\.fseventsd|\\._.+)$/i\n\n// RFC 3986 unreserved set.\nconst URL_UNRESERVED = /[A-Za-z0-9\\-._~]/\n\nconst utf8 = new TextEncoder()\n\nfunction isControlCode(cp: number): boolean {\n  return (cp >= 0 && cp <= 0x1f) || cp === 0x7f\n}\n\nfunction stripControlChars(s: string): string {\n  let out = ''\n  for (let i = 0; i < s.length; i++) {\n    out += isControlCode(s.charCodeAt(i)) ? REPLACEMENT : s[i]\n  }\n  return out\n}\n\nfunction trimWhitespaceAndControls(s: string): string {\n  let start = 0\n  let end = s.length\n  while (start < end) {\n    const ch = s[start]!\n    if (!isControlCode(s.charCodeAt(start)) && ch.trim() !== '') break\n    start++\n  }\n  while (end > start) {\n    const ch = s[end - 1]!\n    if (!isControlCode(s.charCodeAt(end - 1)) && ch.trim() !== '') break\n    end--\n  }\n  return s.slice(start, end)\n}\n\n/**\n * Sanitize a filename for a target-destination profile. Pure: same\n * input + options always returns the same output, no I/O.\n *\n * Returns the sanitized name. Throws {@link FilenameSanitizationError}\n * when the input cannot be made safe at all (NUL byte, empty after\n * normalization, missing `opaqueId` for the opaque profile,\n * `..` segment that would fall out of any reasonable target).\n */\nexport function sanitizeFilename(name: string, opts: SanitizeFilenameOptions): string {\n  if (typeof name !== 'string') {\n    throw new FilenameSanitizationError('input must be a string')\n  }\n  if (name.includes('\\0')) {\n    throw new FilenameSanitizationError('NUL byte in filename')\n  }\n\n  let s = name.normalize('NFC').replace(BIDI_OVERRIDES, '')\n\n  if (opts.profile === 'opaque') {\n    return applyOpaque(s, opts)\n  }\n\n  s = trimWhitespaceAndControls(s)\n\n  switch (opts.profile) {\n    case 'posix':     return cap(applyPosix(s),     opts.maxBytes ?? 255,  'utf8')\n    case 'windows':   return cap(applyWindows(s),   opts.maxBytes ?? 255,  'utf16')\n    case 'macos-smb': return cap(applyMacosSmb(s),  opts.maxBytes ?? 240,  'utf8')\n    case 'zip':       return cap(applyZip(s),       opts.maxBytes ?? 255,  'utf8')\n    case 'url-path':  return cap(applyUrlPath(s),   opts.maxBytes ?? 1024, 'bytes-pre-encode')\n    case 's3-key':    return cap(applyS3Key(s),     opts.maxBytes ?? 1024, 'utf8')\n  }\n}\n\n// ─── Profile implementations ────────────────────────────────────────────\n\nfunction applyPosix(s: string): string {\n  // POSIX is permissive; only `/` and NUL are off-limits.\n  const cleaned = s.replace(/\\//g, REPLACEMENT)\n  return rejectDotSegments(cleaned)\n}\n\nfunction applyWindows(s: string): string {\n  let cleaned = s.replace(WINDOWS_RESERVED_CHARS, REPLACEMENT)\n  cleaned = stripControlChars(cleaned)\n  // Trailing space/dot are stripped by Win32 path resolution.\n  cleaned = cleaned.replace(/[. ]+$/g, '')\n  cleaned = rejectDotSegments(cleaned)\n  return avoidWindowsReservedName(cleaned)\n}\n\nfunction applyMacosSmb(s: string): string {\n  let cleaned = applyWindows(s)\n  if (MAC_HIDDEN_NOISE.test(cleaned)) {\n    cleaned = REPLACEMENT + cleaned\n  }\n  return cleaned\n}\n\nfunction applyZip(s: string): string {\n  let cleaned = s.replace(/^\\/+/, '')\n  cleaned = rejectDotSegments(cleaned)\n  return stripControlChars(cleaned)\n}\n\nfunction applyUrlPath(s: string): string {\n  // RFC 3986 percent-encoding for path segment. Keep `unreserved`,\n  // encode everything else. `+` is encoded as `%2B` because S3 and\n  // legacy servers treat raw `+` as space ambiguously.\n  let out = ''\n  for (const ch of s) {\n    if (URL_UNRESERVED.test(ch)) { out += ch; continue }\n    const bytes = utf8.encode(ch)\n    for (const b of bytes) {\n      out += '%' + b.toString(16).toUpperCase().padStart(2, '0')\n    }\n  }\n  return out\n}\n\nfunction applyS3Key(s: string): string {\n  // Strip leading slashes BEFORE percent-encoding — once `/` is\n  // encoded to `%2F` the leading-slash regex no longer matches.\n  return applyUrlPath(s.replace(/^\\/+/, ''))\n}\n\nfunction applyOpaque(s: string, opts: SanitizeFilenameOptions): string {\n  if (!opts.opaqueId) {\n    throw new FilenameSanitizationError('opaque profile requires opaqueId')\n  }\n  // Preserve a \"safe-looking\" extension only — alphanumeric, ≤16 bytes.\n  const dot = s.lastIndexOf('.')\n  if (dot > 0 && dot < s.length - 1) {\n    const ext = s.slice(dot + 1)\n    if (/^[A-Za-z0-9]{1,16}$/.test(ext)) {\n      return `${opts.opaqueId}.${ext.toLowerCase()}`\n    }\n  }\n  return opts.opaqueId\n}\n\n// ─── Helpers ────────────────────────────────────────────────────────────\n\nfunction rejectDotSegments(s: string): string {\n  if (s === '.' || s === '..' || s.split(/[/\\\\]/).some((seg) => seg === '..')) {\n    throw new FilenameSanitizationError('path traversal segment in filename')\n  }\n  if (s.length === 0) {\n    throw new FilenameSanitizationError('empty filename after sanitization')\n  }\n  return s\n}\n\nfunction avoidWindowsReservedName(s: string): string {\n  const dot = s.indexOf('.')\n  const base = dot === -1 ? s : s.slice(0, dot)\n  if (WINDOWS_RESERVED_NAMES.has(base.toUpperCase())) {\n    return REPLACEMENT + s\n  }\n  return s\n}\n\ntype LengthUnit = 'utf8' | 'utf16' | 'bytes-pre-encode'\n\nfunction cap(s: string, max: number, unit: LengthUnit): string {\n  if (max <= 0) {\n    throw new FilenameSanitizationError('maxBytes must be positive')\n  }\n  if (unit === 'utf16') {\n    if (s.length <= max) return s\n    return s.slice(0, max)\n  }\n  if (unit === 'bytes-pre-encode') {\n    if (utf8.encode(s).byteLength <= max) return s\n    return truncateToByteCap(s, max)\n  }\n  if (utf8.encode(s).byteLength <= max) return s\n  return truncateToByteCap(s, max)\n}\n\nfunction truncateToByteCap(s: string, max: number): string {\n  // Walk by code points so we never split a multi-byte sequence in\n  // the middle. Whole-grapheme handling (ZWJ-joined emoji) is a\n  // documented non-goal; we only protect against UTF-8 boundary\n  // splits here.\n  let out = ''\n  let used = 0\n  for (const cp of s) {\n    const n = utf8.encode(cp).byteLength\n    if (used + n > max) break\n    out += cp\n    used += n\n  }\n  if (out.length === 0) {\n    throw new FilenameSanitizationError('maxBytes too small for a single code point')\n  }\n  return out\n}\n"],"mappings":"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","names":[]}

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-BiasFcYx.d.ts → with-materialized-view-6p0Fk8bL.d.ts}

@@ -1,4 +1,4 @@
-import { aT as MaterializedViewStrategy, aU as MaterializedViewStrategyHandle } from './types-DGU60JDt.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-CQViuko_.d.ts → with-overlayed-view-BJ6mXGMd.d.ts}

@@ -1,10 +1,9 @@
-import { aV as OverlayedViewStrategy, aY as OverlayedViewStrategyHandle } from './types-DGU60JDt.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":[]}