@remnic/core 9.69.33 → 9.69.35

package/src/access-offline-manifest.ts

@@ -1,16 +1,22 @@
 import * as nodePath from "node:path";
-import type { Orchestrator } from "./orchestrator.js";
-import { iterateOfflineSyncSnapshotFileRecords } from "./offline-sync.js";
 import { offlineSyncStorageForSnapshot } from "./offline-sync-impression-drain.js";
+import { iterateOfflineSyncSnapshotFileRecords } from "./offline-sync.js";
+import type { Orchestrator } from "./orchestrator.js";
 import {
-  buildReconcileManifestFile,
+  CONTENT_HASH_NORMALIZER_VERSION,
+  IDENTITY_RESOLUTION_VERSION,
   RECONCILE_MANIFEST_FORMAT,
   RECONCILE_MANIFEST_SCHEMA_VERSION,
   type ReconcileManifest,
   type ReconcileManifestFile,
+  type ReconcileMemoryIdentity,
   type ReconcileMemoryParser,
+  buildReconcileManifestFile,
+  citationTemplateFingerprint,
+  isCachedIdentityReusable,
+  isReconcileMemoryIdentity,
 } from "./reconcile/manifest.js";
-import { isSupportPassportPrivateMemory } from "./support-passport/card-projection.js";
+import { createPersistedSupportPassportPrivateFileExclusion } from "./support-passport/card-projection.js";
 
 export interface OfflineSyncManifestRequest {
   includeTranscripts?: boolean;
@@ -22,14 +28,179 @@ export interface OfflineSyncManifestStreamResponse extends Omit<ReconcileManifes
   files: AsyncIterable<ReconcileManifestFile>;
 }
 
