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

package/dist/index.js

@@ -8,6 +8,399 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/portal/share-link.ts
+var share_link_exports = {};
+__export(share_link_exports, {
+  ShareLinkResolutionError: () => ShareLinkResolutionError,
+  buildShareLinkForClient: () => buildShareLinkForClient,
+  resolveShareLinkAgainstRegistry: () => resolveShareLinkAgainstRegistry
+});
+import {
+  parseShareLink,
+  buildShareLink as buildShareLinkFromParts
+} from "@noy-db/hub/share-link";
+async function registryRows(registry) {
+  await registry.list();
+  return registry.query().toArray();
+}
+async function resolveShareLinkAgainstRegistry(link, registry) {
+  const parsed = typeof link === "string" || link instanceof URL ? 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 buildShareLinkFromParts(
+    {
+      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 ShareLinkResolutionError;
+var init_share_link = __esm({
+  "src/portal/share-link.ts"() {
+    "use strict";
+    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
+});
+import { ValidationError } from "@noy-db/hub/cargo";
+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 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 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 ValidationError(`openReadModel: duplicate model name "${m.name}".`);
+    seen.add(m.name);
+    if (m.posture.surface.length === 0) {
+      throw new 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 PostureViolationError, PROVENANCE_FIELDS, ReadModel;
+var init_read_model = __esm({
+  "src/federation/read-model.ts"() {
+    "use strict";
+    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;
@@ -28,12 +421,10 @@ var init_uint32 = __esm({
 import { sha256Hex, generateULID } from "@noy-db/hub/cargo";
 import {
   writePod,
-  readPodHeader
+  readPodHeader,
+  readPodCover,
+  NOYDB_BUNDLE_MAGIC
 } from "@noy-db/hub/pod";
-import {
-  readNoydbBundlePublicEnvelope,
-  hasNoydbBundleMagic
-} from "@noy-db/hub";
 function encodeMultiBundle(manifest, inner) {
   validateManifest(manifest);
   if (manifest.compartments.length !== inner.length) {
@@ -59,6 +450,11 @@ function encodeMultiBundle(manifest, inner) {
   }
   return out;
 }
+function hasPodMagic(bytes) {
+  if (bytes.length < NOYDB_BUNDLE_MAGIC.length) return false;
+  for (let i = 0; i < NOYDB_BUNDLE_MAGIC.length; i++) if (bytes[i] !== 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 +531,7 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
       );
     }
     if (c.disclose?.publicEnvelope === true) {
-      const env = readNoydbBundlePublicEnvelope(innerBytes);
+      const env = readPodCover(innerBytes);
       if (env !== void 0) entry.publicEnvelope = env;
     }
     const fence = await c.vault.schemaFenceState();
@@ -152,9 +548,9 @@ async function writeMultiVaultBundle(compartments, opts = {}) {
 }
 async function readNoydbBundleManifest(bytes) {
   if (hasMultiMagic(bytes)) return [...decodeMultiBundle(bytes).manifest.compartments];
-  if (hasNoydbBundleMagic(bytes)) {
+  if (hasPodMagic(bytes)) {
     const header = readPodHeader(bytes);
-    const env = readNoydbBundlePublicEnvelope(bytes);
+    const env = readPodCover(bytes);
     const entry = {
       handle: header.handle,
       innerBytes: bytes.length,
@@ -169,7 +565,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 (hasNoydbBundleMagic(bytes) && !hasMultiMagic(bytes)) {
+  if (hasPodMagic(bytes) && !hasMultiMagic(bytes)) {
     const header = readPodHeader(bytes);
     if (selector === 0 || selector === header.handle) return bytes;
     throw new Error(`readMultiVaultBundleCompartment: single v1 bundle has only compartment "${header.handle}".`);
@@ -202,7 +598,7 @@ import {
   walkClosure,
   extractPartition,
   describeExtraction
-} from "@noy-db/hub/bundle";
+} from "@noy-db/hub/cargo";
 import { readPodHeader as readPodHeader2 } from "@noy-db/hub/pod";
 import { sha256Hex as sha256Hex2, generateULID as generateULID2 } from "@noy-db/hub/cargo";
 function asIdArray(v) {
@@ -430,7 +826,7 @@ var init_field_authority = __esm({
 
 // src/interchange/merge-compartment.ts
 import { diffVault } from "@noy-db/hub/cargo";
-import { decryptExtractedPartition } from "@noy-db/hub/bundle";
+import { decryptExtractedPartition } from "@noy-db/hub/cargo";
 function strategyFor(opts, collection) {
   if (typeof opts === "string") return opts;
   return opts[collection] ?? opts.default ?? "manual-queue";
@@ -725,7 +1121,7 @@ __export(surface_exports, {
   proposeSurface: () => proposeSurface
 });
 import { generateULID as generateULID3 } from "@noy-db/hub/cargo";
-import { extractPartition as extractPartition2 } from "@noy-db/hub/bundle";
+import { extractPartition as extractPartition2 } from "@noy-db/hub/cargo";
 async function proposeSurface(smv, def, proposedBy, now) {
   const row = {
     ...def,
@@ -1203,85 +1599,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");
@@ -1505,25 +1822,25 @@ __export(vault_group_exports, {
   ShardedQuery: () => ShardedQuery,
   VaultGroup: () => VaultGroup
 });
-import { CrossShardJoinError, DataResidencyError, ReservedVaultNameError, ShardProvisioningError, UnknownShardError, ValidationError } from "@noy-db/hub/cargo";
+import { CrossShardJoinError, DataResidencyError, ReservedVaultNameError, ShardProvisioningError, UnknownShardError, ValidationError as ValidationError2 } from "@noy-db/hub/cargo";
 function autoPushConfig(spec) {
   if (!spec.autoPush) return null;
   return spec.autoPush === true ? {} : spec.autoPush;
 }
 function assertSafePartitionKey(partitionKey) {
   if (partitionKey.length === 0) {
-    throw new ValidationError("partitionKey must be a non-empty string");
+    throw new ValidationError2("partitionKey must be a non-empty string");
   }
   if (partitionKey === STATE_VAULT_NAME) {
     throw new ReservedVaultNameError(partitionKey);
   }
   if (!SAFE_PARTITION_KEY.test(partitionKey)) {
-    throw new ValidationError(
+    throw new ValidationError2(
       `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 ValidationError(
+    throw new ValidationError2(
       `partitionKey "${partitionKey}" must not contain "--" \u2014 it is reserved as the shard vault-id separator and would risk shard-id collisions.`
     );
   }
@@ -1535,6 +1852,7 @@ var init_vault_group = __esm({
     init_state_vault();
     init_constants();
     init_classify_skip();
+    init_read_model();
     init_cross_shard_join();
     init_cross_vault_live();
     init_insight_auto_push();
@@ -1553,7 +1871,7 @@ var init_vault_group = __esm({
         this.cutoverOnOpen = cutoverOnOpen;
         this.meta = meta;
         if (name.includes(SHARD_SEPARATOR)) {
-          throw new ValidationError(
+          throw new ValidationError2(
             `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
           );
         }
@@ -1767,7 +2085,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 ValidationError(
+          throw new ValidationError2(
             `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.`
           );
         }
@@ -1827,12 +2145,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++;
           }
@@ -1852,17 +2165,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);
         }
@@ -2221,8 +2529,111 @@ var init_vault_group = __esm({
   }
 });
 
+// src/portal/provision.ts
+var provision_exports = {};
+__export(provision_exports, {
+  provisionPortal: () => provisionPortal,
+  revokePortalInvite: () => revokePortalInvite
+});
+import { generateULID as generateULID5 } from "@noy-db/hub/cargo";
+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 ?? generateULID5();
+  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 init_provision = __esm({
+  "src/portal/provision.ts"() {
+    "use strict";
+  }
+});
+
 // src/index.ts
-import { ValidationError as ValidationError2, ReservedVaultNameError as ReservedVaultNameError2, VaultTemplateNotFoundError, STATE_VAULT_NAME as STATE_VAULT_NAME2 } from "@noy-db/hub/cargo";
+import { ValidationError as ValidationError3, ReservedVaultNameError as ReservedVaultNameError2, VaultTemplateNotFoundError, STATE_VAULT_NAME as STATE_VAULT_NAME2 } from "@noy-db/hub/cargo";
 
 // src/dock/docked-unit.ts
 var DockedUnit = class {
@@ -2241,6 +2652,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();
@@ -2320,7 +2735,7 @@ import {
 init_merge_compartment();
 init_stage_records();
 init_stage_records();
-import { decryptExtractedPartition as decryptExtractedPartition2 } from "@noy-db/hub/bundle";
+import { decryptExtractedPartition as decryptExtractedPartition2 } from "@noy-db/hub/cargo";
 var MinVersionError = class extends Error {
   constructor(fromVersion, toVersion) {
     super(
@@ -2399,7 +2814,7 @@ var Lobby = class {
   }
   async openVaultGroup(name, opts) {
     const db = this.noydb;
-    if (db.isClosed) throw new ValidationError2("Instance is closed");
+    if (db.isClosed) throw new ValidationError3("Instance is closed");
     if (name === STATE_VAULT_NAME2) throw new ReservedVaultNameError2(name);
     const template = this.vaultTemplates.get(opts.sharding.vaultTemplate);
     if (!template) throw new VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
@@ -2421,7 +2836,7 @@ var Lobby = class {
   }
   async openStateManagementVault() {
     const db = this.noydb;
-    if (db.isClosed) throw new ValidationError2("Instance is closed");
+    if (db.isClosed) throw new ValidationError3("Instance is closed");
     const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
     return StateManagementVault2.open(db);
   }
@@ -2441,6 +2856,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.
@@ -2522,8 +2995,10 @@ export {
   NOYDB_MULTI_BUNDLE_MAGIC,
   NOYDB_MULTI_BUNDLE_PREFIX_BYTES,
   NOYDB_MULTI_BUNDLE_VERSION,
+  PostureViolationError,
   ReservedVaultNameError3 as ReservedVaultNameError,
   ShardProvisioningError2 as ShardProvisioningError,
+  ShareLinkResolutionError,
   SurfaceCadenceScheduler,
   SurfaceNotFoundError,
   SurfaceStateError,