@unbrained/pm-cli 2026.9.1 → 2026.9.3

package/dist/core/history/event-index.js

@@ -5,20 +5,115 @@
  * for cursor-resumable cross-item mutation event reads.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a84b308f-7eef-535c-9531-b33b0775c651")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="72b285a7-970e-5965-bacf-a4e0cfc5f060")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
+import { isFileMissingError } from "../fs/fs-utils.js";
+import { acquireLock, captureProcessIdentity, isProcessIdentityAlive, } from "../lock/lock.js";
+import { EXIT_CODE } from "../shared/constants.js";
+import { PmCliError } from "../shared/errors.js";
+import { isMillisecondPrecisionRfc3339DateTime } from "../shared/time.js";
 import { readHistoryEntries } from "./read.js";
+import { classifyHistoryEvent } from "./event-classification.js";
 const EVENT_INDEX_FILENAME = "history-event-index.sqlite";
-const EVENT_INDEX_VERSION = "2";
+const EVENT_INDEX_VERSION = "5";
 const AUTHORITATIVE_HISTORY_CACHE_LIMIT = 8;
+const HISTORY_EVENT_INDEX_LOCK_ID = "history-event-index";
+const HISTORY_EVENT_INDEX_LOCK_TTL_SECONDS = 300;
+const HISTORY_EVENT_INDEX_LOCK_WAIT_MS = 30_000;
+const HISTORY_EVENT_INDEX_INVALIDATION_LOCK_ID = "history-event-index-invalidation";
+const HISTORY_EVENT_INDEX_INVALIDATION_DIRECTORY = "history-event-index-invalidations";
+const HISTORY_EVENT_INDEX_INVALIDATION_MAX_UNVERIFIED_AGE_MS = HISTORY_EVENT_INDEX_LOCK_TTL_SECONDS * 2 * 1_000;
+const HISTORY_INDEX_LOCK_CONTENDED = Symbol("history-index-lock-contended");
 const authoritativeHistoryCaches = new Map();
 function eventIndexPath(pmRoot) {
     return path.join(pmRoot, "runtime", EVENT_INDEX_FILENAME);
 }
