humanish 0.113.0 → 0.115.0

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

@@ -38,6 +38,14 @@ export declare function prepareContainedOutputDirectory(rootInput: PreparedOutpu
 export declare function prepareContainedOutputDirectoryRoot(rootInput: PreparedOutputRoot, relativePath: string): Promise<PreparedSelectedOutputDirectory>;
 export declare function prepareContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<string>;
 export declare function writeContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string | Uint8Array, encoding?: BufferEncoding): Promise<void>;
+/**
+ * Creates a new file inside the root under its final name, refusing with EEXIST when that name
+ * exists, so it never replaces a file. The file is opened with O_EXCL and O_NOFOLLOW, filled in one
+ * write and synced, so a reader may briefly see it empty or short. It never has a temporary name or
+ * a second link, so the run directory passes its single-link check at every moment.
+ * writeContainedOutputFile renames a finished file into place instead, replacing what is there.
+ */
+export declare function createContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
 /** Read one regular file only when both lexical and physical paths stay in root. */
 export declare function readContainedRegularFile(rootInput: PreparedOutputRoot, relativePath: string): Promise<Buffer | null>;
 /**

package/dist/run/contained-output.js

@@ -123,6 +123,33 @@ export async function writeContainedOutputFile(rootInput, relativePath, data, en
         await assertRegularFileOrMissing(filePath, "Selected output files");
     });
 }
+/**
+ * Creates a new file inside the root under its final name, refusing with EEXIST when that name
+ * exists, so it never replaces a file. The file is opened with O_EXCL and O_NOFOLLOW, filled in one
+ * write and synced, so a reader may briefly see it empty or short. It never has a temporary name or
+ * a second link, so the run directory passes its single-link check at every moment.
+ * writeContainedOutputFile renames a finished file into place instead, replacing what is there.
+ */
+export async function createContainedOutputFile(rootInput, relativePath, data) {
+    const filePath = await prepareContainedOutputFile(rootInput, relativePath);
+    const root = await resolveOutputRoot(rootInput);
+    await assertContainedDirectoryChain(root, path.dirname(filePath));
+    const bytes = Buffer.from(data, "utf8");
+    const handle = await open(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        const { bytesWritten } = await handle.write(bytes, 0, bytes.length, 0);
+        if (bytesWritten !== bytes.length)
+            throw new Error("The file was not written in full.");
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        // O_EXCL created this name here, so removing it removes only this file.
+        await unlink(filePath).catch(() => undefined);
+        throw error;
+    }
+    await handle.close();
+}
 /** Read one regular file only when both lexical and physical paths stay in root. */
 export async function readContainedRegularFile(rootInput, relativePath) {
     const handle = await openContainedRegularFile(rootInput, relativePath);

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

@@ -1,3 +1,4 @@
+import { type FileHandle } from "node:fs/promises";
 import { type PreparedOutputRoot } from "./contained-output.js";
 /**
  * Analysis inputs are retained local artifacts, never URLs or caller-selected outputs. The path is
@@ -22,6 +23,12 @@ export declare function readBoundedFile(root: PreparedOutputRoot, relativePath:
  * there that could not be read. Errors other than ENOENT propagate.
  */
 export declare function pathMissing(filePath: string): Promise<boolean>;
+/**
+ * At most `maxBytes` from the start of an opened file, or null when it holds more. It reads by
+ * position, in chunks of up to 64 KiB, and stops one byte past the limit, so a file that grew
+ * after it was opened is never read whole.
+ */
+export declare function readOpenedAtMost(handle: FileHandle, maxBytes: number): Promise<Buffer | null>;
 export type BoundedFileResult = {
     state: "read";
     bytes: Buffer;

package/dist/run/evidence-files.js

@@ -87,6 +87,25 @@ export async function pathMissing(filePath) {
         throw error;
     }
 }
+/**
+ * At most `maxBytes` from the start of an opened file, or null when it holds more. It reads by
+ * position, in chunks of up to 64 KiB, and stops one byte past the limit, so a file that grew
+ * after it was opened is never read whole.
+ */
+export async function readOpenedAtMost(handle, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+        if (bytesRead === 0)
+            return Buffer.concat(chunks, total);
+        total += bytesRead;
+        if (total > maxBytes)
+            return null;
+        chunks.push(chunk.subarray(0, bytesRead));
+    }
+}
 const unavailable = { state: "unavailable" };
 /** Size refusals are distinguished only after the same contained regular-file checks. */
 export async function readBoundedFileResult(root, relativePath, maxBytes) {
@@ -133,26 +152,17 @@ export async function readBoundedFileResult(root, relativePath, maxBytes) {
         try {
             if (!sameFile(before, await handle.stat({ bigint: true })))
                 return unavailable;
-            const chunks = [];
-            let total = 0;
-            while (total <= maxBytes) {
-                const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1 - total));
-                const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
-                if (bytesRead === 0)
-                    break;
-                total += bytesRead;
-                if (total > maxBytes)
-                    return unavailable;
-                chunks.push(chunk.subarray(0, bytesRead));
-            }
-            if (!sameFile(before, await handle.stat({ bigint: true })) || total !== Number(before.size))
+            const bytes = await readOpenedAtMost(handle, maxBytes);
+            if (bytes === null ||
+                !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 })))
                 return unavailable;
