@orion-agents/orion-code 0.2.2 → 0.3.1

package/dist/runtime/thread-event-store.js

@@ -8,6 +8,7 @@ const file_lock_1 = require("../services/file-lock");
 const canonical_1 = require("./protocol/canonical");
 const runtime_protocol_v1_1 = require("./protocol/runtime-protocol-v1");
 const thread_projection_1 = require("./thread-projection");
+const thread_session_index_1 = require("./thread-session-index");
 class ThreadEventStoreError extends Error {
     constructor(code, message, offset) {
         super(message);
@@ -36,6 +37,7 @@ class ThreadEventStore {
         }
         this.logPath = (0, path_1.join)(rootDir, `${threadId}.events.v1.jsonl`);
         this.projectionPath = (0, path_1.join)(rootDir, `${threadId}.projection.v1.json`);
+        this.headPath = (0, path_1.join)(rootDir, `${threadId}.head.v1.json`);
         this.compactStatePath = (0, path_1.join)(rootDir, `${threadId}.compact-state.v1.json`);
         this.compactCheckpointsDir = (0, path_1.join)(rootDir, `${threadId}.compact-checkpoints.v1`);
         this.maxLogBytes = positiveInteger(options.maxLogBytes ?? DEFAULT_MAX_LOG_BYTES, 'maxLogBytes');
@@ -44,6 +46,7 @@ class ThreadEventStore {
         this.clock = options.clock ?? Date.now;
         this.idFactory = options.idFactory ?? runtime_protocol_v1_1.createRuntimeId;
         this.onBoundary = options.onBoundary;
+        this.onLogScan = options.onLogScan;
     }
     appendDurable(input) {
         return this.appendDurableBatch([input]).events[0];
@@ -54,13 +57,13 @@ class ThreadEventStore {
         }
         const commit = this.withLogLock(() => {
             ensurePrivateDirectory(this.rootDir);
-            const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
-            if (scan.discardedTailBytes > 0)
-                (0, fs_1.truncateSync)(this.logPath, scan.safeByteLength);
-            let seq = scan.events.length;
-            let previousHash = scan.records.at(-1)?.hash ?? null;
+            const head = this.loadVerifiedHead();
+            if (head.discardedTailBytes > 0)
+                (0, fs_1.truncateSync)(this.logPath, head.safeByteLength);
+            let seq = head.projection.cursor;
+            let previousHash = head.lastRecordHash;
             const records = [];
-            const eventIds = new Set(scan.events.map(event => event.eventId));
+            const eventIds = new Set(head.eventIdSet);
             for (const input of inputs) {
                 seq += 1;
                 const eventId = this.idFactory();
@@ -85,10 +88,12 @@ class ThreadEventStore {
                 records.push({ version: 1, previousHash, hash, event });
                 previousHash = hash;
             }
-            // Validate the complete lifecycle before a byte becomes durable. A bad
-            // duplicate terminal event must never poison the append-only fact log.
-            const allEvents = [...scan.events, ...records.map(record => record.event)];
-            const projection = (0, thread_projection_1.projectThreadEvents)(this.threadId, allEvents);
+            // Validate the new tail against the already verified projection before a
+            // byte becomes durable. Historical lifecycle facts were validated when
+            // cachedHead was established and are invalidated by any log fingerprint
+            // change, so append cost no longer grows with Session age.
+            const committedEvents = records.map(record => record.event);
+            const projection = (0, thread_projection_1.advanceThreadProjection)(head.projection, committedEvents);
             this.boundary('before_log_write', seq);
             appendRecordsAndFlush(this.logPath, records, () => this.boundary('after_log_write', seq));
             // appendRecordsAndFlush fsyncs before returning; this boundary is the
@@ -99,7 +104,48 @@ class ThreadEventStore {
             writeProjection(this.projectionPath, projection);
             fsyncDirectory(this.rootDir);
             this.boundary('after_projection_write', seq);
-            return deepFreeze({ events: records.map(record => record.event), projection });
+            const nextLogIdentity = readFileIdentity(this.logPath);
+            const safeByteLength = nextLogIdentity.bytes;
+            const nextScan = head.scan
+                ? {
+                    records: [...head.scan.records, ...records],
+                    events: [...head.scan.events, ...committedEvents],
+                    safeByteLength,
+                    discardedTailBytes: 0,
+                }
+                : undefined;
+            const nextHead = {
+                generation: head.generation + 1,
+                logFingerprint: nextLogIdentity.fingerprint,
+                log: storedLogIdentity(nextLogIdentity),
+                projectionFingerprint: fileFingerprint(this.projectionPath),
+                ...(nextScan ? { scan: nextScan } : {}),
+                projection,
+                lastEventTimestamp: committedEvents.at(-1)?.timestamp ?? head.lastEventTimestamp,
+                lastRecordHash: previousHash,
+                safeByteLength,
+                discardedTailBytes: 0,
+                eventIds: [...eventIds],
+                eventIdSet: eventIds,
+                verifiedPrefixes: head.verifiedPrefixes,
+            };
+            this.cachedHead = nextHead;
+            this.tryPersistVerifiedHead(nextHead);
+            try {
+                (0, thread_session_index_1.advanceThreadSessionIndexV1)({
+                    rootDir: this.rootDir,
+                    threadId: this.threadId,
+                    previousHead: sessionIndexHead(head),
+                    nextHead: sessionIndexHead(nextHead),
+                    projection,
+                    committedEvents,
+                });
+            }
+            catch {
+                // The immutable transcript index is derived. A stale manifest forces
+                // a verified rebuild on the next snapshot and cannot veto the fact.
+            }
+            return deepFreeze({ events: committedEvents, projection });
         });
         this.notifyCommitted(commit.events);
         return commit;
@@ -135,7 +181,7 @@ class ThreadEventStore {
             throw new ThreadEventStoreError('ORION_THREAD_EVENT_LIMIT', `Replay limit ${safeLimit} exceeds ${this.maxReplayEvents}`);
         }
         return this.withLogLock(() => {
-            const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
+            const scan = requireVerifiedScan(this.loadVerifiedHead(true));
             const lastSeq = scan.events.length;
             if (cursor > lastSeq) {
                 throw new ThreadEventStoreError('ORION_THREAD_EVENT_CURSOR', `Replay cursor ${cursor} is ahead of durable cursor ${lastSeq}`);
@@ -150,24 +196,134 @@ class ThreadEventStore {
             });
         });
     }
+    /**
+     * Verify and seal an immutable imported prefix. The first call may scan the
+     * authoritative log; later processes reuse the prefix receipt while the
+     * exact log identity/projection checkpoint remains current. Internal append
+     * carries the proof forward because the hash-chained prefix cannot change.
+     */
+    verifyDurablePrefix(cursor, eventDigest, projectionDigest) {
+        if (!Number.isSafeInteger(cursor) ||
+            cursor <= 0 ||
+            !isSha256(eventDigest) ||
+            !isSha256(projectionDigest)) {
+            return false;
+        }
+        return this.withLogLock(() => {
+            let head = this.loadVerifiedHead();
+            if (cursor > head.projection.cursor)
+                return false;
+            const expected = { cursor, eventDigest, projectionDigest };
+            if (head.verifiedPrefixes.some(prefix => sameVerifiedPrefix(prefix, expected)))
+                return true;
+            head = this.loadVerifiedHead(true);
+            const scan = requireVerifiedScan(head);
+            const events = scan.events.slice(0, cursor);
+            if (events.length !== cursor ||
+                (0, canonical_1.digestRuntimeValue)(events) !== eventDigest ||
+                (0, thread_projection_1.projectThreadEvents)(this.threadId, events).digest !== projectionDigest) {
+                return false;
+            }
+            const next = {
+                ...head,
+                generation: head.generation + 1,
+                verifiedPrefixes: [...head.verifiedPrefixes, expected].sort((left, right) => left.cursor - right.cursor),
+            };
+            this.cachedHead = next;
+            this.tryPersistVerifiedHead(next);
+            return true;
+        });
+    }
     getCursor() {
-        return this.withLogLock(() => scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes).events.length);
+        const cached = this.cachedHead;
+        if (cached && cached.logFingerprint === fileFingerprint(this.logPath)) {
+            return cached.projection.cursor;
+        }
+        return this.withLogLock(() => this.loadVerifiedHead().projection.cursor);
+    }
+    /**
+     * Read the compact persisted receipt without parsing the potentially large
+     * projection. Callers must fall back to the authoritative scan whenever the
+     * receipt is missing, stale, or lacks their required cutover proof.
+     */
+    capturePersistedCheckpointHead() {
+        return this.withLogLock(() => {
+            const identity = readFileIdentity(this.logPath);
+            const cached = this.cachedHead;
+            if (cached?.logFingerprint === identity.fingerprint) {
+                return checkpointHead(cached);
+            }
+            const stored = readStoredThreadHead(this.headPath, this.threadId);
+            if (!stored ||
+                !sameStoredLogIdentity(stored.log, identity) ||
+                stored.safeByteLength + stored.discardedTailBytes !== identity.bytes) {
+                return undefined;
+            }
+            return deepFreeze({
+                cursor: stored.cursor,
+                projectionDigest: stored.projectionDigest,
+                lastEventTimestamp: stored.lastEventTimestamp,
+                lastRecordHash: stored.lastRecordHash,
+                log: { ...stored.log },
+                verifiedPrefixes: stored.verifiedPrefixes.map(prefix => ({ ...prefix })),
+            });
+        });
+    }
+    /** Capture the catalog read model and its exact verified log identity atomically. */
+    captureReadModelHead() {
+        return this.withLogLock(() => {
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+                const head = this.loadVerifiedHead();
+                const identity = readFileIdentity(this.logPath);
+                if (identity.fingerprint !== head.logFingerprint) {
+                    this.cachedHead = undefined;
+                    continue;
+                }
+                return deepFreeze({
+                    projection: head.projection,
+                    lastEventTimestamp: head.lastEventTimestamp,
+                    lastRecordHash: head.lastRecordHash,
+                    log: {
+                        bytes: identity.bytes,
+                        device: identity.device,
+                        inode: identity.inode,
+                        mtimeNs: identity.mtimeNs,
+                        ctimeNs: identity.ctimeNs,
+                    },
+                });
+            }
+            throw corrupt('Thread event log changed while capturing its read model', 0);
+        });
     }
     loadProjection() {
         return this.withLogLock(() => {
             ensurePrivateDirectory(this.rootDir);
-            const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
-            const replayed = (0, thread_projection_1.projectThreadEvents)(this.threadId, scan.events);
+            const head = this.loadVerifiedHead();
+            const replayed = head.projection;
+            const projectionFingerprint = fileFingerprint(this.projectionPath);
+            if (head.projectionFingerprint === projectionFingerprint) {
+                this.tryPersistVerifiedHead(head);
+                return replayed;
+            }
             const cached = readProjection(this.projectionPath);
             if (cached &&
                 cached.threadId === this.threadId &&
                 cached.cursor === replayed.cursor &&
                 cached.digest === replayed.digest &&
                 (0, thread_projection_1.verifyThreadProjectionDigest)(cached)) {
-                return deepFreeze(cached);
+                const current = { ...head, projectionFingerprint };
+                this.cachedHead = current;
+                this.tryPersistVerifiedHead(current);
+                return replayed;
             }
             writeProjection(this.projectionPath, replayed);
             fsyncDirectory(this.rootDir);
+            const current = {
+                ...head,
+                projectionFingerprint: fileFingerprint(this.projectionPath),
+            };
+            this.cachedHead = current;
+            this.tryPersistVerifiedHead(current);
             return replayed;
         });
     }
@@ -177,7 +333,7 @@ class ThreadEventStore {
      */
     loadAuthoritativeModelHistory() {
         return this.withLogLock(() => {
-            const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
+            const scan = requireVerifiedScan(this.loadVerifiedHead(true));
             const state = readCompactState(this.compactStatePath, this.threadId);
             if (state)
                 this.assertCompactCheckpoint(state);
@@ -194,8 +350,9 @@ class ThreadEventStore {
     captureCompactSource(turnId) {
         return this.withLogLock(() => {
             ensurePrivateDirectory(this.rootDir);
-            const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
-            const projection = (0, thread_projection_1.projectThreadEvents)(this.threadId, scan.events);
+            const head = this.loadVerifiedHead(true);
+            const scan = requireVerifiedScan(head);
+            const { projection } = head;
             assertActiveMaintenanceTurn(projection, turnId);
             const state = readCompactState(this.compactStatePath, this.threadId);
             if (state)
@@ -230,8 +387,9 @@ class ThreadEventStore {
             ensurePrivateDirectory(this.compactCheckpointsDir);
             validateCompactCommitInput(input, this.threadId);
             input.onBoundary('before_cas_recheck');
-            const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
-            const projection = (0, thread_projection_1.projectThreadEvents)(this.threadId, scan.events);
+            const head = this.loadVerifiedHead(true);
+            const scan = requireVerifiedScan(head);
+            const { projection } = head;
             const eventsAfterAnchor = scan.events.slice(input.expectedEventAnchor.cursor);
             const onlyQueuedFollowUps = eventsAfterAnchor.length > 0 &&
                 eventsAfterAnchor.every(event => event.payload.type === 'turn.queued');
@@ -296,7 +454,7 @@ class ThreadEventStore {
     }
     listCompactEvents() {
         return this.withLogLock(() => {
-            const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
+            const scan = requireVerifiedScan(this.loadVerifiedHead(true));
             return deepFreeze(scan.events.filter((event) => event.payload.type === 'compact.started' ||
                 event.payload.type === 'compact.completed' ||
                 event.payload.type === 'compact.failed'));
@@ -347,6 +505,79 @@ class ThreadEventStore {
         }
         return inputs.length > 0 ? this.appendDurableBatch(inputs).projection : projection;
     }
+    /**
+     * Return the last verified log head. A fresh process may adopt the persisted
+     * receipt only when the exact JSONL identity and independently validated
+     * projection still match. Callers that need historical events explicitly
+     * request a scan; cursor/projection/append paths stay O(head + projection).
+     */
+    loadVerifiedHead(requireScan = false) {
+        ensurePrivateDirectory(this.rootDir);
+        const logIdentity = readFileIdentity(this.logPath);
+        if (this.cachedHead?.logFingerprint === logIdentity.fingerprint &&
+            (!requireScan || this.cachedHead.scan)) {
+            return this.cachedHead;
+        }
+        const stored = readStoredThreadHead(this.headPath, this.threadId);
+        if (!requireScan && stored) {
+            const projection = readProjection(this.projectionPath);
+            const persisted = hydratePersistedThreadHead(stored, logIdentity, projection, fileFingerprint(this.projectionPath));
+            if (persisted) {
+                this.cachedHead = persisted;
+                return persisted;
+            }
+        }
+        const scan = scanThreadEventLog(this.logPath, this.threadId, this.maxLogBytes);
+        this.onLogScan?.({
+            threadId: this.threadId,
+            bytes: scan.safeByteLength + scan.discardedTailBytes,
+            events: scan.events.length,
+        });
+        const projection = (0, thread_projection_1.projectThreadEvents)(this.threadId, scan.events);
+        const eventIds = scan.events.map(event => event.eventId);
+        const projectionFingerprint = projectionFileMatches(this.projectionPath, projection)
+            ? fileFingerprint(this.projectionPath)
+            : undefined;
+        const head = {
+            generation: (stored?.generation ?? 0) + 1,
+            logFingerprint: logIdentity.fingerprint,
+            log: storedLogIdentity(logIdentity),
+            ...(projectionFingerprint ? { projectionFingerprint } : {}),
+            scan,
+            projection,
+            lastEventTimestamp: scan.events.at(-1)?.timestamp ?? 0,
+            lastRecordHash: scan.records.at(-1)?.hash ?? null,
+            safeByteLength: scan.safeByteLength,
+            discardedTailBytes: scan.discardedTailBytes,
+            eventIds,
+            eventIdSet: new Set(eventIds),
+            verifiedPrefixes: retainVerifiedPrefixes(stored?.verifiedPrefixes ?? [], scan, this.threadId),
+        };
+        this.cachedHead = head;
+        if (projectionFingerprint)
+            this.tryPersistVerifiedHead(head);
+        return head;
+    }
+    tryPersistVerifiedHead(head) {
+        try {
+            const logIdentity = readFileIdentity(this.logPath);
+            if (logIdentity.fingerprint !== head.logFingerprint)
+                return;
+            if (!projectionFileMatches(this.projectionPath, head.projection))
+                return;
+            const stored = createStoredThreadHead(head, logIdentity);
+            (0, atomic_write_1.atomicWriteFileSync)(this.headPath, `${(0, canonical_1.canonicalRuntimeJson)(stored)}\n`, {
+                mode: 0o600,
+                fsync: true,
+            });
+            fsyncDirectory(this.rootDir);
+        }
+        catch {
+            // The JSONL fact and projection are already durable. A missing/stale
+            // derived head merely makes the next process take the full verification
+            // path; it must never turn a committed fact into a reported failure.
+        }
+    }
     withLogLock(operation) {
         ensurePrivateDirectory((0, path_1.dirname)(this.logPath));
         return (0, file_lock_1.withFileLockSync)(this.logPath, operation, { waitMs: this.lockWaitMs });
@@ -497,6 +728,209 @@ function readProjection(path) {
         return null;
     }
 }
+function projectionFileMatches(path, expected) {
+    const projection = readProjection(path);
+    return Boolean(projection &&
+        projection.threadId === expected.threadId &&
+        projection.cursor === expected.cursor &&
+        projection.digest === expected.digest &&
+        (0, thread_projection_1.verifyThreadProjectionDigest)(projection));
+}
+function readStoredThreadHead(path, threadId) {
+    if (!(0, fs_1.existsSync)(path))
+        return null;
+    try {
+        const value = JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+        if (!isRecord(value))
+            return null;
+        const { digest: _digest, ...content } = value;
+        void _digest;
+        if (value.version !== 1 ||
+            value.threadId !== threadId ||
+            !Number.isSafeInteger(value.generation) ||
+            value.generation < 1 ||
+            !Number.isSafeInteger(value.cursor) ||
+            value.cursor < 0 ||
+            typeof value.projectionDigest !== 'string' ||
+            !Number.isSafeInteger(value.lastEventTimestamp) ||
+            value.lastEventTimestamp < 0 ||
+            (value.lastRecordHash !== null && !isSha256(value.lastRecordHash)) ||
+            !Number.isSafeInteger(value.safeByteLength) ||
+            value.safeByteLength < 0 ||
+            !Number.isSafeInteger(value.discardedTailBytes) ||
+            value.discardedTailBytes < 0 ||
+            !Array.isArray(value.eventIds) ||
+            !Array.isArray(value.verifiedPrefixes) ||
+            value.verifiedPrefixes.length > 32 ||
+            !isStoredLogIdentity(value.log) ||
+            typeof value.digest !== 'string' ||
+            (0, canonical_1.digestRuntimeValue)(content) !== value.digest) {
+            return null;
+        }
+        const eventIds = value.eventIds;
+        if (eventIds.length !== value.cursor ||
+            eventIds.some(eventId => typeof eventId !== 'string' || !(0, runtime_protocol_v1_1.isRuntimeId)(eventId)) ||
+            new Set(eventIds).size !== eventIds.length ||
+            (value.cursor === 0) !== (value.lastRecordHash === null) ||
+            (value.cursor === 0 && value.lastEventTimestamp !== 0)) {
+            return null;
+        }
+        const prefixes = value.verifiedPrefixes;
+        if (prefixes.some(prefix => !isStoredVerifiedPrefix(prefix, value.cursor)) ||
+            new Set(prefixes.map(prefix => prefix.cursor)).size !==
+                prefixes.length) {
+            return null;
+        }
+        return deepFreeze(value);
+    }
+    catch {
+        return null;
+    }
+}
+function hydratePersistedThreadHead(stored, logIdentity, projection, projectionFingerprint) {
+    if (!sameStoredLogIdentity(stored.log, logIdentity) ||
+        stored.safeByteLength + stored.discardedTailBytes !== logIdentity.bytes ||
+        !projection ||
+        projection.threadId !== stored.threadId ||
+        projection.cursor !== stored.cursor ||
+        projection.digest !== stored.projectionDigest ||
+        !(0, thread_projection_1.verifyThreadProjectionDigest)(projection)) {
+        return null;
+    }
+    const eventIds = [...stored.eventIds];
+    return {
+        generation: stored.generation,
+        logFingerprint: logIdentity.fingerprint,
+        log: storedLogIdentity(logIdentity),
+        projectionFingerprint,
+        projection,
+        lastEventTimestamp: stored.lastEventTimestamp,
+        lastRecordHash: stored.lastRecordHash,
+        safeByteLength: stored.safeByteLength,
+        discardedTailBytes: stored.discardedTailBytes,
+        eventIds,
+        eventIdSet: new Set(eventIds),
+        verifiedPrefixes: stored.verifiedPrefixes.map(prefix => ({ ...prefix })),
+    };
+}
+function createStoredThreadHead(head, logIdentity) {
+    const content = {
+        version: 1,
+        generation: head.generation,
+        threadId: head.projection.threadId,
+        cursor: head.projection.cursor,
+        projectionDigest: head.projection.digest,
+        lastEventTimestamp: head.lastEventTimestamp,
+        lastRecordHash: head.lastRecordHash,
+        safeByteLength: head.safeByteLength,
+        discardedTailBytes: head.discardedTailBytes,
+        eventIds: [...head.eventIds],
+        verifiedPrefixes: head.verifiedPrefixes.map(prefix => ({ ...prefix })),
+        log: storedLogIdentity(logIdentity),
+    };
+    return deepFreeze({ ...content, digest: (0, canonical_1.digestRuntimeValue)(content) });
+}
+function retainVerifiedPrefixes(prefixes, scan, threadId) {
+    return prefixes.filter(prefix => {
+        if (prefix.cursor > scan.events.length)
+            return false;
+        const events = scan.events.slice(0, prefix.cursor);
+        return ((0, canonical_1.digestRuntimeValue)(events) === prefix.eventDigest &&
+            (0, thread_projection_1.projectThreadEvents)(threadId, events).digest === prefix.projectionDigest);
+    });
+}
+function requireVerifiedScan(head) {
+    if (!head.scan)
+        throw new Error('Thread event history was not loaded');
+    return head.scan;
+}
+function sessionIndexHead(head) {
+    return {
+        cursor: head.projection.cursor,
+        projectionDigest: head.projection.digest,
+        lastEventTimestamp: head.lastEventTimestamp,
+        lastRecordHash: head.lastRecordHash,
+        log: head.log,
+    };
+}
+function checkpointHead(head) {
+    return deepFreeze({
+        cursor: head.projection.cursor,
+        projectionDigest: head.projection.digest,
+        lastEventTimestamp: head.lastEventTimestamp,
+        lastRecordHash: head.lastRecordHash,
+        log: { ...head.log },
+        verifiedPrefixes: head.verifiedPrefixes.map(prefix => ({ ...prefix })),
+    });
+}
+function isStoredVerifiedPrefix(value, headCursor) {
+    return (isRecord(value) &&
+        Number.isSafeInteger(value.cursor) &&
+        value.cursor > 0 &&
+        value.cursor <= headCursor &&
+        isSha256(value.eventDigest) &&
+        isSha256(value.projectionDigest));
+}
+function sameVerifiedPrefix(left, right) {
+    return (left.cursor === right.cursor &&
+        left.eventDigest === right.eventDigest &&
+        left.projectionDigest === right.projectionDigest);
+}
+function isStoredLogIdentity(value) {
+    return (isRecord(value) &&
+        Number.isSafeInteger(value.bytes) &&
+        value.bytes >= 0 &&
+        ['device', 'inode', 'mtimeNs', 'ctimeNs'].every(key => typeof value[key] === 'string' && /^\d+$/.test(value[key])));
+}
+function sameStoredLogIdentity(stored, current) {
+    return (stored.bytes === current.bytes &&
+        stored.device === current.device &&
+        stored.inode === current.inode &&
+        stored.mtimeNs === current.mtimeNs &&
+        stored.ctimeNs === current.ctimeNs);
+}
+function storedLogIdentity(identity) {
+    return {
+        bytes: identity.bytes,
+        device: identity.device,
+        inode: identity.inode,
+        mtimeNs: identity.mtimeNs,
+        ctimeNs: identity.ctimeNs,
+    };
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+}
+function readFileIdentity(path) {
+    try {
+        const stats = (0, fs_1.statSync)(path, { bigint: true });
+        const device = stats.dev.toString();
+        const inode = stats.ino.toString();
+        const mtimeNs = stats.mtimeNs.toString();
+        const ctimeNs = stats.ctimeNs.toString();
+        return {
+            fingerprint: [device, inode, stats.size, mtimeNs, ctimeNs].join(':'),
+            bytes: Number(stats.size),
+            device,
+            inode,
+            mtimeNs,
+            ctimeNs,
+        };
+    }
+    catch {
+        return {
+            fingerprint: 'missing',
+            bytes: 0,
+            device: '0',
+            inode: '0',
+            mtimeNs: '0',
+            ctimeNs: '0',
+        };
+    }
+}
+function fileFingerprint(path) {
+    return readFileIdentity(path).fingerprint;
+}
 function ensurePrivateDirectory(path) {
     (0, fs_1.mkdirSync)(path, { recursive: true, mode: 0o700 });
 }