@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/protocol/features.js

@@ -0,0 +1,64 @@
+/**
+ * Features: what a host can switch off (spec §4.1). Every protocol is one; `scripts` is the first
+ * that is not. A feature set is immutable: a host that changes a switch creates a new set.
+ */
+function assertNoCycle(byId) {
+    const done = new Set();
+    const visit = (id, path) => {
+        if (path.includes(id)) {
+            throw new Error(`createFeatureSet: "requires" cycle: ${[...path, id].join(' -> ')}`);
+        }
+        if (done.has(id))
+            return;
+        for (const required of byId.get(id)?.requires ?? []) {
+            visit(required, [...path, id]);
+        }
+        done.add(id);
+    };
+    for (const id of byId.keys())
+        visit(id, []);
+}
+/**
+ * Builds a feature set. A feature is on when its switch says so (its `default` when no switch
+ * names it) and every feature it requires is on. A switch for an id with no descriptor is ignored:
+ * it may belong to a module this build does not have.
+ *
+ * @throws Error for a duplicate id or a `requires` cycle; both are programming errors
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export function createFeatureSet(descriptors, switches = {}) {
+    const byId = new Map();
+    for (const descriptor of descriptors) {
+        if (byId.has(descriptor.id)) {
+            throw new Error(`createFeatureSet: duplicate feature "${descriptor.id}"`);
+        }
+        byId.set(descriptor.id, descriptor);
+    }
+    assertNoCycle(byId);
+    const why = new Map();
+    const resolve = (id) => {
+        if (why.has(id))
+            return why.get(id);
+        const descriptor = byId.get(id);
+        let result;
+        if (descriptor === undefined) {
+            result = { by: 'unknown' };
+        }
+        else if (!(switches[id] ?? descriptor.default)) {
+            result = { by: 'switch' };
+        }
+        else {
+            const blocked = descriptor.requires.find((required) => resolve(required) !== undefined);
+            result = blocked !== undefined ? { by: 'requires', feature: blocked } : undefined;
+        }
+        why.set(id, result);
+        return result;
+    };
+    for (const id of byId.keys())
+        resolve(id);
+    return {
+        descriptors: [...byId.values()],
+        isEnabled: (id) => resolve(id) === undefined,
+        whyDisabled: (id) => resolve(id),
+    };
+}

package/dist/protocol/index.d.ts

@@ -0,0 +1,7 @@
+/** Protocol modules, their registry and the feature set (spec §3, §4). */
+export { createFeatureSet } from './features.js';
+export type { FeatureDescriptor, FeatureSet, WhyDisabled } from './features.js';
+export { defineProtocol } from './module.js';
+export type { ContainerBase, ContainerDir, LoadContext, ProtocolModule, ProtocolRun, ProtocolScripting, ProtocolStorage, RequestSnapshotBase, ResponseSnapshotBase, RunGroup, RunScope, ScriptedSend, SelectedBase, SnapshotFacts, } from './module.js';
+export { createProtocolRegistry, featureDisabled } from './registry.js';
+export type { ProtocolRegistry, ProtocolRegistryOptions } from './registry.js';

package/dist/protocol/index.js

@@ -0,0 +1,4 @@
+/** Protocol modules, their registry and the feature set (spec §3, §4). */
+export { createFeatureSet } from './features.js';
+export { defineProtocol } from './module.js';
+export { createProtocolRegistry, featureDisabled } from './registry.js';

package/dist/protocol/module.d.ts

