@remnic/core 9.69.56 → 9.69.57

package/dist/chunk-U2SK45U3.js

@@ -1,1476 +0,0 @@
-import {
-  resolveDefaultNamespaceRoot,
-  resolveNamespaceStorageRoot
-} from "./chunk-AH44WTLJ.js";
-import {
-  MutationSerializer,
-  withHeldFileLock
-} from "./chunk-FFAZ2XFU.js";
-import {
-  isSafeRouteNamespace
-} from "./chunk-PCXDUHQH.js";
-import {
-  namespaceIdentityFromToken,
-  namespaceIdentityLegacyToken,
-  namespaceIdentityToken,
-  normalizeNamespaceIdentity
-} from "./chunk-VUFL7X3H.js";
-import {
-  resolveNamespaceCapabilities
-} from "./chunk-JUOZ62Y7.js";
-import {
-  ALL_CATEGORY_DIRS
-} from "./chunk-VS2IYZRU.js";
-import {
-  isNotFoundError
-} from "./chunk-KNA3BXXL.js";
-
-// src/namespaces/catalog.ts
-import path from "path";
-import {
-  appendFile,
-  lstat,
-  mkdir,
-  open,
-  readdir,
-  realpath,
-  rename,
-  stat,
-  writeFile
-} from "fs/promises";
-import { StringDecoder } from "string_decoder";
-var NAMESPACE_KINDS = [
-  "default",
-  "shared",
-  "project",
-  "branch",
-  "team-project",
-  "explicit"
-];
-var NAMESPACE_DISCOVERY_SOURCES = [
-  "config",
-  "write",
-  "read",
-  "scan",
-  "migration"
-];
-var CATALOG_FILE = "namespaces.jsonl";
-var STATE_DIR = "state";
-var REBUILD_LOCK_FILE = "namespaces.rebuild.lock";
-var REBUILD_LOCK_STALE_MS = 3e4;
-var REBUILD_LOCK_MAX_WAIT_MS = 5e3;
-var REBUILD_LOCK_POLL_MS = 50;
-var REBUILD_LOCK_HEARTBEAT_MS = 1e4;
-var MEMORY_DATA_CHILDREN = [
-  ...ALL_CATEGORY_DIRS,
-  "entities",
-  "artifacts",
-  "identity",
-  "config",
-  "summaries",
-  "profile.md",
-  "state"
-];
-function isCatalogEnabled(config) {
-  if (resolveNamespaceCapabilities(config).namespaces !== true) return false;
-  return config.namespaceCatalogEnabled !== false;
-}
-var FILE_MEMORY_DATA_CHILDREN = /* @__PURE__ */ new Set(["profile.md"]);
-async function inspectMemoryDataMarker(rootDir, child) {
-  const childPath = path.join(rootDir, child);
-  let entry;
-  try {
-    entry = await lstat(childPath);
-  } catch (err) {
-    return isNotFoundError(err) ? { state: "absent" } : { state: "invalid", detail: `${child}: ${err instanceof Error ? err.message : String(err)}` };
-  }
-  if (entry.isSymbolicLink()) return { state: "invalid", detail: `${child}: symlink` };
-  if (FILE_MEMORY_DATA_CHILDREN.has(child)) {
-    return entry.isFile() ? { state: "valid" } : { state: "invalid", detail: `${child}: expected file` };
-  }
-  if (!entry.isDirectory()) return { state: "invalid", detail: `${child}: expected directory` };
-  try {
-    const rootReal = await realpath(rootDir);
-    const childReal = await realpath(childPath);
-    return isPathInside(rootReal, childReal) ? { state: "valid" } : { state: "invalid", detail: `${child}: escapes namespace root` };
-  } catch (err) {
-    return { state: "invalid", detail: `${child}: ${err instanceof Error ? err.message : String(err)}` };
-  }
-}
-async function inspectMemoryDataRoot(rootDir) {
-  let hasData = false;
-  for (const child of MEMORY_DATA_CHILDREN) {
-    const marker = await inspectMemoryDataMarker(rootDir, child);
-    if (marker.state === "invalid") {
-      return { hasData: false, invalidMarker: marker.detail };
-    }
-    if (marker.state === "valid") {
-      hasData = true;
-    }
-  }
-  return { hasData };
-}
-async function hasMemoryData(rootDir) {
-  return (await inspectMemoryDataRoot(rootDir)).hasData;
-}
-function isValidIsoTimestamp(value) {
-  const ms = Date.parse(value);
-  return Number.isFinite(ms);
-}
-function isNamespaceKind(value) {
-  return typeof value === "string" && NAMESPACE_KINDS.includes(value);
-}
-function isNamespaceDiscoverySource(value) {
-  return typeof value === "string" && NAMESPACE_DISCOVERY_SOURCES.includes(value);
-}
-function coerceRecord(value) {
-  if (typeof value !== "object" || value === null) return null;
-  const v = value;
-  if (typeof v.namespace !== "string") return null;
-  const namespace = normalizeNamespaceIdentity(v.namespace);
-  if (namespace.length === 0) return null;
-  if (typeof v.identityToken !== "string" || v.identityToken.length === 0) return null;
-  const expectedIdentityToken = namespaceIdentityToken(namespace);
-  if (v.identityToken !== expectedIdentityToken) return null;
-  if (typeof v.storageDir !== "string" || v.storageDir.length === 0) return null;
-  if (typeof v.createdAt !== "string" || v.createdAt.length === 0) return null;
-  if (!isValidIsoTimestamp(v.createdAt)) return null;
-  const kind = isNamespaceKind(v.kind) ? v.kind : "explicit";
-  const discoveredBy = v.discoveredBy === void 0 ? "scan" : isNamespaceDiscoverySource(v.discoveredBy) ? v.discoveredBy : null;
-  if (!discoveredBy) return null;
-  const record = {
-    namespace,
-    identityToken: expectedIdentityToken,
-    kind,
-    createdAt: v.createdAt,
-    storageDir: v.storageDir,
-    discoveredBy
-  };
-  if (typeof v.lastReadAt === "string" && isValidIsoTimestamp(v.lastReadAt)) {
-    record.lastReadAt = v.lastReadAt;
-  }
-  if (typeof v.lastWriteAt === "string" && isValidIsoTimestamp(v.lastWriteAt)) {
-    record.lastWriteAt = v.lastWriteAt;
-  }
-  if (v.lastMaintenanceAt && typeof v.lastMaintenanceAt === "object") {
-    const out = {};
-    for (const [k, val] of Object.entries(v.lastMaintenanceAt)) {
-      if (typeof val === "string" && isValidIsoTimestamp(val)) out[k] = val;
-    }
-    if (Object.keys(out).length > 0) record.lastMaintenanceAt = out;
-  }
-  return record;
-}
-function laterIso(a, b) {
-  if (!a) return b;
-  if (!b) return a;
-  const am = Date.parse(a);
-  const bm = Date.parse(b);
-  if (!Number.isFinite(am)) return b;
-  if (!Number.isFinite(bm)) return a;
-  return bm > am ? b : a;
-}
-function mergeNewerTouchFields(base, fresh) {
-  const merged = { ...base };
-  const lr = laterIso(base.lastReadAt, fresh.lastReadAt);
-  if (lr) merged.lastReadAt = lr;
-  const lw = laterIso(base.lastWriteAt, fresh.lastWriteAt);
-  if (lw) merged.lastWriteAt = lw;
-  if (base.lastMaintenanceAt || fresh.lastMaintenanceAt) {
-    const jobs = { ...base.lastMaintenanceAt ?? {} };
-    for (const [job, ts] of Object.entries(fresh.lastMaintenanceAt ?? {})) {
-      const latest = laterIso(jobs[job], ts);
-      if (latest) jobs[job] = latest;
-    }
-    if (Object.keys(jobs).length > 0) merged.lastMaintenanceAt = jobs;
-  }
-  return merged;
-}
-function serializeRecord(record) {
-  const ordered = {};
-  const source = record;
-  for (const key of Object.keys(source).sort()) {
-    const value = source[key];
-    if (value === void 0) continue;
-    if (key === "lastMaintenanceAt" && value && typeof value === "object") {
-      const sortedJobs = {};
-      for (const jobKey of Object.keys(value).sort()) {
-        sortedJobs[jobKey] = value[jobKey];
-      }
-      ordered[key] = sortedJobs;
-      continue;
-    }
-    ordered[key] = value;
-  }
-  return JSON.stringify(ordered);
-}
-function inferKind(namespace, config) {
-  if (namespace === normalizeNamespaceIdentity(config.defaultNamespace)) return "default";
-  if (namespace === normalizeNamespaceIdentity(config.sharedNamespace)) return "shared";
-  if (config.namespacePolicies.some((p) => normalizeNamespaceIdentity(p.name) === namespace)) {
-    return "explicit";
-  }
-  if (/-branch-|^project-[^-]+-branch-/.test(namespace) || namespace.includes("-branch-")) {
-    return "branch";
-  }
-  if (/^team-.*-project-/.test(namespace) || /^team-.*project-/.test(namespace)) {
-    return "team-project";
-  }
-  if (/^project-/.test(namespace) || /-project-/.test(namespace)) {
-    return "project";
-  }
-  return "explicit";
-}
-var NamespaceCatalog = class {
-  constructor(config) {
-    this.config = config;
-    this.memoryDir = config.memoryDir;
-    this.stateDir = path.join(this.memoryDir, STATE_DIR);
-    this.catalogPath = path.join(this.stateDir, CATALOG_FILE);
-    this.rebuildLockPath = path.join(this.stateDir, REBUILD_LOCK_FILE);
-    this.defaultNamespaceIdentity = normalizeNamespaceIdentity(config.defaultNamespace);
-    this.compactBytesLimit = config.namespacesCatalogCompactBytes ?? 16 * 1024 * 1024;
-    this.readCoalesceMs = config.namespacesCatalogReadTouchCoalesceMs ?? 6e4;
-    this.writeCoalesceMs = config.namespacesCatalogWriteTouchCoalesceMs ?? 1e3;
-  }
-  config;
-  memoryDir;
-  stateDir;
-  catalogPath;
-  rebuildLockPath;
-  // In-process serialization for catalog mutations (issue #1524 adoption).
-  // Replaces the bespoke `writeChain` field: every touch/rebuild runs through
-  // this serializer so a single failed section never poisons subsequent ones
-  // (CLAUDE.md rule #40 — recovery is the util's contract, not re-implemented
-  // here). Cross-process identity (the lock file's owner-uuid) is now per-CALL
-  // inside the shared util, which is STRONGER than the previous per-instance
-  // `lockOwnerId` — two calls on the SAME instance get different ids, so
-  // neither mistakes the other's lock for self-held (round 6, codex P2 — NBsGP
-  // invariant preserved and tightened).
-  criticalSection = new MutationSerializer();
-  compactedCache;
-  // Test-only seam (round 7 — NEZkA): fires inside a touch's HELD-lock critical
-  // section, after the lock is acquired but BEFORE the read→merge→append. A
-  // deterministic concurrency test installs a hook here to widen the (otherwise
-  // microscopic) window and prove that a cross-process rebuild CANNOT run its
-  // load→rename while a touch holds the lock. Never set in production code.
-  onTouchCriticalSectionForTest;
-  // Test-only observation seam: fires only when the JSONL file is fully read.
-  // Cached loads do not invoke it.
-  onCatalogReadForTest;
-  // Test-only seam: fires after this process appends but before it stats the
-  // file to refresh the cache identity.
-  onAfterCatalogAppendForTest;
-  // Test-only seam (round 7 — NEZkA): fires inside a mutating rebuild's HELD-lock
-  // critical section, after the final cross-process re-merge `loadCompacted()` and
-  // BEFORE the atomic `rename()`. This is the EXACT window in which a check-then-
-  // append touch (the old bug) would clobber its append. A deterministic test
-  // installs a hook here to attempt a cross-instance touch in this window and
-  // assert the held mutex blocks it. Never set in production code.
-  onRebuildBeforeRenameForTest;
-  // Test-only seam (NFgCT, codex P2): fires AFTER the lockless disk scan but
-  // BEFORE the rebuild acquires the cross-process file lock for its final
-  // load→merge→rename window. A deterministic test installs a hook here to attempt
-  // a cross-instance touch DURING the scan window and assert it is NOT blocked or
-  // dropped — proving the scan no longer holds the mutex. Never set in production.
-  onRebuildAfterScanForTest;
-  // Test-only seam (NG7Bg, codex P2): fires inside `breakStaleRebuildLock` AFTER it
-  // has judged the lock stale and captured its identity, but BEFORE the final
-  // re-validation+unlink. A deterministic test installs a hook here to REPLACE the
-  // lock file (a fresh holder created a new lock in the race window) and assert the
-  // break is skipped — the replacement's active lock is not deleted. Never set in
-  // production.
-  onBeforeBreakStaleUnlinkForTest;
-  // Normalized (trimmed) default namespace identity (NH-FH, cursor Medium).
-  // Catalog records key namespaces by their NORMALIZED identity
-  // (`normalizeNamespaceIdentity`), but several default-namespace exemptions and
-  // memoryDir-ownership checks compared against the RAW `config.defaultNamespace`.
-  // If the configured default name carries surrounding whitespace the record key
-  // is trimmed while the comparison string is not, so the default row is
-  // misclassified, dropped at read time, or given the wrong storage root. Compare
-  // against this normalized form everywhere instead.
-  defaultNamespaceIdentity;
-  // Issue #1903 — touch-path performance knobs, resolved with the documented
-  // defaults when an externally-built PluginConfig omits them (so a partial
-  // config object still yields the production behavior). `0` is a real disable
-  // switch for each and is preserved by `??` (0 is not null/undefined).
-  compactBytesLimit;
-  readCoalesceMs;
-  writeCoalesceMs;
-  // Size after the most recent auto-compaction (0 = none yet). Hysteresis for
-  // maybeAutoCompact: a folded catalog that is itself above the limit (many
-  // distinct namespaces) would otherwise be re-folded + re-rewritten on every
-  // touch. We only compact again once the log has grown by >= one limit-worth
-  // since the last compaction (#1903, Codex).
-  lastCompactedSize = 0;
-  // Issue #1903 — per-(namespace, kind) coalescing buffer. Keyed `${kind}:${ns}`.
-  // Holds the latest buffered timestamp/metadata for a pure-timestamp touch on
-  // an already-known record; a `.unref()`'d timer flushes it once per window so
-  // the append-only log does not grow one line per repeat touch. Semantically
-  // observable touches (first sight, provenance/field change) bypass this buffer
-  // and flush immediately (see `coalesceTouch`).
-  pendingTouches = /* @__PURE__ */ new Map();
-  /** Whether the catalog is active (namespaces enabled and catalog not opted out). */
-  get enabled() {
-    return isCatalogEnabled(this.config);
-  }
-  // ── Public enumeration API ──────────────────────────────────────────────
-  /**
-   * Sanitize a record at the enumeration boundary (round 5, cursor Medium + codex
-   * P2; round 6 — NDXHe). Reads return whatever is in `namespaces.jsonl` after
-   * schema checks only, so a tampered or pre-fix row could surface unsafe data to
-   * maintenance/QMD until a rewrite occurs. Two distinct defenses:
-   *
-   *  1. UNSAFE NAMESPACE NAME (NGZqr, codex P2): an unsafe non-default namespace
-   *     (e.g. `../evil`, a name with separators, or >64 chars) is REJECTED outright
-   *     — return `null` so the caller drops it. The disk SCAN and the hot touch
-   *     path both reject such names with the SAME default-exempt `isSafeRouteNamespace`
-   *     gate, so the read boundary MUST agree, or `listNamespaces()`/`getNamespaceRecord()`
-   *     would expose a namespace those paths reject (note `isStorageDirForNamespace`
-   *     can still build a tokenized root even for `../evil`, so storageDir sanitation
-   *     alone does not catch it). The default namespace is exempt (it may be a
-   *     non-route literal), matching every other validation site.
-   *
-   *  2. UNSAFE storageDir: for an otherwise-valid namespace, apply the SAME contract
-   *     as the write path — full containment (`isContainedStorageDir`: lexical +
-   *     symlink/realpath) AND namespace ownership (`isStorageDirForNamespace`). When
-   *     a record fails EITHER check we substitute the trusted resolved-and-safe root
-   *     for that namespace (rule 42: read and write stay symmetric).
-   */
-  async sanitizeRecordForRead(record) {
-    if (record.namespace !== this.defaultNamespaceIdentity && !isSafeRouteNamespace(record.namespace)) {
-      return null;
-    }
-    if (await this.isContainedStorageDir(record.storageDir) && await this.isStorageDirForNamespace(record.namespace, record.storageDir)) {
-      return record;
-    }
-    const safe = await this.resolveSafeStorageDir(record.namespace);
-    return { ...record, storageDir: safe };
-  }
-  storageRootOwnershipRank(record, resolvedStorageDir, configured) {
-    if (resolvedStorageDir === path.resolve(this.memoryDir)) {
-      return record.namespace === this.defaultNamespaceIdentity ? 0 : 3;
-    }
-    const leaf = path.basename(resolvedStorageDir);
-    const tokenOwnsRoot = namespaceIdentityToken(record.namespace) === leaf;
-    if (tokenOwnsRoot && configured.has(record.namespace)) {
-      return 0;
-    }
-    if (record.namespace === leaf) return 1;
-    if (tokenOwnsRoot) return 2;
-    return 3;
-  }
-  configuredNamespaceIdentities() {
-    return new Set(
-      [
-        this.config.defaultNamespace,
-        this.config.sharedNamespace,
-        ...this.config.namespacePolicies.map((p) => p.name)
-      ].map((n) => normalizeNamespaceIdentity(n)).filter((n) => n.length > 0)
-    );
-  }
-  preferStorageRootOwner(current, candidate, resolvedStorageDir, configured) {
-    const currentRank = this.storageRootOwnershipRank(current, resolvedStorageDir, configured);
-    const candidateRank = this.storageRootOwnershipRank(candidate, resolvedStorageDir, configured);
-    if (candidateRank < currentRank) return candidate;
-    if (candidateRank > currentRank) return current;
-    const byName = candidate.namespace.localeCompare(current.namespace);
-    if (byName < 0) return candidate;
-    if (byName > 0) return current;
-    return candidate.identityToken.localeCompare(current.identityToken) < 0 ? candidate : current;
-  }
-  dropDuplicateStorageRootAliases(records) {
-    const byStorageDir = /* @__PURE__ */ new Map();
-    const configured = this.configuredNamespaceIdentities();
-    for (const record of records) {
-      const resolvedStorageDir = path.resolve(record.storageDir);
-      const current = byStorageDir.get(resolvedStorageDir);
-      if (!current) {
-        byStorageDir.set(resolvedStorageDir, record);
-        continue;
-      }
-      const owner = this.preferStorageRootOwner(current, record, resolvedStorageDir, configured);
-      const alias = owner === current ? record : current;
-      byStorageDir.set(resolvedStorageDir, mergeNewerTouchFields(owner, alias));
-    }
-    return [...byStorageDir.values()];
-  }
-  loadSanitizedRecords() {
-    return this.queueCritical(async () => {
-      const records = await this.loadCompacted();
-      const sanitized = await Promise.all(
-        [...records.values()].map((r) => this.sanitizeRecordForRead(r))
-      );
-      return this.dropDuplicateStorageRootAliases(
-        sanitized.filter((r) => r !== null)
-      );
-    });
-  }
-  async listNamespaces(filter) {
-    if (!this.enabled) return [];
-    let out = await this.loadSanitizedRecords();
-    if (filter?.kind) out = out.filter((r) => r.kind === filter.kind);
-    if (filter?.discoveredBy) out = out.filter((r) => r.discoveredBy === filter.discoveredBy);
-    if (filter?.writtenSince) {
-      const sinceMs = filter.writtenSince.getTime();
-      out = out.filter((r) => {
-        if (!r.lastWriteAt) return false;
-        const ms = Date.parse(r.lastWriteAt);
-        return Number.isFinite(ms) && ms >= sinceMs;
-      });
-    }
-    return out.sort((a, b) => {
-      const byName = a.namespace.localeCompare(b.namespace);
-      if (byName !== 0) return byName;
-      return a.identityToken.localeCompare(b.identityToken);
-    });
-  }
-  async getNamespaceRecord(namespace) {
-    if (!this.enabled) return null;
-    const ns = normalizeNamespaceIdentity(namespace);
-    return (await this.loadSanitizedRecords()).find((record) => record.namespace === ns) ?? null;
-  }
-  // ── Touch API (cheap, failure-tolerant) ─────────────────────────────────
-  async markRead(namespace, metadata) {
-    await this.coalesceTouch(namespace, "read", metadata);
-  }
-  async markWrite(namespace, metadata) {
-    await this.coalesceTouch(namespace, "write", metadata);
-  }
-  /**
-   * Route a read/write touch through the per-(namespace, kind) coalescing buffer
-   * (issue #1903). A touch flushes IMMEDIATELY (bypassing the buffer) whenever it
-   * is semantically observable to an in-process reader — first sight of the
-   * namespace, a `config`→`write` provenance upgrade, the first time a touch
-   * field is set (so `listNamespaces({ writtenSince })` and record presence stay
-   * correct), or a change to `kind`/`principal`/`projectId`/`branch`/
-   * `parentNamespace`. A pure timestamp refresh on an already-known record is
-   * DEFERRED and coalesced: the newest buffered `at`/metadata wins and a single
-   * `touch` runs when the window elapses (or on `flushPendingTouches`). Window
-   * `0` skips the buffer entirely (the pre-#1903 immediate-append behavior).
-   * Best-effort: coalescing decisions read only the warm `compactedCache`, never
-   * forcing a disk parse; a cold cache flushes immediately (and re-warms it).
-   */
-  async coalesceTouch(namespace, kind, metadata) {
-    if (!this.enabled) return;
-    const window = kind === "read" ? this.readCoalesceMs : this.writeCoalesceMs;
-    if (window <= 0) {
-      await this.touch(namespace, kind, metadata);
-      return;
-    }
-    const ns = this.validateNamespace(namespace);
-    const cached = this.compactedCache?.records.get(ns);
-    if (cached === void 0 || this.touchMustFlushImmediately(kind, metadata, cached)) {
-      const stale = this.pendingTouches.get(`${kind}:${ns}`);
-      if (stale) {
-        clearTimeout(stale.timer);
-        this.pendingTouches.delete(`${kind}:${ns}`);
-      }
-      await this.touch(namespace, kind, metadata);
-      return;
-    }
-    const key = `${kind}:${ns}`;
-    const at = metadata?.at ?? /* @__PURE__ */ new Date();
-    const existing = this.pendingTouches.get(key);
-    if (existing) {
-      existing.metadata = metadata;
-      existing.at = at;
-      return;
-    }
-    const safeWindow = Math.min(window, 2147483647);
-    const timer = setTimeout(() => {
-      void this.flushPendingTouch(key);
-    }, safeWindow);
-    timer.unref();
-    this.pendingTouches.set(key, { namespace: ns, kind, metadata, at, timer });
-  }
-  /**
-   * Whether a read/write touch on an EXISTING cached record must flush
-   * immediately rather than coalesce. Only pure timestamp refreshes (the value
-   * returns false) are safe to defer.
-   */
-  touchMustFlushImmediately(kind, metadata, cached) {
-    if (kind === "write" && cached.discoveredBy === "config") return true;
-    if (kind === "write" && cached.lastWriteAt === void 0) return true;
-    if (kind === "read" && cached.lastReadAt === void 0) return true;
-    if (!metadata) return false;
-    if (metadata.kind !== void 0 && metadata.kind !== cached.kind) return true;
-    if (metadata.storageDir !== void 0 && metadata.storageDir !== cached.storageDir) return true;
-    return false;
-  }
-  /** Fire a single buffered touch when its coalescing window elapses. */
-  async flushPendingTouch(key) {
-    const pending = this.pendingTouches.get(key);
-    if (!pending) return;
-    this.pendingTouches.delete(key);
-    clearTimeout(pending.timer);
-    await this.touch(pending.namespace, pending.kind, { ...pending.metadata, at: pending.at }).catch(
-      () => void 0
-    );
-  }
-  /**
-   * Flush every buffered coalesced touch now (issue #1903). Called from the
-   * router/orchestrator shutdown hook so a long-lived host does not drop
-   * buffered read/write timestamps on teardown, and by tests to make coalesced
-   * touches deterministically observable. Best-effort: a failed flush never
-   * throws (each touch is `.catch()`-guarded).
-   */
-  async flushPendingTouches() {
-    const pending = [...this.pendingTouches.values()];
-    this.pendingTouches.clear();
-    for (const p of pending) {
-      clearTimeout(p.timer);
-      await this.touch(p.namespace, p.kind, { ...p.metadata, at: p.at }).catch(() => void 0);
-    }
-  }
-  async markMaintenance(namespace, jobName, at) {
-    if (typeof jobName !== "string" || jobName.trim().length === 0) {
-      throw new Error("markMaintenance requires a non-empty jobName");
-    }
-    await this.touch(namespace, "maintenance", { at }, jobName.trim());
-  }
-  /**
-   * Register namespaces known purely from config (default, shared, explicit
-   * policies). Source `config`. Cheap and idempotent.
-   */
-  async registerConfiguredNamespaces() {
-    if (!this.enabled) return;
-    const names = /* @__PURE__ */ new Set([
-      this.config.defaultNamespace,
-      this.config.sharedNamespace,
-      ...this.config.namespacePolicies.map((p) => p.name)
-    ]);
-    for (const ns of names) {
-      if (!ns) continue;
-      if (normalizeNamespaceIdentity(ns) !== this.defaultNamespaceIdentity && !isSafeRouteNamespace(ns)) {
-        continue;
-      }
-      try {
-        await this.register(ns, { discoveredBy: "config" });
-      } catch {
-      }
-    }
-  }
-  /**
-   * Register a namespace whose storage was just resolved by the router. Used as
-   * the router's integration hook (`discoveredBy: config`). Storage dir is
-   * provided so we do not re-resolve it. Failure-tolerant. Returns whether the
-   * registration actually APPENDED (round 6, codex P2 — NEFoX), so the router's
-   * resolve-hook dedup only marks a namespace notified when it truly persisted —
-   * a dropped append (disabled catalog or rebuild-lock-timeout drop) returns
-   * `false` and is retried on the next resolve.
-   */
-  async registerResolved(namespace, storageDir) {
-    if (!this.enabled) return false;
-    return this.register(namespace, { discoveredBy: "config", storageDir });
-  }
-  /**
-   * Generic register/touch without changing read/write timestamps unless the
-   * source implies it. Validates the namespace and resolves a storage dir.
-   * Returns whether the touch actually appended.
-   */
-  async register(namespace, metadata) {
-    return this.touch(namespace, "register", metadata);
-  }
-  validateNamespace(namespace) {
-    const ns = normalizeNamespaceIdentity(namespace);
-    if (ns.length === 0) throw new Error("empty namespace");
-    if (ns !== this.defaultNamespaceIdentity && !isSafeRouteNamespace(ns)) {
-      throw new Error(`unsafe namespace: ${ns}`);
-    }
-    return ns;
-  }
-  /**
-   * Resolve the on-disk storage dir for a namespace WITHOUT trusting caller
-   * input. The default namespace may use the legacy memoryDir root; everything
-   * else lives under `<memoryDir>/namespaces/<token>`. Containment is enforced
-   * by rejecting separators/parent-refs in the token.
-   */
-  resolveStorageDir(namespace) {
-    if (normalizeNamespaceIdentity(namespace) === this.defaultNamespaceIdentity) {
-      return this.memoryDir;
-    }
-    const token = namespaceIdentityToken(namespace);
-    return this.namespaceTokenDir(token);
-  }
-  namespaceTokenDir(token) {
-    if (token.length === 0 || token.includes("/") || token.includes("\\") || token.includes("..") || path.isAbsolute(token)) {
-      throw new Error(`unsafe namespace token: ${token}`);
-    }
-    return path.join(this.memoryDir, "namespaces", token);
-  }
-  /**
-   * Whether a candidate storage dir is LEXICALLY contained: it is either the
-   * legacy default root (`memoryDir`) or a strict descendant of
-   * `<memoryDir>/namespaces/`. The router legitimately resolves a namespace to
-   * EITHER the tokenized dir or a legacy raw-name dir under `namespaces/`, so we
-   * accept any contained child rather than a single exact token path. This is a
-   * pure string check — symlink escape is checked separately via realpath.
-   */
-  isLexicallyContained(candidate) {
-    const resolved = path.resolve(candidate);
-    if (resolved === path.resolve(this.memoryDir)) return true;
-    const nsBase = path.resolve(path.join(this.memoryDir, "namespaces"));
-    const rel = path.relative(nsBase, resolved);
-    return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
-  }
-  /**
-   * Whether a candidate storage dir satisfies the catalog containment contract,
-   * including SYMLINK-escape rejection (round 5, codex P2). A lexically-contained
-   * path that is actually a symlink to an outside directory would let maintenance
-   * or QMD follow it outside `memoryDir`. We mirror `rebuildFromDisk`'s posture:
-   * the path must be lexically contained AND, if it exists on disk, neither the
-   * path itself a symlink nor its realpath escaping the memory root. Non-existent
-   * paths pass the realpath stage (nothing to follow yet) but still must be
-   * lexically contained.
-   */
-  async isContainedStorageDir(candidate) {
-    if (!this.isLexicallyContained(candidate)) return false;
-    if (path.resolve(candidate) === path.resolve(this.memoryDir)) return true;
-    let memoryReal;
-    try {
-      memoryReal = await realpath(this.memoryDir);
-    } catch {
-      memoryReal = path.resolve(this.memoryDir);
-    }
-    if (await this.hasSymlinkedAncestor(candidate)) return false;
-    try {
-      const stat2 = await lstat(candidate);
-      if (stat2.isSymbolicLink()) return false;
-      if (!stat2.isDirectory()) return false;
-    } catch {
-      return this.isNearestExistingAncestorContained(candidate, memoryReal);
-    }
-    try {
-      const real = await realpath(candidate);
-      return isPathInside(memoryReal, real);
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * Reject a candidate whose path crosses a SYMLINKED ancestor strictly between
-   * memoryDir and the leaf (codex NVuq5). `realpath`-based containment accepts a
-   * symlinked `<memoryDir>/namespaces` that currently resolves back inside
-   * memoryDir, but the disk scanner rejects such a root and a later retarget would
-   * escape the memory tree — so refuse it here too. The leaf itself is
-   * symlink-checked by the caller; this walks only the intermediate ancestors.
-   */
-  async hasSymlinkedAncestor(candidate) {
-    const stopAt = path.resolve(this.memoryDir);
-    let dir = path.dirname(path.resolve(candidate));
-    const root = path.parse(dir).root;
-    while (dir !== stopAt && dir !== root && dir !== path.dirname(dir)) {
-      try {
-        if ((await lstat(dir)).isSymbolicLink()) return true;
-      } catch {
-      }
-      dir = path.dirname(dir);
-    }
-    return false;
-  }
-  /**
-   * Walk up from a not-yet-existing candidate to the nearest ancestor that exists
-   * on disk and verify its realpath stays inside `memoryReal` (round 6, codex P2
-   * — NDo79). Rejects a non-existent leaf whose existing parent chain escapes
-   * memoryDir via a symlink. Stops at memoryDir's resolved root.
-   *
-   * The nearest existing ancestor must also be a DIRECTORY (NHIdt, codex P2): if
-   * an existing parent such as `<memoryDir>/namespaces` is a regular FILE (or
-   * socket/fifo), `realpath(parent)` still succeeds and resolves inside memoryDir,
-   * so a containment-only check would ACCEPT a leaf that can never be created — you
-   * cannot mkdir a child under a file. We `lstat` the nearest existing ancestor and
-   * reject when it is not a directory, mirroring the leaf non-directory rejection
-   * (NF21i) and the disk scan, so every containment consumer agrees.
-   */
-  async isNearestExistingAncestorContained(candidate, memoryReal) {
-    let dir = path.resolve(candidate);
-    const root = path.parse(dir).root;
-    for (; ; ) {
-      const parent = path.dirname(dir);
-      if (parent === dir || dir === root) return false;
-      let real;
-      try {
-        real = await realpath(parent);
-      } catch {
-        dir = parent;
-        continue;
-      }
-      if (!(isPathInside(memoryReal, real) || real === memoryReal)) return false;
-      try {
-        const stat2 = await lstat(real);
-        return stat2.isDirectory();
-      } catch {
-        return false;
-      }
-    }
-  }
-  /**
-   * Resolve the storage dir to persist for a touch, validating any caller-
-   * provided `metadata.storageDir` against the catalog containment contract
-   * (round 4 + round 5, codex P2). `markWrite`/`registerResolved` accept an
-   * explicit storageDir, but persisting it verbatim would let a bad hook or
-   * external consumer write an arbitrary path — including one outside `memoryDir`
-   * or a symlink that escapes it — into the catalog, handing maintenance/QMD an
-   * unsafe root. We accept an explicit (or previously-stored) dir ONLY when it
-   * stays contained under memoryDir (lexically AND via realpath); otherwise we
-   * drop it and fall back to the trusted resolved dir.
-   */
-  async resolveTouchStorageDir(namespace, explicit, existingDir) {
-    if (explicit !== void 0 && await this.isContainedStorageDir(explicit) && await this.isStorageDirForNamespace(namespace, explicit)) {
-      return explicit;
-    }
-    if (existingDir !== void 0 && await this.isContainedStorageDir(existingDir) && await this.isStorageDirForNamespace(namespace, existingDir)) {
-      return existingDir;
-    }
-    return this.resolveSafeStorageDir(namespace);
-  }
-  /**
-   * Whether `candidate` is a legitimate storage root FOR `namespace` (round 6,
-   * codex P2 — NDATT). Accepts the namespace's router-resolved root, its canonical
-   * lexical tokenized dir, and (for the default namespace only) memoryDir. This
-   * prevents a contained-but-CROSS-NAMESPACE path — another namespace's tree, or
-   * memoryDir for a non-default namespace — from being persisted as this
-   * namespace's root. Compared on resolved (absolute) paths.
-   */
-  async isStorageDirForNamespace(namespace, candidate) {
-    const resolvedCandidate = path.resolve(candidate);
-    const valid = /* @__PURE__ */ new Set();
-    try {
-      valid.add(path.resolve(this.namespaceTokenDir(namespaceIdentityToken(namespace))));
-    } catch {
-    }
-    try {
-      valid.add(path.resolve(this.namespaceTokenDir(namespace)));
-    } catch {
-    }
-    try {
-      valid.add(path.resolve(await resolveNamespaceStorageRoot(this.config, namespace)));
-    } catch {
-    }
-    if (normalizeNamespaceIdentity(namespace) === this.defaultNamespaceIdentity) {
-      valid.add(path.resolve(this.memoryDir));
-      try {
-        valid.add(path.resolve(await resolveDefaultNamespaceRoot(this.config)));
-      } catch {
-      }
-    }
-    return valid.has(resolvedCandidate);
-  }
-  /**
-   * Resolve the canonical storage dir for a namespace as the LIVE ROUTER would,
-   * but NEVER return a path that escapes the memory root.
-   *
-   * Router alignment (round 4, cursor Medium): a read/register touch with no
-   * explicit storageDir previously used the lexical `resolveStorageDir`, which
-   * always picks `<memoryDir>/namespaces/<token>` (or `memoryDir` for the
-   * default). That diverges from `NamespaceStorageRouter`, which can route to a
-   * legacy raw-name dir or a migrated default root — so a recall touch could
-   * record a contained-but-WRONG root that maintenance/rebuild then targets. We
-   * now delegate to the shared `resolveNamespaceStorageRoot` (the very helper the
-   * router uses) so the catalog records the same on-disk root the router serves.
-   *
-   * Containment (round 5, codex P2): the resolved path can still be a symlink
-   * escaping memoryDir, so we run the full (lexical + realpath) containment
-   * contract. When it FAILS we fall back to a NAMESPACE-SPECIFIC safe root, NOT
-   * a blanket `memoryDir`. Recording `memoryDir` for a non-default namespace
-   * would point enumeration/maintenance at the DEFAULT namespace's tree (round 5,
-   * cursor/codex Medium/P2) — a cross-namespace fanout error. The correct safe
-   * root is the namespace's own lexical tokenized dir
-   * (`<memoryDir>/namespaces/<token>`), which is always contained and is that
-   * namespace's canonical location (we record the lexical PATH as metadata; we do
-   * not follow the escaping symlink). Only the default namespace — or a token so
-   * unsafe even the lexical dir cannot be built — falls back to `memoryDir`.
-   */
-  async resolveSafeStorageDir(namespace) {
-    let resolved;
-    try {
-      resolved = await resolveNamespaceStorageRoot(this.config, namespace);
-    } catch {
-      return this.safeFallbackStorageDir(namespace);
-    }
-    if (await this.isContainedStorageDir(resolved)) return resolved;
-    return this.safeFallbackStorageDir(namespace);
-  }
-  /**
-   * The namespace-specific contained fallback root, used when the router-resolved
-   * root fails containment (round 5, cursor/codex Medium/P2).
-   *
-   * Preference order:
-   *  1. The namespace's OWN lexical tokenized dir (`namespaces/<token>`) — so a
-   *     non-default namespace is NOT pointed at the DEFAULT namespace's `memoryDir`
-   *     tree (which would misdirect maintenance fanout). Returned only when the
-   *     token dir itself stays CONTAINED (it is not a symlink, and its realpath
-   *     does not escape memoryDir — e.g. via a symlinked `namespaces/` parent).
-   *  2. `memoryDir` as a LAST resort — for the default namespace, an unsafe token
-   *     that cannot build a contained path, OR the irreparable case where the
-   *     token dir's realpath escapes the root (so even its lexical path resolves
-   *     outside). NF21m note (codex P2): we deliberately do NOT record the lexical
-   *     token dir in that irreparable case — its realpath escapes memoryDir, and
-   *     the NDo79 contract REQUIRES that an escaping path is never persisted (a
-   *     later mkdir/maintenance/QMD op would follow it outside the root). Since no
-   *     contained namespace-specific path exists, containment wins: `memoryDir` is
-   *     the only safe root left. A namespace whose token dir's realpath escapes is
-   *     an irreparable on-disk state; recording the contained default root is
-   *     strictly safer than persisting an escaping one. The common case where the
-   *     token dir IS contained is handled by branch 1, so a healthy non-default
-   *     namespace never reaches `memoryDir`.
-   */
-  async safeFallbackStorageDir(namespace) {
-    if (normalizeNamespaceIdentity(namespace) === this.defaultNamespaceIdentity) return this.memoryDir;
-    let tokenDir;
-    try {
-      tokenDir = this.namespaceTokenDir(namespaceIdentityToken(namespace));
-    } catch {
-      return this.memoryDir;
-    }
-    if (await this.isContainedStorageDir(tokenDir)) return tokenDir;
-    return this.memoryDir;
-  }
-  /**
-   * Re-check, NOW, whether a namespace's storage root currently EXISTS on disk
-   * with the SAME safety the directory scan uses (NFJV8, codex P2).
-   *
-   * The rebuild's final re-merge runs under the held lock and folds the freshly
-   * re-read log (`latest`) into the scanned `rebuilt` set. A namespace present in
-   * `latest` (a live touch row) but ABSENT from `rebuilt` is normally PURGED as
-   * deleted (the NATqU "disk scan is authoritative" rule). But there is a TOCTOU
-   * window: a dynamic namespace can be CREATED on disk AFTER `rebuildFromDisk()`
-   * already enumerated `namespaces/` but BEFORE this re-merge. The scan snapshot
-   * missed its new root, yet a gateway `markWrite` already appended a row for it.
-   * Blindly purging that row would rewrite the catalog WITHOUT a live namespace
-   * that now has data on disk, so `writtenSince`/maintenance/QMD consumers miss
-   * it until another touch or rebuild.
-   *
-   * So before purging, we re-resolve the namespace's safe storage root (the same
-   * router-aligned, containment-checked path the scan would have catalogued) and
-   * confirm it is a real, contained, non-symlink directory that actually holds
-   * memory data RIGHT NOW. If so the namespace was created-after-scan and is LIVE
-   * — KEEP its row. This is the precise inverse of NATqU and does NOT reintroduce
-   * it: a touch on a REMOVED root re-checks as ABSENT (no data on disk) and is
-   * still purged; only a root that EXISTS on a fresh re-check is kept.
-   *
-   * Mirrors the per-entry scan checks (symlink rejection + realpath containment +
-   * `hasMemoryData`) so a symlinked/escaping root is never resurrected.
-   */
-  async liveStorageRootExistsForRebuild(namespace, memoryReal) {
-    let root;
-    try {
-      root = await this.resolveSafeStorageDir(namespace);
-    } catch {
-      return false;
-    }
-    if (normalizeNamespaceIdentity(namespace) !== this.defaultNamespaceIdentity && path.resolve(root) === path.resolve(this.memoryDir)) {
-      return false;
-    }
-    let stat2;
-    try {
-      stat2 = await lstat(root);
-    } catch {
-      return false;
-    }
-    if (stat2.isSymbolicLink()) return false;
-    if (!stat2.isDirectory()) return false;
-    try {
-      const real = await realpath(root);
-      if (memoryReal && !isPathInside(memoryReal, real)) return false;
-    } catch {
-      return false;
-    }
-    return hasMemoryData(root);
-  }
-  /**
-   * Record a namespace touch. Returns whether the touch actually APPENDED to the
-   * log (round 6, codex P2 — NEFoX): a disabled catalog or a dropped append (the
-   * NAUf7 rebuild-lock-timeout drop) returns `false`, so callers (e.g. the router
-   * resolve-hook dedup) can avoid marking a dropped registration as completed and
-   * suppressing its retry.
-   */
-  async touch(namespace, kind, metadata, jobName) {
-    if (!this.enabled) return false;
-    const ns = this.validateNamespace(namespace);
-    const nowIso = (metadata?.at ?? /* @__PURE__ */ new Date()).toISOString();
-    return this.queueCritical(
-      async () => this.withHeldCatalogLock(async (acquired) => {
-        if (!acquired) return false;
-        if (this.onTouchCriticalSectionForTest) {
-          await this.onTouchCriticalSectionForTest();
-        }
-        const records = await this.loadCompacted();
-        const existing = records.get(ns);
-        const storageDir = await this.resolveTouchStorageDir(
-          ns,
-          metadata?.storageDir,
-          existing?.storageDir
-        );
-        const record = existing ? { ...existing } : {
-          namespace: ns,
-          identityToken: namespaceIdentityToken(ns),
-          kind: metadata?.kind ?? inferKind(ns, this.config),
-          createdAt: nowIso,
-          storageDir,
-          discoveredBy: metadata?.discoveredBy ?? (kind === "register" ? "config" : kind === "maintenance" ? "scan" : kind)
-        };
-        record.storageDir = storageDir;
-        if (metadata?.kind) record.kind = metadata.kind;
-        if (kind === "write" && existing && record.discoveredBy === "config") {
-          record.discoveredBy = "write";
-        }
-        if (kind === "read") record.lastReadAt = nowIso;
-        if (kind === "write") record.lastWriteAt = nowIso;
-        if (kind === "maintenance" && jobName) {
-          record.lastMaintenanceAt = { ...record.lastMaintenanceAt ?? {}, [jobName]: nowIso };
-        }
-        await this.appendUnchained(record);
-        await this.maybeAutoCompact();
-        return true;
-      })
-    );
-  }
-  /**
-   * Fold-and-rewrite the JSONL log when it exceeds `compactBytesLimit`
-   * (issue #1903). MUST be called only from inside `touch`'s held-lock +
-   * `queueCritical` critical section — it reuses `loadCompacted` (last-record-
-   * wins fold; every namespace row survives) and `rewriteUnchained` (atomic
-   * temp-file + rename), so the collapse is cross-process safe and never
-   * invokes the disk-scan purge in `finishRebuild`. Best-effort and fail-open
-   * (rule #40): the append already succeeded and is durable, so a failed
-   * compaction must not fail the touch — the next over-limit touch retries.
-   */
-  async maybeAutoCompact() {
-    try {
-      const limit = this.compactBytesLimit;
-      if (limit <= 0) return;
-      const size = this.compactedCache?.identity.size;
-      if (size === void 0 || size <= limit) return;
-      if (this.lastCompactedSize > 0 && size - this.lastCompactedSize < limit) return;
-      const folded = await this.loadCompacted();
-      await this.rewriteUnchained([...folded.values()]);
-      this.lastCompactedSize = this.compactedCache?.identity.size ?? size;
-    } catch {
-    }
-  }
-  // ── Rebuild from disk ────────────────────────────────────────────────────
-  async rebuildFromDisk(options) {
-    const dryRun = options?.dryRun === true;
-    if (!this.enabled) {
-      return { dryRun, records: [], skipped: [], applied: false };
-    }
-    if (dryRun) {
-      return this.queueCritical(async () => this.rebuildInsideChain(dryRun, false));
-    }
-    return this.queueCritical(async () => this.rebuildInsideChain(dryRun, true));
-  }
-  /**
-   * Body of `rebuildFromDisk`, run inside a single `queueCritical` turn. MUST
-   * only be invoked from within the serialized chain so the load and the
-   * rewrite are atomic with respect to concurrent touches (in-process).
-   *
-   * `wantMutate` is true for an `--apply` (the caller intends to rewrite). The
-   * cross-process file lock is acquired LATE — only around the final
-   * load→merge→rename window (NFgCT, codex P2) — never across the disk scan, so a
-   * long scan does not force concurrent gateway touches to wait (and drop their
-   * append). Whether the rewrite actually happened is reported via the result's
-   * `applied`: true only when `wantMutate` AND the lock was acquired.
-   */
-  async rebuildInsideChain(dryRun, wantMutate) {
-    const existing = await this.loadCompacted();
-    const skipped = [];
-    const rebuilt = /* @__PURE__ */ new Map();
-    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
-    let memoryReal = null;
-    try {
-      memoryReal = await realpath(this.memoryDir);
-    } catch {
-      memoryReal = this.memoryDir;
-    }
-    const defaultNs = normalizeNamespaceIdentity(this.config.defaultNamespace);
-    const configured = new Set(
-      [
-        this.config.defaultNamespace,
-        this.config.sharedNamespace,
-        ...this.config.namespacePolicies.map((p) => p.name)
-      ].map((n) => normalizeNamespaceIdentity(n)).filter((n) => n.length > 0)
-    );
-    const resolvedDefaultRoot = await resolveDefaultNamespaceRoot(this.config);
-    const defaultStorageDir = await this.isContainedStorageDir(resolvedDefaultRoot) ? resolvedDefaultRoot : this.memoryDir;
-    const legacyDefaultHasData = defaultStorageDir === this.memoryDir;
-    for (const ns of configured) {
-      if (!ns) continue;
-      if (ns !== defaultNs && !isSafeRouteNamespace(ns)) {
-        let token;
-        try {
-          token = namespaceIdentityToken(ns);
-        } catch {
-          token = ns;
-        }
-        skipped.push({ token, reason: "unsafe", detail: ns });
-        continue;
-      }
-      let storageDir;
-      if (ns === defaultNs) {
-        storageDir = defaultStorageDir;
-      } else {
-        try {
-          storageDir = await resolveNamespaceStorageRoot(this.config, ns);
-        } catch {
-          storageDir = this.namespaceTokenDir(namespaceIdentityToken(ns));
-        }
-      }
-      if (!await this.isContainedStorageDir(storageDir)) {
-        if (ns === defaultNs) {
-          storageDir = this.memoryDir;
-        } else {
-          skipped.push({ token: namespaceIdentityToken(ns), reason: "escape", detail: storageDir });
-          continue;
-        }
-      }
-      rebuilt.set(
-        ns,
-        this.mergeForRebuild(existing.get(ns), {
-          namespace: ns,
-          identityToken: namespaceIdentityToken(ns),
-          kind: inferKind(ns, this.config),
-          createdAt: existing.get(ns)?.createdAt ?? nowIso,
-          storageDir,
-          discoveredBy: "config"
-        })
-      );
-    }
-    const namespacesDir = path.join(this.memoryDir, "namespaces");
-    let entries = [];
-    let namespacesDirSafe = true;
-    try {
-      const rootStat = await lstat(namespacesDir);
-      if (rootStat.isSymbolicLink()) {
-        namespacesDirSafe = false;
-      } else {
-        const realNamespacesDir = await realpath(namespacesDir);
-        if (memoryReal && !isPathInside(memoryReal, realNamespacesDir)) {
-          namespacesDirSafe = false;
-        }
-      }
-    } catch {
-      namespacesDirSafe = true;
-    }
-    if (!namespacesDirSafe) {
-      skipped.push({ token: "namespaces", reason: "symlink", detail: namespacesDir });
-    } else {
-      try {
-        entries = await readdir(namespacesDir, { withFileTypes: true });
-      } catch {
-        entries = [];
-      }
-    }
-    const scannedFromTokenized = /* @__PURE__ */ new Map();
-    for (const entry of entries) {
-      const token = entry.name;
-      const fullPath = path.join(namespacesDir, token);
-      let stat2;
-      try {
-        stat2 = await lstat(fullPath);
-      } catch (err) {
-        skipped.push({ token, reason: "error", detail: err instanceof Error ? err.message : String(err) });
-        continue;
-      }
-      if (stat2.isSymbolicLink()) {
-        skipped.push({ token, reason: "symlink", detail: fullPath });
-        continue;
-      }
-      if (!stat2.isDirectory()) continue;
-      try {
-        const real = await realpath(fullPath);
-        if (memoryReal && !isPathInside(memoryReal, real)) {
-          skipped.push({ token, reason: "escape", detail: real });
-          continue;
-        }
-      } catch (err) {
-        skipped.push({ token, reason: "error", detail: err instanceof Error ? err.message : String(err) });
-        continue;
-      }
-      const literalRecord = existing.get(token);
-      const literalOwnsRoot = configured.has(token) || literalRecord !== void 0 && path.resolve(literalRecord.storageDir) === path.resolve(fullPath);
-      const tokenDecoded = literalOwnsRoot ? null : namespaceIdentityFromToken(token);
-      const rawDecoded = tokenDecoded && tokenDecoded.length > 0 ? tokenDecoded : token;
-      const decoded = normalizeNamespaceIdentity(rawDecoded);
-      if (decoded.length === 0 || rawDecoded !== decoded && rawDecoded.normalize("NFC") !== decoded) {
-        skipped.push({ token, reason: "unsafe", detail: rawDecoded });
-        continue;
-      }
-      if (decoded !== defaultNs && !isSafeRouteNamespace(decoded)) {
-        skipped.push({ token, reason: "unsafe", detail: decoded });
-        continue;
-      }
-      const memoryData = await inspectMemoryDataRoot(fullPath);
-      if (memoryData.invalidMarker) {
-        skipped.push({
-          token,
-          reason: "unsafe",
-          detail: `invalid memory marker: ${memoryData.invalidMarker}`
-        });
-        continue;
-      }
-      if (!memoryData.hasData) continue;
-      if (decoded === defaultNs) {
-        const def = rebuilt.get(defaultNs);
-        if (def) {
-          def.storageDir = defaultStorageDir;
-          def.kind = "default";
-        }
-        continue;
-      }
-      const canonicalToken = namespaceIdentityToken(decoded);
-      const legacyToken = namespaceIdentityLegacyToken(decoded.normalize("NFD"));
-      const tokenKind = token === canonicalToken ? 2 : token === legacyToken ? 1 : 0;
-      const priorTokenKind = scannedFromTokenized.get(decoded) ?? 0;
-      if (rebuilt.has(decoded) && priorTokenKind > tokenKind) continue;
-      if (tokenKind > 0) scannedFromTokenized.set(decoded, tokenKind);
-      const prior = existing.get(decoded);
-      rebuilt.set(
-        decoded,
-        this.mergeForRebuild(prior, {
-          namespace: decoded,
-          identityToken: namespaceIdentityToken(decoded),
-          kind: inferKind(decoded, this.config),
-          createdAt: prior?.createdAt ?? nowIso,
-          storageDir: fullPath,
-          // Configured-and-present namespaces keep config provenance; purely
-          // discovered ones are scan.
-          discoveredBy: configured.has(decoded) ? "config" : prior?.discoveredBy ?? "scan"
-        })
-      );
-    }
-    if (legacyDefaultHasData && defaultStorageDir === this.memoryDir) {
-      const def = rebuilt.get(defaultNs);
-      if (def) def.kind = "default";
-    }
-    if (!wantMutate) {
-      return this.finishRebuild(rebuilt, skipped, dryRun, false, memoryReal, nowIso);
-    }
-    if (this.onRebuildAfterScanForTest) {
-      await this.onRebuildAfterScanForTest();
-    }
-    return this.withHeldCatalogLock(
-      (acquired) => this.finishRebuild(rebuilt, skipped, dryRun, acquired, memoryReal, nowIso)
-    );
-  }
-  /**
-   * Final load→merge→rename window of a rebuild, factored out so the caller can
-   * run it WITHIN the cross-process file lock (NFgCT, codex P2) without holding
-   * that lock across the preceding disk scan. Re-reads the latest on-disk state,
-   * folds concurrent touches, then (when `canMutate`) atomically rewrites the log.
-   *
-   * `canMutate` records that the cross-process lock was actually held. The
-   * re-merge + rewrite run only when it is true — a dry-run, or an unlocked apply
-   * (lock-acquisition timeout), computes records but does NOT rename, so it can
-   * never clobber a concurrent lock holder's window. `applied` mirrors `canMutate`.
-   */
-  async finishRebuild(rebuilt, skipped, dryRun, canMutate, memoryReal, nowIso) {
-    if (canMutate) {
-      const latest = await this.loadCompacted(true);
-      for (const [ns, fresh] of latest) {
-        const current = rebuilt.get(ns);
-        if (!current) {
-          if (ns !== this.defaultNamespaceIdentity && !isSafeRouteNamespace(ns)) {
-            continue;
-          }
-          if (await this.liveStorageRootExistsForRebuild(ns, memoryReal)) {
-            const safeDir = await this.resolveSafeStorageDir(ns);
-            const resolvedSafe = path.resolve(safeDir);
-            let owningNamespace = null;
-            for (const [otherNs, otherRec] of rebuilt) {
-              if (otherNs !== ns && path.resolve(otherRec.storageDir) === resolvedSafe) {
-                owningNamespace = otherNs;
-                break;
-              }
-            }
-            if (owningNamespace) {
-              const owner = rebuilt.get(owningNamespace);
-              if (owner) rebuilt.set(owningNamespace, mergeNewerTouchFields(owner, fresh));
-              continue;
-            }
-            rebuilt.set(ns, {
-              ...fresh,
-              storageDir: safeDir,
-              identityToken: namespaceIdentityToken(ns),
-              kind: fresh.kind ?? inferKind(ns, this.config),
-              createdAt: fresh.createdAt ?? nowIso
-            });
-            continue;
-          }
-          continue;
-        }
-        rebuilt.set(ns, mergeNewerTouchFields(current, fresh));
-      }
-    }
-    const records = [...rebuilt.values()].sort((a, b) => {
-      const byName = a.namespace.localeCompare(b.namespace);
-      if (byName !== 0) return byName;
-      return a.identityToken.localeCompare(b.identityToken);
-    });
-    if (canMutate) {
-      if (this.onRebuildBeforeRenameForTest) {
-        await this.onRebuildBeforeRenameForTest();
-      }
-      await this.rewriteUnchained(records);
-    }
-    return { dryRun, records, skipped, applied: canMutate };
-  }
-  // ── Cross-process catalog write lock (held mutex) ────────────────────────
-  /**
-   * Run `fn` while HOLDING the shared cross-process advisory lock (round 5, codex
-   * P2; generalized round 7 — NEZkA). This is the SINGLE mutex shared by BOTH the
-   * touch read→merge→append window AND the rebuild final load→merge→rename window,
-   * so a touch and a rebuild in different processes are mutually exclusive over
-   * their respective critical sections — closing the check-then-append gap where a
-   * polled-only touch could append into a rebuild's load→rename window.
-   *
-   * Issue #1524 adoption: this is now a thin delegation to the shared
-   * `withHeldFileLock` utility. The acquire loop, mtime heartbeat, stale-break
-   * (NG7Bg replacement-safe), and ownership-checked release (NCzT6) all live in
-   * ONE place — the util — so this module no longer re-implements them. The
-   * catalog's `REBUILD_LOCK_*` constants and the `onBeforeBreakStaleUnlinkForTest`
-   * seam flow straight through. The util generates a per-CALL owner uuid, which
-   * is stricter than the previous per-instance `lockOwnerId` (two calls on the
-   * same instance get different ids, so neither mistakes the other's lock as
-   * self-held — the NBsGP invariant, preserved and tightened).
-   *
-   * IN-PROCESS SAFETY: every caller invokes this from inside (or wrapping) the
-   * per-process `queueCritical` chain, which serializes all catalog mutations in
-   * THIS process (now via `MutationSerializer`). So within one process only one
-   * logical holder attempts OS-lock acquisition at a time — the file lock is never
-   * self-contended in-process, and the lock is acquired and released within a
-   * single in-process turn. The file lock adds only the missing CROSS-process
-   * exclusion.
-   *
-   * ACQUISITION RESULT (round 6, codex P2 — NBPmY): `fn` receives whether WE
-   * actually hold the lock. When acquisition TIMED OUT (another holder is active),
-   * a MUTATING rebuild must NOT perform its load/rename window unlocked, and a
-   * touch must NOT append unlocked — both would recreate the lost-append race. The
-   * caller uses `acquired` to run compute-only (rebuild) or DROP the append
-   * (touch) when unlocked.
-   */
-  withHeldCatalogLock(fn) {
-    return withHeldFileLock(
-      this.rebuildLockPath,
-      {
-        staleMs: REBUILD_LOCK_STALE_MS,
-        maxWaitMs: REBUILD_LOCK_MAX_WAIT_MS,
-        pollMs: REBUILD_LOCK_POLL_MS,
-        heartbeatMs: REBUILD_LOCK_HEARTBEAT_MS,
-        // NG7Bg seam: fires inside the util's breakStaleLock after it judges the
-        // lock stale and captures its identity, before the atomic rename+verify.
-        onBeforeBreakStaleUnlinkForTest: this.onBeforeBreakStaleUnlinkForTest
-      },
-      fn
-    );
-  }
-  /**
-   * Merge a prior record's preserved metadata (timestamps, principal hints)
-   * onto a freshly-discovered record. Disk-derived fields (storageDir, kind)
-   * take precedence from the new record.
-   *
-   * PROVENANCE (round 3, cursor Low): `discoveredBy` and `createdAt` are
-   * CREATION-ONLY — identical to the touch path's invariant. A rebuild must NOT
-   * reset a namespace first seen via a `write`/`read` touch back to `config`
-   * just because it is also listed in policies. So when a prior record exists we
-   * carry its `discoveredBy` forward; only brand-new records keep the fresh
-   * (config/scan) provenance.
-   */
-  mergeForRebuild(prior, fresh) {
-    if (!prior) return fresh;
-    const merged = {
-      ...fresh,
-      createdAt: prior.createdAt ?? fresh.createdAt,
-      discoveredBy: prior.discoveredBy ?? fresh.discoveredBy
-    };
-    if (prior.lastReadAt) merged.lastReadAt = prior.lastReadAt;
-    if (prior.lastWriteAt) merged.lastWriteAt = prior.lastWriteAt;
-    if (prior.lastMaintenanceAt) merged.lastMaintenanceAt = { ...prior.lastMaintenanceAt };
-    return merged;
-  }
-  // ── Persistence ──────────────────────────────────────────────────────────
-  /** Load the JSONL log and fold it into current state (last-record-wins). */
-  async loadCompacted(forceFresh = false) {
-    const records = /* @__PURE__ */ new Map();
-    let handle;
-    try {
-      handle = await open(this.catalogPath, "r");
-    } catch {
-      this.compactedCache = void 0;
-      return records;
-    }
-    let identity;
-    try {
-      const fileStat = await handle.stat();
-      identity = {
-        size: fileStat.size,
-        mtimeMs: fileStat.mtimeMs,
-        ctimeMs: fileStat.ctimeMs,
-        ino: fileStat.ino
-      };
-      if (!forceFresh && this.compactedCache && this.compactedCache.identity.size === identity.size && this.compactedCache.identity.mtimeMs === identity.mtimeMs && this.compactedCache.identity.ctimeMs === identity.ctimeMs && this.compactedCache.identity.ino === identity.ino) {
-        await handle.close().catch(() => void 0);
-        return this.cloneCompactedRecords(this.compactedCache.records);
-      }
-    } catch {
-    }
-    try {
-      this.onCatalogReadForTest?.();
-      const CHUNK_BYTES = 1 << 16;
-      const YIELD_EVERY_LINES = 5e3;
-      const chunk = Buffer.allocUnsafe(CHUNK_BYTES);
-      const decoder = new StringDecoder("utf8");
-      let leftover = "";
-      let linesSinceYield = 0;
-      const foldLine = (line) => {
-        const trimmed = line.trim();
-        if (trimmed.length === 0) return;
-        let parsed;
-        try {
-          parsed = JSON.parse(trimmed);
-        } catch {
-          return;
-        }
-        const record = coerceRecord(parsed);
-        if (!record) return;
-        const prior = records.get(record.namespace);
-        records.set(record.namespace, prior ? mergeNewerTouchFields(record, prior) : record);
-      };
-      for (; ; ) {
-        const { bytesRead } = await handle.read(chunk, 0, CHUNK_BYTES, null);
-        if (bytesRead === 0) break;
-        leftover += decoder.write(chunk.subarray(0, bytesRead));
-        let newlineIndex = leftover.indexOf("\n");
-        while (newlineIndex !== -1) {
-          foldLine(leftover.slice(0, newlineIndex));
-          leftover = leftover.slice(newlineIndex + 1);
-          if (++linesSinceYield >= YIELD_EVERY_LINES) {
-            linesSinceYield = 0;
-            await new Promise((resolve) => setImmediate(resolve));
-          }
-          newlineIndex = leftover.indexOf("\n");
-        }
-      }
-      leftover += decoder.end();
-      foldLine(leftover);
-    } catch {
-      this.compactedCache = void 0;
-      return /* @__PURE__ */ new Map();
-    } finally {
-      await handle.close().catch(() => void 0);
-    }
-    this.compactedCache = identity ? { identity, records } : void 0;
-    return this.cloneCompactedRecords(records);
-  }
-  cloneCompactedRecords(records) {
-    return new Map(
-      [...records].map(([namespace, record]) => [
-        namespace,
-        {
-          ...record,
-          lastMaintenanceAt: record.lastMaintenanceAt ? { ...record.lastMaintenanceAt } : void 0
-        }
-      ])
-    );
-  }
-  /**
-   * Serialize an arbitrary read-modify-write critical section through the single
-   * per-instance chain. Every catalog mutation and cached catalog read runs
-   * through this queue, so cache validation and updates cannot race in-process.
-   *
-   * Issue #1524 adoption: delegates to the shared `MutationSerializer` (stored
-   * as `criticalSection`). The util owns the rejection-recovery invariant
-   * (CLAUDE.md rule #40 — one failed section never poisons subsequent ones, but
-   * the failing section's error still surfaces to ITS awaited promise) and the
-   * no-unbounded-growth cleanup. The key is constant: the catalog has ONE
-   * logical mutation queue (touches and rebuilds mutually exclude in-process).
-   */
-  queueCritical(fn) {
-    return this.criticalSection.serialize("catalog", fn);
-  }
-  /**
-   * Append a single record to the JSONL log WITHOUT re-serializing through the
-   * write chain. MUST only be called from inside a `queueCritical(...)` section
-   * (which already holds the serialized turn); calling it directly would bypass
-   * the read-before-append ordering that prevents lost-field races.
-   */
-  async appendUnchained(record) {
-    const line = serializeRecord(record) + "\n";
-    const lineByteLength = Buffer.byteLength(line, "utf8");
-    await mkdir(this.stateDir, { recursive: true });
-    await appendFile(this.catalogPath, line, "utf8");
-    if (this.onAfterCatalogAppendForTest) {
-      await this.onAfterCatalogAppendForTest();
-    }
-    await this.refreshCacheAfterAppend(record, lineByteLength);
-  }
-  /**
-   * Atomic temp-file + rename rewrite (CLAUDE.md rule #54: write temp, then
-   * rename — never delete-before-write) WITHOUT re-entering the write chain.
-   * MUST only be called from inside a `queueCritical(...)` turn (e.g. the
-   * rebuild critical section, which already holds the serialized turn so its
-   * load and rewrite are atomic against concurrent touches). Re-entering the
-   * chain from within a held turn would deadlock.
-   */
-  async rewriteUnchained(records) {
-    const body = records.map((r) => serializeRecord(r)).join("\n") + (records.length > 0 ? "\n" : "");
-    await mkdir(this.stateDir, { recursive: true });
-    const tmp = `${this.catalogPath}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(tmp, body, "utf8");
-    await rename(tmp, this.catalogPath);
-    await this.refreshCacheIdentity(new Map(records.map((record) => [record.namespace, record])));
-  }
-  async refreshCacheAfterAppend(record, lineByteLength) {
-    const cached = this.compactedCache;
-    if (!cached) return;
-    const expectedSize = cached.identity.size + lineByteLength;
-    try {
-      const fileStat = await stat(this.catalogPath);
-      if (fileStat.size !== expectedSize || fileStat.ino !== cached.identity.ino) {
-        this.compactedCache = void 0;
-        return;
-      }
-      const prior = cached.records.get(record.namespace);
-      cached.records.set(record.namespace, prior ? mergeNewerTouchFields(record, prior) : record);
-      this.compactedCache = {
-        identity: {
-          size: fileStat.size,
-          mtimeMs: fileStat.mtimeMs,
-          ctimeMs: fileStat.ctimeMs,
-          ino: fileStat.ino
-        },
-        records: cached.records
-      };
-    } catch {
-      this.compactedCache = void 0;
-    }
-  }
-  async refreshCacheIdentity(records) {
-    try {
-      const fileStat = await stat(this.catalogPath);
-      this.compactedCache = {
-        identity: {
-          size: fileStat.size,
-          mtimeMs: fileStat.mtimeMs,
-          ctimeMs: fileStat.ctimeMs,
-          ino: fileStat.ino
-        },
-        records
-      };
-    } catch {
-      this.compactedCache = void 0;
-    }
-  }
-};
-function isPathInside(root, child) {
-  const relative = path.relative(root, child);
-  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
-}
-
-export {
-  hasMemoryData,
-  isNamespaceKind,
-  NamespaceCatalog
-};
-//# sourceMappingURL=chunk-U2SK45U3.js.map