@remnic/core 9.3.653 → 9.3.654

package/dist/{orchestrator-8fTZsa0y.d.ts → orchestrator-B4Y4sWQH.d.ts}

@@ -18,9 +18,9 @@ import { a as SemanticDedupHit } from './semantic-DJR8_DMQ.js';
 import { ReplayTurn } from './replay/types.js';
 import { I as ImportTurn } from './types-ByK7T3L6.js';
 import { JudgeCandidate, JudgeBatchResult } from './extraction-judge.js';
-import { Y as BufferTurn, af as ExtractionResult, M as MemoryCategory, I as ImportanceScore, h as MemoryStatus, aw as WearableConversation, ax as WearableSourceSettings, ay as WearableNativeMemory, az as WearableMemoryMode, aA as WearableSourceConnector, aB as WearablesConfig, aC as WearableSyncSummary, aD as WearableSourceStatus, aE as WearableDayTranscript, aF as WearableCorrectionRule, P as PluginConfig, aG as CodingContext, Z as QmdSearchResult, e as BehaviorLoopPolicyState, aH as BootstrapOptions, aI as BootstrapResult, aJ as ConsolidationObservation, g as MemoryFile, ah as DaySummaryResult, m as MemoryActionEvent, H as RecallPlanMode, ai as MemoryIntent, aK as EntityTimelineEntry, j as MemoryFrontmatter, J as IdentityInjectionMode } from './types-D8yUmSik.js';
+import { Y as BufferTurn, af as ExtractionResult, M as MemoryCategory, I as ImportanceScore, h as MemoryStatus, aw as WearableConversation, ax as WearableSourceSettings, ay as WearableNativeMemory, az as WearableMemoryMode, aA as WearableSourceConnector, aB as WearablesConfig, aC as WearableSyncSummary, aD as WearableSourceStatus, aE as WearableDayTranscript, aF as WearableCorrectionRule, P as PluginConfig, aG as CodingContext, Z as QmdSearchResult, e as BehaviorLoopPolicyState, aH as BootstrapOptions, aI as BootstrapResult, aJ as ConsolidationObservation, g as MemoryFile, ah as DaySummaryResult, m as MemoryActionEvent, H as RecallPlanMode, ai as MemoryIntent, aK as EntityTimelineEntry, j as MemoryFrontmatter, J as IdentityInjectionMode } from './types-BgChEr0M.js';
 import { LcmEngine } from './lcm/engine.js';
-import { S as SemanticConsolidationResult } from './semantic-consolidation-DKdYzQOg.js';
+import { S as SemanticConsolidationResult } from './semantic-consolidation-BKd0Pype.js';
 import { ConversationIndexBackendInspection } from './conversation-index/backend.js';
 import { NamespaceSearchHealth } from './namespaces/search.js';
 import { SharedContextManager } from './shared-context/manager.js';
@@ -527,6 +527,459 @@ declare function locateTranscriptPath(hitPath: string): {
     date: string;
 } | null;
 
