@jini-ai/platform 0.1.2 → 0.5.0

package/dist/fetch-with-timeout.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @module fetch-with-timeout
+ *
+ * The shared timeout wrapper for every outbound `fetch()` call this monorepo makes to a remote
+ * service — see the 2026-08-16 Jini failure-mode audit, Finding 2: 101 raw `fetch()` call sites
+ * repo-wide (corrected from the audit's own initial "67" — re-count before trusting any figure in
+ * a handoff), across devops deploy providers, agent-runtime providers, media-provider dispatch,
+ * github-client, and llm-provider, most already protected in some ad hoc way. A remote that accepts
+ * the TCP connection but
+ * never responds — a stalled load balancer, a provider having a bad day, a firewall black-holing the
+ * request — leaves `await fetch(...)` unresolved forever; whatever awaits it hangs indefinitely, with
+ * nothing to alert on. A hang like that is worse than a crash: a crash is loud.
+ *
+ * Deliberately ONE helper, not 67 call sites each hand-rolling a slightly different
+ * `AbortController`/`setTimeout` idiom — a caller who already has their own `AbortSignal` (a
+ * user-initiated cancel, a parent request's own deadline) can still supply it via `init.signal`;
+ * `AbortSignal.any` composes it with the timeout so either one aborts the call, and the thrown
+ * `FetchTimeoutError` vs. the caller's own abort reason stay distinguishable (see `fetchWithTimeout`'s
+ * own doc).
+ *
+ * `FETCH_TIMEOUT_MS` gives call sites a small, documented, shared vocabulary instead of inventing a
+ * number each time — a deploy-provider API call, an image byte-fetch, and a large asset upload
+ * genuinely have different reasonable ceilings. `timeoutMs` is never hidden inside the helper as an
+ * undocumented default with no parameter, though: every call site names one explicitly (usually one
+ * of these constants), because a caller reading its own code should see the number, not have to go
+ * find it.
+ *
+ * Deliberately excludes anything meant to stay open for a long time independent of transfer size —
+ * Server-Sent Events, WebSockets, long-poll. None of the 67 flagged call sites are that shape (the
+ * audit traced this: the repo's real streaming transports are `EventSource` on the browser side and
+ * a hand-rolled SSE channel server-side, both entirely separate from `fetch()`), but a future caller
+ * reaching for this helper for one of those would be reaching for the wrong tool — `AbortSignal.timeout`
+ * bounds the WHOLE call, body included, so it would sever a deliberately long-lived stream partway
+ * through exactly like the bug this fixes, just self-inflicted instead of accidental.
+ *
+ * **Also exported as its own subpath, `@jini-ai/platform/fetch-with-timeout`, deliberately.** This
+ * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
+ * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
+ * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, `undici`'s `Agent`, etc.
+ * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
+ * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
+ * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is
+ * NOT fine in `vite dev` or any other unbundled-native-ESM serving mode: there is no tree-shaking on
+ * that path, so the browser eagerly loads and evaluates every sibling the barrel re-exports, and
+ * `process.ts`'s very first statement destructures `execFile`/`spawn` off `node:child_process` —
+ * which Vite's dev server serves as a `Proxy` that throws on first property access. The whole module
+ * graph fails to evaluate the instant anything imports the barrel, regardless of which export is
+ * actually used. Verified empirically (`esbuild --bundle --platform=browser` on the barrel: 154
+ * resolution errors; `vite build`: clean, 5.92kB, zero Node-only code in the output; `vite dev`
+ * serving `index.js`: throws at import time) — see the 2026-08-17 Jini hardening report. Browser
+ * call sites should import from this subpath, never the root barrel.
+ */
+/** Thrown in place of the platform's generic abort error specifically when the timeout — not a
+ * caller-supplied `init.signal` — is what ended the call, so a caller can tell "this took too long"
+ * apart from "I cancelled it myself" without string-matching an error message. */
+export declare class FetchTimeoutError extends Error {
+    readonly url: string;
+    readonly timeoutMs: number;
+    constructor(url: string, timeoutMs: number);
+}
+/**
+ * Shared, documented timeout classes for outbound `fetch()` calls. Every call site names one
+ * explicitly (or its own justified number) rather than relying on an unstated default.
+ */
+export declare const FETCH_TIMEOUT_MS: {
+    /** A single metadata/status/API-read call expected to return quickly: a model catalog listing, a
+     * connection test, a GitHub API read, an LLM provider's non-streaming completion call. */
+    readonly QUICK: 15000;
+    /** A deploy-provider API call that may involve real backend work on the provider's side — site
+     * creation, DNS record lookups, deployment status polling. */
+    readonly DEPLOY: 30000;
+    /** A large-payload transfer: an asset/blob upload, a generated-media byte fetch. */
+    readonly UPLOAD: 120000;
+    /** A media-generation API call whose response only arrives once the vendor has actually finished
+     * generating the image/video/audio server-side — routinely minutes, not seconds. Matches the
+     * value OpenAI's and OpenRouter's own image providers already hardcode locally
+     * (`OPENAI_IMAGE_*_TIMEOUT_MS`/`OPENROUTER_IMAGE_TIMEOUT_MS`); used as the shared dispatch-level
+     * backstop in `@jini-ai/integrations`' `dispatchVendorRequest` for every OTHER vendor that (as of
+     * 2026-08-16) sets no timeout of its own at all. Deliberately NOT the same as `UPLOAD`: a backstop
+     * shorter than a vendor's own already-correct 10-minute generation timeout would abort a
+     * legitimately still-generating request early. */
+    readonly GENERATE: number;
+};
+export interface FetchWithTimeoutOptions {
+    /** Milliseconds before the call is aborted. Pick one of {@link FETCH_TIMEOUT_MS}, or a specific
+     * justified number for a call site that doesn't fit those classes. */
+    timeoutMs: number;
+}
+/**
+ * `fetch`, but aborted after `options.timeoutMs` if it hasn't settled by then. If `init.signal` is
+ * already set, the call aborts on EITHER that signal or the timeout, via `AbortSignal.any` — a
+ * caller's own cancellation (e.g. a user-initiated cancel button) keeps working exactly as it did
+ * without this wrapper.
+ *
+ * @param url - Same as `fetch`'s first argument.
+ * @param init - Same as `fetch`'s second argument. `init.signal`, if present, is combined with the
+ * timeout rather than replaced.
+ * @param options - See {@link FetchWithTimeoutOptions}.
+ * @returns The same `Promise<Response>` `fetch` itself would return.
+ * @throws {@link FetchTimeoutError} if the timeout fires before the call settles and the caller's own
+ * `init.signal` (if any) did not itself already abort. Any other rejection (a caller's own abort, a
+ * genuine network error) propagates unchanged.
+ */
+export declare function fetchWithTimeout(url: string | URL, init: RequestInit | undefined, options: FetchWithTimeoutOptions): Promise<Response>;
+//# sourceMappingURL=fetch-with-timeout.d.ts.map

