@wirebench/engine 2.1.1

package/dist/project/environments.js

@@ -0,0 +1,124 @@
+/**
+ * Environment resolution: named sets of endpoints and property overrides, which let a
+ * saved project be pointed at different deployments (endpoints + property
+ * overrides) without editing the project itself.
+ *
+ * Precedence for the endpoint a request is actually sent to: an active
+ * environment's override for the interface (an explicit deployment choice)
+ * wins over everything else, including a request's own custom URL; then the
+ * request's custom URL; then its chosen endpoint; then the interface
+ * default; then the interface's first endpoint.
+ */
+import { enabledProperties } from './properties.js';
+/** Finds the environment with `envId` in `project`, or `undefined` when there is none or it isn't found. */
+export function findEnvironment(project, envId) {
+    if (envId === undefined) {
+        return undefined;
+    }
+    return project.environments.find((environment) => environment.id === envId);
+}
+/**
+ * Resolves the URL a request should actually be sent to, given an optional
+ * active environment. See the module doc for the precedence order.
+ *
+ * `endpoint` is the `Endpoint` object the URL came from, when one exists — the environment
+ * override and a request's custom URL name no endpoint, so they carry none. Callers that need
+ * the endpoint's own settings (its `trustInvalid` flag, say) read it from here rather than
+ * re-deriving the precedence.
+ */
+export function resolveEndpoint(project, envId, iface, request) {
+    const environment = findEnvironment(project, envId);
+    if (environment !== undefined) {
+        const override = environment.endpoints[iface.slug];
+        if (override !== undefined) {
+            return { url: override, source: 'environment' };
+        }
+    }
+    if (request.endpointUrl !== undefined) {
+        return { url: request.endpointUrl, source: 'request-custom' };
+    }
+    if (request.endpointId !== undefined) {
+        const endpoint = iface.endpoints.find((candidate) => candidate.id === request.endpointId);
+        if (endpoint !== undefined) {
+            return { url: endpoint.url, source: 'request-endpoint', endpoint };
+        }
+    }
+    if (iface.defaultEndpointId !== undefined) {
+        const endpoint = iface.endpoints.find((candidate) => candidate.id === iface.defaultEndpointId);
+        if (endpoint !== undefined) {
+            return { url: endpoint.url, source: 'interface-default', endpoint };
+        }
+    }
+    const first = iface.endpoints[0];
+    if (first !== undefined) {
+        return { url: first.url, source: 'interface-default', endpoint: first };
+    }
+    return { url: undefined, source: 'none' };
+}
+/**
+ * Resolves the base URL a REST API's requests are sent against.
+ *
+ * The same shape as {@link resolveEndpoint} and the same precedence as far as it goes: an active
+ * environment's override for the API wins over the API's own base URL, because choosing an
+ * 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 function resolveApiBaseUrl(project, envId, api) {
+    const environment = findEnvironment(project, envId);
+    const override = environment?.endpoints[api.slug];
+    return override !== undefined ? { url: override, source: 'environment' } : { url: api.baseUrl, source: 'api' };
+}
+/**
+ * Resolves the `Endpoint` object a request's *credentials* should come from: the request's own
+ * chosen endpoint, else the interface's default, else its first endpoint — the same precedence
+ * {@link resolveEndpoint} uses for the URL (minus the environment-override and custom-URL cases,
+ * which name no `Endpoint` object of their own, so have no auth to contribute). Callers that need
+ * 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 function resolveAuthEndpoint(iface, request) {
+    if (request.endpointId !== undefined) {
+        const endpoint = iface.endpoints.find((candidate) => candidate.id === request.endpointId);
+        if (endpoint !== undefined) {
+            return endpoint;
+        }
+    }
+    if (iface.defaultEndpointId !== undefined) {
+        const endpoint = iface.endpoints.find((candidate) => candidate.id === iface.defaultEndpointId);
+        if (endpoint !== undefined) {
+            return endpoint;
+        }
+    }
+    return iface.endpoints[0];
+}
+/**
+ * Builds the {@link PropertyScopes} for expanding properties against `project`
+ * under the (optional) active environment `envId`. `env` is omitted entirely
+ * when there is no active environment, so shorthand lookups correctly skip it.
+ * A property switched off via `disabledProperties` (on the project, or on the
+ * active environment) is excluded from its scope's map, so it resolves exactly
+ * as if it were absent — see {@link enabledProperties}.
+ */
+export function resolveScopes(project, envId, globals, system) {
+    const environment = findEnvironment(project, envId);
+    return {
+        project: enabledProperties(project.properties, project.disabledProperties),
+        global: globals,
+        ...(environment !== undefined
+            ? { env: enabledProperties(environment.properties, environment.disabledProperties) }
+            : {}),
+        ...(system !== undefined ? { system } : {}),
+    };
+}
+/** Replaces the environment with `env.id` if present, else appends it; preserves relative order otherwise. */
+export function upsertEnvironment(project, env) {
+    const exists = project.environments.some((candidate) => candidate.id === env.id);
+    const environments = exists
+        ? project.environments.map((candidate) => (candidate.id === env.id ? env : candidate))
+        : [...project.environments, env];
+    return { ...project, environments };
+}
+/** Removes the environment with `envId`, keeping the remaining environments' relative order. */
+export function removeEnvironment(project, envId) {
+    return { ...project, environments: project.environments.filter((candidate) => candidate.id !== envId) };
+}

