@jinn-network/core 0.1.0

package/dist/evidence-adapter.js

@@ -0,0 +1,321 @@
+/**
+ * EvidencePort adapter (#1660) — a file-backed evidence store under one
+ * captures dir that (AC2) round-trips a schema-canonical `EpisodeV1` AND reads
+ * legacy `CapturedTask` captures, up-mapping them to `EpisodeV1`.
+ *
+ * Round-trip guarantee: `put` persists the schema-parsed form, so `get`
+ * returns the canonical `EpisodeV1` for what was put — not necessarily the
+ * caller's literal input. `EpisodeV1Schema` applies defaults
+ * (`distributionTags`/`redactedKeys` → `[]`, `provenance` → `'contributed'`),
+ * so a caller who omits defaulted fields reads back the canonicalized superset.
+ *
+ * Suffix discipline: written episodes are `<id>.episode.json`; legacy captures
+ * are any other `*.json`. The two never collide — the strict `CapturedTaskSchema`
+ * would reject the extra `EpisodeV1` fields, so `.episode.json` files are read
+ * back only as episodes and legacy `.json` files only as captures.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, fchmodSync, readFileSync, readdirSync, } from 'node:fs';
+import { link, lstat, open, rm, } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { EpisodeV1Schema, EpisodeV1WriteSchema } from '@jinn-network/plugin';
+import { degraded, ok, unavailable } from '@jinn-network/plugin';
+import { parseCapturedTask } from './captured-task.js';
+import { assertSafeOwner, fsyncDirectory, identityFrom, inspectRegularPath, nodeErrorCode, openVerifiedRegular, prepareEvidenceDirectory, readVerifiedText, sameIdentity, secureRegularPath, validateDirectory, } from './evidence-filesystem.js';
+import { withEvidenceStoreLock } from './evidence-store-lock.js';
+const DEFAULT_RETENTION = { policy: 'local-private', maxEpisodes: 200 };
+const EPISODE_SUFFIX = '.episode.json';
+const MAX_PORTABLE_FILENAME_BYTES = 255;
+const HASHED_EPISODE_STEM = /^episode-[a-f0-9]{64}$/;
+export function episodeFileName(id) {
+    const literalStemIsSafe = /^[A-Za-z0-9._-]+$/.test(id)
+        && id !== '.'
+        && id !== '..'
+        && !HASHED_EPISODE_STEM.test(id)
+        && Buffer.byteLength(`${id}${EPISODE_SUFFIX}`, 'utf8') <= MAX_PORTABLE_FILENAME_BYTES;
+    const stem = literalStemIsSafe
+        ? id
+        : `episode-${createHash('sha256').update(id).digest('hex')}`;
+    return `${stem}${EPISODE_SUFFIX}`;
+}
+/**
+ * Up-map a legacy `CapturedTask` to a strict `EpisodeV1`. Fail-closed:
+ * `EpisodeV1Schema.parse` throws if the up-map is wrong.
+ *
+ * Field gaps `CapturedTask` leaves that this fills: each step's discriminated
+ * `kind`, `environment.skillsLoadout` (default `[]`), `retention.policy`
+ * (from the adapter's configured retention), and `episodeId` (the sessionId).
+ */
+export function capturedTaskToEpisode(task, retention) {
+    const built = {
+        schemaVersion: 'jinn.episode.v1',
+        episodeId: task.session.sessionId,
+        session: task.session,
+        task: task.task,
+        trajectory: task.steps.map((step) => ({
+            spanId: step.spanId,
+            parentSpanId: step.parentSpanId,
+            kind: step.kind ?? stepKind(step),
+            name: step.name,
+            startTimeUnixNano: step.startTimeUnixNano,
+            endTimeUnixNano: step.endTimeUnixNano,
+            attributes: step.attributes,
+            redactedKeys: step.redactedKeys,
+        })),
+        environment: {
+            ...task.environment,
+            skillsLoadout: task.environment.skillsLoadout ?? [],
+        },
+        outcome: task.outcome,
+        cost: task.cost,
+        retention: { policy: retention.policy },
+        provenance: task.provenance,
+        ...(task.attemptGroup ? { attemptGroup: task.attemptGroup } : {}),
+    };
+    return EpisodeV1Schema.parse(built);
+}
+/**
+ * Classify a legacy step as an agent turn or a tool call. Real `CapturedTask`
+ * steps carry the capture-event convention — `jinn.capture.event.kind` is
+ * user-message/assistant-message/tool-call/tool-result/edit, with `name`
+ * falling back to `jinn.transcript.<kind>` — matching `distill-traces.ts`'s
+ * `eventKind`. User/assistant messages are `jinn.agent_turn`; everything else
+ * (tool calls/results, edits) is a `jinn.tool_call`.
+ */
+function stepKind(step) {
+    const eventKind = typeof step.attributes['jinn.capture.event.kind'] === 'string'
+        ? step.attributes['jinn.capture.event.kind']
+        : step.name;
+    return /(^|\.)(user|assistant)-message$/.test(eventKind) ? 'jinn.agent_turn' : 'jinn.tool_call';
+}
+export function createEvidenceAdapter(deps) {
+    const capturesDir = deps.capturesDir;
+    const retention = deps.retention ?? DEFAULT_RETENTION;
+    function episodePath(id) {
+        // EpisodeV1 intentionally permits opaque host ids. Safe ids retain the
+        // original filename; path-shaped or platform-unsafe ids use a stable hash
+        // that the Python fallback mirrors exactly.
+        const path = join(capturesDir, episodeFileName(id));
+        const base = resolve(capturesDir);
+        if (!resolve(path).startsWith(base + sep)) {
+            throw new Error(`unsafe episodeId (escapes captures dir): ${JSON.stringify(id)}`);
+        }
+        return path;
+    }
+    async function classifyExisting(path, episode) {
+        try {
+            const identity = inspectRegularPath(path, 'evidence episode');
+            if (!identity)
+                return 'missing';
+            const opened = openVerifiedRegular(path, 'evidence episode', identity);
+            try {
+                if (process.platform !== 'win32')
+                    fchmodSync(opened.fd, 0o600);
+                const existing = EpisodeV1Schema.parse(JSON.parse(readFileSync(opened.fd, 'utf8')));
+                return isDeepStrictEqual(existing, episode) ? 'identical' : 'collision';
+            }
+            finally {
+                closeSync(opened.fd);
+            }
+        }
+        catch (error) {
+            return nodeErrorCode(error) === 'ENOENT' ? 'missing' : 'collision';
+        }
+    }
+    async function prepareEvidenceDir() {
+        prepareEvidenceDirectory(capturesDir, 'evidence store', true);
+    }
+    /**
+     * Enforce the declared newest-`maxEpisodes` retention (#1772 rider — was
+     * declared via `retention()` but never enforced). Keeps the
+     * `maxEpisodes` episodes with the most recent `session.capturedAt`,
+     * deleting the rest. Runs after every successful write; a no-op once the
+     * dir is at or under the cap. Never throws into `put()` — pruning is
+     * hygiene, not the write contract; a failure to prune is warned and
+     * skipped, same posture as the malformed-file skip in `list()`.
+     */
+    async function pruneOldEpisodes() {
+        let files;
+        try {
+            files = readdirSync(capturesDir).filter((file) => file.endsWith(EPISODE_SUFFIX));
+        }
+        catch {
+            return;
+        }
+        if (files.length <= retention.maxEpisodes)
+            return;
+        const byRecency = files
+            .map((file) => {
+            const path = join(capturesDir, file);
+            let identity;
+            try {
+                const verified = readVerifiedText(path, 'evidence episode');
+                identity = verified.identity;
+                const episode = EpisodeV1Schema.parse(JSON.parse(verified.text));
+                return { file, capturedAt: episode.session.capturedAt, identity };
+            }
+            catch {
+                // An unparseable file sorts oldest — never preferentially retained
+                // over a valid, dated episode.
+                return { file, capturedAt: '', identity };
+            }
+        })
+            .sort((a, b) => b.capturedAt.localeCompare(a.capturedAt)
+            || a.file.localeCompare(b.file));
+        for (const { file, identity } of byRecency.slice(retention.maxEpisodes)) {
+            try {
+                if (!identity) {
+                    throw new Error('refusing to prune a source that did not pass descriptor validation');
+                }
+                const path = join(capturesDir, file);
+                secureRegularPath(path, 'evidence episode', identity);
+                await rm(path, { force: true });
+                fsyncDirectory(capturesDir);
+            }
+            catch (err) {
+                console.warn(`[evidence] failed to prune old episode ${file}: ${String(err)}`);
+            }
+        }
+    }
+    async function persistEpisode(episode) {
+        const path = episodePath(episode.episodeId);
+        const existing = await classifyExisting(path, episode);
+        if (existing === 'identical') {
+            return ok({ episodeId: episode.episodeId });
+        }
+        if (existing === 'collision') {
+            return unavailable(`evidence episodeId collision: ${episode.episodeId}`);
+        }
+        const tmp = join(capturesDir, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await open(tmp, 'wx', 0o600);
+            await handle.writeFile(JSON.stringify(episode), 'utf8');
+            if (process.platform !== 'win32')
+                await handle.chmod(0o600);
+            await handle.sync();
+            const expected = identityFrom(await handle.stat());
+            assertSafeOwner(await handle.stat(), tmp, 'evidence temp file');
+            try {
+                // A hard link atomically publishes the complete temp file without
+                // overwriting a concurrent winner at the canonical destination.
+                await link(tmp, path);
+                const [tempAfterLink, published] = await Promise.all([lstat(tmp), lstat(path)]);
+                if (!tempAfterLink.isFile()
+                    || tempAfterLink.isSymbolicLink()
+                    || !published.isFile()
+                    || published.isSymbolicLink()
+                    || !sameIdentity(identityFrom(tempAfterLink), expected)
+                    || !sameIdentity(identityFrom(published), expected)) {
+                    throw new Error(`evidence episode changed while it was being published: ${path}`);
+                }
+                assertSafeOwner(tempAfterLink, tmp, 'evidence temp file');
+                assertSafeOwner(published, path, 'evidence episode');
+                fsyncDirectory(capturesDir);
+                return ok({ episodeId: episode.episodeId });
+            }
+            catch (error) {
+                if (nodeErrorCode(error) !== 'EEXIST')
+                    throw error;
+                const raced = await classifyExisting(path, episode);
+                if (raced === 'identical') {
+                    return ok({ episodeId: episode.episodeId });
+                }
+                return unavailable(`evidence episodeId collision: ${episode.episodeId}`);
+            }
+        }
+        finally {
+            if (handle !== undefined)
+                await handle.close().catch(() => undefined);
+            await rm(tmp, { force: true });
+            fsyncDirectory(capturesDir);
+        }
+    }
+    return {
+        async put(episode) {
+            try {
+                const parsed = EpisodeV1WriteSchema.parse(episode);
+                const result = await withEvidenceStoreLock(capturesDir, async () => {
+                    await prepareEvidenceDir();
+                    const persisted = await persistEpisode(parsed);
+                    if (persisted.status === 'ok')
+                        await pruneOldEpisodes();
+                    return persisted;
+                }, async (persisted) => {
+                    if (persisted.status !== 'ok')
+                        return;
+                    try {
+                        await deps.onStoreChanged?.();
+                    }
+                    catch (error) {
+                        console.warn(`[evidence] derived index refresh failed: ${String(error)}`);
+                    }
+                });
+                return result;
+            }
+            catch (e) {
+                return unavailable(`evidence store put failed: ${String(e)}`);
+            }
+        },
+        async get(episodeId) {
+            try {
+                const path = episodePath(episodeId);
+                if (!inspectRegularPath(path, 'evidence episode'))
+                    return ok(null);
+                return ok(EpisodeV1Schema.parse(JSON.parse(readVerifiedText(path, 'evidence episode').text)));
+            }
+            catch (e) {
+                return unavailable(`evidence store get failed: ${String(e)}`);
+            }
+        },
+        async list(query = {}) {
+            try {
+                try {
+                    validateDirectory(capturesDir, 'evidence store', false);
+                }
+                catch (error) {
+                    if (nodeErrorCode(error) === 'ENOENT')
+                        return ok([]);
+                    throw error;
+                }
+                const episodes = [];
+                let unreadable = 0;
+                for (const file of readdirSync(capturesDir)) {
+                    const path = join(capturesDir, file);
+                    if (file.endsWith(EPISODE_SUFFIX)) {
+                        try {
+                            episodes.push(EpisodeV1Schema.parse(JSON.parse(readVerifiedText(path, 'evidence episode').text)));
+                        }
+                        catch (err) {
+                            unreadable += 1;
+                            console.warn(`[evidence] skipping malformed episode file ${file}: ${String(err)}`);
+                        }
+                    }
+                    else if (file.endsWith('.json')) {
+                        // A legacy CapturedTask capture — up-map it. A capture that fails
+                        // to parse or up-map is skipped (warn), never throws.
+                        try {
+                            const task = parseCapturedTask(JSON.parse(readVerifiedText(path, 'legacy evidence capture').text));
+                            episodes.push(capturedTaskToEpisode(task, retention));
+                        }
+                        catch (err) {
+                            unreadable += 1;
+                            console.warn(`[evidence] skipping malformed legacy capture ${file}: ${String(err)}`);
+                        }
+                    }
+                }
+                const value = query.limit ? episodes.slice(0, query.limit) : episodes;
+                return unreadable > 0
+                    ? degraded(`evidence list skipped ${unreadable} unreadable record(s)`, value)
+                    : ok(value);
+            }
+            catch (e) {
+                return unavailable(`evidence store list failed: ${String(e)}`);
+            }
+        },
+        async retention() {
+            return ok(retention);
+        },
+    };
+}

