@klum-db/lobby 0.2.0-pre.26 → 0.2.0-pre.28

package/dist/bin/klum.cjs

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bin/klum.ts
+var klum_exports = {};
+__export(klum_exports, {
+  main: () => main,
+  parseArgs: () => parseArgs,
+  runInspectGroup: () => runInspectGroup,
+  runMeterGroup: () => runMeterGroup
+});
+module.exports = __toCommonJS(klum_exports);
+var import_in_devtools = require("@noy-db/in-devtools");
+
+// src/federation/group-inspector.ts
+function groupInspector(group) {
+  let shardIds = /* @__PURE__ */ new Set();
+  const refresh = async () => {
+    const rows = await group.allRows();
+    shardIds = new Set(rows.map((r) => r.vaultId));
+    return rows;
+  };
+  return {
+    async listAccessibleVaults() {
+      const rows = await refresh();
+      return rows.map((r) => ({ id: r.vaultId, role: "owner" }));
+    },
+    async openVault(name) {
+      const vault = await group.db.openVault(name);
+      group.template.configure(vault);
+      return vault;
+    },
+    onAfterWrite(handler) {
+      return group.db.onAfterWrite((event) => {
+        if (shardIds.has(event.vault)) return handler(event);
+      });
+    },
+    onWriteConflict(handler) {
+      return group.db.onWriteConflict((c) => {
+        if (shardIds.has(c.vault)) handler(c);
+      });
+    },
+    get writeQueue() {
+      return group.db.writeQueue;
+    }
+  };
+}
+
+// src/federation/meter-group.ts
+async function meterGroup(group, opts = {}) {
+  const { eligible, skipped } = await group.resolveEligible(
+    opts.minVersion !== void 0 ? { minVersion: opts.minVersion } : {}
+  );
+  const perShard = [];
+  const names = /* @__PURE__ */ new Set();
+  let records = 0;
+  for (const row of eligible) {
+    const vault = await group.shard(row.partitionKey);
+    const collNames = await vault.collections();
+    let shardRecords = 0;
+    for (const n of collNames) {
+      names.add(n);
+      shardRecords += await vault.collection(n).count();
+    }
+    records += shardRecords;
+    perShard.push({
+      vaultId: row.vaultId,
+      partitionKey: row.partitionKey,
+      schemaVersion: row.schemaVersion,
+      collections: collNames.length,
+      records: shardRecords
+    });
+  }
+  return { vaults: eligible.length, collections: names.size, records, perShard, skipped };
+}
+
+// src/bin/klum.ts
+var import_meta = {};
+function parseArgs(argv) {
+  const out = { command: argv[0] ?? "", meter: false };
+  for (const a of argv.slice(1)) {
+    if (a.startsWith("--group=")) out.group = a.slice("--group=".length);
+    else if (a.startsWith("--vault=")) out.vault = a.slice("--vault=".length);
+    else if (a === "--meter") out.meter = true;
+    else if (!a.startsWith("--")) out.configPath = a;
+  }
+  return out;
+}
+async function loadGroup(args) {
+  const mod = await import(args.configPath);
+  return mod.default(args.group);
+}
+async function runInspectGroup(args, log) {
+  if (!args.configPath) {
+    log("usage: klum inspect-group <config> --group=<name> [--vault=<id>]");
+    return 2;
+  }
+  const group = await loadGroup(args);
+  const inspector = (0, import_in_devtools.createInspector)(groupInspector(group));
+  const vaults = await inspector.listVaults();
+  log(`group "${args.group ?? ""}" \u2014 ${vaults.length} shard(s):`);
+  for (const v of vaults) log(`  ${v.id} [${v.role}]`);
+  if (args.vault) {
+    const vault = await group.db.openVault(args.vault);
+    group.template.configure(vault);
+    const snap = await inspector.snapshot(vault);
+    log(`  collections in ${args.vault}: ${snap.collections.map((c) => c.name).join(", ")}`);
+  }
+  return 0;
+}
+async function runMeterGroup(args, log) {
+  if (!args.configPath) {
+    log("usage: klum meter-group <config> --group=<name>");
+    return 2;
+  }
+  const group = await loadGroup(args);
+  const r = await meterGroup(group);
+  log(`group "${args.group ?? ""}" \u2014 ${r.vaults} vault(s), ${r.collections} collection(s), ${r.records} record(s)`);
+  for (const s of r.perShard) {
+    log(`  ${s.vaultId} (${s.partitionKey}) v${s.schemaVersion}: ${s.collections} coll, ${s.records} rec`);
+  }
+  if (r.skipped.length) log(`  skipped: ${r.skipped.length} shard(s)`);
+  return 0;
+}
+async function main(argv, log = console.log) {
+  const args = parseArgs(argv);
+  switch (args.command) {
+    case "inspect-group":
+      return runInspectGroup(args, log);
+    case "meter-group":
+      return runMeterGroup(args, log);
+    default:
+      log("klum <inspect-group|meter-group> <config> --group=<name> [--vault=<id>]");
+      return args.command ? 1 : 0;
+  }
+}
+if (process.argv[1] && import_meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  }).catch((e) => {
+    console.error(e);
+    process.exitCode = 1;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main,
+  parseArgs,
+  runInspectGroup,
+  runMeterGroup
+});
+//# sourceMappingURL=klum.cjs.map

