A local-first multi-agent app development platform, built on PenguinHarness
/**
* Trace-file index tests: mtime-gated reconciliation (an unchanged tree costs zero
* directory scans), registration-time classification, gate blind spots recovered by
* the consumers' force-retry, write-time registration (import) and delete coherence.
* A cache row registered before the source was required (NULL, or the retired `benchmark`)
* reads as a head that records no source (which the session list reads with the row's client)
* / as `cli`, without being rewritten.
*/
import fs from "node:fs/promises";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { sessionMeta, userText } from "@adelie/core";
import type { SessionMetaPayload, SessionSource } from "@adelie/core";
import { makeTempRoot, makeTraceHarness, writeTraceFile } from "./helpers.js";
const P = "project-i";
const A = "agent-i";
const S1 = "session-2026-07-05-10-00-00-aabb0001";
const S2 = "session-2026-07-06-09-00-00-aabb0002";
const OLD = "session-2026-07-01-08-00-00-aabb0003";
/**
* Ages the given paths' mtimes past the reconciler's FRESH_MS window: freshly written
* dirs are deliberately never cached as clean (same-tick change hazard), so steady-state
* assertions first make the tree look quiet, exactly like a tree written minutes ago.
*/
async function backdate(...paths: string[]): Promise<void> {
// A FIXED past instant, so repeated backdates are idempotent. Every date dir is now
// gated, so the blind-spot test relies on that idempotence rather than on an unwatched
// dir: it resets a CHANGED dir to exactly the mtime the gate already cached, which is
// the surviving "backdated write" scenario.
const old = new Date("2026-01-01T00:00:00.000Z");
for (const p of paths) {
await fs.utimes(p, old, old);
}
}
function tracesRoot(root: string): string {
return path.join(root, P, "agents", A, "traces");
}
function meta(sessionId: string, over: Partial<SessionMetaPayload> = {}): SessionMetaPayload {
return {
session_id: sessionId,
model_id: "m1",
provider: "custom",
model_context_window: 1000,
system_prompt: "sp",
agent_state: "/tmp/a",
workspace: "/ws/one",
source: "user",
...over,
};
}
describe("trace-index", () => {
let root: string;
let h: ReturnType<typeof makeTraceHarness>;
beforeEach(async () => {
root = await makeTempRoot();
h = makeTraceHarness(root);
});
afterEach(async () => {
h.close();
await fs.rm(root, { recursive: true, force: true });
});
it("registers external files on reconcile and classifies each Session once; an unchanged tree costs zero directory scans", async () => {
await writeTraceFile(root, P, A, "2026-07-05", S1, 1, [
sessionMeta(meta(S1, { source: "subagent" })),
userText("你好,请检查代码"),
]);
await backdate(tracesRoot(root), path.join(tracesRoot(root), "2026-07-05"));
await h.traceIndex.reconcileAgent(P, A);
const rows = h.traceIndex.repo.listFilesByAgent(P, A);
expect(
rows.map((r) => ({ sessionId: r.sessionId, fileIndex: r.fileIndex, date: r.date })),
).toEqual([{ sessionId: S1, fileIndex: 1, date: "2026-07-05" }]);
expect(rows[0]!.sizeBytes).toBeGreaterThan(0);
// Registration-time facts: origin / workspace / first-prompt title, one head-read.
const facts = h.traceIndex.repo.getSession(S1);
expect(facts?.source).toBe("subagent");
expect(facts?.workspace).toBe("/ws/one");
expect(facts?.title).toBe("你好,请检查代码");
expect(facts?.metaRead).toBe(true);
expect(h.sources.get(S1)).toBe("subagent");
expect(h.traceIndex.counters.headReads).toBe(1);
// Steady state: reconciling an unchanged tree is pure gate stats — no readdir, no reads.
// gateStats is pinned too: the gate costs one root stat plus one per date dir, and
// only one date dir exists here. Without this the hot path could grow silently.
const scans = h.traceIndex.counters.dirScans;
const gate = h.traceIndex.counters.gateStats;
await h.traceIndex.reconcileAgent(P, A);
await h.traceIndex.reconcileAgent(P, A);
expect(h.traceIndex.counters.dirScans).toBe(scans);
expect(h.traceIndex.counters.headReads).toBe(1);
expect(h.traceIndex.counters.gateStats).toBe(gate + 2 * (1 + 1));
// A new shard in the same (newest) date dir moves that dir's mtime: the gate notices.
await writeTraceFile(root, P, A, "2026-07-05", S2, 1, [
sessionMeta(meta(S2)),
userText("second session"),
]);
await h.traceIndex.reconcileAgent(P, A);
expect(h.traceIndex.repo.listFilesByAgent(P, A)).toHaveLength(2);
expect(h.traceIndex.counters.dirScans).toBe(scans + 1);
expect(h.traceIndex.repo.getSession(S2)?.metaRead).toBe(true);
});
it("a new shard (compaction rotate) in a NON-newest date dir is caught by the gate", async () => {
// Simulates compaction: session starts in 2026-07-05, then rotate() creates _002
// in the SAME date dir — but a newer date dir (2026-07-06) already exists.
await writeTraceFile(root, P, A, "2026-07-05", S1, 1, [userText("first turn")]);
await writeTraceFile(root, P, A, "2026-07-06", S2, 1, [userText("other session next day")]);
await backdate(
tracesRoot(root),
path.join(tracesRoot(root), "2026-07-05"),
path.join(tracesRoot(root), "2026-07-06"),
);
await h.traceIndex.reconcileAgent(P, A);
expect(h.traceIndex.repo.listFilesBySession(P, A, S1)).toHaveLength(1);
// Compaction rotate: new shard in the OLD date dir (2026-07-05), not the newest (2026-07-06).
await writeTraceFile(root, P, A, "2026-07-05", S1, 2, [userText("post-compaction turn")]);
await h.traceIndex.reconcileAgent(P, A);
// The gate must catch the change in the non-newest dir and register the new shard.
expect(h.traceIndex.repo.listFilesBySession(P, A, S1)).toHaveLength(2);
// The newest dir is gated FIRST and short-circuits: with the tree quiet again, a
// change confined to the newest dir must settle the gate in one date-dir stat, so
// the older dirs stay off the hot path however many of them accumulate.
await backdate(
tracesRoot(root),
path.join(tracesRoot(root), "2026-07-05"),
path.join(tracesRoot(root), "2026-07-06"),
);
await h.traceIndex.reconcileAgent(P, A);
const gate = h.traceIndex.counters.gateStats;
await writeTraceFile(root, P, A, "2026-07-06", S2, 2, [userText("newest dir moves")]);
await h.traceIndex.reconcileAgent(P, A);
expect(h.traceIndex.repo.listFilesBySession(P, A, S2)).toHaveLength(2);
expect(h.traceIndex.counters.gateStats).toBe(gate + 2); // root + newest only
});
it("a write into an OLD date dir with backdated mtime slips past the gate; the consumers' force-retry (locateAll) recovers it", async () => {
// Two date dirs indexed; the gate now watches the root + ALL date dirs.
// A normal write moves the old dir's mtime and is caught (covered by the test above).
// The remaining blind spot is a backdated write: the external writer changes the
// old dir but then resets its mtime to the cached value, making the change invisible.
await writeTraceFile(root, P, A, "2026-07-01", OLD, 1, [userText("old day")]);
await writeTraceFile(root, P, A, "2026-07-05", S1, 1, [userText("new day")]);
await backdate(
tracesRoot(root),
path.join(tracesRoot(root), "2026-07-01"),
path.join(tracesRoot(root), "2026-07-05"),
);
await h.traceIndex.reconcileAgent(P, A);
expect(h.traceIndex.repo.listFilesByAgent(P, A)).toHaveLength(2);
// External writer appends a SECOND shard into the old dir: neither gated mtime
// (root / newest dir) moves. Backdating the old dir again keeps its change invisible
// even to a freshness-triggered re-diff — the pure gate blind spot.
await writeTraceFile(root, P, A, "2026-07-01", OLD, 2, [userText("late arrival")]);
await backdate(tracesRoot(root), path.join(tracesRoot(root), "2026-07-01"));
await h.traceIndex.reconcileAgent(P, A);
expect(h.traceIndex.repo.listFilesBySession(P, A, OLD)).toHaveLength(1); // gate blind spot
// A consumer that misses must force-reconcile and retry rather than 404: the
// service's listTraceFiles goes through locateAll, which does exactly that when the
// requested index is absent... locateAll's whole-session miss is the trigger, so
// exercise it via a session the index does not know at all.
const LATE = "session-2026-07-01-09-00-00-aabb0009";
await writeTraceFile(root, P, A, "2026-07-01", LATE, 1, [userText("unseen session")]);
await backdate(tracesRoot(root), path.join(tracesRoot(root), "2026-07-01"));
const files = await h.service.listTraceFiles(P, A, LATE);
expect(files.map((f) => f.index)).toEqual([1]);
// The forced pass also swept in the other blind-spot shard.
expect(h.traceIndex.repo.listFilesBySession(P, A, OLD)).toHaveLength(2);
});
it("import registers synchronously (rows + facts, no re-read); Session delete removes files and rows", async () => {
const IMP = "session-2026-07-03-12-00-00-aabb0004";
const lines = [
sessionMeta(meta(IMP, { source: "schedule", workspace: "/ws/imp" })),
userText("imported prompt"),
]
.map((m) => JSON.stringify({ ...m, timestamp: "2026-07-03T12:00:00.000Z" }))
.join("\n");
const headReads = h.traceIndex.counters.headReads;
const res = await h.service.importTraceFile(P, A, lines);
expect(res).toEqual({ sessionId: IMP, index: 1, date: "2026-07-03", shards: 1 });
// Registered without any head-read (the records were already in memory).
expect(h.traceIndex.counters.headReads).toBe(headReads);
expect(h.traceIndex.repo.listFilesBySession(P, A, IMP)).toHaveLength(1);
const facts = h.traceIndex.repo.getSession(IMP);
expect(facts?.source).toBe("schedule");
expect(facts?.workspace).toBe("/ws/imp");
expect(facts?.title).toBe("imported prompt");
await h.service.deleteSessionTraces(P, A, IMP);
expect(h.traceIndex.repo.listFilesBySession(P, A, IMP)).toEqual([]);
expect(h.traceIndex.repo.getSession(IMP)).toBeNull();
// The files are gone from disk too, and a fresh reconcile does not resurrect rows.
await h.traceIndex.reconcileAgent(P, A, { force: true });
expect(h.traceIndex.repo.listFilesBySession(P, A, IMP)).toEqual([]);
});
it("reads a cache row registered before the source was required: NULL as no recorded source, benchmark as cli", async () => {
// The derived cache is never migrated: rows an older release registered keep the string
// (or the NULL) their head carried, and are read through the same narrowing. NULL stays
// "records none": whether that is a person's conversation or a company Session is the
// index row's to say (readRecordedSource).
const row = {
sessionId: S1,
projectId: P,
agentId: A,
workspace: "/ws/one",
title: null,
provider: "custom",
modelId: "m1",
firstTs: null,
metaRead: true,
};
h.traceIndex.repo.upsertSession({ ...row, source: null });
expect(h.traceIndex.repo.getSession(S1)?.source).toBeNull();
h.traceIndex.repo.upsertSession({ ...row, source: "benchmark" as unknown as SessionSource });
expect(h.traceIndex.repo.getSession(S1)?.source).toBe("cli");
});
it("externally deleted files and date dirs fall out of the index on the next changed-dir pass", async () => {
await writeTraceFile(root, P, A, "2026-07-05", S1, 1, [userText("a")]);
await writeTraceFile(root, P, A, "2026-07-05", S1, 2, [userText("b")]);
await h.traceIndex.reconcileAgent(P, A);
expect(h.traceIndex.repo.listFilesBySession(P, A, S1)).toHaveLength(2);
const dir = path.join(root, P, "agents", A, "traces", "2026-07-05");
await fs.rm(path.join(dir, `${S1}_002.jsonl`));
await h.traceIndex.reconcileAgent(P, A); // the dir's mtime moved: rescanned
expect(h.traceIndex.repo.listFilesBySession(P, A, S1).map((r) => r.fileIndex)).toEqual([1]);
await fs.rm(dir, { recursive: true });
await h.traceIndex.reconcileAgent(P, A); // the root's mtime moved: date dir purged
expect(h.traceIndex.repo.listFilesByAgent(P, A)).toEqual([]);
});
});