@open-agent-toolkit/cli 0.2.50 → 0.2.52

package/dist/fs/io.d.ts

@@ -1,10 +1,77 @@
 export declare function fileExists(path: string): Promise<boolean>;
 export declare function dirExists(path: string): Promise<boolean>;
 export type LinkStrategy = 'symlink' | 'copy';
+export interface CreatedCollectionSymlink {
+    linkText: string;
+    device: string;
+    inode: string;
+}
+export interface CollectionSymlinkCreationGuard {
+    scopeRoot: string;
+    expectedParent: {
+        device: string;
+        inode: string;
+    };
+}
 export type CopyDirectoryFilter = (sourcePath: string, relativePath: string) => boolean | Promise<boolean>;
 export declare function ensureDir(dirPath: string): Promise<void>;
 export declare function copyDirectory(src: string, dest: string, filter?: CopyDirectoryFilter, sourceRoot?: string): Promise<void>;
 export declare function copySingleFile(src: string, dest: string): Promise<void>;
+export declare function copySingleFileNoClobber(src: string, dest: string): Promise<void>;
+export declare function writeFileNoClobber(dest: string, content: string): Promise<void>;
 export declare function createSymlink(target: string, linkPath: string, onFallback?: (error: unknown) => void, isFile?: boolean): Promise<LinkStrategy>;
+export declare function createSymlinkNoClobber(target: string, linkPath: string, isFile?: boolean): Promise<'symlink'>;
+export declare function createCollectionSymlinkNoClobber(_target: string, linkPath: string, guard: CollectionSymlinkCreationGuard): Promise<CreatedCollectionSymlink>;
+export declare function removeCollectionSymlinkIfUnchanged(linkPath: string, created: CreatedCollectionSymlink): Promise<boolean>;
+/**
+ * The one serialization of a JSON document OAT writes to disk.
+ *
+ * Every size bound that claims to constrain a published file must measure this
+ * exact string. Validating compact `JSON.stringify` while writing pretty-printed
+ * output with a trailing newline let a record validated at 65,536 bytes land on
+ * disk at 65,874.
+ */
+export declare function serializeJsonDocument(data: unknown): string;
 export declare function atomicWriteJson(filePath: string, data: unknown): Promise<void>;
+export interface ContainedWriterLockOptions {
+    timeoutMs?: number;
+    minReclaimMs?: number;
+    hardStaleMs?: number;
+}
+/**
+ * Exclusive contained writer lock. `mkdir` without `recursive` is the atomic
+ * primitive: exactly one caller can create the directory, and every other
+ * caller observes `EEXIST`. The lock is validated as a real directory so a
+ * planted symlink fails closed instead of redirecting the guarded section, it
+ * records holder evidence so a crashed writer can be reclaimed rather than
+ * wedging the project forever, and no message it raises contains an absolute
+ * path.
+ */
+export declare function withContainedWriterLock<T>(lockPath: string, scopeRoot: string, run: () => Promise<T>, options?: ContainedWriterLockOptions): Promise<T>;
+export declare function journalErrorCode(error: unknown): string | null;
+/**
+ * Re-raise a filesystem error without Node's absolute-path message text while
+ * preserving its `code` so callers can still branch on `EEXIST`/`ENOENT`.
+ * Exported so every journal producer redacts identically instead of each one
+ * re-deriving the rule.
+ */
+export declare function redactedFsError(error: unknown, operation: string, relativeTarget: string): Error;
+/**
+ * Publish one immutable JSON journal revision.
+ *
+ * Guarantees, stated as what the code does:
+ * - The destination is created with `link` only. An occupied destination raises
+ *   `EEXIST`; the destination is never renamed onto, removed, or truncated.
+ * - After publication the destination is proven to be the exact staged inode,
+ *   inside the same directory inode validated before staging, still resolving
+ *   inside `scopeRoot`. Failure raises and removes nothing.
+ * - Staging cleanup removes only the inode this call created.
+ * - No raised message contains an absolute path.
+ *
+ * Residual, unchanged by this design: a privileged concurrent process that
+ * swaps the validated directory pathname can cause the `link` to create an
+ * unreferenced file under a directory it controls, and can strand the staged
+ * file. Neither outcome replaces or deletes pre-existing content.
+ */
+export declare function publishContainedJsonRevision(filePath: string, data: unknown, scopeRoot: string): Promise<void>;
 //# sourceMappingURL=io.d.ts.map