package/dist/fetch-with-timeout.js

@@ -0,0 +1,121 @@
+/**
+ * @module fetch-with-timeout
+ *
+ * The shared timeout wrapper for every outbound `fetch()` call this monorepo makes to a remote
+ * service — see the 2026-08-16 Jini failure-mode audit, Finding 2: 101 raw `fetch()` call sites
+ * repo-wide (corrected from the audit's own initial "67" — re-count before trusting any figure in
+ * a handoff), across devops deploy providers, agent-runtime providers, media-provider dispatch,
+ * github-client, and llm-provider, most already protected in some ad hoc way. A remote that accepts
+ * the TCP connection but
+ * never responds — a stalled load balancer, a provider having a bad day, a firewall black-holing the
+ * request — leaves `await fetch(...)` unresolved forever; whatever awaits it hangs indefinitely, with
+ * nothing to alert on. A hang like that is worse than a crash: a crash is loud.
+ *
+ * Deliberately ONE helper, not 67 call sites each hand-rolling a slightly different
+ * `AbortController`/`setTimeout` idiom — a caller who already has their own `AbortSignal` (a
+ * user-initiated cancel, a parent request's own deadline) can still supply it via `init.signal`;
+ * `AbortSignal.any` composes it with the timeout so either one aborts the call, and the thrown
+ * `FetchTimeoutError` vs. the caller's own abort reason stay distinguishable (see `fetchWithTimeout`'s
+ * own doc).
+ *
+ * `FETCH_TIMEOUT_MS` gives call sites a small, documented, shared vocabulary instead of inventing a
+ * number each time — a deploy-provider API call, an image byte-fetch, and a large asset upload
+ * genuinely have different reasonable ceilings. `timeoutMs` is never hidden inside the helper as an
+ * undocumented default with no parameter, though: every call site names one explicitly (usually one
+ * of these constants), because a caller reading its own code should see the number, not have to go
+ * find it.
+ *
+ * Deliberately excludes anything meant to stay open for a long time independent of transfer size —
+ * Server-Sent Events, WebSockets, long-poll. None of the 67 flagged call sites are that shape (the
+ * audit traced this: the repo's real streaming transports are `EventSource` on the browser side and
+ * a hand-rolled SSE channel server-side, both entirely separate from `fetch()`), but a future caller
+ * reaching for this helper for one of those would be reaching for the wrong tool — `AbortSignal.timeout`
+ * bounds the WHOLE call, body included, so it would sever a deliberately long-lived stream partway
+ * through exactly like the bug this fixes, just self-inflicted instead of accidental.
+ *
+ * **Also exported as its own subpath, `@jini-ai/platform/fetch-with-timeout`, deliberately.** This
+ * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
+ * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
+ * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, `undici`'s `Agent`, etc.
+ * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
+ * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
+ * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is
+ * NOT fine in `vite dev` or any other unbundled-native-ESM serving mode: there is no tree-shaking on
+ * that path, so the browser eagerly loads and evaluates every sibling the barrel re-exports, and
+ * `process.ts`'s very first statement destructures `execFile`/`spawn` off `node:child_process` —
+ * which Vite's dev server serves as a `Proxy` that throws on first property access. The whole module
+ * graph fails to evaluate the instant anything imports the barrel, regardless of which export is
+ * actually used. Verified empirically (`esbuild --bundle --platform=browser` on the barrel: 154
+ * resolution errors; `vite build`: clean, 5.92kB, zero Node-only code in the output; `vite dev`
+ * serving `index.js`: throws at import time) — see the 2026-08-17 Jini hardening report. Browser
+ * call sites should import from this subpath, never the root barrel.
+ */
+/** Thrown in place of the platform's generic abort error specifically when the timeout — not a
+ * caller-supplied `init.signal` — is what ended the call, so a caller can tell "this took too long"
+ * apart from "I cancelled it myself" without string-matching an error message. */
+export class FetchTimeoutError extends Error {
+    url;
+    timeoutMs;
+    constructor(url, timeoutMs) {
+        super(`fetch timed out after ${timeoutMs}ms: ${url}`);
+        this.name = "FetchTimeoutError";
+        this.url = url;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Shared, documented timeout classes for outbound `fetch()` calls. Every call site names one
+ * explicitly (or its own justified number) rather than relying on an unstated default.
+ */
+export const FETCH_TIMEOUT_MS = {
+    /** A single metadata/status/API-read call expected to return quickly: a model catalog listing, a
+     * connection test, a GitHub API read, an LLM provider's non-streaming completion call. */
+    QUICK: 15_000,
+    /** A deploy-provider API call that may involve real backend work on the provider's side — site
+     * creation, DNS record lookups, deployment status polling. */
+    DEPLOY: 30_000,
+    /** A large-payload transfer: an asset/blob upload, a generated-media byte fetch. */
+    UPLOAD: 120_000,
+    /** A media-generation API call whose response only arrives once the vendor has actually finished
+     * generating the image/video/audio server-side — routinely minutes, not seconds. Matches the
+     * value OpenAI's and OpenRouter's own image providers already hardcode locally
+     * (`OPENAI_IMAGE_*_TIMEOUT_MS`/`OPENROUTER_IMAGE_TIMEOUT_MS`); used as the shared dispatch-level
+     * backstop in `@jini-ai/integrations`' `dispatchVendorRequest` for every OTHER vendor that (as of
+     * 2026-08-16) sets no timeout of its own at all. Deliberately NOT the same as `UPLOAD`: a backstop
+     * shorter than a vendor's own already-correct 10-minute generation timeout would abort a
+     * legitimately still-generating request early. */
+    GENERATE: 10 * 60_000,
+};
+/**
+ * `fetch`, but aborted after `options.timeoutMs` if it hasn't settled by then. If `init.signal` is
+ * already set, the call aborts on EITHER that signal or the timeout, via `AbortSignal.any` — a
+ * caller's own cancellation (e.g. a user-initiated cancel button) keeps working exactly as it did
+ * without this wrapper.
+ *
+ * @param url - Same as `fetch`'s first argument.
+ * @param init - Same as `fetch`'s second argument. `init.signal`, if present, is combined with the
+ * timeout rather than replaced.
+ * @param options - See {@link FetchWithTimeoutOptions}.
+ * @returns The same `Promise<Response>` `fetch` itself would return.
+ * @throws {@link FetchTimeoutError} if the timeout fires before the call settles and the caller's own
+ * `init.signal` (if any) did not itself already abort. Any other rejection (a caller's own abort, a
+ * genuine network error) propagates unchanged.
+ */
+export async function fetchWithTimeout(url, init = {}, options) {
+    const { timeoutMs } = options;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+    try {
+        return await fetch(url, { ...init, signal });
+    }
+    catch (error) {
+        // `timeoutSignal` is the original object this function created, not the (possibly composed)
+        // signal handed to `fetch` — checking its own `.aborted` tells us specifically whether OUR
+        // timeout fired, independent of whether a caller-supplied signal also exists or also aborted.
+        if (timeoutSignal.aborted && !init.signal?.aborted) {
+            throw new FetchTimeoutError(String(url), timeoutMs);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=fetch-with-timeout.js.map

package/dist/fs/atomic-write.d.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import { type PlatformMessages } from "../messages.js";
+/** Synchronous seam preserves the original fail-before-rename and permission contract.
+ * Descriptor ownership separates failed exclusive creates from failures after creating a temp. */
+export interface AtomicFilesystemPort {
+    stat(required: {
+        path: string;
+    }): {
+        mode: number;
+    };
+    lstat(required: {
+        path: string;
+    }): {
+        mode: number;
+        isSymbolicLink(): boolean;
+    };
+    open(required: {
+        path: string;
+        flags: "wx" | "r";
+        mode?: number;
+    }): number;
+    write(required: {
+        descriptor: number;
+        content: string;
+    }): void;
+    sync(required: {
+        descriptor: number;
+    }): void;
+    close(required: {
+        descriptor: number;
+    }): void;
+    chmod(required: {
+        path: string;
+        mode: number;
+    }): void;
+    rename(required: {
+        from: string;
+        to: string;
+    }): void;
+    remove(required: {
+        path: string;
+    }): void;
+}
+export type AtomicNativeFilesystem = Pick<typeof fs, "statSync" | "lstatSync" | "openSync" | "writeFileSync" | "fsyncSync" | "closeSync" | "chmodSync" | "renameSync" | "rmSync">;
+export type AtomicAsyncFilesystem = Pick<typeof fsPromises, "stat" | "lstat" | "open" | "chmod" | "rename" | "rm" | "mkdir">;
+export interface AtomicWriteRequired {
+    filePath: string;
+    content: string;
+    fs: AtomicFilesystemPort;
+}
+export interface AtomicWriteOptions {
+    messages?: PlatformMessages;
+    /** Optional collision token; native pid + UUID restores the original default. */
+    tempName?: (required: {
+        filePath: string;
+    }) => string;
+    /** Explicit mode overrides preservation, e.g. secret-bearing files must use 0600. */
+    mode?: number;
+    /** Default for a missing destination; shared durable stores retain their former 0666 create mode. */
+    defaultMode?: number;
+    refuseSymlink?: boolean;
+    /** Verify owner-only permissions before rename on POSIX, as secret stores require. */
+    verifyOwnerOnly?: boolean;
+    platform?: NodeJS.Platform;
+    /** Same-directory legacy temp layout, for stores that expose their temp path publicly. */
+    tempPath?: (required: {
+        filePath: string;
+    }) => string;
+}
+/** Optional adapter wiring: no layout, env key, or application name is selected here. */
+export declare function createNodeAtomicFilesystem(_required: Record<string, never>, { filesystem }?: {
+    filesystem?: AtomicNativeFilesystem;
+}): AtomicFilesystemPort;
+/** Same-directory rename; preserve existing mode exactly, default new files to 0600.
+ * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
+ * Flush file bytes before rename so metadata cannot precede content; then flush the parent dir.
+ * A directory-sync failure is reported after replacement, because rename cannot be rolled back safely.
+ */
+export declare function writeFileAtomic(required: AtomicWriteRequired, options?: AtomicWriteOptions): void;
+/** Pretty JSON delegates to the same mode-preserving atomic primitive. */
+export declare function writeJsonFileAtomic(required: Omit<AtomicWriteRequired, "content"> & {
+    data: unknown;
+}, options?: AtomicWriteOptions): void;
+/** Async counterpart with the same ownership, permission and durability guarantees.
+ * Parent creation supports runtime-state and secret stores without another writer implementation. */
+export declare function writeFileAtomicAsync(required: {
+    filePath: string;
+    content: string;
+}, options?: AtomicWriteOptions & {
+    fs?: AtomicAsyncFilesystem;
+    createParent?: boolean;
+}): Promise<void>;
+/** Pretty JSON can retain a state-store's trailing newline without changing its serialization. */
+export declare function writeJsonFileAtomicAsync(required: {
+    filePath: string;
+    data: unknown;
+}, options?: AtomicWriteOptions & {
+    fs?: AtomicAsyncFilesystem;
+    createParent?: boolean;
+    trailingNewline?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/fs/atomic-write.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { defaultPlatformMessages } from "../messages.js";
+/** Optional adapter wiring: no layout, env key, or application name is selected here. */
+export function createNodeAtomicFilesystem(_required, { filesystem = fs } = {}) {
+    return {
+        stat: ({ path }) => filesystem.statSync(path),
+        lstat: ({ path }) => filesystem.lstatSync(path),
+        open: ({ path, flags, mode }) => filesystem.openSync(path, flags, mode),
+        write: ({ descriptor, content }) => filesystem.writeFileSync(descriptor, content),
+        sync: ({ descriptor }) => filesystem.fsyncSync(descriptor),
+        close: ({ descriptor }) => filesystem.closeSync(descriptor),
+        chmod: ({ path, mode }) => filesystem.chmodSync(path, mode),
+        rename: ({ from, to }) => filesystem.renameSync(from, to),
+        remove: ({ path }) => filesystem.rmSync(path, { force: true }),
+    };
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function validateMode(mode, options) {
+    if (!Number.isInteger(mode) || mode < 0 || mode > 0o777)
+        throw new RangeError((options.messages ?? defaultPlatformMessages).atomicModeInvalid());
+    return mode;
+}
+function temporaryPath({ filePath }, options) {
+    const { tempName = () => `${process.pid}.${randomUUID()}` } = options;
+    if (options.tempPath) {
+        const temporary = options.tempPath({ filePath });
+        if (path.resolve(path.dirname(temporary)) !== path.resolve(path.dirname(filePath)) || path.resolve(temporary) === path.resolve(filePath) || temporary.includes("\0"))
+            throw new RangeError((options.messages ?? defaultPlatformMessages).atomicTempPathInvalid());
+        return temporary;
+    }
+    const token = tempName({ filePath });
+    if (!token || token === "." || token === ".." || /[/\\\x00]/.test(token))
+        throw new RangeError((options.messages ?? defaultPlatformMessages).atomicTempNameInvalid());
+    return path.join(path.dirname(filePath), `.${path.basename(filePath)}.${token}.tmp`);
+}
+function assertNotSymlink(info, options) {
+    if (info.isSymbolicLink())
+        throw new Error((options.messages ?? defaultPlatformMessages).atomicSymlinkRefused());
+}
+function assertOwnerOnly(mode, options) {
+    // Windows has no POSIX group/other bits; secret stores skip this verification there.
+    if (options.verifyOwnerOnly && (options.platform ?? process.platform) !== "win32" && (mode & 0o077) !== 0)
+        throw new Error((options.messages ?? defaultPlatformMessages).atomicPermissionsRefused());
+}
+/** Same-directory rename; preserve existing mode exactly, default new files to 0600.
+ * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
+ * Flush file bytes before rename so metadata cannot precede content; then flush the parent dir.
+ * A directory-sync failure is reported after replacement, because rename cannot be rolled back safely.
+ */
+export function writeFileAtomic(required, options = {}) {
+    const { filePath, content, fs: filesystem } = required;
+    let existingMode;
+    try {
+        if (options.refuseSymlink) {
+            const info = filesystem.lstat({ path: filePath });
+            assertNotSymlink(info, options);
+            existingMode = info.mode & 0o777;
+        }
+        else {
+            existingMode = filesystem.stat({ path: filePath }).mode & 0o777;
+        }
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    const mode = validateMode(options.mode ?? existingMode ?? options.defaultMode ?? 0o600, options);
+    const temporary = temporaryPath(required, options);
+    // A failed exclusive create does not grant ownership of an existing temporary file.
+    let descriptor = filesystem.open({ path: temporary, flags: "wx", mode });
+    let renamed = false;
+    try {
+        filesystem.write({ descriptor, content });
+        filesystem.chmod({ path: temporary, mode });
+        assertOwnerOnly(filesystem.stat({ path: temporary }).mode, options);
+        filesystem.sync({ descriptor });
+        const fileDescriptor = descriptor;
+        descriptor = undefined;
+        filesystem.close({ descriptor: fileDescriptor });
+        if (options.refuseSymlink) {
+            try {
+                assertNotSymlink(filesystem.lstat({ path: filePath }), options);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+        filesystem.rename({ from: temporary, to: filePath });
+        renamed = true;
+        const directory = filesystem.open({ path: path.dirname(filePath), flags: "r" });
+        try {
+            filesystem.sync({ descriptor: directory });
+        }
+        finally {
+            filesystem.close({ descriptor: directory });
+        }
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            try {
+                filesystem.close({ descriptor });
+            }
+            catch { /* preserve the original failure */ }
+        }
+        if (!renamed) {
+            try {
+                filesystem.remove({ path: temporary });
+            }
+            catch { /* preserve the original failure */ }
+        }
+        throw error;
+    }
+}
+/** Pretty JSON delegates to the same mode-preserving atomic primitive. */
+export function writeJsonFileAtomic(required, options = {}) {
+    const { data, ...writer } = required;
+    const content = JSON.stringify(data, null, 2);
+    if (content === undefined)
+        throw new TypeError((options.messages ?? defaultPlatformMessages).atomicJsonUnserializable());
+    writeFileAtomic({ ...writer, content }, options);
+}
+/** Async counterpart with the same ownership, permission and durability guarantees.
+ * Parent creation supports runtime-state and secret stores without another writer implementation. */
+export async function writeFileAtomicAsync(required, options = {}) {
+    const { filePath, content } = required;
+    const filesystem = options.fs ?? fsPromises;
+    if (options.createParent)
+        await filesystem.mkdir(path.dirname(filePath), { recursive: true });
+    let existingMode;
+    try {
+        const info = options.refuseSymlink ? await filesystem.lstat(filePath) : await filesystem.stat(filePath);
+        if (options.refuseSymlink)
+            assertNotSymlink(info, options);
+        existingMode = info.mode & 0o777;
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    const mode = validateMode(options.mode ?? existingMode ?? options.defaultMode ?? 0o600, options);
+    const temporary = temporaryPath(required, options);
+    // Keep the exclusive create outside cleanup: EEXIST belongs to a different writer.
+    const handle = await filesystem.open(temporary, "wx", mode);
+    let closed = false, renamed = false;
+    try {
+        await handle.writeFile(content, "utf8");
+        await handle.chmod(mode);
+        assertOwnerOnly((await handle.stat()).mode, options);
+        await handle.sync();
+        await handle.close();
+        closed = true;
+        if (options.refuseSymlink) {
+            try {
+                assertNotSymlink(await filesystem.lstat(filePath), options);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+        await filesystem.rename(temporary, filePath);
+        renamed = true;
+        const directory = await filesystem.open(path.dirname(filePath), "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    catch (error) {
+        if (!closed) {
+            try {
+                await handle.close();
+            }
+            catch { /* preserve the original failure */ }
+        }
+        if (!renamed) {
+            try {
+                await filesystem.rm(temporary, { force: true });
+            }
+            catch { /* preserve the original failure */ }
+        }
+        throw error;
+    }
+}
+/** Pretty JSON can retain a state-store's trailing newline without changing its serialization. */
+export async function writeJsonFileAtomicAsync(required, options = {}) {
+    const { data, ...writer } = required;
+    const content = JSON.stringify(data, null, 2);
+    if (content === undefined)
+        throw new TypeError((options.messages ?? defaultPlatformMessages).atomicJsonUnserializable());
+    await writeFileAtomicAsync({ ...writer, content: content + (options.trailingNewline ? "\n" : "") }, options);
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/fs/durable-json.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared stores once wrote JSON directly, treated torn reads as empty, then persisted the empty
+ * state on the next write, erasing recoverable records. One mechanism keeps stores from drifting:
+ * atomic replacement, explicit unreadable state, quarantine, and locks for shared read-modify-write.
+ * Recovery policy stays with each store: salvage, restart, or leave untouched is not decided here.
+ * Native effects are Electron-free so desktop, CLI, and bridge processes can share the mechanism.
+ */
+import nodeFs from "node:fs";
+import type { Clock } from "@jini-ai/core/primitives";
+export type JsonFileRead = {
+    state: "ok";
+    value: unknown;
+} | {
+    state: "missing";
+} | {
+    state: "unreadable";
+    text?: string;
+};
+export interface QuarantineNotice {
+    label: string;
+    consequence: string;
+}
+export interface FileLockOptions {
+    waitMs?: number;
+}
+export interface DurableJsonPorts {
+    filesystem: Pick<typeof nodeFs, "readFileSync" | "mkdirSync" | "openSync" | "writeFileSync" | "fsyncSync" | "closeSync" | "renameSync" | "rmSync" | "writeSync" | "statSync" | "fstatSync" | "lstatSync" | "chmodSync">;
+    clock: Clock;
+    sleep: {
+        sleep(required: {
+            durationMs: number;
+        }): void;
+    };
+    process: {
+        pid: number;
+        isAlive(required: {
+            pid: number;
+        }): boolean;
+    };
+    random: {
+        token(_required: Record<string, never>): string;
+    };
+    report: {
+        error(required: {
+            message: string;
+        }): void;
+    };
+}
+export interface DurableJsonNotices {
+    prefix: string;
+    lockTimeout(required: {
+        lockPath: string;
+        waitMs: number;
+    }): string;
+}
+/** Native synchronous adapters. Liveness probes treat permission errors as alive. */
+export declare function createNodeDurableJsonPorts(_required: Record<string, never>): DurableJsonPorts;
+export interface DurableJsonFile {
+    read(required: Record<string, never>): JsonFileRead;
+    tempPath(required: Record<string, never>, optional?: {
+        pid?: number;
+    }): string;
+    write(required: {
+        value: unknown;
+    }): void;
+    quarantine(required: {
+        notice: QuarantineNotice;
+    }): boolean;
+    withLock<T>(required: {
+        critical: () => T;
+    }, optional?: FileLockOptions): T;
+}
+/** Atomic replacement, distinct corrupt reads, quarantine, and token-owned synchronous locks.
+ * Lock stealing rechecks inode, bytes and mtime; conditional unlink is not available on all hosts.
+ * File fsync precedes rename; directory fsync follows it. Persistence remains filesystem-dependent.
+ */
+export declare function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep, process, random, report, notices }: DurableJsonPorts & {
+    filePath: string;
+    notices: DurableJsonNotices;
+}, { pollMs, staleMs }?: {
+    pollMs?: number;
+    staleMs?: number;
+}): DurableJsonFile;
+export declare function salvageJsonPrefix({ text }: {
+    text: string;
+}, { maxAttempts }?: {
+    maxAttempts?: number;
+}): unknown;
+//# sourceMappingURL=durable-json.d.ts.map