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

package/dist/chunk-EMAWOGVH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-shape/introspection/walk.ts"],"sourcesContent":["/**\n * Orchestrate the structural walk of a Vault, producing a\n * {@link VaultSchemaSnapshot}. Called from `Vault.dumpSchema()`.\n *\n * @module\n */\n\nimport { derivePersistedSchema } from '../persisted-schemas/derive.js'\nimport { loadPersistedSchema } from '../persisted-schemas/storage.js'\nimport { fallbackDerivationName } from './derivation-key.js'\nimport { jsonSchemaToFields } from './fields.js'\nimport type {\n  CollectionConfig,\n  CollectionDescriptor,\n  CollectionStats,\n  DumpSchemaOptions,\n  FieldDescriptor,\n  InternalCollectionStats,\n  MaterializedViewDescriptor,\n  OverlayViewDescriptor,\n  DerivationDescriptor,\n  VaultSchemaSnapshot,\n} from './types.js'\nimport type { Collection } from '../../kernel/collection.js'\nimport type { NoydbStore } from '../../kernel/types.js'\nimport type { UnlockedKeyring } from '../../with-party/team/keyring.js'\nimport type { RefRegistry } from '../../kernel/refs.js'\nimport type { VaultMeta } from './meta.js'\nimport type { EnclaveKey } from '../../capsule/index.js'\n\n/**\n * The minimal slice of Vault internal state the walker needs.\n * Exposed via `vault._introspectState()` to keep the public Vault\n * surface narrow.\n *\n * @internal\n */\nexport interface VaultIntrospectState {\n  readonly name: string\n  readonly adapter: NoydbStore\n  readonly collectionCache: Map<string, Collection<unknown>>\n  readonly refRegistry: RefRegistry\n  readonly getDEK: (collectionName: string) => Promise<EnclaveKey>\n  /** The active unlocked keyring — role/permissions/userId for access-scoped ops. */\n  readonly keyring: UnlockedKeyring\n  readonly subsystems: Record<string, boolean>\n  /** Vault-level descriptive metadata, when set via `openVault({meta})`. */\n  readonly vaultMeta?: VaultMeta\n  // Typed loosely on purpose — these are private service registries\n  // accessed only for \"is anything registered\" enumeration.\n  readonly mvRegistry: unknown\n  readonly overlayRegistry: unknown\n  readonly derivationRegistry: unknown\n  /**\n   * Returns the registered schema-update strategy names for a collection,\n   * or `undefined` when none are registered. Populated from\n   * `vault.#schemaUpdateNames` in `_introspectState()`.\n   */\n  readonly getCollectionSchemaUpdateNames?: (col: string) => readonly string[] | undefined\n  /**\n   * Returns `true` when the collection has an archive policy registered\n   * in `vault.archiveRegistry`, `false` otherwise. Populated from\n   * `vault.archiveRegistry` in `_introspectState()`.\n   */\n  readonly hasCollectionArchive?: (col: string) => boolean\n}\n\nconst INTERNAL_PREFIX = '_'\n\n/** Reserved internal collections always present in any real vault. */\nconst KNOWN_INTERNAL_NAMES = ['_keyring', '_ledger', '_meta', '_schemas', '_deltas']\n\nexport async function dumpVaultSchema(\n  vault: { _introspectState(): VaultIntrospectState },\n  opts: DumpSchemaOptions,\n): Promise<VaultSchemaSnapshot> {\n  const state = vault._introspectState()\n  const sampleSize = opts.sampleSize ?? 50\n  const withStats = opts.withStats === true\n\n  // 1. User-facing collections — alphabetical for diff stability\n  const cacheNames = [...state.collectionCache.keys()]\n  const storageNames = (await safeListAllCollections(state.adapter, state.name))\n    .filter((n) => !n.startsWith(INTERNAL_PREFIX))\n  const allNames = Array.from(new Set([...cacheNames, ...storageNames])).sort()\n\n  const collections: Record<string, CollectionDescriptor> = {}\n  for (const name of allNames) {\n    collections[name] = await describeCollection(state, name, sampleSize, withStats)\n  }\n\n  // 2. Materialized views (placeholder — real walk in MV slice 2 follow-up)\n  const materializedViews = describeMVs(state.mvRegistry)\n  // 3. Overlay views\n  const overlayViews = describeOverlays(state.overlayRegistry)\n  // 4. Derivations\n  const derivations = describeDerivations(state.derivationRegistry)\n\n  // 5. Internal collections — only with stats\n  let internal: Record<string, InternalCollectionStats> | undefined\n  if (withStats) {\n    internal = {}\n    for (const name of KNOWN_INTERNAL_NAMES) {\n      const stats = await statsForCollection(state.adapter, state.name, name)\n      if (stats.records > 0) {\n        internal[name] = { records: stats.records, bytes: stats.bytes }\n      }\n    }\n  }\n\n  const snap: VaultSchemaSnapshot = {\n    _noydb_snapshot: 2,\n    // #1447 — what this emitter CAN report, not what it found. `via` is listed\n    // unconditionally: a vault declaring no via fields still gets it, because\n    // the consumer's question is \"can you answer?\", not \"did you find any\".\n    reports: withStats ? ['via', 'stats'] : ['via'],\n    vault: state.name,\n    emittedAt: new Date().toISOString(),\n    subsystems: state.subsystems,\n    ...(state.vaultMeta !== undefined ? { meta: state.vaultMeta } : {}),\n    collections,\n    materializedViews,\n    overlayViews,\n    derivations,\n    ...(internal !== undefined ? { internal } : {}),\n  }\n  return snap\n}\n\nasync function safeListAllCollections(adapter: NoydbStore, vault: string): Promise<string[]> {\n  try {\n    const snap = await adapter.loadAll(vault)\n    return Object.keys(snap)\n  } catch {\n    return []\n  }\n}\n\nasync function describeCollection(\n  state: VaultIntrospectState,\n  collectionName: string,\n  sampleSize: number,\n  withStats: boolean,\n): Promise<CollectionDescriptor> {\n  let fields: Record<string, FieldDescriptor> = {}\n  let validator: CollectionDescriptor['validator']\n\n  const refsRaw = state.refRegistry.getOutbound(collectionName)\n  const refs: CollectionDescriptor['refs'] = {}\n  for (const [name, desc] of Object.entries(refsRaw)) {\n    refs[name] = { target: desc.target, mode: desc.mode, ...(desc.isArray ? { isArray: true } : {}) }\n  }\n\n  // 1. Try the persisted Route B envelope first.\n  try {\n    const dek = await state.getDEK(collectionName)\n    const persisted = await loadPersistedSchema(state.adapter, state.name, collectionName, dek)\n    if (persisted) {\n      validator = { kind: persisted.kind, source: 'persisted' }\n      if (persisted.jsonSchema) {\n        fields = jsonSchemaToFields(persisted.jsonSchema, 'persisted', refsRaw)\n      }\n    }\n  } catch {\n    // No DEK or decrypt failure — fall through to live-validator\n  }\n\n  const liveColl = state.collectionCache.get(collectionName)\n\n  // 2. Try the live in-process validator (when no persisted envelope).\n  if (!validator) {\n    const schema = liveColl?.getSchema()\n    if (schema) {\n      try {\n        const derived = await derivePersistedSchema(schema)\n        validator = { kind: derived.kind, source: 'live-validator' }\n        if (derived.jsonSchema) {\n          fields = jsonSchemaToFields(derived.jsonSchema, 'live-validator', refsRaw)\n        }\n      } catch {\n        // Derivation failed (e.g. missing peer-dep) — silently leave fields empty\n      }\n    }\n  }\n\n  // 3. Sampling fallback — deferred to a follow-up. For now: empty when no schema.\n  if (Object.keys(fields).length === 0 && sampleSize > 0) {\n    // Sampling path not implemented in baseline slice 2; reserved for follow-up.\n  }\n\n  // Read-shape sensitivity (#1363): `FieldMeta.bulk` lives in the `fieldMeta`\n  // channel, which is never persisted with the schema — so it can only be read\n  // off a collection that is live in this process. Merged onto whatever fields\n  // the persisted/derived route already produced; never invents a field.\n  if (liveColl !== undefined && Object.keys(fields).length > 0) {\n    fields = overlayBulk(fields, liveColl)\n  }\n\n  // Populate collection-level meta and config from the live collection when available.\n  const collMeta = liveColl?.getMeta()\n  const collConfig = liveColl?.getConfig()\n\n  // Thread vault-level config (archive + schemaUpdate) that the Collection cannot see.\n  const archivePresent = state.hasCollectionArchive?.(collectionName) === true\n  const schemaUpdateNames = state.getCollectionSchemaUpdateNames?.(collectionName)\n  const hasSchemaUpdate = schemaUpdateNames !== undefined && schemaUpdateNames.length > 0\n\n  // Merge Collection-level config with vault-level fields. Omit config entirely\n  // when all sources are empty.\n  let mergedConfig: CollectionConfig | undefined\n  if (collConfig !== undefined || archivePresent || hasSchemaUpdate) {\n    mergedConfig = {\n      ...(collConfig ?? {}),\n      ...(archivePresent ? { archive: true as const } : {}),\n      ...(hasSchemaUpdate ? { schemaUpdate: schemaUpdateNames } : {}),\n    }\n  }\n\n  const viaCoverage = liveColl?.getViaCoverage()\n\n  const descriptor: CollectionDescriptor = {\n    fields,\n    indexes: liveColl?.getDeclaredIndexes() ?? [],\n    refs,\n    ...(validator ? { validator } : {}),\n    ...(collMeta !== undefined ? { meta: collMeta } : {}),\n    ...(mergedConfig !== undefined ? { config: mergedConfig } : {}),\n    // #1447 — omitted entirely when the collection declares no via pipeline,\n    // so absence reads as \"nothing declared\" rather than \"nothing reported\".\n    ...(viaCoverage !== undefined ? { via: viaCoverage } : {}),\n  }\n  if (withStats) {\n    const stats = await statsForCollection(state.adapter, state.name, collectionName)\n    ;(descriptor as { stats?: CollectionStats }).stats = stats\n  }\n  return descriptor\n}\n\n/**\n * Overlay the `bulk` axis from a live collection's `describe()` onto the\n * snapshot's field map. Sync and store-free by construction (`describe()` with\n * no options does no I/O); silent if a collection cannot describe itself,\n * because a snapshot that throws is worse than one missing a telemetry hint.\n */\nfunction overlayBulk(\n  fields: Record<string, FieldDescriptor>,\n  liveColl: Collection<unknown>,\n): Record<string, FieldDescriptor> {\n  let described\n  try {\n    described = liveColl.describe()\n  } catch {\n    return fields\n  }\n  let out: Record<string, FieldDescriptor> | undefined\n  for (const f of described.fields) {\n    if (f.bulk === undefined) continue\n    const existing = fields[f.key]\n    if (existing === undefined) continue\n    out ??= { ...fields }\n    out[f.key] = { ...existing, bulk: f.bulk }\n  }\n  return out ?? fields\n}\n\nasync function statsForCollection(\n  adapter: NoydbStore,\n  vault: string,\n  collection: string,\n): Promise<CollectionStats> {\n  const ids = await adapter.list(vault, collection)\n  if (ids.length === 0) {\n    return { records: 0, bytes: 0, bytesAvg: 0, bytesMin: 0, bytesMax: 0, oldest: '', newest: '' }\n  }\n  let total = 0\n  let min = Number.POSITIVE_INFINITY\n  let max = 0\n  let oldest = '￿'\n  let newest = ''\n  for (const id of ids) {\n    const env = await adapter.get(vault, collection, id)\n    if (!env) continue\n    const size = (env._data ?? '').length\n    total += size\n    if (size < min) min = size\n    if (size > max) max = size\n    if (env._ts < oldest) oldest = env._ts\n    if (env._ts > newest) newest = env._ts\n  }\n  return {\n    records: ids.length,\n    bytes: total,\n    bytesAvg: Math.round(total / ids.length),\n    bytesMin: min === Number.POSITIVE_INFINITY ? 0 : min,\n    bytesMax: max,\n    oldest: oldest === '￿' ? '' : oldest,\n    newest,\n  }\n}\n\nfunction describeMVs(registry: unknown): Record<string, MaterializedViewDescriptor> {\n  if (!registry || typeof registry !== 'object') return {}\n  const items = listFromRegistry(registry as Record<string, unknown>)\n  const out: Record<string, MaterializedViewDescriptor> = {}\n  // Each item is RegisteredMV { spec, dependencies, outputCollection, ... }\n  for (const item of items) {\n    const reg = item as {\n      spec?: {\n        name?: string\n        unionSources?: ReadonlyArray<{ collection: string }>\n        groupBy?: string | ReadonlyArray<string>\n        aggregate?: Record<string, unknown>\n        refresh?: string\n      }\n      dependencies?: ReadonlySet<string>\n    }\n    const spec = reg.spec\n    if (!spec?.name) continue\n    const sources = spec.unionSources\n      ? spec.unionSources.map((u) => u.collection)\n      : (reg.dependencies ? [...reg.dependencies].sort() : [])\n    const groupBy = spec.groupBy\n      ? Array.isArray(spec.groupBy) ? [...spec.groupBy] : [spec.groupBy]\n      : undefined\n    const aggregate = spec.aggregate ? Object.fromEntries(\n      Object.entries(spec.aggregate).map(([k, v]) => [k, summariseAggregateOp(v)]),\n    ) : undefined\n    out[spec.name] = {\n      sources,\n      ...(groupBy ? { groupBy } : {}),\n      ...(aggregate ? { aggregate } : {}),\n      refresh: spec.refresh ?? 'eager',\n    }\n  }\n  return out\n}\n\nfunction describeOverlays(registry: unknown): Record<string, OverlayViewDescriptor> {\n  if (!registry || typeof registry !== 'object') return {}\n  const specs = listFromRegistry(registry as Record<string, unknown>)\n  const out: Record<string, OverlayViewDescriptor> = {}\n  for (const spec of specs) {\n    const s = spec as { name?: string; base?: string; overlay?: string }\n    if (!s.name || !s.base || !s.overlay) continue\n    out[s.name] = { base: s.base, overlay: s.overlay }\n  }\n  return out\n}\n\nfunction describeDerivations(registry: unknown): Record<string, DerivationDescriptor> {\n  if (!registry || typeof registry !== 'object') return {}\n  const items = listFromRegistry(registry as Record<string, unknown>)\n  const out: Record<string, DerivationDescriptor> = {}\n  const used = new Set<string>()\n  // Pre-seed with every explicit name BEFORE keying any derivation, so an\n  // unnamed derivation's fallback key never collides with (and clobbers) a\n  // named one, regardless of registration order (#973).\n  for (const item of items) {\n    const reg = item as { spec?: { name?: string }; name?: string }\n    const explicitName = (reg.spec ?? reg).name\n    if (explicitName !== undefined) used.add(explicitName)\n  }\n  for (const item of items) {\n    // `all()` on DerivationRegistry returns RegisteredStrategy objects:\n    // { spec: DerivationSpec, strategyHash }. Read `spec` and fall\n    // back to the item itself for forward-compat with other registries.\n    const reg = item as { spec?: { name?: string; source?: string; outputs?: Record<string, { collection: string }> }; name?: string; source?: string; outputs?: Record<string, { collection: string }> }\n    const s = reg.spec ?? reg\n    if (!s.source) continue\n    const outputCollections = s.outputs\n      ? Object.values(s.outputs).map((o) => (o as { collection: string }).collection)\n      : []\n    // Named derivations key by their (vault-unique) `name`. Unnamed ones key\n    // by the shared collision-safe fallback (sorted output collections, else\n    // source, with a `#occurrence` suffix on collision) — the SAME algorithm\n    // `listBehaviors` uses (`./derivation-key.ts`) so both surfaces key an\n    // unnamed derivation identically.\n    const key = s.name ?? fallbackDerivationName(outputCollections, s.source, used)\n    if (s.name === undefined) used.add(key)\n    out[key] = {\n      source: s.source,\n      outputs: outputCollections,\n      ...(s.name !== undefined ? { name: s.name } : {}),\n    }\n  }\n  return out\n}\n\nfunction listFromRegistry(reg: Record<string, unknown>): readonly unknown[] {\n  // Registries expose different accessor methods; try the common ones.\n  for (const method of ['all', 'list', 'specs', 'values']) {\n    const fn = reg[method]\n    if (typeof fn === 'function') {\n      try {\n        const out = (fn as () => unknown).call(reg)\n        if (Array.isArray(out)) return out\n        if (out && typeof (out as { values?: () => unknown }).values === 'function') {\n          return [...(out as { values: () => Iterable<unknown> }).values()]\n        }\n      } catch {\n        continue\n      }\n    }\n  }\n  return []\n}\n\nfunction summariseAggregateOp(value: unknown): string {\n  if (value && typeof value === 'object') {\n    const op = (value as { op?: string; kind?: string; field?: string }).op\n      ?? (value as { kind?: string }).kind\n    const field = (value as { field?: string }).field\n    if (op && field) return `${op}(${field})`\n    if (op) return op\n  }\n  return String(value)\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-3F7GLNAE.js → chunk-EUD3HQM4.js}

@@ -1,20 +1,16 @@
 import {
   linkCollectionName,
   linkRowKey
-} from "./chunk-AOWGXU6D.js";
+} from "./chunk-UAKY6E4N.js";
 import {
   buildRecordAad,
+  buildRecordEnvelope,
+  encrypt,
   openEnvelopeJson
-} from "./chunk-KJFW62P4.js";
-import {
-  buildRecordEnvelope
-} from "./chunk-SEE332EV.js";
-import {
-  encrypt
-} from "./chunk-UYB234ZR.js";
+} from "./chunk-4J3MNVVX.js";
 import {
   NoydbError
-} from "./chunk-244VXYPG.js";
+} from "./chunk-VSUQI5Q6.js";
 
 // src/with-shape/links/link-set.ts
 var LinkSet = class {
@@ -55,7 +51,7 @@ var LinkSet = class {
     return buildRecordEnvelope(identity, { iv, data });
   }
   async decryptEntry(key, env) {
-    const json = this.encrypted ? await openEnvelopeJson({ collection: this.collName, id: key }, env, await this.dek()) : env._data;
+    const json = this.encrypted ? await openEnvelopeJson({ collection: this.collName, id: key }, env, await this.dek()) : env._data ?? "";
     return JSON.parse(json);
   }
   async connect(aId, bId, meta) {
@@ -130,4 +126,4 @@ export {
   LinkSet,
   LinkEndpointError
 };
-//# sourceMappingURL=chunk-3F7GLNAE.js.map
+//# sourceMappingURL=chunk-EUD3HQM4.js.map

package/dist/chunk-EUD3HQM4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-shape/links/link-set.ts"],"sourcesContent":["/**\n * `_links_*` reserved collections — managed bidirectional many-to-many\n * junctions (design B).\n *\n * Where `refArray` (design A) stores an id-array on one owning record,\n * `vault.link()` creates a first-class junction: a dedicated encrypted\n * `_links_<name>` collection whose rows are `{ a, b, meta? }` link tuples.\n * It is queryable from BOTH sides (`of(id)`), carries optional per-link\n * metadata, and cascades on endpoint delete.\n *\n * Each link is slot-typed: `a` is an id in the `a` endpoint collection,\n * `b` an id in the `b` endpoint collection (they may be the same\n * collection for self-links). A link's identity is the ordered pair\n * `(a, b)`; `of(id)` matches either slot.\n *\n * Rows are encrypted under a dedicated `_links_<name>` DEK — same\n * zero-knowledge stack as every other collection (the store sees only\n * ciphertext). Backup/restore rides the normal `loadAll` path.\n */\n\nimport type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js'\nimport type { NoydbEventEmitter } from '../../kernel/events.js'\nimport { buildRecordAad, buildRecordEnvelope, encrypt, openEnvelopeJson, type EnclaveKey } from '../../capsule/index.js'\nimport { NoydbError } from '../../kernel/errors.js'\n\n// Naming helpers, declaration types, and LinkIntegrityError live in\n// `names.ts` (the always-loadable slice — #553); re-exported here so\n// existing import paths and the root barrel are unchanged.\nexport {\n  LINK_COLLECTION_PREFIX,\n  linkCollectionName,\n  isLinkCollectionName,\n  linkRowKey,\n  LinkIntegrityError,\n} from './names.js'\nexport type { LinkOnDelete, LinkSpec, LinkRow, LinkSetHandle } from './names.js'\nimport { linkCollectionName, linkRowKey } from './names.js'\nimport type { LinkSpec, LinkRow, LinkSetHandle } from './names.js'\n\n/** Stored form (also the row key derivation source). */\ninterface LinkEntry {\n  a: string\n  b: string\n  meta?: Record<string, unknown>\n}\n\n/**\n * @internal — the concrete handle. The Vault owns construction (one per\n * link name) and the cascade hooks; consumers use the {@link LinkSetHandle}\n * surface via `vault.links(name)`.\n */\nexport class LinkSet implements LinkSetHandle {\n  private readonly collName: string\n  private dekPromise: Promise<EnclaveKey> | null = null\n\n  constructor(\n    private readonly adapter: NoydbStore,\n    private readonly vault: string,\n    private readonly name: string,\n    private readonly spec: LinkSpec,\n    private readonly encrypted: boolean,\n    private readonly getDEK: (collectionName: string) => Promise<EnclaveKey>,\n    private readonly actor: string,\n    private readonly emitter: NoydbEventEmitter,\n    /** Vault-provided existence check for endpoint validation on connect(). */\n    private readonly endpointExists: (collection: string, id: string) => Promise<boolean>,\n  ) {\n    this.collName = linkCollectionName(name)\n  }\n\n  private dek(): Promise<EnclaveKey> {\n    if (!this.dekPromise) this.dekPromise = this.getDEK(this.collName)\n    return this.dekPromise\n  }\n\n  private async encryptEntry(entry: LinkEntry, version: number, key: string): Promise<EncryptedEnvelope> {\n    const json = JSON.stringify(entry)\n    const identity = { collection: this.collName, id: key, by: this.actor, version }\n    if (!this.encrypted) {\n      return buildRecordEnvelope(identity, { iv: '', data: json})\n    }\n    const { iv, data } = await encrypt(json, await this.dek(), buildRecordAad(identity))\n    return buildRecordEnvelope(identity, { iv, data})\n  }\n\n  private async decryptEntry(key: string, env: EncryptedEnvelope): Promise<LinkEntry> {\n    const json = this.encrypted ? await openEnvelopeJson({ collection: this.collName, id: key }, env, await this.dek()) : (env._data ?? '')\n    return JSON.parse(json) as LinkEntry\n  }\n\n  async connect(aId: string, bId: string, meta?: Record<string, unknown>): Promise<void> {\n    if (!(await this.endpointExists(this.spec.a, aId))) {\n      throw new LinkEndpointError(this.name, this.spec.a, aId)\n    }\n    if (!(await this.endpointExists(this.spec.b, bId))) {\n      throw new LinkEndpointError(this.name, this.spec.b, bId)\n    }\n    const key = linkRowKey(aId, bId)\n    const entry: LinkEntry = meta !== undefined ? { a: aId, b: bId, meta } : { a: aId, b: bId }\n    const existing = await this.adapter.get(this.vault, this.collName, key)\n    const env = await this.encryptEntry(entry, (existing?._v ?? 0) + 1, key)\n    await this.adapter.put(this.vault, this.collName, key, env, existing?._v)\n    this.emitter.emit('change', { vault: this.vault, collection: this.collName, id: key, action: 'put' })\n  }\n\n  async disconnect(aId: string, bId: string): Promise<void> {\n    const key = linkRowKey(aId, bId)\n    const existing = await this.adapter.get(this.vault, this.collName, key)\n    if (!existing) return\n    await this.adapter.delete(this.vault, this.collName, key)\n    this.emitter.emit('change', { vault: this.vault, collection: this.collName, id: key, action: 'delete' })\n  }\n\n  async has(aId: string, bId: string): Promise<boolean> {\n    return (await this.adapter.get(this.vault, this.collName, linkRowKey(aId, bId))) !== null\n  }\n\n  async of(id: string): Promise<LinkRow[]> {\n    const rows = await this.list()\n    return rows.filter((r) => r.a === id || r.b === id)\n  }\n\n  async list(): Promise<LinkRow[]> {\n    const keys = await this.adapter.list(this.vault, this.collName)\n    const out: LinkRow[] = []\n    for (const key of keys) {\n      const env = await this.adapter.get(this.vault, this.collName, key)\n      if (!env) continue\n      const e = await this.decryptEntry(key, env)\n      out.push(e.meta !== undefined ? { a: e.a, b: e.b, meta: e.meta } : { a: e.a, b: e.b })\n    }\n    return out\n  }\n\n  // ── Vault-internal cascade helpers ──────────────────────────────────\n\n  /** @internal — rows where the deleted endpoint id matches the relevant slot. */\n  async _rowsTouchingEndpoint(collection: string, id: string): Promise<LinkRow[]> {\n    const rows = await this.list()\n    return rows.filter(\n      (r) => (this.spec.a === collection && r.a === id) || (this.spec.b === collection && r.b === id),\n    )\n  }\n\n  /** @internal — the storage collection name (for tx pre-image capture). */\n  get _collectionName(): string {\n    return this.collName\n  }\n}\n\n/** Thrown by `connect()` when an endpoint record does not exist. */\nexport class LinkEndpointError extends NoydbError {\n  readonly link: string\n  readonly endpoint: string\n  readonly missingId: string\n  constructor(link: string, endpoint: string, missingId: string) {\n    super(\n      'LINK_ENDPOINT',\n      `link(\"${link}\").connect: endpoint \"${endpoint}\" has no record \"${missingId}\".`,\n    )\n    this.name = 'LinkEndpointError'\n    this.link = link\n    this.endpoint = endpoint\n    this.missingId = missingId\n  }\n}\n"],"mappings":"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","names":[]}