@remnic/core 9.65.7 → 9.66.0

package/src/okf/index-files.ts

@@ -0,0 +1,114 @@
+import { readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import path from "node:path";
+
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
+import { normalizeProjectionPreview } from "../memory-projection-format.js";
+import { OKF_RESERVED_BASENAMES } from "./type-mapping.js";
+
+export const OKF_INDEX_MARKER = "<!-- remnic-okf-index -->";
+
+const INDEXED_ROOTS = ["entities", "facts", "corrections", "summaries"] as const;
+
+export interface OkfIndexReport {
+  written: string[];
+  removed: string[];
+}
+
+export async function runOkfIndexMaintenance(
+  memoryDir: string,
+  enabled: boolean,
+): Promise<OkfIndexReport> {
+  const written: string[] = [];
+  const removed: string[] = [];
+  const dirs = collectIndexDirs(memoryDir);
+  for (const dir of dirs) {
+    const indexPath = path.join(dir, "index.md");
+    if (!enabled) {
+      if (isGeneratedIndex(indexPath)) {
+        unlinkSync(indexPath);
+        removed.push(indexPath);
+      }
+      continue;
+    }
+    const next = renderIndex(dir);
+    if (next === null) continue;
+    if (isUnchangedGenerated(indexPath, next)) continue;
+    await writeFileAtomically(indexPath, next);
+    written.push(indexPath);
+  }
+  return { written, removed };
+}
+
+function collectIndexDirs(memoryDir: string): string[] {
+  const dirs = [memoryDir];
+  for (const root of INDEXED_ROOTS) {
+    const full = path.join(memoryDir, root);
+    if (!isDir(full)) continue;
+    dirs.push(full);
+    if (root === "facts") {
+      for (const entry of safeList(full)) {
+        const child = path.join(full, entry);
+        if (isDir(child) && /^\d{4}-\d{2}-\d{2}$/.test(entry)) dirs.push(child);
+      }
+    }
+  }
+  return dirs;
+}
+
+function renderIndex(dir: string): string | null {
+  const entries = safeList(dir)
+    .filter((name) => name.endsWith(".md") && OKF_RESERVED_BASENAMES[name] !== true)
+    .sort((a, b) => a.localeCompare(b));
+  if (entries.length === 0) return null;
+  const lines = [OKF_INDEX_MARKER, "", `# ${path.basename(dir)}`, ""];
+  for (const name of entries) {
+    const preview = previewFile(path.join(dir, name));
+    lines.push(`* [${titleFrom(name, preview)}](${name}) - ${preview}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function previewFile(filePath: string): string {
+  try {
+    return normalizeProjectionPreview(readFileSync(filePath, "utf8"), 120);
+  } catch {
+    return "";
+  }
+}
+
+function titleFrom(name: string, preview: string): string {
+  return preview.split(" ").slice(0, 8).join(" ") || name.replace(/\.md$/, "");
+}
+
+function isGeneratedIndex(filePath: string): boolean {
+  try {
+    return readFileSync(filePath, "utf8").includes(OKF_INDEX_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function isUnchangedGenerated(filePath: string, next: string): boolean {
+  try {
+    return readFileSync(filePath, "utf8") === next;
+  } catch {
+    return false;
+  }
+}
+
+function isDir(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function safeList(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}

package/src/okf/render.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared OKF bundle-rendering helpers (issues #1948 + #1950).
+ *
+ * One source of truth for the mechanics every OKF bundle exporter uses:
+ * deterministic frontmatter rendering, staging-directory file writes, the
+ * symlink-guarded atomic publish, and the bundle version stamp. The memory
+ * exporter (transfer/export-okf.ts) and the codegraph exporter
+ * (coding/export-okf-codegraph.ts) both consume this module so their
+ * bundles are byte-compatible in convention (rule 38 — deterministic
+ * rendering discipline; rule 9 — stable seam over shared mechanics).
+ */
+import { lstatSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** OKF spec version emitted in every bundle root index. */
+export const OKF_EXPORT_VERSION = "0.1";
+
+/**
+ * Render a YAML frontmatter block from a flat field map.
+ *
+ * Key order: the canonical OKF keys first (`type`, `title`, `description`,
+ * `tags`, `timestamp`), everything else alphabetical — one deterministic
+ * layout so identical inputs always render byte-identical files. A key set
+ * to `undefined` is omitted; callers must not pass a key twice.
+ */
+export function renderFrontmatter(fields: Record<string, unknown>): string {
+  const keys = Object.keys(fields).sort((a, b) => {
+    const order = ["type", "title", "description", "tags", "timestamp"];
+    const ai = order.indexOf(a);
+    const bi = order.indexOf(b);
+    if (ai >= 0 || bi >= 0) return (ai < 0 ? 99 : ai) - (bi < 0 ? 99 : bi);
+    return a.localeCompare(b);
+  });
+  const lines = keys.flatMap((key) => yamlLine(key, fields[key]));
+  return `---\n${lines.join("\n")}\n---\n\n`;
+}
+
+function yamlLine(key: string, value: unknown): string[] {
+  if (value === undefined) return [];
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [`${key}: []`];
+    if (value.every((item) => typeof item !== "object" || item === null)) {
+      return [`${key}:`, ...value.map((item) => `  - ${yamlScalar(item)}`)];
+    }
+    return [`${key}: ${JSON.stringify(value)}`];
+  }
+  if (typeof value === "object" && value !== null) return [`${key}: ${JSON.stringify(value)}`];
+  return [`${key}: ${yamlScalar(value)}`];
+}
+
+function yamlScalar(value: unknown): string {
+  if (typeof value === "string") {
+    if (value === "" || /[:#\n]/.test(value) || value !== value.trim()) return JSON.stringify(value);
+    return value;
+  }
+  return String(value);
+}
+
+/**
+ * Write one file into a bundle staging tree. `rel` is a POSIX-style
+ * bundle-relative path; parent directories are created as needed.
+ */
+export function writeBundleFile(root: string, rel: string, content: string): void {
+  const dest = path.join(root, ...rel.split("/"));
+  mkdirSync(path.dirname(dest), { recursive: true });
+  writeFileSync(dest, content, "utf8");
+}
+
+/**
+ * Publish a staged bundle: refuse a non-empty target without `--force`,
+ * swap via rename so the target is never observed half-written, and keep a
+ * restorable backup when replacing an existing tree.
+ */
+export function publishBundle(staging: string, outDir: string, force: boolean): void {
+  let exists = false;
+  try {
+    const stat = lstatSync(outDir);
+    if (stat.isSymbolicLink()) throw new Error(`--out must not be a symlink: ${outDir}`);
+    exists = true;
+    const entries = readdirSync(outDir).filter((name) => name !== "." && name !== "..");
+    if (entries.length > 0 && !force) {
+      rmSync(staging, { recursive: true, force: true });
+      throw new Error(`--out ${outDir} is not empty; pass --force to replace it`);
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+  mkdirSync(path.dirname(outDir), { recursive: true });
+  if (exists && force) {
+    const backup = `${outDir}.okf-prev`;
+    try {
+      renameSync(outDir, backup);
+    } catch {
+      rmSync(staging, { recursive: true, force: true });
+      throw new Error(`cannot replace --out ${outDir}`);
+    }
+    try {
+      renameSync(staging, outDir);
+      rmSync(backup, { recursive: true, force: true });
+    } catch (err) {
+      try {
+        renameSync(backup, outDir);
+      } catch {
+        // Keep backup if restore fails.
+      }
+      throw err;
+    }
+    return;
+  }
+  renameSync(staging, outDir);
+}
+
+/**
+ * Reject a --out path with a symlink anywhere in its component chain
+ * (pattern 42 + hermes-shim precedent): a symlinked component could aim
+ * the atomic rename outside the operator's chosen directory.
+ */
+export function rejectSymlinkPath(target: string): void {
+  let current = path.resolve(target);
+  while (true) {
+    try {
+      if (lstatSync(current).isSymbolicLink()) {
+        throw new Error(`--out path component is a symlink: ${current}`);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+

package/src/okf/type-mapping.test.ts

@@ -49,6 +49,7 @@ test("parseOkfConfig treats false as a real disable", () => {
   assert.deepEqual(parseOkfConfig({ conformanceEnabled: false, sweepEnabled: "false" }), {
     conformanceEnabled: false,
     sweepEnabled: false,
+    indexFilesEnabled: false,
   });
   assert.throws(() => parseOkfConfig("nope"), /okf must be an object/);
 });
@@ -164,6 +165,7 @@ test("runOkfCliCommand handles help and rejects unexpected tokens", async () =>
       memoryDir: "/tmp",
       conformanceEnabled: true,
       sweepEnabled: false,
+      indexFilesEnabled: false,
     });
     assert.equal(code, 0);
     assert.match(chunks.join(""), /usage: remnic okf/);
@@ -176,6 +178,7 @@ test("runOkfCliCommand handles help and rejects unexpected tokens", async () =>
       memoryDir: "/tmp",
       conformanceEnabled: true,
       sweepEnabled: false,
+      indexFilesEnabled: false,
     });
     assert.equal(code, 1);
     assert.match(errChunks.join(""), new RegExp(`unexpected argument '${token}'`));

package/src/okf/type-mapping.ts

@@ -57,6 +57,8 @@ export function okfTypeForEntityKind(kind: string | undefined): string {
 export const OKF_PROFILE_TYPE = "Profile";
 export const OKF_QUESTION_TYPE = "Question";
 export const OKF_DECISION_RECORD_TYPE = "Decision Record";
+export const OKF_ARCHITECTURE_CARD_TYPE = "Architecture Card";
+export const OKF_CODE_MODULE_TYPE = "Code Module";
 
 /**
  * OKF §6/§7 reserve `index.md` and `log.md` for bundle-level files with a

package/src/orchestration/extraction-run.ts

@@ -40,6 +40,7 @@ import {
   type MemoryLifecycleCapabilitySet,
 } from "../capabilities.js";
 import { parseFlexibleIsoTimestamp } from "../utils/iso-timestamp.js";
+import { tagPersistedMemories } from "../location/tagging.js";
 import { log } from "../logger.js";
 import type { PluginConfig, BufferTurn, ExtractionResult, MetaState, ExtractionFailureClass } from "../types.js";
 import type { TierMigrationCycleSummary } from "../recall-state.js";
@@ -62,7 +63,6 @@ export class ExtractionDeadlineError extends Error {
   }
 }
 
-
 /** Dependencies injected by the orchestrator. All stable references or
  *  live accessors — lazy getters for anything tests reassign
  *  post-construction (buffer, extraction, storageRouter, threading). */
@@ -1090,6 +1090,7 @@ export class ExtractionRunCoordinator {
       log.warn("runExtraction: durable-commit callback failed", error);
     }
     const runPostPersistBestEffort = runExtractionPostPersistBestEffort.bind(null, runDeadlineAware);
+    await tagPersistedMemories(storage, persistedIds, this.config);
     const postPersist = await runExtractionPostPersist({
       result,
       storage,

package/src/orchestration/generic-recall-paths.ts

@@ -9,6 +9,8 @@ import {
   isLocationDayPath,
   isMeetingRecordPath,
 } from "./orchestrator-helpers.js";
+import { OKF_RESERVED_BASENAMES } from "../okf/type-mapping.js";
+
 
 export interface GenericRecallPathPolicy {
   readonly memoryDir?: string;
@@ -230,9 +232,8 @@ export function isGenericRecallExcludedPath(
 ): boolean {
   return (
     isSearchExcludedPath(filePath, policy, source) ||
-    // Recall-only: archived memories are cold, but an explicit search is one
-    // of the surfaces they remain reachable through.
-    isTopLevelArchivePath(filePath, policy, source)
+    isTopLevelArchivePath(filePath, policy, source) ||
+    OKF_RESERVED_BASENAMES[path.basename(filePath)] === true
   );
 }
 

package/src/schemas.ts

@@ -181,7 +181,7 @@ export const ExtractedFactSchema = z.object({
     .optional()
     .nullable()
     .describe(
-      'For category "reasoning_trace" only: a stored solution chain with ordered steps, a final answer, and an optional observed outcome. Require at least two steps.',
+      'For category "reasoning_trace" only: a stored solution chain with ordered steps, a final answer, and an optional observed outcome. Require at least two steps. IMPORTANT: must include a non-empty finalAnswer (or final_answer) — the JSON Schema sent to providers cannot enforce this constraint.',
     ),
   eventTime: z
     .string()
@@ -350,6 +350,22 @@ export const ExtractionResultSchema = z.object({
     ),
 });
 
+/**
+ * Provider-facing extraction contract. Keep this free of transforms/refinements:
+ * JSON Schema generators cannot faithfully represent salvageArray's ZodEffects.
+ * ExtractionResultSchema remains the authoritative tolerant parser after the
+ * provider returns.
+ */
+export const ExtractionProviderOutputSchema = z.object({
+  facts: z.array(ExtractedFactSchema),
+  profileUpdates: z.array(z.string()),
+  entities: z.array(EntityMentionSchema),
+  questions: z.array(ExtractedQuestionSchema),
+  identityReflection: z.string().optional().nullable(),
+  episodeTitle: z.string().optional().nullable(),
+  relationships: z.array(ExtractedRelationshipSchema).optional().nullable(),
+});
+
 export const ConsolidationItemSchema = z.object({
   existingId: z
     .string()

package/src/standup/access-operations.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+import { defineOperation } from "../access-boundary.js";
+import { buildStandup, parseStandupDate } from "./build.js";
+
+defineOperation({
+  name: "standup",
+  description: "Deterministic yesterday/today/blockers standup brief.",
+  fleetWide: true,
+  schema: z.object({ date: z.string().optional() }).strict(),
+  handler: async (input, ctx) => ({
+    result: buildStandup(ctx.service.memoryDir, parseStandupDate(input.date)),
+  }),
+});

package/src/standup/build.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { buildStandup, parseStandupDate, previousDate } from "./build.js";
+
+test("parseStandupDate rejects garbage and defaults to UTC today", () => {
+  assert.equal(parseStandupDate(undefined, new Date("2026-08-18T12:00:00Z")), "2026-08-18");
+  assert.throws(() => parseStandupDate("nope"), /YYYY-MM-DD/);
+  assert.equal(previousDate("2026-08-18"), "2026-08-17");
+});
+
+test("buildStandup is deterministic and marks missing days", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-standup-"));
+  try {
+    await mkdir(path.join(memoryDir, "activity"), { recursive: true });
+    await writeFile(
+      path.join(memoryDir, "activity", "2026-08-18.md"),
+      "---\ndate: 2026-08-18\n---\n# Today\n- shipped standup\n- blocker: waiting on review\n",
+      "utf8",
+    );
+    const a = buildStandup(memoryDir, "2026-08-18");
+    const b = buildStandup(memoryDir, "2026-08-18");
+    assert.equal(a.markdown, b.markdown);
+    assert.equal(a.yesterday, "2026-08-17");
+    assert.match(a.markdown, /blocker: waiting on review/);
+    assert.match(a.activityGrid, /yesterday \| \./);
+    assert.match(a.activityGrid, /today \| x/);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/standup/build.ts

@@ -0,0 +1,115 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { activityDigestPath, isValidActivityDate } from "../activity/digest.js";
+
+export interface StandupBrief {
+  date: string;
+  yesterday: string;
+  today: string;
+  highlights: string[];
+  blockers: string[];
+  activityGrid: string;
+  markdown: string;
+}
+
+export function parseStandupDate(raw: unknown, now = new Date()): string {
+  if (raw === undefined || raw === null || raw === "") {
+    return now.toISOString().slice(0, 10);
+  }
+  const value = String(raw);
+  if (!isValidActivityDate(value)) {
+    throw new Error(`invalid --date ${value}; expected YYYY-MM-DD`);
+  }
+  return value;
+}
+
+export function previousDate(date: string): string {
+  const ms = Date.parse(`${date}T00:00:00Z`);
+  return new Date(ms - 86_400_000).toISOString().slice(0, 10);
+}
+
+export function buildStandup(memoryDir: string, date: string): StandupBrief {
+  const yesterday = previousDate(date);
+  const todayBody = readOptional(activityDigestPath(memoryDir, date));
+  const yesterdayBody = readOptional(activityDigestPath(memoryDir, yesterday));
+  const highlights = extractHighlights(todayBody);
+  const blockers = extractBlockers(todayBody);
+  const activityGrid = renderGrid(yesterdayBody, todayBody);
+  const markdown = [
+    `# Standup ${date}`,
+    "",
+    `## Yesterday (${yesterday})`,
+    yesterdayBody ? firstLines(yesterdayBody, 8) : "_No activity digest._",
+    "",
+    `## Today (${date})`,
+    todayBody ? firstLines(todayBody, 8) : "_No activity digest._",
+    "",
+    "## Highlights",
+    ...(highlights.length > 0 ? highlights.map((line) => `- ${line}`) : ["- _None._"]),
+    "",
+    "## Blockers",
+    ...(blockers.length > 0 ? blockers.map((line) => `- ${line}`) : ["- _None._"]),
+    "",
+    "## Activity grid",
+    "",
+    activityGrid,
+    "",
+  ].join("\n");
+  return {
+    date,
+    yesterday,
+    today: date,
+    highlights,
+    blockers,
+    activityGrid,
+    markdown,
+  };
+}
+
+function readOptional(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function firstLines(body: string, n: number): string {
+  return body.split("\n").filter((line) => !line.startsWith("---")).slice(0, n).join("\n").trim() || "_Empty digest._";
+}
+
+function extractHighlights(body: string | null): string[] {
+  if (!body) return [];
+  return body
+    .split("\n")
+    .map((line) => line.replace(/^[-*]\s+/, "").trim())
+    .filter((line) => line.length > 0 && !line.startsWith("#") && !line.startsWith("---"))
+    .slice(0, 5);
+}
+
+function extractBlockers(body: string | null): string[] {
+  if (!body) return [];
+  return body
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => /blocker|blocked|stuck|waiting/i.test(line))
+    .slice(0, 5);
+}
+
+function renderGrid(yesterday: string | null, today: string | null): string {
+  const y = yesterday ? "x" : ".";
+  const t = today ? "x" : ".";
+  return ["| day | digest |", "|---|---|", `| yesterday | ${y} |`, `| today | ${t} |`].join("\n");
+}
+
+export function standupHelp(): string {
+  return `Usage: remnic standup [--date YYYY-MM-DD]
+
+Deterministic yesterday/today/blockers brief plus an activity grid.
+`;
+}
+
+export function standupMemoryDirPlaceholder(memoryDir: string): string {
+  return path.resolve(memoryDir);
+}

package/src/standup/http-glue.ts

@@ -0,0 +1,15 @@
+import type { ServerResponse } from "node:http";
+import { getOperation } from "../access-boundary.js";
+import type { EngramAccessService } from "../access-service.js";
+
+export async function respondStandup(
+  date: string | null,
+  res: ServerResponse,
+  respondJson: (res: ServerResponse, status: number, payload: unknown) => void,
+  service: EngramAccessService,
+): Promise<void> {
+  const op = getOperation("standup");
+  if (!op) throw new Error("access-boundary: operation not registered: standup");
+  const output = (await op.run({ ...(date ? { date } : {}) }, { service })) as { result: unknown };
+  respondJson(res, 200, output.result);
+}

package/src/standup/mcp-tools.ts

@@ -0,0 +1,16 @@
+import type { McpTool } from "../access-mcp.js";
+
+export const STANDUP_MCP_TOOLS: McpTool[] = [
+  {
+    name: "engram.standup",
+    description:
+      "Deterministic standup brief: yesterday highlights, today priorities, blockers, and an activity grid. Pass date as YYYY-MM-DD; default is today UTC.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        date: { type: "string", description: "Standup day (YYYY-MM-DD). Defaults to today UTC." },
+      },
+      additionalProperties: false,
+    },
+  },
+];

