@remnic/core 9.69.56 → 9.69.58

package/dist/migrate/from-engram.d.ts

@@ -1,11 +1,11 @@
-interface MigrationResult {
+export interface MigrationResult {
     status: "fresh-install" | "already-migrated" | "migrated";
     copied: string[];
     tokensRegenerated: number;
     servicesReinstalled: string[];
     rollbackCommand: string;
 }
-interface MigrationOptions {
+export interface MigrationOptions {
     connectorConfigPaths?: string[];
     cwd?: string;
     execCommand?: (command: string, args: string[]) => void;
@@ -14,11 +14,10 @@ interface MigrationOptions {
     platform?: NodeJS.Platform;
     quiet?: boolean;
 }
-interface RollbackResult {
+export interface RollbackResult {
     removed: string[];
     restored: string[];
 }
-declare function rollbackFromEngramMigration(options?: MigrationOptions): Promise<RollbackResult>;
-declare function migrateFromEngram(options?: MigrationOptions): Promise<MigrationResult>;
-
-export { type MigrationOptions, type MigrationResult, type RollbackResult, migrateFromEngram, rollbackFromEngramMigration };
+export declare function rollbackFromEngramMigration(options?: MigrationOptions): Promise<RollbackResult>;
+export declare function migrateFromEngram(options?: MigrationOptions): Promise<MigrationResult>;
+//# sourceMappingURL=from-engram.d.ts.map

package/dist/migrate/from-engram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-engram.d.ts","sourceRoot":"","sources":["../../src/migrate/from-engram.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,GAAG,kBAAkB,GAAG,UAAU,CAAC;IAC1D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;CACzB;AAuBD,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA64BD,wBAAsB,2BAA2B,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CA8DrG;AAED,wBAAsB,iBAAiB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA8F5F"}

package/dist/model-registry.d.ts

@@ -2,7 +2,7 @@
  * Model Registry - Stores and retrieves model capabilities
  * Avoids repeated external lookups by caching model info locally
  */
-interface ModelCapabilities {
+export interface ModelCapabilities {
     modelId: string;
     maxPositionEmbeddings: number;
     contextWindow: number;
@@ -16,7 +16,7 @@ interface ModelCapabilities {
     source: "huggingface" | "lmstudio" | "manual" | "default";
     fetchedAt: string;
 }
-declare class ModelRegistry {
+export declare class ModelRegistry {
     private registryPath;
     private data;
     private readonly CACHE_TTL_DAYS;
@@ -56,5 +56,4 @@ declare class ModelRegistry {
      */
     cleanExpired(): number;
 }
-
-export { type ModelCapabilities, ModelRegistry };
+//# sourceMappingURL=model-registry.d.ts.map

package/dist/model-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-registry.d.ts","sourceRoot":"","sources":["../src/model-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,OAAO,CAAC;IACjC,WAAW,CAAC,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,6BAA6B,EAAE,MAAM,CAAC;KACvC,CAAC;IACF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AA0FD,qBAAa,aAAa;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAK;gBAExB,SAAS,EAAE,MAAM;IAS7B,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB;IAsCnD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,WAAW,CAAC,GAAG,IAAI;IAYtG;;;OAGG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG;QACnE,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;KACrB;IAkDD;;;OAGG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO7D;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAItB;;OAEG;IACH,YAAY,IAAI,MAAM;CAavB"}

package/dist/models-json.d.ts

@@ -1,34 +1,15 @@
-import { O as ModelProviderConfig } from './types-Du6VdoAg.js';
-import './message-parts/index.js';
-import './bounded-jsonl-state.js';
-import './operator-doctor-types.js';
-import './external-wiki-config.js';
-import './recall-state-view.js';
-import './contradiction-config.js';
-import './graph-path-scoring-config.js';
-import './background-generation-config.js';
-import './deep-recall-config.js';
-import './recall-navigation-config.js';
-import './recall-recognition-tier.js';
-import './causal-trajectory.js';
-import './objective-state.js';
-import './active-context-config.js';
-import './local-llm-config.js';
-import './semantic-merge-config.js';
-import './types-continuity.js';
-
+import type { ModelProviderConfig } from "./types.js";
 /**
  * Load the full providers map from the gateway's models.json.
  * Returns an empty object if the file doesn't exist or can't be parsed.
  */
-declare function loadModelsJsonProviders(): Record<string, ModelProviderConfig>;
+export declare function loadModelsJsonProviders(): Record<string, ModelProviderConfig>;
 /**
  * Clear the cached providers (useful for testing).
  */
-declare function clearModelsJsonCache(): void;
+export declare function clearModelsJsonCache(): void;
 /**
  * Inject a providers map for testing, bypassing file I/O.
  */
-declare function __setModelsJsonForTest(providers: Record<string, ModelProviderConfig>): void;
-
-export { __setModelsJsonForTest, clearModelsJsonCache, loadModelsJsonProviders };
+export declare function __setModelsJsonForTest(providers: Record<string, ModelProviderConfig>): void;
+//# sourceMappingURL=models-json.d.ts.map

package/dist/models-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models-json.d.ts","sourceRoot":"","sources":["../src/models-json.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAsBtD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CA6B7E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,IAAI,CAG3F"}

package/dist/namespaces/catalog.d.ts

@@ -0,0 +1,473 @@
+import type { PluginConfig } from "../types.js";
+/**
+ * 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.
+ */
+export type NamespaceKind = "default" | "shared" | "project" | "branch" | "team-project" | "explicit";
+export type NamespaceDiscoverySource = "config" | "write" | "read" | "scan" | "migration";
+export interface NamespaceRecord {
+    namespace: string;
+    identityToken: string;
+    kind: NamespaceKind;
+    createdAt: string;
+    lastReadAt?: string;
+    lastWriteAt?: string;
+    lastMaintenanceAt?: Record<string, string>;
+    storageDir: string;
+    discoveredBy: NamespaceDiscoverySource;
+}
+export interface NamespaceCatalogFilter {
+    kind?: NamespaceKind;
+    discoveredBy?: NamespaceDiscoverySource;
+    /** Only include namespaces written since this instant (inclusive lower bound). */
+    writtenSince?: Date;
+}
+export interface NamespaceTouchMetadata {
+    discoveredBy?: NamespaceDiscoverySource;
+    kind?: NamespaceKind;
+    /** Explicit storage dir (when the caller already resolved it). */
+    storageDir?: string;
+    /** Override the touch timestamp (mainly for tests / migration replay). */
+    at?: Date;
+}
+export interface NamespaceCatalogSkippedRoot {
+    token: string;
+    reason: "symlink" | "escape" | "unsafe" | "error";
+    detail?: string;
+}
+export 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;
+}
+export declare function hasMemoryData(rootDir: string): Promise<boolean>;
+export declare function isNamespaceKind(value: unknown): value is NamespaceKind;
+export declare class NamespaceCatalog {
+    private readonly config;
+    private readonly memoryDir;
+    private readonly stateDir;
+    private readonly catalogPath;
+    private readonly rebuildLockPath;
+    private readonly criticalSection;
+    private compactedCache;
+    protected onTouchCriticalSectionForTest?: () => Promise<void>;
+    protected onCatalogReadForTest?: () => void;
+    protected onAfterCatalogAppendForTest?: () => Promise<void>;
+    protected onRebuildBeforeRenameForTest?: () => Promise<void>;
+    protected onRebuildAfterScanForTest?: () => Promise<void>;
+    protected onBeforeBreakStaleUnlinkForTest?: () => Promise<void>;
+    private readonly defaultNamespaceIdentity;
+    private readonly compactBytesLimit;
+    private readonly readCoalesceMs;
+    private readonly writeCoalesceMs;
+    private lastCompactedSize;
+    private readonly pendingTouches;
+    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>;
+    /**
+     * Route a read/write touch through the per-(namespace, kind) coalescing buffer
+     * (issue #1903). A touch flushes IMMEDIATELY (bypassing the buffer) whenever it
+     * is semantically observable to an in-process reader — first sight of the
+     * namespace, a `config`→`write` provenance upgrade, the first time a touch
+     * field is set (so `listNamespaces({ writtenSince })` and record presence stay
+     * correct), or a change to `kind`/`principal`/`projectId`/`branch`/
+     * `parentNamespace`. A pure timestamp refresh on an already-known record is
+     * DEFERRED and coalesced: the newest buffered `at`/metadata wins and a single
+     * `touch` runs when the window elapses (or on `flushPendingTouches`). Window
+     * `0` skips the buffer entirely (the pre-#1903 immediate-append behavior).
+     * Best-effort: coalescing decisions read only the warm `compactedCache`, never
+     * forcing a disk parse; a cold cache flushes immediately (and re-warms it).
+     */
+    private coalesceTouch;
+    /**
+     * Whether a read/write touch on an EXISTING cached record must flush
+     * immediately rather than coalesce. Only pure timestamp refreshes (the value
+     * returns false) are safe to defer.
+     */
+    private touchMustFlushImmediately;
+    /** Fire a single buffered touch when its coalescing window elapses. */
+    private flushPendingTouch;
+    /**
+     * Flush every buffered coalesced touch now (issue #1903). Called from the
+     * router/orchestrator shutdown hook so a long-lived host does not drop
+     * buffered read/write timestamps on teardown, and by tests to make coalesced
+     * touches deterministically observable. Best-effort: a failed flush never
+     * throws (each touch is `.catch()`-guarded).
+     */
+    flushPendingTouches(): 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;
+    /**
+     * Fold-and-rewrite the JSONL log when it exceeds `compactBytesLimit`
+     * (issue #1903). MUST be called only from inside `touch`'s held-lock +
+     * `queueCritical` critical section — it reuses `loadCompacted` (last-record-
+     * wins fold; every namespace row survives) and `rewriteUnchained` (atomic
+     * temp-file + rename), so the collapse is cross-process safe and never
+     * invokes the disk-scan purge in `finishRebuild`. Best-effort and fail-open
+     * (rule #40): the append already succeeded and is durable, so a failed
+     * compaction must not fail the touch — the next over-limit touch retries.
+     */
+    private maybeAutoCompact;
+    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.
+     *
+     * Issue #1524 adoption: this is now a thin delegation to the shared
+     * `withHeldFileLock` utility. The acquire loop, mtime heartbeat, stale-break
+     * (NG7Bg replacement-safe), and ownership-checked release (NCzT6) all live in
+     * ONE place — the util — so this module no longer re-implements them. The
+     * catalog's `REBUILD_LOCK_*` constants and the `onBeforeBreakStaleUnlinkForTest`
+     * seam flow straight through. The util generates a per-CALL owner uuid, which
+     * is stricter than the previous per-instance `lockOwnerId` (two calls on the
+     * same instance get different ids, so neither mistakes the other's lock as
+     * self-held — the NBsGP invariant, preserved and tightened).
+     *
+     * IN-PROCESS SAFETY: every caller invokes this from inside (or wrapping) the
+     * per-process `queueCritical` chain, which serializes all catalog mutations in
+     * THIS process (now via `MutationSerializer`). So within one process only one
+     * logical holder attempts OS-lock acquisition at a time — the file lock is never
+     * self-contended in-process, and the lock is acquired and released within a
+     * single in-process turn. The file lock adds only the missing CROSS-process
+     * exclusion.
+     *
+     * ACQUISITION RESULT (round 6, codex P2 — NBPmY): `fn` receives whether WE
+     * actually hold the lock. When acquisition TIMED OUT (another holder is active),
+     * a MUTATING rebuild must NOT perform its load/rename window unlocked, and a
+     * touch must NOT append unlocked — both would recreate the lost-append race. The
+     * caller uses `acquired` to run compute-only (rebuild) or DROP the append
+     * (touch) when unlocked.
+     */
+    private withHeldCatalogLock;
+    /**
+     * 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;
+    private cloneCompactedRecords;
+    /**
+     * Serialize an arbitrary read-modify-write critical section through the single
+     * per-instance chain. Every catalog mutation and cached catalog read runs
+     * through this queue, so cache validation and updates cannot race in-process.
+     *
+     * Issue #1524 adoption: delegates to the shared `MutationSerializer` (stored
+     * as `criticalSection`). The util owns the rejection-recovery invariant
+     * (CLAUDE.md rule #40 — one failed section never poisons subsequent ones, but
+     * the failing section's error still surfaces to ITS awaited promise) and the
+     * no-unbounded-growth cleanup. The key is constant: the catalog has ONE
+     * logical mutation queue (touches and rebuilds mutually exclude in-process).
+     */
+    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;
+    private refreshCacheAfterAppend;
+    private refreshCacheIdentity;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/dist/namespaces/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/namespaces/catalog.ts"],"names":[],"mappings":"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"}

package/dist/namespaces/identity.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeNamespaceIdentity(namespace: string | null | undefined): string;
+export declare function namespaceIdentityToken(namespace: string): string;
+export declare function namespaceIdentityLegacyToken(namespace: string): string;
+export declare function namespaceIdentityFromToken(token: string): string | null;
+//# sourceMappingURL=identity.d.ts.map

package/dist/namespaces/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/namespaces/identity.ts"],"names":[],"mappings":"AAAA,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAEvF;AAQD,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAavE"}