+/**
+ * Rebuildable namespace catalog (issue #1499).
+ *
+ * Purpose: a downstream, rebuildable metadata index that lets Remnic ENUMERATE
+ * the configured and dynamically-created namespaces that exist or should be
+ * maintained. Filesystem memory remains the single source of truth; the catalog
+ * is derived metadata and can always be reconstructed from disk.
+ *
+ * Storage format: `<memoryDir>/state/namespaces.jsonl` — an append-and-compact
+ * JSON-lines log. We chose this over per-namespace sidecar files because:
+ *   - touches (markRead/markWrite/markMaintenance) are cheap single appends;
+ *   - it is naturally audit-friendly (the raw log preserves touch history);
+ *   - a single file makes enumeration trivial (no directory walk per call);
+ *   - last-record-wins compaction folds the log into the current state on read,
+ *     and `rebuildFromDisk` rewrites it atomically (temp file + rename).
+ *
+ * SECURITY:
+ *   - The catalog stores ONLY metadata (namespace names, kinds, timestamps,
+ *     resolved storage dirs). It NEVER holds raw memory content or secrets.
+ *   - Catalog presence grants NO authorization. Read/write access still flows
+ *     through the namespace policies in `principal.ts`; this module never makes
+ *     an access decision.
+ *   - All namespace tokens are validated with `isSafeRouteNamespace` (except the
+ *     configured default namespace, which is exempt at the routing layer) and
+ *     every storage dir is contained under `<memoryDir>/namespaces`.
+ *   - `rebuildFromDisk` rejects/reports symlinked roots that escape the memory
+ *     root rather than trusting them.
+ *
+ * LIFECYCLE: catalog write failures must NEVER crash a primary memory op.
+ * Callers should wrap touch calls in try/catch (or rely on the internal
+ * failure-tolerant append). The internal serialized write chain recovers from
+ * rejection so one failed append cannot poison subsequent writes.
+ */
+type NamespaceKind = "default" | "self" | "shared" | "project" | "branch" | "team-project" | "explicit" | "legacy";
+type NamespaceDiscoverySource = "config" | "write" | "read" | "scan" | "migration";
+interface NamespaceRecord {
+    namespace: string;
+    identityToken: string;
+    kind: NamespaceKind;
+    principal?: string;
+    projectId?: string;
+    branch?: string;
+    parentNamespace?: string;
+    createdAt: string;
+    lastReadAt?: string;
+    lastWriteAt?: string;
+    lastMaintenanceAt?: Record<string, string>;
+    storageDir: string;
+    discoveredBy: NamespaceDiscoverySource;
+}
+interface NamespaceCatalogFilter {
+    kind?: NamespaceKind;
+    discoveredBy?: NamespaceDiscoverySource;
+    /** Only include namespaces written since this instant (inclusive lower bound). */
+    writtenSince?: Date;
+}
+interface NamespaceTouchMetadata {
+    discoveredBy?: NamespaceDiscoverySource;
+    kind?: NamespaceKind;
+    principal?: string;
+    projectId?: string;
+    branch?: string;
+    parentNamespace?: string;
+    /** Explicit storage dir (when the caller already resolved it). */
+    storageDir?: string;
+    /** Override the touch timestamp (mainly for tests / migration replay). */
+    at?: Date;
+}
+interface NamespaceCatalogSkippedRoot {
+    token: string;
+    reason: "symlink" | "escape" | "unsafe" | "error";
+    detail?: string;
+}
+interface NamespaceCatalogRebuildResult {
+    dryRun: boolean;
+    records: NamespaceRecord[];
+    /** Roots reported as ambiguous/unsafe rather than silently misclassified. */
+    skipped: NamespaceCatalogSkippedRoot[];
+    /**
+     * Whether the rebuild actually rewrote the on-disk catalog (round 6, codex P2
+     * / cursor Medium — NBn3n/NBsGG). `false` for a dry-run, AND for an `--apply`
+     * that could NOT acquire the cross-process rebuild lock within the bounded wait
+     * (it ran compute-only to avoid clobbering a concurrent lock holder). Callers
+     * (CLI) must NOT report unqualified success when `applied` is false for a
+     * non-dry-run — the catalog was left unchanged and a retry is needed.
+     */
+    applied: boolean;
+}
+declare class NamespaceCatalog {
+    private readonly config;
+    private readonly memoryDir;
+    private readonly stateDir;
+    private readonly catalogPath;
+    private readonly rebuildLockPath;
+    private readonly lockOwnerId;
+    private writeChain;
+    protected onTouchCriticalSectionForTest?: () => Promise<void>;
+    protected onRebuildBeforeRenameForTest?: () => Promise<void>;
+    protected onRebuildAfterScanForTest?: () => Promise<void>;
+    protected onBeforeBreakStaleUnlinkForTest?: () => Promise<void>;
+    private readonly defaultNamespaceIdentity;
+    constructor(config: PluginConfig);
+    /** Whether the catalog is active (namespaces enabled and catalog not opted out). */
+    get enabled(): boolean;
+    /**
+     * 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).
+     */
+    private sanitizeRecordForRead;
+    private storageRootOwnershipRank;
+    private configuredNamespaceIdentities;
+    private preferStorageRootOwner;
+    private dropDuplicateStorageRootAliases;
+    private loadSanitizedRecords;
+    listNamespaces(filter?: NamespaceCatalogFilter): Promise<NamespaceRecord[]>;
+    getNamespaceRecord(namespace: string): Promise<NamespaceRecord | null>;
+    markRead(namespace: string, metadata?: NamespaceTouchMetadata): Promise<void>;
+    markWrite(namespace: string, metadata?: NamespaceTouchMetadata): Promise<void>;
+    markMaintenance(namespace: string, jobName: string, at?: Date): Promise<void>;
+    /**
+     * Register namespaces known purely from config (default, shared, explicit
+     * policies). Source `config`. Cheap and idempotent.
+     */
+    registerConfiguredNamespaces(): Promise<void>;
+    /**
+     * 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.
+     */
+    registerResolved(namespace: string, storageDir: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    private register;
+    private validateNamespace;
+    /**
+     * 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.
+     */
+    private resolveStorageDir;
+    private namespaceTokenDir;
+    /**
+     * 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.
+     */
+    private isLexicallyContained;
+    /**
+     * 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.
+     */
+    private isContainedStorageDir;
+    /**
+     * 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.
+     */
+    private hasSymlinkedAncestor;
+    /**
+     * 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.
+     */
+    private isNearestExistingAncestorContained;
+    /**
+     * 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.
+     */
+    private resolveTouchStorageDir;
+    /**
+     * 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.
+     */
+    private isStorageDirForNamespace;
+    /**
+     * 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`.
+     */
+    private resolveSafeStorageDir;
+    /**
+     * 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`.
+     */
+    private safeFallbackStorageDir;
+    /**
+     * 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.
+     */
+    private liveStorageRootExistsForRebuild;
+    /**
+     * 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.
+     */
+    private touch;
+    rebuildFromDisk(options?: {
+        dryRun?: boolean;
+    }): Promise<NamespaceCatalogRebuildResult>;
+    /**
+     * 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.
+     */
+    private rebuildInsideChain;
+    /**
+     * 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`.
+     */
+    private finishRebuild;
+    /**
+     * 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.
+     */
+    private withHeldCatalogLock;
+    /** Try to acquire the rebuild lock; returns true if WE created it. */
+    private acquireRebuildLock;
+    /**
+     * 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.
+     */
+    private breakStaleRebuildLock;
+    /**
+     * 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.
+     */
+    private rebuildLockHeldBySelf;
+    /**
+     * 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.
+     */
+    private mergeForRebuild;
+    /** Load the JSONL log and fold it into current state (last-record-wins). */
+    private loadCompacted;
+    /**
+     * 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.
+     */
+    private queueCritical;
+    /**
+     * 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.
+     */
+    private appendUnchained;
+    /**
+     * 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.
+     */
+    private rewriteUnchained;
+}
+
 interface BulkImportBatchIngestResult {
     attemptedTurnCount: number;
     extractionCount: number;
@@ -825,6 +1278,10 @@ declare function resolvePersistedMemoryRelativePath(options: {
 declare class Orchestrator {
     readonly storage: StorageManager;
     private readonly storageRouter;
+    /** Rebuildable namespace catalog (issue #1499). Inert unless namespaces enabled. */
+    readonly namespaceCatalog: NamespaceCatalog;
+    private readonly namespaceStorageDirHints;
+    private namespaceStorageDirHintsLoaded;
     private readonly namespaceSearchRouter;
     qmd: SearchBackend;
     private readonly conversationQmd?;
@@ -1124,6 +1581,26 @@ declare class Orchestrator {
     } | null;
     getStorageForNamespace(namespace?: string): Promise<StorageManager>;
     private configuredNamespaces;
+    private rememberNamespaceStorageDirHint;
+    private storageDirMatchesNamespaceHint;
+    private namespaceStorageDirHintOwnershipRank;
+    private preferNamespaceStorageDirHintOwner;
+    private loadNamespaceStorageDirHintsFromCatalog;
+    /**
+     * Namespaces that QMD maintenance (update/embed) must cover: the CONFIGURED set
+     * PLUS every dynamic namespace recorded in the catalog (NGnei, codex P2). An
+     * extraction that writes to a coding-scoped/dynamic namespace (not in
+     * defaultNamespace/sharedNamespace/namespacePolicies) is only made discoverable
+     * via the catalog; if maintenance embeds only `configuredNamespaces()`, that
+     * namespace's QMD collection is never updated/embedded after writes and
+     * recall/search stays stale or empty until it is manually configured. We union in
+     * the catalog's namespaces so maintenance keeps dynamic namespaces fresh.
+     * `updateNamespaces`/`embedNamespaces` already trim, dedup, and skip
+     * unavailable/missing collections, so extra names are filtered safely. A catalog
+     * read failure must never break maintenance — fall back to the configured set.
+     */
+    private maintenanceNamespaces;
+    private isCatalogedMaintenanceRootLive;
     private buildConfiguredQmdSearchOptions;
     searchAcrossNamespaces(options: {
         query: string;
@@ -1761,8 +2238,31 @@ declare class Orchestrator {
     private graphSeedPathsWithinDeadline;
     private namespaceFromPath;
     private namespaceFromStorageDir;
+    /**
+     * Record a namespace write in the catalog (issue #1499). Best-effort and
+     * failure-tolerant: a catalog write error MUST NOT crash the primary memory
+     * write (CLAUDE.md gotcha #13, rule #40). Fire-and-forget by design.
+     */
+    private markCatalogWrite;
+    /**
+     * Public best-effort catalog write touch (issue #1499). User-facing explicit
+     * captures (`memory_store`) and review-queue approvals persist via
+     * `persistExplicitCapture()` → `storage.writeMemory()`, which bypasses the
+     * extraction write path that calls `markCatalogWrite`. Without this their
+     * namespaces never record `lastWriteAt`, so the catalog under-reports write
+     * recency (round 5, codex P2). Fire-and-forget and failure-tolerant — a
+     * catalog error must never affect the explicit write (gotcha #13, rule #40).
+     *
+     * An undefined/empty `namespace` means the write targeted the DEFAULT namespace
+     * (`getStorage(undefined)` routes there), so we record it under the configured
+     * default rather than skipping it (round 6, codex P2 — default `memory_store`
+     * and inline-note writes were missing from `writtenSince`/maintenance).
+     */
+    recordCatalogWrite(namespace?: string, storageDir?: string): void;
+    /** Record a namespace read in the catalog. Best-effort, failure-tolerant. */
+    private markCatalogRead;
     private readAllMemoriesForNamespaces;
     private readArchivedMemoriesForNamespaces;
 }
 
-export { computeArtifactCandidateFetchLimit as $, sanitizeSessionKeyForFilename as A, saveSpeakerRegistry as B, speakerRegistryKey as C, DEFAULT_SELF_NAME as D, speakersFilePath as E, syncWearableSource as F, type GraphRecallSnapshot as G, wearableDayTag as H, type IntentDebugSnapshot as I, wearableSourceLabel as J, writeDailyDigestMemory as K, type BulkImportBatchIngestResult as L, BulkImportBatchPartialFailureError as M, type GraphRecallRankedResult as N, Orchestrator as O, type PatternReinforcementResult as P, type GraphRecallShadowComparison as Q, type ResolvedSpeaker as R, type SpeakerRegistry as S, type QmdRecallSnapshot as T, type RecallInvocationOptions as U, type RecallModeDecision as V, WearablesService as W, appendMemoryToGraphContext as X, blendGraphExpandedRecallScore as Y, buildCompressionGuidelinesMarkdown as Z, buildMemoryPathById as _, type SpeakerOverride as a, computeArtifactRecallLimit as a0, computeQmdHybridFetchLimit as a1, dedupeEntitySynthesisEvidenceEntries as a2, deriveTopicsFromExtraction as a3, filterRecallCandidates as a4, formatCompressionGuidelinesForRecall as a5, graphPathRelativeToStorage as a6, hasIdentityRecoveryIntent as a7, isArtifactMemoryPath as a8, lifecycleRecallScoreAdjustment as a9, mergeArtifactRecallCandidates as aa, mergeGraphExpandedResults as ab, resolveEffectiveIdentityInjectionMode as ac, resolveEffectiveRecallMode as ad, resolvePersistedMemoryRelativePath as ae, resolveRecallModeDecision as af, resolveRecallModeDecisionAsync as ag, resolveRecentThreadMemoryPaths as ah, shouldFilterLifecycleRecallCandidate as ai, summarizeGraphShadowComparison as aj, WEARABLE_SOURCE_PREFIX as b, type WearableDayTranscriptView as c, type WearableMemoryGenDeps as d, type WearableMemoryGenResult as e, type WearableMemorySearchResult as f, type WearableMemoryWriter as g, type WearableSearchBackend as h, type WearableStorageIo as i, type WearableSyncDeps as j, type WearableSyncOptions as k, type WearableTranscriptSearchResult as l, type WearablesServiceDeps as m, buildExtractionTurns as n, dateInTimezone as o, defaultTimezone as p, defaultWorkspaceDir as q, distinctSpeakerLabels as r, emptySpeakerRegistry as s, generateWearableMemories as t, importNativeMemories as u, loadSpeakerRegistry as v, locateTranscriptPath as w, memoryStatusForMode as x, resolveSpeaker as y, resolveSyncDates as z };
+export { type GraphRecallShadowComparison as $, generateWearableMemories as A, importNativeMemories as B, loadSpeakerRegistry as C, DEFAULT_SELF_NAME as D, locateTranscriptPath as E, memoryStatusForMode as F, type GraphRecallSnapshot as G, resolveSpeaker as H, type IntentDebugSnapshot as I, resolveSyncDates as J, sanitizeSessionKeyForFilename as K, saveSpeakerRegistry as L, speakerRegistryKey as M, NamespaceCatalog as N, Orchestrator as O, type PatternReinforcementResult as P, speakersFilePath as Q, type ResolvedSpeaker as R, type SpeakerRegistry as S, syncWearableSource as T, wearableDayTag as U, wearableSourceLabel as V, WearablesService as W, writeDailyDigestMemory as X, type BulkImportBatchIngestResult as Y, BulkImportBatchPartialFailureError as Z, type GraphRecallRankedResult as _, type NamespaceCatalogFilter as a, type QmdRecallSnapshot as a0, type RecallInvocationOptions as a1, type RecallModeDecision as a2, appendMemoryToGraphContext as a3, blendGraphExpandedRecallScore as a4, buildCompressionGuidelinesMarkdown as a5, buildMemoryPathById as a6, computeArtifactCandidateFetchLimit as a7, computeArtifactRecallLimit as a8, computeQmdHybridFetchLimit as a9, dedupeEntitySynthesisEvidenceEntries as aa, deriveTopicsFromExtraction as ab, filterRecallCandidates as ac, formatCompressionGuidelinesForRecall as ad, graphPathRelativeToStorage as ae, hasIdentityRecoveryIntent as af, isArtifactMemoryPath as ag, lifecycleRecallScoreAdjustment as ah, mergeArtifactRecallCandidates as ai, mergeGraphExpandedResults as aj, resolveEffectiveIdentityInjectionMode as ak, resolveEffectiveRecallMode as al, resolvePersistedMemoryRelativePath as am, resolveRecallModeDecision as an, resolveRecallModeDecisionAsync as ao, resolveRecentThreadMemoryPaths as ap, shouldFilterLifecycleRecallCandidate as aq, summarizeGraphShadowComparison as ar, type NamespaceCatalogRebuildResult as b, type NamespaceCatalogSkippedRoot as c, type NamespaceDiscoverySource as d, type NamespaceKind as e, type NamespaceRecord as f, type NamespaceTouchMetadata as g, type SpeakerOverride as h, WEARABLE_SOURCE_PREFIX as i, type WearableDayTranscriptView as j, type WearableMemoryGenDeps as k, type WearableMemoryGenResult as l, type WearableMemorySearchResult as m, type WearableMemoryWriter as n, type WearableSearchBackend as o, type WearableStorageIo as p, type WearableSyncDeps as q, type WearableSyncOptions as r, type WearableTranscriptSearchResult as s, type WearablesServiceDeps as t, buildExtractionTurns as u, dateInTimezone as v, defaultTimezone as w, defaultWorkspaceDir as x, distinctSpeakerLabels as y, emptySpeakerRegistry as z };

package/dist/orchestrator.d.ts

@@ -7,7 +7,7 @@ import './summarizer.js';
 import './local-llm.js';
 import './fallback-llm.js';
 import './live-connectors-runner.js';
-export { L as BulkImportBatchIngestResult, M as BulkImportBatchPartialFailureError, N as GraphRecallRankedResult, Q as GraphRecallShadowComparison, G as GraphRecallSnapshot, I as IntentDebugSnapshot, O as Orchestrator, T as QmdRecallSnapshot, U as RecallInvocationOptions, V as RecallModeDecision, X as appendMemoryToGraphContext, Y as blendGraphExpandedRecallScore, Z as buildCompressionGuidelinesMarkdown, _ as buildMemoryPathById, $ as computeArtifactCandidateFetchLimit, a0 as computeArtifactRecallLimit, a1 as computeQmdHybridFetchLimit, a2 as dedupeEntitySynthesisEvidenceEntries, q as defaultWorkspaceDir, a3 as deriveTopicsFromExtraction, a4 as filterRecallCandidates, a5 as formatCompressionGuidelinesForRecall, a6 as graphPathRelativeToStorage, a7 as hasIdentityRecoveryIntent, a8 as isArtifactMemoryPath, a9 as lifecycleRecallScoreAdjustment, aa as mergeArtifactRecallCandidates, ab as mergeGraphExpandedResults, ac as resolveEffectiveIdentityInjectionMode, ad as resolveEffectiveRecallMode, ae as resolvePersistedMemoryRelativePath, af as resolveRecallModeDecision, ag as resolveRecallModeDecisionAsync, ah as resolveRecentThreadMemoryPaths, A as sanitizeSessionKeyForFilename, ai as shouldFilterLifecycleRecallCandidate, aj as summarizeGraphShadowComparison } from './orchestrator-8fTZsa0y.js';
+export { Y as BulkImportBatchIngestResult, Z as BulkImportBatchPartialFailureError, _ as GraphRecallRankedResult, $ as GraphRecallShadowComparison, G as GraphRecallSnapshot, I as IntentDebugSnapshot, O as Orchestrator, a0 as QmdRecallSnapshot, a1 as RecallInvocationOptions, a2 as RecallModeDecision, a3 as appendMemoryToGraphContext, a4 as blendGraphExpandedRecallScore, a5 as buildCompressionGuidelinesMarkdown, a6 as buildMemoryPathById, a7 as computeArtifactCandidateFetchLimit, a8 as computeArtifactRecallLimit, a9 as computeQmdHybridFetchLimit, aa as dedupeEntitySynthesisEvidenceEntries, x as defaultWorkspaceDir, ab as deriveTopicsFromExtraction, ac as filterRecallCandidates, ad as formatCompressionGuidelinesForRecall, ae as graphPathRelativeToStorage, af as hasIdentityRecoveryIntent, ag as isArtifactMemoryPath, ah as lifecycleRecallScoreAdjustment, ai as mergeArtifactRecallCandidates, aj as mergeGraphExpandedResults, ak as resolveEffectiveIdentityInjectionMode, al as resolveEffectiveRecallMode, am as resolvePersistedMemoryRelativePath, an as resolveRecallModeDecision, ao as resolveRecallModeDecisionAsync, ap as resolveRecentThreadMemoryPaths, K as sanitizeSessionKeyForFilename, aq as shouldFilterLifecycleRecallCandidate, ar as summarizeGraphShadowComparison } from './orchestrator-B4Y4sWQH.js';
 import './model-registry.js';
 import './relevance.js';
 import './negative.js';
@@ -18,9 +18,9 @@ import './embedding-fallback.js';
 import './semantic-DJR8_DMQ.js';
 import './replay/types.js';
 import './types-ByK7T3L6.js';
-import './types-D8yUmSik.js';
+import './types-BgChEr0M.js';
 import './lcm/engine.js';
-import './semantic-consolidation-DKdYzQOg.js';
+import './semantic-consolidation-BKd0Pype.js';
 import './conversation-index/backend.js';
 import './namespaces/search.js';
 import './shared-context/manager.js';