package/src/storage/context-transform-ledger.ts

@@ -0,0 +1,39 @@
+import type { ContextTransformTelemetryRecord } from "../active-context-transform.js";
+import { readContextTransformRecordRowsFromLines, readMaybeEncryptedLines } from "./secure-line-reader.js";
+
+export interface ContextTransformLedgerHost {
+  memoryActionsPath: string;
+  ensureDirectories(): Promise<void>;
+  appendStorageSecureFile(path: string, payload: string): Promise<void>;
+  readStorageSecureFile(path: string): Promise<string>;
+}
+
+export async function appendContextTransformRecords(
+  host: ContextTransformLedgerHost,
+  records: ContextTransformTelemetryRecord[],
+): Promise<number> {
+  if (records.length === 0) return 0;
+  await host.ensureDirectories();
+  await host.appendStorageSecureFile(
+    host.memoryActionsPath,
+    records.map((record) => `${JSON.stringify(record)}\n`).join(""),
+  );
+  return records.length;
+}
+
+export async function readContextTransformRecords(
+  host: ContextTransformLedgerHost,
+  limit = 200,
+): Promise<ContextTransformTelemetryRecord[]> {
+  const cappedLimit = Math.max(0, Math.floor(limit));
+  if (cappedLimit === 0 || Number.isNaN(cappedLimit)) return [];
+  try {
+    const rows = await readContextTransformRecordRowsFromLines(
+      readMaybeEncryptedLines(host.memoryActionsPath, () => host.readStorageSecureFile(host.memoryActionsPath)),
+      cappedLimit,
+    );
+    return rows.map((row) => row.record);
+  } catch {
+    return [];
+  }
+}