package/dist/project/fs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The narrow file-system surface the project loader/saver needs, so callers can
+ * substitute an in-memory or instrumented implementation in tests.
+ */
+/** One entry of a directory listing. */
+export interface DirEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+}
+/** Minimal metadata about a path. */
+export interface FileStat {
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+    readonly size: number;
+}
+/** The file-system operations `loadProject`/`saveProject` depend on. */
+export interface FsLike {
+    readFile(path: string): Promise<Buffer>;
+    writeFile(path: string, data: Buffer | string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    mkdir(path: string, options: {
+        readonly recursive: true;
+    }): Promise<void>;
+    readdir(path: string): Promise<readonly DirEntry[]>;
+    stat(path: string): Promise<FileStat>;
+    rm(path: string, options?: {
+        readonly recursive?: boolean;
+        readonly force?: boolean;
+    }): Promise<void>;
+}
+/** The default {@link FsLike}, backed by `node:fs/promises`. */
+export declare const nodeFs: FsLike;
+/** True when the error is a "no such file or directory" error. */
+export declare function isNotFound(error: unknown): boolean;
+/** Reads a file, returning `undefined` instead of throwing when it does not exist. */
+export declare function readFileIfExists(fs: FsLike, path: string): Promise<Buffer | undefined>;
+/** Lists a directory, returning `[]` instead of throwing when it does not exist. */
+export declare function readdirIfExists(fs: FsLike, path: string): Promise<readonly DirEntry[]>;
+/**
+ * Writes `data` to `path` atomically: the bytes land in a sibling temp file that
+ * is then renamed over the target, so a crash mid-write can never leave a
+ * half-written project file behind.
+ */
+export declare function writeFileAtomic(fs: FsLike, path: string, data: Buffer | string): Promise<void>;

package/dist/project/fs.js

@@ -0,0 +1,78 @@
+/**
+ * The narrow file-system surface the project loader/saver needs, so callers can
+ * substitute an in-memory or instrumented implementation in tests.
+ */
+import { randomBytes } from 'node:crypto';
+import { dirname } from 'node:path';
+import { mkdir as nodeMkdir, readFile as nodeReadFile, readdir as nodeReaddir, rename as nodeRename, rm as nodeRm, stat as nodeStat, writeFile as nodeWriteFile, } from 'node:fs/promises';
+/** The default {@link FsLike}, backed by `node:fs/promises`. */
+export const nodeFs = {
+    async readFile(path) {
+        return nodeReadFile(path);
+    },
+    async writeFile(path, data) {
+        await nodeWriteFile(path, data);
+    },
+    async rename(from, to) {
+        await nodeRename(from, to);
+    },
+    async mkdir(path, options) {
+        await nodeMkdir(path, options);
+    },
+    async readdir(path) {
+        const entries = await nodeReaddir(path, { withFileTypes: true });
+        return entries.map((e) => ({ name: e.name, isDirectory: e.isDirectory(), isFile: e.isFile() }));
+    },
+    async stat(path) {
+        const s = await nodeStat(path);
+        return { isDirectory: s.isDirectory(), isFile: s.isFile(), size: s.size };
+    },
+    async rm(path, options) {
+        await nodeRm(path, options);
+    },
+};
+/** True when the error is a "no such file or directory" error. */
+export function isNotFound(error) {
+    return typeof error === 'object' && error !== null && error.code === 'ENOENT';
+}
+/** Reads a file, returning `undefined` instead of throwing when it does not exist. */
+export async function readFileIfExists(fs, path) {
+    try {
+        return await fs.readFile(path);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/** Lists a directory, returning `[]` instead of throwing when it does not exist. */
+export async function readdirIfExists(fs, path) {
+    try {
+        return await fs.readdir(path);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Writes `data` to `path` atomically: the bytes land in a sibling temp file that
+ * is then renamed over the target, so a crash mid-write can never leave a
+ * half-written project file behind.
+ */
+export async function writeFileAtomic(fs, path, data) {
+    await fs.mkdir(dirname(path), { recursive: true });
+    const temp = `${path}.tmp-${randomBytes(6).toString('hex')}`;
+    try {
+        await fs.writeFile(temp, data);
+        await fs.rename(temp, path);
+    }
+    catch (error) {
+        await fs.rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/project/history.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Persistent, per-project request history: a JSON-Lines file the desktop app keeps outside the
+ * project folder (under Electron's `userData`), so history survives even when the project folder
+ * 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.
+ */
+import type { FsLike } from './fs.js';
+import type { WsExchange, WsFrame } from '../ws/model.js';
+/** One HTTP header, in author order. */
+export interface HistoryHeader {
+    readonly name: string;
+    readonly value: string;
+}
+/** The SOAP fault a send resolved to, if any. */
+export interface HistoryFault {
+    readonly code: string;
+    readonly reason: string;
+}
+/** Why a send failed before a response was ever received (transport error, timeout, abort, ...). */
+export interface HistoryError {
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * The gRPC side of a history entry: the call and every message on both sides. The response is a
+ * list rather than one body because a server stream answers with several — the extension ADR-0007
+ * left room for — and the SOAP-shaped fields carry what they can (`interfaceName` the API, `endpoint`
+ * the target, `status` the HTTP status) so one history view serves all three protocols.
+ */
+export interface HistoryGrpc {
+    readonly service: string;
+    readonly method: string;
+    readonly methodKind: 'unary' | 'server-streaming' | 'client-streaming' | 'bidi-streaming';
+    /** The gRPC status code, absent when the call never produced one. */
+    readonly status?: number;
+    readonly statusName?: string;
+    readonly statusMessage?: string;
+    /** Request messages as canonical JSON text, in send order. */
+    readonly requestMessages: readonly string[];
+    /** Response messages as canonical JSON text (or base64 when one did not decode), in arrival order. */
+    readonly responseMessages: readonly string[];
+    readonly trailers: readonly HistoryHeader[];
+}
+/**
+ * The WebSocket side of a history entry: one session's handshake outcome, how it closed, the
+ * frame counts, and a capped transcript ({@link capFrames}) so a chatty session doesn't blow up
+ * the history file.
+ */
+export interface HistoryWs {
+    readonly url: string;
+    /** The handshake's HTTP status, absent when the handshake never got a response. */
+    readonly status?: number;
+    /** The subprotocol the server picked, absent when none was negotiated. */
+    readonly protocol?: string;
+    readonly closeCode: number;
+    readonly closeReason: string;
+    readonly closedBy: 'client' | 'server' | 'error';
+    readonly counts: WsExchange['counts'];
+    readonly frames: readonly WsFrame[];
+    /** Set only when {@link capFrames} actually trimmed something (frames, or just a payload). */
+    readonly truncated?: boolean;
+    /** How many frames were dropped by the head/tail cap; absent when only a payload was stripped. */
+    readonly omittedFrames?: number;
+    /** The handshake's transport error, absent when the handshake succeeded (or never ran). */
+    readonly error?: string;
+}
+/**
+ * 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.
+ */
+export interface HistoryEntry {
+    /** ulid, also the entry's sort key (ulids are lexicographically time-ordered). */
+    readonly id: string;
+    /**
+     * Which protocol this send used. Absent in every line written before the REST client, so a
+     * missing value reads as `'soap'` ({@link normalizeHistoryEntry}) and no file needs migrating.
+     *
+     * The response side of the record is deliberately one message. A protocol that answers with
+     * several — a gRPC server stream — extends this union with its own shape rather than bending
+     * this one, which is why the field exists before there is a second value for it to hold.
+     */
+    readonly kind?: 'soap' | 'rest' | 'grpc' | 'websocket';
+    /** The HTTP method, for a REST send. A SOAP send is always a POST and does not record one. */
+    readonly method?: string;
+    /** ISO-8601 timestamp of the send. */
+    readonly at: string;
+    readonly projectId: string;
+    /** The saved request this send came from, if it still existed at send time. */
+    readonly requestId?: string;
+    /** The saved request's name at send time, or a synthesised label for an ad-hoc/raw resend. */
+    readonly requestName: string;
+    readonly interfaceName: string;
+    readonly operationName: string;
+    readonly endpoint: string;
+    readonly soapVersion: '1.1' | '1.2' | 'none';
+    readonly soapAction?: string;
+    /** HTTP status, absent when the send never received a response. */
+    readonly status?: number;
+    readonly durationMs: number;
+    /** True for a 2xx response with no SOAP fault. */
+    readonly ok: boolean;
+    readonly fault?: HistoryFault;
+    readonly request: {
+        readonly envelopeXml: string;
+        readonly headers: readonly HistoryHeader[];
+    };
+    readonly response?: {
+        readonly envelopeXml?: string;
+        readonly rawHeaders: readonly (readonly [string, string])[];
+        readonly status: number;
+        readonly statusText: string;
+    };
+    readonly error?: HistoryError;
+    /** The call record of a gRPC send; absent for the other protocols. */
+    readonly grpc?: HistoryGrpc;
+    /** The session record of a WebSocket send; absent for the other protocols. */
+    readonly ws?: HistoryWs;
+    readonly sizeBytes: number;
+    readonly tags?: readonly string[];
+}
+/** Options accepted by {@link appendHistory} and {@link openHistory}. */
+export interface HistoryOptions {
+    readonly fs?: FsLike;
+    /** Oldest entries are dropped once the file holds more than this many. Defaults to 1000. */
+    readonly cap?: number;
+}
+/** Filters accepted by {@link HistoryFile.list}. */
+export interface HistoryListQuery {
+    /** Case-insensitive substring match over name/operation/interface/endpoint/status/fault/tags. */
+    readonly query?: string;
+    readonly limit?: number;
+    /** Only entries strictly older than this id (for paging past a previous page's last row). */
+    readonly before?: string;
+}
+/** A live handle on one project's history file: an in-memory cache backed by the jsonl file. */
+export interface HistoryFile {
+    /** Appends one entry (serialised, rotated against the configured cap) and updates the cache. */
+    append(entry: HistoryEntry): Promise<void>;
+    /** Newest-first entries matching `query`, most recent (or most recent before `before`) first. */
+    list(query?: HistoryListQuery): HistoryEntry[];
+    get(id: string): HistoryEntry | undefined;
+    /** Empties the file and the cache. Returns the number of entries that were cleared. */
+    clear(): Promise<number>;
+    count(): number;
+    /** Corrupt lines skipped while loading the file. */
+    readonly problems: number;
+}
+/**
+ * One entry as callers should see it: a line written before the REST client carried no `kind`,
+ * and every such send was SOAP. Applied on read so nothing has to rewrite a `.jsonl` file.
+ */
+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).
+ */
+export declare function appendHistory(file: string, entry: HistoryEntry, options?: HistoryOptions): 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.
+ */
+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;

package/dist/project/history.js

@@ -0,0 +1,179 @@
+/**
+ * Persistent, per-project request history: a JSON-Lines file the desktop app keeps outside the
+ * project folder (under Electron's `userData`), so history survives even when the project folder
+ * 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.
+ */
+import { ulid } from 'ulidx';
+import { nodeFs, readFileIfExists, writeFileAtomic } from './fs.js';
+import { capFrames } from '../ws/transcript.js';
+const DEFAULT_CAP = 1000;
+/**
+ * One entry as callers should see it: a line written before the REST client carried no `kind`,
+ * and every such send was SOAP. Applied on read so nothing has to rewrite a `.jsonl` file.
+ */
+export function normalizeHistoryEntry(entry) {
+    return entry.kind === undefined ? { ...entry, kind: 'soap' } : entry;
+}
+/** Case-insensitive substring test, empty needle always matches. */
+function matches(entry, needle) {
+    if (needle.length === 0) {
+        return true;
+    }
+    const lower = needle.toLowerCase();
+    const haystack = [
+        entry.requestName,
+        entry.operationName,
+        entry.interfaceName,
+        entry.endpoint,
+        entry.method ?? '',
+        entry.grpc?.service ?? '',
+        entry.grpc?.method ?? '',
+        entry.grpc?.statusName ?? '',
+        entry.ws?.url ?? '',
+        entry.ws?.protocol ?? '',
+        entry.status !== undefined ? String(entry.status) : '',
+        entry.fault?.reason ?? '',
+        ...(entry.tags ?? []),
+    ]
+        .join('\n')
+        .toLowerCase();
+    return haystack.includes(lower);
+}
+/** Parses one jsonl line into a `HistoryEntry`, or `undefined` when the line is corrupt/blank. */
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed !== 'object' || parsed === null || typeof parsed.id !== 'string') {
+            return undefined;
+        }
+        return normalizeHistoryEntry(parsed);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Reads a jsonl file's entries (oldest first, as stored) and the count of corrupt lines. */
+async function readAll(fs, file) {
+    const buffer = await readFileIfExists(fs, file);
+    if (buffer === undefined) {
+        return { entries: [], problems: 0 };
+    }
+    const lines = buffer.toString('utf8').split('\n');
+    const entries = [];
+    let problems = 0;
+    for (const line of lines) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        const entry = parseLine(line);
+        if (entry === undefined) {
+            problems += 1;
+            continue;
+        }
+        entries.push(entry);
+    }
+    return { entries, problems };
+}
+/** Serialises entries (oldest first) back to jsonl text. */
+function serialise(entries) {
+    return entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length > 0 ? '\n' : '');
+}
+/**
+ * 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).
+ */
+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));
+}
+/**
+ * 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.
+ */
+export async function openHistory(file, options = {}) {
+    const fs = options.fs ?? nodeFs;
+    const cap = options.cap ?? DEFAULT_CAP;
+    const { entries, problems } = await readAll(fs, file);
+    // Oldest-first in memory (matches on-disk order); newest-first is only materialised for `list`.
+    let cache = entries;
+    let queue = Promise.resolve();
+    const enqueue = (task) => {
+        const result = queue.then(task);
+        // Swallow rejections in the chain itself so one failed op doesn't wedge the queue for the
+        // next; the caller of this specific call still sees the real rejection via `result`.
+        queue = result.catch(() => undefined);
+        return result;
+    };
+    return {
+        problems,
+        append(entry) {
+            return enqueue(async () => {
+                cache.push(entry);
+                if (cache.length > cap) {
+                    cache = cache.slice(cache.length - cap);
+                }
+                await writeFileAtomic(fs, file, serialise(cache));
+            });
+        },
+        list(query) {
+            const needle = query?.query ?? '';
+            const limit = query?.limit ?? Number.POSITIVE_INFINITY;
+            const newestFirst = [...cache].reverse();
+            let startIndex = 0;
+            if (query?.before !== undefined) {
+                const cursor = newestFirst.findIndex((e) => e.id === query.before);
+                startIndex = cursor === -1 ? newestFirst.length : cursor + 1;
+            }
+            const filtered = newestFirst.slice(startIndex).filter((entry) => matches(entry, needle));
+            return filtered.slice(0, limit);
+        },
+        get(id) {
+            return cache.find((entry) => entry.id === id);
+        },
+        clear() {
+            return enqueue(async () => {
+                const cleared = cache.length;
+                cache = [];
+                await writeFileAtomic(fs, file, '');
+                return cleared;
+            });
+        },
+        count() {
+            return cache.length;
+        },
+    };
+}
+/** Generates a new history entry id (ulid: lexicographically time-ordered, unique). */
+export function generateHistoryId() {
+    return ulid();
+}
+/** Builds a {@link HistoryWs} from a completed session, applying {@link capFrames}. */
+export function historyWsOf(exchange) {
+    const { frames, truncated, omittedFrames } = capFrames(exchange.frames);
+    return {
+        url: exchange.url,
+        ...(exchange.handshake.status !== undefined ? { status: exchange.handshake.status } : {}),
+        ...(exchange.handshake.protocol !== undefined ? { protocol: exchange.handshake.protocol } : {}),
+        closeCode: exchange.closed.code,
+        closeReason: exchange.closed.reason,
+        closedBy: exchange.closed.by,
+        counts: exchange.counts,
+        frames,
+        ...(truncated ? { truncated: true, ...(omittedFrames > 0 ? { omittedFrames } : {}) } : {}),
+        ...(exchange.handshake.error !== undefined ? { error: exchange.handshake.error } : {}),
+    };
+}

package/dist/project/keystores.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The bridge between the project model's loose `WssRef` (which round-trips the raw
+ * `wss/keystores.yaml` entry verbatim, so an unknown field written by a later build survives)
+ * and the typed `KeystoreDef` the keystore loaders take.
+ */
+import type { WssRef } from './model.js';
+import type { KeystoreDef } from '../wss/keystore/model.js';
+/**
+ * Reads one keystore registry entry out of its `WssRef`.
+ *
+ * @param ref the `Project.wss.keystores` entry
+ * @returns the typed definition
+ * @throws ProjectError `keystore-entry-invalid` when the stored document is not a keystore entry
+ */
+export declare function toKeystoreDef(ref: WssRef): KeystoreDef;
+/**
+ * The `WssRef` that stores `def` in `wss/keystores.yaml`, preserving any unknown fields the
+ * existing entry carried.
+ *
+ * @param def the definition to persist
+ * @param existing the entry being replaced, when this is an update
+ * @returns the ref to put into `Project.wss.keystores`
+ */
+export declare function toKeystoreRef(def: KeystoreDef, existing?: WssRef): WssRef;