package/dist/fs/io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/fs/io.ts"],"names":[],"mappings":"AAaA,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC;AAC9C,MAAM,MAAM,mBAAmB,GAAG,CAChC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,mBAAmB,EAC5B,UAAU,SAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7E;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACrC,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,CAuBvB;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,IAAI,CAAC,CAKf"}
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/fs/io.ts"],"names":[],"mappings":"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"}

package/dist/fs/io.js

@@ -1,5 +1,7 @@
-import { chmod, mkdir, readdir, readFile, rename, rm, stat, symlink, writeFile, } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, lstat, link, mkdir, open, readdir, readFile, readlink, realpath, rename, rm, stat, symlink, writeFile, } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from 'node:path';
 export async function fileExists(path) {
     try {
         const s = await stat(path);
@@ -18,6 +20,7 @@ export async function dirExists(path) {
         return false;
     }
 }
+const COLLECTION_LINK_UNSAFE_CODE = 'E_COLLECTION_LINK_UNSAFE';
 export async function ensureDir(dirPath) {
     await mkdir(dirPath, { recursive: true });
 }
@@ -49,6 +52,15 @@ export async function copySingleFile(src, dest) {
     const content = await readFile(src);
     await writeFile(dest, content);
 }
+export async function copySingleFileNoClobber(src, dest) {
+    await ensureDir(dirname(dest));
+    const content = await readFile(src);
+    await writeFile(dest, content, { flag: 'wx' });
+}
+export async function writeFileNoClobber(dest, content) {
+    await ensureDir(dirname(dest));
+    await writeFile(dest, content, { encoding: 'utf8', flag: 'wx' });
+}
 export async function createSymlink(target, linkPath, onFallback, isFile) {
     await ensureDir(dirname(linkPath));
     // Use relative symlink targets so links stay valid when the source tree
@@ -73,9 +85,530 @@ export async function createSymlink(target, linkPath, onFallback, isFile) {
         return 'copy';
     }
 }
+export async function createSymlinkNoClobber(target, linkPath, isFile) {
+    await ensureDir(dirname(linkPath));
+    const symlinkTarget = isAbsolute(target)
+        ? relative(dirname(linkPath), target)
+        : target;
+    await symlink(symlinkTarget, linkPath, isFile ? 'file' : 'dir');
+    return 'symlink';
+}
+export async function createCollectionSymlinkNoClobber(_target, linkPath, guard) {
+    const scopeRoot = resolve(guard.scopeRoot);
+    const parent = resolve(dirname(linkPath));
+    const relativeParent = relative(scopeRoot, parent);
+    if (relativeParent === '..' ||
+        relativeParent.startsWith(`..${sep}`) ||
+        isAbsolute(relativeParent)) {
+        throw new Error('Collection destination parent is outside the sync scope.');
+    }
+    const parentSegments = relativeParent === '' ? [] : relativeParent.split(sep);
+    const ancestors = [scopeRoot];
+    let current = scopeRoot;
+    for (const segment of parentSegments) {
+        current = resolve(current, segment);
+        ancestors.push(current);
+    }
+    let nearestExisting;
+    for (const ancestor of [...ancestors].reverse()) {
+        try {
+            nearestExisting = await lstat(ancestor);
+            break;
+        }
+        catch (error) {
+            if (typeof error !== 'object' ||
+                error === null ||
+                !('code' in error) ||
+                error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    if (nearestExisting === undefined ||
+        nearestExisting.isSymbolicLink() ||
+        !nearestExisting.isDirectory() ||
+        String(nearestExisting.dev) !== guard.expectedParent.device ||
+        String(nearestExisting.ino) !== guard.expectedParent.inode) {
+        throw new Error('Collection destination ancestry changed before creation.');
+    }
+    for (const ancestor of ancestors) {
+        let ancestorStat;
+        try {
+            ancestorStat = await lstat(ancestor);
+        }
+        catch (error) {
+            if (typeof error !== 'object' ||
+                error === null ||
+                !('code' in error) ||
+                error.code !== 'ENOENT') {
+                throw error;
+            }
+            continue;
+        }
+        if (ancestorStat.isSymbolicLink() || !ancestorStat.isDirectory()) {
+            throw new Error('Collection destination ancestry must contain only real directories.');
+        }
+    }
+    try {
+        await lstat(linkPath);
+        throw Object.assign(new Error('Collection destination already exists.'), {
+            code: 'EEXIST',
+        });
+    }
+    catch (error) {
+        if (typeof error !== 'object' ||
+            error === null ||
+            !('code' in error) ||
+            error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    throw Object.assign(new Error('Collection link creation is disabled because this runtime has no securely guarded parent-relative symlink primitive.'), { code: COLLECTION_LINK_UNSAFE_CODE });
+}
+export async function removeCollectionSymlinkIfUnchanged(linkPath, created) {
+    try {
+        const current = await lstat(linkPath);
+        if (!current.isSymbolicLink() ||
+            String(current.dev) !== created.device ||
+            String(current.ino) !== created.inode) {
+            return false;
+        }
+        if ((await readlink(linkPath)) !== created.linkText) {
+            return false;
+        }
+        // Node's path-based unlink cannot bind the final removal to the identity
+        // proven above. Preserve the alias until a guarded parent-relative
+        // no-follow removal primitive is available.
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The one serialization of a JSON document OAT writes to disk.
+ *
+ * Every size bound that claims to constrain a published file must measure this
+ * exact string. Validating compact `JSON.stringify` while writing pretty-printed
+ * output with a trailing newline let a record validated at 65,536 bytes land on
+ * disk at 65,874.
+ */
+export function serializeJsonDocument(data) {
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
 export async function atomicWriteJson(filePath, data) {
     const tempPath = `${filePath}.tmp`;
     await ensureDir(dirname(filePath));
-    await writeFile(tempPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    await writeFile(tempPath, serializeJsonDocument(data), 'utf8');
     await rename(tempPath, filePath);
 }
+const WRITER_LOCK_RETRY_MS = 10;
+const WRITER_LOCK_TIMEOUT_MS = 5000;
+/** A lock younger than this is never reclaimed, so a writer that has not yet
+ * written its holder file is not mistaken for a crash. */
+const WRITER_LOCK_MIN_RECLAIM_MS = 1000;
+/**
+ * Hard cap. A lock older than this is reclaimed unconditionally — including one
+ * whose holder is provably alive — because a dispatch write is a sub-second
+ * operation and a holder past this bound is hung rather than working. This is
+ * safe because the lock is not what protects the journal: the create-only
+ * revision compare-and-swap is, and it holds independently of any lock, so a
+ * wrongly reclaimed lock costs mutual exclusion but never correctness.
+ */
+const WRITER_LOCK_HARD_STALE_MS = 15 * 60 * 1000;
+const HOLDER_FILE = 'holder.json';
+/**
+ * Non-identifying, stable-per-host token. Liveness of a recorded pid is only
+ * meaningful on the host that recorded it, and the raw hostname is never
+ * written into a project artifact or an error message.
+ */
+function hostId() {
+    return createHash('sha256')
+        .update(hostname(), 'utf8')
+        .digest('hex')
+        .slice(0, 16);
+}
+function processStartedAt() {
+    return Math.round(Date.now() - process.uptime() * 1000);
+}
+function holderIsRunning(holder) {
+    if (holder.hostId !== hostId()) {
+        // Another host's pid says nothing about this one; fall back to age alone.
+        return true;
+    }
+    try {
+        process.kill(holder.pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but is owned by somebody else.
+        return errorCode(error) !== 'ESRCH';
+    }
+}
+async function readWriterLockHolder(lockPath) {
+    try {
+        const parsed = JSON.parse(await readFile(join(lockPath, HOLDER_FILE), 'utf8'));
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            typeof parsed.pid !== 'number' ||
+            typeof parsed.hostId !== 'string') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bounded staleness policy. A lock is reclaimable when it is old enough that a
+ * live writer would have finished, and either its recorded holder is provably
+ * gone on this host or its age exceeds the hard cap. Returns the reason so the
+ * caller can report what it did.
+ */
+async function writerLockStaleReason(lockPath, minReclaimMs, hardStaleMs) {
+    let age;
+    try {
+        age = Date.now() - (await lstat(lockPath)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+    if (age < minReclaimMs)
+        return null;
+    const holder = await readWriterLockHolder(lockPath);
+    if (holder !== null && !holderIsRunning(holder)) {
+        return 'its recorded holder process is no longer running';
+    }
+    return age >= hardStaleMs ? 'it exceeded the staleness cap' : null;
+}
+/**
+ * Exclusive contained writer lock. `mkdir` without `recursive` is the atomic
+ * primitive: exactly one caller can create the directory, and every other
+ * caller observes `EEXIST`. The lock is validated as a real directory so a
+ * planted symlink fails closed instead of redirecting the guarded section, it
+ * records holder evidence so a crashed writer can be reclaimed rather than
+ * wedging the project forever, and no message it raises contains an absolute
+ * path.
+ */
+export async function withContainedWriterLock(lockPath, scopeRoot, run, options = {}) {
+    const resolvedScope = resolve(scopeRoot);
+    const resolvedLock = resolve(lockPath);
+    if (dirname(resolvedLock) !== resolvedScope) {
+        throw new Error('Writer lock must live directly inside its scope root.');
+    }
+    const scopeStat = await lstat(resolvedScope);
+    if (scopeStat.isSymbolicLink() || !scopeStat.isDirectory()) {
+        throw new Error('Writer lock scope must be a real directory.');
+    }
+    const reportedLock = scopeRelative(resolvedScope, resolvedLock);
+    const timeoutMs = options.timeoutMs ?? WRITER_LOCK_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    let reclaimed = false;
+    for (;;) {
+        try {
+            await mkdir(resolvedLock);
+            break;
+        }
+        catch (error) {
+            if (errorCode(error) !== 'EEXIST') {
+                throw error;
+            }
+            if (!reclaimed) {
+                const stale = await writerLockStaleReason(resolvedLock, options.minReclaimMs ?? WRITER_LOCK_MIN_RECLAIM_MS, options.hardStaleMs ?? WRITER_LOCK_HARD_STALE_MS);
+                if (stale !== null) {
+                    const held = await lstat(resolvedLock);
+                    if (held.isSymbolicLink() || !held.isDirectory()) {
+                        throw new Error(`Writer lock ${reportedLock} is not a real directory.`, { cause: error });
+                    }
+                    await rm(resolvedLock, { recursive: true, force: true });
+                    reclaimed = true;
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Another writer holds ${reportedLock}. If no writer is running, remove ${reportedLock} inside the project and retry.`, { cause: error });
+            }
+            await new Promise((resolveDelay) => setTimeout(resolveDelay, WRITER_LOCK_RETRY_MS));
+        }
+    }
+    const holder = {
+        hostId: hostId(),
+        pid: process.pid,
+        processStartedAt: processStartedAt(),
+        acquiredAt: new Date().toISOString(),
+    };
+    const held = await lstat(resolvedLock);
+    if (held.isSymbolicLink() || !held.isDirectory()) {
+        throw new Error(`Writer lock ${reportedLock} is not a real directory.`);
+    }
+    const lockIdentity = identityOf(held);
+    try {
+        await writeFile(join(resolvedLock, HOLDER_FILE), `${JSON.stringify(holder, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+        return await run();
+    }
+    finally {
+        await releaseWriterLock(resolvedLock, lockIdentity, holder);
+    }
+}
+/**
+ * Release only a lock this call still provably holds. Both the directory
+ * identity captured at acquisition and the holder record must still match. A
+ * missing holder file counts as "not mine" — it is exactly the window in which
+ * a reclaiming writer has re-created the directory but not yet written its own
+ * record — so the replacement is left to the staleness policy rather than
+ * removed from under its new owner.
+ */
+async function releaseWriterLock(lockPath, identity, holder) {
+    try {
+        const current = await lstat(lockPath);
+        if (current.isSymbolicLink() || !current.isDirectory())
+            return;
+        if (!sameIdentity(identityOf(current), identity))
+            return;
+        const currentHolder = await readWriterLockHolder(lockPath);
+        if (currentHolder === null ||
+            currentHolder.hostId !== holder.hostId ||
+            currentHolder.pid !== holder.pid ||
+            currentHolder.acquiredAt !== holder.acquiredAt) {
+            return;
+        }
+        await rm(lockPath, { recursive: true, force: true });
+    }
+    catch {
+        // Nothing releasable remains.
+    }
+}
+function identityOf(entry) {
+    return { device: String(entry.dev), inode: String(entry.ino) };
+}
+function sameIdentity(left, right) {
+    return left.device === right.device && left.inode === right.inode;
+}
+async function assertUnchangedIdentity(path, expected, message) {
+    if (!sameIdentity(identityOf(await lstat(path)), expected)) {
+        throw new Error(message);
+    }
+}
+/**
+ * Scope-relative rendering for any path this module reports. NFR1 requires that
+ * home paths and user-specific absolute paths stay out of durable output, so no
+ * error raised below may carry an absolute path.
+ */
+function scopeRelative(resolvedScope, target) {
+    const rendered = relative(resolvedScope, resolve(target));
+    return rendered === '' ? '.' : rendered.split(sep).join('/');
+}
+export function journalErrorCode(error) {
+    return errorCode(error);
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : null;
+}
+/**
+ * Re-raise a filesystem error without Node's absolute-path message text while
+ * preserving its `code` so callers can still branch on `EEXIST`/`ENOENT`.
+ * Exported so every journal producer redacts identically instead of each one
+ * re-deriving the rule.
+ */
+export function redactedFsError(error, operation, relativeTarget) {
+    const code = errorCode(error);
+    const raised = new Error(`Journal ${operation} failed for ${relativeTarget}${code === null ? '' : ` (${code})`}.`, { cause: error });
+    return code === null ? raised : Object.assign(raised, { code });
+}
+/**
+ * Node exposes no `openat`/`renameat`/`linkat`, so a path-based final operation
+ * cannot be bound to a directory file descriptor. Publication is therefore
+ * append-only and create-only: the destination must not already exist, the only
+ * publishing syscall is `link`, and this module never issues `rename`, `rm`, or
+ * `unlink` against a publication destination. A pathname swapped after the last
+ * check can therefore cause at most an unreferenced create, never a replacement
+ * or a deletion of content this call did not create.
+ */
+async function publicationIsMisplaced(resolvedFile, tempIdentity, parentIdentity, realScope) {
+    let published;
+    try {
+        published = await lstat(resolvedFile);
+    }
+    catch {
+        return 'the published name disappeared';
+    }
+    if (published.isSymbolicLink() || !published.isFile()) {
+        return 'the published name is not a regular file';
+    }
+    if (!sameIdentity(identityOf(published), tempIdentity)) {
+        return 'the published name is not the staged file';
+    }
+    try {
+        if (!sameIdentity(identityOf(await lstat(dirname(resolvedFile))), parentIdentity)) {
+            return 'the parent directory identity changed';
+        }
+        const currentRealParent = await realpath(dirname(resolvedFile));
+        const currentRelative = relative(realScope, currentRealParent);
+        if (currentRelative === '..' ||
+            currentRelative.startsWith(`..${sep}`) ||
+            isAbsolute(currentRelative)) {
+            return 'the parent directory resolves outside the allowed scope';
+        }
+    }
+    catch {
+        return 'the parent directory could not be re-validated';
+    }
+    return null;
+}
+/**
+ * Remove the staging file only when the name still resolves to the exact inode
+ * this call created. A swapped directory pathname therefore strands the staged
+ * file rather than deleting an unrelated one. Returns whether the staged data
+ * was provably removed, so callers can report the outcome accurately.
+ *
+ * Precisely: this removes only the *inode* this call created, not only the
+ * *names* it created. A privileged process that hard-links the staged file into
+ * a directory it controls and then swaps the journal pathname at it can have
+ * that alias unlinked here. No data is destroyed — the inode stays linked from
+ * the real directory, and no pre-existing foreign file can ever match, since a
+ * distinct file has a distinct dev/ino pair.
+ */
+async function removeStagedFile(tempPath, tempIdentity) {
+    try {
+        if (tempIdentity === null) {
+            await rm(tempPath, { force: true });
+            return 'removed';
+        }
+        const current = await lstat(tempPath);
+        if (!sameIdentity(identityOf(current), tempIdentity)) {
+            return 'stranded';
+        }
+        await rm(tempPath, { force: true });
+        return 'removed';
+    }
+    catch {
+        return 'stranded';
+    }
+}
+/**
+ * Publish one immutable JSON journal revision.
+ *
+ * Guarantees, stated as what the code does:
+ * - The destination is created with `link` only. An occupied destination raises
+ *   `EEXIST`; the destination is never renamed onto, removed, or truncated.
+ * - After publication the destination is proven to be the exact staged inode,
+ *   inside the same directory inode validated before staging, still resolving
+ *   inside `scopeRoot`. Failure raises and removes nothing.
+ * - Staging cleanup removes only the inode this call created.
+ * - No raised message contains an absolute path.
+ *
+ * Residual, unchanged by this design: a privileged concurrent process that
+ * swaps the validated directory pathname can cause the `link` to create an
+ * unreferenced file under a directory it controls, and can strand the staged
+ * file. Neither outcome replaces or deletes pre-existing content.
+ */
+export async function publishContainedJsonRevision(filePath, data, scopeRoot) {
+    const resolvedScope = resolve(scopeRoot);
+    const resolvedFile = resolve(filePath);
+    const relativeFile = relative(resolvedScope, resolvedFile);
+    if (relativeFile === '..' ||
+        relativeFile.startsWith(`..${sep}`) ||
+        isAbsolute(relativeFile)) {
+        throw new Error('JSON journal destination is outside its allowed scope.');
+    }
+    const reportedFile = scopeRelative(resolvedScope, resolvedFile);
+    const scopeStat = await lstat(resolvedScope);
+    if (scopeStat.isSymbolicLink() || !scopeStat.isDirectory()) {
+        throw new Error('JSON journal scope must be a real directory.');
+    }
+    const realScope = await realpath(resolvedScope);
+    const parentRelative = relative(resolvedScope, dirname(resolvedFile));
+    const segments = parentRelative === '' ? [] : parentRelative.split(sep);
+    let current = resolvedScope;
+    for (const segment of segments) {
+        current = join(current, segment);
+        try {
+            const currentStat = await lstat(current);
+            if (currentStat.isSymbolicLink() || !currentStat.isDirectory()) {
+                throw new Error('JSON journal ancestry must not contain symlinks and must contain only real directories.');
+            }
+        }
+        catch (error) {
+            if (errorCode(error) !== 'ENOENT') {
+                throw error;
+            }
+            await mkdir(current);
+        }
+    }
+    const realParent = await realpath(dirname(resolvedFile));
+    const relativeParent = relative(realScope, realParent);
+    if (relativeParent === '..' ||
+        relativeParent.startsWith(`..${sep}`) ||
+        isAbsolute(relativeParent)) {
+        throw new Error('JSON journal ancestry resolves outside its allowed scope.');
+    }
+    // Publication is create-only, so an already-published revision is a lost
+    // compare-and-swap rather than something to overwrite.
+    try {
+        await lstat(resolvedFile);
+        throw Object.assign(new Error(`Journal revision ${reportedFile} already exists.`), { code: 'EEXIST' });
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT') {
+            throw error;
+        }
+    }
+    const parentIdentity = identityOf(await lstat(dirname(resolvedFile)));
+    const content = serializeJsonDocument(data);
+    const tempPath = join(dirname(resolvedFile), `.${basename(resolvedFile)}.${randomUUID()}.tmp`);
+    const reportedTemp = scopeRelative(resolvedScope, tempPath);
+    let tempCreated = false;
+    let stagedIdentity = null;
+    try {
+        let handle;
+        try {
+            handle = await open(tempPath, 'wx');
+        }
+        catch (error) {
+            throw redactedFsError(error, 'staging', reportedTemp);
+        }
+        let tempIdentity;
+        try {
+            tempCreated = true;
+            await handle.writeFile(content, 'utf8');
+            tempIdentity = identityOf(await handle.stat());
+            stagedIdentity = tempIdentity;
+        }
+        finally {
+            await handle.close();
+        }
+        // Last ancestry check, then the identity binding that narrows the window
+        // between that check and the path-based publication below.
+        if ((await realpath(dirname(resolvedFile))) !== realParent) {
+            throw new Error('JSON journal ancestry changed before publication.');
+        }
+        await assertUnchangedIdentity(dirname(resolvedFile), parentIdentity, 'JSON journal directory identity changed before publication.');
+        await assertUnchangedIdentity(tempPath, tempIdentity, 'JSON journal staging file identity changed before publication.');
+        try {
+            await link(tempPath, resolvedFile);
+        }
+        catch (error) {
+            throw redactedFsError(error, 'publication', reportedFile);
+        }
+        const misplaced = await publicationIsMisplaced(resolvedFile, tempIdentity, parentIdentity, realScope);
+        if (misplaced) {
+            // Never remove the destination: under a swapped pathname it may name
+            // content this call did not create.
+            const staged = await removeStagedFile(tempPath, tempIdentity);
+            tempCreated = false;
+            throw new Error(`Journal revision ${reportedFile} could not be verified inside the validated directory (${misplaced}). It was not published to the project journal, and this call removed and replaced nothing. ${staged === 'removed'
+                ? 'Staged data was removed.'
+                : 'A staged copy may remain outside the validated directory.'}`);
+        }
+        await removeStagedFile(tempPath, tempIdentity);
+        tempCreated = false;
+    }
+    finally {
+        if (tempCreated) {
+            await removeStagedFile(tempPath, stagedIdentity);
+        }
+    }
+}

package/dist/manifest/index.d.ts

@@ -1,5 +1,5 @@
 export { computeDirectoryHash } from './hash.js';
 export { addEntry, createEmptyManifest, findEntry, loadManifest, removeEntry, saveManifest, } from './manager.js';
-export type { Manifest, ManifestEntry } from './manifest.types.js';
-export { ManifestEntrySchema, ManifestSchema } from './manifest.types.js';
+export type { Manifest, ManifestCollectionEntry, ManifestEntry, ManifestEntryV2, ManifestV1, ManifestV2, } from './manifest.types.js';
+export { ManifestCollectionEntrySchema, ManifestEntrySchema, ManifestSchema, ManifestV1Schema, ManifestV2Schema, } from './manifest.types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/manifest/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,QAAQ,EACR,uBAAuB,EACvB,aAAa,EACb,eAAe,EACf,UAAU,EACV,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,6BAA6B,EAC7B,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/manifest/index.js

@@ -1,3 +1,3 @@
 export { computeDirectoryHash } from './hash.js';
 export { addEntry, createEmptyManifest, findEntry, loadManifest, removeEntry, saveManifest, } from './manager.js';
-export { ManifestEntrySchema, ManifestSchema } from './manifest.types.js';
+export { ManifestCollectionEntrySchema, ManifestEntrySchema, ManifestSchema, ManifestV1Schema, ManifestV2Schema, } from './manifest.types.js';