@remnic/core 9.3.688 → 9.3.690

package/dist/chunk-ZU7N3S6V.js

@@ -0,0 +1,2190 @@
+import {
+  resolveDefaultNamespaceRoot,
+  resolveNamespaceStorageRoot
+} from "./chunk-UD5OKH4J.js";
+import {
+  namespaceIdentityFromToken,
+  namespaceIdentityToken,
+  normalizeNamespaceIdentity
+} from "./chunk-ZFXCQPNO.js";
+import {
+  displayErrorDetail
+} from "./chunk-6KYMPV2O.js";
+import {
+  ALL_CATEGORY_DIRS
+} from "./chunk-VS2IYZRU.js";
+import {
+  isSafeRouteNamespace
+} from "./chunk-U3PN77QT.js";
+
+// src/namespaces/catalog.ts
+import path from "path";
+import { randomUUID } from "crypto";
+import {
+  appendFile,
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  realpath,
+  rename,
+  stat,
+  unlink,
+  utimes,
+  writeFile
+} from "fs/promises";
+var NAMESPACE_KINDS = [
+  "default",
+  "self",
+  "shared",
+  "project",
+  "branch",
+  "team-project",
+  "explicit",
+  "legacy"
+];
+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 (config.namespacesEnabled !== true) return false;
+  return config.namespaceCatalogEnabled !== false;
+}
+var FILE_MEMORY_DATA_CHILDREN = /* @__PURE__ */ new Set(["profile.md"]);
+function isNotFoundError(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+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 = v.kind === void 0 ? "explicit" : isNamespaceKind(v.kind) ? v.kind : null;
+  if (!kind) return null;
+  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.principal === "string") record.principal = v.principal;
+  if (typeof v.projectId === "string") record.projectId = v.projectId;
+  if (typeof v.branch === "string") record.branch = v.branch;
+  if (typeof v.parentNamespace === "string") record.parentNamespace = v.parentNamespace;
+  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);
+  }
+  config;
+  memoryDir;
+  stateDir;
+  catalogPath;
+  rebuildLockPath;
+  // Per-INSTANCE lock owner id (round 6, codex P2 — NBsGP). The rebuild lock
+  // file records this id, not just `process.pid`, so two NamespaceCatalog
+  // instances in the SAME process sharing a memoryDir are NOT mistaken for each
+  // other: a touch on instance B must still wait for instance A's rebuild lock
+  // (different owner id, same PID) instead of skipping as "self-held".
+  lockOwnerId = randomUUID();
+  // Serialized write chain that recovers from rejection (CLAUDE.md rule #40)
+  // so a single failed append cannot permanently poison subsequent writes.
+  writeChain = Promise.resolve();
+  // 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 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;
+  /** 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()];
+  }
+  async loadSanitizedRecords() {
+    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.touch(namespace, "read", metadata);
+  }
+  async markWrite(namespace, metadata) {
+    await this.touch(namespace, "write", metadata);
+  }
+  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 stat3 = await lstat(candidate);
+      if (stat3.isSymbolicLink()) return false;
+      if (!stat3.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 stat3 = await lstat(real);
+        return stat3.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 stat3;
+    try {
+      stat3 = await lstat(root);
+    } catch {
+      return false;
+    }
+    if (stat3.isSymbolicLink()) return false;
+    if (!stat3.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 (metadata?.principal !== void 0) record.principal = metadata.principal;
+        if (metadata?.projectId !== void 0) record.projectId = metadata.projectId;
+        if (metadata?.branch !== void 0) record.branch = metadata.branch;
+        if (metadata?.parentNamespace !== void 0)
+          record.parentNamespace = metadata.parentNamespace;
+        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);
+        return true;
+      })
+    );
+  }
+  // ── 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 Set();
+    for (const entry of entries) {
+      const token = entry.name;
+      const fullPath = path.join(namespacesDir, token);
+      let stat3;
+      try {
+        stat3 = await lstat(fullPath);
+      } catch (err) {
+        skipped.push({ token, reason: "error", detail: err instanceof Error ? err.message : String(err) });
+        continue;
+      }
+      if (stat3.isSymbolicLink()) {
+        skipped.push({ token, reason: "symlink", detail: fullPath });
+        continue;
+      }
+      if (!stat3.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) {
+        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 isTokenizedEntry = token === namespaceIdentityToken(decoded);
+      if (rebuilt.has(decoded) && scannedFromTokenized.has(decoded) && !isTokenizedEntry) {
+        continue;
+      }
+      if (isTokenizedEntry) scannedFromTokenized.add(decoded);
+      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();
+      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.
+   *
+   * Acquisition is atomic via `open(..., "wx")`. A lock older than
+   * `REBUILD_LOCK_STALE_MS` is treated as a crashed holder and broken. After
+   * `REBUILD_LOCK_MAX_WAIT_MS` of contention we proceed best-effort WITHOUT the
+   * lock rather than block forever. The lock is always released in `finally`.
+   *
+   * IN-PROCESS SAFETY: every caller invokes this from inside (or wrapping) the
+   * per-process `queueCritical` chain, which serializes all catalog mutations in
+   * THIS process. 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.
+   *
+   * HEARTBEAT (round 5, cursor/codex Medium/P2): while WE hold the lock a timer
+   * refreshes its mtime every `REBUILD_LOCK_HEARTBEAT_MS`, so a legitimately long
+   * holder (> `REBUILD_LOCK_STALE_MS`) is not treated as a crashed holder and
+   * unlinked by another process — which would let overlapping windows lose
+   * appends. Heartbeat failures are swallowed; the timer is always cleared in
+   * `finally`.
+   *
+   * 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.
+   */
+  async withHeldCatalogLock(fn) {
+    const acquired = await this.acquireRebuildLock();
+    let heartbeat;
+    if (acquired) {
+      heartbeat = setInterval(() => {
+        const now = /* @__PURE__ */ new Date();
+        utimes(this.rebuildLockPath, now, now).catch(() => void 0);
+      }, REBUILD_LOCK_HEARTBEAT_MS);
+      heartbeat.unref?.();
+    }
+    try {
+      return await fn(acquired);
+    } finally {
+      if (heartbeat) clearInterval(heartbeat);
+      if (acquired) {
+        try {
+          if (await this.rebuildLockHeldBySelf()) {
+            await unlink(this.rebuildLockPath);
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  /** Try to acquire the rebuild lock; returns true if WE created it. */
+  async acquireRebuildLock() {
+    const deadline = Date.now() + REBUILD_LOCK_MAX_WAIT_MS;
+    await mkdir(this.stateDir, { recursive: true });
+    for (; ; ) {
+      try {
+        const handle = await open(this.rebuildLockPath, "wx");
+        try {
+          await handle.writeFile(
+            `${process.pid} ${this.lockOwnerId} ${(/* @__PURE__ */ new Date()).toISOString()}
+`,
+            "utf8"
+          );
+        } catch {
+        } finally {
+          await handle.close();
+        }
+        return true;
+      } catch (err) {
+        if (err?.code !== "EEXIST") {
+          return false;
+        }
+        await this.breakStaleRebuildLock();
+        if (Date.now() >= deadline) return false;
+        await new Promise((r) => setTimeout(r, REBUILD_LOCK_POLL_MS));
+      }
+    }
+  }
+  /**
+   * Remove the lock file if its mtime is older than the stale threshold.
+   *
+   * REPLACEMENT-SAFE (NG7Bg, codex P2): a plain `stat` → `unlink` has a TOCTOU
+   * window — two processes can both observe the SAME stale lock; one removes it and
+   * creates a FRESH lock, and the other's later `unlink` then deletes that fresh
+   * holder's ACTIVE lock based on the stale identity it read earlier, leaving the
+   * fresh holder running its critical section with no visible lock and reopening the
+   * lost-update race the mutex prevents. We therefore capture the lock's IDENTITY
+   * (its full content line: `<pid> <owner-uuid> <iso>`) when we judge it stale, then
+   * RE-READ immediately before unlinking and only remove it when the content is
+   * byte-identical AND still stale. A replacement lock has a different owner id /
+   * timestamp, so its content differs and we leave it untouched. We never unlink a
+   * lock whose mtime is now fresh (a heartbeat refreshed it) or whose identity
+   * changed (a replacement was created). This is best-effort: any mismatch/vanish
+   * simply skips the break and the caller polls again.
+   */
+  async breakStaleRebuildLock() {
+    let staleIdentity;
+    try {
+      const info = await stat(this.rebuildLockPath);
+      if (Date.now() - info.mtimeMs <= REBUILD_LOCK_STALE_MS) {
+        return;
+      }
+      staleIdentity = await readFile(this.rebuildLockPath, "utf8");
+    } catch {
+      return;
+    }
+    if (this.onBeforeBreakStaleUnlinkForTest) {
+      await this.onBeforeBreakStaleUnlinkForTest();
+    }
+    try {
+      const current = await readFile(this.rebuildLockPath, "utf8");
+      if (current !== staleIdentity) return;
+      const recheck = await stat(this.rebuildLockPath);
+      if (Date.now() - recheck.mtimeMs <= REBUILD_LOCK_STALE_MS) return;
+      await unlink(this.rebuildLockPath).catch(() => void 0);
+    } catch {
+    }
+  }
+  /**
+   * Whether the rebuild lock file was written by THIS instance (round 6, codex
+   * P2 — NBsGP). Matches the per-instance owner id, NOT just `process.pid`: two
+   * NamespaceCatalog instances in the same process share a PID, so a PID-only
+   * check would wrongly treat instance A's lock as self-held by instance B and
+   * let B's touch skip the wait and append into A's rebuild window. Falls back to
+   * the legacy PID-only form for lock files written before owner ids existed.
+   */
+  async rebuildLockHeldBySelf() {
+    try {
+      const body = await readFile(this.rebuildLockPath, "utf8");
+      const parts = body.trim().split(/\s+/);
+      const pid = Number.parseInt(parts[0] ?? "", 10);
+      const ownerId = parts[1];
+      const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (ownerId && UUID_RE.test(ownerId)) {
+        return ownerId === this.lockOwnerId;
+      }
+      return Number.isFinite(pid) && pid === process.pid;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * 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 };
+    if (prior.principal !== void 0) merged.principal = prior.principal;
+    if (prior.projectId !== void 0) merged.projectId = prior.projectId;
+    if (prior.branch !== void 0) merged.branch = prior.branch;
+    if (prior.parentNamespace !== void 0) merged.parentNamespace = prior.parentNamespace;
+    return merged;
+  }
+  // ── Persistence ──────────────────────────────────────────────────────────
+  /** Load the JSONL log and fold it into current state (last-record-wins). */
+  async loadCompacted() {
+    const records = /* @__PURE__ */ new Map();
+    let raw;
+    try {
+      raw = await readFile(this.catalogPath, "utf8");
+    } catch {
+      return records;
+    }
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        continue;
+      }
+      const record = coerceRecord(parsed);
+      if (!record) continue;
+      const prior = records.get(record.namespace);
+      records.set(record.namespace, prior ? mergeNewerTouchFields(record, prior) : record);
+    }
+    return records;
+  }
+  /**
+   * Serialize an arbitrary read-modify-write critical section through the single
+   * write chain. Every catalog mutation (touch read+merge+append, full rewrite)
+   * runs through this so they are mutually exclusive: a touch always reads the
+   * latest persisted state before appending, and a rebuild rewrite cannot
+   * interleave with a touch's append. The chain recovers from rejection
+   * (CLAUDE.md rule #40) — one failed section never poisons subsequent ones —
+   * while still surfacing the error to that section's awaited promise.
+   */
+  queueCritical(fn) {
+    const run = this.writeChain.then(fn);
+    this.writeChain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  /**
+   * 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";
+    await mkdir(this.stateDir, { recursive: true });
+    await appendFile(this.catalogPath, line, "utf8");
+  }
+  /**
+   * 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);
+  }
+};
+function isPathInside(root, child) {
+  const relative = path.relative(root, child);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+// src/maintenance/namespace-planner.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { lstat as lstat2, mkdir as mkdir2, open as open2, readFile as readFile2, readdir as readdir2, rename as rename2, rm, rmdir, utimes as utimes2, writeFile as writeFile2 } from "fs/promises";
+import path2 from "path";
+var DEFAULT_MAX_NAMESPACES_PER_CYCLE = 20;
+var DEFAULT_LOCK_STALE_MS = 10 * 6e4;
+var LOCK_BASE = "maintenance-locks";
+var STATUS_BASE = "namespace-maintenance-status";
+var namespaceMaintenanceFs = { open: open2, rm };
+function configuredNamespaces(config) {
+  return Array.from(
+    new Set(
+      [config.defaultNamespace, config.sharedNamespace, ...config.namespacePolicies.map((policy) => policy.name)].map((value) => value.trim()).filter(Boolean)
+    )
+  );
+}
+function inferConfiguredKind(config, namespace) {
+  if (namespace === config.defaultNamespace.trim()) return "default";
+  if (namespace === config.sharedNamespace.trim()) return "shared";
+  return "explicit";
+}
+function maxNamespacesPerCycle(config) {
+  return Math.max(
+    1,
+    Math.floor(
+      typeof config.maintenanceMaxNamespacesPerCycle === "number" && Number.isFinite(config.maintenanceMaxNamespacesPerCycle) ? config.maintenanceMaxNamespacesPerCycle : DEFAULT_MAX_NAMESPACES_PER_CYCLE
+    )
+  );
+}
+function namespaceKindAllowed(config, kind) {
+  switch (kind) {
+    case "branch":
+      return config.maintenanceIncludeBranchNamespaces === true;
+    case "project":
+      return config.maintenanceIncludeProjectNamespaces !== false;
+    case "team-project":
+      return config.maintenanceIncludeTeamProjectNamespaces !== false;
+    default:
+      return true;
+  }
+}
+function disabledReasonForKind(kind) {
+  if (kind === "branch") return "branch_disabled";
+  if (kind === "project") return "project_disabled";
+  if (kind === "team-project") return "team_project_disabled";
+  return "fanout_disabled";
+}
+async function catalogRootIsLive(config, record) {
+  if (typeof record.storageDir !== "string" || record.storageDir.length === 0) {
+    return false;
+  }
+  try {
+    const liveRoot = await resolveNamespaceStorageRoot(config, record.namespace);
+    if (path2.resolve(liveRoot) !== path2.resolve(record.storageDir)) return false;
+    return hasMemoryData(liveRoot);
+  } catch {
+    return false;
+  }
+}
+function candidateSortKey(candidate) {
+  const write = candidate.lastWriteAt ?? "";
+  return `${write}\0${candidate.namespace}`;
+}
+function candidatePriority(candidate) {
+  if (candidate.kind === "default") return 0;
+  if (candidate.kind === "shared") return 1;
+  if (candidate.source === "configured") return 2;
+  if (candidate.kind === "team-project") return 3;
+  if (candidate.kind === "project") return 4;
+  if (candidate.kind === "self") return 5;
+  if (candidate.kind === "legacy") return 6;
+  if (candidate.kind === "branch") return 8;
+  return 7;
+}
+function sortCandidates(a, b) {
+  const priority = candidatePriority(a) - candidatePriority(b);
+  if (priority !== 0) return priority;
+  const am = Date.parse(a.lastMaintenanceAt ?? "");
+  const bm = Date.parse(b.lastMaintenanceAt ?? "");
+  const aMaintained = Number.isFinite(am);
+  const bMaintained = Number.isFinite(bm);
+  if (aMaintained && bMaintained && am !== bm) return am - bm;
+  if (aMaintained !== bMaintained) return aMaintained ? 1 : -1;
+  const aw = Date.parse(a.lastWriteAt ?? "");
+  const bw = Date.parse(b.lastWriteAt ?? "");
+  const aValid = Number.isFinite(aw);
+  const bValid = Number.isFinite(bw);
+  if (aValid && bValid && aw !== bw) return bw - aw;
+  if (aValid !== bValid) return aValid ? -1 : 1;
+  const byKey = candidateSortKey(a).localeCompare(candidateSortKey(b));
+  if (byKey !== 0) return byKey;
+  return a.namespace.localeCompare(b.namespace);
+}
+async function planNamespaceMaintenance(config, options) {
+  const generatedAt = (options.now ?? /* @__PURE__ */ new Date()).toISOString();
+  const configured = config.namespacesEnabled ? configuredNamespaces(config) : [config.defaultNamespace.trim()].filter(Boolean);
+  const byNamespace = /* @__PURE__ */ new Map();
+  const skipped = [];
+  for (const namespace of configured) {
+    const kind = inferConfiguredKind(config, namespace);
+    byNamespace.set(namespace, {
+      namespace,
+      kind,
+      source: "configured"
+    });
+  }
+  if (config.namespacesEnabled && config.maintenanceNamespaceFanoutEnabled !== false) {
+    const configuredSet = new Set(configured);
+    try {
+      const records = options.catalog?.enabled ? await options.catalog.listNamespaces() : [];
+      for (const record of records) {
+        const namespace = record.namespace.trim();
+        if (!namespace) continue;
+        const isConfigured = configuredSet.has(namespace);
+        const kind = isConfigured ? inferConfiguredKind(config, namespace) : record.kind;
+        if (!namespaceKindAllowed(config, kind)) {
+          skipped.push({
+            namespace,
+            kind,
+            reason: disabledReasonForKind(kind)
+          });
+          continue;
+        }
+        if (!isConfigured && !await catalogRootIsLive(config, record)) {
+          skipped.push({
+            namespace,
+            kind,
+            reason: "unsafe_or_stale_root"
+          });
+          continue;
+        }
+        byNamespace.set(namespace, {
+          namespace,
+          kind,
+          storageDir: record.storageDir,
+          source: isConfigured ? "configured" : "catalog",
+          lastWriteAt: record.lastWriteAt,
+          lastMaintenanceAt: record.lastMaintenanceAt?.[options.jobName]
+        });
+      }
+    } catch (error) {
+      skipped.push({
+        namespace: "*",
+        reason: "catalog_read_failed",
+        detail: error instanceof Error ? error.message : String(error)
+      });
+    }
+  } else if (config.namespacesEnabled) {
+    skipped.push({
+      namespace: "*",
+      reason: "fanout_disabled"
+    });
+  }
+  if (options.budgetMode !== "unbounded") {
+    const latestStatusAtByNamespace = await readLatestStatusAtByNamespace(config, options.jobName);
+    for (const candidate of byNamespace.values()) {
+      if (!candidate.lastMaintenanceAt) {
+        candidate.lastMaintenanceAt = latestStatusAtByNamespace.get(candidate.namespace);
+      }
+    }
+  }
+  const candidates = [...byNamespace.values()].filter((candidate) => namespaceKindAllowed(config, candidate.kind)).sort(sortCandidates);
+  const max = maxNamespacesPerCycle(config);
+  const applyCycleBudget = options.budgetMode !== "unbounded";
+  const selected = applyCycleBudget ? candidates.slice(0, max) : candidates;
+  if (applyCycleBudget) {
+    for (const candidate of candidates.slice(max)) {
+      skipped.push({
+        namespace: candidate.namespace,
+        kind: candidate.kind,
+        reason: "budget_exhausted"
+      });
+    }
+  }
+  return {
+    jobName: options.jobName,
+    generatedAt,
+    namespaces: selected,
+    skipped,
+    budget: {
+      maxNamespacesPerCycle: max,
+      selected: selected.length
+    }
+  };
+}
+function stablePathSegment(value) {
+  const sanitized = value.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 128) || "unnamed";
+  if (sanitized.length <= 128 && sanitized === value) return sanitized;
+  return `${sanitized.slice(0, 80)}-${createHash("sha256").update(value).digest("hex").slice(0, 16)}`;
+}
+function namespacePathSegment(namespace) {
+  const token = namespaceIdentityToken(namespace);
+  if (token.length <= 160) return token;
+  return `ns-${createHash("sha256").update(namespace).digest("hex")}`;
+}
+function lockPath(config, jobName, namespace) {
+  return path2.join(
+    config.memoryDir,
+    "state",
+    LOCK_BASE,
+    stablePathSegment(jobName),
+    `${namespacePathSegment(namespace)}.lock`
+  );
+}
+function namespaceMaintenanceLockStaleMs(config) {
+  if (typeof config.maintenanceNamespaceLockStaleMs === "number" && Number.isFinite(config.maintenanceNamespaceLockStaleMs) && config.maintenanceNamespaceLockStaleMs > 0) {
+    return Math.floor(config.maintenanceNamespaceLockStaleMs);
+  }
+  return DEFAULT_LOCK_STALE_MS;
+}
+function namespaceMaintenanceLockHeartbeatMs(config) {
+  const staleMs = namespaceMaintenanceLockStaleMs(config);
+  return Math.max(1, Math.min(3e4, Math.floor(staleMs / 3) || 1));
+}
+function errorCode(error) {
+  return typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+}
+async function withNamespaceMaintenanceLockHeartbeat(config, locks, task) {
+  const activeLocks = Array.isArray(locks) ? locks : [locks];
+  const interval = setInterval(() => {
+    for (const lock of activeLocks) {
+      void lock.touch().catch(() => void 0);
+    }
+  }, namespaceMaintenanceLockHeartbeatMs(config));
+  interval.unref?.();
+  try {
+    return await task();
+  } finally {
+    clearInterval(interval);
+  }
+}
+async function removeStaleLockDirectory(filePath) {
+  let entries;
+  try {
+    entries = await readdir2(filePath, { withFileTypes: true });
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    await namespaceMaintenanceFs.rm(path2.join(filePath, entry.name), { force: true });
+  }
+  try {
+    await rmdir(filePath);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return;
+    throw error;
+  }
+}
+async function tryAcquireNamespaceMaintenanceLock(config, jobName, namespace) {
+  const filePath = lockPath(config, jobName, namespace);
+  await mkdir2(path2.dirname(filePath), { recursive: true });
+  try {
+    const lockId = randomUUID2();
+    await mkdir2(filePath);
+    const ownerPath = path2.join(filePath, `${lockId}.json`);
+    let handle;
+    try {
+      handle = await namespaceMaintenanceFs.open(ownerPath, "wx");
+      await handle.writeFile(
+        `${JSON.stringify({
+          lockId,
+          pid: process.pid,
+          jobName,
+          namespace,
+          acquiredAt: (/* @__PURE__ */ new Date()).toISOString()
+        })}
+`,
+        "utf8"
+      );
+      await handle.close();
+    } catch (setupError) {
+      await handle?.close().catch(() => void 0);
+      await namespaceMaintenanceFs.rm(ownerPath, { force: true }).catch(() => void 0);
+      await rmdir(filePath).catch(() => void 0);
+      throw setupError;
+    }
+    return {
+      path: filePath,
+      async touch() {
+        try {
+          const parsed = JSON.parse(await readFile2(ownerPath, "utf8"));
+          if (parsed.lockId === lockId) {
+            const now = /* @__PURE__ */ new Date();
+            await utimes2(ownerPath, now, now);
+            await utimes2(filePath, now, now);
+          }
+        } catch {
+        }
+      },
+      async release() {
+        try {
+          const parsed = JSON.parse(await readFile2(ownerPath, "utf8"));
+          if (parsed.lockId === lockId) {
+            await namespaceMaintenanceFs.rm(ownerPath, { force: true });
+            await rmdir(filePath).catch(() => void 0);
+          }
+        } catch {
+        }
+      }
+    };
+  } catch (error) {
+    if (errorCode(error) === "EEXIST") {
+      const staleMs = namespaceMaintenanceLockStaleMs(config);
+      try {
+        const s = await lstat2(filePath);
+        if (s.isSymbolicLink()) {
+          return null;
+        }
+        if ((s.isFile() || s.isDirectory()) && Date.now() - s.mtimeMs > staleMs) {
+          try {
+            if (s.isDirectory()) {
+              await removeStaleLockDirectory(filePath);
+            } else {
+              await namespaceMaintenanceFs.rm(filePath, { force: true });
+            }
+          } catch (removeError) {
+            if (errorCode(removeError) === "ENOENT") {
+              return tryAcquireNamespaceMaintenanceLock(config, jobName, namespace);
+            }
+            if (errorCode(removeError) === "ENOTEMPTY") {
+              return null;
+            }
+            throw removeError;
+          }
+          return tryAcquireNamespaceMaintenanceLock(config, jobName, namespace);
+        }
+      } catch (statError) {
+        if (errorCode(statError) === "ENOENT") {
+          return tryAcquireNamespaceMaintenanceLock(config, jobName, namespace);
+        }
+        throw statError;
+      }
+      return null;
+    }
+    throw error;
+  }
+}
+function statusBasePath(config) {
+  return path2.join(config.memoryDir, "state", STATUS_BASE);
+}
+function statusPath(config, jobName, namespace) {
+  return path2.join(statusBasePath(config), stablePathSegment(jobName), `${namespacePathSegment(namespace)}.json`);
+}
+function lastRanStatusPath(config, jobName, namespace) {
+  return path2.join(statusBasePath(config), stablePathSegment(jobName), `${namespacePathSegment(namespace)}.last-ran.json`);
+}
+function parseStatus(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const v = value;
+  if (typeof v.namespace === "string" && typeof v.jobName === "string" && (v.state === "ran" || v.state === "skipped" || v.state === "failed") && typeof v.startedAt === "string" && typeof v.completedAt === "string") {
+    return v;
+  }
+  return null;
+}
+async function readLatestStatusAtByNamespace(config, jobName) {
+  const latest = /* @__PURE__ */ new Map();
+  const latestMs = /* @__PURE__ */ new Map();
+  for (const status of [...await readStatusFiles(config), ...await readLastRanStatusFiles(config)]) {
+    if (status.state !== "ran") continue;
+    if (status.jobName !== jobName) continue;
+    const completedAtMs = Date.parse(status.completedAt);
+    if (!Number.isFinite(completedAtMs)) continue;
+    const previousMs = latestMs.get(status.namespace);
+    if (previousMs !== void 0 && previousMs >= completedAtMs) continue;
+    latestMs.set(status.namespace, completedAtMs);
+    latest.set(status.namespace, status.completedAt);
+  }
+  return latest;
+}
+async function readStatusFile(filePath) {
+  try {
+    const parsed = JSON.parse(await readFile2(filePath, "utf8"));
+    return parseStatus(parsed);
+  } catch {
+    return null;
+  }
+}
+async function readStatusFiles(config) {
+  if (typeof config.memoryDir !== "string" || config.memoryDir.length === 0) {
+    return [];
+  }
+  const root = statusBasePath(config);
+  const statuses = [];
+  let jobDirs;
+  try {
+    jobDirs = await readdir2(root, { withFileTypes: true });
+  } catch {
+    return statuses;
+  }
+  for (const jobDir of jobDirs) {
+    if (!jobDir.isDirectory()) continue;
+    let files;
+    try {
+      files = await readdir2(path2.join(root, jobDir.name), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!file.isFile() || !file.name.endsWith(".json")) continue;
+      if (file.name.endsWith(".last-ran.json")) continue;
+      const status = await readStatusFile(path2.join(root, jobDir.name, file.name));
+      if (status) statuses.push(status);
+    }
+  }
+  return statuses;
+}
+async function readLastRanStatusFiles(config) {
+  if (typeof config.memoryDir !== "string" || config.memoryDir.length === 0) {
+    return [];
+  }
+  const root = statusBasePath(config);
+  const statuses = [];
+  let jobDirs;
+  try {
+    jobDirs = await readdir2(root, { withFileTypes: true });
+  } catch {
+    return statuses;
+  }
+  for (const jobDir of jobDirs) {
+    if (!jobDir.isDirectory()) continue;
+    let files;
+    try {
+      files = await readdir2(path2.join(root, jobDir.name), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!file.isFile() || !file.name.endsWith(".last-ran.json")) continue;
+      const status = await readStatusFile(path2.join(root, jobDir.name, file.name));
+      if (status) statuses.push(status);
+    }
+  }
+  return statuses;
+}
+async function writeStatusPayload(target, status) {
+  const dir = path2.dirname(target);
+  await mkdir2(dir, { recursive: true });
+  const temp = `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+  const payload = {
+    version: 1,
+    ...status
+  };
+  await writeFile2(temp, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+  await rename2(temp, target);
+}
+async function writeStatusFile(config, status) {
+  await writeStatusPayload(statusPath(config, status.jobName, status.namespace), status);
+  if (status.state === "ran") {
+    await writeStatusPayload(lastRanStatusPath(config, status.jobName, status.namespace), status);
+  }
+}
+async function recordNamespaceMaintenanceStatusSafely(config, status) {
+  try {
+    await writeStatusFile(config, status);
+  } catch {
+  }
+}
+function maintenanceErrorDetail(error) {
+  return displayErrorDetail(error) || "Error";
+}
+async function readNamespaceMaintenanceStatuses(config) {
+  return (await readStatusFiles(config)).sort((a, b) => {
+    const byJob = a.jobName.localeCompare(b.jobName);
+    if (byJob !== 0) return byJob;
+    return a.namespace.localeCompare(b.namespace);
+  });
+}
+async function readNamespaceMaintenanceLastRanStatuses(config) {
+  return (await readLastRanStatusFiles(config)).sort((a, b) => {
+    const byJob = a.jobName.localeCompare(b.jobName);
+    if (byJob !== 0) return byJob;
+    return a.namespace.localeCompare(b.namespace);
+  });
+}
+async function runNamespaceMaintenancePlan(config, plan, runner, catalog) {
+  const statuses = [];
+  for (const skipped of plan.skipped) {
+    if (skipped.namespace === "*") continue;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const status = {
+      namespace: skipped.namespace,
+      jobName: plan.jobName,
+      state: "skipped",
+      reason: skipped.reason,
+      startedAt: now,
+      completedAt: now
+    };
+    statuses.push(status);
+    await recordNamespaceMaintenanceStatusSafely(config, status);
+  }
+  for (const candidate of plan.namespaces) {
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const lock = await tryAcquireNamespaceMaintenanceLock(config, plan.jobName, candidate.namespace);
+    if (!lock) {
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const status = {
+        namespace: candidate.namespace,
+        jobName: plan.jobName,
+        state: "skipped",
+        reason: "lock_held",
+        startedAt,
+        completedAt
+      };
+      statuses.push(status);
+      await recordNamespaceMaintenanceStatusSafely(config, status);
+      continue;
+    }
+    try {
+      const result = await withNamespaceMaintenanceLockHeartbeat(config, lock, () => runner(candidate));
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      if (result?.skipped) {
+        const status = {
+          namespace: candidate.namespace,
+          jobName: plan.jobName,
+          state: "skipped",
+          reason: result.skipReason ?? "throttled",
+          startedAt,
+          completedAt
+        };
+        statuses.push(status);
+        await recordNamespaceMaintenanceStatusSafely(config, status);
+      } else {
+        const status = {
+          namespace: candidate.namespace,
+          jobName: plan.jobName,
+          state: "ran",
+          startedAt,
+          completedAt,
+          itemCount: result?.itemCount
+        };
+        statuses.push(status);
+        await recordNamespaceMaintenanceStatusSafely(config, status);
+        try {
+          await catalog?.markMaintenance(candidate.namespace, plan.jobName, new Date(completedAt));
+        } catch {
+        }
+      }
+    } catch (error) {
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const status = {
+        namespace: candidate.namespace,
+        jobName: plan.jobName,
+        state: "failed",
+        reason: "job_failed",
+        startedAt,
+        completedAt,
+        error: maintenanceErrorDetail(error)
+      };
+      statuses.push(status);
+      await recordNamespaceMaintenanceStatusSafely(config, status);
+    } finally {
+      await lock.release().catch(() => void 0);
+    }
+  }
+  return {
+    jobName: plan.jobName,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ran: statuses.filter((s) => s.state === "ran").length,
+    skipped: statuses.filter((s) => s.state === "skipped").length,
+    failed: statuses.filter((s) => s.state === "failed").length,
+    statuses
+  };
+}
+async function runNamespaceMaintenanceBatchPlan(config, plan, runner, catalog, options = {}) {
+  const statuses = [];
+  for (const skipped of plan.skipped) {
+    if (skipped.namespace === "*") continue;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const status = {
+      namespace: skipped.namespace,
+      jobName: plan.jobName,
+      state: "skipped",
+      reason: skipped.reason,
+      startedAt: now,
+      completedAt: now
+    };
+    statuses.push(status);
+    await recordNamespaceMaintenanceStatusSafely(config, status);
+  }
+  const acquired = [];
+  try {
+    for (const candidate of plan.namespaces) {
+      const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const lock = await tryAcquireNamespaceMaintenanceLock(config, plan.jobName, candidate.namespace);
+      if (!lock) {
+        const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+        const status = {
+          namespace: candidate.namespace,
+          jobName: plan.jobName,
+          state: "skipped",
+          reason: "lock_held",
+          startedAt,
+          completedAt
+        };
+        statuses.push(status);
+        await recordNamespaceMaintenanceStatusSafely(config, status);
+        continue;
+      }
+      acquired.push({ candidate, lock, startedAt });
+    }
+  } catch (error) {
+    await Promise.all(acquired.map(({ lock }) => lock.release().catch(() => void 0)));
+    throw error;
+  }
+  if (options.requireAllLocks && acquired.length > 0 && acquired.length < plan.namespaces.length) {
+    for (const { candidate, startedAt } of acquired) {
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const status = {
+        namespace: candidate.namespace,
+        jobName: plan.jobName,
+        state: "skipped",
+        reason: "batch_lock_incomplete",
+        startedAt,
+        completedAt
+      };
+      statuses.push(status);
+      await recordNamespaceMaintenanceStatusSafely(config, status);
+    }
+    await Promise.all(acquired.map(({ lock }) => lock.release().catch(() => void 0)));
+    return {
+      jobName: plan.jobName,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ran: statuses.filter((s) => s.state === "ran").length,
+      skipped: statuses.filter((s) => s.state === "skipped").length,
+      failed: statuses.filter((s) => s.state === "failed").length,
+      statuses
+    };
+  }
+  if (acquired.length === 0) {
+    return {
+      jobName: plan.jobName,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ran: statuses.filter((s) => s.state === "ran").length,
+      skipped: statuses.filter((s) => s.state === "skipped").length,
+      failed: statuses.filter((s) => s.state === "failed").length,
+      statuses
+    };
+  }
+  try {
+    const result = await withNamespaceMaintenanceLockHeartbeat(
+      config,
+      acquired.map(({ lock }) => lock),
+      () => runner(acquired.map(({ candidate }) => candidate))
+    );
+    for (const { candidate, startedAt } of acquired) {
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const status = {
+        namespace: candidate.namespace,
+        jobName: plan.jobName,
+        state: "ran",
+        startedAt,
+        completedAt,
+        itemCount: itemCountForNamespace(result, candidate.namespace)
+      };
+      statuses.push(status);
+      await recordNamespaceMaintenanceStatusSafely(config, status);
+      try {
+        await catalog?.markMaintenance(candidate.namespace, plan.jobName, new Date(completedAt));
+      } catch {
+      }
+    }
+  } catch (error) {
+    const skipReason = options.skipReasonForError?.(error);
+    for (const { candidate, startedAt } of acquired) {
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const status = skipReason ? {
+        namespace: candidate.namespace,
+        jobName: plan.jobName,
+        state: "skipped",
+        reason: skipReason,
+        startedAt,
+        completedAt
+      } : {
+        namespace: candidate.namespace,
+        jobName: plan.jobName,
+        state: "failed",
+        reason: "job_failed",
+        startedAt,
+        completedAt,
+        error: maintenanceErrorDetail(error)
+      };
+      statuses.push(status);
+      await recordNamespaceMaintenanceStatusSafely(config, status);
+    }
+  } finally {
+    await Promise.all(acquired.map(({ lock }) => lock.release().catch(() => void 0)));
+  }
+  return {
+    jobName: plan.jobName,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ran: statuses.filter((s) => s.state === "ran").length,
+    skipped: statuses.filter((s) => s.state === "skipped").length,
+    failed: statuses.filter((s) => s.state === "failed").length,
+    statuses
+  };
+}
+function itemCountForNamespace(result, namespace) {
+  const itemCounts = result?.itemCounts;
+  if (itemCounts instanceof Map) return itemCounts.get(namespace);
+  if (itemCounts && Object.prototype.hasOwnProperty.call(itemCounts, namespace)) {
+    return itemCounts[namespace];
+  }
+  return result?.itemCount;
+}
+
+// src/maintenance/namespace-maintenance-fanout.ts
+var NAMESPACE_MAINTENANCE_JOBS = [
+  "qmd",
+  "pattern-reinforcement",
+  "contradiction-scan",
+  "semantic-consolidation",
+  "governance",
+  "lifecycle",
+  "graph-decay",
+  "fact-archival",
+  "tier-migration"
+];
+async function runNamespaceMaintenanceFanout(options) {
+  if (options.enabled === false) {
+    return {
+      jobName: options.jobName,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ran: 0,
+      skipped: 0,
+      failed: 0,
+      statuses: []
+    };
+  }
+  const plan = await planNamespaceMaintenance(options.config, {
+    jobName: options.jobName,
+    catalog: options.catalog
+  });
+  return runNamespaceMaintenancePlan(
+    options.config,
+    plan,
+    async (candidate) => {
+      return options.runner({
+        config: options.config,
+        candidate,
+        resolveStorage: options.resolveStorage
+      });
+    },
+    options.catalog
+  );
+}
+async function summarizeNamespaceMaintenanceHealth(config) {
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const statuses = await readNamespaceMaintenanceStatuses(config);
+  const lastRanStatuses = await readNamespaceMaintenanceLastRanStatuses(config);
+  const lastRanByJobNs = /* @__PURE__ */ new Map();
+  for (const lr of lastRanStatuses) {
+    lastRanByJobNs.set(`${lr.jobName}\0${lr.namespace}`, lr);
+  }
+  const byJob = /* @__PURE__ */ new Map();
+  for (const status of statuses) {
+    const bucket = byJob.get(status.jobName);
+    if (bucket) {
+      bucket.push(status);
+    } else {
+      byJob.set(status.jobName, [status]);
+    }
+  }
+  const knownJobs = new Set(NAMESPACE_MAINTENANCE_JOBS);
+  for (const jobName of byJob.keys()) {
+    knownJobs.add(jobName);
+  }
+  const jobs = [];
+  let totalRan = 0;
+  let totalSkipped = 0;
+  let totalFailed = 0;
+  for (const jobName of [...knownJobs].sort()) {
+    const jobStatuses = byJob.get(jobName) ?? [];
+    const ran = jobStatuses.filter((s) => s.state === "ran").length;
+    const skipped = jobStatuses.filter((s) => s.state === "skipped").length;
+    const failed = jobStatuses.filter((s) => s.state === "failed").length;
+    const candidates = [];
+    for (const st of jobStatuses) {
+      if (typeof st.completedAt === "string") candidates.push(st.completedAt);
+      const lr = lastRanByJobNs.get(`${jobName}\0${st.namespace}`);
+      if (lr && typeof lr.completedAt === "string") candidates.push(lr.completedAt);
+    }
+    const lastRunAt = candidates.sort().at(-1) ?? null;
+    totalRan += ran;
+    totalSkipped += skipped;
+    totalFailed += failed;
+    jobs.push({
+      jobName,
+      ran,
+      skipped,
+      failed,
+      lastRunAt,
+      namespaces: jobStatuses
+    });
+  }
+  return {
+    generatedAt,
+    fanoutEnabled: config.maintenanceNamespaceFanoutEnabled !== false,
+    namespacesEnabled: config.namespacesEnabled,
+    maxNamespacesPerCycle: config.maintenanceMaxNamespacesPerCycle,
+    jobs,
+    totalRan,
+    totalSkipped,
+    totalFailed
+  };
+}
+function formatNamespaceMaintenanceHealthText(summary) {
+  const lines = [
+    "=== Namespace Maintenance ===",
+    "",
+    `  fanout:        ${summary.fanoutEnabled ? "enabled" : "disabled"}`,
+    `  namespaces:    ${summary.namespacesEnabled ? "enabled" : "disabled"}`,
+    `  max/cycle:     ${summary.maxNamespacesPerCycle}`,
+    `  total ran:     ${summary.totalRan}`,
+    `  total skipped: ${summary.totalSkipped}`,
+    `  total failed:  ${summary.totalFailed}`,
+    ""
+  ];
+  if (summary.totalRan === 0 && summary.totalSkipped === 0 && summary.totalFailed === 0) {
+    lines.push("  (no maintenance status recorded yet)");
+    return lines.join("\n");
+  }
+  lines.push("  Per-job breakdown:");
+  for (const job of summary.jobs) {
+    const parts = [
+      `ran=${job.ran}`,
+      `skipped=${job.skipped}`,
+      `failed=${job.failed}`
+    ];
+    if (job.lastRunAt) {
+      parts.push(`last=${job.lastRunAt}`);
+    }
+    lines.push(`    ${job.jobName}: ${parts.join(", ")}`);
+    const failedNs = job.namespaces.filter((n) => n.state === "failed");
+    for (const ns of failedNs) {
+      const detail = ns.error ? `: ${ns.error}` : "";
+      lines.push(`      ! ${ns.namespace} failed (reason=${ns.reason ?? "unknown"})${detail}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export {
+  NamespaceCatalog,
+  planNamespaceMaintenance,
+  runNamespaceMaintenanceBatchPlan,
+  runNamespaceMaintenanceFanout,
+  summarizeNamespaceMaintenanceHealth,
+  formatNamespaceMaintenanceHealthText
+};
+//# sourceMappingURL=chunk-ZU7N3S6V.js.map