package/dist/bin/klum.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bin/klum.ts","../../src/federation/group-inspector.ts","../../src/federation/meter-group.ts"],"sourcesContent":["import { createInspector } from '@noy-db/in-devtools'\nimport { groupInspector } from '../federation/group-inspector.js'\nimport { meterGroup } from '../federation/meter-group.js'\nimport type { VaultGroup } from '../federation/vault-group.js'\n\n/**\n * A config module for the `klum` CLI default-exports this factory: given an\n * optional group name, it returns an opened VaultGroup (the user's module owns\n * the store, templates, and sharding config — the CLI stays agnostic of them).\n */\nexport type GroupFactory = (groupName?: string) => Promise<VaultGroup<unknown>>\n\ntype Log = (s: string) => void\n\nexport interface ParsedArgs {\n  command: string\n  configPath?: string\n  group?: string\n  vault?: string\n  meter: boolean\n}\n\nexport function parseArgs(argv: readonly string[]): ParsedArgs {\n  const out: ParsedArgs = { command: argv[0] ?? '', meter: false }\n  for (const a of argv.slice(1)) {\n    if (a.startsWith('--group=')) out.group = a.slice('--group='.length)\n    else if (a.startsWith('--vault=')) out.vault = a.slice('--vault='.length)\n    else if (a === '--meter') out.meter = true\n    else if (!a.startsWith('--')) out.configPath = a\n  }\n  return out\n}\n\nasync function loadGroup(args: ParsedArgs): Promise<VaultGroup<unknown>> {\n  const mod = (await import(args.configPath!)) as { default: GroupFactory }\n  return mod.default(args.group)\n}\n\nexport async function runInspectGroup(args: ParsedArgs, log: Log): Promise<number> {\n  if (!args.configPath) {\n    log('usage: klum inspect-group <config> --group=<name> [--vault=<id>]')\n    return 2\n  }\n  const group = await loadGroup(args)\n  const inspector = createInspector(groupInspector(group))\n  const vaults = await inspector.listVaults()\n  log(`group \"${args.group ?? ''}\" — ${vaults.length} shard(s):`)\n  for (const v of vaults) log(`  ${v.id} [${v.role}]`)\n  if (args.vault) {\n    const vault = await group.db.openVault(args.vault)\n    group.template.configure(vault)\n    const snap = await inspector.snapshot(vault)\n    log(`  collections in ${args.vault}: ${snap.collections.map((c) => c.name).join(', ')}`)\n  }\n  return 0\n}\n\nexport async function runMeterGroup(args: ParsedArgs, log: Log): Promise<number> {\n  if (!args.configPath) {\n    log('usage: klum meter-group <config> --group=<name>')\n    return 2\n  }\n  const group = await loadGroup(args)\n  const r = await meterGroup(group)\n  log(`group \"${args.group ?? ''}\" — ${r.vaults} vault(s), ${r.collections} collection(s), ${r.records} record(s)`)\n  for (const s of r.perShard) {\n    log(`  ${s.vaultId} (${s.partitionKey}) v${s.schemaVersion}: ${s.collections} coll, ${s.records} rec`)\n  }\n  if (r.skipped.length) log(`  skipped: ${r.skipped.length} shard(s)`)\n  return 0\n}\n\nexport async function main(argv: readonly string[], log: Log = console.log): Promise<number> {\n  const args = parseArgs(argv)\n  switch (args.command) {\n    case 'inspect-group':\n      return runInspectGroup(args, log)\n    case 'meter-group':\n      return runMeterGroup(args, log)\n    default:\n      log('klum <inspect-group|meter-group> <config> --group=<name> [--vault=<id>]')\n      return args.command ? 1 : 0\n  }\n}\n\n// bin entrypoint — only runs when executed directly, not when imported in tests.\nif (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {\n  main(process.argv.slice(2))\n    .then((code) => {\n      process.exitCode = code\n    })\n    .catch((e: unknown) => {\n      console.error(e)\n      process.exitCode = 1\n    })\n}\n","import type { InspectableContainer } from '@noy-db/in-devtools'\nimport type { AccessibleVault, Vault, WriteHook, WriteConflict, WriteQueue, Unsubscribe } from '@noy-db/hub'\nimport type { VaultGroup } from './vault-group.js'\n\n/**\n * Adapt a federation {@link VaultGroup} to the dev-tools `InspectableContainer`\n * contract from `@noy-db/in-devtools`, so the inspector / TUI can browse a\n * whole fleet exactly like a single instance.\n *\n * Built entirely on the group's public surface (`allRows`, `db`, `template`) —\n * no `VaultGroup` changes, and (critically) no `@klum-db` import lands in any\n * `@noy-db` package: the dependency runs one way, klum → noy.\n *\n * Write-event scoping: `group.db` may host vaults outside this group, so write\n * and conflict events are filtered to the group's shard ids. The id set is\n * primed/refreshed on every `listAccessibleVaults()` call — drive `listVaults()`\n * (the inspector's normal first step) before relying on event scoping.\n */\nexport function groupInspector<T>(group: VaultGroup<T>): InspectableContainer {\n  let shardIds = new Set<string>()\n  const refresh = async () => {\n    const rows = await group.allRows()\n    shardIds = new Set(rows.map((r) => r.vaultId))\n    return rows\n  }\n  return {\n    async listAccessibleVaults(): Promise<readonly AccessibleVault[]> {\n      const rows = await refresh()\n      return rows.map((r): AccessibleVault => ({ id: r.vaultId, role: 'owner' }))\n    },\n    async openVault(name: string): Promise<Vault> {\n      const vault = await group.db.openVault(name)\n      group.template.configure(vault)\n      return vault\n    },\n    onAfterWrite(handler: WriteHook): Unsubscribe {\n      return group.db.onAfterWrite((event) => {\n        if (shardIds.has(event.vault)) return handler(event)\n      })\n    },\n    onWriteConflict(handler: (c: WriteConflict) => void): Unsubscribe {\n      return group.db.onWriteConflict((c) => {\n        if (shardIds.has(c.vault)) handler(c)\n      })\n    },\n    get writeQueue(): WriteQueue {\n      return group.db.writeQueue\n    },\n  }\n}\n","import type { VaultGroup } from './vault-group.js'\nimport type { SkippedVault } from './types.js'\n\nexport interface GroupShardMetrics {\n  readonly vaultId: string\n  readonly partitionKey: string\n  readonly schemaVersion: number\n  readonly collections: number\n  readonly records: number\n}\n\nexport interface GroupMeterReport {\n  /** Number of eligible shards measured. */\n  readonly vaults: number\n  /** Distinct collection names across the group. */\n  readonly collections: number\n  /** Total record count summed across shards. */\n  readonly records: number\n  readonly perShard: ReadonlyArray<GroupShardMetrics>\n  /** Drifted / provisioning-failed shards — surfaced, never counted or hidden. */\n  readonly skipped: ReadonlyArray<SkippedVault>\n}\n\n/**\n * Fan shape-metrics (collection count + record count) across the group's\n * ELIGIBLE shards. Skipped shards (schema-drift / provisioning failures) are\n * reported in `skipped`, never silently dropped. Reuses the per-vault pattern\n * from `multi-bundle.ts` (`vault.collections()` → `collection(n).count()`).\n *\n * Operational store metrics (calls, CAS conflicts) are a separate concern and\n * are already group-wide via `@noy-db/to-meter` on the underlying store.\n */\nexport async function meterGroup<T>(\n  group: VaultGroup<T>,\n  opts: { minVersion?: number } = {},\n): Promise<GroupMeterReport> {\n  const { eligible, skipped } = await group.resolveEligible(\n    opts.minVersion !== undefined ? { minVersion: opts.minVersion } : {},\n  )\n  const perShard: GroupShardMetrics[] = []\n  const names = new Set<string>()\n  let records = 0\n  for (const row of eligible) {\n    const vault = await group.shard(row.partitionKey)\n    const collNames = await vault.collections()\n    let shardRecords = 0\n    for (const n of collNames) {\n      names.add(n)\n      shardRecords += await vault.collection(n).count()\n    }\n    records += shardRecords\n    perShard.push({\n      vaultId: row.vaultId,\n      partitionKey: row.partitionKey,\n      schemaVersion: row.schemaVersion,\n      collections: collNames.length,\n      records: shardRecords,\n    })\n  }\n  return { vaults: eligible.length, collections: names.size, records, perShard, skipped }\n}\n"],"mappings":"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","names":[]}

