Skip to content

Commit 46d5718

Browse files
fix(server): document identity helpers and the safe-direction race note
1 parent db8fba5 commit 46d5718

1 file changed

Lines changed: 40 additions & 8 deletions

File tree

‎apps/server/src/project/AgentSessionScanner.ts‎

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -589,7 +589,14 @@ function extractCwd(line: string): string | null {
589589
return null;
590590
}
591591

592-
/** @public Pure helper exported for regression tests; identity construction stays beside its comparison. */
592+
/**
593+
* File identity snapshot for one transcript path.
594+
*
595+
* `inodeRaw` carries the decimal `ino` so NTFS file IDs above
596+
* `Number.MAX_SAFE_INTEGER` survive; it is `null` when the raw stat failed.
597+
*
598+
* @public Pure helper exported for regression tests; identity construction stays beside its comparison.
599+
*/
593600
export function transcriptIdentity(
594601
filePath: string,
595602
stats: FileSystem.File.Info,
@@ -611,6 +618,11 @@ export function transcriptIdentity(
611618
};
612619
}
613620

621+
/**
622+
* Normalizes a stored or freshly read raw inode to a comparable string.
623+
* Anything that is not a non-empty string (missing field on pre-fix records,
624+
* failed stat) becomes `null` and falls back to the numeric check.
625+
*/
614626
function normalizeInodeRaw(value: unknown): string | null {
615627
return typeof value === "string" && value.length > 0 ? value : null;
616628
}
@@ -626,7 +638,15 @@ interface TranscriptIdentityLike {
626638
readonly birthtimeMs: number | null;
627639
}
628640

629-
/** @public Pure helper exported for regression tests; the Windows collision is decided here. */
641+
/**
642+
* Whether two identity snapshots describe the same file.
643+
*
644+
* Records written before the raw ID existed have no `inodeRaw`; they fall
645+
* back to the numeric check so they are not re-imported. When both sides
646+
* carry a raw ID (the Windows case where `inode` is `null`), it must match.
647+
*
648+
* @public Pure helper exported for regression tests; the Windows collision is decided here.
649+
*/
630650
export function sameTranscriptIdentity(
631651
left: TranscriptIdentityLike,
632652
right: TranscriptIdentityLike,
@@ -652,12 +672,7 @@ export function sameTranscriptIdentity(
652672
return true;
653673
}
654674

655-
/**
656-
* Decimal `ino` for `transcriptIdentity`, preserving NTFS file IDs above
657-
* `Number.MAX_SAFE_INTEGER` where Effect's `ino` is `None`. Returns the safe
658-
* integer as a string without extra I/O; otherwise stats the path with
659-
* bigint enabled. `null` when the file is gone or the ID is unavailable.
660-
*/
675+
/** Tagged failure for the raw bigint stat in {@link readRawInode}. */
661676
class TranscriptInodeStatError extends Schema.TaggedError<TranscriptInodeStatError>()(
662677
"TranscriptInodeStatError",
663678
{
@@ -666,6 +681,18 @@ class TranscriptInodeStatError extends Schema.TaggedError<TranscriptInodeStatErr
666681
},
667682
) {}
668683

684+
/**
685+
* Decimal `ino` for `transcriptIdentity`, preserving NTFS file IDs above
686+
* `Number.MAX_SAFE_INTEGER` where Effect's `ino` is `None`. Returns the safe
687+
* integer as a string without extra I/O; otherwise stats the path with
688+
* bigint enabled. `null` when the file is gone or the ID is unavailable.
689+
*
690+
* The raw stat is path-based while surrounding reads use the opened handle,
691+
* so a replacement racing between the two can only mix metadata from one file
692+
* with the raw ID of another. A mixed identity mismatches (a raw ID names
693+
* exactly one file), so the outcome is always the safe direction — skip or
694+
* re-read — never a false match.
695+
*/
669696
const readRawInode = (
670697
filePath: string,
671698
knownIno: Option.Option<number>,
@@ -726,6 +753,11 @@ export const make = Effect.gen(function* () {
726753
const statOption = (target: string) =>
727754
fileSystem.stat(target).pipe(Effect.asSome, Effect.orElseSucceed(Option.none));
728755

756+
/**
757+
* Builds a transcript identity snapshot, filling `inodeRaw` from the safe
758+
* numeric inode when available and from a raw bigint stat otherwise, so
759+
* large NTFS file IDs survive on Windows without extra I/O on other systems.
760+
*/
729761
const transcriptIdentityEffect = Effect.fn("AgentSessionScanner.transcriptIdentity")(function* (
730762
filePath: string,
731763
stats: FileSystem.File.Info,

0 commit comments

Comments
 (0)