@klum-db/lobby 0.3.0-pre.1 → 0.4.0-pre.1

package/dist/index.cjs

@@ -30,6 +30,396 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/portal/share-link.ts
+var share_link_exports = {};
+__export(share_link_exports, {
+  ShareLinkResolutionError: () => ShareLinkResolutionError,
+  buildShareLinkForClient: () => buildShareLinkForClient,
+  resolveShareLinkAgainstRegistry: () => resolveShareLinkAgainstRegistry
+});
+async function registryRows(registry) {
+  await registry.list();
+  return registry.query().toArray();
+}
+async function resolveShareLinkAgainstRegistry(link, registry) {
+  const parsed = typeof link === "string" || link instanceof URL ? (0, import_share_link.parseShareLink)(link) : link;
+  const rows = await registryRows(registry);
+  const row = rows.find((r) => r.handle === parsed.vaultHandle);
+  if (!row) {
+    throw new ShareLinkResolutionError(
+      "UNKNOWN_VAULT_HANDLE",
+      `share link addresses vault handle "${parsed.vaultHandle}", which is not registered in this fleet.`
+    );
+  }
+  return {
+    link: parsed,
+    row,
+    consoleRoute: {
+      vaultId: row.vaultId,
+      collection: parsed.collection,
+      recordId: parsed.recordId,
+      ...parsed.period !== void 0 ? { period: parsed.period } : {},
+      ...parsed.version !== void 0 ? { version: parsed.version } : {}
+    }
+  };
+}
+async function buildShareLinkForClient(opts, registry) {
+  const rows = await registryRows(registry);
+  const row = rows.find((r) => r.partitionKey === opts.client && r.group === opts.group);
+  if (!row) {
+    throw new ShareLinkResolutionError(
+      "UNKNOWN_CLIENT",
+      `client "${opts.client}" is not registered in group "${opts.group}".`
+    );
+  }
+  if (row.handle === void 0) {
+    throw new ShareLinkResolutionError(
+      "NO_PORTAL_HANDLE",
+      `client "${opts.client}" has no portal vault handle \u2014 provision the portal before minting share links.`
+    );
+  }
+  return (0, import_share_link.buildShareLink)(
+    {
+      vaultHandle: row.handle,
+      collection: opts.collection,
+      recordId: opts.record,
+      ...opts.period !== void 0 ? { period: opts.period } : {},
+      ...opts.version !== void 0 ? { version: opts.version } : {},
+      ...opts.grantToken !== void 0 ? { grantToken: opts.grantToken } : {}
+    },
+    opts.base
+  );
+}
+var import_share_link, ShareLinkResolutionError;
+var init_share_link = __esm({
+  "src/portal/share-link.ts"() {
+    "use strict";
+    import_share_link = require("@noy-db/hub/share-link");
+    ShareLinkResolutionError = class extends Error {
+      constructor(code, message) {
+        super(message);
+        this.code = code;
+      }
+      code;
+      name = "ShareLinkResolutionError";
+    };
+  }
+});
+
+// src/federation/insight-auto-push.ts
+var InsightAutoPush;
+var init_insight_auto_push = __esm({
+  "src/federation/insight-auto-push.ts"() {
+    "use strict";
+    InsightAutoPush = class {
+      constructor(recompute, isSource, onError = (err, pk) => console.warn(`[klum-db] insight auto-push failed for shard "${pk}":`, err), debounceMs) {
+        this.recompute = recompute;
+        this.isSource = isSource;
+        this.onError = onError;
+        this.debounceMs = debounceMs;
+      }
+      recompute;
+      isSource;
+      onError;
+      debounceMs;
+      dirty = /* @__PURE__ */ new Set();
+      pending = null;
+      timer = null;
+      resolvePending = null;
+      flushing = false;
+      /** Called from a shard's onAfterWrite hook. Marks the shard dirty + schedules a flush. */
+      noteWrite(partitionKey, collection) {
+        if (!this.isSource(collection)) return;
+        this.dirty.add(partitionKey);
+        if (this.debounceMs !== void 0) this.scheduleDebounced();
+        else this.schedule();
+      }
+      /** Resolve once no flush is pending (drains rescheduled flushes too). */
+      async whenSettled() {
+        while (this.pending) await this.pending;
+      }
+      // ── microtask path (unchanged default) ──
+      schedule() {
+        if (this.pending) return;
+        this.pending = this.runFlush().finally(() => {
+          this.pending = null;
+          if (this.dirty.size > 0) this.schedule();
+        });
+      }
+      // ── debounce path (#13) ──
+      scheduleDebounced() {
+        if (!this.pending) this.pending = new Promise((r) => {
+          this.resolvePending = r;
+        });
+        if (this.timer) clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+          this.timer = null;
+          if (this.flushing) return;
+          this.flushing = true;
+          void this.runFlush().finally(() => {
+            this.flushing = false;
+            if (this.dirty.size > 0) {
+              this.scheduleDebounced();
+            } else {
+              const resolve = this.resolvePending;
+              this.resolvePending = null;
+              this.pending = null;
+              resolve?.();
+            }
+          });
+        }, this.debounceMs);
+      }
+      async runFlush() {
+        await Promise.resolve();
+        const pks = [...this.dirty];
+        this.dirty.clear();
+        for (const pk of pks) {
+          try {
+            await this.recompute(pk);
+          } catch (err) {
+            this.onError(err, pk);
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/federation/read-model.ts
+var read_model_exports = {};
+__export(read_model_exports, {
+  PostureViolationError: () => PostureViolationError,
+  ReadModel: () => ReadModel,
+  deriveShardSummary: () => deriveShardSummary,
+  openReadModel: () => openReadModel
+});
+function deriveShardSummary(spec, records, row) {
+  const ctx = {
+    vaultId: row.vaultId,
+    partitionKey: row.partitionKey,
+    schemaVersion: row.schemaVersion
+  };
+  return spec.derive(records, ctx);
+}
+function checkPosture(model, row, shard) {
+  const declared = new Set(model.posture.surface);
+  const undeclared = Object.keys(row).filter((k) => !declared.has(k) && !PROVENANCE_FIELDS.has(k));
+  if (undeclared.length > 0) throw new PostureViolationError(model.name, undeclared, shard);
+}
+async function openReadModel(group, opts) {
+  const target = opts.vault;
+  if (target === group.name || target.startsWith(`${group.name}--`)) {
+    throw new import_cargo.ValidationError(
+      `openReadModel: vault "${target}" is the "${group.name}" group itself or one of its shards \u2014 the read-model must live outside the group it composes.`
+    );
+  }
+  if (opts.models.length === 0) {
+    throw new import_cargo.ValidationError("openReadModel: at least one model is required.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of opts.models) {
+    if (seen.has(m.name)) throw new import_cargo.ValidationError(`openReadModel: duplicate model name "${m.name}".`);
+    seen.add(m.name);
+    if (m.posture.surface.length === 0) {
+      throw new import_cargo.ValidationError(`openReadModel: model "${m.name}" declares an empty posture.surface.`);
+    }
+  }
+  const vault = await group.db.openVault(target);
+  const rm = new ReadModel(group, target, vault, opts.models, opts.shards);
+  const autoPush = opts.freshness?.autoPush;
+  if (autoPush) rm._armAutoPush(autoPush === true ? {} : autoPush);
+  return rm;
+}
+var import_cargo, PostureViolationError, PROVENANCE_FIELDS, ReadModel;
+var init_read_model = __esm({
+  "src/federation/read-model.ts"() {
+    "use strict";
+    import_cargo = require("@noy-db/hub/cargo");
+    init_insight_auto_push();
+    PostureViolationError = class extends Error {
+      constructor(model, fields, shard) {
+        super(
+          `read-model "${model}": derive emitted undeclared field(s) [${fields.join(", ")}] for shard "${shard}" \u2014 every emitted field must be listed in posture.surface (fail closed; nothing was written).`
+        );
+        this.model = model;
+        this.fields = fields;
+        this.shard = shard;
+      }
+      model;
+      fields;
+      shard;
+      name = "PostureViolationError";
+    };
+    PROVENANCE_FIELDS = /* @__PURE__ */ new Set(["_shard", "_sourceId", "_sourceVersion"]);
+    ReadModel = class {
+      /** @internal */
+      constructor(group, vaultName, vault, models, shards) {
+        this.group = group;
+        this.vaultName = vaultName;
+        this.vault = vault;
+        this.models = models;
+        this.shards = shards;
+      }
+      group;
+      vaultName;
+      vault;
+      models;
+      shards;
+      /** @internal — auto-push controller; armed by {@link _armAutoPush}. */
+      autoPush;
+      /**
+       * @internal — wire the #13 controller (spec § 3). Trigger is the
+       * Noydb-level change stream filtered to this group's shard vaults
+       * (`<group>--<pk>`); the read-model vault can never match that prefix
+       * (guarded at open), so its own writes can't loop back. Recompute is
+       * a per-shard `refresh({ only })` — rollup re-reduces and mirror
+       * reconciles just that shard; other shards' rows are untouched
+       * (registered shards are preserved by the reconcile asymmetry).
+       */
+      _armAutoPush(cfg) {
+        const controller = new InsightAutoPush(
+          async (partitionKey) => {
+            await this.refresh({
+              only: [partitionKey],
+              ...cfg.minVersion !== void 0 ? { minVersion: cfg.minVersion } : {}
+            });
+          },
+          (collection) => this.models.some((m) => m.source === collection),
+          void 0,
+          cfg.debounceMs
+        );
+        this.autoPush = controller;
+        const prefix = `${this.group.name}--`;
+        this.group.db.on("change", (e) => {
+          if (!e.vault.startsWith(prefix)) return;
+          controller.noteWrite(e.vault.slice(prefix.length), e.collection);
+        });
+      }
+      /**
+       * Await any pending auto-push flush. Resolves immediately when
+       * `freshness.autoPush` is off or nothing is pending.
+       */
+      async whenSettled() {
+        if (this.autoPush) await this.autoPush.whenSettled();
+      }
+      /** An output collection of the read-model vault (keyed by model `name`). */
+      collection(model) {
+        return this.vault.collection(model);
+      }
+      /**
+       * Explicit refresh: for each model, read every eligible shard's
+       * `source`, posture-check, and write — rollup: one summary row per
+       * shard (id = partitionKey); mirror: one row per source record
+       * (id = `${shard}:${idOf(row)}`). Every row is stamped with `_shard`
+       * + `_sourceVersion` (mirror rows additionally `_sourceId`).
+       *
+       * Reconciliation (spec § 4): rows whose source record is gone, and
+       * all rows of a shard that LEFT the group, are deleted (`retracted`).
+       * Rows of a merely-unreachable shard are PRESERVED — offline is not
+       * departure; those shards land in `skippedVaults` instead.
+       */
+      async refresh(options = {}) {
+        const resolved = await this.group.resolveEligible({
+          ...options.minVersion !== void 0 ? { minVersion: options.minVersion } : {},
+          ...options.only !== void 0 ? { only: options.only } : {},
+          ...options.failFast !== void 0 ? { failFast: options.failFast } : {}
+        });
+        const eligible = this.shards ? resolved.eligible.filter((r) => this.shards(r)) : resolved.eligible;
+        const skipped = resolved.skipped;
+        let written = 0;
+        let retracted = 0;
+        for (const model of this.models) {
+          const results = await this.group.db.queryAcross(
+            eligible.map((r) => r.vaultId),
+            async (vault) => {
+              this.group.template.configure(vault);
+              const coll = vault.collection(model.source);
+              const records = await coll.list();
+              if (model.kind === "rollup") return records.map((record) => ({ record, id: "", version: 0 }));
+              return Promise.all(records.map(async (record) => {
+                const id = model.idOf(record);
+                const meta = await coll.getMetadata(id);
+                return { record, id, version: meta?.version ?? 0 };
+              }));
+            },
+            { create: false, ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {} }
+          );
+          const out = this.vault.collection(model.name);
+          const expected = /* @__PURE__ */ new Set();
+          const healthyShards = /* @__PURE__ */ new Set();
+          for (let i = 0; i < eligible.length; i++) {
+            const row = eligible[i];
+            const res = results[i];
+            if (!res || res.result === void 0) {
+              if (options.failFast && res?.error) throw res.error;
+              if (!skipped.some((s) => s.vaultId === row.vaultId)) {
+                skipped.push({ vaultId: row.vaultId, reason: "error", ...res?.error ? { error: res.error } : {} });
+              }
+              continue;
+            }
+            healthyShards.add(row.partitionKey);
+            if (model.kind === "rollup") {
+              const summary = deriveShardSummary(model, res.result.map((e) => e.record), row);
+              checkPosture(model, summary, row.partitionKey);
+              await out.put(row.partitionKey, {
+                ...summary,
+                _shard: row.partitionKey,
+                _sourceVersion: row.schemaVersion
+              });
+              expected.add(row.partitionKey);
+              written++;
+            } else {
+              for (const entry of res.result) {
+                checkPosture(model, entry.record, row.partitionKey);
+                const id = `${row.partitionKey}:${entry.id}`;
+                await out.put(id, {
+                  ...entry.record,
+                  _shard: row.partitionKey,
+                  _sourceId: entry.id,
+                  _sourceVersion: entry.version
+                });
+                expected.add(id);
+                written++;
+              }
+            }
+          }
+          retracted += await this.reconcile(out, model, expected, healthyShards);
+        }
+        return { written, retracted, skippedVaults: skipped };
+      }
+      /**
+       * Delete stale rows: id not in `expected` AND the row's shard is
+       * healthy this refresh (source record deleted), no longer in the
+       * group registry (shard departed), or outside the audience predicate
+       * (scope narrowed — out-of-scope data never lingers, spec § 5).
+       * Unreachable-but-registered in-scope shards are preserved.
+       */
+      async reconcile(out, model, expected, healthyShards) {
+        await this.group.registry.list();
+        const registryRows2 = new Map(
+          this.group.registry.query().toArray().filter((r) => r.group === this.group.name).map((r) => [r.partitionKey, r])
+        );
+        await out.list();
+        const rows = out.query().toArray();
+        let retracted = 0;
+        for (const row of rows) {
+          const shard = row["_shard"];
+          if (shard === void 0) continue;
+          const id = model.kind === "rollup" ? shard : `${shard}:${String(row["_sourceId"])}`;
+          if (expected.has(id)) continue;
+          const registryRow = registryRows2.get(shard);
+          const outOfScope = registryRow !== void 0 && this.shards !== void 0 && !this.shards(registryRow);
+          if (healthyShards.has(shard) || registryRow === void 0 || outOfScope) {
+            await out.delete(id);
+            retracted++;
+          }
+        }
+        return retracted;
+      }
+    };
+  }
+});
+
 // src/bundle/uint32.ts
 function readUint32BE(bytes, offset) {
   return (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
@@ -72,6 +462,11 @@ function encodeMultiBundle(manifest, inner) {
   }
   return out;
 }
+function hasPodMagic(bytes) {
+  if (bytes.length < import_pod.NOYDB_BUNDLE_MAGIC.length) return false;
+  for (let i = 0; i < import_pod.NOYDB_BUNDLE_MAGIC.length; i++) if (bytes[i] !== import_pod.NOYDB_BUNDLE_MAGIC[i]) return false;
+  return true;
+}
 function hasMultiMagic(bytes) {
   if (bytes.length < NOYDB_MULTI_BUNDLE_MAGIC.length) return false;
   for (let i = 0; i < NOYDB_MULTI_BUNDLE_MAGIC.length; i++) if (bytes[i] !== NOYDB_MULTI_BUNDLE_MAGIC[i]) return false;
@@ -135,7 +530,7 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
       handle: header.handle,
       exportedAt: c.exportedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
       innerBytes: innerBytes.length,
-      innerSha256: await (0, import_cargo.sha256Hex)(innerBytes)
+      innerSha256: await (0, import_cargo2.sha256Hex)(innerBytes)
     };
     if (c.roleTag !== void 0) entry.roleTag = c.roleTag;
     if (c.disclose?.name !== void 0 && c.disclose.name !== false) {
@@ -148,7 +543,7 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
       );
     }
     if (c.disclose?.publicEnvelope === true) {
-      const env = (0, import_hub.readNoydbBundlePublicEnvelope)(innerBytes);
+      const env = (0, import_pod.readPodCover)(innerBytes);
       if (env !== void 0) entry.publicEnvelope = env;
     }
     const fence = await c.vault.schemaFenceState();
@@ -158,20 +553,20 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
   }
   const manifest = {
     multiFormatVersion: NOYDB_MULTI_BUNDLE_VERSION,
-    handle: opts.handle ?? (0, import_cargo.generateULID)(),
+    handle: opts.handle ?? (0, import_cargo2.generateULID)(),
     compartments: entries
   };
   return encodeMultiBundle(manifest, inner);
 }
 async function readNoydbBundleManifest(bytes) {
   if (hasMultiMagic(bytes)) return [...decodeMultiBundle(bytes).manifest.compartments];
-  if ((0, import_hub.hasNoydbBundleMagic)(bytes)) {
+  if (hasPodMagic(bytes)) {
     const header = (0, import_pod.readPodHeader)(bytes);
-    const env = (0, import_hub.readNoydbBundlePublicEnvelope)(bytes);
+    const env = (0, import_pod.readPodCover)(bytes);
     const entry = {
       handle: header.handle,
       innerBytes: bytes.length,
-      innerSha256: await (0, import_cargo.sha256Hex)(bytes)
+      innerSha256: await (0, import_cargo2.sha256Hex)(bytes)
     };
     if (env !== void 0) entry.publicEnvelope = env;
     return [entry];
@@ -182,7 +577,7 @@ function readMultiVaultBundleCompartment(bytes, selector) {
   if (typeof selector === "number" && !Number.isInteger(selector)) {
     throw new Error(`readMultiVaultBundleCompartment: numeric selector must be an integer, got ${selector}.`);
   }
-  if ((0, import_hub.hasNoydbBundleMagic)(bytes) && !hasMultiMagic(bytes)) {
+  if (hasPodMagic(bytes) && !hasMultiMagic(bytes)) {
     const header = (0, import_pod.readPodHeader)(bytes);
     if (selector === 0 || selector === header.handle) return bytes;
     throw new Error(`readMultiVaultBundleCompartment: single v1 bundle has only compartment "${header.handle}".`);
@@ -192,13 +587,12 @@ function readMultiVaultBundleCompartment(bytes, selector) {
   if (idx < 0 || idx >= inner.length) throw new Error(`readMultiVaultBundleCompartment: no compartment ${typeof selector === "number" ? `at index ${selector}` : `"${selector}"`}.`);
   return inner[idx];
 }
-var import_cargo, import_pod, import_hub, NOYDB_MULTI_BUNDLE_MAGIC, NOYDB_MULTI_BUNDLE_PREFIX_BYTES, NOYDB_MULTI_BUNDLE_VERSION;
+var import_cargo2, import_pod, NOYDB_MULTI_BUNDLE_MAGIC, NOYDB_MULTI_BUNDLE_PREFIX_BYTES, NOYDB_MULTI_BUNDLE_VERSION;
 var init_multi_bundle = __esm({
   "src/bundle/multi-bundle.ts"() {
     "use strict";
-    import_cargo = require("@noy-db/hub/cargo");
+    import_cargo2 = require("@noy-db/hub/cargo");
     import_pod = require("@noy-db/hub/pod");
-    import_hub = require("@noy-db/hub");
     init_uint32();
     NOYDB_MULTI_BUNDLE_MAGIC = new Uint8Array([78, 68, 66, 77]);
     NOYDB_MULTI_BUNDLE_PREFIX_BYTES = 10;
@@ -271,7 +665,7 @@ async function walkCrossVaultClosure(openVault, opts) {
     for (const vaultName of batch) {
       const seeds = perVaultSeeds.get(vaultName);
       const v = await openVault(vaultName);
-      const { closure } = await (0, import_bundle.walkClosure)(v, {
+      const { closure } = await (0, import_cargo3.walkClosure)(v, {
         seeds,
         ...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {}
       });
@@ -323,7 +717,7 @@ async function extractCrossVaultPartition(openVault, opts) {
   const sealIds = {};
   for (const [vaultName, seeds] of plan.perVaultSeeds) {
     const v = await openVault(vaultName);
-    const { bundleBytes, transferKey, sealId } = await (0, import_bundle.extractPartition)(v, {
+    const { bundleBytes, transferKey, sealId } = await (0, import_cargo3.extractPartition)(v, {
       seeds,
       ...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {},
       carrySchemas: opts.carrySchemas ?? true,
@@ -336,7 +730,7 @@ async function extractCrossVaultPartition(openVault, opts) {
       handle: header.handle,
       exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
       innerBytes: bundleBytes.length,
-      innerSha256: await (0, import_cargo2.sha256Hex)(bundleBytes)
+      innerSha256: await (0, import_cargo4.sha256Hex)(bundleBytes)
     };
     if (meta?.roleTag !== void 0) entry.roleTag = meta.roleTag;
     if (meta?.disclose?.name !== void 0 && meta.disclose.name !== false) {
@@ -355,7 +749,7 @@ async function extractCrossVaultPartition(openVault, opts) {
   }
   const manifest = {
     multiFormatVersion: NOYDB_MULTI_BUNDLE_VERSION,
-    handle: (0, import_cargo2.generateULID)(),
+    handle: (0, import_cargo4.generateULID)(),
     compartments
   };
   return { bundle: encodeMultiBundle(manifest, inner), transferKeys, sealIds };
@@ -365,7 +759,7 @@ async function describeCrossVaultExtraction(openVault, opts) {
   const compartments = [];
   for (const [vaultName, seeds] of plan.perVaultSeeds) {
     const v = await openVault(vaultName);
-    const preview = await (0, import_bundle.describeExtraction)(v, {
+    const preview = await (0, import_cargo3.describeExtraction)(v, {
       seeds,
       ...opts.maxDepth !== void 0 ? { maxDepth: opts.maxDepth } : {}
     });
@@ -373,13 +767,13 @@ async function describeCrossVaultExtraction(openVault, opts) {
   }
   return { compartments, dangling: plan.dangling };
 }
-var import_bundle, import_pod2, import_cargo2, CrossVaultDanglingRefError;
+var import_cargo3, import_pod2, import_cargo4, CrossVaultDanglingRefError;
 var init_extract_cross_vault = __esm({
   "src/interchange/extract-cross-vault.ts"() {
     "use strict";
-    import_bundle = require("@noy-db/hub/bundle");
+    import_cargo3 = require("@noy-db/hub/cargo");
     import_pod2 = require("@noy-db/hub/pod");
-    import_cargo2 = require("@noy-db/hub/cargo");
+    import_cargo4 = require("@noy-db/hub/cargo");
     init_multi_bundle();
     CrossVaultDanglingRefError = class extends Error {
       constructor(dangling) {
@@ -465,7 +859,7 @@ async function mergeDecryptedRecords(receiver, decrypted, opts) {
     incomingSource.set(coll, srcMap);
     incomingSourceTs.set(coll, stsMap);
   }
-  const diff = await (0, import_cargo3.diffVault)(receiver, candidate);
+  const diff = await (0, import_cargo5.diffVault)(receiver, candidate);
   const byCollection = {};
   const conflicts = [];
   const writes = [];
@@ -581,15 +975,15 @@ async function mergeDecryptedRecords(receiver, decrypted, opts) {
   };
 }
 async function mergeCompartment(receiver, compartmentBytes, opts) {
-  const incoming = await (0, import_bundle2.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
+  const incoming = await (0, import_cargo6.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
   return mergeDecryptedRecords(receiver, incoming, opts);
 }
-var import_cargo3, import_bundle2, FieldLevelDeferredError;
+var import_cargo5, import_cargo6, FieldLevelDeferredError;
 var init_merge_compartment = __esm({
   "src/interchange/merge-compartment.ts"() {
     "use strict";
-    import_cargo3 = require("@noy-db/hub/cargo");
-    import_bundle2 = require("@noy-db/hub/bundle");
+    import_cargo5 = require("@noy-db/hub/cargo");
+    import_cargo6 = require("@noy-db/hub/cargo");
     init_field_authority();
     FieldLevelDeferredError = class extends Error {
       constructor(collection) {
@@ -685,7 +1079,7 @@ async function graduate(noydb, docked, opts) {
   await mergeDecryptedRecords(vault, staged, { strategy: "take-incoming", reason: "dock:graduate" });
   let deedSealed = false;
   if (opts.deed) {
-    await (0, import_cargo4.createDeedOwner)(noydb._store, opts.vaultName, opts.deed.ownerId, opts.deed.sealingProvider);
+    await (0, import_cargo8.createDeedOwner)(noydb._store, opts.vaultName, opts.deed.ownerId, opts.deed.sealingProvider);
     deedSealed = true;
   }
   if (opts.stateVault) {
@@ -705,11 +1099,11 @@ async function graduate(noydb, docked, opts) {
     event: { type: "unit-graduated", unitId: docked.unitId, vault: opts.vaultName }
   };
 }
-var import_cargo4, UnitGraduationError, ISO_EPOCH;
+var import_cargo8, UnitGraduationError, ISO_EPOCH;
 var init_graduate = __esm({
   "src/dock/graduate.ts"() {
     "use strict";
-    import_cargo4 = require("@noy-db/hub/cargo");
+    import_cargo8 = require("@noy-db/hub/cargo");
     init_merge_compartment();
     init_stage_records();
     UnitGraduationError = class extends Error {
@@ -739,7 +1133,7 @@ __export(surface_exports, {
 async function proposeSurface(smv, def, proposedBy, now) {
   const row = {
     ...def,
-    id: def.id ?? (0, import_cargo5.generateULID)(),
+    id: def.id ?? (0, import_cargo9.generateULID)(),
     status: "proposed",
     proposedBy,
     createdAt: now
@@ -760,7 +1154,7 @@ async function exportSurface(source, surface) {
     throw new SurfaceStateError(surface.id, surface.status, "agreed");
   }
   const seeds = Object.fromEntries(surface.collections.map((c) => [c, () => true]));
-  const { bundleBytes, transferKey } = await (0, import_bundle4.extractPartition)(source, {
+  const { bundleBytes, transferKey } = await (0, import_cargo10.extractPartition)(source, {
     seeds,
     maxDepth: 0,
     ...surface.fields ? { fieldProjection: surface.fields } : {},
@@ -798,12 +1192,12 @@ async function markSynced(smv, id, now) {
     nextSyncDueAt: now + cadenceMs
   });
 }
-var import_cargo5, import_bundle4, SurfaceNotFoundError, SurfaceStateError, SurfaceCadenceScheduler;
+var import_cargo9, import_cargo10, SurfaceNotFoundError, SurfaceStateError, SurfaceCadenceScheduler;
 var init_surface = __esm({
   "src/interchange/surface.ts"() {
     "use strict";
-    import_cargo5 = require("@noy-db/hub/cargo");
-    import_bundle4 = require("@noy-db/hub/bundle");
+    import_cargo9 = require("@noy-db/hub/cargo");
+    import_cargo10 = require("@noy-db/hub/cargo");
     init_merge_compartment();
     SurfaceNotFoundError = class extends Error {
       name = "SurfaceNotFoundError";
@@ -908,38 +1302,38 @@ function canonical(value) {
   return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
 }
 async function fingerprintBlueprint(bp) {
-  return (0, import_cargo6.sha256Hex)(new TextEncoder().encode(canonical(bp)));
+  return (0, import_cargo11.sha256Hex)(new TextEncoder().encode(canonical(bp)));
 }
-var import_cargo6;
+var import_cargo11;
 var init_schema_manifest = __esm({
   "src/federation/schema-manifest.ts"() {
     "use strict";
-    import_cargo6 = require("@noy-db/hub/cargo");
+    import_cargo11 = require("@noy-db/hub/cargo");
   }
 });
 
 // src/federation/constants.ts
-var import_cargo7;
+var import_cargo12;
 var init_constants = __esm({
   "src/federation/constants.ts"() {
     "use strict";
-    import_cargo7 = require("@noy-db/hub/cargo");
+    import_cargo12 = require("@noy-db/hub/cargo");
   }
 });
 
 // src/federation/state-vault.ts
 var state_vault_exports = {};
 __export(state_vault_exports, {
-  STATE_VAULT_NAME: () => import_cargo7.STATE_VAULT_NAME,
+  STATE_VAULT_NAME: () => import_cargo12.STATE_VAULT_NAME,
   StateManagementVault: () => StateManagementVault
 });
-var import_cargo8, REGISTRY, MANIFEST, EVENTS, MIGRATION_STATUS, SURFACES, StateManagementVault;
+var import_cargo13, REGISTRY, MANIFEST, EVENTS, MIGRATION_STATUS, SURFACES, StateManagementVault;
 var init_state_vault = __esm({
   "src/federation/state-vault.ts"() {
     "use strict";
     init_schema_manifest();
     init_constants();
-    import_cargo8 = require("@noy-db/hub/cargo");
+    import_cargo13 = require("@noy-db/hub/cargo");
     init_constants();
     REGISTRY = "vaultRegistry";
     MANIFEST = "schemaManifest";
@@ -969,7 +1363,7 @@ var init_state_vault = __esm({
       #surfaces;
       /** Idempotently open the reserved state vault and bind the control-plane collections. */
       static async open(db) {
-        const vault = await db.openVault(import_cargo7.STATE_VAULT_NAME);
+        const vault = await db.openVault(import_cargo12.STATE_VAULT_NAME);
         return new _StateManagementVault(
           vault.collection(REGISTRY),
           vault.collection(MANIFEST),
@@ -1029,7 +1423,7 @@ var init_state_vault = __esm({
        */
       async appendEvent(event) {
         const ts = event.ts ?? Date.now();
-        const id = (0, import_cargo8.generateULID)();
+        const id = (0, import_cargo13.generateULID)();
         await this.#events.put(id, { ...event, id, ts });
       }
       /**
@@ -1071,13 +1465,13 @@ var init_state_vault = __esm({
 
 // src/federation/classify-skip.ts
 function classifyShardSkip(err) {
-  return err instanceof import_cargo9.NoAccessError ? "no-grant" : "error";
+  return err instanceof import_cargo14.NoAccessError ? "no-grant" : "error";
 }
-var import_cargo9;
+var import_cargo14;
 var init_classify_skip = __esm({
   "src/federation/classify-skip.ts"() {
     "use strict";
-    import_cargo9 = require("@noy-db/hub/cargo");
+    import_cargo14 = require("@noy-db/hub/cargo");
   }
 });
 
@@ -1102,7 +1496,7 @@ async function applyBroadcastLegs(rows, legs) {
   for (const leg of legs) {
     const map = /* @__PURE__ */ new Map();
     for (const rec of await leg.from.list()) {
-      const k = coerceKey((0, import_cargo10.readPath)(rec, leg.on));
+      const k = coerceKey((0, import_cargo15.readPath)(rec, leg.on));
       if (k !== null && !map.has(k)) map.set(k, rec);
     }
     indexes.push({ leg, map });
@@ -1110,7 +1504,7 @@ async function applyBroadcastLegs(rows, legs) {
   return rows.map((row) => {
     const out = { ...row };
     for (const { leg, map } of indexes) {
-      const key = coerceKey((0, import_cargo10.readPath)(row, leg.field));
+      const key = coerceKey((0, import_cargo15.readPath)(row, leg.field));
       const match = key === null ? null : map.get(key) ?? null;
       if (match === null && leg.mode === "warn") {
         warnOnceBroadcastMiss(leg.field, leg.as, key ?? "<null>");
@@ -1120,11 +1514,11 @@ async function applyBroadcastLegs(rows, legs) {
     return out;
   });
 }
-var import_cargo10, warnedBroadcastKeys;
+var import_cargo15, warnedBroadcastKeys;
 var init_cross_shard_join = __esm({
   "src/federation/cross-shard-join.ts"() {
     "use strict";
-    import_cargo10 = require("@noy-db/hub/cargo");
+    import_cargo15 = require("@noy-db/hub/cargo");
     warnedBroadcastKeys = /* @__PURE__ */ new Set();
   }
 });
@@ -1218,85 +1612,6 @@ var init_cross_vault_live = __esm({
   }
 });
 
-// src/federation/insight-auto-push.ts
-var InsightAutoPush;
-var init_insight_auto_push = __esm({
-  "src/federation/insight-auto-push.ts"() {
-    "use strict";
-    InsightAutoPush = class {
-      constructor(recompute, isSource, onError = (err, pk) => console.warn(`[klum-db] insight auto-push failed for shard "${pk}":`, err), debounceMs) {
-        this.recompute = recompute;
-        this.isSource = isSource;
-        this.onError = onError;
-        this.debounceMs = debounceMs;
-      }
-      recompute;
-      isSource;
-      onError;
-      debounceMs;
-      dirty = /* @__PURE__ */ new Set();
-      pending = null;
-      timer = null;
-      resolvePending = null;
-      flushing = false;
-      /** Called from a shard's onAfterWrite hook. Marks the shard dirty + schedules a flush. */
-      noteWrite(partitionKey, collection) {
-        if (!this.isSource(collection)) return;
-        this.dirty.add(partitionKey);
-        if (this.debounceMs !== void 0) this.scheduleDebounced();
-        else this.schedule();
-      }
-      /** Resolve once no flush is pending (drains rescheduled flushes too). */
-      async whenSettled() {
-        while (this.pending) await this.pending;
-      }
-      // ── microtask path (unchanged default) ──
-      schedule() {
-        if (this.pending) return;
-        this.pending = this.runFlush().finally(() => {
-          this.pending = null;
-          if (this.dirty.size > 0) this.schedule();
-        });
-      }
-      // ── debounce path (#13) ──
-      scheduleDebounced() {
-        if (!this.pending) this.pending = new Promise((r) => {
-          this.resolvePending = r;
-        });
-        if (this.timer) clearTimeout(this.timer);
-        this.timer = setTimeout(() => {
-          this.timer = null;
-          if (this.flushing) return;
-          this.flushing = true;
-          void this.runFlush().finally(() => {
-            this.flushing = false;
-            if (this.dirty.size > 0) {
-              this.scheduleDebounced();
-            } else {
-              const resolve = this.resolvePending;
-              this.resolvePending = null;
-              this.pending = null;
-              resolve?.();
-            }
-          });
-        }, this.debounceMs);
-      }
-      async runFlush() {
-        await Promise.resolve();
-        const pks = [...this.dirty];
-        this.dirty.clear();
-        for (const pk of pks) {
-          try {
-            await this.recompute(pk);
-          } catch (err) {
-            this.onError(err, pk);
-          }
-        }
-      }
-    };
-  }
-});
-
 // src/federation/partial-reduce.ts
 function canPartialReduce(spec) {
   return Object.values(spec).every((r) => typeof r.merge === "function");
@@ -1335,12 +1650,12 @@ var init_partial_reduce = __esm({
 });
 
 // src/federation/aggregate-across.ts
-var import_cargo11, import_cargo12, CrossVaultAggregation, CrossVaultGroupedAggregation;
+var import_cargo16, import_cargo17, CrossVaultAggregation, CrossVaultGroupedAggregation;
 var init_aggregate_across = __esm({
   "src/federation/aggregate-across.ts"() {
     "use strict";
-    import_cargo11 = require("@noy-db/hub/cargo");
-    import_cargo12 = require("@noy-db/hub/cargo");
+    import_cargo16 = require("@noy-db/hub/cargo");
+    import_cargo17 = require("@noy-db/hub/cargo");
     init_cross_vault_live();
     init_partial_reduce();
     CrossVaultAggregation = class {
@@ -1358,7 +1673,7 @@ var init_aggregate_across = __esm({
           return { result: finalizePartial(this.spec, mergePartials(this.spec, partials)), skippedVaults: skippedVaults2 };
         }
         const { records, skippedVaults } = await this.src.fanoutRecords(options);
-        return { result: (0, import_cargo11.reduceRecords)(records, this.spec), skippedVaults };
+        return { result: (0, import_cargo16.reduceRecords)(records, this.spec), skippedVaults };
       }
       live(options = {}) {
         if (!this.bind) throw new Error("CrossVaultAggregation: live() requires a LiveBinding \u2014 use ShardedQuery.aggregate()");
@@ -1369,7 +1684,7 @@ var init_aggregate_across = __esm({
           isRelevant: this.bind.isRelevant,
           compute: async () => {
             const { records, skippedVaults } = await src.fanoutRecords(options);
-            return { value: (0, import_cargo11.reduceRecords)(records, spec), skipped: skippedVaults };
+            return { value: (0, import_cargo16.reduceRecords)(records, spec), skipped: skippedVaults };
           },
           initialSnapshot: { value: void 0, skipped: [] },
           ...options.debounceMs !== void 0 ? { debounceMs: options.debounceMs } : {}
@@ -1404,7 +1719,7 @@ var init_aggregate_across = __esm({
       async run(options = {}) {
         const { records, skippedVaults } = await this.src.fanoutRecords(options);
         return {
-          results: (0, import_cargo12.groupAndReduce)(records, this.field, this.spec),
+          results: (0, import_cargo17.groupAndReduce)(records, this.field, this.spec),
           skippedVaults
         };
       }
@@ -1419,7 +1734,7 @@ var init_aggregate_across = __esm({
           compute: async () => {
             const { records, skippedVaults } = await src.fanoutRecords(options);
             return {
-              records: (0, import_cargo12.groupAndReduce)(records, field, spec),
+              records: (0, import_cargo17.groupAndReduce)(records, field, spec),
               skipped: skippedVaults
             };
           },
@@ -1492,7 +1807,7 @@ async function retrieveAcross(group, collectionName, query, opts = {}) {
     }
     return pv.hits.map((h) => ({ ...h, id: pv.vault + SEP + h.id }));
   });
-  const fused = (0, import_cargo13.fuseRetrieval)(lists, {
+  const fused = (0, import_cargo18.fuseRetrieval)(lists, {
     ...opts.limit !== void 0 ? { limit: opts.limit } : {},
     ...opts.rrfK !== void 0 ? { k: opts.rrfK } : {}
   });
@@ -1502,11 +1817,11 @@ async function retrieveAcross(group, collectionName, query, opts = {}) {
   });
   return { hits, skippedVaults };
 }
-var import_cargo13, SEP;
+var import_cargo18, SEP;
 var init_retrieve_across = __esm({
   "src/federation/retrieve-across.ts"() {
     "use strict";
-    import_cargo13 = require("@noy-db/hub/cargo");
+    import_cargo18 = require("@noy-db/hub/cargo");
     init_classify_skip();
     SEP = "\0";
   }
@@ -1526,30 +1841,31 @@ function autoPushConfig(spec) {
 }
 function assertSafePartitionKey(partitionKey) {
   if (partitionKey.length === 0) {
-    throw new import_cargo14.ValidationError("partitionKey must be a non-empty string");
+    throw new import_cargo19.ValidationError("partitionKey must be a non-empty string");
   }
-  if (partitionKey === import_cargo7.STATE_VAULT_NAME) {
-    throw new import_cargo14.ReservedVaultNameError(partitionKey);
+  if (partitionKey === import_cargo12.STATE_VAULT_NAME) {
+    throw new import_cargo19.ReservedVaultNameError(partitionKey);
   }
   if (!SAFE_PARTITION_KEY.test(partitionKey)) {
-    throw new import_cargo14.ValidationError(
+    throw new import_cargo19.ValidationError(
       `partitionKey "${partitionKey}" contains characters outside [A-Za-z0-9._-]. Map your records to a store-safe key in sharding.keyOf.`
     );
   }
   if (partitionKey.includes(SHARD_SEPARATOR)) {
-    throw new import_cargo14.ValidationError(
+    throw new import_cargo19.ValidationError(
       `partitionKey "${partitionKey}" must not contain "--" \u2014 it is reserved as the shard vault-id separator and would risk shard-id collisions.`
     );
   }
 }
-var import_cargo14, SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQuery, ShardedGroupedQuery;
+var import_cargo19, SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQuery, ShardedGroupedQuery;
 var init_vault_group = __esm({
   "src/federation/vault-group.ts"() {
     "use strict";
     init_state_vault();
-    import_cargo14 = require("@noy-db/hub/cargo");
+    import_cargo19 = require("@noy-db/hub/cargo");
     init_constants();
     init_classify_skip();
+    init_read_model();
     init_cross_shard_join();
     init_cross_vault_live();
     init_insight_auto_push();
@@ -1568,7 +1884,7 @@ var init_vault_group = __esm({
         this.cutoverOnOpen = cutoverOnOpen;
         this.meta = meta;
         if (name.includes(SHARD_SEPARATOR)) {
-          throw new import_cargo14.ValidationError(
+          throw new import_cargo19.ValidationError(
             `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
           );
         }
@@ -1673,11 +1989,11 @@ var init_vault_group = __esm({
         const vaultId = this.shardVaultId(partitionKey);
         const row = await this.registry.get(this.registryId(partitionKey));
         const provisioned = await this.db._shardVaultProvisioned(vaultId);
-        if (row && !provisioned) throw new import_cargo14.ShardProvisioningError(vaultId, partitionKey);
+        if (row && !provisioned) throw new import_cargo19.ShardProvisioningError(vaultId, partitionKey);
         if (row && provisioned) return this.openShard(partitionKey);
         if (region !== void 0) {
           const backendRegion = this.db._resolveBackend(vaultId).capabilities?.region;
-          if (backendRegion !== region) throw new import_cargo14.DataResidencyError(vaultId, region, backendRegion);
+          if (backendRegion !== region) throw new import_cargo19.DataResidencyError(vaultId, region, backendRegion);
         }
         const vault = await this.db.openVault(vaultId);
         this.template.configure(vault);
@@ -1711,9 +2027,9 @@ var init_vault_group = __esm({
       async shard(partitionKey) {
         const vaultId = this.shardVaultId(partitionKey);
         const row = await this.registry.get(this.registryId(partitionKey));
-        if (!row) throw new import_cargo14.UnknownShardError(partitionKey, this.name);
+        if (!row) throw new import_cargo19.UnknownShardError(partitionKey, this.name);
         const provisioned = await this.db._shardVaultProvisioned(vaultId);
-        if (!provisioned) throw new import_cargo14.ShardProvisioningError(vaultId, partitionKey);
+        if (!provisioned) throw new import_cargo19.ShardProvisioningError(vaultId, partitionKey);
         return this.openShard(partitionKey);
       }
       /** A sharded view over one logical collection across all shards. */
@@ -1745,7 +2061,7 @@ var init_vault_group = __esm({
         for (const p of probes) {
           if ("error" in p) skipped.push({ vaultId: p.row.vaultId, reason: "error", error: p.error });
           else if (p.provisioned) eligible.push(p.row);
-          else skipped.push({ vaultId: p.row.vaultId, reason: "error", error: new import_cargo14.ShardProvisioningError(p.row.vaultId, p.row.partitionKey) });
+          else skipped.push({ vaultId: p.row.vaultId, reason: "error", error: new import_cargo19.ShardProvisioningError(p.row.vaultId, p.row.partitionKey) });
         }
         return { eligible, skipped };
       }
@@ -1782,7 +2098,7 @@ var init_vault_group = __esm({
       withCrossVaultDerivation(spec) {
         const target = spec.target.vault;
         if (target === this.name || target.startsWith(`${this.name}${SHARD_SEPARATOR}`)) {
-          throw new import_cargo14.ValidationError(
+          throw new import_cargo19.ValidationError(
             `withCrossVaultDerivation: target.vault "${target}" is the "${this.name}" group itself or one of its shards \u2014 an Insight summary must target a SEPARATE analytics vault, never write back into client-shard data (it would breach the per-shard DEK boundary). Use a distinct vault name.`
           );
         }
@@ -1842,12 +2158,7 @@ var init_vault_group = __esm({
               skipped.push({ vaultId: row.vaultId, reason: "error", ...res?.error ? { error: res.error } : {} });
               continue;
             }
-            const ctx = {
-              vaultId: row.vaultId,
-              partitionKey: row.partitionKey,
-              schemaVersion: row.schemaVersion
-            };
-            const summary = spec.derive(res.result, ctx);
+            const summary = deriveShardSummary(spec, res.result, row);
             await out.put(row.partitionKey, summary);
             written++;
           }
@@ -1867,17 +2178,12 @@ var init_vault_group = __esm({
         const row = await this.registry.get(this.registryId(partitionKey));
         if (!row) return;
         const shard = await this.openShard(partitionKey);
-        const ctx = {
-          vaultId: row.vaultId,
-          partitionKey,
-          schemaVersion: row.schemaVersion
-        };
         for (const spec of this.crossVaultDerivations) {
           if (!spec.autoPush) continue;
           const min = autoPushConfig(spec)?.minVersion;
           if (min !== void 0 && row.schemaVersion < min) continue;
           const records = await shard.collection(spec.source).list();
-          const summary = spec.derive(records, ctx);
+          const summary = deriveShardSummary(spec, records, row);
           const insight = await this.db.openVault(spec.target.vault);
           await insight.collection(spec.target.collection).put(partitionKey, summary);
         }
@@ -1908,7 +2214,7 @@ var init_vault_group = __esm({
       async cutoverShard(partitionKey) {
         const vaultId = this.shardVaultId(partitionKey);
         const row = await this.registry.get(this.registryId(partitionKey));
-        if (!row) throw new import_cargo14.UnknownShardError(partitionKey, this.name);
+        if (!row) throw new import_cargo19.UnknownShardError(partitionKey, this.name);
         const target = this.template.version;
         const sv = await this.ensureStateVault();
         const base = { vaultId, group: this.name, currentVersion: row.schemaVersion, targetVersion: target };
@@ -1991,7 +2297,7 @@ var init_vault_group = __esm({
         let vault;
         if (!row) {
           if (this.group.sharding.autoCreate === false) {
-            throw new import_cargo14.UnknownShardError(key, this.group.name);
+            throw new import_cargo19.UnknownShardError(key, this.group.name);
           }
           vault = await this.group.createShard(key, this.group.sharding.regionOf?.(record));
         } else {
@@ -2074,7 +2380,7 @@ var init_vault_group = __esm({
           this.group.template.configure(probe);
           for (const leg of this.coPartitionedLegs) {
             if (!probe.resolveRef(this.collectionName, leg.field)) {
-              throw new import_cargo14.CrossShardJoinError(
+              throw new import_cargo19.CrossShardJoinError(
                 `crossShardJoin("${leg.field}"): no ref() declared for "${leg.field}" on collection "${this.collectionName}" in template "${this.group.sharding.vaultTemplate}". Add refs: { ${leg.field}: ref('<target>') } to the template's collection options.`
               );
             }
@@ -2236,13 +2542,117 @@ var init_vault_group = __esm({
   }
 });
 
+// src/portal/provision.ts
+var provision_exports = {};
+__export(provision_exports, {
+  provisionPortal: () => provisionPortal,
+  revokePortalInvite: () => revokePortalInvite
+});
+async function requireRow(group, client) {
+  const row = await group.registry.get(group.registryId(client));
+  if (!row) throw new Error(`provisionPortal: client "${client}" has no registry row in group.`);
+  return row;
+}
+async function provisionPortal(db, group, opts) {
+  const existing = await group.registry.get(group.registryId(opts.client));
+  if (!existing) await group.createShard(opts.client);
+  const row = existing ?? await requireRow(group, opts.client);
+  const vaultId = row.vaultId;
+  for (const g of opts.firmGrants ?? []) {
+    await db.grant(vaultId, {
+      userId: g.userId,
+      displayName: g.displayName,
+      role: g.role,
+      passphrase: g.passphrase
+    });
+  }
+  const { issueInvite, issuePeerRecovery } = await import("@noy-db/on-magic-link");
+  const mode = opts.mode ?? "invite";
+  const issued = mode === "rebind" ? await issuePeerRecovery(db, vaultId, {
+    userId: opts.invite.userId,
+    displayName: opts.invite.displayName,
+    ...opts.invite.role !== void 0 ? { role: opts.invite.role } : {},
+    ...opts.invite.ttlMs !== void 0 ? { ttlMs: opts.invite.ttlMs } : {},
+    ...opts.invite.tempPhrase !== void 0 ? { tempPhrase: opts.invite.tempPhrase } : {}
+  }) : await issueInvite(db, vaultId, {
+    userId: opts.invite.userId,
+    displayName: opts.invite.displayName,
+    role: opts.invite.role ?? "client",
+    ...opts.invite.ttlMs !== void 0 ? { ttlMs: opts.invite.ttlMs } : {},
+    ...opts.invite.tempPhrase !== void 0 ? { tempPhrase: opts.invite.tempPhrase } : {}
+  });
+  const auditRef = {
+    tokenId: issued.payload.tokenId,
+    userId: opts.invite.userId,
+    kind: mode,
+    issuedAt: Date.now(),
+    expiresAt: issued.payload.expiresAt
+  };
+  const handle = row.handle ?? (0, import_cargo20.generateULID)();
+  const updated = {
+    ...row,
+    handle,
+    portal: {
+      enabledAt: row.portal?.enabledAt ?? Date.now(),
+      invites: [...row.portal?.invites ?? [], auditRef]
+    }
+  };
+  await group.registry.put(group.registryId(opts.client), updated);
+  return {
+    vaultId,
+    handle,
+    invite: {
+      encoded: issued.encoded,
+      tokenId: issued.payload.tokenId,
+      userId: opts.invite.userId,
+      expiresAt: issued.payload.expiresAt
+    },
+    row: updated
+  };
+}
+async function revokePortalInvite(db, group, opts) {
+  const row = await requireRow(group, opts.client);
+  const invites = row.portal?.invites ?? [];
+  const ref = invites.find((i) => i.tokenId === opts.tokenId);
+  if (!ref) {
+    throw new Error(`revokePortalInvite: no invite with tokenId "${opts.tokenId}" for client "${opts.client}".`);
+  }
+  if (ref.revokedAt !== void 0) return row;
+  const { revokeInvite } = await import("@noy-db/on-magic-link");
+  await revokeInvite(db, row.vaultId, {
+    tokenId: ref.tokenId,
+    vault: row.vaultId,
+    userId: ref.userId,
+    kind: ref.kind === "rebind" ? "peer-recovery" : "invite",
+    issuer: "",
+    tempPhrase: "",
+    expiresAt: ref.expiresAt
+  });
+  const updated = {
+    ...row,
+    portal: {
+      enabledAt: row.portal?.enabledAt ?? Date.now(),
+      invites: invites.map((i) => i.tokenId === opts.tokenId ? { ...i, revokedAt: Date.now() } : i)
+    }
+  };
+  await group.registry.put(group.registryId(opts.client), updated);
+  return updated;
+}
+var import_cargo20;
+var init_provision = __esm({
+  "src/portal/provision.ts"() {
+    "use strict";
+    import_cargo20 = require("@noy-db/hub/cargo");
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  CrossShardJoinError: () => import_cargo16.CrossShardJoinError,
+  CrossShardJoinError: () => import_cargo22.CrossShardJoinError,
   CrossVaultDanglingRefError: () => CrossVaultDanglingRefError,
-  CustodyApi: () => import_cargo17.CustodyApi,
-  DataResidencyError: () => import_cargo16.DataResidencyError,
+  CustodyApi: () => import_cargo23.CustodyApi,
+  DataResidencyError: () => import_cargo22.DataResidencyError,
   DockedUnit: () => DockedUnit,
   FieldAuthorityPolicyMissingError: () => FieldAuthorityPolicyMissingError,
   FieldLevelDeferredError: () => FieldLevelDeferredError,
@@ -2253,17 +2663,19 @@ __export(index_exports, {
   NOYDB_MULTI_BUNDLE_MAGIC: () => NOYDB_MULTI_BUNDLE_MAGIC,
   NOYDB_MULTI_BUNDLE_PREFIX_BYTES: () => NOYDB_MULTI_BUNDLE_PREFIX_BYTES,
   NOYDB_MULTI_BUNDLE_VERSION: () => NOYDB_MULTI_BUNDLE_VERSION,
-  ReservedVaultNameError: () => import_cargo16.ReservedVaultNameError,
-  ShardProvisioningError: () => import_cargo16.ShardProvisioningError,
+  PostureViolationError: () => PostureViolationError,
+  ReservedVaultNameError: () => import_cargo22.ReservedVaultNameError,
+  ShardProvisioningError: () => import_cargo22.ShardProvisioningError,
+  ShareLinkResolutionError: () => ShareLinkResolutionError,
   SurfaceCadenceScheduler: () => SurfaceCadenceScheduler,
   SurfaceNotFoundError: () => SurfaceNotFoundError,
   SurfaceStateError: () => SurfaceStateError,
   UnitGraduationError: () => UnitGraduationError,
-  UnknownShardError: () => import_cargo16.UnknownShardError,
-  VaultTemplateNotFoundError: () => import_cargo16.VaultTemplateNotFoundError,
+  UnknownShardError: () => import_cargo22.UnknownShardError,
+  VaultTemplateNotFoundError: () => import_cargo22.VaultTemplateNotFoundError,
   agreeSurface: () => agreeSurface,
   applySurface: () => applySurface,
-  createDeedOwner: () => import_cargo17.createDeedOwner,
+  createDeedOwner: () => import_cargo23.createDeedOwner,
   createLobby: () => createLobby,
   decodeMultiBundle: () => decodeMultiBundle,
   describeCrossVaultExtraction: () => describeCrossVaultExtraction,
@@ -2271,11 +2683,11 @@ __export(index_exports, {
   exportSurface: () => exportSurface,
   extractCrossVaultPartition: () => extractCrossVaultPartition,
   groupInspector: () => groupInspector,
-  isDeedVault: () => import_cargo17.isDeedVault,
+  isDeedVault: () => import_cargo23.isDeedVault,
   isSurfaceDue: () => isSurfaceDue,
-  liberateVault: () => import_cargo17.liberateVault,
+  liberateVault: () => import_cargo23.liberateVault,
   listDueSurfaces: () => listDueSurfaces,
-  loadDeedMarker: () => import_cargo17.loadDeedMarker,
+  loadDeedMarker: () => import_cargo23.loadDeedMarker,
   markSynced: () => markSynced,
   mergeCompartment: () => mergeCompartment,
   mergeDecryptedRecords: () => mergeDecryptedRecords,
@@ -2290,7 +2702,7 @@ __export(index_exports, {
   writeMultiVaultBundle: () => writeMultiVaultBundle
 });
 module.exports = __toCommonJS(index_exports);
-var import_cargo15 = require("@noy-db/hub/cargo");
+var import_cargo21 = require("@noy-db/hub/cargo");
 
 // src/dock/docked-unit.ts
 var DockedUnit = class {
@@ -2309,6 +2721,10 @@ var DockedUnit = class {
   }
 };
 
+// src/index.ts
+init_share_link();
+init_read_model();
+
 // src/federation/group-inspector.ts
 function groupInspector(group) {
   let shardIds = /* @__PURE__ */ new Set();
@@ -2372,13 +2788,13 @@ async function meterGroup(group, opts = {}) {
 }
 
 // src/index.ts
-var import_cargo16 = require("@noy-db/hub/cargo");
+var import_cargo22 = require("@noy-db/hub/cargo");
 init_multi_bundle();
 init_extract_cross_vault();
 init_merge_compartment();
 
 // src/interchange/migrate-then-merge.ts
-var import_bundle3 = require("@noy-db/hub/bundle");
+var import_cargo7 = require("@noy-db/hub/cargo");
 init_merge_compartment();
 init_stage_records();
 init_stage_records();
@@ -2403,7 +2819,7 @@ async function migrateThenMerge(receiver, compartmentBytes, opts) {
     );
   }
   if (fromVersion > toVersion) throw new MinVersionError(fromVersion, toVersion);
-  const incoming = await (0, import_bundle3.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
+  const incoming = await (0, import_cargo7.decryptExtractedPartition)(compartmentBytes, opts.transferKey);
   const transformsByCollection = {};
   const migrationByCollection = {};
   for (const [coll, recs] of Object.entries(incoming)) {
@@ -2426,7 +2842,7 @@ async function migrateThenMerge(receiver, compartmentBytes, opts) {
 
 // src/index.ts
 init_field_authority();
-var import_cargo17 = require("@noy-db/hub/cargo");
+var import_cargo23 = require("@noy-db/hub/cargo");
 
 // src/dock/unit-driver.ts
 var InMemoryUnitDriver = class {
@@ -2460,10 +2876,10 @@ var Lobby = class {
   }
   async openVaultGroup(name, opts) {
     const db = this.noydb;
-    if (db.isClosed) throw new import_cargo15.ValidationError("Instance is closed");
-    if (name === import_cargo15.STATE_VAULT_NAME) throw new import_cargo15.ReservedVaultNameError(name);
+    if (db.isClosed) throw new import_cargo21.ValidationError("Instance is closed");
+    if (name === import_cargo21.STATE_VAULT_NAME) throw new import_cargo21.ReservedVaultNameError(name);
     const template = this.vaultTemplates.get(opts.sharding.vaultTemplate);
-    if (!template) throw new import_cargo15.VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
+    if (!template) throw new import_cargo21.VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
     const { VaultGroup: VaultGroup2 } = await Promise.resolve().then(() => (init_vault_group(), vault_group_exports));
     const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
     const stateVault = opts.registry ? void 0 : await StateManagementVault2.open(db);
@@ -2482,7 +2898,7 @@ var Lobby = class {
   }
   async openStateManagementVault() {
     const db = this.noydb;
-    if (db.isClosed) throw new import_cargo15.ValidationError("Instance is closed");
+    if (db.isClosed) throw new import_cargo21.ValidationError("Instance is closed");
     const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
     return StateManagementVault2.open(db);
   }
@@ -2502,6 +2918,64 @@ var Lobby = class {
     const { graduate: graduateFn } = await Promise.resolve().then(() => (init_graduate(), graduate_exports));
     return graduateFn(this.noydb, docked, opts);
   }
+  // ─── Portal deep-link addressing (#43) ────────────────────────────────────
+  /**
+   * Resolve a portal share link (raw URL/path or a parsed `ShareLink`)
+   * against the fleet registry: `vaultHandle → registry row` plus a
+   * console-route descriptor the firm app turns into its own URL.
+   * Unknown/foreign handles fail closed with `ShareLinkResolutionError`.
+   * Delegates to `resolveShareLinkAgainstRegistry` in `portal/share-link.ts`.
+   */
+  async resolveShareLink(link, opts) {
+    const { resolveShareLinkAgainstRegistry: resolveShareLinkAgainstRegistry2 } = await Promise.resolve().then(() => (init_share_link(), share_link_exports));
+    return resolveShareLinkAgainstRegistry2(link, opts.registry);
+  }
+  /**
+   * Mint a portal share link for a fleet client (`client` partition key +
+   * `group`), delegating the link grammar to `@noy-db/hub/share-link`.
+   * Fails closed when the client is unknown or has no portal handle.
+   * Delegates to `buildShareLinkForClient` in `portal/share-link.ts`.
+   */
+  async buildShareLink(parts, opts) {
+    const { buildShareLinkForClient: buildShareLinkForClient2 } = await Promise.resolve().then(() => (init_share_link(), share_link_exports));
+    return buildShareLinkForClient2(parts, opts.registry);
+  }
+  // ─── Portal provisioning (#42) ────────────────────────────────────────────
+  /**
+   * Provision (or re-invite, `mode: 'rebind'`) a client portal vault in
+   * one audited operation: ensure the shard, assign the portal handle
+   * (#43's link target), apply firm grants, issue the magic-link invite,
+   * stamp the audit trail on the fleet registry row.
+   * Needs `@noy-db/on-magic-link` (optional peer) and a session created
+   * with `teamStrategy: withTeam()`.
+   * Delegates to `provisionPortal` in `portal/provision.ts`.
+   */
+  async provisionPortal(group, opts) {
+    const { provisionPortal: provisionPortalFn } = await Promise.resolve().then(() => (init_provision(), provision_exports));
+    return provisionPortalFn(this.noydb, group, opts);
+  }
+  /**
+   * Revoke an outstanding portal invite and stamp `revokedAt` on the
+   * fleet audit trail. Idempotent; fails closed on an unknown tokenId.
+   * Delegates to `revokePortalInvite` in `portal/provision.ts`.
+   */
+  async revokePortalInvite(group, opts) {
+    const { revokePortalInvite: revokePortalInviteFn } = await Promise.resolve().then(() => (init_provision(), provision_exports));
+    return revokePortalInviteFn(this.noydb, group, opts);
+  }
+  // ─── Federated read-model (#44) ───────────────────────────────────────────
+  /**
+   * Open a maintained federated read-model over `group` (#44 S1): rollup
+   * models reduce each shard's `source` into one summary row per shard in
+   * the read-model vault — deterministic ids, `_shard`/`_sourceVersion`
+   * provenance, fail-closed `posture.surface` allowlist, explicit
+   * `refresh()`. Spec: docs/federated-read-model.md.
+   * Delegates to `openReadModel` in `federation/read-model.ts`.
+   */
+  async openReadModel(group, opts) {
+    const { openReadModel: openReadModelFn } = await Promise.resolve().then(() => (init_read_model(), read_model_exports));
+    return openReadModelFn(group, opts);
+  }
   // ─── FR-7 Surface API ─────────────────────────────────────────────────────
   /**
    * Export a scoped partition from `vaultName` bounded to the given surface.
@@ -2584,8 +3058,10 @@ function createLobby(noydb) {
   NOYDB_MULTI_BUNDLE_MAGIC,
   NOYDB_MULTI_BUNDLE_PREFIX_BYTES,
   NOYDB_MULTI_BUNDLE_VERSION,
+  PostureViolationError,
   ReservedVaultNameError,
   ShardProvisioningError,
+  ShareLinkResolutionError,
   SurfaceCadenceScheduler,
   SurfaceNotFoundError,
   SurfaceStateError,