package/dist/bin/klum.d.cts

@@ -0,0 +1,25 @@
+import { V as VaultGroup } from '../vault-group-DeBoCFT9.cjs';
+import '@noy-db/hub/kernel';
+import '@noy-db/hub';
+import '@noy-db/hub/bundle';
+
+/**
+ * A config module for the `klum` CLI default-exports this factory: given an
+ * optional group name, it returns an opened VaultGroup (the user's module owns
+ * the store, templates, and sharding config — the CLI stays agnostic of them).
+ */
+type GroupFactory = (groupName?: string) => Promise<VaultGroup<unknown>>;
+type Log = (s: string) => void;
+interface ParsedArgs {
+    command: string;
+    configPath?: string;
+    group?: string;
+    vault?: string;
+    meter: boolean;
+}
+declare function parseArgs(argv: readonly string[]): ParsedArgs;
+declare function runInspectGroup(args: ParsedArgs, log: Log): Promise<number>;
+declare function runMeterGroup(args: ParsedArgs, log: Log): Promise<number>;
+declare function main(argv: readonly string[], log?: Log): Promise<number>;
+
+export { type GroupFactory, type ParsedArgs, main, parseArgs, runInspectGroup, runMeterGroup };

package/dist/bin/klum.d.ts

@@ -0,0 +1,25 @@
+import { V as VaultGroup } from '../vault-group-DeBoCFT9.js';
+import '@noy-db/hub/kernel';
+import '@noy-db/hub';
+import '@noy-db/hub/bundle';
+
+/**
+ * A config module for the `klum` CLI default-exports this factory: given an
+ * optional group name, it returns an opened VaultGroup (the user's module owns
+ * the store, templates, and sharding config — the CLI stays agnostic of them).
+ */
+type GroupFactory = (groupName?: string) => Promise<VaultGroup<unknown>>;
+type Log = (s: string) => void;
+interface ParsedArgs {
+    command: string;
+    configPath?: string;
+    group?: string;
+    vault?: string;
+    meter: boolean;
+}
+declare function parseArgs(argv: readonly string[]): ParsedArgs;
+declare function runInspectGroup(args: ParsedArgs, log: Log): Promise<number>;
+declare function runMeterGroup(args: ParsedArgs, log: Log): Promise<number>;
+declare function main(argv: readonly string[], log?: Log): Promise<number>;
+
+export { type GroupFactory, type ParsedArgs, main, parseArgs, runInspectGroup, runMeterGroup };