package/dist/evidence-filesystem.d.ts

@@ -0,0 +1,40 @@
+import { type Stats } from 'node:fs';
+export interface FileIdentity {
+    dev: number;
+    ino: number;
+    uid: number;
+    nlink: number;
+}
+export declare function nodeErrorCode(error: unknown): string | undefined;
+export declare function identityFrom(stat: Stats): FileIdentity;
+export declare function sameIdentity(left: FileIdentity, right: FileIdentity): boolean;
+export declare function assertSafeOwner(stat: Stats, path: string, label: string): void;
+export declare function assertRegularStat(stat: Stats, path: string, label: string): void;
+export declare function inspectRegularPath(path: string, label: string): FileIdentity | undefined;
+export declare function openVerifiedRegular(path: string, label: string, expected?: FileIdentity): {
+    fd: number;
+    identity: FileIdentity;
+};
+export declare function openVerifiedRegularForUpdate(path: string, label: string, expected?: FileIdentity): {
+    fd: number;
+    identity: FileIdentity;
+};
+export declare function secureRegularPath(path: string, label: string, expected?: FileIdentity): FileIdentity;
+export declare function validateDirectory(path: string, label: string, secure: boolean): FileIdentity;
+export declare function prepareEvidenceDirectory(path: string, label: string, secure: boolean): FileIdentity;
+/**
+ * Complete the one recoverable interval in no-clobber episode publication.
+ *
+ * Both writers fsync a complete private temp file, hardlink it at the
+ * canonical name, fsync the directory, and finally remove the temp alias. A
+ * process or host crash after link(2) can therefore leave exactly two names
+ * for the same inode. Under the store lock, recognize only the two writer
+ * namespaces and remove the proven temp alias. Arbitrary hardlinks remain
+ * rejected by the normal reader path.
+ */
+export declare function recoverWriterPublicationAliases(directory: string): void;
+export declare function fsyncDirectory(path: string): void;
+export declare function readVerifiedText(path: string, label: string, expected?: FileIdentity): {
+    text: string;
+    identity: FileIdentity;
+};

