humanish 0.123.0 → 0.125.0

package/dist/routes/computer-use/live-flush.d.ts

@@ -5,16 +5,21 @@ import type { RunBundle } from "../../run/bundle.js";
 import type { RunStudyHomes } from "../../study/run-study-homes.js";
 import type { DesktopParticipantRun } from "./types.js";
 export interface LiveTraceFlush {
-    /** Record a participant's recorded-so-far items; the bundle rewrite follows on the flush
-     *  schedule. */
+    /**
+     * Record a participant's recorded-so-far items; the bundle write follows on the flush schedule.
+     * Each item is deep-frozen here: the run writer appends an item to the participant's live file
+     * once, so an item edited after it was recorded would leave the file stale. A producer that
+     * needs a different item records a new one.
+     */
     flush: (participantId: string, items: readonly ActorTraceItem[], usage?: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
     /** Stop flushing, clear the timer and wait for an in-flight write. Call it on every exit. */
     stop: () => Promise<void>;
 }
 /**
  * Incremental live flush: as each participant's loop reports its recorded-so-far items,
- * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
- * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
+ * publish the in-progress bundle with per-stream `liveActor` partials so the attached
+ * Observer's 5s poll sees the timeline grow; the run writer appends each participant's new items
+ * to its live file. Throttled (one write per interval, trailing
  * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
  * any snapshot once the final write began, so a late flush cannot resurrect the in-progress
  * bundle. A flush failure is swallowed: mid-run observability must never break the run itself.

package/dist/routes/computer-use/live-flush.js

@@ -2,8 +2,9 @@ import { attachObserverRuntimeStreamUrls } from "../../observer/render.js";
 import {} from "../../observer/run-routes.js";
 /**
  * Incremental live flush: as each participant's loop reports its recorded-so-far items,
- * rewrite the in-progress bundle with per-stream `liveActor` partials so the attached
- * Observer's 5s poll sees the timeline grow. Throttled (one write per interval, trailing
+ * publish the in-progress bundle with per-stream `liveActor` partials so the attached
+ * Observer's 5s poll sees the timeline grow; the run writer appends each participant's new items
+ * to its live file. Throttled (one write per interval, trailing
  * write guaranteed). `write` is the run's `writeSnapshot`, which serializes writes and refuses
  * any snapshot once the final write began, so a late flush cannot resurrect the in-progress
  * bundle. A flush failure is swallowed: mid-run observability must never break the run itself.
@@ -56,7 +57,9 @@ export function startLiveTraceFlush(args) {
                                         ids: { model },
                                     }),
                                 ...liveMetadataByStream.get(stream.id),
-                                items: [...liveItems],
+                                // The flush's own copy, replaced and never changed, so the run writer compares
+                                // each write's items with the last by identity.
+                                items: liveItems,
                             },
                         };
                 }),
@@ -94,6 +97,8 @@ export function startLiveTraceFlush(args) {
         const streamId = streamIdByParticipant.get(participantId);
         if (streamId === undefined)
             return;
+        for (const item of items)
+            deepFreeze(item);
         liveItemsByStream.set(streamId, items.slice());
         if (metadata !== undefined)
             liveMetadataByStream.set(streamId, metadata);
@@ -112,6 +117,14 @@ export function startLiveTraceFlush(args) {
     };
     return { flush, stop };
 }
+/** `value` and every object and array it holds, frozen. */
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return;
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+}
 /**
  * The live desktop views (runtime stream URLs) participants report, attached to whichever Observer shows
  * the run. The URLs carry auth, so they live in memory and on the Observer result, never in run

package/dist/run/bundle-shape.js

@@ -1,6 +1,6 @@
 import { isCommsReceivingEvidence } from "../comms/receiving-evidence.js";
 import { isCapturedGitState } from "./git-state.js";
-import { PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA, RUN_BUNDLE_V1_SCHEMA, } from "./bundle.js";
+import { PUBLIC_TARGET_CWD, REVIEW_SCHEMA, isReadRunBundleSchema, } from "./bundle.js";
 import { CLEANUP_SCHEMA, } from "./results.js";
 import { isRunSimulationStatus, isRunStream, isRunStreamKind } from "./stream-shape.js";
 import { isLocalEvidenceArtifactPath } from "./paths.js";
@@ -10,7 +10,7 @@ import { isSharedWorldEvidence } from "./shared-world-shape.js";
 import { isNonNegativeSafeInteger, isPositiveSafeInteger, isRecord } from "./type-guards.js";
 export function isRunBundle(value) {
     return (isRecord(value) &&
-        (value.schema === RUN_BUNDLE_SCHEMA || value.schema === RUN_BUNDLE_V1_SCHEMA) &&
+        isReadRunBundleSchema(value.schema) &&
         (value.commsReceiving === undefined || isCommsReceivingEvidence(value.commsReceiving)) &&
         (value.publication === undefined ||
             (isRecord(value.publication) &&

package/dist/run/bundle.d.ts

@@ -5,10 +5,17 @@ import type { SharedWorldEvidence } from "./shared-world-evidence.js";
 import { type RunStudyProvenance } from "./study-provenance.js";
 import type { RunInterruptSignal } from "./status.js";
 import type { RunSimulationStatus, RunStream, RunStreamKind } from "./streams.js";
-/** The run bundle version this release writes: each stream's trace is a file run.json indexes. */
-export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v2";
+/**
+ * The run bundle version this release writes: each stream's trace, and each running participant's
+ * items so far, are files run.json indexes.
+ */
+export declare const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v3";
+/** The version 0.123.0 and 0.124.0 wrote, with a running participant's items inline. It is still read. */
+export declare const RUN_BUNDLE_V2_SCHEMA = "humanish.run-bundle.v2";
 /** The version 0.122.0 and earlier wrote, with every trace inline. It is still read. */
 export declare const RUN_BUNDLE_V1_SCHEMA = "humanish.run-bundle.v1";