package/dist/bin/klum.js

@@ -0,0 +1,139 @@
+// src/bin/klum.ts
+import { createInspector } from "@noy-db/in-devtools";
+
+// src/federation/group-inspector.ts
+function groupInspector(group) {
+  let shardIds = /* @__PURE__ */ new Set();
+  const refresh = async () => {
+    const rows = await group.allRows();
+    shardIds = new Set(rows.map((r) => r.vaultId));
+    return rows;
+  };
+  return {
+    async listAccessibleVaults() {
+      const rows = await refresh();
+      return rows.map((r) => ({ id: r.vaultId, role: "owner" }));
+    },
+    async openVault(name) {
+      const vault = await group.db.openVault(name);
+      group.template.configure(vault);
+      return vault;
+    },
+    onAfterWrite(handler) {
+      return group.db.onAfterWrite((event) => {
+        if (shardIds.has(event.vault)) return handler(event);
+      });
+    },
+    onWriteConflict(handler) {
+      return group.db.onWriteConflict((c) => {
+        if (shardIds.has(c.vault)) handler(c);
+      });
+    },
+    get writeQueue() {
+      return group.db.writeQueue;
+    }
+  };
+}
+
+// src/federation/meter-group.ts
+async function meterGroup(group, opts = {}) {
+  const { eligible, skipped } = await group.resolveEligible(
+    opts.minVersion !== void 0 ? { minVersion: opts.minVersion } : {}
+  );
+  const perShard = [];
+  const names = /* @__PURE__ */ new Set();
+  let records = 0;
+  for (const row of eligible) {
+    const vault = await group.shard(row.partitionKey);
+    const collNames = await vault.collections();
+    let shardRecords = 0;
+    for (const n of collNames) {
+      names.add(n);
+      shardRecords += await vault.collection(n).count();
+    }
+    records += shardRecords;
+    perShard.push({
+      vaultId: row.vaultId,
+      partitionKey: row.partitionKey,
+      schemaVersion: row.schemaVersion,
+      collections: collNames.length,
+      records: shardRecords
+    });
+  }
+  return { vaults: eligible.length, collections: names.size, records, perShard, skipped };
+}
+
+// src/bin/klum.ts
+function parseArgs(argv) {
+  const out = { command: argv[0] ?? "", meter: false };
+  for (const a of argv.slice(1)) {
+    if (a.startsWith("--group=")) out.group = a.slice("--group=".length);
+    else if (a.startsWith("--vault=")) out.vault = a.slice("--vault=".length);
+    else if (a === "--meter") out.meter = true;
+    else if (!a.startsWith("--")) out.configPath = a;
+  }
+  return out;
+}
+async function loadGroup(args) {
+  const mod = await import(args.configPath);
+  return mod.default(args.group);
+}
+async function runInspectGroup(args, log) {
+  if (!args.configPath) {
+    log("usage: klum inspect-group <config> --group=<name> [--vault=<id>]");
+    return 2;
+  }
+  const group = await loadGroup(args);
+  const inspector = createInspector(groupInspector(group));
+  const vaults = await inspector.listVaults();
+  log(`group "${args.group ?? ""}" \u2014 ${vaults.length} shard(s):`);
+  for (const v of vaults) log(`  ${v.id} [${v.role}]`);
+  if (args.vault) {
+    const vault = await group.db.openVault(args.vault);
+    group.template.configure(vault);
+    const snap = await inspector.snapshot(vault);
+    log(`  collections in ${args.vault}: ${snap.collections.map((c) => c.name).join(", ")}`);
+  }
+  return 0;
+}
+async function runMeterGroup(args, log) {
+  if (!args.configPath) {
+    log("usage: klum meter-group <config> --group=<name>");
+    return 2;
+  }
+  const group = await loadGroup(args);
+  const r = await meterGroup(group);
+  log(`group "${args.group ?? ""}" \u2014 ${r.vaults} vault(s), ${r.collections} collection(s), ${r.records} record(s)`);
+  for (const s of r.perShard) {
+    log(`  ${s.vaultId} (${s.partitionKey}) v${s.schemaVersion}: ${s.collections} coll, ${s.records} rec`);
+  }
+  if (r.skipped.length) log(`  skipped: ${r.skipped.length} shard(s)`);
+  return 0;
+}
+async function main(argv, log = console.log) {
+  const args = parseArgs(argv);
+  switch (args.command) {
+    case "inspect-group":
+      return runInspectGroup(args, log);
+    case "meter-group":
+      return runMeterGroup(args, log);
+    default:
+      log("klum <inspect-group|meter-group> <config> --group=<name> [--vault=<id>]");
+      return args.command ? 1 : 0;
+  }
+}
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  }).catch((e) => {
+    console.error(e);
+    process.exitCode = 1;
+  });
+}
+export {
+  main,
+  parseArgs,
+  runInspectGroup,
+  runMeterGroup
+};
+//# sourceMappingURL=klum.js.map

