@wirebench/engine 2.1.1

package/dist/errors.js

@@ -0,0 +1,121 @@
+/**
+ * Base class for every error the engine throws. Every Wirebench error carries
+ * a stable, machine-readable `code` in addition to a human-readable message,
+ * so callers (CLI, IPC, UI) can branch on `code` without parsing text.
+ */
+export class WirebenchError extends Error {
+    /** Stable, machine-readable identifier for this error condition. */
+    code;
+    /** Structured context for the error, if any. */
+    details;
+    constructor(code, message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'WirebenchError';
+        this.code = code;
+        if (options?.details !== undefined) {
+            this.details = options.details;
+        }
+    }
+}
+/** Thrown when a WSDL document cannot be parsed or is structurally invalid. */
+export class WsdlParseError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'WsdlParseError';
+    }
+}
+/** Thrown for XML Schema (XSD) validation or resolution failures. */
+export class SchemaError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'SchemaError';
+    }
+}
+/** Thrown for HTTP transport failures (network, status, timeout). */
+export class HttpError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'HttpError';
+    }
+}
+/** Thrown for WS-Security signing/encryption/verification failures. */
+export class WssError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'WssError';
+    }
+}
+/** Thrown for WS-Addressing header construction failures. */
+export class WsaError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'WsaError';
+    }
+}
+/** Thrown for project file (load/save/migration) failures. */
+export class ProjectError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'ProjectError';
+    }
+}
+/** Thrown for workspace file (load/save/migration) failures. */
+export class WorkspaceError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'WorkspaceError';
+    }
+}
+/** Thrown when an OpenAPI document cannot be read, or describes something this client cannot import. */
+export class OpenApiError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'OpenApiError';
+    }
+}
+/** Thrown when a Postman collection cannot be read, or is structurally invalid. */
+export class PostmanError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'PostmanError';
+    }
+}
+/** Thrown when a legacy single-XML SOAP project file cannot be read, or is not one. */
+export class LegacyProjectError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'LegacyProjectError';
+    }
+}
+/** Thrown when a `.proto` set cannot be parsed, an import cannot be found, or a name does not resolve. */
+export class ProtoError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'ProtoError';
+    }
+}
+/** Thrown for gRPC transport failures: the connection, the HTTP/2 stream, or a malformed frame. */
+export class GrpcError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'GrpcError';
+    }
+}
+/** Thrown for WebSocket transport failures: the handshake, the connection, or a malformed frame. */
+export class WsError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'WsError';
+    }
+}
+/** Thrown when a value fails validation against a schema or business rule. */
+export class ValidationError extends WirebenchError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'ValidationError';
+    }
+}
+/** Type guard identifying any {@link WirebenchError} (base class or subclass). */
+export function isWirebenchError(e) {
+    return e instanceof WirebenchError;
+}

package/dist/fs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * "Does this path stay inside that folder?", answered against the real file system.
+ *
+ * The engine needs the same answer the desktop app's `main/path-containment.ts` gives, for a
+ * different reason: a WSDL fetched from anywhere may reference further documents by `file:`
+ * URL, and those references must not be able to walk out of the root document's own folder.
+ * Main's copy stays where it is — it guards renderer-named paths and is reachable from
+ * Electron-only code — but the rule itself is identical, so a fix here should be mirrored
+ * there (and vice versa).
+ */
+/**
+ * `path`, with `realpath` resolved through whatever prefix of it already exists on disk, the
+ * still-missing tail joined back on. Nothing is created; this only computes the path a later
+ * read would actually land at, so a symlink anywhere in the existing prefix cannot be used to
+ * escape a containment check.
+ *
+ * @param path the absolute path to resolve
+ * @returns the real path of the existing prefix joined with the unresolved tail
+ */
+export declare function realpathOfPrefix(path: string): Promise<string>;
+/**
+ * True when `candidate` is `root` itself or sits below it. Both must already be real paths.
+ *
+ * @param root the containing folder, as a real path
+ * @param candidate the path to test, as a real path
+ */
+export declare function isInsideReal(root: string, candidate: string): boolean;
+/**
+ * True when `candidate` resolves inside `root`, comparing real paths so a symlink cannot be
+ * used to point out of it.
+ *
+ * @param root the containing folder
+ * @param candidate the path to test
+ */
+export declare function isInsideRealDir(root: string, candidate: string): Promise<boolean>;