@@ -0,0 +1,247 @@
+/**
+ * A protocol behind one interface (spec §3, ADR-0017): how its containers are stored, how its
+ * requests run, and what a script sees of them. Core code calls a module through the registry and
+ * never names a protocol. This file imports no protocol.
+ */
+import type { z } from 'zod';
+import type { Assertion } from '../assert/model.js';
+import type { FsLike } from '../project/fs.js';
+import type { ProjectProblem } from '../project/load.js';
+import type { Project } from '../project/model.js';
+import type { RunContext } from '../run/context.js';
+import type { ExchangeHandle, ExchangeOptions } from '../run/exchange.js';
+import type { SendHost } from '../run/host.js';
+import type { ScriptSession } from '../run/script-support.js';
+import type { SecretNeed } from '../secrets/env-names.js';
+import type { HeaderPair, RequestScripts, ScriptFailure, ScriptPhase } from '../script/model.js';
+import type { RequestScriptTypes } from '../script/request-scripts.js';
+import type { SecretPlaceholders } from '../script/send.js';
+import type { ApiReferenceSection } from '../script/types/api.js';
+import type { FeatureDescriptor } from './features.js';
+/**
+ * The two top-level directories a project keeps containers in (ADR-0003, ADR-0007).
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export type ContainerDir = 'interfaces' | 'apis';
+/**
+ * What every container has, whatever its protocol.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ContainerBase {
+    readonly kind: string;
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+}
+/**
+ * What a module's loader is given. Problems that do not stop the load are pushed to `problems`.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface LoadContext {
+    readonly fs: FsLike;
+    /** The project folder. */
+    readonly root: string;
+    readonly problems: ProjectProblem[];
+}
+/**
+ * How a protocol's containers are read from and written to a project folder (spec §3.2).
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ProtocolStorage<C extends ContainerBase = ContainerBase> {
+    /** Where its containers live: `interfaces` (SOAP) or `apis` (every other protocol). */
+    readonly dir: ContainerDir;
+    /**
+     * Reads the container directory `<dir>/<slug>/`, given its already-parsed container file.
+     * Returns undefined when the container cannot be used and a problem was recorded.
+     *
+     * @throws ProjectError what the file schemas throw
+     */
+    load(ctx: LoadContext, slug: string, document: unknown): Promise<C | undefined>;
+    /** Every file the container is written as: path relative to the project root, to its text. */
+    files(container: C): ReadonlyMap<string, string>;
+    /** The files under `<dir>/<slug>/` a save may delete when it no longer writes them. */
+    managed(fs: FsLike, root: string, slug: string): Promise<readonly string[]>;
+    /** The project's containers of this kind. */
+    containers(project: Project): readonly C[];
+    /** The project with its containers of this kind replaced. */
+    withContainers(project: Project, containers: readonly C[]): Project;
+}
+/**
+ * What every selected request has, whatever its protocol.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface SelectedBase {
+    readonly kind: string;
+    /** The display path, `<group>/<request name>`. */
+    readonly path: string;
+    readonly group: string;
+    readonly request: {
+        readonly id: string;
+        readonly name: string;
+        readonly slug: string;
+        readonly assertions?: readonly Assertion[];
+        readonly scripts?: RequestScripts;
+    };
+}
+/**
+ * One container's runnable requests, in explorer order.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface RunGroup<S extends SelectedBase = SelectedBase> {
+    readonly order: number;
+    readonly name: string;
+    readonly candidates: readonly {
+        readonly item: S;
+        /** The request's path on disk, without the `.request.yaml` suffix. */
+        readonly diskPath: string;
+    }[];
+    /** Sent only when a selector names it, and listed after every container (webhook items). */
+    readonly explicitOnly?: true;
+}
+/**
+ * What a module is given for one run.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface RunScope {
+    readonly context: RunContext;
+    /**
+     * One value per key for the whole run. A load that rejects is remembered and rejects again.
+     * Keys are `<kind>:<container id>:<what>`.
+     */
+    memo<T>(key: string, load: () => Promise<T>): Promise<T>;
+}
+/**
+ * The scripts of one send, when the request has active scripts.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ScriptedSend {
+    readonly session: ScriptSession;
+    readonly placeholders: SecretPlaceholders;
+}
+/**
+ * How a protocol's requests run (spec §3.3).
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ProtocolRun<S extends SelectedBase = SelectedBase> {
+    /** The requests a run can send, one group per container (and any `explicitOnly` group). */
+    groups(project: Project): readonly RunGroup<S>[];
+    /** For a request id found in this protocol's containers but not runnable: why. */
+    whyNotRunnable(project: Project, requestId: string): string | undefined;
+    /**
+     * Opens one send (spec §4): resolve, pre-request script, connect, send. The send's own failure
+     * rejects `result`; it throws at once only for a request of another kind.
+     */
+    open(selected: S, scope: RunScope, host: SendHost, options: ExchangeOptions): ExchangeHandle;
+    /** The resolve step alone (spec §3.3): what a send would send, with nothing connected. */
+    resolve(selected: S, scope: RunScope, host: SendHost): Promise<unknown>;
+    /** The request's script types, from whatever contract the run has cached for it. */
+    scriptTypes(selected: S, scope: RunScope): Promise<RequestScriptTypes>;
+    /** The secrets this protocol's configuration needs: auth, keystores, signing, WS-Security. */
+    secretNeeds(selected: S, project: Project): readonly SecretNeed[];
+}
+/**
+ * What every request snapshot carries.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface RequestSnapshotBase {
+    readonly protocol: string;
+}
+/**
+ * What every response snapshot carries.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ResponseSnapshotBase {
+    readonly protocol: string;
+}
+/**
+ * What core's script rules check on a request snapshot (spec §3.4).
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface SnapshotFacts {
+    /** Where the request goes. A URL keeps its scheme, host and port; anything else stays identical. */
+    readonly destination: string;
+    /** Values a script may not change at all. Compared before and after with `JSON.stringify`. */
+    readonly fixed: unknown;
+    /** Header or metadata pairs: no name or value may hold CR, LF or NUL. */
+    readonly pairs: readonly HeaderPair[];
+    /** Other single-line values (a URL, a SOAPAction): none may hold CR, LF or NUL. */
+    readonly lines: readonly string[];
+    /** Every text in which a `${secret:…}` reference would be expanded. */
+    readonly texts: readonly string[];
+}
+/**
+ * What a script sees of a protocol's requests and responses (spec §3.4).
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ProtocolScripting<Q extends RequestSnapshotBase = RequestSnapshotBase, R extends ResponseSnapshotBase = ResponseSnapshotBase> {
+    /** The API's ambient declarations for one phase, after the common ones. */
+    declarations(phase: ScriptPhase): string;
+    /** The docs site's reference sections for this protocol, in order. */
+    reference(): readonly ApiReferenceSection[];
+    /** Sandbox-side source that defines `request` and `response` from the input snapshot. */
+    prelude(phase: ScriptPhase): string;
+    /** The shape a pre-request script may hand back. */
+    readonly requestSchema: z.ZodType<Q>;
+    /** What core's rules check. */
+    inspect(snapshot: Q): SnapshotFacts;
+    /** Protocol-only rules on a changed request, run after core's. */
+    validate?(before: Q, after: Q): ScriptFailure | undefined;
+    /** Typed views a script sees that the snapshot does not carry (SOAP's typed `body`). */
+    readonly views?: {
+        request(snapshot: Q, types: RequestScriptTypes): Q;
+        response(snapshot: R, types: RequestScriptTypes): R;
+        /** Writes a changed view back into the snapshot, or refuses the script. */
+        writeBack(before: Q, after: Q, types: RequestScriptTypes): {
+            readonly ok: true;
+            readonly request: Q;
+        } | {
+            readonly ok: false;
+            readonly error: ScriptFailure;
+        };
+    };
+}
+/**
+ * One protocol (spec §3).
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ProtocolModule {
+    /** The `kind` written on the container file and on every request file under it. */
+    readonly kind: string;
+    /** The feature that switches this protocol; its `id` equals `kind`. */
+    readonly feature: FeatureDescriptor;
+    /** How its containers are read from and written to a project folder. */
+    readonly storage: ProtocolStorage;
+    /** Absent: the protocol's requests cannot be run. */
+    readonly run?: ProtocolRun;
+    /** Absent: the protocol's requests cannot have scripts. */
+    readonly scripting?: ProtocolScripting;
+}
+/**
+ * A module as the registry holds it: the facets written against the protocol's own types, with a
+ * guard on every call that takes a selected request, so a wrong pairing fails loudly.
+ *
+ * @throws Error when the feature's id is not the module's kind
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export declare function defineProtocol<S extends SelectedBase>(module: {
+    readonly kind: string;
+    readonly feature: FeatureDescriptor;
+    readonly storage: ProtocolStorage;
+    readonly run?: ProtocolRun<S>;
+    readonly scripting?: ProtocolScripting;
+}): ProtocolModule;

package/dist/protocol/module.js

@@ -0,0 +1,48 @@
+function assertKind(module, item) {
+    if (item.kind !== module) {
+        throw new Error(`The "${module}" protocol was handed a "${item.kind}" request`);
+    }
+}
+/**
+ * A module as the registry holds it: the facets written against the protocol's own types, with a
+ * guard on every call that takes a selected request, so a wrong pairing fails loudly.
+ *
+ * @throws Error when the feature's id is not the module's kind
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export function defineProtocol(module) {
+    const { run } = module;
+    if (module.feature.id !== module.kind) {
+        throw new Error(`defineProtocol: the feature of "${module.kind}" must have the same id`);
+    }
+    return {
+        kind: module.kind,
+        feature: module.feature,
+        storage: module.storage,
+        ...(module.scripting !== undefined ? { scripting: module.scripting } : {}),
+        ...(run !== undefined
+            ? {
+                run: {
+                    groups: (project) => run.groups(project),
+                    whyNotRunnable: (project, requestId) => run.whyNotRunnable(project, requestId),
+                    open: (selected, scope, host, options) => {
+                        assertKind(module.kind, selected);
+                        return run.open(selected, scope, host, options);
+                    },
+                    resolve: (selected, scope, host) => {
+                        assertKind(module.kind, selected);
+                        return run.resolve(selected, scope, host);
+                    },
+                    scriptTypes: (selected, scope) => {
+                        assertKind(module.kind, selected);
+                        return run.scriptTypes(selected, scope);
+                    },
+                    secretNeeds: (selected, project) => {
+                        assertKind(module.kind, selected);
+                        return run.secretNeeds(selected, project);
+                    },
+                },
+            }
+            : {}),
+    };
+}

package/dist/protocol/registry.d.ts

@@ -0,0 +1,42 @@
+/** The modules a host composed, with its feature set (spec §4.2). */
+import { WirebenchError } from '../errors.js';
+import type { FeatureDescriptor, FeatureSet } from './features.js';
+import type { ProtocolModule } from './module.js';
+/**
+ * The modules of one host.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ProtocolRegistry {
+    readonly features: FeatureSet;
+    /** The enabled modules, in registration order. */
+    readonly modules: readonly ProtocolModule[];
+    status(kind: string): 'enabled' | 'disabled' | 'unknown';
+    /** The enabled module for `kind`, or undefined. */
+    find(kind: string): ProtocolModule | undefined;
+    /** @throws WirebenchError `feature-disabled` | ProjectError `project-kind-not-supported` */
+    require(kind: string): ProtocolModule;
+}
+/**
+ * What a registry is built with besides its modules.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface ProtocolRegistryOptions {
+    /** Descriptors for features that are not protocols (`scripts`). */
+    readonly features?: readonly FeatureDescriptor[];
+    readonly switches?: Readonly<Record<string, boolean>>;
+}
+/**
+ * The error for using a feature that is off: a WirebenchError `feature-disabled` with
+ * `details.feature`, and `details.requires` when a required feature is what is off.
+ */
+export declare function featureDisabled(features: FeatureSet, id: string): WirebenchError;
+/**
+ * Builds a registry from `modules`. Its feature set is the modules' descriptors plus
+ * `options.features`, with `options.switches` applied.
+ *
+ * @throws Error for two modules of one kind; what `createFeatureSet` throws
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export declare function createProtocolRegistry(modules: readonly ProtocolModule[], options?: ProtocolRegistryOptions): ProtocolRegistry;

package/dist/protocol/registry.js

@@ -0,0 +1,47 @@
+/** The modules a host composed, with its feature set (spec §4.2). */
+import { ProjectError, WirebenchError } from '../errors.js';
+import { createFeatureSet } from './features.js';
+/**
+ * The error for using a feature that is off: a WirebenchError `feature-disabled` with
+ * `details.feature`, and `details.requires` when a required feature is what is off.
+ */
+export function featureDisabled(features, id) {
+    const why = features.whyDisabled(id);
+    const title = features.descriptors.find((descriptor) => descriptor.id === id)?.title ?? id;
+    return new WirebenchError('feature-disabled', why?.by === 'requires' ? `${title} is off because "${why.feature}" is off` : `${title} is switched off`, { details: { feature: id, ...(why?.by === 'requires' ? { requires: why.feature } : {}) } });
+}
+/**
+ * Builds a registry from `modules`. Its feature set is the modules' descriptors plus
+ * `options.features`, with `options.switches` applied.
+ *
+ * @throws Error for two modules of one kind; what `createFeatureSet` throws
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export function createProtocolRegistry(modules, options = {}) {
+    const byKind = new Map();
+    for (const module of modules) {
+        if (byKind.has(module.kind)) {
+            throw new Error(`createProtocolRegistry: two modules for "${module.kind}"`);
+        }
+        byKind.set(module.kind, module);
+    }
+    const features = createFeatureSet([...modules.map((module) => module.feature), ...(options.features ?? [])], options.switches);
+    const status = (kind) => !byKind.has(kind) ? 'unknown' : features.isEnabled(kind) ? 'enabled' : 'disabled';
+    const find = (kind) => status(kind) === 'enabled' ? byKind.get(kind) : undefined;
+    return {
+        features,
+        modules: modules.filter((module) => features.isEnabled(module.kind)),
+        status,
+        find,
+        require(kind) {
+            const found = find(kind);
+            if (found !== undefined)
+                return found;
+            if (status(kind) === 'disabled')
+                throw featureDisabled(features, kind);
+            throw new ProjectError('project-kind-not-supported', `This build has no "${kind}" protocol`, {
+                details: { kind, supported: [...byKind.keys()] },
+            });
+        },
+    };
+}

package/dist/protocols.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The composition file (spec §4.3): the one core file that imports every built-in protocol module.
+ * It holds the built-in registry every entry point falls back to, and the union types a host that
+ * narrows on `kind` uses.
+ */
+import type { GrpcCallResult } from './grpc/call.js';
+import type { GrpcLiveEvent } from './grpc/events.js';
+import type { GrpcResolvedInput, GrpcSelected } from './grpc/run.js';
+import type { GrpcRequestSnapshot, GrpcResponseSnapshot } from './grpc/scripting.js';
+import type { FeatureDescriptor } from './protocol/features.js';
+import type { ProtocolModule } from './protocol/module.js';
+import type { ProtocolRegistry } from './protocol/registry.js';
+import type { RestSelected } from './rest/run.js';
+import type { RestRequestSnapshot, RestResponseSnapshot } from './rest/scripting.js';
+import type { RestLiveEvent } from './rest/events.js';
+import type { RestExchange, RestSendInput } from './rest/send.js';
+import type { SoapSelected } from './soap/run.js';
+import type { SoapRequestSnapshot, SoapResponseSnapshot } from './soap/scripting.js';
+import type { SoapExchange, SoapSendInput, WsdlImportResult } from './soap/types.js';
+import type { WsLiveEvent } from './ws/events.js';
+import type { WsExchange } from './ws/model.js';
+import type { WsSelected } from './ws/run.js';
+/**
+ * The four built-in protocols, in the order their containers tie-break in the explorer.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export declare const BUILTIN_PROTOCOLS: readonly ProtocolModule[];
+/** The feature that switches request scripts (#63). Not a protocol, so the registry is told of it. */
+export declare const SCRIPTS_FEATURE: FeatureDescriptor;
+/**
+ * A registry of the built-in protocols and the `scripts` feature, with `switches` applied.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export declare function createBuiltinRegistry(switches?: Readonly<Record<string, boolean>>): ProtocolRegistry;
+/**
+ * The registry an entry point uses when its caller passes none: the built-in protocols with every
+ * feature on. Created on first use and kept. Call it inside a function, never at module scope: the
+ * modules import core files that import this one.
+ */
+export declare function defaultRegistry(): ProtocolRegistry;
+/** One saved request selected for a run, of any built-in protocol a run can send. */
+export type SelectedRequest = SoapSelected | RestSelected | GrpcSelected | WsSelected;
+/** A SOAP interface's definition as a host already holds it in memory: imported and compiled. */
+export type HeldSoapDefinition = Pick<WsdlImportResult, 'definition' | 'bundle' | 'schemaSet' | 'wsa'>;
+/** The exchange a request travelled as, for a host that keeps more of it than a report does. */
+export type SentExchange = {
+    readonly kind: 'soap';
+    readonly soap: SoapExchange;
+    /** The request as resolved: references unexpanded, before its script and its credentials. */
+    readonly input: SoapSendInput;
+} | {
+    readonly kind: 'rest';
+    readonly rest: RestExchange;
+    /** What was sent: after the script, with the credentials resolved. */
+    readonly input: RestSendInput;
+    readonly contract?: unknown;
+} | {
+    readonly kind: 'grpc';
+    /** The call whole: every request message as sent, every response message decoded. */
+    readonly grpc: GrpcCallResult;
+    /** What was sent: after the script, with the credentials resolved. */
+    readonly input: GrpcResolvedInput;
+    /** The request message text as sent, after the script. */
+    readonly messageText: string;
+} | {
+    readonly kind: 'websocket';
+    /** The session whole: its handshake, every frame both ways, and how it closed. */
+    readonly ws: WsExchange;
+};
+/** A message an open exchange reports, whatever its protocol. */
+export type LiveEvent = RestLiveEvent | GrpcLiveEvent | WsLiveEvent;
+/** The request snapshot of any built-in protocol that has scripts (spec §3.1). */
+export type RequestSnapshot = RestRequestSnapshot | SoapRequestSnapshot | GrpcRequestSnapshot;
+/** The response snapshot of any built-in protocol that has scripts (spec §3.1). */
+export type ResponseSnapshot = RestResponseSnapshot | SoapResponseSnapshot | GrpcResponseSnapshot;