package/dist/bin/klum.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bin/klum.ts","../../src/federation/group-inspector.ts","../../src/federation/meter-group.ts"],"sourcesContent":["import { createInspector } from '@noy-db/in-devtools'\nimport { groupInspector } from '../federation/group-inspector.js'\nimport { meterGroup } from '../federation/meter-group.js'\nimport type { VaultGroup } from '../federation/vault-group.js'\n\n/**\n * A config module for the `klum` CLI default-exports this factory: given an\n * optional group name, it returns an opened VaultGroup (the user's module owns\n * the store, templates, and sharding config — the CLI stays agnostic of them).\n */\nexport type GroupFactory = (groupName?: string) => Promise<VaultGroup<unknown>>\n\ntype Log = (s: string) => void\n\nexport interface ParsedArgs {\n  command: string\n  configPath?: string\n  group?: string\n  vault?: string\n  meter: boolean\n}\n\nexport function parseArgs(argv: readonly string[]): ParsedArgs {\n  const out: ParsedArgs = { command: argv[0] ?? '', meter: false }\n  for (const a of argv.slice(1)) {\n    if (a.startsWith('--group=')) out.group = a.slice('--group='.length)\n    else if (a.startsWith('--vault=')) out.vault = a.slice('--vault='.length)\n    else if (a === '--meter') out.meter = true\n    else if (!a.startsWith('--')) out.configPath = a\n  }\n  return out\n}\n\nasync function loadGroup(args: ParsedArgs): Promise<VaultGroup<unknown>> {\n  const mod = (await import(args.configPath!)) as { default: GroupFactory }\n  return mod.default(args.group)\n}\n\nexport async function runInspectGroup(args: ParsedArgs, log: Log): Promise<number> {\n  if (!args.configPath) {\n    log('usage: klum inspect-group <config> --group=<name> [--vault=<id>]')\n    return 2\n  }\n  const group = await loadGroup(args)\n  const inspector = createInspector(groupInspector(group))\n  const vaults = await inspector.listVaults()\n  log(`group \"${args.group ?? ''}\" — ${vaults.length} shard(s):`)\n  for (const v of vaults) log(`  ${v.id} [${v.role}]`)\n  if (args.vault) {\n    const vault = await group.db.openVault(args.vault)\n    group.template.configure(vault)\n    const snap = await inspector.snapshot(vault)\n    log(`  collections in ${args.vault}: ${snap.collections.map((c) => c.name).join(', ')}`)\n  }\n  return 0\n}\n\nexport async function runMeterGroup(args: ParsedArgs, log: Log): Promise<number> {\n  if (!args.configPath) {\n    log('usage: klum meter-group <config> --group=<name>')\n    return 2\n  }\n  const group = await loadGroup(args)\n  const r = await meterGroup(group)\n  log(`group \"${args.group ?? ''}\" — ${r.vaults} vault(s), ${r.collections} collection(s), ${r.records} record(s)`)\n  for (const s of r.perShard) {\n    log(`  ${s.vaultId} (${s.partitionKey}) v${s.schemaVersion}: ${s.collections} coll, ${s.records} rec`)\n  }\n  if (r.skipped.length) log(`  skipped: ${r.skipped.length} shard(s)`)\n  return 0\n}\n\nexport async function main(argv: readonly string[], log: Log = console.log): Promise<number> {\n  const args = parseArgs(argv)\n  switch (args.command) {\n    case 'inspect-group':\n      return runInspectGroup(args, log)\n    case 'meter-group':\n      return runMeterGroup(args, log)\n    default:\n      log('klum <inspect-group|meter-group> <config> --group=<name> [--vault=<id>]')\n      return args.command ? 1 : 0\n  }\n}\n\n// bin entrypoint — only runs when executed directly, not when imported in tests.\nif (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {\n  main(process.argv.slice(2))\n    .then((code) => {\n      process.exitCode = code\n    })\n    .catch((e: unknown) => {\n      console.error(e)\n      process.exitCode = 1\n    })\n}\n","import type { InspectableContainer } from '@noy-db/in-devtools'\nimport type { AccessibleVault, Vault, WriteHook, WriteConflict, WriteQueue, Unsubscribe } from '@noy-db/hub'\nimport type { VaultGroup } from './vault-group.js'\n\n/**\n * Adapt a federation {@link VaultGroup} to the dev-tools `InspectableContainer`\n * contract from `@noy-db/in-devtools`, so the inspector / TUI can browse a\n * whole fleet exactly like a single instance.\n *\n * Built entirely on the group's public surface (`allRows`, `db`, `template`) —\n * no `VaultGroup` changes, and (critically) no `@klum-db` import lands in any\n * `@noy-db` package: the dependency runs one way, klum → noy.\n *\n * Write-event scoping: `group.db` may host vaults outside this group, so write\n * and conflict events are filtered to the group's shard ids. The id set is\n * primed/refreshed on every `listAccessibleVaults()` call — drive `listVaults()`\n * (the inspector's normal first step) before relying on event scoping.\n */\nexport function groupInspector<T>(group: VaultGroup<T>): InspectableContainer {\n  let shardIds = new Set<string>()\n  const refresh = async () => {\n    const rows = await group.allRows()\n    shardIds = new Set(rows.map((r) => r.vaultId))\n    return rows\n  }\n  return {\n    async listAccessibleVaults(): Promise<readonly AccessibleVault[]> {\n      const rows = await refresh()\n      return rows.map((r): AccessibleVault => ({ id: r.vaultId, role: 'owner' }))\n    },\n    async openVault(name: string): Promise<Vault> {\n      const vault = await group.db.openVault(name)\n      group.template.configure(vault)\n      return vault\n    },\n    onAfterWrite(handler: WriteHook): Unsubscribe {\n      return group.db.onAfterWrite((event) => {\n        if (shardIds.has(event.vault)) return handler(event)\n      })\n    },\n    onWriteConflict(handler: (c: WriteConflict) => void): Unsubscribe {\n      return group.db.onWriteConflict((c) => {\n        if (shardIds.has(c.vault)) handler(c)\n      })\n    },\n    get writeQueue(): WriteQueue {\n      return group.db.writeQueue\n    },\n  }\n}\n","import type { VaultGroup } from './vault-group.js'\nimport type { SkippedVault } from './types.js'\n\nexport interface GroupShardMetrics {\n  readonly vaultId: string\n  readonly partitionKey: string\n  readonly schemaVersion: number\n  readonly collections: number\n  readonly records: number\n}\n\nexport interface GroupMeterReport {\n  /** Number of eligible shards measured. */\n  readonly vaults: number\n  /** Distinct collection names across the group. */\n  readonly collections: number\n  /** Total record count summed across shards. */\n  readonly records: number\n  readonly perShard: ReadonlyArray<GroupShardMetrics>\n  /** Drifted / provisioning-failed shards — surfaced, never counted or hidden. */\n  readonly skipped: ReadonlyArray<SkippedVault>\n}\n\n/**\n * Fan shape-metrics (collection count + record count) across the group's\n * ELIGIBLE shards. Skipped shards (schema-drift / provisioning failures) are\n * reported in `skipped`, never silently dropped. Reuses the per-vault pattern\n * from `multi-bundle.ts` (`vault.collections()` → `collection(n).count()`).\n *\n * Operational store metrics (calls, CAS conflicts) are a separate concern and\n * are already group-wide via `@noy-db/to-meter` on the underlying store.\n */\nexport async function meterGroup<T>(\n  group: VaultGroup<T>,\n  opts: { minVersion?: number } = {},\n): Promise<GroupMeterReport> {\n  const { eligible, skipped } = await group.resolveEligible(\n    opts.minVersion !== undefined ? { minVersion: opts.minVersion } : {},\n  )\n  const perShard: GroupShardMetrics[] = []\n  const names = new Set<string>()\n  let records = 0\n  for (const row of eligible) {\n    const vault = await group.shard(row.partitionKey)\n    const collNames = await vault.collections()\n    let shardRecords = 0\n    for (const n of collNames) {\n      names.add(n)\n      shardRecords += await vault.collection(n).count()\n    }\n    records += shardRecords\n    perShard.push({\n      vaultId: row.vaultId,\n      partitionKey: row.partitionKey,\n      schemaVersion: row.schemaVersion,\n      collections: collNames.length,\n      records: shardRecords,\n    })\n  }\n  return { vaults: eligible.length, collections: names.size, records, perShard, skipped }\n}\n"],"mappings":"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","names":[]}