@remnic/core 10.0.56 → 10.0.57

package/dist/namespaces/catalog-repair.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Single-flight gate for the malformed-catalog repair (#3298 review), extracted
+ * from catalog.ts so that file stays under its structural-ratchet ceiling
+ * (issue #1995). Pure scheduling state plus the quarantine-sidecar path helper.
+ */
+/** After a dropped attempt, wait this long before another read may schedule one. */
+export declare const MALFORMED_REPAIR_DROP_BACKOFF_MS = 250;
+/**
+ * Bounds repairs triggered by malformed reads (#3298 review): one attempt in
+ * flight at a time, and a short backoff after an attempt was dropped (another
+ * process held the lock). The guard is what stops concurrent malformed reads
+ * from queueing serial lock waits ahead of touch(); the 5 s lock wait is itself
+ * the rate limiter under sustained contention, which is why the backoff is
+ * short — a longer window would delay the legitimate warm-cache retry after
+ * contention clears. A fast failure holds no lock budget and does not back off.
+ */
+export declare class MalformedCatalogRepairGate {
+    private inFlight;
+    private nextAttemptAt;
+    private attempts;
+    /** Test-only observability: attempts that actually entered the gate. */
+    get attemptCount(): number;
+    /**
+     * Run `attempt` unless one is already in flight or the backoff window is on.
+     * Resolves when the attempt settles; never rejects (the repair is fail-open).
+     */
+    run(attempt: () => Promise<"repaired" | "dropped" | "failed">): Promise<void>;
+}
+/**
+ * Quarantine sidecar path for the rows a repair drops (#3298 review): named by a
+ * hash of the dropped lines, so repeated attempts over the same bad rows reuse
+ * one file instead of piling one sidecar per failed attempt.
+ */
+export declare function malformedSidecarPath(catalogPath: string, dropped: string[]): string;
+//# sourceMappingURL=catalog-repair.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-repair.d.ts","sourceRoot":"","sources":["../../src/namespaces/catalog-repair.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,oFAAoF;AACpF,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD;;;;;;;;GAQG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAK;IAErB,wEAAwE;IACxE,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAoB9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAEnF"}

package/dist/namespaces/catalog.d.ts

@@ -89,6 +89,15 @@ export interface NamespaceCatalogRebuildResult {
 }
 export declare function hasMemoryData(rootDir: string): Promise<boolean>;
 export declare function isNamespaceKind(value: unknown): value is NamespaceKind;
+/**
+ * Fold the touch fields (lastReadAt / lastWriteAt / lastMaintenanceAt) from a
+ * freshly re-read on-disk record into the rebuilt record, taking the LATER
+ * timestamp per field (round 5 cross-process re-merge). Disk-derived fields
+ * (storageDir, kind, discoveredBy, createdAt, principal hints) are owned by the
+ * rebuilt record and left untouched — we only recover touch recency that a
+ * concurrent (possibly cross-process) writer recorded after our initial load.
+ */
+export declare function mergeNewerTouchFields(base: NamespaceRecord, fresh: NamespaceRecord): NamespaceRecord;
 export declare class NamespaceCatalog {
     private readonly config;
     private readonly memoryDir;
@@ -107,38 +116,15 @@ export declare class NamespaceCatalog {
     private readonly compactBytesLimit;
     private readonly readCoalesceMs;
     private readonly writeCoalesceMs;
+    private readonly malformedRepairGate;
+    /** Test-only observability: how many repair attempts actually entered the gate. */
+    get malformedRepairAttemptsForTest(): number;
     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 catalogReadBoundaryPort;
     private loadSanitizedRecords;
     listNamespaces(filter?: NamespaceCatalogFilter, options?: NamespaceCatalogReadOptions): Promise<NamespaceRecord[]>;
     getNamespaceRecord(namespace: string): Promise<NamespaceRecord | null>;
@@ -357,6 +343,24 @@ export declare class NamespaceCatalog {
      * suppressing its retry.
      */
     private touch;
+    /**
+     * Rewrite the catalog after a read skipped malformed rows (#3297). Same fold-and-rewrite as the
+     * size-triggered compaction — the readable rows survive, the malformed ones do not — so a stuck
+     * bad row stops keeping every completion request owed. Best-effort and fail-open (rule #40): a
+     * failed rewrite leaves the catalog unchanged and the next read reports and retries.
+     *
+     * Locking: the fold runs inside `queueCritical` (in-process serialization, like every other
+     * read), and the rewrite's load→rename window runs under the held catalog file lock, so it can
+     * never interleave with another process's touch append or rebuild. If another process already
+     * holds the lock, the rewrite is dropped (not queued): that process's own rewrite or rebuild is
+     * the likeliest repair, and the next incomplete read retries anyway.
+     *
+     * Data safety: the locked re-read must itself reach the end of the file and still find
+     * malformed rows, and must leave at least one readable row. A failed re-read folds to an empty
+     * map, and a catalog with nothing readable is left for `rebuildFromDisk`: rewriting either
+     * would replace a healthy or recoverable catalog with an empty file.
+     */
+    private rewriteAfterIncompleteRead;
     /**
      * Fold-and-rewrite the JSONL log when it exceeds `compactBytesLimit`
      * (issue #1903). MUST be called only from inside `touch`'s held-lock +

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

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

package/dist/operator-toolkit.js

@@ -14,8 +14,8 @@ import {
   summarizeProvenanceCoverage,
   summarizeTierDistribution,
   summarizeTombstoneStatus
-} from "./chunk-GMRP3HN3.js";
-import "./chunk-CZS7UTXL.js";
+} from "./chunk-W3R77WHT.js";
+import "./chunk-KCTL5EY7.js";
 import "./chunk-KFY3SGN7.js";
 import "./chunk-CMTINOFS.js";
 import "./chunk-M4U25HLR.js";
@@ -54,7 +54,7 @@ import "./chunk-G2XTGEGL.js";
 import "./chunk-27NO2KVB.js";
 import "./chunk-KFZY2OFH.js";
 import "./chunk-B32WYRXX.js";
-import "./chunk-S3OI5DP5.js";
+import "./chunk-P5FYZH5G.js";
 import "./chunk-QS5DUSBM.js";
 import "./chunk-B6SPPYGJ.js";
 import "./chunk-TTTPTQ6S.js";

package/dist/orchestration/maintenance.js

@@ -1,20 +1,20 @@
 import {
   MaintenanceScheduler
-} from "../chunk-5C44AMRV.js";
+} from "../chunk-L5UB5BIY.js";
 import "../chunk-666A3MOW.js";
 import "../chunk-B43P3DTC.js";
 import "../chunk-6CDNOREO.js";
 import "../chunk-53OFDW3P.js";
 import "../chunk-5KBIOI4G.js";
 import "../chunk-IFOCK3OJ.js";
-import "../chunk-CZS7UTXL.js";
+import "../chunk-KCTL5EY7.js";
 import "../chunk-QAHP5SBG.js";
 import "../chunk-KJTKLXTH.js";
 import "../chunk-2DQ2XREU.js";
 import "../chunk-J5WI4QRP.js";
 import "../chunk-EWMRFW3F.js";
 import "../chunk-V4VCBFAL.js";
-import "../chunk-S3OI5DP5.js";
+import "../chunk-P5FYZH5G.js";
 import "../chunk-OGXXGHW6.js";
 import "../chunk-WR5POHQ3.js";
 import "../chunk-TTTPTQ6S.js";

package/dist/orchestrator.js

@@ -4,13 +4,13 @@ import {
   graphPathRelativeToStorage,
   mergeGraphExpandedResults,
   qmdStartupCollectionChecksWithTimeout
-} from "./chunk-CC2ESKHP.js";
+} from "./chunk-E2YAGEFR.js";
 import "./chunk-YDIOMDBW.js";
 import "./chunk-HM3ZTDAX.js";
 import {
   formatCompressionGuidelinesForRecall
 } from "./chunk-5PHOU5QI.js";
-import "./chunk-5C44AMRV.js";
+import "./chunk-L5UB5BIY.js";
 import "./chunk-I74SUMNI.js";
 import "./chunk-ILNPU5W5.js";
 import "./chunk-VZAKYDMJ.js";
@@ -121,7 +121,7 @@ import "./chunk-PYIR4SSB.js";
 import "./chunk-7G5NTS7F.js";
 import "./chunk-FFQNNFHX.js";
 import "./chunk-3I4FUAVJ.js";
-import "./chunk-OGR52N7A.js";
+import "./chunk-W2KH27MQ.js";
 import "./chunk-MMACM5G2.js";
 import "./chunk-54BGIBCR.js";
 import "./chunk-H4CKS5B2.js";
@@ -164,8 +164,8 @@ import "./chunk-HDN7IVIO.js";
 import "./chunk-LR7RW4T6.js";
 import "./chunk-3T74IZB3.js";
 import "./chunk-2LA3H54D.js";
-import "./chunk-GMRP3HN3.js";
-import "./chunk-CZS7UTXL.js";
+import "./chunk-W3R77WHT.js";
+import "./chunk-KCTL5EY7.js";
 import "./chunk-KFY3SGN7.js";
 import "./chunk-CMTINOFS.js";
 import "./chunk-M4U25HLR.js";
@@ -238,7 +238,7 @@ import "./chunk-27NO2KVB.js";
 import "./chunk-KFZY2OFH.js";
 import "./chunk-B32WYRXX.js";
 import "./chunk-QW27DOHG.js";
-import "./chunk-FCAXGYDT.js";
+import "./chunk-CTNDFKEX.js";
 import "./chunk-V7IZKJI3.js";
 import "./chunk-TB6CBZ5V.js";
 import "./chunk-XW2T4QAW.js";
@@ -283,8 +283,8 @@ import "./chunk-2FLFJTCI.js";
 import "./chunk-JATHBCAV.js";
 import "./chunk-ZQUVBZI4.js";
 import "./chunk-5R627MYY.js";
-import "./chunk-VZ7VJGPL.js";
-import "./chunk-S3OI5DP5.js";
+import "./chunk-W4QTA2H5.js";
+import "./chunk-P5FYZH5G.js";
 import "./chunk-AB3A7EFH.js";
 import "./chunk-KIUVEMBI.js";
 import "./chunk-HJ4X4BGS.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "10.0.56",
+  "version": "10.0.57",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3346,7 +3346,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^10.0.56"
+    "@remnic/coding-graph": "^10.0.57"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/namespaces/catalog-read-boundary.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { PluginConfig } from "../types.js";
+import type { NamespaceRecord } from "./catalog.js";
+import { namespaceIdentityToken } from "./identity.js";
+import {
+  configuredNamespaceIdentities,
+  dropDuplicateStorageRootAliases,
+  preferStorageRootOwner,
+  sanitizeRecordForRead,
+  storageRootOwnershipRank,
+  type CatalogReadBoundaryPort,
+} from "./catalog-read-boundary.js";
+
+/**
+ * Config for the name-only boundary functions. Object.create(null) yields an untyped value, so
+ * no assertion is needed: the functions read only the three namespace-name fields.
+ */
+function namesOnlyConfig(
+  defaultNamespace: string,
+  sharedNamespace: string,
+  policyNames: string[],
+): PluginConfig {
+  return Object.assign(Object.create(null), {
+    defaultNamespace,
+    sharedNamespace,
+    namespacePolicies: policyNames.map((name) => ({ name, readPrincipals: [], writePrincipals: [] })),
+  });
+}
+
+const config = namesOnlyConfig("default", "shared", ["project-a"]);
+
+const port: CatalogReadBoundaryPort = {
+  defaultNamespaceIdentity: "default",
+  memoryDir: "/mem",
+  async isContainedStorageDir(candidate) {
+    return candidate.startsWith("/mem/namespaces/");
+  },
+  async isStorageDirForNamespace() {
+    return true;
+  },
+  async resolveSafeStorageDir(namespace) {
+    return `/mem/namespaces/${namespaceIdentityToken(namespace)}`;
+  },
+};
+
+function rec(namespace: string, storageDir: string): NamespaceRecord {
+  // SAFETY: this literal is a complete NamespaceRecord; the cast only supplies the optional
+  // timestamp fields (lastReadAt/lastWriteAt/lastMaintenanceAt) as undefined.
+  return {
+    namespace,
+    identityToken: namespaceIdentityToken(namespace),
+    kind: "project",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    storageDir,
+    discoveredBy: "write",
+  };
+}
+
+test("storageRootOwnershipRank orders the ownership tiers", () => {
+  const configured = configuredNamespaceIdentities(config);
+  const tokenA = namespaceIdentityToken("project-a");
+  // Tier 0: the catalog-owned literal for a configured namespace.
+  assert.equal(storageRootOwnershipRank(port, rec("project-a", `/mem/namespaces/${tokenA}`), `/mem/namespaces/${tokenA}`, configured), 0);
+  // Tier 1: the namespace name is the root's leaf.
+  assert.equal(storageRootOwnershipRank(port, rec("leaf", "/mem/namespaces/leaf"), "/mem/namespaces/leaf", configured), 1);
+  // Tier 2: token-shaped root for an unconfigured namespace.
+  const tokenOther = namespaceIdentityToken("other");
+  assert.equal(storageRootOwnershipRank(port, rec("other", `/mem/namespaces/${tokenOther}`), `/mem/namespaces/${tokenOther}`, configured), 2);
+  // Tier 3: neither, and the memoryDir root is only owned by the default namespace.
+  assert.equal(storageRootOwnershipRank(port, rec("other", "/mem/unrelated-root"), "/mem/unrelated-root", configured), 3);
+  assert.equal(storageRootOwnershipRank(port, rec("default", "/mem"), "/mem", configured), 0, "the default namespace owns the memoryDir root");
+  assert.equal(storageRootOwnershipRank(port, rec("other", "/mem"), "/mem", configured), 3);
+});
+
+test("configuredNamespaceIdentities drops empty names and keeps configured ones", () => {
+  const cfg = namesOnlyConfig(" default ", "", ["  ", "project-a"]);
+  assert.deepEqual([...configuredNamespaceIdentities(cfg)].sort(), ["default", "project-a"]);
+  // A single-character namespace is a valid identity and must survive the empty filter.
+  const shortCfg = namesOnlyConfig("x", "y", []);
+  assert.deepEqual([...configuredNamespaceIdentities(shortCfg)].sort(), ["x", "y"]);
+});
+
+test("preferStorageRootOwner breaks ties by name then identityToken", () => {
+  const configured = configuredNamespaceIdentities(config);
+  const a = rec("beta", "/mem/x");
+  const b = rec("alpha", "/mem/x");
+  assert.equal(preferStorageRootOwner(port, a, b, "/mem/x", configured), b);
+  assert.equal(preferStorageRootOwner(port, b, a, "/mem/x", configured), b);
+  // Same name: the lower identityToken wins, whichever side it arrives on.
+  const t1 = { ...rec("alpha", "/mem/x"), identityToken: "token-one" };
+  const t2 = { ...rec("alpha", "/mem/x"), identityToken: "token-two" };
+  assert.equal(preferStorageRootOwner(port, t2, t1, "/mem/x", configured), t1);
+  assert.equal(preferStorageRootOwner(port, t1, t2, "/mem/x", configured), t1);
+  // Exact identity tie: the CURRENT wins (localeCompare returns 0, and 0 < 0 is false).
+  const same1 = rec("alpha", "/mem/x");
+  const same2 = { ...rec("alpha", "/mem/x"), lastWriteAt: "2026-02-02T00:00:00.000Z" };
+  assert.equal(preferStorageRootOwner(port, same1, same2, "/mem/x", configured), same1);
+  assert.equal(preferStorageRootOwner(port, same2, same1, "/mem/x", configured), same2);
+  // Candidate sorts AFTER the current name: the current wins on the name comparison alone.
+  const zeta = rec("zeta", "/mem/x");
+  assert.equal(preferStorageRootOwner(port, b, zeta, "/mem/x", configured), b);
+  assert.equal(preferStorageRootOwner(port, zeta, b, "/mem/x", configured), b);
+});
+
+test("dropDuplicateStorageRootAliases keeps one owner per root and merges the alias's recency", () => {
+  const tokenA = namespaceIdentityToken("project-a");
+  const configured = rec("project-a", `/mem/namespaces/${tokenA}`);
+  const alias = { ...rec("other", `/mem/namespaces/${tokenA}`), lastWriteAt: "2026-02-02T00:00:00.000Z" };
+  const out = dropDuplicateStorageRootAliases(port, [alias, configured], config);
+  assert.equal(out.length, 1);
+  assert.equal(out[0].namespace, "project-a");
+  assert.equal(out[0].lastWriteAt, "2026-02-02T00:00:00.000Z", "the dropped alias's recency survives in the owner");
+});
+
+test("sanitizeRecordForRead drops unsafe names and substitutes unsafe storage dirs", async () => {
+  assert.equal(await sanitizeRecordForRead(port, rec("../evil", "/mem/x")), null);
+  const safe = await sanitizeRecordForRead(port, rec("alpha", "/mem/elsewhere"));
+  assert.ok(safe);
+  assert.equal(safe.storageDir, `/mem/namespaces/${namespaceIdentityToken("alpha")}`);
+});

package/src/namespaces/catalog-read-boundary.ts

@@ -0,0 +1,159 @@
+import path from "node:path";
+import type { PluginConfig } from "../types.js";
+import { namespaceIdentityToken, normalizeNamespaceIdentity } from "./identity.js";
+import { mergeNewerTouchFields } from "./catalog.js";
+import type { NamespaceRecord } from "./catalog.js";
+import { isSafeRouteNamespace } from "../routing/engine.js";
+
+/**
+ * Read-boundary sanitation for NamespaceCatalog (extracted in #3297): the two
+ * defenses against a tampered or pre-fix `namespaces.jsonl` row, and the
+ * storage-root alias collapse that picks one owner per physical root.
+ */
+export interface CatalogReadBoundaryPort {
+  defaultNamespaceIdentity: string;
+  memoryDir: string;
+  isContainedStorageDir(candidate: string): Promise<boolean>;
+  isStorageDirForNamespace(
+    namespace: string,
+    candidate: string,
+  ): Promise<boolean>;
+  resolveSafeStorageDir(namespace: string): Promise<string>;
+}
+
+/**
+ * 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).
+ */
+export async function sanitizeRecordForRead(
+  port: CatalogReadBoundaryPort,
+  record: NamespaceRecord,
+): Promise<NamespaceRecord | null> {
+  // Defense 1: drop an unsafe non-default namespace name entirely. Compare
+  // against the NORMALIZED default identity — record keys are trimmed, so a raw
+  // whitespace-padded config default would never match the default row (NH-FH).
+  if (
+    record.namespace !== port.defaultNamespaceIdentity &&
+    !isSafeRouteNamespace(record.namespace)
+  ) {
+    return null;
+  }
+  // Defense 2: keep the record but substitute a safe storageDir when needed.
+  if (
+    (await port.isContainedStorageDir(record.storageDir)) &&
+    (await port.isStorageDirForNamespace(record.namespace, record.storageDir))
+  ) {
+    return record;
+  }
+  const safe = await port.resolveSafeStorageDir(record.namespace);
+  return { ...record, storageDir: safe };
+}
+
+export function storageRootOwnershipRank(
+  port: CatalogReadBoundaryPort,
+  record: NamespaceRecord,
+  resolvedStorageDir: string,
+  configured: Set<string>,
+): number {
+  if (resolvedStorageDir === path.resolve(port.memoryDir)) {
+    return record.namespace === port.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;
+}
+
+export function configuredNamespaceIdentities(
+  config: PluginConfig,
+): Set<string> {
+  return new Set(
+    [
+      config.defaultNamespace,
+      config.sharedNamespace,
+      ...config.namespacePolicies.map((p) => p.name),
+    ]
+      .map((n) => normalizeNamespaceIdentity(n))
+      .filter((n) => n.length > 0),
+  );
+}
+
+export function preferStorageRootOwner(
+  port: CatalogReadBoundaryPort,
+  current: NamespaceRecord,
+  candidate: NamespaceRecord,
+  resolvedStorageDir: string,
+  configured: Set<string>,
+): NamespaceRecord {
+  const currentRank = storageRootOwnershipRank(
+    port,
+    current,
+    resolvedStorageDir,
+    configured,
+  );
+  const candidateRank = storageRootOwnershipRank(
+    port,
+    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;
+}
+
+export function dropDuplicateStorageRootAliases(
+  port: CatalogReadBoundaryPort,
+  records: NamespaceRecord[],
+  config: PluginConfig,
+): NamespaceRecord[] {
+  const byStorageDir = new Map<string, NamespaceRecord>();
+  const configured = configuredNamespaceIdentities(config);
+  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 = preferStorageRootOwner(
+      port,
+      current,
+      record,
+      resolvedStorageDir,
+      configured,
+    );
+    const alias = owner === current ? record : current;
+    byStorageDir.set(resolvedStorageDir, mergeNewerTouchFields(owner, alias));
+  }
+  return [...byStorageDir.values()];
+}

package/src/namespaces/catalog-repair.ts

@@ -0,0 +1,69 @@
+/**
+ * Single-flight gate for the malformed-catalog repair (#3298 review), extracted
+ * from catalog.ts so that file stays under its structural-ratchet ceiling
+ * (issue #1995). Pure scheduling state plus the quarantine-sidecar path helper.
+ */
+
+import { createHash } from "node:crypto";
+
+/** After a dropped attempt, wait this long before another read may schedule one. */
+export const MALFORMED_REPAIR_DROP_BACKOFF_MS = 250;
+
+/**
+ * Bounds repairs triggered by malformed reads (#3298 review): one attempt in
+ * flight at a time, and a short backoff after an attempt was dropped (another
+ * process held the lock). The guard is what stops concurrent malformed reads
+ * from queueing serial lock waits ahead of touch(); the 5 s lock wait is itself
+ * the rate limiter under sustained contention, which is why the backoff is
+ * short — a longer window would delay the legitimate warm-cache retry after
+ * contention clears. A fast failure holds no lock budget and does not back off.
+ */
+export class MalformedCatalogRepairGate {
+  private inFlight: Promise<void> | undefined;
+  private nextAttemptAt = 0;
+  private attempts = 0;
+
+  /** Test-only observability: attempts that actually entered the gate. */
+  get attemptCount(): number {
+    return this.attempts;
+  }
+
+  /**
+   * Run `attempt` unless one is already in flight or the backoff window is on.
+   * Resolves when the attempt settles; never rejects (the repair is fail-open).
+   */
+  run(attempt: () => Promise<"repaired" | "dropped" | "failed">): Promise<void> {
+    if (this.inFlight || Date.now() < this.nextAttemptAt) return Promise.resolve();
+    this.attempts += 1;
+    // Start the attempt as a microtask so run() returns before any of its work
+    // begins, keeping the guard decision synchronous for every caller.
+    this.inFlight = Promise.resolve().then(async () => {
+      let outcome: "repaired" | "dropped" | "failed" = "failed";
+      try {
+        outcome = await attempt();
+      } catch {
+        outcome = "failed";
+      } finally {
+        this.inFlight = undefined;
+        if (outcome === "dropped") {
+          this.nextAttemptAt = Date.now() + MALFORMED_REPAIR_DROP_BACKOFF_MS;
+        }
+      }
+    });
+    return this.inFlight;
+  }
+}
+
+/**
+ * Quarantine sidecar path for the rows a repair drops (#3298 review): named by a
+ * hash of the dropped lines, so repeated attempts over the same bad rows reuse
+ * one file instead of piling one sidecar per failed attempt.
+ */
+export function malformedSidecarPath(catalogPath: string, dropped: string[]): string {
+  return `${catalogPath}.malformed-${contentHash(dropped.join("\n"))}`;
+}
+
+// sha256 of the dropped lines, truncated for a filename; stable across processes.
+function contentHash(input: string): string {
+  return createHash("sha256").update(input, "utf8").digest("hex").slice(0, 16);
+}