package/dist/protocols.js

@@ -0,0 +1,40 @@
+import { grpcProtocol } from './grpc/module.js';
+import { createProtocolRegistry } from './protocol/registry.js';
+import { restProtocol } from './rest/module.js';
+import { soapProtocol } from './soap/module.js';
+import { wsProtocol } from './ws/module.js';
+/**
+ * The four built-in protocols, in the order their containers tie-break in the explorer.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export const BUILTIN_PROTOCOLS = [soapProtocol, restProtocol, grpcProtocol, wsProtocol];
+/** The feature that switches request scripts (#63). Not a protocol, so the registry is told of it. */
+export const SCRIPTS_FEATURE = {
+    id: 'scripts',
+    title: 'Scripts',
+    default: true,
+    stage: 'stable',
+    requires: [],
+};
+/**
+ * A registry of the built-in protocols and the `scripts` feature, with `switches` applied.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export function createBuiltinRegistry(switches) {
+    return createProtocolRegistry(BUILTIN_PROTOCOLS, {
+        features: [SCRIPTS_FEATURE],
+        ...(switches !== undefined ? { switches } : {}),
+    });
+}
+let builtin;
+/**
+ * The registry an entry point uses when its caller passes none: the built-in protocols with every
+ * feature on. Created on first use and kept. Call it inside a function, never at module scope: the
+ * modules import core files that import this one.
+ */
+export function defaultRegistry() {
+    builtin ??= createBuiltinRegistry();
+    return builtin;
+}

