@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/{wss/keystore → keystore}/pem.js

@@ -8,7 +8,7 @@
  * because a passphrase-protected key is exactly what the keystore password is for.
  */
 import forge from 'node-forge';
-import { WssError } from '../../errors.js';
+import { WssError } from '../errors.js';
 import { buildChain, commonNameOf, describeCertificate, keyPemMatchesCertificate } from './certificate.js';
 /** The block types this reader treats as a private key. */
 const KEY_TYPES = new Set(['PRIVATE KEY', 'RSA PRIVATE KEY', 'EC PRIVATE KEY', 'ENCRYPTED PRIVATE KEY']);

package/dist/{wss/keystore → keystore}/pkcs12.js

@@ -8,7 +8,7 @@
  * expected to keep the result out of the renderer.
  */
 import forge from 'node-forge';
-import { WssError } from '../../errors.js';
+import { WssError } from '../errors.js';
 import { buildChain, commonNameOf, describeCertificate, keyMatchesCertificate } from './certificate.js';
 function invalid(cause) {
     return new WssError('keystore-invalid', 'The file is not a readable PKCS#12 keystore.', { cause });

package/dist/project/attachments-cache.d.ts

@@ -8,8 +8,10 @@
  * deleted implicitly: {@link pruneAttachments} exists so the UI can offer it explicitly,
  * because a blob whose last reference was removed in an unsaved edit must survive an undo.
  */
+import type { Attachment } from './model.js';
 import { type FsLike } from './fs.js';
-import type { AttachmentResolver } from '../soap/mime/types.js';
+/** Resolves one attachment's bytes. Rejects when the attachment cannot be read. */
+export type AttachmentResolver = (attachment: Attachment) => Promise<Uint8Array>;
 /** One blob in the attachment cache, as recorded in `attachments/index.yaml`. */
 export interface AttachmentCacheEntry {
     readonly sha256: string;

package/dist/{wsdl → project}/cache-naming.js

@@ -10,7 +10,7 @@
  * reserved device name (`CON`, `NUL`, `COM1`, ...) is renamed safely instead
  * of being written as-is.
  */
-import { isReservedFileName, sanitiseFileName } from '../project/paths.js';
+import { isReservedFileName, sanitiseFileName } from './paths.js';
 /** Extracts the last path segment of a location's pathname, ignoring any query/fragment. */
 function lastPathSegment(location) {
     try {

package/dist/project/endpoints.d.ts

@@ -1,17 +1,27 @@
 /**
- * Endpoint-level credential precedence: how a request's own `EndpointAuth` combines with the
- * auth configured on the endpoint it is sent to (and, as a last resort, on its interface).
- * Pure — the desktop app resolves the resulting `passwordRef` afterwards.
+ * Endpoint-level credential precedence: how a request's own auth combines with the auth
+ * configured on the endpoint it is sent to (and, as a last resort, on its interface). Pure — the
+ * desktop app resolves the resulting `passwordRef`/`tokenRef`/etc. afterwards.
  */
-import type { EndpointAuth } from './model.js';
+import type { EndpointAuth, SoapOwnerAuth } from './model.js';
+/**
+ * Narrows a {@link SoapOwnerAuth} to the {@link EndpointAuth} arm (Basic/NTLM/none) — the arms
+ * with username/password fields to merge, and the ones the transport authenticates itself.
+ * Exported so every site that has to tell them from the token schemes shares one definition.
+ */
+export declare function isEndpointAuth(auth: SoapOwnerAuth): auth is EndpointAuth;
 /**
  * Combines request, endpoint and interface credentials for one send.
  *
  * `override` (the endpoint wins): a defined endpoint auth replaces the request's entirely —
  * including an explicit `{ type: 'none' }`, which deliberately turns authentication off.
- * `complement` (the endpoint only fills blanks): start from the request's auth and take
- * `username`, `passwordRef`, `domain` and `preemptive` from the endpoint wherever the request
- * left them undefined, plus `type` when the request has no type or asks for `none`.
+ * `complement` (the endpoint only fills blanks): when both sides are Basic/NTLM/none — the only
+ * arms with fields to share — start from the request's auth and take `username`, `passwordRef`,
+ * `domain` and `preemptive` from the endpoint wherever the request left them undefined, plus
+ * `type` when the request has no type or asks for `none`. For any other combination (a token
+ * scheme on either side) `complement` means the request's own auth, unless it is absent or
+ * `none`, then the endpoint's — field-merging a Bearer/API-key/OAuth2 config has no shared shape
+ * to merge into.
  *
  * When nothing is configured at either level, the interface's auth applies unchanged.
  *
@@ -20,4 +30,4 @@ import type { EndpointAuth } from './model.js';
  * @param authMode how the endpoint's credentials combine with the request's
  * @param interfaceAuth the interface-wide fallback, if any
  */
-export declare function effectiveAuth(requestAuth: EndpointAuth | undefined, endpointAuth: EndpointAuth | undefined, authMode: 'override' | 'complement', interfaceAuth?: EndpointAuth): EndpointAuth | undefined;
+export declare function effectiveAuth(requestAuth: SoapOwnerAuth | undefined, endpointAuth: SoapOwnerAuth | undefined, authMode: 'override' | 'complement', interfaceAuth?: SoapOwnerAuth): SoapOwnerAuth | undefined;

package/dist/project/endpoints.js

@@ -1,16 +1,28 @@
 /**
- * Endpoint-level credential precedence: how a request's own `EndpointAuth` combines with the
- * auth configured on the endpoint it is sent to (and, as a last resort, on its interface).
- * Pure — the desktop app resolves the resulting `passwordRef` afterwards.
+ * Endpoint-level credential precedence: how a request's own auth combines with the auth
+ * configured on the endpoint it is sent to (and, as a last resort, on its interface). Pure — the
+ * desktop app resolves the resulting `passwordRef`/`tokenRef`/etc. afterwards.
  */
+/**
+ * Narrows a {@link SoapOwnerAuth} to the {@link EndpointAuth} arm (Basic/NTLM/none) — the arms
+ * with username/password fields to merge, and the ones the transport authenticates itself.
+ * Exported so every site that has to tell them from the token schemes shares one definition.
+ */
+export function isEndpointAuth(auth) {
+    return auth.type === 'none' || auth.type === 'basic' || auth.type === 'ntlm';
+}
 /**
  * Combines request, endpoint and interface credentials for one send.
  *
  * `override` (the endpoint wins): a defined endpoint auth replaces the request's entirely —
  * including an explicit `{ type: 'none' }`, which deliberately turns authentication off.
- * `complement` (the endpoint only fills blanks): start from the request's auth and take
- * `username`, `passwordRef`, `domain` and `preemptive` from the endpoint wherever the request
- * left them undefined, plus `type` when the request has no type or asks for `none`.
+ * `complement` (the endpoint only fills blanks): when both sides are Basic/NTLM/none — the only
+ * arms with fields to share — start from the request's auth and take `username`, `passwordRef`,
+ * `domain` and `preemptive` from the endpoint wherever the request left them undefined, plus
+ * `type` when the request has no type or asks for `none`. For any other combination (a token
+ * scheme on either side) `complement` means the request's own auth, unless it is absent or
+ * `none`, then the endpoint's — field-merging a Bearer/API-key/OAuth2 config has no shared shape
+ * to merge into.
  *
  * When nothing is configured at either level, the interface's auth applies unchanged.
  *
@@ -32,6 +44,9 @@ function combine(requestAuth, endpointAuth, authMode) {
     if (requestAuth === undefined) {
         return endpointAuth;
     }
+    if (!isEndpointAuth(requestAuth) || !isEndpointAuth(endpointAuth)) {
+        return requestAuth.type === 'none' ? endpointAuth : requestAuth;
+    }
     const type = requestAuth.type === 'none' ? endpointAuth.type : requestAuth.type;
     const username = requestAuth.username ?? endpointAuth.username;
     const passwordRef = requestAuth.passwordRef ?? endpointAuth.passwordRef;

package/dist/project/environments.d.ts

@@ -9,8 +9,7 @@
  * request's custom URL; then its chosen endpoint; then the interface
  * default; then the interface's first endpoint.
  */
-import type { Endpoint, Environment, Interface, Project, PropertyMap, RequestDef } from './model.js';
-import type { RestApi } from '../rest/model.js';
+import type { Endpoint, Environment, Interface, Project, PropertyMap, SoapRequestDef } from './model.js';
 import type { PropertyScopes } from './properties.js';
 /** Finds the environment with `envId` in `project`, or `undefined` when there is none or it isn't found. */
 export declare function findEnvironment(project: Project, envId: string | undefined): Environment | undefined;
@@ -25,7 +24,7 @@ export type EndpointSource = 'environment' | 'workspace-environment' | 'request-
  * the endpoint's own settings (its `trustInvalid` flag, say) read it from here rather than
  * re-deriving the precedence.
  */
-export declare function resolveEndpoint(project: Project, envId: string | undefined, iface: Interface, request: Pick<RequestDef, 'endpointId' | 'endpointUrl'>): {
+export declare function resolveEndpoint(project: Project, envId: string | undefined, iface: Interface, request: Pick<SoapRequestDef, 'endpointId' | 'endpointUrl'>): {
     url: string | undefined;
     source: EndpointSource;
     endpoint?: Endpoint;
@@ -40,7 +39,10 @@ export type BaseUrlSource = 'environment' | 'workspace-environment' | 'api';
  * environment is how a user says "point everything at test". An API has no per-request URL
  * override to consider — a request that needs another host writes an absolute URL instead.
  */
-export declare function resolveApiBaseUrl(project: Project, envId: string | undefined, api: Pick<RestApi, 'slug' | 'baseUrl'>): {
+export declare function resolveApiBaseUrl(project: Project, envId: string | undefined, api: {
+    readonly slug: string;
+    readonly baseUrl: string;
+}): {
     url: string;
     source: BaseUrlSource;
 };
@@ -52,7 +54,7 @@ export declare function resolveApiBaseUrl(project: Project, envId: string | unde
  * a request's effective auth (not just its URL) should resolve the endpoint through this function
  * rather than re-deriving the precedence, so the two cannot drift apart.
  */
-export declare function resolveAuthEndpoint(iface: Interface, request: Pick<RequestDef, 'endpointId'>): Endpoint | undefined;
+export declare function resolveAuthEndpoint(iface: Interface, request: Pick<SoapRequestDef, 'endpointId'>): Endpoint | undefined;
 /**
  * Builds the {@link PropertyScopes} for expanding properties against `project`
  * under the (optional) active environment `envId`. `env` is omitted entirely

package/dist/project/history.d.ts

@@ -4,11 +4,15 @@
  * itself is deleted, moved, or never saved. Entries are appended already redacted — this module
  * never sees a secret, it only stores and reads back whatever the caller hands it.
  *
- * Pure and `FsLike`-injectable, like the rest of `project/*`: no knowledge of Electron's
- * `userData`, no knowledge of the wire format's redaction rules.
+ * Reads and writes go through an injectable `FsLike`, like the rest of `project/*`. The lock and the
+ * freshness check use `node:fs` directly, because `FsLike` has neither an exclusive create nor an
+ * mtime: two processes (the desktop app and `wirebench mcp`) may write one file, so every write takes
+ * `<file>.lock` and rereads the file first when another writer changed it.
  */
 import type { FsLike } from './fs.js';
 import type { WsExchange, WsFrame } from '../ws/model.js';
+import type { SseRow } from '../rest/sse.js';
+import type { RestContractResult } from '../rest/contract-check.js';
 /** One HTTP header, in author order. */
 export interface HistoryHeader {
     readonly name: string;
@@ -67,6 +71,51 @@ export interface HistoryWs {
     /** The handshake's transport error, absent when the handshake succeeded (or never ran). */
     readonly error?: string;
 }
+/**
+ * The shape {@link historySseOf} needs from a REST send's event-stream summary: the desktop's
+ * `RestEventStreamWire` matches it field for field, but this module stays free of the wire schema
+ * (the engine has no business depending on the desktop's zod types) and takes anything with the
+ * same shape instead.
+ */
+export interface RestEventStreamLike {
+    readonly rows: readonly SseRow[];
+    readonly counts: {
+        readonly events: number;
+        readonly comments: number;
+        readonly retries: number;
+        readonly bytes: number;
+    };
+    readonly lastEventId: string;
+    readonly endedBy: 'server' | 'client' | 'error';
+    readonly error?: string;
+    /** Rows already evicted from the in-memory store before this summary was built. */
+    readonly droppedRows: number;
+    /** Whether the summary's own cap (`SSE_SUMMARY_LIMITS`) cut anything further. */
+    readonly truncated: boolean;
+    /** Rows the summary's own cap omitted, on top of `droppedRows`. */
+    readonly omittedRows: number;
+}
+/**
+ * The REST event-stream side of a history entry: the rows, the outcome, and a capped transcript
+ * ({@link historySseOf}'s own re-cap via {@link SSE_HISTORY_LIMITS}) so a long-running stream
+ * doesn't blow up the history file, the same way {@link HistoryWs} caps a WebSocket session's frames.
+ */
+export interface HistorySse {
+    readonly rows: readonly SseRow[];
+    readonly counts: {
+        readonly events: number;
+        readonly comments: number;
+        readonly retries: number;
+        readonly bytes: number;
+    };
+    readonly lastEventId: string;
+    readonly endedBy: 'server' | 'client' | 'error';
+    readonly error?: string;
+    /** Set only when re-capping actually trimmed something (rows, or just a payload). */
+    readonly truncated?: boolean;
+    /** How many rows are missing from `rows` compared to the live stream, in total. */
+    readonly omittedRows?: number;
+}
 /**
  * One recorded send. Stored **already redacted** by the caller — this module has no concept of
  * secrets and never inspects `request`/`response` bodies beyond storing and searching them.
@@ -118,14 +167,47 @@ export interface HistoryEntry {
     readonly grpc?: HistoryGrpc;
     /** The session record of a WebSocket send; absent for the other protocols. */
     readonly ws?: HistoryWs;
+    /** The event-stream record of a REST send whose response was `text/event-stream`; absent otherwise. */
+    readonly sse?: HistorySse;
+    /** How a REST response compared with its OpenAPI contract; absent when it was not checked. */
+    readonly contract?: RestContractResult;
     readonly sizeBytes: number;
     readonly tags?: readonly string[];
 }
+/**
+ * A contract result as a history entry keeps it: only the fields the result declares, under the
+ * check's own caps (problems, notes, message length), so a line cannot grow past what the live
+ * result could show — whatever produced the value.
+ */
+export declare function historyContractOf(result: RestContractResult): RestContractResult;
+/** How long a writer waits for the file's lock, and when a lock counts as a crashed writer's. */
+export interface HistoryLockOptions {
+    /** How long a writer waits before failing with `history-busy`. Default 2000 ms. */
+    readonly timeoutMs?: number;
+    /** A lock older than this was left by a crashed writer and is broken. Default 5000 ms. */
+    readonly staleMs?: number;
+    /** How often a waiting writer tries again. Default 25 ms. */
+    readonly retryMs?: number;
+}
 /** Options accepted by {@link appendHistory} and {@link openHistory}. */
 export interface HistoryOptions {
+    /**
+     * Reads and writes the History file. The lock file and the freshness check always use the real
+     * disk through `node:fs`, whatever `fs` is injected.
+     */
     readonly fs?: FsLike;
     /** Oldest entries are dropped once the file holds more than this many. Defaults to 1000. */
     readonly cap?: number;
+    readonly lock?: HistoryLockOptions;
+}
+/** Options accepted by {@link appendHistory}. */
+export interface AppendHistoryOptions extends HistoryOptions {
+    /**
+     * Never drop an entry the file already holds: the cap trims only down to the current count, so
+     * the file may grow past `cap`. For a writer that does not know the cap the user chose (the
+     * desktop's own cap applies again on its next write).
+     */
+    readonly keepAtLeastCurrent?: boolean;
 }
 /** Filters accepted by {@link HistoryFile.list}. */
 export interface HistoryListQuery {
@@ -145,6 +227,11 @@ export interface HistoryFile {
     /** Empties the file and the cache. Returns the number of entries that were cleared. */
     clear(): Promise<number>;
     count(): number;
+    /**
+     * Rereads the file when it is not the version this handle last read or wrote — another process
+     * wrote it. Resolves `true` when it reread. Serialised with `append` and `clear`.
+     */
+    refresh(): Promise<boolean>;
     /** Corrupt lines skipped while loading the file. */
     readonly problems: number;
 }
@@ -154,18 +241,27 @@ export interface HistoryFile {
  */
 export declare function normalizeHistoryEntry(entry: HistoryEntry): HistoryEntry;
 /**
- * Appends one entry to `file`, rotating so at most `cap` (default 1000) entries remain — the
- * oldest are dropped first. Stateless: rereads the whole file first, so prefer {@link openHistory}
- * when appending more than once (it keeps the entries cached in memory).
+ * Appends one entry to `file` under the file's lock, rotating so at most `cap` (default 1000)
+ * entries remain — the oldest are dropped first. With `keepAtLeastCurrent`, no entry already in the
+ * file is dropped. Stateless: rereads the whole file first, so prefer {@link openHistory} when
+ * appending more than once (it keeps the entries cached in memory).
  */
-export declare function appendHistory(file: string, entry: HistoryEntry, options?: HistoryOptions): Promise<void>;
+export declare function appendHistory(file: string, entry: HistoryEntry, options?: AppendHistoryOptions): Promise<void>;
 /**
- * Opens a live handle on `file`'s history: loads the current entries into memory once, then
- * serves `list`/`get`/`count` from that cache and keeps it (and the file) in sync on `append`/
- * `clear`. Concurrent `append`/`clear` calls on the same handle are serialised.
+ * Opens a live handle on `file`'s history: loads the entries into memory, serves `list`/`get`/`count`
+ * from that cache, and on `append`/`clear` takes the file's lock, rereads the file when another
+ * writer changed it, and writes it back. Calls on one handle are serialised.
  */
 export declare function openHistory(file: string, options?: HistoryOptions): Promise<HistoryFile>;
 /** Generates a new history entry id (ulid: lexicographically time-ordered, unique). */
 export declare function generateHistoryId(): string;
 /** Builds a {@link HistoryWs} from a completed session, applying {@link capFrames}. */
 export declare function historyWsOf(exchange: WsExchange): HistoryWs;
+/**
+ * Builds a {@link HistorySse} from a REST send's event-stream summary, re-capping its rows down to
+ * {@link SSE_HISTORY_LIMITS} (tighter than the summary's own `SSE_SUMMARY_LIMITS`, the same way
+ * {@link historyWsOf} re-caps a WebSocket session's frames). `omittedRows` totals every row missing
+ * from the result compared to the live stream: rows the in-memory store had already dropped
+ * (`droppedRows`), rows the summary's own cap left out (`omittedRows`), and rows this re-cap cut.
+ */
+export declare function historySseOf(stream: RestEventStreamLike): HistorySse;

package/dist/project/history.js

@@ -4,12 +4,45 @@
  * itself is deleted, moved, or never saved. Entries are appended already redacted — this module
  * never sees a secret, it only stores and reads back whatever the caller hands it.
  *
- * Pure and `FsLike`-injectable, like the rest of `project/*`: no knowledge of Electron's
- * `userData`, no knowledge of the wire format's redaction rules.
+ * Reads and writes go through an injectable `FsLike`, like the rest of `project/*`. The lock and the
+ * freshness check use `node:fs` directly, because `FsLike` has neither an exclusive create nor an
+ * mtime: two processes (the desktop app and `wirebench mcp`) may write one file, so every write takes
+ * `<file>.lock` and rereads the file first when another writer changed it.
  */
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, readFile, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { ulid } from 'ulidx';
-import { nodeFs, readFileIfExists, writeFileAtomic } from './fs.js';
+import { ProjectError } from '../errors.js';
+import { isNotFound, nodeFs, readFileIfExists, writeFileAtomic } from './fs.js';
 import { capFrames } from '../ws/transcript.js';
+import { capSseRows, SSE_HISTORY_LIMITS } from '../rest/sse-transcript.js';
+import { MAX_CONTRACT_MESSAGE_LENGTH, MAX_CONTRACT_PROBLEMS } from '../rest/contract-check.js';
+function clipped(text) {
+    return text.length > MAX_CONTRACT_MESSAGE_LENGTH ? text.slice(0, MAX_CONTRACT_MESSAGE_LENGTH) : text;
+}
+/**
+ * A contract result as a history entry keeps it: only the fields the result declares, under the
+ * check's own caps (problems, notes, message length), so a line cannot grow past what the live
+ * result could show — whatever produced the value.
+ */
+export function historyContractOf(result) {
+    return {
+        status: result.status,
+        ...(result.operation !== undefined
+            ? { operation: { method: result.operation.method, path: result.operation.path } }
+            : {}),
+        ...(result.responseKey !== undefined ? { responseKey: result.responseKey } : {}),
+        ...(result.mediaType !== undefined ? { mediaType: result.mediaType } : {}),
+        problems: result.problems.slice(0, MAX_CONTRACT_PROBLEMS).map((problem) => ({
+            path: clipped(problem.path),
+            keyword: problem.keyword,
+            message: clipped(problem.message),
+        })),
+        notes: result.notes.slice(0, MAX_CONTRACT_PROBLEMS).map(clipped),
+    };
+}
 const DEFAULT_CAP = 1000;
 /**
  * One entry as callers should see it: a line written before the REST client carried no `kind`,
@@ -38,6 +71,7 @@ function matches(entry, needle) {
         entry.status !== undefined ? String(entry.status) : '',
         entry.fault?.reason ?? '',
         ...(entry.tags ?? []),
+        ...(entry.sse?.rows.flatMap((row) => (row.kind === 'event' ? [row.event, row.data] : [])) ?? []),
     ]
         .join('\n')
         .toLowerCase();
@@ -86,30 +120,123 @@ async function readAll(fs, file) {
 function serialise(entries) {
     return entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length > 0 ? '\n' : '');
 }
+const LOCK_DEFAULTS = { timeoutMs: 2_000, staleMs: 5_000, retryMs: 25 };
+async function signatureOf(file) {
+    try {
+        const found = await stat(file);
+        return { ino: found.ino, size: found.size, mtimeMs: found.mtimeMs };
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function sameSignature(a, b) {
+    if (a === undefined || b === undefined) {
+        return a === b;
+    }
+    return a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs;
+}
+/** Creates the lock file holding `token` if nobody holds it. */
+async function createLock(lockFile, token) {
+    try {
+        const handle = await open(lockFile, 'wx');
+        try {
+            await handle.writeFile(token);
+        }
+        finally {
+            await handle.close();
+        }
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return false;
+        }
+        throw error;
+    }
+}
+/** Removes the lock only when it still holds `token`: a lock broken as stale is the next holder's. */
+async function releaseLock(lockFile, token) {
+    try {
+        if ((await readFile(lockFile, 'utf8')) === token) {
+            await rm(lockFile, { force: true });
+        }
+    }
+    catch (error) {
+        if (!isNotFound(error)) {
+            throw error;
+        }
+    }
+}
 /**
- * Appends one entry to `file`, rotating so at most `cap` (default 1000) entries remain — the
- * oldest are dropped first. Stateless: rereads the whole file first, so prefer {@link openHistory}
- * when appending more than once (it keeps the entries cached in memory).
+ * Runs `task` holding `<file>.lock`, which carries an owner token (pid plus random bytes). A lock
+ * older than `staleMs` is a crashed writer's and is removed; otherwise the writer retries every
+ * `retryMs` until `timeoutMs`, then fails with `history-busy`. Release is owner-checked: the lock
+ * is removed only while it still holds this writer's token, so a holder whose lock was broken
+ * never deletes the next holder's. Breaking a stale lock can still race between two waiters who
+ * both see it as stale; that is accepted, because a critical section is a reread plus one atomic
+ * write.
+ */
+async function withLock(file, options, task) {
+    const { timeoutMs, staleMs, retryMs } = { ...LOCK_DEFAULTS, ...options };
+    const lockFile = `${file}.lock`;
+    const token = `${String(process.pid)}-${randomBytes(8).toString('hex')}`;
+    await mkdir(dirname(file), { recursive: true });
+    const deadline = Date.now() + timeoutMs;
+    while (!(await createLock(lockFile, token))) {
+        const held = await signatureOf(lockFile);
+        if (held !== undefined && Date.now() - held.mtimeMs > staleMs) {
+            await rm(lockFile, { force: true });
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new ProjectError('history-busy', `This writer waited ${String(timeoutMs)} ms for the History lock and gave up; try again`, { details: { file, lock: lockFile } });
+        }
+        await delay(retryMs);
+    }
+    try {
+        return await task();
+    }
+    finally {
+        await releaseLock(lockFile, token);
+    }
+}
+/**
+ * Appends one entry to `file` under the file's lock, rotating so at most `cap` (default 1000)
+ * entries remain — the oldest are dropped first. With `keepAtLeastCurrent`, no entry already in the
+ * file is dropped. Stateless: rereads the whole file first, so prefer {@link openHistory} when
+ * appending more than once (it keeps the entries cached in memory).
  */
 export async function appendHistory(file, entry, options = {}) {
     const fs = options.fs ?? nodeFs;
-    const cap = options.cap ?? DEFAULT_CAP;
-    const { entries } = await readAll(fs, file);
-    entries.push(entry);
-    const capped = entries.length > cap ? entries.slice(entries.length - cap) : entries;
-    await writeFileAtomic(fs, file, serialise(capped));
+    await withLock(file, options.lock, async () => {
+        const { entries } = await readAll(fs, file);
+        // Decided after the reread, inside the lock: every entry held now, plus the new one, stays.
+        const cap = options.keepAtLeastCurrent === true
+            ? Math.max(options.cap ?? DEFAULT_CAP, entries.length + 1)
+            : (options.cap ?? DEFAULT_CAP);
+        entries.push(entry);
+        const capped = entries.length > cap ? entries.slice(entries.length - cap) : entries;
+        await writeFileAtomic(fs, file, serialise(capped));
+    });
 }
 /**
- * Opens a live handle on `file`'s history: loads the current entries into memory once, then
- * serves `list`/`get`/`count` from that cache and keeps it (and the file) in sync on `append`/
- * `clear`. Concurrent `append`/`clear` calls on the same handle are serialised.
+ * Opens a live handle on `file`'s history: loads the entries into memory, serves `list`/`get`/`count`
+ * from that cache, and on `append`/`clear` takes the file's lock, rereads the file when another
+ * writer changed it, and writes it back. Calls on one handle are serialised.
  */
 export async function openHistory(file, options = {}) {
     const fs = options.fs ?? nodeFs;
     const cap = options.cap ?? DEFAULT_CAP;
-    const { entries, problems } = await readAll(fs, file);
+    // Taken before the read: a write that lands in between makes the next check reread, never miss.
+    let seen = await signatureOf(file);
+    const initial = await readAll(fs, file);
     // Oldest-first in memory (matches on-disk order); newest-first is only materialised for `list`.
-    let cache = entries;
+    let cache = initial.entries;
+    let problems = initial.problems;
     let queue = Promise.resolve();
     const enqueue = (task) => {
         const result = queue.then(task);
@@ -118,16 +245,34 @@ export async function openHistory(file, options = {}) {
         queue = result.catch(() => undefined);
         return result;
     };
+    const reload = async () => {
+        const current = await signatureOf(file);
+        if (sameSignature(current, seen)) {
+            return false;
+        }
+        const read = await readAll(fs, file);
+        cache = read.entries;
+        problems = read.problems;
+        seen = current;
+        return true;
+    };
+    const write = async (text) => {
+        await writeFileAtomic(fs, file, text);
+        seen = await signatureOf(file);
+    };
     return {
-        problems,
+        get problems() {
+            return problems;
+        },
         append(entry) {
-            return enqueue(async () => {
+            return enqueue(() => withLock(file, options.lock, async () => {
+                await reload();
                 cache.push(entry);
                 if (cache.length > cap) {
                     cache = cache.slice(cache.length - cap);
                 }
-                await writeFileAtomic(fs, file, serialise(cache));
-            });
+                await write(serialise(cache));
+            }));
         },
         list(query) {
             const needle = query?.query ?? '';
@@ -145,16 +290,20 @@ export async function openHistory(file, options = {}) {
             return cache.find((entry) => entry.id === id);
         },
         clear() {
-            return enqueue(async () => {
+            return enqueue(() => withLock(file, options.lock, async () => {
+                await reload();
                 const cleared = cache.length;
                 cache = [];
-                await writeFileAtomic(fs, file, '');
+                await write('');
                 return cleared;
-            });
+            }));
         },
         count() {
             return cache.length;
         },
+        refresh() {
+            return enqueue(reload);
+        },
     };
 }
 /** Generates a new history entry id (ulid: lexicographically time-ordered, unique). */
@@ -177,3 +326,26 @@ export function historyWsOf(exchange) {
         ...(exchange.handshake.error !== undefined ? { error: exchange.handshake.error } : {}),
     };
 }
+/**
+ * Builds a {@link HistorySse} from a REST send's event-stream summary, re-capping its rows down to
+ * {@link SSE_HISTORY_LIMITS} (tighter than the summary's own `SSE_SUMMARY_LIMITS`, the same way
+ * {@link historyWsOf} re-caps a WebSocket session's frames). `omittedRows` totals every row missing
+ * from the result compared to the live stream: rows the in-memory store had already dropped
+ * (`droppedRows`), rows the summary's own cap left out (`omittedRows`), and rows this re-cap cut.
+ */
+export function historySseOf(stream) {
+    const capped = capSseRows(stream.rows, SSE_HISTORY_LIMITS);
+    const totalOmitted = stream.droppedRows + stream.omittedRows + capped.omittedRows;
+    // `stream.truncated`/`capped.truncated` only say whether a *cap* had to cut something; a live
+    // stream can also have rows the in-memory store already evicted (`droppedRows`) with neither cap
+    // ever needing to trim anything further, which is still an incomplete transcript.
+    const truncated = totalOmitted > 0 || stream.truncated || capped.truncated;
+    return {
+        rows: capped.rows,
+        counts: stream.counts,
+        lastEventId: stream.lastEventId,
+        endedBy: stream.endedBy,
+        ...(stream.error !== undefined ? { error: stream.error } : {}),
+        ...(truncated ? { truncated: true, ...(totalOmitted > 0 ? { omittedRows: totalOmitted } : {}) } : {}),
+    };
+}

package/dist/project/inherit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * "Inherit", as a send input means it: a setting a request leaves unset takes the value of the next
+ * level up. Shared by the REST and gRPC send inputs, which climb the same ladder (request, API,
+ * project, preference), so it lives in core (protocol modules spec §7.2).
+ */
+/** The first of `values` that is not `undefined`, which is what "inherit" means. */
+export declare function inherited<T>(...values: readonly (T | undefined)[]): T | undefined;

package/dist/project/inherit.js

@@ -0,0 +1,9 @@
+/**
+ * "Inherit", as a send input means it: a setting a request leaves unset takes the value of the next
+ * level up. Shared by the REST and gRPC send inputs, which climb the same ladder (request, API,
+ * project, preference), so it lives in core (protocol modules spec §7.2).
+ */
+/** The first of `values` that is not `undefined`, which is what "inherit" means. */
+export function inherited(...values) {
+    return values.find((value) => value !== undefined);
+}

package/dist/project/keystores.d.ts

@@ -4,7 +4,7 @@
  * and the typed `KeystoreDef` the keystore loaders take.
  */
 import type { WssRef } from './model.js';
-import type { KeystoreDef } from '../wss/keystore/model.js';
+import type { KeystoreDef } from '../keystore/model.js';
 /**
  * Reads one keystore registry entry out of its `WssRef`.
  *