-            return { state: "read", bytes: Buffer.concat(chunks, total) };
+            return { state: "read", bytes };
         }
         finally {
             await handle.close();

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

@@ -0,0 +1,54 @@
+import { type RunNote } from "./note-shape.js";
+import { type PreparedRunArtifactPaths } from "./paths.js";
+export declare const RUN_NOTES_DIR = "notes";
+/** The bytes one note file may hold: 2000 characters of text with JSON escapes, and its fields. */
+export declare const MAX_NOTE_FILE_BYTES: number;
+/** A run's notes as read, in the order they were added, and why any file was skipped. */
+export interface RunNotes {
+    runId: string;
+    notes: RunNote[];
+    skipped: string[];
+}
+/** A new note id: `note-<creation time>-<48 random bits>`, such as `note-20261007t214500123z-…`. */
+export declare function newRunNoteId(createdAt: Date): string;
+/** The note's file, relative to the run directory. */
+export declare function runNoteFile(id: string): string;
+/** The note as its file holds it. */
+export declare function encodeRunNote(note: RunNote, runId: string): string;
+/** How many note files notes/ lists, without reading any. Throws when notes/ is unusable. */
+export declare function countRunNotes(prepared: PreparedRunArtifactPaths): Promise<number>;
+/**
+ * Where a run's notes are read from: the run's id, its directory, and a reader of the files under
+ * it that refuses a link or a special file and stops at `maxBytes`.
+ */
+export interface RunNoteFiles {
+    readonly runId: string;
+    /** The run directory's physical path, once it is checked to be the directory bound. Throws otherwise. */
+    directory(): Promise<string>;
+    /** A file under the run directory: its bytes, "limit" when it holds more than `maxBytes`, or null. */
+    read(relativePath: string, maxBytes: number): Promise<Buffer | "limit" | null>;
+}
+/**
+ * The run's notes, read from its prepared paths through the bounded reader or through `from`, the
+ * files of a run the caller already holds (the served Observer passes its pinned root's). Each file
+ * is read within MAX_NOTE_FILE_BYTES; a file the reader refuses, or that is not a note of this run,
+ * is skipped and named in `skipped`.
+ */
+export declare function readRunNotes(from: PreparedRunArtifactPaths | RunNoteFiles): Promise<RunNotes>;
+/** What verify's text scan finds in notes about to be shared, and the share safety that gives them. */
+export interface NotesSharingProblem {
+    status: "local_only" | "blocked";
+    reason: {
+        code: "PUBLIC_SAFETY_FINDINGS" | "UNSCANNED_ARTIFACT";
+        message: string;
+    };
+}
+/**
+ * The run's notes as a caller is about to share them, read once, with what verify's text scan
+ * finds in that set as it would be shared. The caller shares this set only, so a note added or
+ * changed after verify ran cannot go out unchecked.
+ */
+export declare function readNotesForSharing(prepared: PreparedRunArtifactPaths): Promise<{
+    notes: RunNotes;
+    problem: NotesSharingProblem | null;
+}>;

package/dist/run/note-files.js

@@ -0,0 +1,212 @@
+// Reviewer notes on disk: one file per note, notes/<id>.json (humanish.run-note.v1) in the run
+// directory. A note is written once, by creating its name only when nothing holds it, and is never
+// rewritten, so a writer never reads or replaces another writer's note and no lock is needed. An
+// id starts with its creation time, so the files sort in the order they were added, and ends in
+// random bits. Readers list notes/ and read each file within MAX_NOTE_FILE_BYTES, skipping and
+// naming anything that is not a readable note of the run, including a note still being written.
+import { randomBytes } from "node:crypto";
+import { lstat, opendir } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { scanEncodedTextCached } from "../evidence/encoded-text.js";
+import { readBoundedFileResult } from "./evidence-files.js";
+import { MAX_NOTE_TEXT, MAX_RUN_NOTES, NOTE_FIELD_LIMITS, NOTE_ID, } from "./note-shape.js";
+import { runIdOf, validatePreparedRunRootIdentity, } from "./paths.js";
+import { isNodeError } from "./type-guards.js";
+const RUN_NOTE_SCHEMA = "humanish.run-note.v1";
+export const RUN_NOTES_DIR = "notes";
+/** The bytes one note file may hold: 2000 characters of text with JSON escapes, and its fields. */
+export const MAX_NOTE_FILE_BYTES = 16 * 1024;
+/** The entries a reader lists in notes/ before it stops. */
+const MAX_LISTED_ENTRIES = 2 * MAX_RUN_NOTES;
+/** A temporary file of the atomic writer, or one a 0.114.0 note writer left. Never a note. */
+const WRITE_IN_PROGRESS = /^\.humanish-write-/;
+const text = (max) => z.string().min(1).max(max);
+const timestamp = text(NOTE_FIELD_LIMITS.timestamp).refine((value) => Number.isFinite(Date.parse(value)));
+/** A note file. Fields a later release adds are dropped on reading, so they never hide a note. */
+const runNoteFileSchema = z.object({
+    schema: z.literal(RUN_NOTE_SCHEMA),
+    runId: z.string(),
+    id: z.string().regex(NOTE_ID),
+    atMs: z.int().min(0),
+    participant: text(NOTE_FIELD_LIMITS.participant).nullable(),
+    nearest: z
+        .object({
+        participant: text(NOTE_FIELD_LIMITS.participant),
+        itemId: text(NOTE_FIELD_LIMITS.itemId),
+    })
+        .nullable(),
+    text: text(MAX_NOTE_TEXT),
+    author: text(NOTE_FIELD_LIMITS.author),
+    createdAt: timestamp,
+    editedAt: timestamp.nullable(),
+});
+/** A new note id: `note-<creation time>-<48 random bits>`, such as `note-20261007t214500123z-…`. */
+export function newRunNoteId(createdAt) {
+    const stamp = createdAt.toISOString().replace(/[-:.]/g, "").toLowerCase();
+    return `note-${stamp}-${randomBytes(6).toString("hex")}`;
+}
+/** The note's file, relative to the run directory. */
+export function runNoteFile(id) {
+    return `${RUN_NOTES_DIR}/${id}.json`;
+}
+/** The note as its file holds it. */
+export function encodeRunNote(note, runId) {
+    return `${JSON.stringify({ schema: RUN_NOTE_SCHEMA, runId, ...note }, null, 2)}\n`;
+}
+/** The note in a note file's bytes, when it is a note of `runId` stored under its own `id`. */
+function decodeRunNote(bytes, runId, id) {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    const parsed = runNoteFileSchema.safeParse(value);
+    if (!parsed.success || parsed.data.runId !== runId || parsed.data.id !== id)
+        return null;
+    const { schema: _schema, runId: _runId, ...note } = parsed.data;
+    return note;
+}
+/**
+ * Up to MAX_LISTED_ENTRIES names in the notes directory at `dir`, or null when there is none.
+ * Throws when `dir` is there and is not a plain directory.
+ */
+async function listNoteEntries(dir) {
+    try {
+        const stats = await lstat(dir);
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            throw new Error("The notes entry is not a directory.");
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const names = [];
+    const listing = await opendir(dir);
+    try {
+        for await (const entry of listing) {
+            if (names.length === MAX_LISTED_ENTRIES)
+                return { names, truncated: true };
+            names.push(entry.name);
+        }
+    }
+    finally {
+        await listing.close().catch(() => undefined);
+    }
+    return { names, truncated: false };
+}
+/** The note ids to read from a listing of notes/, in creation order, and what was left out. */
+function noteListing(listing) {
+    const ids = [];
+    const skipped = [];
+    for (const name of listing.names) {
+        if (WRITE_IN_PROGRESS.test(name))
+            continue;
+        const id = name.endsWith(".json") ? name.slice(0, -".json".length) : "";
+        if (NOTE_ID.test(id))
+            ids.push(id);
+        else
+            skipped.push(`${RUN_NOTES_DIR}/${name} is not a note file, so it was skipped.`);
+    }
+    ids.sort();
+    if (listing.truncated)
+        skipped.push(`${RUN_NOTES_DIR}/ holds more than ${MAX_LISTED_ENTRIES} entries; only the first ${MAX_LISTED_ENTRIES} were listed.`);
+    if (ids.length > MAX_RUN_NOTES) {
+        const left = ids.length - MAX_RUN_NOTES;
+        skipped.push(`${left} note${left === 1 ? "" : "s"} after the first ${MAX_RUN_NOTES} ${left === 1 ? "was" : "were"} not read.`);
+        ids.length = MAX_RUN_NOTES;
+    }
+    return { ids, skipped };
+}
+/** How many note files notes/ lists, without reading any. Throws when notes/ is unusable. */
+export async function countRunNotes(prepared) {
+    const listing = await listNoteEntries(path.join(prepared.physicalRunRoot, RUN_NOTES_DIR));
+    return listing === null ? 0 : noteListing(listing).ids.length + (listing.truncated ? 1 : 0);
+}
+/** The run's note files through the bounded reader, which rechecks the run directory on each read. */
+function boundedNoteFiles(prepared) {
+    return {
+        runId: runIdOf(prepared),
+        async directory() {
+            await validatePreparedRunRootIdentity(prepared);
+            return prepared.physicalRunRoot;
+        },
+        async read(relativePath, maxBytes) {
+            const read = await readBoundedFileResult(prepared, relativePath, maxBytes);
+            return read.state === "read" ? read.bytes : read.state === "limit" ? "limit" : null;
+        },
+    };
+}
+/**
+ * The run's notes, read from its prepared paths through the bounded reader or through `from`, the
+ * files of a run the caller already holds (the served Observer passes its pinned root's). Each file
+ * is read within MAX_NOTE_FILE_BYTES; a file the reader refuses, or that is not a note of this run,
+ * is skipped and named in `skipped`.
+ */
+export async function readRunNotes(from) {
+    const files = "physicalRunRoot" in from ? boundedNoteFiles(from) : from;
+    const { runId } = files;
+    let listing;
+    try {
+        listing = await listNoteEntries(path.join(await files.directory(), RUN_NOTES_DIR));
+    }
+    catch {
+        return {
+            runId,
+            notes: [],
+            skipped: [`${RUN_NOTES_DIR} in run ${runId} is not a plain folder, so no notes were read.`],
+        };
+    }
+    if (listing === null)
+        return { runId, notes: [], skipped: [] };
+    const { ids, skipped } = noteListing(listing);
+    const notes = [];
+    for (const id of ids) {
+        const read = await files.read(runNoteFile(id), MAX_NOTE_FILE_BYTES);
+        const note = Buffer.isBuffer(read) ? decodeRunNote(read, runId, id) : null;
+        if (note !== null)
+            notes.push(note);
+        else
+            skipped.push(read === "limit"
+                ? `${runNoteFile(id)} is over ${MAX_NOTE_FILE_BYTES / 1024} KiB, so it was skipped.`
+                : `${runNoteFile(id)} is not a readable note of run ${runId}, so it was skipped.`);
+    }
+    return { runId, notes, skipped };
+}
+/**
+ * The run's notes as a caller is about to share them, read once, with what verify's text scan
+ * finds in that set as it would be shared. The caller shares this set only, so a note added or
+ * changed after verify ran cannot go out unchecked.
+ */
+export async function readNotesForSharing(prepared) {
+    const notes = await readRunNotes(prepared);
+    if (notes.notes.length === 0)
+        return { notes, problem: null };
+    const scan = scanEncodedTextCached(JSON.stringify(notes.notes));
+    if (scan.sensitive)
+        return {
+            notes,
+            problem: {
+                status: "blocked",
+                reason: {
+                    code: "PUBLIC_SAFETY_FINDINGS",
+                    message: "The reviewer notes being shared match secret, token or local-path patterns.",
+                },
+            },
+        };
+    if (scan.opaque)
+        return {
+            notes,
+            problem: {
+                status: "local_only",
+                reason: {
+                    code: "UNSCANNED_ARTIFACT",
+                    message: "The reviewer notes being shared hold encoded text the scan cannot read.",
+                },
+            },
+        };
+    return { notes, problem: null };
+}

package/dist/run/note-shape.d.ts

@@ -0,0 +1,35 @@
+/** The characters a note's text may hold. */
+export declare const MAX_NOTE_TEXT = 2000;
+/** The notes one run keeps. A reader reads this many and names the rest. */
+export declare const MAX_RUN_NOTES = 500;
+/** The characters of a participant id, a trace item id or a timestamp a note records. */
+export declare const NOTE_FIELD_LIMITS: {
+    participant: number;
+    itemId: number;
+    author: number;
+    timestamp: number;
+};
+/** A note id: `note-<creation time>-<48 random bits in hex>`. */
+export declare const NOTE_ID: RegExp;
+/** Where an Observer page sends a note to the loopback server that rendered it. */
+export declare const NOTES_PATH = "/api/notes";
+/** The request header that carries the server's note token. */
+export declare const NOTES_TOKEN_HEADER = "x-humanish-notes-token";
+export interface RunNote {
+    id: string;
+    /** Milliseconds from the run clock's start. */
+    atMs: number;
+    /** The participant's stream id, or null for a note on the whole run. */
+    participant: string | null;
+    /** The latest timed capture or event at or before the moment, with its participant. */
+    nearest: {
+        participant: string;
+        itemId: string;
+    } | null;
+    text: string;
+    author: string;
+    createdAt: string;
+    editedAt: string | null;
+}
+/** Notes in run clock order, the earliest added first at the same moment. */
+export declare function byRunTime(notes: readonly RunNote[]): RunNote[];

package/dist/run/note-shape.js

@@ -0,0 +1,20 @@
+// A reviewer note as the server keeps it and the Observer shows it: its fields, their limits, and
+// where an Observer page sends a new one. The Observer bundles this module, so it has no runtime imports
+// (observer/tests/contract-lock.test.ts checks that); the server validates notes against these
+// limits with zod in note-files.ts and notes-route.ts.
+/** The characters a note's text may hold. */
+export const MAX_NOTE_TEXT = 2000;
+/** The notes one run keeps. A reader reads this many and names the rest. */
+export const MAX_RUN_NOTES = 500;
+/** The characters of a participant id, a trace item id or a timestamp a note records. */
+export const NOTE_FIELD_LIMITS = { participant: 256, itemId: 256, author: 80, timestamp: 64 };
+/** A note id: `note-<creation time>-<48 random bits in hex>`. */
+export const NOTE_ID = /^note-\d{8}t\d{9}z-[0-9a-f]{12}$/;
+/** Where an Observer page sends a note to the loopback server that rendered it. */
+export const NOTES_PATH = "/api/notes";
+/** The request header that carries the server's note token. */
+export const NOTES_TOKEN_HEADER = "x-humanish-notes-token";
+/** Notes in run clock order, the earliest added first at the same moment. */
+export function byRunTime(notes) {
+    return [...notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
+}

package/dist/run/notes.d.ts

@@ -0,0 +1,34 @@
+import type { RunBundle } from "./bundle.js";
+import { type RunNote } from "./note-shape.js";
+import { type PreparedRunArtifactPaths } from "./paths.js";
+export interface RunNoteInput {
+    atMs: number;
+    participant: string | null;
+    text: string;
+}
+export type RunNoteErrorCode = "HUMANISH_INVALID_RUN_BUNDLE" | "HUMANISH_NOTE_INVALID" | "HUMANISH_NOTE_NO_CLOCK" | "HUMANISH_NOTE_UNKNOWN_PARTICIPANT" | "HUMANISH_NOTE_OUTSIDE_RUN" | "HUMANISH_NOTES_UNREADABLE" | "HUMANISH_NOTES_FULL" | "HUMANISH_NOTE_ID_TAKEN";
+export type AddRunNoteResult = 
+/** `scrubbed`: redaction replaced part of the text before it was written. */
+{
+    ok: true;
+    note: RunNote;
+    scrubbed: boolean;
+} | {
+    ok: false;
+    error: {
+        code: RunNoteErrorCode;
+        message: string;
+    };
+};
+/** A run clock time as the Observer shows it: whole minutes and seconds, `02:31`. */
+export declare function formatRunTime(ms: number): string;
+/** The run clock: the first and last timed capture or desktop video moment, in epoch ms. */
+export declare function runClock(bundle: RunBundle): {
+    startMs: number;
+    endMs: number;
+} | null;
+/**
+ * Adds a note as a new file, notes/<id>.json, created under a name nothing holds. It reads no other
+ * note and replaces nothing, so notes added at the same time, from any process, are all kept.
+ */
+export declare function addRunNote(prepared: PreparedRunArtifactPaths, input: RunNoteInput): Promise<AddRunNoteResult>;