package/dist/redact/index.d.ts

@@ -8,9 +8,15 @@
 export declare const REDACTED_MARKER = "<redacted>";
 /** True when `text` contains the redaction marker — i.e. it was produced by a `redact*` helper. */
 export declare function containsRedaction(text: string): boolean;
-/** Masks the values of sensitive headers in a plain header map, case-insensitively. */
+/** True when a header named `name` (any case) always carries a credential; see {@link redactHeaders}. */
+export declare function isSensitiveHeaderName(name: string): boolean;
+/**
+ * Masks the values of sensitive headers in a plain header map, case-insensitively. `extraHeaders`
+ * names more headers to mask, as `redactUrl`'s `extraParams` does for query parameters.
+ */
 export declare function redactHeaders(headers: Readonly<Record<string, string>>, opts?: {
     show?: boolean;
+    extraHeaders?: readonly string[];
 }): Record<string, string>;
 /**
  * Masks the values of sensitive headers in a `[name, value]` pair list — the raw, duplicate-
@@ -19,7 +25,10 @@ export declare function redactHeaders(headers: Readonly<Record<string, string>>,
  */
 export declare function redactHeaderPairs(pairs: readonly (readonly [string, string])[], opts?: {
     show?: boolean;
+    extraHeaders?: readonly string[];
 }): [string, string][];
+/** True when a query parameter named `name` (any case) carries a credential; see {@link redactUrl}. */
+export declare function isSensitiveQueryParam(name: string): boolean;
 /**
  * Masks the value of every sensitive query parameter in `url`, plus any parameter named in
  * `extraParams` — which is how the send path masks the exact parameter an API key is configured to
@@ -74,4 +83,6 @@ export declare function redactStructuredBody(text: string, contentType: string |
 export declare function redactRawHttp(input: string, opts?: {
     show?: boolean;
     encoding?: 'text' | 'base64';
+    extraParams?: readonly string[];
+    extraHeaders?: readonly string[];
 }): string;