@klum-db/lobby 0.2.0-pre.27 → 0.2.0-pre.29

package/README.md

@@ -67,7 +67,7 @@ lobby.withVaultTemplate('client', { version: 1, configure: v => v.collection('in
 const group = await lobby.openVaultGroup('clients', { registry, sharding: { keyOf, vaultTemplate: 'client', autoCreate: true } })
 await group.shard('acme-co').collection('invoices').put('i1', { id: 'i1', total: '1200.00' })
 const all = await group.queryAcross(/* … */)          // fan-out read across shards
-await group.migrateFleet({ batchSize: 4 })             // resumable, registry-tracked
+await group.rolloutSchema({ batchSize: 4 })             // resumable, registry-tracked
 ```
 
 ### 2 · Interchange — move data between vaults, safely
@@ -137,11 +137,11 @@ await lobby.applySurface('tax-vault', surface, bundleBytes, transferKey)
 
 - **Depends on `@noy-db/hub`**, binds to the stable **`@noy-db/hub/kernel`** subpath — never reaches into hub internals.
 - **Custody is a vault-level concern** and lives *in* hub (keyring/CEK/consent primitives); the Lobby **re-exports** it (`createDeedOwner`, `liberateVault`, `CustodyApi`) so consumers have one import surface.
-- **Federation** was extracted *out of* hub into the Lobby (a breaking pre-1.0 change): `Noydb.openVaultGroup` now throws `FederationMovedError` — use `lobby.openVaultGroup`.
+- **Federation** lives in the Lobby, not in hub — open fleets with `lobby.openVaultGroup` (`@noy-db/hub` no longer ships the `openVaultGroup` / `openStateManagementVault` / `withVaultTemplate` fleet methods).
 - The dependency is enforced one-way at build time; an `@noy-db` package importing `@klum-db` fails the architecture check.
 
 ## Status
 
-Preview, developed inside the noy-db monorepo while the kernel boundary stabilizes (it graduates to its own repo once proven). Versions track noy-db in lockstep. Pilot-1 epic (FR-1…FR-9) complete.
+Preview. `@klum-db/lobby` is its own repository and the sole publisher of `@klum-db/*` to npm. It depends on the **published** `@noy-db/*` packages through the stable `@noy-db/hub/kernel` boundary and versions **independently** (`0.2.0-pre.N`, decoupled from noy-db). Pilot-1 (FR-1…FR-9), the dock tier, and `Lobby.graduate()` are complete.
 
-Design spec: [`docs/superpowers/specs/2026-06-16-lobby-framework-design.md`](../../docs/superpowers/specs/2026-06-16-lobby-framework-design.md). Runnable showcases: [`showcases/src/12x-klum-*`](../../showcases/src).
+See [`PROVENANCE.md`](./PROVENANCE.md) for origin and build history.

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-BXjO5kHB.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-BXjO5kHB.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":[]}

package/dist/index.cjs

@@ -1415,13 +1415,13 @@ var init_vault_group = __esm({
     SHARD_SEPARATOR = "--";
     SAFE_PARTITION_KEY = /^[A-Za-z0-9._-]+$/;
     VaultGroup = class {
-      constructor(db, name, registry, sharding, template, migrateOnOpen = false) {
+      constructor(db, name, registry, sharding, template, cutoverOnOpen = false) {
         this.db = db;
         this.name = name;
         this.registry = registry;
         this.sharding = sharding;
         this.template = template;
-        this.migrateOnOpen = migrateOnOpen;
+        this.cutoverOnOpen = cutoverOnOpen;
         if (name.includes(SHARD_SEPARATOR)) {
           throw new import_kernel10.ValidationError(
             `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
@@ -1433,7 +1433,7 @@ var init_vault_group = __esm({
       registry;
       sharding;
       template;
-      migrateOnOpen;
+      cutoverOnOpen;
       /** @internal — set when the group is managed (no explicit registry). */
       stateVault;
       /** @internal */
@@ -1468,20 +1468,20 @@ var init_vault_group = __esm({
         return rows.filter((r) => r.group === this.name);
       }
       /**
-       * Open an existing shard and apply the template. When `migrateOnOpen` is set
+       * Open an existing shard and apply the template. When `cutoverOnOpen` is set
        * (#271) and the shard's registry version is behind the template, its cutover
        * runs inline first — so a behind shard never surfaces a stale handle.
        */
       async openShard(partitionKey) {
-        if (this.migrateOnOpen) {
+        if (this.cutoverOnOpen) {
           const row = await this.registry.get(this.registryId(partitionKey));
           if (row && row.schemaVersion < this.template.version) {
-            await this.migrateShard(partitionKey);
+            await this.cutoverShard(partitionKey);
           }
         }
         return this._openShardRaw(partitionKey);
       }
-      /** @internal — open + configure with no migrate-on-open hook (used by the migration path itself to avoid recursion). */
+      /** @internal — open + configure with no cutover-on-open hook (used by the migration path itself to avoid recursion). */
       async _openShardRaw(partitionKey) {
         const vault = await this.db.openVault(this.shardVaultId(partitionKey), { create: false });
         this.template.configure(vault);
@@ -1703,7 +1703,7 @@ var init_vault_group = __esm({
        * Never throws on a cutover failure — it records `status: 'failed'` and
        * returns the row, so a fleet run continues past a bad shard.
        */
-      async migrateShard(partitionKey) {
+      async cutoverShard(partitionKey) {
         const vaultId = this.shardVaultId(partitionKey);
         const row = await this.registry.get(this.registryId(partitionKey));
         if (!row) throw new import_kernel10.UnknownShardError(partitionKey, this.name);
@@ -1754,7 +1754,7 @@ var init_vault_group = __esm({
        * - `batchSize` — max shards migrated concurrently per batch (back-pressure).
        *   Default 4. Batches run sequentially; shards within a batch run in parallel.
        */
-      async migrateFleet(options = {}) {
+      async rolloutSchema(options = {}) {
         const target = this.template.version;
         const rows = await this.allRows();
         const cohort = options.cohort;
@@ -1766,7 +1766,7 @@ var init_vault_group = __esm({
         const failed = [];
         for (let i = 0; i < todo.length; i += batchSize) {
           const batch = todo.slice(i, i + batchSize);
-          const settled = await Promise.all(batch.map((r) => this.migrateShard(r.partitionKey)));
+          const settled = await Promise.all(batch.map((r) => this.cutoverShard(r.partitionKey)));
           for (const res of settled) {
             if (res.status === "done") migrated.push(res.vaultId);
             else failed.push({ vaultId: res.vaultId, error: res.error ?? "unknown" });
@@ -2015,6 +2015,7 @@ __export(index_exports, {
   encodeMultiBundle: () => encodeMultiBundle,
   exportSurface: () => exportSurface,
   extractCrossVaultPartition: () => extractCrossVaultPartition,
+  groupInspector: () => groupInspector,
   isDeedVault: () => import_hub6.isDeedVault,
   isSurfaceDue: () => isSurfaceDue,
   liberateVault: () => import_hub6.liberateVault,
@@ -2023,6 +2024,7 @@ __export(index_exports, {
   markSynced: () => markSynced,
   mergeCompartment: () => mergeCompartment,
   mergeDecryptedRecords: () => mergeDecryptedRecords,
+  meterGroup: () => meterGroup,
   migrateThenMerge: () => migrateThenMerge,
   proposeSurface: () => proposeSurface,
   readMultiVaultBundleCompartment: () => readMultiVaultBundleCompartment,
@@ -2053,6 +2055,68 @@ var DockedUnit = class {
   }
 };
 
+// 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/index.ts
 var import_kernel12 = require("@noy-db/hub/kernel");
 init_multi_bundle();
@@ -2150,7 +2214,7 @@ var Lobby = class {
     const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
     const stateVault = opts.registry ? void 0 : await StateManagementVault2.open(db);
     const registry = opts.registry ?? stateVault.registry;
-    const group = new VaultGroup2(db, name, registry, opts.sharding, template, opts.migrateOnOpen ?? false);
+    const group = new VaultGroup2(db, name, registry, opts.sharding, template, opts.cutoverOnOpen ?? false);
     if (stateVault) {
       group._attachStateVault(stateVault);
       await stateVault.recordManifest(opts.sharding.vaultTemplate, template);
@@ -2283,6 +2347,7 @@ function createLobby(noydb) {
   encodeMultiBundle,
   exportSurface,
   extractCrossVaultPartition,
+  groupInspector,
   isDeedVault,
   isSurfaceDue,
   liberateVault,
@@ -2291,6 +2356,7 @@ function createLobby(noydb) {
   markSynced,
   mergeCompartment,
   mergeDecryptedRecords,
+  meterGroup,
   migrateThenMerge,
   proposeSurface,
   readMultiVaultBundleCompartment,