-async function readAuthoritativeHistoryEvents(pmRoot) {
+function historyEventIndexInvalidationDirectory(pmRoot) {
+    return path.join(pmRoot, "runtime", HISTORY_EVENT_INDEX_INVALIDATION_DIRECTORY);
+}
+async function listHistoryEventIndexInvalidations(pmRoot) {
+    const entries = await fs
+        .readdir(historyEventIndexInvalidationDirectory(pmRoot))
+        .catch((error) => {
+        if (isFileMissingError(error))
+            return [];
+        throw error;
+    });
+    return {
+        pending: entries.filter((name) => name.endsWith(".pending")).sort(),
+        committed: entries.filter((name) => name.endsWith(".committed")).sort(),
+    };
+}
+/** Remove only pending markers proven abandoned by the caller's invalidation-lock ownership. */
+async function recoverAbandonedHistoryEventIndexInvalidations(pmRoot) {
+    const invalidations = await listHistoryEventIndexInvalidations(pmRoot);
+    const pending = (await Promise.all(invalidations.pending.map(async (name) => {
+        const owner = /^(\d+)-(unknown|\d+)-(\d+)-.+\.pending$/u.exec(name);
+        if (owner !== null) {
+            const processStartIdentity = owner[2];
+            if (await isProcessIdentityAlive({
+                pid: Number(owner[1]),
+                ...(processStartIdentity === "unknown"
+                    ? {}
+                    : { process_start_identity: processStartIdentity }),
+            }, Math.max(0, Date.now() - Number(owner[3])), HISTORY_EVENT_INDEX_INVALIDATION_MAX_UNVERIFIED_AGE_MS)) {
+                return name;
+            }
+        }
+        await fs.rm(path.join(historyEventIndexInvalidationDirectory(pmRoot), name), {
+            force: true,
+        });
+        return null;
+    }))).filter((name) => name !== null);
+    return { pending, committed: invalidations.committed };
+}
+async function withHistoryEventIndexInvalidationLock(pmRoot, operation) {
+    const release = await acquireLock(pmRoot, HISTORY_EVENT_INDEX_INVALIDATION_LOCK_ID, HISTORY_EVENT_INDEX_LOCK_TTL_SECONDS, `history-event-index-invalidation:${process.pid}`, false, false, HISTORY_EVENT_INDEX_LOCK_WAIT_MS);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
+async function beginHistoryEventIndexInvalidation(pmRoot) {
+    const directory = historyEventIndexInvalidationDirectory(pmRoot);
+    await fs.mkdir(directory, { recursive: true });
+    const token = randomUUID();
+    const processIdentity = await captureProcessIdentity();
+    const pendingPath = path.join(directory, `${processIdentity.pid}-${processIdentity.process_start_identity ?? "unknown"}-${Date.now()}-${token}.pending`);
+    await fs.writeFile(pendingPath, "pending\n", { flag: "wx" });
+    return {
+        pendingPath,
+        committedPath: path.join(directory, `${token}.committed`),
+    };
+}
+function sameInvalidationNames(left, right) {
+    return (left.length === right.length &&
+        left.every((name, index) => name === right[index]));
+}
+async function invalidateHistoryEventIndex(pmRoot) {
+    try {
+        await fs.rm(eventIndexPath(pmRoot), { force: true });
+    }
+    catch {
+        // The authoritative append already committed. A retained projection remains
+        // unusable because its recorded stream byte size no longer matches authority.
+    }
+}
+async function withHistoryEventIndexLock(pmRoot, operation) {
+    const release = await acquireLock(pmRoot, HISTORY_EVENT_INDEX_LOCK_ID, HISTORY_EVENT_INDEX_LOCK_TTL_SECONDS, `history-event-index:${process.pid}`, false, false, HISTORY_EVENT_INDEX_LOCK_WAIT_MS);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
+async function readAuthoritativeHistorySnapshot(pmRoot) {
     const historyRoot = path.join(pmRoot, "history");
     const entries = await fs
         .readdir(historyRoot, { withFileTypes: true })
@@ -53,9 +148,10 @@ async function readAuthoritativeHistoryEvents(pmRoot) {
         ].join(":");
         if (cached.streams.get(streamId)?.signature === signature)
             continue;
-        const history = await readHistoryEntries(historyPath, streamId);
+        const history = await readIndexableHistoryEntries(historyPath, streamId);
         cached.streams.set(streamId, {
             signature,
+            byte_size: Number(stats.size),
             events: history.map((entry, streamOffset) => ({
                 stream_id: streamId,
                 stream_offset: streamOffset,
@@ -81,7 +177,29 @@ async function readAuthoritativeHistoryEvents(pmRoot) {
         const oldestRoot = authoritativeHistoryCaches.keys().next().value;
         authoritativeHistoryCaches.delete(oldestRoot);
     }
-    return cached.ordered_events;
+    return {
+        events: cached.ordered_events,
+        stream_byte_sizes: new Map([...cached.streams].map(([streamId, stream]) => [
+            streamId,
+            stream.byte_size,
+        ])),
+    };
+}
+async function readIndexableHistoryEntries(historyPath, streamId) {
+    const entries = await readHistoryEntries(historyPath, streamId);
+    for (const [index, entry] of entries.entries()) {
+        if (typeof entry.ts !== "string" ||
+            !isMillisecondPrecisionRfc3339DateTime(entry.ts.trim())) {
+            throw new PmCliError(`History for ${streamId} contains an invalid or sub-millisecond timestamp at line ${index + 1}. Repair or restore the history stream and retry.`, EXIT_CODE.GENERIC_FAILURE, { code: "history_timestamp_invalid" });
+        }
+    }
+    return entries.map((entry) => ({
+        ...entry,
+        ts: new Date(entry.ts.trim()).toISOString(),
+    }));
+}
+async function readAuthoritativeHistoryEvents(pmRoot) {
+    return (await readAuthoritativeHistorySnapshot(pmRoot)).events;
 }
 function loadDatabaseSync(loadModule) {
     try {
@@ -121,13 +239,20 @@ function createSchema(database) {
       agent_harness TEXT,
       agent_instance TEXT,
       op TEXT NOT NULL,
+      event_class TEXT NOT NULL CHECK(event_class IN ('substantive', 'maintenance')),
       entry_json TEXT NOT NULL,
       PRIMARY KEY(stream_id, stream_offset)
     ) STRICT;
+    CREATE TABLE streams (
+      stream_id TEXT PRIMARY KEY,
+      byte_size INTEGER NOT NULL CHECK(byte_size >= 0)
+    ) STRICT;
     CREATE INDEX events_order
       ON events(ts, stream_id, stream_offset);
     CREATE INDEX events_op_order
       ON events(op, ts, stream_id, stream_offset);
+    CREATE INDEX events_class_stream_order
+      ON events(event_class, stream_id, ts, stream_offset);
     CREATE INDEX events_author_order
       ON events(author, ts, stream_id, stream_offset);
     CREATE INDEX events_harness_order
@@ -140,41 +265,92 @@ function createSchema(database) {
         .run(EVENT_INDEX_VERSION);
 }
 function insertEvent(database, event) {
+    const entry = {
+        ...event.entry,
+        ts: new Date(event.entry.ts.trim()).toISOString(),
+    };
     database
         .prepare(`INSERT INTO events(
         stream_id, stream_offset, ts, author, agent_harness,
-        agent_instance, op, entry_json
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(event.stream_id, event.stream_offset, event.entry.ts, event.entry.author, event.entry.agent_harness ?? null, event.entry.agent_instance ?? null, event.entry.op, JSON.stringify(event.entry));
+        agent_instance, op, event_class, entry_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(event.stream_id, event.stream_offset, entry.ts, entry.author, entry.agent_harness ?? null, entry.agent_instance ?? null, entry.op, classifyHistoryEvent(entry), JSON.stringify(entry));
+}
+function parseIndexedHistoryEvent(row) {
+    const entry = JSON.parse(String(row.entry_json));
+    if (typeof entry.ts !== "string" ||
+        !isMillisecondPrecisionRfc3339DateTime(entry.ts.trim())) {
+        return null;
+    }
+    return {
+        stream_id: String(row.stream_id),
+        stream_offset: Number(row.stream_offset),
+        entry: { ...entry, ts: new Date(entry.ts.trim()).toISOString() },
+    };
+}
+function upsertStreamByteSize(database, streamId, byteSize) {
+    database
+        .prepare(`INSERT INTO streams(stream_id, byte_size) VALUES (?, ?)
+       ON CONFLICT(stream_id) DO UPDATE SET byte_size = excluded.byte_size`)
+        .run(streamId, byteSize);
 }
 /** Rebuild the complete optional event projection from authoritative streams. */
 export async function rebuildHistoryEventIndex(pmRoot) {
     const Database = resolveDatabaseSync();
     if (!Database)
         return false;
-    const targetPath = eventIndexPath(pmRoot);
-    await fs.mkdir(path.dirname(targetPath), { recursive: true });
-    const temporaryPath = `${targetPath}.${randomUUID()}.tmp`;
-    let database;
-    try {
-        database = new Database(temporaryPath);
-        createSchema(database);
-        database.exec("BEGIN IMMEDIATE");
-        for (const event of await readAuthoritativeHistoryEvents(pmRoot)) {
-            insertEvent(database, event);
+    return withHistoryEventIndexLock(pmRoot, async () => {
+        let invalidations;
+        try {
+            invalidations = await withHistoryEventIndexInvalidationLock(pmRoot, () => recoverAbandonedHistoryEventIndexInvalidations(pmRoot));
         }
-        database.exec("COMMIT");
-        database.close();
-        database = undefined;
-        await fs.rm(targetPath, { force: true });
-        await fs.rename(temporaryPath, targetPath);
-        return true;
-    }
-    catch (error) {
-        database?.close();
-        await fs.rm(temporaryPath, { force: true });
-        throw error;
-    }
+        catch (error) {
+            if (error instanceof PmCliError && error.code === "lock_conflict") {
+                return false;
+            }
+            throw error;
+        }
+        if (invalidations.pending.length > 0)
+            return false;
+        const targetPath = eventIndexPath(pmRoot);
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        const temporaryPath = `${targetPath}.${randomUUID()}.tmp`;
+        let database;
+        try {
+            database = new Database(temporaryPath);
+            createSchema(database);
+            database.exec("BEGIN IMMEDIATE");
+            const authoritative = await readAuthoritativeHistorySnapshot(pmRoot);
+            for (const event of authoritative.events) {
+                insertEvent(database, event);
+            }
+            for (const [streamId, byteSize] of authoritative.stream_byte_sizes) {
+                upsertStreamByteSize(database, streamId, byteSize);
+            }
+            database.exec("COMMIT");
+            database.close();
+            database = undefined;
+            const published = await withHistoryEventIndexInvalidationLock(pmRoot, async () => {
+                const current = await recoverAbandonedHistoryEventIndexInvalidations(pmRoot);
+                if (current.pending.length > 0 ||
+                    !sameInvalidationNames(invalidations.committed, current.committed)) {
+                    return false;
+                }
+                await fs.rm(targetPath, { force: true });
+                await fs.rename(temporaryPath, targetPath);
+                await Promise.all(invalidations.committed.map((name) => fs.rm(path.join(historyEventIndexInvalidationDirectory(pmRoot), name), { force: true })));
+                return true;
+            });
+            if (!published)
+                await fs.rm(temporaryPath, { force: true });
+            return published;
+        }
+        catch (error) {
+            database?.close();
+            await fs.rm(temporaryPath, { force: true });
+            throw error;
+        }
+    });
 }
 function matchesSet(value, accepted) {
     return !accepted || accepted.length === 0 || accepted.includes(value);
@@ -184,6 +360,12 @@ function compareHistoryEventPosition(left, right) {
         left.stream_id.localeCompare(right.stream_id) ||
         left.stream_offset - right.stream_offset);
 }
+function canonicalHistoryQueryTimestamp(value) {
+    const milliseconds = Date.parse(value);
+    return Number.isFinite(milliseconds)
+        ? new Date(milliseconds).toISOString()
+        : value;
+}
 function isInsideHistoryEventWindow(event, query) {
     if (query.after_ts !== undefined &&
         query.after_stream_id !== undefined &&
@@ -191,13 +373,16 @@ function isInsideHistoryEventWindow(event, query) {
         if (compareHistoryEventPosition(event, {
             stream_id: query.after_stream_id,
             stream_offset: query.after_stream_offset,
-            entry: { ...event.entry, ts: query.after_ts },
+            entry: {
+                ...event.entry,
+                ts: canonicalHistoryQueryTimestamp(query.after_ts),
+            },
         }) <= 0) {
             return false;
         }
     }
     else if (query.since_ts !== undefined &&
-        event.entry.ts < query.since_ts) {
+        event.entry.ts < canonicalHistoryQueryTimestamp(query.since_ts)) {
         return false;
     }
     return true;
@@ -239,44 +424,116 @@ export async function queryHistoryEventStreams(pmRoot, query) {
     };
 }
 /**
- * Update an already-built event projection after one authoritative append.
- * Absence is a cheap no-op; corrupt projections are removed for lazy rebuild.
+ * Serialize an authoritative append with its optional SQLite projection.
+ * The database write lock spans the file append and size capture, so compliant
+ * cross-process writers cannot certify a newer stream size with older rows.
  */
-export async function updateHistoryEventIndexAfterAppend(historyPath, entry) {
+export async function appendHistoryEntryWithEventIndex(historyPath, entry, append) {
     const pmRoot = path.dirname(path.dirname(historyPath));
-    const targetPath = eventIndexPath(pmRoot);
-    try {
-        await fs.access(targetPath);
-    }
-    catch {
-        return;
-    }
     const Database = resolveDatabaseSync();
-    if (!Database)
+    if (!Database) {
+        await append();
         return;
-    let database;
+    }
+    let authoritativeAppendCommitted = false;
     try {
-        database = new Database(targetPath);
-        const version = database
-            .prepare("SELECT value FROM metadata WHERE key = 'version'")
-            .get();
-        if (version?.value !== EVENT_INDEX_VERSION) {
-            throw new TypeError("Unsupported history event index version");
-        }
-        const streamId = path.basename(historyPath, ".jsonl");
-        const offset = database
-            .prepare("SELECT COALESCE(MAX(stream_offset), -1) + 1 AS value FROM events WHERE stream_id = ?")
-            .get(streamId);
-        insertEvent(database, {
-            stream_id: streamId,
-            stream_offset: Number(offset.value),
-            entry,
+        await withHistoryEventIndexLock(pmRoot, async () => {
+            const targetPath = eventIndexPath(pmRoot);
+            try {
+                await fs.access(targetPath);
+            }
+            catch {
+                await append();
+                return;
+            }
+            let database;
+            try {
+                database = new Database(targetPath);
+                const version = database
+                    .prepare("SELECT value FROM metadata WHERE key = 'version'")
+                    .get();
+                if (version?.value !== EVENT_INDEX_VERSION) {
+                    throw new TypeError("Unsupported history event index version");
+                }
+            }
+            catch {
+                database?.close();
+                await fs.rm(targetPath, { force: true });
+                await append();
+                return;
+            }
+            try {
+                database.exec("PRAGMA busy_timeout = 5000");
+                database.exec("BEGIN IMMEDIATE");
+            }
+            catch (error) {
+                database.close();
+                throw error;
+            }
+            let appended = false;
+            try {
+                await append();
+                appended = true;
+                authoritativeAppendCommitted = true;
+                const streamId = path.basename(historyPath, ".jsonl");
+                const offset = database
+                    .prepare("SELECT COALESCE(MAX(stream_offset), -1) + 1 AS value FROM events WHERE stream_id = ?")
+                    .get(streamId);
+                insertEvent(database, {
+                    stream_id: streamId,
+                    stream_offset: Number(offset.value),
+                    entry,
+                });
+                upsertStreamByteSize(database, streamId, (await fs.stat(historyPath)).size);
+                database.exec("COMMIT");
+                database.close();
+            }
+            catch (error) {
+                database?.close();
+                if (!appended)
+                    throw error;
+                await invalidateHistoryEventIndex(pmRoot);
+            }
         });
-        database.close();
     }
-    catch {
-        database?.close();
-        await fs.rm(targetPath, { force: true });
+    catch (error) {
+        if (authoritativeAppendCommitted) {
+            await invalidateHistoryEventIndex(pmRoot);
+            return;
+        }
+        if (!(error instanceof PmCliError) || error.code !== "lock_conflict") {
+            throw error;
+        }
+        let pendingMarkerPath;
+        try {
+            await withHistoryEventIndexInvalidationLock(pmRoot, async () => {
+                const marker = await beginHistoryEventIndexInvalidation(pmRoot);
+                pendingMarkerPath = marker.pendingPath;
+                try {
+                    await append();
+                    authoritativeAppendCommitted = true;
+                }
+                catch (appendError) {
+                    await fs.rm(marker.pendingPath, { force: true });
+                    throw appendError;
+                }
+                await fs.rename(marker.pendingPath, marker.committedPath);
+                await invalidateHistoryEventIndex(pmRoot);
+            });
+        }
+        catch (fallbackError) {
+            if (authoritativeAppendCommitted) {
+                await invalidateHistoryEventIndex(pmRoot);
+                try {
+                    await fs.rm(pendingMarkerPath, { force: true });
+                }
+                catch {
+                    // The authoritative append is durable; marker cleanup is best effort.
+                }
+                return;
+            }
+            throw fallbackError;
+        }
     }
 }
 /** Invalidate the optional event projection after a non-append rewrite. */
@@ -315,11 +572,12 @@ export async function queryHistoryEventIndex(pmRoot, query) {
         query.after_stream_id !== undefined &&
         query.after_stream_offset !== undefined) {
         clauses.push("(ts > ? OR (ts = ? AND stream_id > ?) OR (ts = ? AND stream_id = ? AND stream_offset > ?))");
-        parameters.push(query.after_ts, query.after_ts, query.after_stream_id, query.after_ts, query.after_stream_id, query.after_stream_offset);
+        const afterTimestamp = canonicalHistoryQueryTimestamp(query.after_ts);
+        parameters.push(afterTimestamp, afterTimestamp, query.after_stream_id, afterTimestamp, query.after_stream_id, query.after_stream_offset);
     }
     else if (query.since_ts !== undefined) {
         clauses.push("ts >= ?");
-        parameters.push(query.since_ts);
+        parameters.push(canonicalHistoryQueryTimestamp(query.since_ts));
     }
     appendSetPredicate(clauses, parameters, "op", query.ops);
     appendSetPredicate(clauses, parameters, "author", query.authors);
@@ -333,36 +591,233 @@ export async function queryHistoryEventIndex(pmRoot, query) {
     const where = clauses.length === 0 ? "" : ` WHERE ${clauses.join(" AND ")}`;
     let database;
     try {
-        database = new Database(eventIndexPath(pmRoot), { readOnly: true });
-        const version = database
-            .prepare("SELECT value FROM metadata WHERE key = 'version'")
-            .get();
-        if (version?.value !== EVENT_INDEX_VERSION) {
-            database.close();
-            return null;
-        }
-        const rows = database
-            .prepare(`SELECT stream_id, stream_offset, entry_json
-         FROM events${where}
-         ORDER BY ts, stream_id, stream_offset
-         LIMIT ?`)
-            .all(...parameters, Math.max(0, Math.floor(query.limit)) + 1);
-        const hasMore = rows.length > query.limit;
-        const events = rows.slice(0, query.limit).map((row) => ({
-            stream_id: String(row.stream_id),
-            stream_offset: Number(row.stream_offset),
-            entry: JSON.parse(String(row.entry_json)),
-        }));
-        database.close();
-        return { events, has_more: hasMore };
+        return await withHistoryEventIndexLock(pmRoot, async () => {
+            return withHistoryEventIndexInvalidationLock(pmRoot, async () => {
+                const invalidations = await recoverAbandonedHistoryEventIndexInvalidations(pmRoot);
+                if (invalidations.pending.length > 0 ||
+                    invalidations.committed.length > 0) {
+                    return null;
+                }
+                database = new Database(eventIndexPath(pmRoot), { readOnly: true });
+                const version = database
+                    .prepare("SELECT value FROM metadata WHERE key = 'version'")
+                    .get();
+                const validationStreamIds = await historyIndexValidationStreamIds(database, pmRoot, query.stream_ids);
+                if (version?.value !== EVENT_INDEX_VERSION ||
+                    !(await historyIndexMatchesStreamSizes(database, pmRoot, validationStreamIds))) {
+                    database.close();
+                    database = undefined;
+                    return null;
+                }
+                const rows = database
+                    .prepare(`SELECT stream_id, stream_offset, entry_json
+             FROM events${where}
+             ORDER BY ts, stream_id, stream_offset
+             LIMIT ?`)
+                    .all(...parameters, Math.max(0, Math.floor(query.limit)) + 1);
+                const events = rows.slice(0, query.limit).map(parseIndexedHistoryEvent);
+                database.close();
+                database = undefined;
+                return events.includes(null)
+                    ? null
+                    : {
+                        events: events,
+                        has_more: rows.length > query.limit,
+                    };
+            });
+        });
     }
     catch {
         database?.close();
         return null;
     }
 }
+function collectLatestSubstantiveEvents(events, requested) {
+    const latest = Object.create(null);
+    for (const event of events) {
+        if (!requested.has(event.stream_id) ||
+            classifyHistoryEvent(event.entry) !== "substantive") {
+            continue;
+        }
+        const current = latest[event.stream_id];
+        if (current === undefined ||
+            compareHistoryEventPosition(current, event) < 0) {
+            latest[event.stream_id] = event;
+        }
+    }
+    return latest;
+}
+async function readHistoryStreamByteSize(pmRoot, streamId) {
+    if (path.basename(streamId) !== streamId)
+        return null;
+    try {
+        return (await fs.stat(path.join(pmRoot, "history", `${streamId}.jsonl`)))
+            .size;
+    }
+    catch (error) {
+        if (isFileMissingError(error))
+            return 0;
+        throw error;
+    }
+}
+async function historyIndexMatchesStreamSizes(database, pmRoot, streamIds) {
+    for (let start = 0; start < streamIds.length; start += 500) {
+        const chunk = streamIds.slice(start, start + 500);
+        const storedSizes = new Map(database
+            .prepare(`SELECT stream_id, byte_size FROM streams
+           WHERE stream_id IN (${chunk.map(() => "?").join(", ")})`)
+            .all(...chunk)
+            .map((row) => [String(row.stream_id), Number(row.byte_size)]));
+        const currentSizes = await Promise.all(chunk.map((streamId) => readHistoryStreamByteSize(pmRoot, streamId)));
+        for (const [index, currentSize] of currentSizes.entries()) {
+            if (currentSize === null)
+                return false;
+            const streamId = chunk[index];
+            const storedSize = storedSizes.get(streamId);
+            if (currentSize === 0 && storedSize === undefined)
+                continue;
+            if (currentSize !== storedSize)
+                return false;
+        }
+    }
+    return true;
+}
+async function historyIndexValidationStreamIds(database, pmRoot, requestedStreamIds) {
+    if (requestedStreamIds && requestedStreamIds.length > 0) {
+        return [
+            ...new Set(requestedStreamIds.filter((streamId) => streamId.trim().length > 0)),
+        ];
+    }
+    const indexed = database
+        .prepare("SELECT stream_id FROM streams")
+        .all()
+        .map((row) => String(row.stream_id));
+    const authoritative = await fs
+        .readdir(path.join(pmRoot, "history"), { withFileTypes: true })
+        .then((entries) => entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => entry.name.slice(0, -".jsonl".length)))
+        .catch((error) => {
+        if (isFileMissingError(error))
+            return [];
+        throw error;
+    });
+    return [...new Set([...indexed, ...authoritative])];
+}
+async function readIndexedLatestSubstantiveEvents(Database, pmRoot, streamIds, requested) {
+    if (!Database)
+        return null;
+    let database;
+    try {
+        return await withHistoryEventIndexLock(pmRoot, async () => {
+            return withHistoryEventIndexInvalidationLock(pmRoot, async () => {
+                const invalidations = await recoverAbandonedHistoryEventIndexInvalidations(pmRoot);
+                if (invalidations.pending.length > 0 ||
+                    invalidations.committed.length > 0) {
+                    return null;
+                }
+                database = new Database(eventIndexPath(pmRoot), { readOnly: true });
+                const version = database
+                    .prepare("SELECT value FROM metadata WHERE key = 'version'")
+                    .get();
+                if (version?.value !== EVENT_INDEX_VERSION ||
+                    !(await historyIndexMatchesStreamSizes(database, pmRoot, streamIds))) {
+                    database.close();
+                    database = undefined;
+                    return null;
+                }
+                const indexed = [];
+                for (let start = 0; start < streamIds.length; start += 500) {
+                    const chunk = streamIds.slice(start, start + 500);
+                    const rows = database
+                        .prepare(`SELECT stream_id, stream_offset, entry_json
+               FROM (
+                 SELECT stream_id, stream_offset, entry_json,
+                        ROW_NUMBER() OVER (
+                          PARTITION BY stream_id
+                          ORDER BY ts DESC, stream_offset DESC
+                        ) AS recency_rank
+                 FROM events
+                 WHERE event_class = 'substantive'
+                   AND stream_id IN (${chunk.map(() => "?").join(", ")})
+               )
+               WHERE recency_rank = 1`)
+                        .all(...chunk);
+                    const parsed = rows.map(parseIndexedHistoryEvent);
+                    if (parsed.includes(null)) {
+                        database.close();
+                        database = undefined;
+                        return null;
+                    }
+                    indexed.push(...parsed);
+                }
+                database.close();
+                database = undefined;
+                return collectLatestSubstantiveEvents(indexed, requested);
+            });
+        });
+    }
+    catch (error) {
+        database?.close();
+        if (error instanceof PmCliError && error.code === "lock_conflict") {
+            return HISTORY_INDEX_LOCK_CONTENDED;
+        }
+        return null;
+    }
+}
+/**
+ * Read one latest substantive coordinate per requested stream. The optional
+ * SQLite projection is preferred; individual authoritative streams are the
+ * fail-closed fallback and remain the source of truth.
+ */
+export async function readLatestSubstantiveHistoryEvents(pmRoot, streamIds) {
+    const uniqueIds = [
+        ...new Set(streamIds.filter((id) => id.trim().length > 0 && path.basename(id) === id)),
+    ];
+    if (uniqueIds.length === 0)
+        return {};
+    const requested = new Set(uniqueIds);
+    const Database = resolveDatabaseSync();
+    const indexed = await readIndexedLatestSubstantiveEvents(Database, pmRoot, uniqueIds, requested);
+    if (indexed !== null && indexed !== HISTORY_INDEX_LOCK_CONTENDED) {
+        return indexed;
+    }
+    if (Database && indexed !== HISTORY_INDEX_LOCK_CONTENDED) {
+        try {
+            if (await rebuildHistoryEventIndex(pmRoot)) {
+                const rebuilt = await readIndexedLatestSubstantiveEvents(Database, pmRoot, uniqueIds, requested);
+                if (rebuilt !== null && rebuilt !== HISTORY_INDEX_LOCK_CONTENDED) {
+                    return rebuilt;
+                }
+            }
+        }
+        catch {
+            // A corrupt unrelated stream must not prevent requested authoritative reads.
+        }
+    }
+    const authoritative = [];
+    await Promise.all(uniqueIds.map(async (streamId) => {
+        const historyPath = path.join(pmRoot, "history", `${streamId}.jsonl`);
+        const entries = await readIndexableHistoryEntries(historyPath, streamId).catch((error) => {
+            if (error instanceof PmCliError &&
+                error.code === "history_timestamp_invalid") {
+                return [];
+            }
+            throw error;
+        });
+        entries.forEach((entry, streamOffset) => {
+            authoritative.push({
+                stream_id: streamId,
+                stream_offset: streamOffset,
+                entry,
+            });
+        });
+    }));
+    return collectLatestSubstantiveEvents(authoritative, requested);
+}
 /** Test-only dependency seam for runtimes without `node:sqlite`. */
 export const _testOnly = {
+    collectLatestSubstantiveEvents,
     loadDatabaseSync,
     loadStableDatabaseSync,
     setDatabaseSync(databaseSync) {
@@ -374,4 +829,4 @@ export const _testOnly = {
     },
 };
 //# sourceMappingURL=event-index.js.map
-//# debugId=a84b308f-7eef-535c-9531-b33b0775c651
+//# debugId=72b285a7-970e-5965-bacf-a4e0cfc5f060