+/** Whether `value` names a run bundle version this release reads: v3, v2 or v1. */
+export declare function isReadRunBundleSchema(value: unknown): value is RunBundle["schema"];
 /** The run bundle file, relative to the run directory. */
 export declare const RUN_BUNDLE_FILE = "run.json";
 export declare const REVIEW_SCHEMA = "humanish.review.v1";
@@ -231,7 +238,7 @@ export interface RunBundle {
         restrictions: ["real-communications"];
     };
     commsReceiving?: CommsReceivingEvidence;
-    schema: typeof RUN_BUNDLE_SCHEMA | typeof RUN_BUNDLE_V1_SCHEMA;
+    schema: typeof RUN_BUNDLE_SCHEMA | typeof RUN_BUNDLE_V2_SCHEMA | typeof RUN_BUNDLE_V1_SCHEMA;
     runId: string;
     mode: "dry-run" | "live";
     simCount: number;

package/dist/run/bundle.js

@@ -1,10 +1,19 @@
 import path from "node:path";
 import { captureGitState } from "./git-state.js";
 import { studyFields } from "./study-provenance.js";
-/** The run bundle version this release writes: each stream's trace is a file run.json indexes. */
-export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v2";
+/**
+ * The run bundle version this release writes: each stream's trace, and each running participant's
+ * items so far, are files run.json indexes.
+ */
+export const RUN_BUNDLE_SCHEMA = "humanish.run-bundle.v3";
+/** The version 0.123.0 and 0.124.0 wrote, with a running participant's items inline. It is still read. */
+export const RUN_BUNDLE_V2_SCHEMA = "humanish.run-bundle.v2";
 /** The version 0.122.0 and earlier wrote, with every trace inline. It is still read. */
 export const RUN_BUNDLE_V1_SCHEMA = "humanish.run-bundle.v1";
+/** Whether `value` names a run bundle version this release reads: v3, v2 or v1. */
+export function isReadRunBundleSchema(value) {
+    return (value === RUN_BUNDLE_SCHEMA || value === RUN_BUNDLE_V2_SCHEMA || value === RUN_BUNDLE_V1_SCHEMA);
+}
 /** The run bundle file, relative to the run directory. */
 export const RUN_BUNDLE_FILE = "run.json";
 export const REVIEW_SCHEMA = "humanish.review.v1";

package/dist/run/contained-output.d.ts

