@remnic/core 9.7.11 → 9.7.12

package/dist/{types-Cmkz7csa.d.ts → types-CHSXOq7s.d.ts}

@@ -2052,6 +2052,40 @@ interface PluginConfig {
      * existing single-namespace behavior is unchanged. Default on.
      */
     namespaceCatalogEnabled: boolean;
+    /**
+     * Size (bytes) at which a namespace-catalog touch triggers an in-lock
+     * auto-compaction of `state/namespaces.jsonl` (issue #1903). The append-only
+     * log grows one line per touch; once it exceeds this many bytes the next
+     * touch folds it (last-record-wins, every namespace row preserved) and
+     * atomically rewrites it. Default `16 * 1024 * 1024` (16 MB). `0` disables
+     * auto-compaction (restores the pre-#1903 unbounded-append behavior).
+     */
+    namespacesCatalogCompactBytes: number;
+    /**
+     * Coalescing window (ms) for pure-timestamp READ touches on an
+     * already-known namespace record (issue #1903). Repeated `markRead` touches
+     * that only refresh `lastReadAt` are buffered per (namespace, kind) and
+     * flushed once per window instead of appending a line each time.
+     * Semantically-observable touches (first sight, provenance/field changes)
+     * always flush immediately. Default `60000`. `0` disables read coalescing
+     * (each touch appends immediately, the pre-#1903 behavior).
+     */
+    namespacesCatalogReadTouchCoalesceMs: number;
+    /**
+     * Coalescing window (ms) for pure-timestamp WRITE touches on an
+     * already-known namespace record (issue #1903). Mirrors
+     * `namespacesCatalogReadTouchCoalesceMs` for `markWrite`/`lastWriteAt`.
+     * Default `1000`. `0` disables write coalescing.
+     */
+    namespacesCatalogWriteTouchCoalesceMs: number;
+    /**
+     * Whether pure state-file writes (`state/buffer.json`, ledgers, indexes)
+     * touch the namespace catalog (issue #1903). State files are not namespace
+     * memory data, so by default their writes do NOT record a catalog touch.
+     * Set `true` to restore the pre-#1903 behavior where every secure-file
+     * write touched the catalog. Default `false`.
+     */
+    namespacesCatalogTouchStateWrites: boolean;
     defaultNamespace: string;
     sharedNamespace: string;
     principalFromSessionKeyMode: PrincipalFromSessionKeyMode;

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-export { aD as AccessTrackingEntry, A as ActiveRecallChatType, f as ActiveRecallModelFallbackPolicy, d as ActiveRecallPromptStyle, c as ActiveRecallQueryMode, e as ActiveRecallThinking, a3 as AgentAccessAuthToken, bp as AgentAccessHttpConfig, bq as AgentDefaultsConfig, br as AgentPersona, r as AgentPersonaModelConfig, bs as BehaviorLoopAdjustment, g as BehaviorLoopPolicyState, bt as BehaviorSignalDirection, B as BehaviorSignalEvent, bu as BehaviorSignalType, aW as BootstrapOptions, aX as BootstrapResult, l as BriefingActiveThread, bv as BriefingCalendarSourceError, b2 as BriefingConfig, j as BriefingFocus, i as BriefingFollowup, b3 as BriefingOpenCommitment, n as BriefingRecentEntity, m as BriefingResult, h as BriefingSections, b4 as BriefingWindow, bw as BufferEntryState, ay as BufferState, Z as BufferSurpriseEvent, o as BufferTurn, k as CalendarEvent, C as CalendarSource, bx as CaptureMode, by as ChatConfig, q as Checkpoint, bz as CodexCliReasoningEffort, bA as CodexCompactionFlushMode, b7 as CodexCompatConfig, bB as CodexConnectorConfig, aG as CodingContext, bC as CodingGraphLspConfig, a_ as CodingKnowledgeConfig, aZ as CodingModeConfig, bD as CompressionGuidelineActivationState, a5 as CompressionGuidelineOptimizerActionSummary, a4 as CompressionGuidelineOptimizerEventCounts, a6 as CompressionGuidelineOptimizerRuleUpdate, bE as CompressionGuidelineOptimizerSourceWindow, a9 as CompressionGuidelineOptimizerState, bF as ConfidenceTier, bG as ConsolidationAction, bH as ConsolidationItem, aY as ConsolidationObservation, z as ConsolidationResult, ah as ContinuityImprovementLoop, af as ContinuityIncidentCloseInput, ag as ContinuityIncidentOpenInput, ae as ContinuityIncidentRecord, bI as ContinuityIncidentState, bJ as ContinuityLoopCadence, ai as ContinuityLoopReviewInput, bK as ContinuityLoopStatus, aj as ContinuityLoopUpsertInput, bL as ContradictionScanConfig, U as ConversationThread, bM as CronConversationRecallMode, bN as CronRecallMode, b8 as DEFAULT_RECALL_DISCLOSURE, J as DaySummaryResult, bO as DreamingConfig, bP as DreamingNarrativePromptStyle, bQ as DreamsDeepSleepConfig, bR as DreamsLightSleepConfig, D as DreamsPhase, bS as DreamsPhaseStatus, bT as DreamsPhasesConfig, bU as DreamsRemConfig, a as DreamsRunResult, aH as DreamsStatusResult, bV as EngramTraceEvent, aC as EntityActivityEntry, E as EntityFile, aa as EntityMention, aB as EntityRelationship, ab as EntitySchemaDefinition, ac as EntitySchemaSectionDefinition, ad as EntityStructuredSection, aF as EntityTimelineEntry, b9 as ExtractedFact, bW as ExtractedProcedureStep, bX as ExtractedQuestion, bY as ExtractedReasoningTrace, bZ as ExtractedReasoningTraceStep, b_ as ExtractedRelationship, K as ExtractionFailureClass, b$ as ExtractionPassSource, y as ExtractionResult, F as FaithfulnessFrontmatter, aA as FileHygieneConfig, G as GatewayConfig, c0 as GitHubLiveConnectorConfig, c1 as GmailLiveConnectorConfig, c2 as GoogleDriveLiveConnectorConfig, c3 as HeartbeatConfig, c4 as HeartbeatDetectionMode, H as HourlySummary, I as IdentityInjectionMode, Y as ImportanceLevel, ak as ImportanceScore, V as LifecycleState, L as LiveConnectorsConfig, c5 as LlmTraceCallback, c6 as LlmTraceEvent, am as MemoryActionEligibilityContext, bc as MemoryActionEligibilitySource, a8 as MemoryActionEvent, c7 as MemoryActionOutcome, c8 as MemoryActionPolicyDecision, an as MemoryActionPolicyResult, c9 as MemoryActionStatus, a7 as MemoryActionType, u as MemoryCategory, M as MemoryFile, p as MemoryFrontmatter, al as MemoryIntent, x as MemoryLifecycleEvent, ao as MemoryLifecycleEventType, ap as MemoryLifecycleStateSummary, ax as MemoryLink, ca as MemoryLinkType, bd as MemoryObservation, cb as MemoryOsPresetName, w as MemoryProjectionCurrentState, be as MemoryScope, v as MemoryStatus, aE as MemorySummary, az as MetaState, cc as ModelApi, cd as ModelDefinitionConfig, ce as ModelProviderAuthMode, aq as ModelProviderConfig, cf as NamespacePolicy, ar as NativeKnowledgeConfig, cg as NativeKnowledgeFolderRuleConfig, ch as NativeKnowledgeObsidianVaultConfig, ci as NativeKnowledgeOpenClawWorkspaceConfig, cj as NotionLiveConnectorConfig, P as PluginConfig, X as PolicyClass, ck as PrincipalFromSessionKeyMode, cl as PrincipalRule, cm as ProceduralConfig, as as ProvenanceConfig, N as ProvenanceSource, aw as QmdSearchExplain, Q as QmdSearchResult, cn as QuestionEntry, bf as RECALL_DISCLOSURE_LEVELS, co as ReasoningEffort, R as RecallDisclosure, cp as RecallPipelineConfig, b as RecallPlanMode, aV as RecallSectionConfig, s as RecallTierExplain, cq as RecallTraceEvent, cr as RelevanceFeedback, at as RetrievalTier, cs as SPECULATIVE_TTL_DAYS, ct as ScopeProfileAutoPromoteConfig, aI as ScopeProfileConfig, aJ as ScopeProfileLayerId, aK as ScopeProfilePromotionTarget, cu as ScopeProfileTeamProjectConfig, cv as ScopeTeamConfig, cw as ScoredEntity, a2 as SecretRef, cx as SemanticChunkingConfigShape, S as SessionObserverBandConfig, cy as SignalLevel, au as SignalScanResult, cz as SlotBehaviorConfig, cA as SlotMismatchMode, t as SourceConnectorProvenance, av as TopicScore, T as TranscriptEntry, cB as TriggerMode, O as TrustWeights, W as VerificationState, cC as confidenceTier, bm as isRecallDisclosure } from './types-Cmkz7csa.js';
+export { aD as AccessTrackingEntry, A as ActiveRecallChatType, f as ActiveRecallModelFallbackPolicy, d as ActiveRecallPromptStyle, c as ActiveRecallQueryMode, e as ActiveRecallThinking, a3 as AgentAccessAuthToken, bp as AgentAccessHttpConfig, bq as AgentDefaultsConfig, br as AgentPersona, r as AgentPersonaModelConfig, bs as BehaviorLoopAdjustment, g as BehaviorLoopPolicyState, bt as BehaviorSignalDirection, B as BehaviorSignalEvent, bu as BehaviorSignalType, aW as BootstrapOptions, aX as BootstrapResult, l as BriefingActiveThread, bv as BriefingCalendarSourceError, b2 as BriefingConfig, j as BriefingFocus, i as BriefingFollowup, b3 as BriefingOpenCommitment, n as BriefingRecentEntity, m as BriefingResult, h as BriefingSections, b4 as BriefingWindow, bw as BufferEntryState, ay as BufferState, Z as BufferSurpriseEvent, o as BufferTurn, k as CalendarEvent, C as CalendarSource, bx as CaptureMode, by as ChatConfig, q as Checkpoint, bz as CodexCliReasoningEffort, bA as CodexCompactionFlushMode, b7 as CodexCompatConfig, bB as CodexConnectorConfig, aG as CodingContext, bC as CodingGraphLspConfig, a_ as CodingKnowledgeConfig, aZ as CodingModeConfig, bD as CompressionGuidelineActivationState, a5 as CompressionGuidelineOptimizerActionSummary, a4 as CompressionGuidelineOptimizerEventCounts, a6 as CompressionGuidelineOptimizerRuleUpdate, bE as CompressionGuidelineOptimizerSourceWindow, a9 as CompressionGuidelineOptimizerState, bF as ConfidenceTier, bG as ConsolidationAction, bH as ConsolidationItem, aY as ConsolidationObservation, z as ConsolidationResult, ah as ContinuityImprovementLoop, af as ContinuityIncidentCloseInput, ag as ContinuityIncidentOpenInput, ae as ContinuityIncidentRecord, bI as ContinuityIncidentState, bJ as ContinuityLoopCadence, ai as ContinuityLoopReviewInput, bK as ContinuityLoopStatus, aj as ContinuityLoopUpsertInput, bL as ContradictionScanConfig, U as ConversationThread, bM as CronConversationRecallMode, bN as CronRecallMode, b8 as DEFAULT_RECALL_DISCLOSURE, J as DaySummaryResult, bO as DreamingConfig, bP as DreamingNarrativePromptStyle, bQ as DreamsDeepSleepConfig, bR as DreamsLightSleepConfig, D as DreamsPhase, bS as DreamsPhaseStatus, bT as DreamsPhasesConfig, bU as DreamsRemConfig, a as DreamsRunResult, aH as DreamsStatusResult, bV as EngramTraceEvent, aC as EntityActivityEntry, E as EntityFile, aa as EntityMention, aB as EntityRelationship, ab as EntitySchemaDefinition, ac as EntitySchemaSectionDefinition, ad as EntityStructuredSection, aF as EntityTimelineEntry, b9 as ExtractedFact, bW as ExtractedProcedureStep, bX as ExtractedQuestion, bY as ExtractedReasoningTrace, bZ as ExtractedReasoningTraceStep, b_ as ExtractedRelationship, K as ExtractionFailureClass, b$ as ExtractionPassSource, y as ExtractionResult, F as FaithfulnessFrontmatter, aA as FileHygieneConfig, G as GatewayConfig, c0 as GitHubLiveConnectorConfig, c1 as GmailLiveConnectorConfig, c2 as GoogleDriveLiveConnectorConfig, c3 as HeartbeatConfig, c4 as HeartbeatDetectionMode, H as HourlySummary, I as IdentityInjectionMode, Y as ImportanceLevel, ak as ImportanceScore, V as LifecycleState, L as LiveConnectorsConfig, c5 as LlmTraceCallback, c6 as LlmTraceEvent, am as MemoryActionEligibilityContext, bc as MemoryActionEligibilitySource, a8 as MemoryActionEvent, c7 as MemoryActionOutcome, c8 as MemoryActionPolicyDecision, an as MemoryActionPolicyResult, c9 as MemoryActionStatus, a7 as MemoryActionType, u as MemoryCategory, M as MemoryFile, p as MemoryFrontmatter, al as MemoryIntent, x as MemoryLifecycleEvent, ao as MemoryLifecycleEventType, ap as MemoryLifecycleStateSummary, ax as MemoryLink, ca as MemoryLinkType, bd as MemoryObservation, cb as MemoryOsPresetName, w as MemoryProjectionCurrentState, be as MemoryScope, v as MemoryStatus, aE as MemorySummary, az as MetaState, cc as ModelApi, cd as ModelDefinitionConfig, ce as ModelProviderAuthMode, aq as ModelProviderConfig, cf as NamespacePolicy, ar as NativeKnowledgeConfig, cg as NativeKnowledgeFolderRuleConfig, ch as NativeKnowledgeObsidianVaultConfig, ci as NativeKnowledgeOpenClawWorkspaceConfig, cj as NotionLiveConnectorConfig, P as PluginConfig, X as PolicyClass, ck as PrincipalFromSessionKeyMode, cl as PrincipalRule, cm as ProceduralConfig, as as ProvenanceConfig, N as ProvenanceSource, aw as QmdSearchExplain, Q as QmdSearchResult, cn as QuestionEntry, bf as RECALL_DISCLOSURE_LEVELS, co as ReasoningEffort, R as RecallDisclosure, cp as RecallPipelineConfig, b as RecallPlanMode, aV as RecallSectionConfig, s as RecallTierExplain, cq as RecallTraceEvent, cr as RelevanceFeedback, at as RetrievalTier, cs as SPECULATIVE_TTL_DAYS, ct as ScopeProfileAutoPromoteConfig, aI as ScopeProfileConfig, aJ as ScopeProfileLayerId, aK as ScopeProfilePromotionTarget, cu as ScopeProfileTeamProjectConfig, cv as ScopeTeamConfig, cw as ScoredEntity, a2 as SecretRef, cx as SemanticChunkingConfigShape, S as SessionObserverBandConfig, cy as SignalLevel, au as SignalScanResult, cz as SlotBehaviorConfig, cA as SlotMismatchMode, t as SourceConnectorProvenance, av as TopicScore, T as TranscriptEntry, cB as TriggerMode, O as TrustWeights, W as VerificationState, cC as confidenceTier, bm as isRecallDisclosure } from './types-CHSXOq7s.js';
 import './message-parts/index.js';

package/dist/types.js

@@ -4,7 +4,7 @@ import {
   SPECULATIVE_TTL_DAYS,
   confidenceTier,
   isRecallDisclosure
-} from "./chunk-3ZVFLMFQ.js";
+} from "./chunk-G5PVJJRA.js";
 import "./chunk-PZ5AY32C.js";
 export {
   DEFAULT_RECALL_DISCLOSURE,

package/dist/utility-runtime.d.ts

@@ -1,5 +1,5 @@
 import { TierRoutingPolicy } from './tier-routing.js';
-import './types-Cmkz7csa.js';
+import './types-CHSXOq7s.js';
 import './message-parts/index.js';
 import './lifecycle.js';
 

package/dist/verified-recall.js

@@ -1,10 +1,10 @@
 import {
   compareVerifiedEpisodeResults,
   searchVerifiedEpisodes
-} from "./chunk-YLTG6BO4.js";
+} from "./chunk-OIFZII6J.js";
 import "./chunk-2A3OXAP2.js";
 import "./chunk-ZBJMUXZH.js";
