@remnic/core 9.69.33 → 9.69.34

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`

package/src/activity/config.ts

@@ -2,13 +2,18 @@ import path from "node:path";
 
 import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
 import { assertValidTimezone } from "./digest.js";
+import { applyLegacyJournalHeading } from "./journal-heading.js";
+import { checkVaultJournalPrerequisites } from "./journal-vault-prereq.js";
 import { resolveJournalSource } from "./journal-source.js";
 import { validateVaultNoteTemplate } from "./vault-path.js";
 import { validateRegionName } from "./vault-region.js";
+import { TIMELINE_ANALYSIS_DEFAULT_TIMEOUT_MS } from "./timeline/analysis.js";
+import { ANALYSIS_METADATA_MAX_FIELD_LENGTH, isAnalysisIdentifier } from "./timeline/analysis-metadata.js";
 import type {
   ActivityConfig,
   ActivityExtractionMode,
   ActivitySourceConfig,
+  ActivityTimelineAnalysisConfig,
   ActivityTimelineConfig,
   ActivityTimelineJournalConfig,
   ActivityTimelineQaConfig,
@@ -38,7 +43,8 @@ export function defaultActivityConfig(): ActivityConfig {
     maxMemoriesPerDay: 0,
     timeline: {
       enabled: false,
-      journal: { enabled: false, source: "file" },
+      analysis: parseTimelineAnalysisConfig(undefined),
+      journal: { enabled: false, source: "memoryDir", extractionMode: "off" },
       qa: { enabled: false, maxRangeDays: 31 },
       vault: parseTimelineVaultConfig(undefined),
     },
@@ -215,7 +221,8 @@ function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
   if (raw === undefined) {
     return {
       enabled: false,
-      journal: { enabled: false, source: "file" },
+      analysis: parseTimelineAnalysisConfig(undefined),
+      journal: { enabled: false, source: "memoryDir", extractionMode: "off" },
       qa: parseTimelineQaConfig(undefined),
       vault: parseTimelineVaultConfig(undefined),
     };
@@ -228,11 +235,123 @@ function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
   if (timeline.enabled !== undefined && enabledValue === undefined) {
     throw new TypeError("activity.timeline.enabled must be a boolean");
   }
+  const journal = parseTimelineJournalConfig(timeline.journal);
+  let vault = parseTimelineVaultConfig(timeline.vault);
+  const journalRaw = timeline.journal;
+  const headingRaw =
+    typeof journalRaw === "object" && journalRaw !== null && !Array.isArray(journalRaw)
+      ? (journalRaw as Record<string, unknown>).heading
+      : undefined;
+  if (headingRaw !== undefined) {
+    const aliased = applyLegacyJournalHeading({
+      journalSection: vault.readback.journalSection,
+      heading: headingRaw,
+    });
+    process.emitWarning(
+      aliased.ignoredLegacyHeading
+        ? 'activity.timeline.journal.heading is deprecated and ignored because activity.timeline.vault.readback.journalSection is set; use vault.readback.journalSection.'
+        : 'activity.timeline.journal.heading is deprecated; use activity.timeline.vault.readback.journalSection.',
+      { type: "DeprecationWarning", code: "REMNIC_DEP_JOURNAL_HEADING" },
+    );
+    if (aliased.usedLegacyHeading) {
+      vault = { ...vault, readback: { ...vault.readback, journalSection: aliased.journalSection } };
+    }
+  }
+  if (journal.source === "vault") {
+    // Parse-time prerequisite gate (issue #1987): the error names EVERY
+    // missing prerequisite, never just the first (§1/§39).
+    const prereq = checkVaultJournalPrerequisites({
+      vaultEnabled: vault.enabled,
+      dailyNotePath: vault.dailyNotePath,
+      journalSection: vault.readback.journalSection,
+    });
+    if (!prereq.ok) {
+      throw new RangeError(
+        `activity.timeline.journal.source "vault" requires ${prereq.message}`,
+      );
+    }
+  }
   return {
     enabled: enabledValue ?? false,
-    journal: parseTimelineJournalConfig(timeline.journal),
+    analysis: parseTimelineAnalysisConfig(timeline.analysis),
+    journal,
     qa: parseTimelineQaConfig(timeline.qa),
-    vault: parseTimelineVaultConfig(timeline.vault),
+    vault,
+  };
+}
+
+/**
+ * Parse the `activity.timeline.analysis.*` block (issue #2050). Independent
+ * gate, default off: disabled means zero provider calls and zero analysis
+ * artifacts. Enabling requires an explicit provider and model; every invalid
+ * value is rejected at parse time — never silently defaulted or fallen back.
+ */
+function parseTimelineAnalysisConfig(raw: unknown): ActivityTimelineAnalysisConfig {
+  if (raw === undefined) return { enabled: false };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline.analysis must be an object");
+  }
+  const analysis = raw as Record<string, unknown>;
+  const enabled = requireBool(analysis.enabled, "activity.timeline.analysis.enabled", false);
+  const provider = optionalNonEmptyString(analysis.provider, "activity.timeline.analysis.provider")?.trim();
+  const model = optionalNonEmptyString(analysis.model, "activity.timeline.analysis.model")?.trim();
+  for (const [key, value] of [
+    ["provider", provider],
+    ["model", model],
+  ] as const) {
+    if (value === undefined) continue;
+    if (key === "provider" && value.includes("/")) {
+      throw new RangeError(
+        "activity.timeline.analysis.provider must be a single provider segment (no '/')",
+      );
+    }
+    if (!isAnalysisIdentifier(value)) {
+      throw new RangeError(
+        `activity.timeline.analysis.${key} must be an identifier (letters, digits, and ._:-/ only)`,
+      );
+    }
+    if (value.length > ANALYSIS_METADATA_MAX_FIELD_LENGTH) {
+      throw new RangeError(
+        `activity.timeline.analysis.${key} must be at most ${ANALYSIS_METADATA_MAX_FIELD_LENGTH} characters`,
+      );
+    }
+  }
+  if (enabled && (provider === undefined || model === undefined)) {
+    throw new RangeError(
+      "activity.timeline.analysis.provider and model are required when analysis is enabled",
+    );
+  }
+  const timeoutMsValue = coerceNumber(analysis.timeoutMs, "activity.timeline.analysis.timeoutMs");
+  if (analysis.timeoutMs !== undefined && timeoutMsValue === undefined) {
+    throw new TypeError("activity.timeline.analysis.timeoutMs must be a finite number");
+  }
+  const timeoutMs = timeoutMsValue ?? TIMELINE_ANALYSIS_DEFAULT_TIMEOUT_MS;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 120_000) {
+    throw new RangeError("activity.timeline.analysis.timeoutMs must be an integer from 1000 to 120000");
+  }
+  if (analysis.preferences !== undefined) {
+    if (!Array.isArray(analysis.preferences)) {
+      throw new TypeError("activity.timeline.analysis.preferences must be an array of strings");
+    }
+    if (analysis.preferences.length > 16) {
+      throw new RangeError("activity.timeline.analysis.preferences supports at most 16 entries");
+    }
+    for (const entry of analysis.preferences) {
+      if (typeof entry !== "string" || entry.trim().length === 0) {
+        throw new TypeError("activity.timeline.analysis.preferences entries must be non-empty strings");
+      }
+      if (entry.length > 200) {
+        throw new RangeError("activity.timeline.analysis.preferences entries must be at most 200 characters");
+      }
+    }
+  }
+  const preferences = analysis.preferences as string[] | undefined;
+  return {
+    enabled,
+    ...(provider === undefined ? {} : { provider }),
+    ...(model === undefined ? {} : { model }),
+    ...(analysis.timeoutMs !== undefined || timeoutMsValue !== undefined ? { timeoutMs } : {}),
+    ...(preferences === undefined ? {} : { preferences }),
   };
 }
 
@@ -312,6 +431,17 @@ export function parseTimelineVaultConfig(raw: unknown): ActivityTimelineVaultCon
   const propertiesRaw = vault.properties;
   const properties: ActivityTimelineVaultConfig["properties"] =
     propertiesRaw === undefined ? { mode: "off", prefix: "remnic_" } : parseVaultProperties(propertiesRaw);
+  const readbackRaw = vault.readback;
+  if (readbackRaw !== undefined && (typeof readbackRaw !== "object" || readbackRaw === null || Array.isArray(readbackRaw))) {
+    throw new TypeError("activity.timeline.vault.readback must be an object");
+  }
+  const readbackJournalSection = optionalNonEmptyString(
+    (readbackRaw as Record<string, unknown> | undefined)?.journalSection,
+    "activity.timeline.vault.readback.journalSection",
+  );
+  const readback = {
+    journalSection: readbackJournalSection ?? "",
+  };
 
   return {
     enabled,
@@ -323,6 +453,7 @@ export function parseTimelineVaultConfig(raw: unknown): ActivityTimelineVaultCon
     sectionStrategy,
     publish,
     insertUnderHeading,
+    readback,
     wikilinks,
     properties,
     autoPublish,
@@ -348,6 +479,7 @@ function defaultVaultConfig(): ActivityTimelineVaultConfig {
     wikilinks: { places: false, placesFolder: "Places" },
     properties: { mode: "off", prefix: "remnic_" },
     autoPublish: true,
+    readback: { journalSection: "" },
   };
 }
 
@@ -470,7 +602,7 @@ function parseVaultProperties(raw: unknown): ActivityTimelineVaultConfig["proper
 }
 
 function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig {
-  if (raw === undefined) return { enabled: false, source: "file" };
+  if (raw === undefined) return { enabled: false, source: "memoryDir", extractionMode: "off" };
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new TypeError("activity.timeline.journal must be an object");
   }
@@ -479,22 +611,22 @@ function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig
   if (journal.enabled !== undefined && enabledValue === undefined) {
     throw new TypeError("activity.timeline.journal.enabled must be a boolean");
   }
-  const heading = journal.heading;
-  if (heading !== undefined && typeof heading !== "string") {
-    throw new TypeError("activity.timeline.journal.heading must be a string");
-  }
-  const source = journal.source === undefined ? "file" : typeof journal.source === "string" ? journal.source : "";
-  const resolved = resolveJournalSource({ source, heading: heading ?? "" });
+  const source = journal.source === undefined ? "memoryDir" : typeof journal.source === "string" ? journal.source : "";
+  const resolved = resolveJournalSource({ source });
   if (!resolved.ok) {
-    if (resolved.error === "unknown_source") {
-      throw new RangeError('activity.timeline.journal.source must be one of "file", "vault"');
-    }
-    throw new RangeError('activity.timeline.journal.heading must be a non-empty string when source is "vault"');
+    throw new RangeError('activity.timeline.journal.source must be one of "memoryDir", "vault"');
+  }
+  if (resolved.deprecatedAlias === "file") {
+    process.emitWarning(
+      'activity.timeline.journal.source "file" is deprecated; use "memoryDir".',
+      { type: "DeprecationWarning", code: "REMNIC_DEP_JOURNAL_SOURCE_FILE" },
+    );
   }
-  if (resolved.mode === "vault") {
-    return { enabled: enabledValue ?? false, source: "vault", heading: resolved.heading };
+  const extractionMode = journal.extractionMode === undefined ? "off" : journal.extractionMode;
+  if (extractionMode !== "off" && extractionMode !== "review") {
+    throw new RangeError('activity.timeline.journal.extractionMode must be one of "off", "review"');
   }
-  return { enabled: enabledValue ?? false, source: "file" };
+  return { enabled: enabledValue ?? false, source: resolved.mode, extractionMode };
 }
 
 function parseTimelineQaConfig(raw: unknown): ActivityTimelineQaConfig {

package/src/activity/index.ts

@@ -16,6 +16,9 @@ export * from "./config.js";
 export * from "./reindex.js";
 export * from "./timeline/index.js";
 export * from "./journal.js";
+export * from "./journal-read.js";
+export * from "./journal-state.js";
+export * from "./journal-extract.js";
 export * from "./journal-vault-read.js";
 export * from "./journal-vault-prereq.js";
 export * from "./journal-vault-provenance.js";

package/src/activity/journal-extract-storage.test.ts

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "../config.js";
+import { NamespaceStorageRouter } from "../namespaces/storage.js";
+import { StorageManager } from "../storage.js";
+import { withTempDir } from "../testing/tmp-dir.js";
+import {
+  createJournalMemoryWriter,
+  runJournalReviewExtraction,
+  type JournalExtractionDeps,
+} from "./journal-extract.js";
+
+const FACT = "I decided to encrypt the journal write path.";
+const MAGIC = Buffer.from("REMNIC-ENC");
+
+function walkFiles(root: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(full));
+    else out.push(full);
+  }
+  return out;
+}
+
+function extractDeps(storage: StorageManager, category: "decision" | "fact" = "decision"): JournalExtractionDeps {
+  return {
+    extract: async () => ({
+      facts: [
+        {
+          content: FACT,
+          category,
+          confidence: 0.9,
+          tags: [],
+          entityRef: undefined,
+        },
+      ],
+      profileUpdates: [],
+      entities: [],
+      questions: [],
+    }),
+    writer: createJournalMemoryWriter(storage),
+  };
+}
+
+test("journal writer encrypts on-disk bodies and never stores the fact as plaintext", async () => {
+  await withTempDir(async (dir) => {
+    const config = parseConfig({ memoryDir: dir });
+    const storage = new StorageManager(config.memoryDir);
+    await storage.ensureDirectories();
+    storage.setSecureStoreRequired(true);
+    storage.setSecureStoreKey(Buffer.alloc(32, 7));
+    const result = await runJournalReviewExtraction({
+      date: "2026-08-20",
+      journalText: FACT,
+      source: "memoryDir",
+      journalConfig: { extractionMode: "review" },
+      deps: extractDeps(storage),
+    });
+    assert.equal(result.completed, true);
+    assert.equal(result.pendingReview, 1);
+    const bodies = walkFiles(dir)
+      .filter((file) => !file.includes(`${path.sep}state${path.sep}`))
+      .map((file) => readFileSync(file));
+    assert.ok(bodies.some((buf) => buf.subarray(0, MAGIC.length).equals(MAGIC)));
+    assert.equal(
+      bodies.some((buf) => buf.toString("utf8").includes(FACT)),
+      false,
+      "encrypted journal writes must not leave the fact as plaintext",
+    );
+  });
+});
+
+test("journal writer uses NamespaceStorageRouter.storageFor(defaultNamespace)", async () => {
+  await withTempDir(async (dir) => {
+    const config = parseConfig({ memoryDir: dir });
+    const router = new NamespaceStorageRouter(config);
+    const storage = await router.storageFor(config.defaultNamespace);
+    await storage.ensureDirectories();
+    const result = await runJournalReviewExtraction({
+      date: "2026-08-20",
+      journalText: FACT,
+      source: "memoryDir",
+      journalConfig: { extractionMode: "review" },
+      deps: extractDeps(storage),
+    });
+    assert.equal(result.completed, true);
+    assert.equal(result.pendingReview, 1);
+    assert.ok(walkFiles(dir).some((file) => statSync(file).isFile()));
+  });
+});
+
+test("tombstoned journal facts are skipped and not written as pending_review", async () => {
+  await withTempDir(async (dir) => {
+    const config = parseConfig({ memoryDir: dir });
+    const storage = new StorageManager(config.memoryDir);
+    await storage.ensureDirectories();
+    storage.setTombstonesConfig({
+      enabled: true,
+      semanticMatch: false,
+      semanticThreshold: 0.9,
+      namespace: config.defaultNamespace,
+    });
+    const tombstoneId = await storage.appendTombstone({
+      reason: "correction",
+      createdBy: "user_correction",
+      sourceMemoryId: "retired-journal-fact",
+      rawContent: FACT,
+    });
+    assert.ok(tombstoneId);
+    const before = walkFiles(dir);
+    const result = await runJournalReviewExtraction({
+      date: "2026-08-20",
+      journalText: FACT,
+      source: "memoryDir",
+      journalConfig: { extractionMode: "review" },
+      deps: extractDeps(storage, "fact"),
+    });
+    assert.equal(result.completed, true);
+    assert.equal(result.pendingReview, 0);
+    assert.equal(result.skipped, 1);
+    const after = walkFiles(dir).filter((file) => !before.includes(file));
+    const pending = after.filter((file) => file.includes("pending_review") || file.includes("pending-review"));
+    assert.equal(pending.length, 0, "tombstoned content must not land as a new pending_review file");
+  });
+});