package/dist/fs.js

@@ -0,0 +1,64 @@
+/**
+ * "Does this path stay inside that folder?", answered against the real file system.
+ *
+ * The engine needs the same answer the desktop app's `main/path-containment.ts` gives, for a
+ * different reason: a WSDL fetched from anywhere may reference further documents by `file:`
+ * URL, and those references must not be able to walk out of the root document's own folder.
+ * Main's copy stays where it is — it guards renderer-named paths and is reachable from
+ * Electron-only code — but the rule itself is identical, so a fix here should be mirrored
+ * there (and vice versa).
+ */
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { existsSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+/**
+ * `path`, with `realpath` resolved through whatever prefix of it already exists on disk, the
+ * still-missing tail joined back on. Nothing is created; this only computes the path a later
+ * read would actually land at, so a symlink anywhere in the existing prefix cannot be used to
+ * escape a containment check.
+ *
+ * @param path the absolute path to resolve
+ * @returns the real path of the existing prefix joined with the unresolved tail
+ */
+export async function realpathOfPrefix(path) {
+    const tail = [];
+    let current = path;
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current) {
+            // Hit the filesystem root without finding anything that exists; nothing to resolve.
+            return path;
+        }
+        tail.unshift(basename(current));
+        current = parent;
+    }
+    try {
+        const real = await realpath(current);
+        return tail.length === 0 ? real : join(real, ...tail);
+    }
+    catch {
+        /* v8 ignore next 2 -- realpath of an existsSync-confirmed path only fails on a race */
+        return path;
+    }
+}
+/**
+ * True when `candidate` is `root` itself or sits below it. Both must already be real paths.
+ *
+ * @param root the containing folder, as a real path
+ * @param candidate the path to test, as a real path
+ */
+export function isInsideReal(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+/**
+ * True when `candidate` resolves inside `root`, comparing real paths so a symlink cannot be
+ * used to point out of it.
+ *
+ * @param root the containing folder
+ * @param candidate the path to test
+ */
+export async function isInsideRealDir(root, candidate) {
+    const [rootReal, candidateReal] = await Promise.all([realpathOfPrefix(root), realpathOfPrefix(candidate)]);
+    return isInsideReal(rootReal, candidateReal);
+}

package/dist/generate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Convenience wrappers around `buildSampleRequest`/`buildEmptyRequest` that
+ * take an {@link ImportResult} directly, so callers don't have to thread
+ * `definition`/`schemaSet` through by hand.
+ */
+import type { GeneratedRequest, OperationRef, RequestBuildOptions } from './soap/request-builder.js';
+import type { GenerateOptions } from './xsd/sample-generator.js';
+import type { ImportResult } from './types.js';
+/** Builds the sample SOAP request for one operation of an imported definition. */
+export declare function generateRequest(result: ImportResult, op: OperationRef, genOptions?: Partial<GenerateOptions>, options?: RequestBuildOptions): GeneratedRequest;
+/** Builds an empty SOAP request (empty `Header`/`Body`) for one operation of an imported definition. */
+export declare function generateEmptyRequest(result: ImportResult, op: OperationRef, options?: RequestBuildOptions): GeneratedRequest;

package/dist/generate.js

@@ -0,0 +1,14 @@
+/**
+ * Convenience wrappers around `buildSampleRequest`/`buildEmptyRequest` that
+ * take an {@link ImportResult} directly, so callers don't have to thread
+ * `definition`/`schemaSet` through by hand.
+ */
+import { buildEmptyRequest, buildSampleRequest } from './soap/request-builder.js';
+/** Builds the sample SOAP request for one operation of an imported definition. */
+export function generateRequest(result, op, genOptions, options) {
+    return buildSampleRequest({ definition: result.definition, schemaSet: result.schemaSet }, op, genOptions, options);
+}
+/** Builds an empty SOAP request (empty `Header`/`Body`) for one operation of an imported definition. */
+export function generateEmptyRequest(result, op, options) {
+    return buildEmptyRequest({ definition: result.definition, schemaSet: result.schemaSet }, op, options);
+}

package/dist/grpc/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The browser-safe face of `grpc/`: pure helpers with no Node dependency, reachable from the
+ * renderer as `@wirebench/engine/grpc` (ESLint allows this subpath and no other). Kept to what an
+ * editor needs to display — the effective target, the method path, the status names — so the
+ * renderer never reimplements a rule the transport enforces.
+ */
+export { clientStreams, defaultTlsFor, GRPC_REFLECTION_VERSIONS, grpcMethodPath, serverStreams } from './shape.js';
+export type { GrpcMethodKind, GrpcReflectionVersion } from './shape.js';
+export { GRPC_STATUS_NAMES, grpcStatusName } from './status.js';
+export { parseGrpcTarget } from './target.js';
+export type { GrpcTarget } from './target.js';

package/dist/grpc/browser.js

@@ -0,0 +1,9 @@
+/**
+ * The browser-safe face of `grpc/`: pure helpers with no Node dependency, reachable from the
+ * renderer as `@wirebench/engine/grpc` (ESLint allows this subpath and no other). Kept to what an
+ * editor needs to display — the effective target, the method path, the status names — so the
+ * renderer never reimplements a rule the transport enforces.
+ */
+export { clientStreams, defaultTlsFor, GRPC_REFLECTION_VERSIONS, grpcMethodPath, serverStreams } from './shape.js';
+export { GRPC_STATUS_NAMES, grpcStatusName } from './status.js';
+export { parseGrpcTarget } from './target.js';

package/dist/grpc/cache.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Persisting a gRPC API's schema under `apis/<slug>/definition/`, in either of the two forms it can
+ * arrive in.
+ *
+ * An **import** keeps the `.proto` files byte-exact, on the same contract the WSDL and OpenAPI caches
+ * keep: nothing is re-serialised, a `manifest.yaml` records each file's size and SHA-256 so
+ * corruption is noticed rather than parsed, and an export is byte-identical to what was imported.
+ * What differs is the layout: a `.proto` reaches its imports by path, so each file is stored under
+ * `protos/` *at its import path* — the set loads again from the cache exactly as it loaded from the
+ * user's folder, with no renaming to undo.
+ *
+ * **Server reflection** has no `.proto` text to keep: a server describes itself in the compiler's own
+ * output, so what is cached is the `FileDescriptorSet` it sent, as one binary file beside a manifest
+ * that says `kind: descriptors`. The two forms are siblings rather than variations of one: a manifest
+ * declares which it is, and {@link readGrpcDefinitionCache} hands the caller whichever it found.
+ */
+import type { FsLike } from '../project/fs.js';
+import type { DescriptorDefinitionCacheManifest, ProtoDefinitionCacheManifest } from '../project/schema.js';
+import type { ProtoSources } from './proto/load.js';
+/** The directory under `definition/` the `.proto` files live in, at their import paths. */
+export declare const PROTOS_DIR = "protos";
+/** The file under `definition/` a discovered schema's `FileDescriptorSet` is stored in. */
+export declare const DESCRIPTORS_FILE = "descriptors.binpb";
+/** Options accepted by the read and write halves. */
+export interface ProtoDefinitionCacheOptions {
+    /** Overrides the file system, e.g. for tests. Defaults to `nodeFs`. */
+    readonly fs?: FsLike;
+}
+/** Options accepted by {@link writeProtoDefinitionCache}. */
+export interface WriteProtoDefinitionCacheOptions extends ProtoDefinitionCacheOptions {
+    /** Where the files came from, as the user gave it. */
+    readonly source: string;
+    /** The import paths the load started from. */
+    readonly roots: readonly string[];
+    /** Overrides the clock used for `fetchedAt`. */
+    readonly now?: () => string;
+}
+/**
+ * Splits an import path into segments, each checked as a path segment (ADR-0005), so a file that
+ * calls itself `../../etc/passwd.proto` never leaves the cache directory.
+ *
+ * @throws ProjectError `project-path-invalid`
+ */
+export declare function protoPathSegments(path: string): string[];
+/**
+ * Writes every source byte-exact under `dir/protos/` alongside a `manifest.yaml`, and returns the
+ * manifest. The previous contents are REPLACED: a file the new manifest does not list is deleted.
+ *
+ * @param sources the `.proto` files, keyed by import path
+ * @param dir absolute path of the API's `definition/` directory
+ * @throws ProjectError `definition-cache-corrupt` for an empty set, `project-path-invalid` for an unsafe path
+ */
+export declare function writeProtoDefinitionCache(sources: ProtoSources, dir: string, options: WriteProtoDefinitionCacheOptions): Promise<ProtoDefinitionCacheManifest>;
+/** A cached `.proto` set: its manifest and every file it lists. */
+export interface CachedProtoDefinition {
+    readonly manifest: ProtoDefinitionCacheManifest;
+    readonly sources: Map<string, string>;
+}
+/**
+ * Reads a cache previously written by {@link writeProtoDefinitionCache}, verifying every file's
+ * bytes against its recorded SHA-256.
+ *
+ * @throws ProjectError `definition-cache-missing` when `dir` has no `manifest.yaml` or it is not a
+ * proto manifest, `definition-cache-corrupt` when a file is gone or its bytes no longer match
+ */
+export declare function readProtoDefinitionCache(dir: string, options?: ProtoDefinitionCacheOptions): Promise<CachedProtoDefinition>;
+/** Options accepted by {@link writeDescriptorDefinitionCache}. */
+export interface WriteDescriptorDefinitionCacheOptions extends ProtoDefinitionCacheOptions {
+    /** The target the server was asked at, as the user gave it. */
+    readonly source: string;
+    /** The descriptor files declaring the services. */
+    readonly roots: readonly string[];
+    /** The reflection protocol version that answered. */
+    readonly reflectionVersion?: 'v1' | 'v1alpha';
+    /** Overrides the clock used for `fetchedAt`. */
+    readonly now?: () => string;
+}
+/**
+ * Writes a discovered schema's `FileDescriptorSet` byte-exact beside a `manifest.yaml`, and returns
+ * the manifest. Any `.proto` cache the directory held is removed: an API has one definition.
+ *
+ * @param descriptors the encoded `FileDescriptorSet`
+ * @param dir absolute path of the API's `definition/` directory
+ * @throws ProjectError `definition-cache-corrupt` when there are no bytes to write
+ */
+export declare function writeDescriptorDefinitionCache(descriptors: Uint8Array, dir: string, options: WriteDescriptorDefinitionCacheOptions): Promise<DescriptorDefinitionCacheManifest>;
+/** A cached descriptor set: its manifest and the `FileDescriptorSet` bytes. */
+export interface CachedDescriptorDefinition {
+    readonly manifest: DescriptorDefinitionCacheManifest;
+    readonly descriptors: Uint8Array;
+}
+/**
+ * Reads a cache previously written by {@link writeDescriptorDefinitionCache}, verifying the bytes
+ * against the recorded SHA-256.
+ *
+ * @throws ProjectError `definition-cache-missing` when `dir` has no `manifest.yaml` or it is not a
+ * descriptor manifest, `definition-cache-corrupt` when the set is gone or no longer matches
+ */
+export declare function readDescriptorDefinitionCache(dir: string, options?: ProtoDefinitionCacheOptions): Promise<CachedDescriptorDefinition>;
+/** Whichever of the two gRPC definition caches a directory holds. */
+export type CachedGrpcDefinition = ({
+    readonly kind: 'proto';
+} & CachedProtoDefinition) | ({
+    readonly kind: 'descriptors';
+} & CachedDescriptorDefinition);
+/**
+ * Reads a gRPC API's definition cache whichever form it is in, so a caller that only wants a loaded
+ * schema does not have to know which one was written.
+ *
+ * @throws ProjectError `definition-cache-missing` when there is no manifest or it declares a kind
+ * this build does not know, and whatever the matching reader throws
+ */
+export declare function readGrpcDefinitionCache(dir: string, options?: ProtoDefinitionCacheOptions): Promise<CachedGrpcDefinition>;

package/dist/grpc/cache.js

@@ -0,0 +1,244 @@
+/**
+ * Persisting a gRPC API's schema under `apis/<slug>/definition/`, in either of the two forms it can
+ * arrive in.
+ *
+ * An **import** keeps the `.proto` files byte-exact, on the same contract the WSDL and OpenAPI caches
+ * keep: nothing is re-serialised, a `manifest.yaml` records each file's size and SHA-256 so
+ * corruption is noticed rather than parsed, and an export is byte-identical to what was imported.
+ * What differs is the layout: a `.proto` reaches its imports by path, so each file is stored under
+ * `protos/` *at its import path* — the set loads again from the cache exactly as it loaded from the
+ * user's folder, with no renaming to undo.
+ *
+ * **Server reflection** has no `.proto` text to keep: a server describes itself in the compiler's own
+ * output, so what is cached is the `FileDescriptorSet` it sent, as one binary file beside a manifest
+ * that says `kind: descriptors`. The two forms are siblings rather than variations of one: a manifest
+ * declares which it is, and {@link readGrpcDefinitionCache} hands the caller whichever it found.
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { ProjectError } from '../errors.js';
+import { nodeFs, readFileIfExists, readdirIfExists, writeFileAtomic } from '../project/fs.js';
+import { assertPathSegment } from '../project/paths.js';
+import { descriptorDefinitionCacheManifestSchema, parseFile, protoDefinitionCacheManifestSchema, } from '../project/schema.js';
+import { parseYaml, stringifyYaml } from '../project/yaml.js';
+const MANIFEST_FILE = 'manifest.yaml';
+/** The directory under `definition/` the `.proto` files live in, at their import paths. */
+export const PROTOS_DIR = 'protos';
+/** The file under `definition/` a discovered schema's `FileDescriptorSet` is stored in. */
+export const DESCRIPTORS_FILE = 'descriptors.binpb';
+function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * Splits an import path into segments, each checked as a path segment (ADR-0005), so a file that
+ * calls itself `../../etc/passwd.proto` never leaves the cache directory.
+ *
+ * @throws ProjectError `project-path-invalid`
+ */
+export function protoPathSegments(path) {
+    const segments = path.split('/');
+    if (segments.length === 0 || segments.some((segment) => segment === '')) {
+        throw new ProjectError('project-path-invalid', `"${path}" is not a usable .proto import path`, {
+            details: { path },
+        });
+    }
+    for (const segment of segments) {
+        assertPathSegment(segment);
+    }
+    return segments;
+}
+/** Every file under `dir`, recursively, as `/`-separated paths relative to it. */
+async function listFiles(fs, dir, prefix = '') {
+    const out = [];
+    for (const entry of await readdirIfExists(fs, dir)) {
+        if (entry.isDirectory) {
+            out.push(...(await listFiles(fs, join(dir, entry.name), `${prefix}${entry.name}/`)));
+        }
+        else if (entry.isFile) {
+            out.push(`${prefix}${entry.name}`);
+        }
+    }
+    return out;
+}
+/**
+ * Writes every source byte-exact under `dir/protos/` alongside a `manifest.yaml`, and returns the
+ * manifest. The previous contents are REPLACED: a file the new manifest does not list is deleted.
+ *
+ * @param sources the `.proto` files, keyed by import path
+ * @param dir absolute path of the API's `definition/` directory
+ * @throws ProjectError `definition-cache-corrupt` for an empty set, `project-path-invalid` for an unsafe path
+ */
+export async function writeProtoDefinitionCache(sources, dir, options) {
+    const fs = options.fs ?? nodeFs;
+    if (sources.size === 0) {
+        throw new ProjectError('definition-cache-corrupt', 'A proto definition cache needs at least one file', {
+            details: { dir },
+        });
+    }
+    const protosDir = join(dir, PROTOS_DIR);
+    const existing = await listFiles(fs, protosDir);
+    const files = [...sources.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, text]) => {
+        protoPathSegments(path);
+        const bytes = Buffer.from(text, 'utf8');
+        return { path, sha256: sha256Hex(bytes), bytes: bytes.byteLength, content: bytes };
+    });
+    const manifest = {
+        formatVersion: 1,
+        kind: 'proto',
+        source: options.source,
+        fetchedAt: (options.now ?? (() => new Date().toISOString()))(),
+        roots: [...options.roots],
+        files: files.map(({ path, sha256, bytes }) => ({ path, sha256, bytes })),
+    };
+    for (const file of files) {
+        await writeFileAtomic(fs, join(protosDir, ...protoPathSegments(file.path)), file.content);
+    }
+    await writeFileAtomic(fs, join(dir, MANIFEST_FILE), stringifyYaml(manifest));
+    const keep = new Set(files.map((file) => file.path));
+    for (const stale of existing) {
+        if (!keep.has(stale)) {
+            await fs.rm(join(protosDir, ...stale.split('/')), { force: true });
+        }
+    }
+    // An API re-imported from files after having been discovered leaves no descriptor set behind.
+    await fs.rm(join(dir, DESCRIPTORS_FILE), { force: true });
+    return manifest;
+}
+/**
+ * Reads and parses `definition/manifest.yaml` as an untyped document.
+ *
+ * @throws ProjectError `definition-cache-missing` when there is none
+ */
+async function readManifestDocument(fs, dir) {
+    const path = join(dir, MANIFEST_FILE);
+    const raw = await readFileIfExists(fs, path);
+    if (raw === undefined) {
+        throw new ProjectError('definition-cache-missing', `No definition cache manifest at ${path}`, {
+            details: { dir },
+        });
+    }
+    return { path, document: parseYaml(raw.toString('utf8'), path) };
+}
+/** The `kind` a manifest document declares, or `undefined` when it declares none. */
+function manifestKind(document) {
+    if (typeof document !== 'object' || document === null || Array.isArray(document)) {
+        return undefined;
+    }
+    const kind = document.kind;
+    return typeof kind === 'string' ? kind : undefined;
+}
+/**
+ * Reads a cache previously written by {@link writeProtoDefinitionCache}, verifying every file's
+ * bytes against its recorded SHA-256.
+ *
+ * @throws ProjectError `definition-cache-missing` when `dir` has no `manifest.yaml` or it is not a
+ * proto manifest, `definition-cache-corrupt` when a file is gone or its bytes no longer match
+ */
+export async function readProtoDefinitionCache(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const { path: manifestPath, document } = await readManifestDocument(fs, dir);
+    if (manifestKind(document) !== 'proto') {
+        throw new ProjectError('definition-cache-missing', `${manifestPath} is not a .proto definition cache`, {
+            details: { dir },
+        });
+    }
+    const manifest = parseFile(protoDefinitionCacheManifestSchema, document, manifestPath);
+    const sources = new Map();
+    for (const file of manifest.files) {
+        const bytes = await readFileIfExists(fs, join(dir, PROTOS_DIR, ...protoPathSegments(file.path)));
+        if (bytes === undefined) {
+            throw new ProjectError('definition-cache-corrupt', `${file.path} is listed in the manifest but missing from the cache`, {
+                details: { dir, path: file.path },
+            });
+        }
+        if (sha256Hex(bytes) !== file.sha256) {
+            throw new ProjectError('definition-cache-corrupt', `${file.path} no longer matches the hash the manifest recorded`, {
+                details: { dir, path: file.path },
+            });
+        }
+        sources.set(file.path, bytes.toString('utf8'));
+    }
+    return { manifest, sources };
+}
+/**
+ * Writes a discovered schema's `FileDescriptorSet` byte-exact beside a `manifest.yaml`, and returns
+ * the manifest. Any `.proto` cache the directory held is removed: an API has one definition.
+ *
+ * @param descriptors the encoded `FileDescriptorSet`
+ * @param dir absolute path of the API's `definition/` directory
+ * @throws ProjectError `definition-cache-corrupt` when there are no bytes to write
+ */
+export async function writeDescriptorDefinitionCache(descriptors, dir, options) {
+    const fs = options.fs ?? nodeFs;
+    if (descriptors.byteLength === 0) {
+        throw new ProjectError('definition-cache-corrupt', 'A descriptor definition cache needs a descriptor set', {
+            details: { dir },
+        });
+    }
+    const content = Buffer.from(descriptors);
+    const manifest = {
+        formatVersion: 1,
+        kind: 'descriptors',
+        source: options.source,
+        fetchedAt: (options.now ?? (() => new Date().toISOString()))(),
+        roots: [...options.roots],
+        ...(options.reflectionVersion !== undefined ? { reflectionVersion: options.reflectionVersion } : {}),
+        file: { path: DESCRIPTORS_FILE, sha256: sha256Hex(content), bytes: content.byteLength },
+    };
+    await writeFileAtomic(fs, join(dir, DESCRIPTORS_FILE), content);
+    await writeFileAtomic(fs, join(dir, MANIFEST_FILE), stringifyYaml(manifest));
+    // An API rediscovered by reflection after having been imported keeps no .proto files behind.
+    const protosDir = join(dir, PROTOS_DIR);
+    for (const stale of await listFiles(fs, protosDir)) {
+        await fs.rm(join(protosDir, ...stale.split('/')), { force: true });
+    }
+    return manifest;
+}
+/**
+ * Reads a cache previously written by {@link writeDescriptorDefinitionCache}, verifying the bytes
+ * against the recorded SHA-256.
+ *
+ * @throws ProjectError `definition-cache-missing` when `dir` has no `manifest.yaml` or it is not a
+ * descriptor manifest, `definition-cache-corrupt` when the set is gone or no longer matches
+ */
+export async function readDescriptorDefinitionCache(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const { path: manifestPath, document } = await readManifestDocument(fs, dir);
+    if (manifestKind(document) !== 'descriptors') {
+        throw new ProjectError('definition-cache-missing', `${manifestPath} is not a descriptor definition cache`, {
+            details: { dir },
+        });
+    }
+    const manifest = parseFile(descriptorDefinitionCacheManifestSchema, document, manifestPath);
+    const bytes = await readFileIfExists(fs, join(dir, ...protoPathSegments(manifest.file.path)));
+    if (bytes === undefined) {
+        throw new ProjectError('definition-cache-corrupt', `${manifest.file.path} is listed in the manifest but missing from the cache`, { details: { dir, path: manifest.file.path } });
+    }
+    if (sha256Hex(bytes) !== manifest.file.sha256) {
+        throw new ProjectError('definition-cache-corrupt', `${manifest.file.path} no longer matches the hash the manifest recorded`, { details: { dir, path: manifest.file.path } });
+    }
+    return { manifest, descriptors: new Uint8Array(bytes) };
+}
+/**
+ * Reads a gRPC API's definition cache whichever form it is in, so a caller that only wants a loaded
+ * schema does not have to know which one was written.
+ *
+ * @throws ProjectError `definition-cache-missing` when there is no manifest or it declares a kind
+ * this build does not know, and whatever the matching reader throws
+ */
+export async function readGrpcDefinitionCache(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const { path: manifestPath, document } = await readManifestDocument(fs, dir);
+    switch (manifestKind(document)) {
+        case 'proto':
+            return { kind: 'proto', ...(await readProtoDefinitionCache(dir, options)) };
+        case 'descriptors':
+            return { kind: 'descriptors', ...(await readDescriptorDefinitionCache(dir, options)) };
+        default:
+            throw new ProjectError('definition-cache-missing', `${manifestPath} is not a gRPC definition cache`, {
+                details: { dir, kind: manifestKind(document) },
+            });
+    }
+}