-import "./chunk-KXLRMM35.js";
+import "./chunk-TRH533CA.js";
 import "./chunk-L2B3EE7B.js";
 import "./chunk-B3ABVQ36.js";
 import "./chunk-5UZXUTVO.js";
@@ -15,7 +15,7 @@ import "./chunk-6CIAGZ6X.js";
 import "./chunk-J6A3CX5N.js";
 import "./chunk-4KJLYTLS.js";
 import "./chunk-SVOZFLIQ.js";
-import "./chunk-3ZVFLMFQ.js";
+import "./chunk-G5PVJJRA.js";
 import "./chunk-RULE4VG5.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-RHOZ5LLO.js";

package/package.json

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

package/src/config.test.ts

@@ -2161,3 +2161,47 @@ test("parseConfig rejects non-positive extraction retry/breaker numerics and fal
   assert.equal(c.extractionBreakerAuthCooldownMs, 1_800_000, "non-positive auth cooldown -> default");
   assert.deepEqual(c.extractionRetryScheduleMs, [60_000, 300_000, 1_800_000, 7_200_000], "schedule with non-positive entry -> default");
 });
+
+test("parseConfig namespace-catalog touch-path knobs: defaults, 0-accepting numerics, and validation (#1903)", () => {
+  // Documented defaults when absent.
+  const d = parseConfig({});
+  assert.equal(d.namespacesCatalogCompactBytes, 16 * 1024 * 1024, "compactBytes default 16 MB");
+  assert.equal(d.namespacesCatalogReadTouchCoalesceMs, 60_000, "read coalesce default 60000ms");
+  assert.equal(d.namespacesCatalogWriteTouchCoalesceMs, 1_000, "write coalesce default 1000ms");
+  assert.equal(d.namespacesCatalogTouchStateWrites, false, "state-write touch default false");
+
+  // 0 is an accepted disable switch for every numeric (resolveNonNegativeIntegerConfig).
+  assert.equal(parseConfig({ namespacesCatalogCompactBytes: 0 }).namespacesCatalogCompactBytes, 0);
+  assert.equal(parseConfig({ namespacesCatalogReadTouchCoalesceMs: 0 }).namespacesCatalogReadTouchCoalesceMs, 0);
+  assert.equal(parseConfig({ namespacesCatalogWriteTouchCoalesceMs: 0 }).namespacesCatalogWriteTouchCoalesceMs, 0);
+
+  // Positive integers pass through; CLI/env numeric strings coerce.
+  assert.equal(parseConfig({ namespacesCatalogCompactBytes: 4096 }).namespacesCatalogCompactBytes, 4096);
+  assert.equal(parseConfig({ namespacesCatalogReadTouchCoalesceMs: "30000" }).namespacesCatalogReadTouchCoalesceMs, 30_000);
+
+  // Boolean-like coercion for the state-write toggle (gotcha #36).
+  assert.equal(parseConfig({ namespacesCatalogTouchStateWrites: true }).namespacesCatalogTouchStateWrites, true);
+  assert.equal(parseConfig({ namespacesCatalogTouchStateWrites: "true" }).namespacesCatalogTouchStateWrites, true);
+  assert.equal(parseConfig({ namespacesCatalogTouchStateWrites: "off" }).namespacesCatalogTouchStateWrites, false);
+
+  // Negative and non-integer numerics are rejected with the documented message.
+  for (const key of [
+    "namespacesCatalogCompactBytes",
+    "namespacesCatalogReadTouchCoalesceMs",
+    "namespacesCatalogWriteTouchCoalesceMs",
+  ]) {
+    for (const bad of [-1, 1.5, "1.5", "abc", Number.NaN, Infinity]) {
+      assert.throws(
+        () => parseConfig({ [key]: bad }),
+        new RegExp(`${key} must be a non-negative integer`),
+        `${key}=${JSON.stringify(bad)} should throw`,
+      );
+    }
+  }
+
+  // A present-but-malformed boolean toggle fails fast (gotcha #51).
+  assert.throws(
+    () => parseConfig({ namespacesCatalogTouchStateWrites: "maybe" }),
+    /namespacesCatalogTouchStateWrites must be a boolean-like value/,
+  );
+});