+export interface ServerIdentityCacheEntry {
+  path: string;
+  sha256: string;
+  memory?: ReconcileMemoryIdentity;
+  /** Stamped on sha-only entries so an upgrade re-parses them. */
+  normalizerVersion?: number;
+  identityResolutionVersion?: number;
+  /** Stat identity the exclusion classification was computed against. */
+  statIdentity?: string;
+  /** Persisted support-passport private-memory classification for statIdentity. */
+  excluded?: boolean;
+}
+
+/**
+ * Decide what the manifest stream should persist, and whether a write is
+ * needed at all.
+ *
+ * A write is required whenever the persisted set changed — an identity was
+ * rebuilt, or an entry was dropped because its file lost its identity — and
+ * also when a completed walk leaves entries for paths it never saw, which are
+ * files that have since been deleted. Skipping the write in that last case
+ * would strand those entries on disk forever.
+ *
+ * Pruning is gated on the walk completing: an aborted or partially consumed
+ * stream has simply not observed the remaining paths, so it may only add.
+ */
+export function planServerIdentityCacheWrite(input: {
+  persisted: ReadonlyMap<string, ServerIdentityCacheEntry>;
+  yieldedPaths: ReadonlySet<string>;
+  streamCompleted: boolean;
+  cacheDirty: boolean;
+}): { shouldWrite: boolean; entries: ServerIdentityCacheEntry[] } {
+  const entries = input.streamCompleted
+    ? [...input.persisted.values()].filter((entry) => input.yieldedPaths.has(entry.path))
+    : [...input.persisted.values()];
+  return { shouldWrite: input.cacheDirty || entries.length !== input.persisted.size, entries };
+}
+
+/**
+ * The cache lives under `.remnic/` rather than `state/`: snapshot enumeration
+ * excludes internal `.remnic/` paths structurally (`isInternalRemnicStatePath`),
+ * whereas `state/` is only filtered by an allowlist of known node-local
+ * artifacts. Under `state/` this node-local cache would be advertised as a peer
+ * file, so convergence would transfer the cache itself — and the stream rewrites
+ * it during finalization, so the advertised digest could go stale mid-transfer.
+ */
+function serverIdentityCachePath(storageDir: string): string {
+  return nodePath.join(storageDir, ".remnic", "state", "converge-identity-cache.json");
+}
+
+async function loadServerIdentityCache(
+  storageDir: string,
+  citationTemplate?: string
+): Promise<Map<string, ServerIdentityCacheEntry>> {
+  const cache = new Map<string, ServerIdentityCacheEntry>();
+  try {
+    const raw = JSON.parse(
+      await import("node:fs/promises").then((fs) => fs.readFile(serverIdentityCachePath(storageDir), "utf8"))
+    ) as {
+      citationTemplate?: string;
+      files?: unknown[];
+    };
+    // Identities are derived after stripping inline attribution for a specific
+    // citation template; entries written under a different one would produce
+    // wrong contentHash values for unchanged files.
+    if (raw.citationTemplate !== citationTemplateFingerprint(citationTemplate)) return cache;
+    for (const candidate of raw.files ?? []) {
+      const entry = candidate as Partial<ServerIdentityCacheEntry> | null;
+      if (typeof entry?.path !== "string" || typeof entry.sha256 !== "string") continue;
+      if (entry.memory !== undefined && !isReconcileMemoryIdentity(entry.memory)) continue;
+      if (entry.statIdentity !== undefined && typeof entry.statIdentity !== "string") continue;
+      if (entry.excluded !== undefined && typeof entry.excluded !== "boolean") continue;
+      if (entry.normalizerVersion !== undefined && typeof entry.normalizerVersion !== "number") continue;
+      if (entry.identityResolutionVersion !== undefined && typeof entry.identityResolutionVersion !== "number") {
+        continue;
+      }
+      cache.set(entry.path, {
+        path: entry.path,
+        sha256: entry.sha256,
+        ...(entry.memory ? { memory: entry.memory } : {}),
+        ...(entry.memory
+          ? {}
+          : {
+              ...(typeof entry.normalizerVersion === "number" ? { normalizerVersion: entry.normalizerVersion } : {}),
+              ...(typeof entry.identityResolutionVersion === "number"
+                ? { identityResolutionVersion: entry.identityResolutionVersion }
+                : {}),
+            }),
+        ...(entry.statIdentity !== undefined && entry.excluded !== undefined
+          ? { statIdentity: entry.statIdentity, excluded: entry.excluded }
+          : {}),
+      });
+    }
+  } catch {
+    // missing or corrupt cache: cold build
+  }
+  return cache;
+}
+
+const serverIdentityCacheWriteLocks = new Map<string, Promise<void>>();
+
+/** Serialize cache replacements per path: overlapping manifest streams for one
+ * namespace would otherwise each publish a whole-file snapshot, and the slower
+ * stream built from older filesystem state would overwrite the newer one. */
+async function withServerIdentityCacheWriteLock(cachePath: string, write: () => Promise<void>): Promise<void> {
+  const previous = serverIdentityCacheWriteLocks.get(cachePath) ?? Promise.resolve();
+  const next = previous.then(write, write);
+  serverIdentityCacheWriteLocks.set(cachePath, next);
+  try {
+    await next;
+  } finally {
+    if (serverIdentityCacheWriteLocks.get(cachePath) === next) {
+      serverIdentityCacheWriteLocks.delete(cachePath);
+    }
+  }
+}
+
+/** Union of the entries being written and the current on-disk set; on conflict
+ * the write wins (it reflects the newer run). Callers hold the write lock. */
+async function mergeServerIdentityCacheEntries(
+  fs: typeof import("node:fs/promises"),
+  cachePath: string,
+  entries: readonly ServerIdentityCacheEntry[],
+  citationTemplate: string | undefined,
+  dropped: ReadonlySet<string> = new Set()
+): Promise<ServerIdentityCacheEntry[]> {
+  const merged = new Map(entries.map((entry) => [entry.path, entry]));
+  try {
+    const raw = JSON.parse(await fs.readFile(cachePath, "utf8")) as {
+      citationTemplate?: string;
+      files?: unknown[];
+    };
+    if (raw.citationTemplate === citationTemplateFingerprint(citationTemplate)) {
+      for (const candidate of raw.files ?? []) {
+        const entry = candidate as Partial<ServerIdentityCacheEntry> | null;
+        if (typeof entry?.path !== "string" || typeof entry.sha256 !== "string") continue;
+        if (entry.memory !== undefined && !isReconcileMemoryIdentity(entry.memory)) continue;
+        if (dropped.has(entry.path) || merged.has(entry.path)) continue;
+        merged.set(entry.path, {
+          path: entry.path,
+          sha256: entry.sha256,
+          ...(entry.memory ? { memory: entry.memory } : {}),
+          ...(entry.memory
+            ? {}
+            : {
+                ...(typeof entry.normalizerVersion === "number" ? { normalizerVersion: entry.normalizerVersion } : {}),
+                ...(typeof entry.identityResolutionVersion === "number"
+                  ? { identityResolutionVersion: entry.identityResolutionVersion }
+                  : {}),
+              }),
+        });
+      }
+    }
+  } catch {
+    // missing or unreadable current cache: the write set stands alone
+  }
+  return [...merged.values()];
+}
+
 export async function createOfflineSyncManifestStream(
   orchestrator: Orchestrator,
   namespace: string,
   userExcludeRegexps: RegExp[],
   options: OfflineSyncManifestRequest,
-  parseMemory: ReconcileMemoryParser,
+  parseMemory: ReconcileMemoryParser
 ): Promise<OfflineSyncManifestStreamResponse> {
   const storage = await offlineSyncStorageForSnapshot(orchestrator, namespace);
+  const citationTemplate = orchestrator.config.inlineSourceAttributionFormat;
+  const identityCache = await loadServerIdentityCache(storage.dir, citationTemplate);
+  // The exclusion callback runs before every yield; without the persisted
+  // classification it would read and parse every candidate file, defeating the
+  // warm-cache skip entirely.
+  const classificationUpdates = new Map<string, { statIdentity: string; excluded: boolean }>();
   const snapshotFiles = iterateOfflineSyncSnapshotFileRecords({
     root: storage.dir,
     includeContent: false,
@@ -37,23 +208,133 @@ export async function createOfflineSyncManifestStream(
     readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
     signal: options.signal,
     userExcludeRegexps,
-    excludeFile: async ({ filePath }) => {
-      const memory = await storage.readMemoryByPath(filePath);
-      return memory ? isSupportPassportPrivateMemory(memory) : false;
-    },
+    excludeFile: createPersistedSupportPassportPrivateFileExclusion(storage, identityCache, classificationUpdates),
   });
   return {
     namespace,
     format: RECONCILE_MANIFEST_FORMAT,
     schemaVersion: RECONCILE_MANIFEST_SCHEMA_VERSION,
     files: (async function* () {
-      for await (const file of snapshotFiles) {
-        yield await buildReconcileManifestFile(
-          file,
-          async ({ path }) => storage.readOfflineSyncFile(nodePath.join(storage.dir, path)),
-          parseMemory,
-          orchestrator.config.inlineSourceAttributionFormat,
-        );
+      // Any change to the persisted set, not just a rebuilt identity: a file
+      // that lost its identity, or a completed walk that must prune vanished
+      // paths, also has to reach disk or the removal is lost forever.
+      let cacheDirty = false;
+      let streamCompleted = false;
+      // Seeded with every previously cached entry so a partially consumed
+      // stream (client disconnect, abort) can only add to the cache. Writing
+      // just this run's rebuilds would drop every cache hit, so one edit to a
+      // large corpus would shrink the cache to that single entry and force a
+      // near-cold rebuild on the next request.
+      const persistedEntries = new Map(identityCache);
+      const yieldedPaths = new Set<string>();
+      const flush = async (): Promise<void> => {
+        const { shouldWrite, entries } = planServerIdentityCacheWrite({
+          persisted: persistedEntries,
+          yieldedPaths,
+          streamCompleted,
+          cacheDirty,
+        });
+        if (!shouldWrite) return;
+        try {
+          const fs = await import("node:fs/promises");
+          const cachePath = serverIdentityCachePath(storage.dir);
+          await withServerIdentityCacheWriteLock(cachePath, async () => {
+            // Merge with whatever is on disk NOW: a concurrent stream for the
+            // same namespace may have published newer entries after this
+            // request loaded its snapshot, and a blind whole-file replace
+            // would discard them.
+            const written = new Set(entries.map((entry) => entry.path));
+            const dropped = streamCompleted
+              ? new Set([...identityCache.keys()].filter((pathName) => !written.has(pathName)))
+              : new Set<string>();
+            const merged = await mergeServerIdentityCacheEntries(
+              fs,
+              cachePath,
+              entries,
+              citationTemplate,
+              dropped
+            );
+            await fs.mkdir(nodePath.dirname(cachePath), { recursive: true });
+            const tmp = `${cachePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+            await fs.writeFile(
+              tmp,
+              JSON.stringify({ citationTemplate: citationTemplateFingerprint(citationTemplate), files: merged })
+            );
+            await fs.rename(tmp, cachePath);
+          });
+        } catch {
+          // cache persistence is best-effort
+        }
+      };
+      try {
+        const applyClassification = (path: string, sha256: string): void => {
+          const classification = classificationUpdates.get(path);
+          if (classification === undefined) return;
+          const entry = persistedEntries.get(path) ?? { path, sha256 };
+          if (entry.statIdentity === classification.statIdentity && entry.excluded === classification.excluded) {
+            return;
+          }
+          persistedEntries.set(path, {
+            ...entry,
+            ...(entry.memory ? { memory: entry.memory } : {}),
+            statIdentity: classification.statIdentity,
+            excluded: classification.excluded,
+          });
+          cacheDirty = true;
+        };
+        for await (const file of snapshotFiles) {
+          yieldedPaths.add(file.path);
+          const cached = identityCache.get(file.path);
+          if (
+            cached !== undefined &&
+            cached.sha256.toLowerCase() === file.sha256.toLowerCase() &&
+            isCachedIdentityReusable(cached)
+          ) {
+            applyClassification(file.path, file.sha256);
+            yield {
+              ...file,
+              ...(cached.memory
+                ? { memory: cached.memory }
+                : {
+                    normalizerVersion: cached.normalizerVersion,
+                    identityResolutionVersion: cached.identityResolutionVersion,
+                  }),
+            };
+            continue;
+          }
+          const built = await buildReconcileManifestFile(
+            file,
+            async ({ path }) => storage.readOfflineSyncFile(nodePath.join(storage.dir, path)),
+            parseMemory,
+            citationTemplate
+          );
+          // Negative results persist too: a memory-shaped file that parses
+          // without an identity would otherwise be re-read on every warm run.
+          const previous = persistedEntries.get(built.path);
+          if (previous?.sha256 !== built.sha256 || (built.memory !== undefined && previous?.memory !== built.memory)) {
+            cacheDirty = true;
+          }
+          if (built.memory === undefined && built.normalizerVersion === undefined) {
+            // Read failed: do not persist a negative identity for this SHA.
+            yield built;
+            continue;
+          }
+          persistedEntries.set(built.path, {
+            path: built.path,
+            sha256: built.sha256,
+            ...(built.memory !== undefined
+              ? { memory: built.memory }
+              : {
+                  normalizerVersion: built.normalizerVersion,
+                  identityResolutionVersion: built.identityResolutionVersion,
+                }),
+          });
+          applyClassification(built.path, built.sha256);
+          yield built;
+        }
+        streamCompleted = true;
+      } finally {
+        await flush();
       }
     })(),
   };

package/src/access-recall-surface.ts

@@ -833,11 +833,10 @@ export class AccessRecallSurface {
       this.deps.budget.gc();
     }
     const topK = Number.isFinite(request.topK) ? Math.max(0, Math.floor(request.topK ?? 0)) : undefined;
-    // Issue #680 — historical recall pin.  Validate at the input
-    // boundary so a malformed `asOf` is rejected with a structured
-    // 400 instead of silently flooring at NaN inside the orchestrator
-    // (CLAUDE.md rule 51, gotcha #51).  Empty / undefined is fine —
-    // means "no pin".
+    // Issue #680 — historical recall pin.  Validate at the input boundary so
+    // a malformed `asOf` is rejected with a structured 400 instead of
+    // silently flooring at NaN inside the orchestrator (rule 51, gotcha #51).
+    // Empty / undefined is fine — means "no pin".
     let asOf: string | undefined;
     if (request.asOf !== undefined && request.asOf !== null) {
       if (typeof request.asOf !== "string" || request.asOf.trim().length === 0) {
@@ -863,6 +862,7 @@ export class AccessRecallSurface {
       },
       ...(authenticatedPrincipal ? { principalOverride: authenticatedPrincipal } : {}),
       ...(request.sourceConnector ? { sourceConnector: request.sourceConnector } : {}),
+      ...(request.stateView !== undefined ? { stateView: request.stateView } : {}),
       ...(asOf !== undefined ? { asOf } : {}),
       ...(request.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
       ...(request.abortSignal ? { abortSignal: request.abortSignal } : {}),

package/src/access-schema.ts

@@ -3,6 +3,8 @@
 // field-level detail so consumers get clear feedback on malformed requests.
 
 import { z } from "zod";
+import { isMemoryCategory, MEMORY_CATEGORY_NAMES } from "./write-envelope.js";
+import type { MemoryCategory } from "./types.js";
 import {
   ACTION_CONFIDENCE_CONTEXT_READINESS,
   ACTION_CONFIDENCE_RISK_CATEGORIES,
@@ -145,6 +147,13 @@ export const recallRequestSchema = z.object({
    * recall traversal (issue #681). Defaults to false.
    */
   includeLowConfidence: z.boolean().optional(),
+  /**
+   * #1952 — per-call opt-in to state-aware recall views for this recall.
+   * ORs with the `recallStateViews` config flag; a change-intent query
+   * (e.g. "when did", "used to", "switched") is still required for any
+   * effect, so this can never perturb ordinary recalls.
+   */
+  stateView: z.boolean().optional(),
 });
 
 export const recallExplainRequestSchema = z.object({
@@ -258,13 +267,73 @@ export const deepRecallRequestSchema = z.object({
 // ---------------------------------------------------------------------------
 
 const writeContentSchema = z.string().min(1, "content is required").max(50000);
-const categorySchema = z
-  .enum([
-    "fact", "preference", "correction", "entity", "decision",
-    "relationship", "principle", "commitment", "moment", "skill", "rule", "procedure",
-    "reasoning_trace",
-  ])
-  .optional();
+/**
+ * #2780: the canonical category set stays authoritative (`isMemoryCategory`),
+ * with exactly four admitted input-compat aliases — the project-shaped
+ * spellings fleet telemetry actually shows (`project`, `project_state`,
+ * `project-state`, `project_update`) — for a project-shaped category that
+ * does not exist. Exact match only, no case folding: `Project_State` and
+ * near-misses like `projection` reject like any other invalid category.
+ * Aliases are NOT enum members: the write-surface funnel coerces them to
+ * "fact" and reports the coercion on the response. Everything else rejects
+ * naming the full valid set plus a "use fact" hint so callers learn the
+ * canonical name.
+ */
+const PROJECT_CATEGORY_ALIASES: Record<string, true> = {
+  project: true,
+  project_state: true,
+  "project-state": true,
+  project_update: true,
+};
+
+export interface CategoryAliasCoercion {
+  from: string;
+  to: "fact";
+}
+
+export function coerceProjectCategoryAlias<T extends { category?: string }>(
+  request: T,
+): { request: T; categoryCoercion?: CategoryAliasCoercion } {
+  const category = request.category;
+  if (category === undefined || PROJECT_CATEGORY_ALIASES[category] !== true) {
+    return { request };
+  }
+  return { request: { ...request, category: "fact" }, categoryCoercion: { from: category, to: "fact" } };
+}
+
+/**
+ * #2780 fix B: an idempotent replay returns the FIRST request's stored
+ * response, whose coercion note names that request's spelling. Rewrite the
+ * note from the CURRENT raw request so every response identifies what its
+ * caller actually sent; the stored idempotent result is reused untouched.
+ */
+export function reapplyCategoryCoercion<T extends { categoryCoercion?: CategoryAliasCoercion }>(
+  response: T,
+  categoryCoercion: CategoryAliasCoercion | undefined,
+): T {
+  if (categoryCoercion !== undefined) {
+    return { ...response, categoryCoercion };
+  }
+  if (response.categoryCoercion === undefined) {
+    return response;
+  }
+  const { categoryCoercion: _stored, ...rest } = response;
+  return rest as T;
+}
+
+const categorySchema = (
+  z
+    .string()
+    .superRefine((value, ctx) => {
+      if (isMemoryCategory(value)) return;
+      if (PROJECT_CATEGORY_ALIASES[value] === true) return;
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `category must be one of: ${MEMORY_CATEGORY_NAMES.join(", ")}; for project state/facts use "fact"`,
+      });
+    })
+    .optional() as unknown as z.ZodType<MemoryCategory | undefined, z.ZodTypeDef, MemoryCategory | undefined>
+);
 const confidenceSchema = z.number().min(0).max(1).optional();
 const tagsSchema = z.array(z.string().max(256)).max(50).optional();
 const entityRefSchema = z.string().trim().max(512).optional();

package/src/access-service.ts

@@ -291,6 +291,7 @@ import {
 } from "./memory-worth-outcomes.js";
 import type { LcmMessagePartInput, MessagePartSourceFormat } from "./message-parts/index.js";
 import type { ObserveRequest, RecallRequest } from "./access-schema.js";
+import { coerceProjectCategoryAlias, type CategoryAliasCoercion } from "./access-schema.js";
 import { recordObjectiveStateSnapshotsFromObservedMessages } from "./objective-state-writers.js";
 import { objectiveStateStoreOverrideForNamespace } from "./objective-state.js";
 import { offlineSyncStorageForSnapshot } from "./offline-sync-impression-drain.js";
@@ -980,6 +981,8 @@ export interface EngramAccessWriteResponse {
   duplicateOf?: string;
   idempotencyKey?: string;
   idempotencyReplay?: boolean;
+  /** #2780: set when a project-shaped category alias was coerced to "fact". */
+  categoryCoercion?: CategoryAliasCoercion;
 }
 
 export interface EngramAccessObserveMessage {
@@ -2935,7 +2938,11 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     return this.accessObserveWriteSurface.memoryStore(request, hooks);
   }
 
-  async peekMemoryStoreIdempotency(request: EngramAccessMemoryStoreRequest): Promise<EngramAccessIdempotencyStatus> {
+  async peekMemoryStoreIdempotency(
+    rawRequest: EngramAccessMemoryStoreRequest
+  ): Promise<EngramAccessIdempotencyStatus> {
+    // #2780: fingerprint the COERCED category so peek never diverges from the write it predicts.
+    const { request } = coerceProjectCategoryAlias(rawRequest);
     const namespace = await this.resolveCodingScopedWriteNamespace(request);
     const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
     if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {
@@ -2970,8 +2977,10 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   }
 
   async peekSuggestionSubmitIdempotency(
-    request: EngramAccessSuggestionSubmitRequest
+    rawRequest: EngramAccessSuggestionSubmitRequest
   ): Promise<EngramAccessIdempotencyStatus> {
+    // #2780: fingerprint the COERCED category so peek never diverges from the write it predicts.
+    const { request } = coerceProjectCategoryAlias(rawRequest);
     const namespace = await this.resolveCodingScopedWriteNamespace(request);
     const schemaVersion = request.schemaVersion ?? ENGRAM_ACCESS_WRITE_SCHEMA_VERSION;
     if (schemaVersion !== ENGRAM_ACCESS_WRITE_SCHEMA_VERSION) {

package/src/activity/config.test.ts

@@ -19,7 +19,8 @@ test("parseActivityConfig defaults to an inert, search-only configuration", () =
     maxMemoriesPerDay: 0,
     timeline: {
       enabled: false,
-      journal: { enabled: false, source: "file" },
+      analysis: { enabled: false },
+      journal: { enabled: false, source: "memoryDir", extractionMode: "off" },
       qa: { enabled: false, maxRangeDays: 31 },
       vault: {
         enabled: false,
@@ -36,6 +37,7 @@ test("parseActivityConfig defaults to an inert, search-only configuration", () =
           locations: { enabled: false, target: "daily", section: "Locations" },
         },
         insertUnderHeading: "",
+        readback: { journalSection: "" },
         wikilinks: { places: false, placesFolder: "Places" },
         properties: { mode: "off", prefix: "remnic_" },
         autoPublish: true,
@@ -174,6 +176,127 @@ test("activity config rejects a null maxMemoriesPerDay instead of silently uncap
   assert.throws(() => parseActivityConfig({ maxMemoriesPerDay: null }), /maxMemoriesPerDay/);
 });
 
+test("activity timeline analysis defaults off with no provider settings stored", () => {
+  const timeline = parseActivityConfig(undefined).timeline;
+  assert.deepEqual(timeline.analysis, { enabled: false });
+  // The gate is independent of the timeline master switch and of capture.
+  assert.equal(parseActivityConfig({ timeline: { enabled: true } }).timeline.analysis.enabled, false);
+});
+
+test("activity timeline analysis parses a valid enabled block", () => {
+  const analysis = parseActivityConfig({
+    timeline: {
+      analysis: {
+        enabled: true,
+        provider: "openai",
+        model: "gpt-5.2",
+        timeoutMs: 30_000,
+        preferences: ["terse titles", "no emoji"],
+      },
+    },
+  }).timeline.analysis;
+  assert.deepEqual(analysis, {
+    enabled: true,
+    provider: "openai",
+    model: "gpt-5.2",
+    timeoutMs: 30_000,
+    preferences: ["terse titles", "no emoji"],
+  });
+});
+
+test("activity timeline analysis rejects enabling without an explicit provider and model", () => {
+  assert.throws(
+    () => parseActivityConfig({ timeline: { analysis: { enabled: true } } }),
+    /provider and model are required/,
+  );
+  assert.throws(
+    () => parseActivityConfig({ timeline: { analysis: { enabled: true, provider: "openai" } } }),
+    /provider and model are required/,
+  );
+});
+
+test("activity timeline analysis rejects prose or blank provider/model identifiers", () => {
+  for (const provider of ["Summarize this user's activity", "  ", "has space"]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { analysis: { provider, model: "m" } } }),
+      /activity\.timeline\.analysis\.provider must be an identifier/,
+    );
+  }
+  assert.throws(
+    () => parseActivityConfig({ timeline: { analysis: { provider: "openai", model: "" } } }),
+    /activity\.timeline\.analysis\.model must be an identifier/,
+  );
+});
+
+test("activity timeline analysis rejects a slash in the provider segment", () => {
+  assert.throws(
+    () =>
+      parseActivityConfig({
+        timeline: { analysis: { enabled: true, provider: "gateway/openai", model: "gpt-test" } },
+      }),
+    /provider must be a single provider segment/,
+  );
+  const ok = parseActivityConfig({
+    timeline: { analysis: { enabled: true, provider: "openai", model: "org/gpt-test" } },
+  }).timeline.analysis;
+  assert.equal(ok.model, "org/gpt-test");
+});
+
+test("activity timeline analysis rejects provider and model longer than metadata max", () => {
+  const tooLong = `m${"x".repeat(120)}`;
+  assert.throws(
+    () =>
+      parseActivityConfig({
+        timeline: { analysis: { enabled: true, provider: tooLong, model: "gpt-test" } },
+      }),
+    /provider must be at most 120 characters/,
+  );
+  assert.throws(
+    () =>
+      parseActivityConfig({
+        timeline: { analysis: { enabled: true, provider: "openai", model: tooLong } },
+      }),
+    /model must be at most 120 characters/,
+  );
+});
+
+test("activity timeline analysis rejects invalid timeout and preferences shapes", () => {
+  const base = { provider: "openai", model: "gpt-5.2" } as const;
+  for (const timeoutMs of [0, 999, 120_001, 1.5, "fast"]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { analysis: { ...base, enabled: true, timeoutMs } } }),
+      /timeoutMs/,
+    );
+  }
+  assert.throws(
+    () => parseActivityConfig({ timeline: { analysis: { ...base, preferences: "terse" } } }),
+    /preferences must be an array/,
+  );
+  assert.throws(
+    () => parseActivityConfig({ timeline: { analysis: { ...base, preferences: [""] } } }),
+    /preferences entries/,
+  );
+  assert.throws(
+    () =>
+      parseActivityConfig({
+        timeline: { analysis: { ...base, preferences: Array.from({ length: 17 }, () => "p") } },
+      }),
+    /at most 16/,
+  );
+  assert.throws(
+    () => parseActivityConfig({ timeline: { analysis: { ...base, preferences: ["x".repeat(201)] } } }),
+    /at most 200 characters/,
+  );
+});
+
+test("activity timeline analysis rejects a non-object or non-boolean block", () => {
+  assert.throws(() => parseActivityConfig({ timeline: { analysis: "on" } }), /analysis must be an object/);
+  assert.throws(
+    () => parseActivityConfig({ timeline: { analysis: { enabled: 3 } } }),
+    /analysis\.enabled must be a boolean/,
+  );
+});
+
 test("vault publish section names are rejected at config load when the publisher would reject them", () => {
   // `Timeline-->` and an embedded newline both pass a trimmed-string check
   // but break the `<!-- remnic:<name>:start -->` marker, so `publishVaultNote`