package/dist/evidence-filesystem.js

@@ -0,0 +1,267 @@
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+export function nodeErrorCode(error) {
+    return error && typeof error === 'object' && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+export function identityFrom(stat) {
+    return {
+        dev: stat.dev,
+        ino: stat.ino,
+        uid: stat.uid,
+        nlink: stat.nlink,
+    };
+}
+export function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+export function assertSafeOwner(stat, path, label) {
+    const uid = process.platform === 'win32' ? undefined : process.getuid?.();
+    if (uid !== undefined && stat.uid !== uid) {
+        throw new Error(`${label} must be owned by uid ${uid}: ${path}`);
+    }
+}
+export function assertRegularStat(stat, path, label) {
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error(`${label} must be a regular file, not a symlink or other file type: ${path}`);
+    }
+    if (stat.nlink !== 1) {
+        throw new Error(`${label} must not be hardlinked: ${path}`);
+    }
+    assertSafeOwner(stat, path, label);
+}
+export function inspectRegularPath(path, label) {
+    try {
+        const stat = lstatSync(path);
+        assertRegularStat(stat, path, label);
+        return identityFrom(stat);
+    }
+    catch (error) {
+        if (nodeErrorCode(error) === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function openVerifiedRegularWithFlags(path, label, flags, expected) {
+    const before = inspectRegularPath(path, label);
+    if (!before)
+        throw new Error(`${label} disappeared before it could be opened: ${path}`);
+    if (expected && !sameIdentity(before, expected)) {
+        throw new Error(`${label} changed while it was being processed: ${path}`);
+    }
+    const fd = openSync(path, flags | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fstatSync(fd);
+        assertRegularStat(opened, path, label);
+        const identity = identityFrom(opened);
+        if (!sameIdentity(identity, before) || (expected && !sameIdentity(identity, expected))) {
+            throw new Error(`${label} changed while it was being opened: ${path}`);
+        }
+        return { fd, identity };
+    }
+    catch (error) {
+        closeSync(fd);
+        throw error;
+    }
+}
+export function openVerifiedRegular(path, label, expected) {
+    return openVerifiedRegularWithFlags(path, label, constants.O_RDONLY, expected);
+}
+export function openVerifiedRegularForUpdate(path, label, expected) {
+    return openVerifiedRegularWithFlags(path, label, constants.O_RDWR, expected);
+}
+export function secureRegularPath(path, label, expected) {
+    const opened = openVerifiedRegular(path, label, expected);
+    try {
+        if (process.platform !== 'win32')
+            fchmodSync(opened.fd, 0o600);
+        return opened.identity;
+    }
+    finally {
+        closeSync(opened.fd);
+    }
+}
+export function validateDirectory(path, label, secure) {
+    // Validate the terminal directory entry and its opened descriptor. Ancestor
+    // components remain outside this guarantee because Node does not expose
+    // portable openat-style traversal for pinning every component.
+    const before = lstatSync(path);
+    if (!before.isDirectory() || before.isSymbolicLink()) {
+        throw new Error(`${label} must be a regular directory, not a symlink: ${path}`);
+    }
+    assertSafeOwner(before, path, label);
+    const noFollow = constants.O_NOFOLLOW ?? 0;
+    const directoryOnly = constants.O_DIRECTORY ?? 0;
+    const fd = openSync(path, constants.O_RDONLY | noFollow | directoryOnly);
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isDirectory() || opened.isSymbolicLink()) {
+            throw new Error(`${label} changed while it was being opened: ${path}`);
+        }
+        assertSafeOwner(opened, path, label);
+        const beforeIdentity = identityFrom(before);
+        const openedIdentity = identityFrom(opened);
+        if (!sameIdentity(beforeIdentity, openedIdentity)) {
+            throw new Error(`${label} changed while it was being opened: ${path}`);
+        }
+        if (secure && process.platform !== 'win32')
+            fchmodSync(fd, 0o700);
+        return openedIdentity;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function prepareEvidenceDirectory(path, label, secure) {
+    try {
+        return validateDirectory(path, label, secure);
+    }
+    catch (error) {
+        if (nodeErrorCode(error) !== 'ENOENT')
+            throw error;
+        mkdirSync(path, { recursive: true, mode: 0o700 });
+        const identity = validateDirectory(path, label, secure);
+        fsyncDirectory(dirname(path));
+        return identity;
+    }
+}
+function writerTempCanonicalName(name) {
+    const coreWriter = /^\.(.+\.episode\.json)\.\d+\.([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.tmp$/i
+        .exec(name);
+    if (coreWriter)
+        return coreWriter[1];
+    const pythonWriter = /^\.(.+)\.([A-Za-z0-9_-]{8})\.tmp$/.exec(name);
+    return pythonWriter ? `${pythonWriter[1]}.episode.json` : undefined;
+}
+function isWriterTempAlias(name, canonicalName) {
+    return writerTempCanonicalName(name) === canonicalName;
+}
+function assertLinkedPublicationStat(stat, path, label) {
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error(`${label} must be a regular file: ${path}`);
+    }
+    assertSafeOwner(stat, path, label);
+}
+/**
+ * Complete the one recoverable interval in no-clobber episode publication.
+ *
+ * Both writers fsync a complete private temp file, hardlink it at the
+ * canonical name, fsync the directory, and finally remove the temp alias. A
+ * process or host crash after link(2) can therefore leave exactly two names
+ * for the same inode. Under the store lock, recognize only the two writer
+ * namespaces and remove the proven temp alias. Arbitrary hardlinks remain
+ * rejected by the normal reader path.
+ */
+export function recoverWriterPublicationAliases(directory) {
+    const names = readdirSync(directory).sort();
+    const canonicalNames = names.filter((name) => name.endsWith('.episode.json'));
+    for (const canonicalName of canonicalNames) {
+        const canonicalPath = join(directory, canonicalName);
+        const canonical = lstatSync(canonicalPath);
+        if (canonical.nlink === 1)
+            continue;
+        assertLinkedPublicationStat(canonical, canonicalPath, 'published evidence episode');
+        if (canonical.nlink !== 2)
+            continue;
+        const canonicalIdentity = identityFrom(canonical);
+        const aliases = names.filter((name) => {
+            if (!isWriterTempAlias(name, canonicalName))
+                return false;
+            const alias = lstatSync(join(directory, name));
+            return sameIdentity(identityFrom(alias), canonicalIdentity);
+        });
+        if (aliases.length !== 1)
+            continue;
+        const aliasPath = join(directory, aliases[0]);
+        const alias = lstatSync(aliasPath);
+        assertLinkedPublicationStat(alias, aliasPath, 'evidence publication temp alias');
+        if (alias.nlink !== 2 || !sameIdentity(identityFrom(alias), canonicalIdentity))
+            continue;
+        // Pin both names before cleanup. The evidence directory is owner-only and
+        // all Jinn writers hold the shared lock; deliberate mutation by another
+        // process running as the same uid is outside the local-store threat model.
+        const canonicalFd = openSync(canonicalPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const aliasFd = openSync(aliasPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const openedCanonical = fstatSync(canonicalFd);
+            const openedAlias = fstatSync(aliasFd);
+            assertLinkedPublicationStat(openedCanonical, canonicalPath, 'published evidence episode');
+            assertLinkedPublicationStat(openedAlias, aliasPath, 'evidence publication temp alias');
+            if (openedCanonical.nlink !== 2
+                || openedAlias.nlink !== 2
+                || !sameIdentity(identityFrom(openedCanonical), canonicalIdentity)
+                || !sameIdentity(identityFrom(openedAlias), canonicalIdentity)) {
+                throw new Error(`evidence publication aliases changed during recovery: ${canonicalPath}`);
+            }
+            const aliasAtCommit = lstatSync(aliasPath);
+            const canonicalAtCommit = lstatSync(canonicalPath);
+            if (!sameIdentity(identityFrom(aliasAtCommit), canonicalIdentity)
+                || !sameIdentity(identityFrom(canonicalAtCommit), canonicalIdentity)) {
+                throw new Error(`evidence publication aliases changed before recovery: ${canonicalPath}`);
+            }
+            unlinkSync(aliasPath);
+            fsyncDirectory(directory);
+        }
+        finally {
+            closeSync(aliasFd);
+            closeSync(canonicalFd);
+        }
+        secureRegularPath(canonicalPath, 'recovered evidence episode', canonicalIdentity);
+    }
+    // A crash before link(2) leaves only the complete nlink=1 temp. Because
+    // temp creation also happens under this store lock, no cooperating writer
+    // can still be using it while recovery holds the lock.
+    for (const name of names) {
+        if (!writerTempCanonicalName(name))
+            continue;
+        const path = join(directory, name);
+        let identity;
+        try {
+            identity = inspectRegularPath(path, 'abandoned evidence publication temp');
+        }
+        catch (error) {
+            if (nodeErrorCode(error) === 'ENOENT')
+                continue;
+            throw error;
+        }
+        if (!identity)
+            continue;
+        const opened = openVerifiedRegular(path, 'abandoned evidence publication temp', identity);
+        try {
+            const atCommit = lstatSync(path);
+            assertRegularStat(atCommit, path, 'abandoned evidence publication temp');
+            if (!sameIdentity(identityFrom(atCommit), opened.identity)) {
+                throw new Error(`evidence publication temp changed before cleanup: ${path}`);
+            }
+            unlinkSync(path);
+            fsyncDirectory(directory);
+        }
+        finally {
+            closeSync(opened.fd);
+        }
+    }
+}
+export function fsyncDirectory(path) {
+    if (process.platform === 'win32')
+        return;
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_DIRECTORY ?? 0));
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readVerifiedText(path, label, expected) {
+    const opened = openVerifiedRegular(path, label, expected);
+    try {
+        return {
+            text: readFileSync(opened.fd, 'utf8'),
+            identity: opened.identity,
+        };
+    }
+    finally {
+        closeSync(opened.fd);
+    }
+}