package/src/config.ts

@@ -435,6 +435,26 @@ function resolvePositiveIntegerConfig(
   return coerced;
 }
 
+function resolveNonNegativeIntegerConfig(
+  value: unknown,
+  defaultValue: number,
+  keyName: string,
+): number {
+  if (value === undefined || value === null) return defaultValue;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < 0
+  ) {
+    throw new Error(
+      `${keyName} must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
 export function isOpenaiApiKeyDisabled(value: unknown): boolean {
   return value === false || (typeof value === "string" && value.trim().toLowerCase() === "false");
 }
@@ -2934,6 +2954,29 @@ export function parseConfig(
     // silently defaulting to enabled (CLAUDE.md rule #51); default to enabled
     // only when the value is absent.
     namespaceCatalogEnabled: resolveNamespaceCatalogEnabled(cfg.namespaceCatalogEnabled, rawOperatorConfig, runtimeSet),
+    // Namespace catalog touch-path performance knobs (issue #1903). Numerics use
+    // resolveNonNegativeIntegerConfig so 0 is an accepted disable switch; a
+    // present-but-invalid value (negative/non-integer) is REJECTED (rule #51).
+    namespacesCatalogCompactBytes: resolveNonNegativeIntegerConfig(
+      cfg.namespacesCatalogCompactBytes,
+      16 * 1024 * 1024,
+      "namespacesCatalogCompactBytes",
+    ),
+    namespacesCatalogReadTouchCoalesceMs: resolveNonNegativeIntegerConfig(
+      cfg.namespacesCatalogReadTouchCoalesceMs,
+      60_000,
+      "namespacesCatalogReadTouchCoalesceMs",
+    ),
+    namespacesCatalogWriteTouchCoalesceMs: resolveNonNegativeIntegerConfig(
+      cfg.namespacesCatalogWriteTouchCoalesceMs,
+      1_000,
+      "namespacesCatalogWriteTouchCoalesceMs",
+    ),
+    namespacesCatalogTouchStateWrites: resolveBooleanConfig(
+      cfg.namespacesCatalogTouchStateWrites,
+      false,
+      "namespacesCatalogTouchStateWrites",
+    ),
     // NOTE: namespace identifiers are intentionally NOT sanitized here — the
     // codebase rejects unsafe namespaces at the point of use (see
     // codex-materialize-runner and NamespaceStorageRouter / resolveNamespaceDir),

package/src/namespaces/catalog.test.ts

@@ -3694,3 +3694,261 @@ test("router resolve-hook serializer recovers after a prior hook rejects (issue
     await rm(memoryDir, { recursive: true, force: true });
   }
 });
+
+// ── Issue #1903: touch-path performance (auto-compaction, coalescing, streaming) ──
+
+async function countCatalogLines(memoryDir: string): Promise<number> {
+  const raw = await readFile(path.join(memoryDir, "state", "namespaces.jsonl"), "utf8").catch(() => "");
+  return raw.split("\n").filter((line) => line.trim().length > 0).length;
+}
+
+// 1. Warm cache: with coalescing OFF every touch appends, but a warm cache means
+// none of them re-parses the JSONL after the initial warm-up parse.
+test("#1903 warm cache: repeated touches never re-parse the log (coalescing off)", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const catalog = new CountingNamespaceCatalog(
+      makeConfig(memoryDir, {
+        namespacesCatalogReadTouchCoalesceMs: 0,
+        namespacesCatalogWriteTouchCoalesceMs: 0,
+      }),
+    );
+    // Warm the cache: the first write creates the file; a read then performs the
+    // one-time full parse and warms the in-process cache.
+    await catalog.markWrite("alpha", { discoveredBy: "write" });
+    await catalog.listNamespaces();
+    const warm = catalog.catalogReadCount;
+    assert.ok(warm >= 1, "the warm-up performed at least one full parse");
+    for (let i = 0; i < 25; i++) {
+      await catalog.markWrite("alpha", { discoveredBy: "write" });
+      await catalog.markRead("alpha", { discoveredBy: "read" });
+    }
+    assert.equal(
+      catalog.catalogReadCount,
+      warm,
+      "every subsequent touch is served from the warm cache without a re-parse",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// 2. Write-touch coalescing collapses many in-window writes into a single append,
+// and the newest buffered timestamp wins on flush.
+test("#1903 write-touch coalescing collapses 50 in-window writes to one append", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const catalog = new NamespaceCatalog(
+      makeConfig(memoryDir, { namespacesCatalogWriteTouchCoalesceMs: 60_000 }),
+    );
+    // Seed the record, then read it back so the in-process cache is warm — the
+    // following writes are then pure-timestamp refreshes on a known record and
+    // are deferred (a cold cache would force the first one to flush immediately).
+    await catalog.markWrite("alpha", { discoveredBy: "write" });
+    await catalog.getNamespaceRecord("alpha");
+    const linesAfterSeed = await countCatalogLines(memoryDir);
+    let newest = new Date();
+    for (let i = 0; i < 50; i++) {
+      newest = new Date(Date.now() + (i + 1) * 1000);
+      await catalog.markWrite("alpha", { discoveredBy: "write", at: newest });
+    }
+    assert.equal(
+      await countCatalogLines(memoryDir),
+      linesAfterSeed,
+      "coalesced writes stay buffered — no per-touch append",
+    );
+    await catalog.flushPendingTouches();
+    assert.equal(
+      await countCatalogLines(memoryDir),
+      linesAfterSeed + 1,
+      "the 50 buffered writes collapse into exactly one append on flush",
+    );
+    const record = await catalog.getNamespaceRecord("alpha");
+    assert.equal(
+      record?.lastWriteAt,
+      newest.toISOString(),
+      "the newest in-window write timestamp wins",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// 3. Read-touch coalescing collapses in-window reads and keeps the latest freshness.
+test("#1903 read-touch coalescing keeps the latest in-window lastReadAt", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const catalog = new NamespaceCatalog(
+      makeConfig(memoryDir, { namespacesCatalogReadTouchCoalesceMs: 60_000 }),
+    );
+    // Seed the read field, then warm the cache so the following reads defer.
+    await catalog.markRead("alpha", { discoveredBy: "read" });
+    await catalog.getNamespaceRecord("alpha");
+    const linesAfterSeed = await countCatalogLines(memoryDir);
+    let newest = new Date();
+    for (let i = 0; i < 30; i++) {
+      newest = new Date(Date.now() + (i + 1) * 1000);
+      await catalog.markRead("alpha", { discoveredBy: "read", at: newest });
+    }
+    assert.equal(
+      await countCatalogLines(memoryDir),
+      linesAfterSeed,
+      "coalesced reads stay buffered — no per-touch append",
+    );
+    await catalog.flushPendingTouches();
+    assert.equal(await countCatalogLines(memoryDir), linesAfterSeed + 1);
+    const record = await catalog.getNamespaceRecord("alpha");
+    assert.equal(
+      record?.lastReadAt,
+      newest.toISOString(),
+      "the newest in-window read timestamp wins",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// 4. Provenance upgrade under coalescing: a config pre-registration followed by a
+// write must read back "write" WITHOUT an explicit flush (immediate-flush rule).
+test("#1903 markWrite upgrades config→write under coalescing without an explicit flush", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const catalog = new NamespaceCatalog(
+      makeConfig(memoryDir, {
+        namespacesCatalogReadTouchCoalesceMs: 60_000,
+        namespacesCatalogWriteTouchCoalesceMs: 60_000,
+      }),
+    );
+    const ns = "project-origin-prov";
+    const storageDir = path.join(memoryDir, "namespaces", namespaceIdentityToken(ns));
+    await catalog.registerResolved(ns, storageDir);
+    assert.equal(
+      (await catalog.getNamespaceRecord(ns))?.discoveredBy,
+      "config",
+      "pre-registration is discovered by config",
+    );
+    // A real write must upgrade the provenance immediately even with coalescing on.
+    await catalog.markWrite(ns, { discoveredBy: "write", storageDir });
+    assert.equal(
+      (await catalog.getNamespaceRecord(ns))?.discoveredBy,
+      "write",
+      "the config→write upgrade flushes immediately (not coalesced away)",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// 5. Zero-limit semantics: CompactBytes=0 never rewrites and CoalesceMs=0 appends
+// one line per touch (line count == touch count) — the pre-#1903 behavior.
+test("#1903 zero knobs restore append-per-touch with no compaction", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const catalog = new NamespaceCatalog(
+      makeConfig(memoryDir, {
+        namespacesCatalogCompactBytes: 0,
+        namespacesCatalogReadTouchCoalesceMs: 0,
+        namespacesCatalogWriteTouchCoalesceMs: 0,
+      }),
+    );
+    const touches = 12;
+    for (let i = 0; i < touches; i++) {
+      await catalog.markWrite("alpha", { discoveredBy: "write" });
+    }
+    assert.equal(
+      await countCatalogLines(memoryDir),
+      touches,
+      "no coalescing and no compaction → exactly one append per touch",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// 6. Auto-compaction bounds the log to one row per namespace and preserves every
+// namespace with its newest fields. A tiny limit forces compaction on each touch.
+test("#1903 auto-compaction bounds the log to one row per namespace and preserves all", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const catalog = new NamespaceCatalog(
+      makeConfig(memoryDir, {
+        namespacesCatalogCompactBytes: 100,
+        namespacesCatalogReadTouchCoalesceMs: 0,
+        namespacesCatalogWriteTouchCoalesceMs: 0,
+      }),
+    );
+    const namespaces = [
+      "project-origin-a",
+      "project-origin-b",
+      "project-origin-c",
+      "project-origin-d",
+      "project-origin-e",
+    ];
+    const newest = new Map<string, string>();
+    for (let round = 0; round < 20; round++) {
+      for (const ns of namespaces) {
+        const at = new Date(Date.now() + (round * namespaces.length + namespaces.indexOf(ns)) * 1000);
+        newest.set(ns, at.toISOString());
+        await catalog.markWrite(ns, { discoveredBy: "write", at });
+      }
+    }
+    assert.equal(
+      await countCatalogLines(memoryDir),
+      namespaces.length,
+      "the log is bounded to exactly one row per namespace after compaction",
+    );
+    const list = await catalog.listNamespaces();
+    for (const ns of namespaces) {
+      const record = list.find((r) => r.namespace === ns);
+      assert.ok(record, `namespace ${ns} survives compaction`);
+      assert.equal(
+        record?.lastWriteAt,
+        newest.get(ns),
+        `namespace ${ns} keeps its newest write timestamp through compaction`,
+      );
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// 7. Cross-process cache-coherence: compaction on one instance must never drop
+// another instance's rows (mirrors the rebuild-race tests). A third fresh
+// instance must read back every namespace touched by either.
+test("#1903 cross-instance compaction never drops another instance's rows", async () => {
+  const memoryDir = await mkMemoryDir();
+  try {
+    const cfg = () =>
+      makeConfig(memoryDir, {
+        namespacesCatalogCompactBytes: 100,
+        namespacesCatalogReadTouchCoalesceMs: 0,
+        namespacesCatalogWriteTouchCoalesceMs: 0,
+      });
+    // Separate instances behave like separate processes (own lock owner id).
+    const a = new NamespaceCatalog(cfg());
+    const b = new NamespaceCatalog(cfg());
+    const written = new Set<string>();
+    for (let round = 0; round < 8; round++) {
+      const nsA = `project-origin-a${round}`;
+      const nsB = `project-origin-b${round}`;
+      written.add(nsA);
+      written.add(nsB);
+      // Interleave: A appends a fresh namespace while B triggers a compaction of
+      // the shared log. The cross-process lock serializes the two.
+      await Promise.all([
+        a.markWrite(nsA, { discoveredBy: "write" }),
+        b.markWrite(nsB, { discoveredBy: "write" }),
+      ]);
+    }
+    const fresh = new NamespaceCatalog(makeConfig(memoryDir));
+    const list = await fresh.listNamespaces();
+    for (const ns of written) {
+      assert.ok(
+        list.some((r) => r.namespace === ns),
+        `namespace ${ns} must survive cross-instance interleaved compaction`,
+      );
+    }
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});