@@ -46,6 +46,21 @@ export declare function writeContainedOutputFile(rootInput: PreparedOutputRoot,
  * writeContainedOutputFile renames a finished file into place instead, replacing what is there.
  */
 export declare function createContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
+/**
+ * Appends `data` to an existing single-link regular file inside the root that holds exactly
+ * `size` bytes, the count the caller says it wrote, so an append never lands after bytes the
+ * caller did not write. The checks writeContainedOutputFile makes run before the open; the opened
+ * file must be the one checked, and the root and its folders are checked again before the write.
+ * The data is synced before this resolves, so a run.json written after it never indexes bytes the
+ * disk may not hold.
+ */
+export declare function appendContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: Uint8Array, size: number): Promise<void>;
+/**
+ * Removes a single-link regular file or an empty folder inside the root. Nothing at the path, or a
+ * folder on it missing, is not an error. A link, a hard-linked file or a folder that holds anything
+ * is refused and kept.
+ */
+export declare function removeContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<void>;
 /**
  * A file in a run directory or a preflight journal. verify reads every run file whole to scan it,
  * and a frame whole to check it, so this covers the largest screenshot src/evidence/image.ts
@@ -99,6 +114,13 @@ export declare function readContainedRegularFile(rootInput: PreparedOutputRoot,
  * after it was opened is never read whole.
  */
 export declare function readOpenedAtMost(handle: FileHandle, maxBytes: number): Promise<Buffer | null>;
+/**
+ * The first `length` bytes of one regular file, under the checks readContainedRegularFile makes,
+ * or all of a file that holds fewer. Bytes past `length`, such as a later append, are not read.
+ */
+export declare function readContainedPrefix(rootInput: PreparedOutputRoot, relativePath: string, length: number): Promise<ContainedRead>;
+/** The first `length` bytes of an opened file, read by position, or all of a shorter one. */
+export declare function readOpenedPrefix(handle: FileHandle, length: number): Promise<Buffer>;
 /** The caller owns this checked descriptor and must close it after reading/streaming. */
 export declare function openContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<FileHandle | null>;
 export declare function assertSafeOutputPathSegment(value: string, label?: string): void;

package/dist/run/contained-output.js

@@ -1,5 +1,5 @@
 import { constants } from "node:fs";
-import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { lstat, mkdir, open, realpath, rename, rmdir, unlink, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { assertDirectoryIdentity, assertRegularFileOrMissing, isPathInside, prepareHumanishStorageDirectory, resolveExistingHumanishStorageDirectory, validatePreparedRunArtifactPaths, validatePreparedRunRootIdentity, } from "./paths.js";
@@ -150,6 +150,70 @@ export async function createContainedOutputFile(rootInput, relativePath, data) {
     }
     await handle.close();
 }