package/src/storage/secure-line-reader.ts

@@ -3,6 +3,7 @@ import { lstat, open } from "node:fs/promises";
 import { createInterface } from "node:readline";
 
 import { isEncryptedFile, MAGIC_HEADER_SIZE } from "../secure-store/secure-fs.js";
+import type { ContextTransformTelemetryRecord } from "../active-context-transform.js";
 import type { MemoryActionEvent, MemoryLifecycleEvent } from "../types.js";
 
 /**
@@ -89,7 +90,11 @@ export async function readMemoryActionEventRowsFromLines(
     const line = row.trim();
     if (!line) continue;
     try {
-      const parsed = JSON.parse(line) as Partial<MemoryActionEvent>;
+      const parsed = JSON.parse(line) as Partial<MemoryActionEvent> & { recordKind?: unknown };
+      // Ledger discriminated union (#2347): any row carrying a `recordKind`
+      // belongs to another record family (e.g. context_transform) and must
+      // be ignored here — the legacy parser stays strict for its own kind.
+      if (parsed.recordKind !== undefined) continue;
       const outcome = parsed.outcome === "applied" || parsed.outcome === "skipped" || parsed.outcome === "failed"
         ? parsed.outcome
         : null;
@@ -116,6 +121,50 @@ export async function readMemoryActionEventRowsFromLines(
   return writeIndex === 0 ? out : [...out.slice(writeIndex), ...out.slice(0, writeIndex)];
 }
 
+/**
+ * Tail read for context-transform telemetry rows (#2347). Selects ONLY
+ * records discriminated by `recordKind: "context_transform"` — the sibling
+ * of `readMemoryActionEventRowsFromLines`, with the same O(limit) ring
+ * buffer and line-number semantics. Malformed rows are skipped fail-open;
+ * legacy action rows are never returned here.
+ */
+export async function readContextTransformRecordRowsFromLines(
+  lines: AsyncIterable<string>,
+  limit: number,
+): Promise<Array<{ line: number; record: ContextTransformTelemetryRecord }>> {
+  const out: Array<{ line: number; record: ContextTransformTelemetryRecord }> = [];
+  let writeIndex = 0;
+  let lineNumber = 0;
+  for await (const row of lines) {
+    lineNumber += 1;
+    const line = row.trim();
+    if (!line) continue;
+    try {
+      const parsed = JSON.parse(line) as Partial<ContextTransformTelemetryRecord>;
+      if (
+        parsed.recordKind === "context_transform" &&
+        typeof parsed.timestamp === "string" &&
+        typeof parsed.actionId === "string" &&
+        typeof parsed.planHash === "string"
+      ) {
+        const entry = {
+          line: lineNumber,
+          record: parsed as ContextTransformTelemetryRecord,
+        };
+        if (out.length < limit) {
+          out.push(entry);
+        } else {
+          out[writeIndex] = entry;
+          writeIndex = (writeIndex + 1) % limit;
+        }
+      }
+    } catch {
+      // Ignore malformed rows (fail-open).
+    }
+  }
+  return writeIndex === 0 ? out : [...out.slice(writeIndex), ...out.slice(0, writeIndex)];
+}
+
 /**
  * Validate that a parsed row carries every required lifecycle-event field.
  * Shared by the tail reader and the per-memory reader so both apply the EXACT