humanish 0.114.0 → 0.115.0

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

@@ -39,12 +39,13 @@ export declare function prepareContainedOutputDirectoryRoot(rootInput: PreparedO
 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>;
 /**
- * Writes a new file inside the root without ever replacing one: the bytes go to a temporary file,
- * which link(2) then gives the final name, failing with EEXIST when that name exists, and the
- * temporary name is removed. writeContainedOutputFile renames instead, which replaces a file that
- * took the name in the meantime.
+ * 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 writeNewContainedOutputFile(rootInput: PreparedOutputRoot, relativePath: string, data: string): Promise<void>;
+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

@@ -1,5 +1,5 @@
 import { constants } from "node:fs";
-import { link, lstat, mkdir, open, realpath, rename, unlink, } from "node:fs/promises";
+import { lstat, mkdir, open, realpath, rename, 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";
@@ -124,38 +124,31 @@ export async function writeContainedOutputFile(rootInput, relativePath, data, en
     });
 }
 /**
- * Writes a new file inside the root without ever replacing one: the bytes go to a temporary file,
- * which link(2) then gives the final name, failing with EEXIST when that name exists, and the
- * temporary name is removed. writeContainedOutputFile renames instead, which replaces a file that
- * took the name in the meantime.
+ * 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 writeNewContainedOutputFile(rootInput, relativePath, data) {
+export async function createContainedOutputFile(rootInput, relativePath, data) {
     const filePath = await prepareContainedOutputFile(rootInput, relativePath);
     const root = await resolveOutputRoot(rootInput);
-    const parent = path.dirname(filePath);
-    const revalidate = async () => {
-        if ((await resolveOutputRoot(rootInput)) !== root) {
-            throw new Error("Output root changed after it was prepared.");
-        }
-        await assertContainedDirectoryChain(root, parent);
-    };
-    await revalidate();
-    const temporary = path.join(parent, `.humanish-write-${process.pid}-${randomUUID()}.tmp`);
-    let handle;
+    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 {
-        handle = await open(temporary, "wx", 0o600);
-        await handle.writeFile(data, "utf8");
+        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();
-        await handle.close();
-        handle = undefined;
-        await revalidate();
-        await link(temporary, filePath);
     }
-    finally {
-        await handle?.close().catch(() => undefined);
-        await unlink(temporary).catch(() => undefined);
+    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 assertRegularFileOrMissing(filePath, "Selected output files");
+    await handle.close();
 }
 /** Read one regular file only when both lexical and physical paths stay in root. */
 export async function readContainedRegularFile(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

@@ -1,26 +1,8 @@
+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;
-/** The notes one run keeps. A reader reads this many and names the rest. */
-export declare const MAX_RUN_NOTES = 500;
-export declare const MAX_NOTE_TEXT = 2000;
-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;
-}
 /** A run's notes as read, in the order they were added, and why any file was skipped. */
 export interface RunNotes {
     runId: string;
@@ -33,34 +15,34 @@ export declare function newRunNoteId(createdAt: Date): string;
 export declare function runNoteFile(id: string): string;
 /** The note as its file holds it. */
 export declare function encodeRunNote(note: RunNote, runId: string): string;
-/** The note in a note file's bytes, when it is a note of `runId` stored under its own `id`. */
-export declare function decodeRunNote(bytes: Buffer, runId: string, id: string): RunNote | null;
-/**
- * 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.
- */
-export declare function listNoteEntries(dir: string): Promise<{
-    names: string[];
-    truncated: boolean;
-} | null>;
-/** The note ids to read from a listing of notes/, in creation order, and what was left out. */
-export declare function noteListing(listing: {
-    names: readonly string[];
-    truncated: boolean;
-}): {
-    ids: string[];
-    skipped: string[];
-};
 /** How many note files notes/ lists, without reading any. Throws when notes/ is unusable. */
 export declare function countRunNotes(prepared: PreparedRunArtifactPaths): Promise<number>;
 /**
- * The run's notes. Each file is read through the bounded reader, which refuses a link, a special
- * file or anything over MAX_NOTE_FILE_BYTES before reading past the limit; a file it refuses, or
- * that is not a note of this run, is skipped and named in `skipped`.
+ * 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 declare function readRunNotes(prepared: PreparedRunArtifactPaths): Promise<RunNotes>;
-/** What verify's text scan finds in shared notes: a secret-shaped value, or text it cannot read. */
-type NotesFinding = "sensitive" | "opaque";
+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
@@ -68,6 +50,5 @@ type NotesFinding = "sensitive" | "opaque";
  */
 export declare function readNotesForSharing(prepared: PreparedRunArtifactPaths): Promise<{
     notes: RunNotes;
-    finding: NotesFinding | null;
+    problem: NotesSharingProblem | null;
 }>;
-export {};

package/dist/run/note-files.js

@@ -1,29 +1,46 @@
 // Reviewer notes on disk: one file per note, notes/<id>.json (humanish.run-note.v1) in the run
-// directory. A note is written once, to a temporary file that link(2) gives its name only when
-// nothing holds that name, 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.
+// 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 { runIdOf } from "./paths.js";
-import { isNodeError, isRecord } from "./type-guards.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 notes one run keeps. A reader reads this many and names the rest. */
-export const MAX_RUN_NOTES = 500;
-export const MAX_NOTE_TEXT = 2000;
 /** The entries a reader lists in notes/ before it stops. */
 const MAX_LISTED_ENTRIES = 2 * MAX_RUN_NOTES;
-const NOTE_ID = /^note-\d{8}t\d{9}z-[0-9a-f]{12}$/;
-/** A temporary file of a write in progress, or of one a stopped writer left. Never a note. */
+/** 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();
@@ -37,10 +54,8 @@ export function runNoteFile(id) {
 export function encodeRunNote(note, runId) {
     return `${JSON.stringify({ schema: RUN_NOTE_SCHEMA, runId, ...note }, null, 2)}\n`;
 }
-const text = (value, max) => typeof value === "string" && value.length > 0 && value.length <= max;
-const timestamp = (value) => text(value, 64) && Number.isFinite(Date.parse(value));
 /** The note in a note file's bytes, when it is a note of `runId` stored under its own `id`. */
-export function decodeRunNote(bytes, runId, id) {
+function decodeRunNote(bytes, runId, id) {
     let value;
     try {
         value = JSON.parse(bytes.toString("utf8"));
@@ -48,42 +63,17 @@ export function decodeRunNote(bytes, runId, id) {
     catch {
         return null;
     }
-    if (!isRecord(value) ||
-        value.schema !== RUN_NOTE_SCHEMA ||
-        value.runId !== runId ||
-        value.id !== id ||
-        typeof value.atMs !== "number" ||
-        !Number.isSafeInteger(value.atMs) ||
-        value.atMs < 0 ||
-        !(value.participant === null || text(value.participant, 256)) ||
-        !(value.nearest === null ||
-            (isRecord(value.nearest) &&
-                text(value.nearest.participant, 256) &&
-                text(value.nearest.itemId, 256))) ||
-        !text(value.text, MAX_NOTE_TEXT) ||
-        !text(value.author, 80) ||
-        !timestamp(value.createdAt) ||
-        !(value.editedAt === null || timestamp(value.editedAt)))
+    const parsed = runNoteFileSchema.safeParse(value);
+    if (!parsed.success || parsed.data.runId !== runId || parsed.data.id !== id)
         return null;
-    const nearest = isRecord(value.nearest) ? value.nearest : null;
-    return {
-        id,
-        atMs: value.atMs,
-        participant: value.participant,
-        nearest: nearest === null
-            ? null
-            : { participant: String(nearest.participant), itemId: String(nearest.itemId) },
-        text: value.text,
-        author: value.author,
-        createdAt: value.createdAt,
-        editedAt: value.editedAt,
-    };
+    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.
  */
-export async function listNoteEntries(dir) {
+async function listNoteEntries(dir) {
     try {
         const stats = await lstat(dir);
         if (!stats.isDirectory() || stats.isSymbolicLink())
@@ -109,7 +99,7 @@ export async function listNoteEntries(dir) {
     return { names, truncated: false };
 }
 /** The note ids to read from a listing of notes/, in creation order, and what was left out. */
-export function noteListing(listing) {
+function noteListing(listing) {
     const ids = [];
     const skipped = [];
     for (const name of listing.names) {
@@ -136,16 +126,32 @@ 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. Each file is read through the bounded reader, which refuses a link, a special
- * file or anything over MAX_NOTE_FILE_BYTES before reading past the limit; a file it refuses, or
- * that is not a note of this run, is skipped and named in `skipped`.
+ * 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(prepared) {
-    const runId = runIdOf(prepared);
+export async function readRunNotes(from) {
+    const files = "physicalRunRoot" in from ? boundedNoteFiles(from) : from;
+    const { runId } = files;
     let listing;
     try {
-        listing = await listNoteEntries(path.join(prepared.physicalRunRoot, RUN_NOTES_DIR));
+        listing = await listNoteEntries(path.join(await files.directory(), RUN_NOTES_DIR));
     }
     catch {
         return {
@@ -159,12 +165,12 @@ export async function readRunNotes(prepared) {
     const { ids, skipped } = noteListing(listing);
     const notes = [];
     for (const id of ids) {
-        const read = await readBoundedFileResult(prepared, runNoteFile(id), MAX_NOTE_FILE_BYTES);
-        const note = read.state === "read" ? decodeRunNote(read.bytes, runId, id) : null;
+        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.state === "limit"
+            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.`);
     }
@@ -178,7 +184,29 @@ export async function readRunNotes(prepared) {
 export async function readNotesForSharing(prepared) {
     const notes = await readRunNotes(prepared);
     if (notes.notes.length === 0)
-        return { notes, finding: null };
+        return { notes, problem: null };
     const scan = scanEncodedTextCached(JSON.stringify(notes.notes));
-    return { notes, finding: scan.sensitive ? "sensitive" : scan.opaque ? "opaque" : null };
+    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

@@ -1,7 +1,6 @@
 import type { RunBundle } from "./bundle.js";
-import { type RunNote } from "./note-files.js";
+import { type RunNote } from "./note-shape.js";
 import { type PreparedRunArtifactPaths } from "./paths.js";
-export { MAX_NOTE_TEXT, readNotesForSharing, readRunNotes, type RunNote, type RunNotes, } from "./note-files.js";
 export interface RunNoteInput {
     atMs: number;
     participant: string | null;
@@ -21,8 +20,6 @@ export type AddRunNoteResult =
         message: string;
     };
 };
-/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
-export declare function runParticipantCaptions(bundle: RunBundle): Map<string, 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. */
@@ -31,7 +28,7 @@ export declare function runClock(bundle: RunBundle): {
     endMs: number;
 } | null;
 /**
- * Adds a note as a new file, notes/<id>.json, published 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.
+ * 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>;

package/dist/run/notes.js

@@ -1,16 +1,16 @@
 // Reviewer notes: free text a person adds at a moment of a recorded run. Each note is its own file
 // in the run directory (note-files.ts). A note's time counts from the run clock's start, the
 // first timed capture or desktop video of any participant, which is the Observer's study clock.
+import { cli } from "../cli/invocation.js";
 import { redactText } from "../evidence/redaction.js";
-import { writeNewContainedOutputFile } from "./contained-output.js";
+import { createContainedOutputFile } from "./contained-output.js";
 import { loadRunBundlePrepared } from "./locate.js";
-import { countRunNotes, encodeRunNote, MAX_NOTE_TEXT, MAX_RUN_NOTES, newRunNoteId, runNoteFile, } from "./note-files.js";
-import { streamCaptions } from "./participant-caption.js";
-import { recordedPersonaId, streamParticipantIdOf } from "./participant-records.js";
+import { countRunNotes, encodeRunNote, newRunNoteId, runNoteFile } from "./note-files.js";
+import { MAX_NOTE_TEXT, MAX_RUN_NOTES } from "./note-shape.js";
+import { runParticipantCaptions, streamParticipantIdOf } from "./participant-records.js";
 import { physicalCwdOf, runIdOf } from "./paths.js";
 import { transientCommsKnownValueScrub } from "./transient-comms-secrets.js";
 import { isNodeError } from "./type-guards.js";
-export { MAX_NOTE_TEXT, readNotesForSharing, readRunNotes, } from "./note-files.js";
 const DEFAULT_AUTHOR = "you";
 /** New ids a note tries when the one before was taken. */
 const PUBLISH_ATTEMPTS = 5;
@@ -18,19 +18,6 @@ const refuse = (code, message) => ({
     ok: false,
     error: { code, message },
 });
-/** Each participant's caption, by stream id, as the Observer and the TUI name them. */
-export function runParticipantCaptions(bundle) {
-    return streamCaptions(bundle.streams.map((stream) => {
-        const participantId = streamParticipantIdOf(stream);
-        const personaId = recordedPersonaId(bundle, stream);
-        return {
-            id: stream.id,
-            label: stream.label,
-            ...(participantId === undefined ? {} : { participantId }),
-            ...(personaId === undefined ? {} : { personaId }),
-        };
-    }));
-}
 /**
  * The stream id a note's participant names: a stream id, or the participant's own id from the study
  * (`charge-nurse`). Both kinds of id are matched, so a name that is one stream's id and another
@@ -136,18 +123,25 @@ function noteTextProblem(text) {
     return null;
 }
 /**
- * Adds a note as a new file, notes/<id>.json, published 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.
+ * 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 async function addRunNote(prepared, input) {
     const text = scrubNoteText(input.text);
     const problem = noteTextProblem(text);
     if (problem)
         return refuse("HUMANISH_NOTE_INVALID", problem);
-    // Containment checks throw on a link or special file anywhere in the run directory.
-    const loaded = await loadRunBundlePrepared(physicalCwdOf(prepared), prepared).catch(() => null);
+    let loaded;
+    try {
+        loaded = await loadRunBundlePrepared(physicalCwdOf(prepared), prepared);
+    }
+    catch (error) {
+        // The storage check throws on a link or a special file anywhere in the run directory, or on a
+        // run directory that moved.
+        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `No note was added to run ${runIdOf(prepared)}: its directory failed humanish's storage check. ${error instanceof Error ? error.message : String(error)} Fix that in the run directory and add the note again.`);
+    }
     if (!loaded)
-        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `Run ${runIdOf(prepared)} has no run.json humanish can read safely, so no note was added. \`humanish verify --run ${runIdOf(prepared)}\` says what is wrong with it.`);
+        return refuse("HUMANISH_INVALID_RUN_BUNDLE", `Run ${runIdOf(prepared)} has no run.json humanish can read safely, so no note was added. \`${cli(`verify --run ${runIdOf(prepared)}`)}\` says what is wrong with it.`);
     const { bundle } = loaded;
     const clock = runClock(bundle);
     if (!clock)
@@ -181,7 +175,7 @@ export async function addRunNote(prepared, input) {
         for (let attempt = 0; attempt < PUBLISH_ATTEMPTS; attempt += 1) {
             const note = { id: newRunNoteId(now), ...fields };
             try {
-                await writeNewContainedOutputFile(prepared, runNoteFile(note.id), encodeRunNote(note, bundle.runId));
+                await createContainedOutputFile(prepared, runNoteFile(note.id), encodeRunNote(note, bundle.runId));
             }
             catch (error) {
                 if (isNodeError(error) && error.code === "EEXIST")