+/**
+ * Appends `data` to an existing single-link regular file inside the root that holds exactly
+ * `size` bytes, the count the caller says it wrote, so an append never lands after bytes the
+ * caller did not write. The checks writeContainedOutputFile makes run before the open; the opened
+ * file must be the one checked, and the root and its folders are checked again before the write.
+ * The data is synced before this resolves, so a run.json written after it never indexes bytes the
+ * disk may not hold.
+ */
+export async function appendContainedOutputFile(rootInput, relativePath, data, size) {
+    const filePath = await prepareContainedOutputFile(rootInput, relativePath);
+    const root = await resolveOutputRoot(rootInput);
+    await assertContainedDirectoryChain(root, path.dirname(filePath));
+    const before = await lstat(filePath, { bigint: true });
+    if (!before.isFile() || before.nlink > 1n)
+        throw new Error(`${relativePath} is not a single-link regular file.`);
+    // O_NONBLOCK: a file swapped for a FIFO after the lstat fails the open at once (no reader), where
+    // a blocking open would wait for a reader and hold up every later write in the run's queue.
+    // Writes to a regular file ignore it.
+    const handle = await open(filePath, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const after = await handle.stat({ bigint: true });
+        if (!after.isFile() || after.nlink > 1n || after.dev !== before.dev || after.ino !== before.ino)
+            throw new Error(`${relativePath} changed while it was opened.`);
+        if (after.size !== BigInt(size))
+            throw new Error(`${relativePath} holds ${after.size} bytes, not ${size}.`);
+        if ((await resolveOutputRoot(rootInput)) !== root)
+            throw new Error("Output root changed after it was prepared.");
+        await assertContainedDirectoryChain(root, path.dirname(filePath));
+        const { bytesWritten } = await handle.write(data, 0, data.length);
+        if (bytesWritten !== data.length)
+            throw new Error(`${relativePath} was not appended in full.`);
+        await handle.datasync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Removes a single-link regular file or an empty folder inside the root. Nothing at the path, or a
+ * folder on it missing, is not an error. A link, a hard-linked file or a folder that holds anything
+ * is refused and kept.
+ */
+export async function removeContainedOutputFile(rootInput, relativePath) {
+    assertSafeRelativeOutputPath(relativePath, false);
+    const root = await resolveOutputRoot(rootInput);
+    const candidate = path.resolve(root, normalizeRelativeOutputPath(relativePath));
+    if (!isPathInside(root, candidate) || candidate === root)
+        throw new Error("Output file must stay inside its selected root.");
+    let stats;
+    try {
+        await assertContainedDirectoryChain(root, path.dirname(candidate));
+        stats = await lstat(candidate, { bigint: true });
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (stats.isDirectory())
+        return rmdir(candidate);
+    if (!stats.isFile() || stats.nlink > 1n)
+        throw new Error(`${relativePath} is not a single-link regular file.`);
+    await unlink(candidate);
+}
 // The most humanish reads of one file of each kind. A larger file is refused unread.
 /**
  * A file in a run directory or a preflight journal. verify reads every run file whole to scan it,
@@ -240,6 +304,38 @@ export async function readOpenedAtMost(handle, maxBytes) {
         chunks.push(chunk.subarray(0, bytesRead));
     }
 }
+/**
+ * The first `length` bytes of one regular file, under the checks readContainedRegularFile makes,
+ * or all of a file that holds fewer. Bytes past `length`, such as a later append, are not read.
+ */
+export async function readContainedPrefix(rootInput, relativePath, length) {
+    const opened = await openContained(rootInput, relativePath);
+    if (opened.status === "missing")
+        return opened;
+    if (opened.status === "refused")
+        return { status: "refused", reason: opened.reason, limit: length };
+    try {
+        return { status: "read", bytes: await readOpenedPrefix(opened.handle, length) };
+    }
+    catch {
+        return { status: "refused", reason: "unreadable", limit: length };
+    }
+    finally {
+        await opened.handle.close().catch(() => { });
+    }
+}
+/** The first `length` bytes of an opened file, read by position, or all of a shorter one. */
+export async function readOpenedPrefix(handle, length) {
+    const bytes = Buffer.allocUnsafe(length);
+    let total = 0;
+    while (total < length) {
+        const { bytesRead } = await handle.read(bytes, total, length - total, total);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return bytes.subarray(0, total);
+}
 /** The caller owns this checked descriptor and must close it after reading/streaming. */
 export async function openContainedRegularFile(rootInput, relativePath) {
     const opened = await openContained(rootInput, relativePath);

package/dist/run/evidence-files.d.ts

@@ -1,3 +1,4 @@
+import { type BigIntStats } from "node:fs";
 import { type PreparedOutputRoot } from "./contained-output.js";
 /**
  * Analysis inputs are retained local artifacts, never URLs or caller-selected outputs. The path is
@@ -17,6 +18,8 @@ export declare function decodesToPlainRelativePath(value: string, maxLength: num
  * authority to select another file or initiate a network request.
  */
 export declare function readBoundedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<Buffer | null>;
+/** The fields of a file's lstat that sameFile compares: which file it is, its size and times. */
+export type FileStamp = Pick<BigIntStats, "dev" | "ino" | "size" | "mtimeNs" | "ctimeNs">;
 /**
  * After a bounded read returned nothing: true when the file is absent, false when something is
  * there that could not be read. Errors other than ENOENT propagate.
@@ -25,6 +28,7 @@ export declare function pathMissing(filePath: string): Promise<boolean>;
 export type BoundedFileResult = {
     state: "read";
     bytes: Buffer;
+    stamp: FileStamp;
 } | {
     state: "limit";
     size: bigint;
@@ -37,6 +41,13 @@ export declare function readBoundedFileResult(root: PreparedOutputRoot, relative
  * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
  * same size and times, from the first check to the last. Size refusals are distinguished only after
  * the same checks. `relativePath` uses `/`, and any name a contained read accepts
- * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did. A read
+ * returns the stamp it held the file to.
  */
 export declare function readUnchangedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;
+/**
+ * True when the file readUnchangedFile would read at `relativePath` is still the file `stamp`
+ * describes: it passes the same root, parent and leaf checks, before and after its lstat matches
+ * the stamp. Opens nothing.
+ */
+export declare function isUnchangedFile(root: PreparedOutputRoot, relativePath: string, stamp: FileStamp): Promise<boolean>;

package/dist/run/evidence-files.js

@@ -99,47 +99,19 @@ export async function readBoundedFileResult(root, relativePath, maxBytes) {
  * At most `maxBytes` of a contained single-link regular file that stays the same file, with the
  * same size and times, from the first check to the last. Size refusals are distinguished only after
  * the same checks. `relativePath` uses `/`, and any name a contained read accepts
- * (isSafeRelativeFilePath) is read: verify and export read the names they always did.
+ * (isSafeRelativeFilePath) is read: verify and export read the names they always did. A read
+ * returns the stamp it held the file to.
  */
 export async function readUnchangedFile(root, relativePath, maxBytes) {
-    if (!isSafeRelativeFilePath(relativePath) ||
-        relativePath.includes("\\") ||
-        !Number.isSafeInteger(maxBytes) ||
-        maxBytes < 1)
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
         return unavailable;
-    const validateRoot = async () => {
-        if ("physicalRunRoot" in root) {
-            await validatePreparedRunRootIdentity(root);
-            return root.physicalRunRoot;
-        }
-        await assertPreparedSelectedOutputDirectory(root);
-        return root.physicalPath;
-    };
     try {
-        const physicalRoot = await validateRoot();
-        const candidate = path.join(physicalRoot, relativePath);
-        if (!isPathInside(physicalRoot, candidate) || candidate === physicalRoot)
-            return unavailable;
-        const validateParents = async () => {
-            let current = physicalRoot;
-            for (const segment of relativePath.split("/").slice(0, -1)) {
-                current = path.join(current, segment);
-                const info = await lstat(current);
-                if (!info.isDirectory() || info.isSymbolicLink())
-                    throw new Error("Unsafe analysis input directory.");
-            }
-        };
-        await validateParents();
-        const before = await lstat(candidate, { bigint: true });
-        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n)
-            return unavailable;
-        if ((await realpath(candidate)) !== candidate)
+        const located = await locateContainedFile(root, relativePath);
+        if (located === null)
             return unavailable;
+        const { candidate, before, stillSameFile } = located;
         if (before.size > BigInt(maxBytes)) {
-            if ((await validateRoot()) !== physicalRoot)
-                return unavailable;
-            await validateParents();
-            if (!sameFile(before, await lstat(candidate, { bigint: true })))
+            if (!(await stillSameFile(before)))
                 return unavailable;
             return { state: "limit", size: before.size };
         }
@@ -153,12 +125,10 @@ export async function readUnchangedFile(root, relativePath, maxBytes) {
                 !sameFile(before, await handle.stat({ bigint: true })) ||
                 bytes.length !== Number(before.size))
                 return unavailable;
-            if ((await validateRoot()) !== physicalRoot)
-                return unavailable;
-            await validateParents();
-            if (!sameFile(before, await lstat(candidate, { bigint: true })))
+            if (!(await stillSameFile(before)))
                 return unavailable;
-            return { state: "read", bytes };
+            const { dev, ino, size, mtimeNs, ctimeNs } = before;
+            return { state: "read", bytes, stamp: { dev, ino, size, mtimeNs, ctimeNs } };
         }
         finally {
             await handle.close();
@@ -168,3 +138,63 @@ export async function readUnchangedFile(root, relativePath, maxBytes) {
         return unavailable;
     }
 }
+/**
+ * True when the file readUnchangedFile would read at `relativePath` is still the file `stamp`
+ * describes: it passes the same root, parent and leaf checks, before and after its lstat matches
+ * the stamp. Opens nothing.
+ */
+export async function isUnchangedFile(root, relativePath, stamp) {
+    try {
+        const located = await locateContainedFile(root, relativePath);
+        return (located !== null && sameFile(stamp, located.before) && (await located.stillSameFile(stamp)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The contained single-link regular file at `relativePath`: its path, its lstat, and a recheck that
+ * the root, its parents and the leaf are unchanged since. Null for a path or leaf a read refuses;
+ * a root or parent that fails its check throws.
+ */
+async function locateContainedFile(root, relativePath) {
+    if (!isSafeRelativeFilePath(relativePath) || relativePath.includes("\\"))
+        return null;
+    const validateRoot = async () => {
+        if ("physicalRunRoot" in root) {
+            await validatePreparedRunRootIdentity(root);
+            return root.physicalRunRoot;
+        }
+        await assertPreparedSelectedOutputDirectory(root);
+        return root.physicalPath;
+    };
+    const physicalRoot = await validateRoot();
+    const candidate = path.join(physicalRoot, relativePath);
+    if (!isPathInside(physicalRoot, candidate) || candidate === physicalRoot)
+        return null;
+    const validateParents = async () => {
+        let current = physicalRoot;
+        for (const segment of relativePath.split("/").slice(0, -1)) {
+            current = path.join(current, segment);
+            const info = await lstat(current);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                throw new Error("Unsafe analysis input directory.");
+        }
+    };
+    await validateParents();
+    const before = await lstat(candidate, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n)
+        return null;
+    if ((await realpath(candidate)) !== candidate)
+        return null;
+    return {
+        candidate,
+        before,
+        stillSameFile: async (stamp) => {
+            if ((await validateRoot()) !== physicalRoot)
+                return false;
+            await validateParents();
+            return sameFile(stamp, await lstat(candidate, { bigint: true }));
+        },
+    };
+}

package/dist/run/live-items.d.ts

@@ -0,0 +1,48 @@
+import type { ActorTraceItem } from "../actors/contract.js";
+import type { RunEvent } from "./bundle.js";
+import { type PreparedOutputRoot } from "./contained-output.js";
+import type { LiveItemsIndex, RunStream } from "./streams.js";
+/** The live actor of a v3 run.json, whose items are in the file `itemsFile` names. */
+export declare const LIVE_ACTOR_SCHEMA = "humanish.live-actor.v2";
+/** The live actor of v1 and v2 run.json, with its items inline. */
+export declare const LIVE_ACTOR_V1_SCHEMA = "humanish.live-actor.v1";
+/** Whether `value` is a live items index naming a live file name and its own generation. */
+export declare function isLiveItemsIndex(value: unknown): value is LiveItemsIndex;
+/**
+ * The items the indexed prefix of a live file holds, or why the bytes do not match the index:
+ * `bytes` must be exactly the indexed byte count, hash to the indexed sha256, and hold the indexed
+ * number of lines, each a JSON object.
+ */
+export declare function liveItemsFromBytes(bytes: Buffer, index: LiveItemsIndex): {
+    items: ActorTraceItem[];
+} | {
+    refused: string;
+};
+/** One run's live files: what each stream position's current generation holds. */
+export interface LiveItemsWriter {
+    /**
+     * `streams` with each running participant's items in its live file: every `liveActor` that
+     * carries `items` becomes humanish.live-actor.v2 with `itemsFile` in their place. A `liveActor`
+     * that already carries `itemsFile` (a bundle built from a run.json this writer wrote) stands for
+     * the list this writer last wrote for its position, and gets the same checks; any other index
+     * (another position's file, an earlier generation, a file this writer did not write) rejects the
+     * write, since the writer can vouch for and scan only its own files. Items past what the participant's current
+     * generation holds are appended, each through publicSandboxView with `sandboxIds`; a new
+     * generation holding the full list starts when appending cannot keep the file equal to the list.
+     * Every byte is on disk when this resolves, so a run.json written after it indexes nothing
+     * missing. Call `published` once run.json naming the returned streams is written: it removes
+     * every superseded generation those streams do not name, including the file of a stream that no
+     * longer carries live items. A generation whose removal fails, or whose write's run.json failed
+     * so `published` never ran, is removed by the next `published`. `events` is the one warn event
+     * the run records once a participant's generation was replaced on two writes in a row, from that
+     * write on; empty until then.
+     */
+    write(streams: readonly RunStream[], sandboxIds: readonly string[]): Promise<{
+        streams: RunStream[];
+        events: RunEvent[];
+        published: () => Promise<void>;
+    }>;
+    /** Remove every live file this writer created, and live/ once empty: after the final run.json. */
+    remove(): Promise<void>;
+}
+export declare function liveItemsWriter(root: PreparedOutputRoot): LiveItemsWriter;