@responsibleai/agent-hooks 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/declaration.js

@@ -0,0 +1,752 @@
+"use strict";
+// Copyright (c) Microsoft. All rights reserved.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeclarationBuilder = exports.HostDeclaration = exports.HostRegistry = exports.HostSurface = exports.HostRegistryError = exports.DeclarationError = exports.DeclarationErrorClass = exports.CAPABILITIES = exports.MAX_TIMEOUT_MS = exports.MAX_DETAIL_LEN = exports.MAX_KIND_LEN = exports.MAX_ID_LEN = exports.MAX_BINDINGS = exports.MAX_DEPTH = exports.MAX_DOCUMENT_BYTES = exports.SUPPORTED_DECLARATION_VERSIONS = exports.DECLARATION_VERSION = void 0;
+exports.fullKnobSupport = fullKnobSupport;
+exports.validReference = validReference;
+exports.validKind = validKind;
+exports.canonicalDeclaration = canonicalDeclaration;
+exports.resolveDeclaration = resolveDeclaration;
+exports.resolveSurfaceOnly = resolveSurfaceOnly;
+exports.declarationVersions = declarationVersions;
+/**
+ * Host declaration document (spec §7.7): the loader, the registry it
+ * resolves against, and the builder for the code path.
+ *
+ * A declaration is one JSON object that fixes a host's configuration
+ * (§7.1, §8, §10.1, §13.1), its declared surface (§13.1) and its
+ * interceptor bindings. It is a versioned contract of its own
+ * (`agent-hooks-declaration/<major>.<minor>`, §7.7.2), separate from
+ * the wire version `SPEC_VERSION` and from the package version.
+ *
+ * Every normative check lives in the Rust core. This module does the
+ * two things only the wrapper can do: read a file (step 1 of §7.7.6)
+ * and run the host's kind resolvers (step 11, in `emitter.ts`). Steps
+ * 2 to 10 cross the native boundary as JSON text, so a document yields
+ * the same refusal class here as in every other SDK.
+ */
+const promises_1 = require("node:fs/promises");
+const index_1 = require("./index");
+const native_1 = require("./native");
+/** The declaration contract version this SDK writes and accepts
+ * (§7.7.2). A test pins it to the core's `declaration_versions()`. */
+exports.DECLARATION_VERSION = "agent-hooks-declaration/1.0";
+/** Every contract version the loader accepts (§7.7.2). Any other
+ * `declaration` value is refused as `declaration_error:version_unsupported`. */
+exports.SUPPORTED_DECLARATION_VERSIONS = Object.freeze([
+    exports.DECLARATION_VERSION,
+]);
+/** Largest document the text and file paths accept, in bytes (§7.7.3). */
+exports.MAX_DOCUMENT_BYTES = 1 << 20;
+/** Deepest nesting the text paths accept (§7.7.3). */
+exports.MAX_DEPTH = 32;
+/** Most entries in `bindings` (§7.7.3). */
+exports.MAX_BINDINGS = 256;
+/** Longest binding `id`, registered name and document `id` (§7.7.3). */
+exports.MAX_ID_LEN = 64;
+/** Longest binding `kind` (§7.7.5). */
+exports.MAX_KIND_LEN = 128;
+/** Longest refusal detail (§7.7.3). */
+exports.MAX_DETAIL_LEN = 512;
+/** Largest `timeout_ms`, `interceptor_ms` and `approval_resolver_ms` (§7.7.3). */
+exports.MAX_TIMEOUT_MS = 3_600_000;
+/** The closed capability vocabulary a surface may name (§7.7.4). */
+exports.CAPABILITIES = Object.freeze([
+    "model_calls",
+    "tool_calls",
+    "parallel_tool_calls",
+    "streaming",
+    "multi_turn",
+    "int64_json",
+    "bigint_json",
+    "incremental_output",
+    "host_declaration",
+]);
+/** §3 lifecycle order; the order sets of points are written in. */
+const POINT_ORDER = Object.freeze([
+    "agent_startup",
+    "input",
+    "pre_model_call",
+    "post_model_call",
+    "pre_tool_call",
+    "post_tool_call",
+    "output",
+    "agent_shutdown",
+]);
+/** The §3.2 floor every surface carries. */
+const FLOOR_POINTS = Object.freeze([
+    "agent_startup",
+    "input",
+    "output",
+    "agent_shutdown",
+]);
+const RESERVED_KIND_SEGMENTS = Object.freeze(["agent_hooks", "ctk"]);
+// ---- errors -----------------------------------------------------------------
+/** The eleven refusal classes (§7.7.6), in pipeline order. */
+exports.DeclarationErrorClass = Object.freeze({
+    Unreadable: "declaration_error:unreadable",
+    Malformed: "declaration_error:malformed",
+    VersionUnsupported: "declaration_error:version_unsupported",
+    SpecUnsupported: "declaration_error:spec_unsupported",
+    UnknownField: "declaration_error:unknown_field",
+    InvalidField: "declaration_error:invalid_field",
+    Inconsistent: "declaration_error:inconsistent",
+    SurfaceUnsupported: "declaration_error:surface_unsupported",
+    ReferenceUnresolved: "declaration_error:reference_unresolved",
+    KindUnknown: "declaration_error:kind_unknown",
+    BindingRejected: "declaration_error:binding_rejected",
+});
+function truncate(s) {
+    const chars = Array.from(s);
+    if (chars.length <= exports.MAX_DETAIL_LEN)
+        return s;
+    return chars.slice(0, exports.MAX_DETAIL_LEN - 1).join("") + "…";
+}
+/** A refused declaration (§7.7.6). Carries one class, every finding
+ * that step produced and, for `version_unsupported`, the accepted
+ * version set. Thrown by every construction path; never a verdict. */
+class DeclarationError extends Error {
+    code;
+    findings;
+    accepted;
+    constructor(
+    /** The namespaced code, `declaration_error:<class>`. */
+    code, findings, accepted = []) {
+        // Bound the findings before anything reads them: the message, the
+        // `findings` list and every log line built from either carry the
+        // same 512-character detail (§7.7.6), so a resolver cannot push an
+        // unbounded string into a host's log through `.message`.
+        const bounded = DeclarationError.bound(findings);
+        super(DeclarationError.describe(code, bounded));
+        this.code = code;
+        this.name = "DeclarationError";
+        this.findings = bounded;
+        this.accepted = [...accepted];
+    }
+    /** One finding under `code`. */
+    static single(code, pointer, detail) {
+        return new DeclarationError(code, [{ pointer, detail }]);
+    }
+    /** Rebuild the error the core reported across the native boundary:
+     * `code` is the `declaration_error:*` string and `detail` the JSON
+     * `{"findings": [...], "accepted": [...]}`. */
+    static fromCore(code, detail) {
+        let findings = [];
+        let accepted = [];
+        try {
+            const parsed = JSON.parse(detail);
+            findings = parsed.findings ?? [];
+            accepted = parsed.accepted ?? [];
+        }
+        catch {
+            findings = [{ pointer: "", detail }];
+        }
+        return new DeclarationError(code, findings, accepted);
+    }
+    /** Copy `findings` with every detail truncated to {@link MAX_DETAIL_LEN}. */
+    static bound(findings) {
+        return findings.map((f) => ({ pointer: f.pointer, detail: truncate(f.detail) }));
+    }
+    /** `code: pointer: detail; pointer: detail` (the Rust `Display`). */
+    static describe(code, findings) {
+        let out = code;
+        findings.forEach((f, i) => {
+            out += i === 0 ? ": " : "; ";
+            out += f.pointer === "" ? f.detail : `${f.pointer}: ${f.detail}`;
+        });
+        return out;
+    }
+}
+exports.DeclarationError = DeclarationError;
+/** A host registry programming error: a duplicate or reserved name, or
+ * a code surface the core rejects. Distinct from
+ * {@link DeclarationError}: the document is not at fault. */
+class HostRegistryError extends Error {
+    constructor(detail) {
+        super(`host registry: ${detail}`);
+        this.name = "HostRegistryError";
+    }
+}
+exports.HostRegistryError = HostRegistryError;
+/** Run a native declaration call and retype its failures: a
+ * `declaration_error:*` code becomes {@link DeclarationError};
+ * `marshal_error` (the wrapper described its own surface wrongly)
+ * becomes {@link HostRegistryError}. */
+function declarationCall(fn) {
+    try {
+        return fn();
+    }
+    catch (e) {
+        if (e instanceof native_1.AgentHooksCoreError) {
+            if (e.code.startsWith("declaration_error:")) {
+                throw DeclarationError.fromCore(e.code, e.detail);
+            }
+            if (e.code === "marshal_error") {
+                throw new HostRegistryError(e.detail);
+            }
+        }
+        throw e;
+    }
+}
+/** Every value of every knob the profile consults (§7.2). */
+function fullKnobSupport(profile) {
+    switch (profile) {
+        case "sequential/first_deny":
+            return { on_approval: ["resume", "stop"] };
+        case "parallel/strictest":
+            return { on_transform_conflict: ["approval", "deny"] };
+        case "parallel/unanimous":
+            return { on_disagreement: ["approval", "deny"] };
+        default:
+            return {};
+    }
+}
+function sortedPoints(points) {
+    const set = new Set(points);
+    return POINT_ORDER.filter((p) => set.has(p));
+}
+function sortedStrings(items) {
+    return [...new Set(items)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** Constructors for {@link HostSurface}. The core validates the
+ * surface (floor, pairs, closed vocabularies) when a document is
+ * resolved against it; a surface that fails there is a
+ * {@link HostRegistryError}, never a refusal of the document. */
+exports.HostSurface = Object.freeze({
+    /** The smallest honest surface for this SDK: the lifecycle floor,
+     * `host_declaration`, every profile with every knob value, posture
+     * `continue`, buffered output, bounded timeouts and every accepted
+     * contract version. A host adds what its runtime does. */
+    sdkDefault() {
+        return {
+            interception_points: [...FLOOR_POINTS],
+            capabilities: ["host_declaration"],
+            profiles: {
+                "sequential/first_deny": fullKnobSupport("sequential/first_deny"),
+                "sequential/run_all": {},
+                "parallel/strictest": fullKnobSupport("parallel/strictest"),
+                "parallel/unanimous": fullKnobSupport("parallel/unanimous"),
+            },
+            tool_seam_host_error: "continue",
+            streams_unbuffered: false,
+            interceptor_timeout: "bounded",
+            declaration_versions: [...exports.SUPPORTED_DECLARATION_VERSIONS],
+        };
+    },
+    /** The surface the CTK derives from a harness's capability list and
+     * posture (§7.7.9): the floor plus the model points iff
+     * `model_calls` plus the tool points iff `tool_calls`. A list naming
+     * `incremental_output` needs {@link HostSurface.withExposureBound}
+     * on top, or the core refuses the surface. */
+    fromCapabilities(caps, posture = "continue") {
+        const s = exports.HostSurface.sdkDefault();
+        s.tool_seam_host_error = posture;
+        const points = new Set(FLOOR_POINTS);
+        const capabilities = new Set();
+        for (const c of caps) {
+            if (c === "model_calls") {
+                points.add("pre_model_call");
+                points.add("post_model_call");
+            }
+            else if (c === "tool_calls") {
+                points.add("pre_tool_call");
+                points.add("post_tool_call");
+            }
+            else if (c === "incremental_output") {
+                s.streams_unbuffered = true;
+            }
+            capabilities.add(c);
+        }
+        s.interception_points = sortedPoints(points);
+        s.capabilities = sortedStrings(capabilities);
+        return s;
+    },
+    /** Add points (the model pair, the tool pair, or both). */
+    withPoints(surface, points) {
+        return {
+            ...surface,
+            interception_points: sortedPoints([...surface.interception_points, ...points]),
+        };
+    },
+    /** Add capabilities. */
+    withCapabilities(surface, caps) {
+        return { ...surface, capabilities: sortedStrings([...surface.capabilities, ...caps]) };
+    },
+    /** State the §12.1a exposure bound an incremental host enforces. Also
+     * marks the host as able to declare `buffered_output: false`. */
+    withExposureBound(surface, bound) {
+        return { ...surface, streams_unbuffered: true, exposure_bound: bound };
+    },
+});
+/** Reference grammar for resolver and redactor names and binding ids:
+ * `^[a-z][a-z0-9_-]{0,63}$`. */
+function validReference(s) {
+    return /^[a-z][a-z0-9_-]*$/.test(s) && s.length <= exports.MAX_ID_LEN;
+}
+/** Binding kind grammar (§7.7.5): dot-separated lowercase segments, at
+ * least two, at most 128 characters. */
+function validKind(s) {
+    if (s.length > exports.MAX_KIND_LEN)
+        return false;
+    const segs = s.split(".");
+    return segs.length >= 2 && segs.every((seg) => /^[a-z][a-z0-9_-]*$/.test(seg));
+}
+/** Everything a host registers in code for a declaration to reference
+ * (§7.7.5): the code surface, kind resolvers, custom identity
+ * providers, approval resolvers and approval redactors. One registry
+ * can build many emitters. */
+class HostRegistry {
+    surface;
+    allowReserved;
+    kinds = new Map();
+    identityProviders = new Map();
+    approvalResolvers = new Map();
+    approvalRedactors = new Map();
+    /** A registry over the given code surface. Kinds under the reserved
+     * `agent_hooks` and `ctk` segments are refused. */
+    constructor(surface, allowReserved = false) {
+        this.surface = surface;
+        this.allowReserved = allowReserved;
+    }
+    /** The conformance kit's registry: as the constructor, but the `ctk`
+     * kind segment may be registered. */
+    static forConformance(surface) {
+        return new HostRegistry(surface, true);
+    }
+    /** Register a kind resolver. */
+    kind(kind, resolver) {
+        if (!validKind(kind)) {
+            throw new HostRegistryError(`kind ${JSON.stringify(kind)} does not match the kind grammar (see spec §7.7.5)`);
+        }
+        const head = kind.split(".")[0];
+        if (RESERVED_KIND_SEGMENTS.includes(head) && !(this.allowReserved && head === "ctk")) {
+            throw new HostRegistryError(`kind ${JSON.stringify(kind)} uses the reserved segment ${JSON.stringify(head)} (see spec §7.7.5)`);
+        }
+        if (this.kinds.has(kind)) {
+            throw new HostRegistryError(`kind ${JSON.stringify(kind)} registered twice`);
+        }
+        if (typeof resolver !== "function") {
+            throw new HostRegistryError(`kind ${JSON.stringify(kind)} resolver is not a function`);
+        }
+        this.kinds.set(kind, resolver);
+        return this;
+    }
+    /** Register a custom identity provider (§10.1 name rules apply). */
+    identityProvider(name, fn) {
+        if (!/^[a-z][a-z0-9_-]*$/.test(name) || name.startsWith("jcs")) {
+            throw new HostRegistryError(`identity provider name ${JSON.stringify(name)} must match ^[a-z][a-z0-9_-]*$ and must not begin with 'jcs' (see spec §10.1)`);
+        }
+        if (name.length > exports.MAX_ID_LEN) {
+            throw new HostRegistryError(`identity provider name ${JSON.stringify(name)} exceeds ${exports.MAX_ID_LEN} characters`);
+        }
+        if (this.identityProviders.has(name)) {
+            throw new HostRegistryError(`identity provider ${JSON.stringify(name)} registered twice`);
+        }
+        this.identityProviders.set(name, fn);
+        return this;
+    }
+    /** Register an approval resolver under a reference name. */
+    approvalResolver(name, resolver) {
+        HostRegistry.checkReference(name, "approval resolver");
+        if (this.approvalResolvers.has(name)) {
+            throw new HostRegistryError(`approval resolver ${JSON.stringify(name)} registered twice`);
+        }
+        this.approvalResolvers.set(name, resolver);
+        return this;
+    }
+    /** Register an approval redactor under a reference name. */
+    approvalRedactor(name, fn) {
+        HostRegistry.checkReference(name, "approval redactor");
+        if (this.approvalRedactors.has(name)) {
+            throw new HostRegistryError(`approval redactor ${JSON.stringify(name)} registered twice`);
+        }
+        this.approvalRedactors.set(name, fn);
+        return this;
+    }
+    /** The registered names, derived (§7.7.5). */
+    names() {
+        return {
+            identity_providers: sortedStrings(this.identityProviders.keys()),
+            approval_resolvers: sortedStrings(this.approvalResolvers.keys()),
+            approval_redactors: sortedStrings(this.approvalRedactors.keys()),
+            kinds: sortedStrings(this.kinds.keys()),
+        };
+    }
+    /** The `host_json` the core's `declaration_resolve` takes: the surface
+     * plus the registered names. */
+    hostDescription() {
+        return JSON.stringify({ surface: this.surface, ...this.names() });
+    }
+    /** @internal */
+    kindResolver(kind) {
+        return this.kinds.get(kind);
+    }
+    /** @internal */
+    identityFn(name) {
+        return this.identityProviders.get(name);
+    }
+    /** @internal */
+    approvalResolverRef(name) {
+        return this.approvalResolvers.get(name);
+    }
+    /** @internal */
+    redactorFn(name) {
+        return this.approvalRedactors.get(name);
+    }
+    static checkReference(name, what) {
+        if (!validReference(name)) {
+            throw new HostRegistryError(`${what} name ${JSON.stringify(name)} does not match ^[a-z][a-z0-9_-]{0,63}$`);
+        }
+    }
+}
+exports.HostRegistry = HostRegistry;
+// ---- document ---------------------------------------------------------------
+/** A declaration that passed steps 2 to 7 (§7.7.6): parsed, of an
+ * accepted version, closed, well-typed and internally consistent as
+ * stated. Not yet checked against any host; `InterceptionEmitter.
+ * fromDeclaration` does that. */
+class HostDeclaration {
+    doc;
+    text;
+    /** `text` is the core's serialization of the validated document and
+     * is what every later core call receives. The loader refuses any
+     * integer token beyond 2^53 - 1 anywhere in the document (§7.7.6),
+     * so `doc`, the JavaScript view of the same text, carries every
+     * number exactly. */
+    constructor(doc, text) {
+        this.doc = doc;
+        this.text = text;
+    }
+    /** Step 1 then {@link HostDeclaration.fromJson}: open exactly `path`,
+     * require a regular file of at most {@link MAX_DOCUMENT_BYTES},
+     * strict UTF-8 without a byte-order mark, read once. */
+    static async fromPath(path) {
+        const unreadable = (detail) => DeclarationError.single(exports.DeclarationErrorClass.Unreadable, "", detail);
+        let size;
+        try {
+            const st = await (0, promises_1.stat)(path);
+            if (!st.isFile())
+                throw unreadable("not a regular file");
+            size = st.size;
+        }
+        catch (e) {
+            if (e instanceof DeclarationError)
+                throw e;
+            throw unreadable(`cannot stat: ${ioClass(e)}`);
+        }
+        if (size > exports.MAX_DOCUMENT_BYTES) {
+            throw unreadable(`document is ${size} bytes; the bound is ${exports.MAX_DOCUMENT_BYTES}`);
+        }
+        // Read through a bounded loop: a file that grows between the stat
+        // and the read is still loaded only up to the bound plus one byte,
+        // then refused.
+        const buf = Buffer.alloc(exports.MAX_DOCUMENT_BYTES + 1);
+        let total = 0;
+        try {
+            const fh = await (0, promises_1.open)(path, "r");
+            try {
+                while (total < buf.length) {
+                    const { bytesRead } = await fh.read(buf, total, buf.length - total, total);
+                    if (bytesRead === 0)
+                        break;
+                    total += bytesRead;
+                }
+            }
+            finally {
+                await fh.close();
+            }
+        }
+        catch (e) {
+            throw unreadable(`cannot read: ${ioClass(e)}`);
+        }
+        if (total > exports.MAX_DOCUMENT_BYTES) {
+            throw unreadable(`document is ${total} bytes; the bound is ${exports.MAX_DOCUMENT_BYTES}`);
+        }
+        const bytes = buf.subarray(0, total);
+        if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+            throw unreadable("document starts with a byte-order mark");
+        }
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw unreadable("document is not valid UTF-8");
+        }
+        return HostDeclaration.fromJson(text);
+    }
+    /** Steps 2 to 7 over JSON text, in the core. */
+    static fromJson(text) {
+        const validated = declarationCall(() => native_1.native.declarationValidate(text));
+        return new HostDeclaration(JSON.parse(validated), validated);
+    }
+    /** Steps 2 to 7 over an in-memory value: serialized and handed to
+     * {@link HostDeclaration.fromJson}, so size, depth and shape checks
+     * are the same code on every path. A non-finite number, which
+     * `JSON.stringify` would corrupt to `null`, is refused as
+     * `malformed` first. */
+    static fromValue(value) {
+        const hit = (0, index_1.findNonFinite)(value);
+        if (hit !== null) {
+            throw DeclarationError.single(exports.DeclarationErrorClass.Malformed, "", `cannot serialize: ${(0, index_1.nonFiniteDetail)(hit)}`);
+        }
+        let text;
+        try {
+            text = JSON.stringify(value);
+        }
+        catch (e) {
+            throw DeclarationError.single(exports.DeclarationErrorClass.Malformed, "", `cannot serialize: ${e?.constructor?.name ?? "Error"}`);
+        }
+        if (text === undefined) {
+            throw DeclarationError.single(exports.DeclarationErrorClass.Malformed, "", "cannot serialize: value has no JSON form");
+        }
+        return HostDeclaration.fromJson(text);
+    }
+    /** A builder for the code path (§7.7.7). */
+    static builder() {
+        return new DeclarationBuilder();
+    }
+    /** The document's own `declaration` value. */
+    get version() {
+        const v = this.doc["declaration"];
+        return typeof v === "string" ? v : "";
+    }
+    /** The validated document, verbatim (including `$schema`). A copy.
+     * Every integer in a validated document is within ±(2^53 - 1), so
+     * this view loses nothing against {@link HostDeclaration.toJson}. */
+    toValue() {
+        return JSON.parse(this.text);
+    }
+    /** @internal The validated document as JSON text, as the core
+     * serialized it. */
+    toJson() {
+        return this.text;
+    }
+}
+exports.HostDeclaration = HostDeclaration;
+function ioClass(e) {
+    const err = e;
+    if (typeof err?.code === "string")
+        return err.code;
+    if (typeof err?.name === "string")
+        return err.name;
+    return "Error";
+}
+/** RFC 8785 canonical JSON of a resolved declaration (the core's
+ * `canonical_json`). */
+function canonicalDeclaration(resolved) {
+    return native_1.native.canonicalJson(JSON.stringify(resolved));
+}
+/** Steps 8 to 10 of §7.7.6 (after steps 2 to 7 again, in the core):
+ * resolve a validated declaration against the registry's surface and
+ * names. Throws {@link DeclarationError} on refusal. */
+function resolveDeclaration(declaration, registry) {
+    const resolved = declarationCall(() => native_1.native.declarationResolve(declaration.toJson(), registry.hostDescription()));
+    return JSON.parse(resolved);
+}
+/** Steps 7 (on the filled surface) and 8 against a code surface alone,
+ * without a registry: what the CTK runner uses on a harness's own
+ * document to learn the surface a run is assessed against (§7.7.9). */
+function resolveSurfaceOnly(declaration, surface) {
+    const resolved = declarationCall(() => native_1.native.declarationResolveSurface(declaration.toJson(), JSON.stringify(surface)));
+    return JSON.parse(resolved);
+}
+/** The contract versions the core writes and accepts (§7.7.2). */
+function declarationVersions() {
+    return JSON.parse(native_1.native.declarationVersions());
+}
+// ---- builder (code path) ----------------------------------------------------
+/** A null-prototype object: every key, `__proto__` included, is an
+ * own member that serializes, so the builder path refuses exactly what
+ * the value path refuses. */
+function plain() {
+    return Object.create(null);
+}
+/** Builds a declaration document in code, one setter per member
+ * (§7.7.7). {@link DeclarationBuilder.build} hands the document to
+ * {@link HostDeclaration.fromValue}, so the code path is validated by
+ * the same function, with the same classes, as a file. */
+class DeclarationBuilder {
+    doc;
+    /** A builder with `declaration` set to {@link DECLARATION_VERSION}
+     * and an empty `bindings` array. */
+    constructor() {
+        this.doc = plain();
+        this.doc["declaration"] = exports.DECLARATION_VERSION;
+        this.doc["bindings"] = [];
+    }
+    /** A builder with no member set at all, not even `declaration` or
+     * `bindings`. For harnesses that must express an incomplete
+     * document; a host wants the constructor. */
+    static empty() {
+        const b = new DeclarationBuilder();
+        delete b.doc["declaration"];
+        delete b.doc["bindings"];
+        return b;
+    }
+    configuration() {
+        return this.sub(this.doc, "configuration");
+    }
+    configurationSub(key) {
+        return this.sub(this.configuration(), key);
+    }
+    surface() {
+        return this.sub(this.doc, "surface");
+    }
+    sub(parent, key) {
+        const existing = parent[key];
+        if (existing !== null && typeof existing === "object" && !Array.isArray(existing)) {
+            return existing;
+        }
+        const fresh = plain();
+        parent[key] = fresh;
+        return fresh;
+    }
+    /** `declaration` (defaults to {@link DECLARATION_VERSION}). */
+    version(v) {
+        this.doc["declaration"] = v;
+        return this;
+    }
+    spec(v) {
+        this.doc["spec"] = v;
+        return this;
+    }
+    id(v) {
+        this.doc["id"] = v;
+        return this;
+    }
+    host(name, version) {
+        const h = plain();
+        h["name"] = name;
+        if (version !== undefined)
+            h["version"] = version;
+        this.doc["host"] = h;
+        return this;
+    }
+    mode(mode) {
+        this.configuration()["mode"] = mode;
+        return this;
+    }
+    /** The composition as the host states it. Knobs the profile does not
+     * consult are written out and refused by {@link build}, exactly as
+     * in a file. */
+    composition(c) {
+        const v = plain();
+        v["profile"] = c.profile;
+        if (c.on_approval !== undefined)
+            v["on_approval"] = c.on_approval;
+        if (c.on_disagreement !== undefined)
+            v["on_disagreement"] = c.on_disagreement;
+        if (c.on_transform_conflict !== undefined)
+            v["on_transform_conflict"] = c.on_transform_conflict;
+        this.configuration()["composition"] = v;
+        return this;
+    }
+    /** A name for `jcs-sha256` or a custom provider, `null` for
+     * identity-unbound. */
+    identityProvider(name) {
+        this.configuration()["identity_provider"] = name;
+        return this;
+    }
+    approvalResolver(name) {
+        this.configurationSub("approval")["resolver"] = name;
+        return this;
+    }
+    approvalRedactor(name) {
+        this.configurationSub("approval")["redactor"] = name;
+        return this;
+    }
+    toolSeamHostError(posture) {
+        this.configurationSub("posture")["tool_seam_host_error"] = posture;
+        return this;
+    }
+    /** `null` writes `null` (unbounded). */
+    interceptorTimeoutMs(ms) {
+        this.configurationSub("timeouts")["interceptor_ms"] = ms;
+        return this;
+    }
+    /** `null` writes `null` (unbounded). */
+    approvalResolverTimeoutMs(ms) {
+        this.configurationSub("timeouts")["approval_resolver_ms"] = ms;
+        return this;
+    }
+    /** `null` writes `null` (unbounded). */
+    maxBufferedRecords(n) {
+        this.configurationSub("records")["max_buffered"] = n;
+        return this;
+    }
+    surfacePoints(points) {
+        this.surface()["interception_points"] = sortedPoints(points);
+        return this;
+    }
+    surfaceCapabilities(caps) {
+        this.surface()["capabilities"] = sortedStrings(caps);
+        return this;
+    }
+    /** Declare support for one profile and its knob values. */
+    surfaceProfile(profile, knobs) {
+        const profiles = this.sub(this.surface(), "profiles");
+        const k = {};
+        if (knobs.on_approval && knobs.on_approval.length > 0)
+            k["on_approval"] = [...knobs.on_approval];
+        if (knobs.on_disagreement && knobs.on_disagreement.length > 0) {
+            k["on_disagreement"] = [...knobs.on_disagreement];
+        }
+        if (knobs.on_transform_conflict && knobs.on_transform_conflict.length > 0) {
+            k["on_transform_conflict"] = [...knobs.on_transform_conflict];
+        }
+        profiles[profile] = k;
+        return this;
+    }
+    /** `buffered_output` and, when `false`, the required exposure bound. */
+    bufferedOutput(buffered, exposureBound) {
+        const s = this.surface();
+        s["buffered_output"] = buffered;
+        if (exposureBound !== undefined)
+            s["exposure_bound"] = exposureBound;
+        else
+            delete s["exposure_bound"];
+        return this;
+    }
+    surfaceDeclarationVersions(versions) {
+        this.surface()["declaration_versions"] = sortedStrings(versions);
+        return this;
+    }
+    /** Append one binding. `at` omitted binds at every surface point;
+     * `timeoutMs` omitted inherits the configured interceptor timeout,
+     * `null` writes `null` (unbounded), a number bounds. */
+    bind(id, kind, config = {}, at, timeoutMs) {
+        const b = { id, kind, config };
+        if (at !== undefined)
+            b["at"] = sortedPoints(at);
+        if (timeoutMs !== undefined)
+            b["timeout_ms"] = timeoutMs;
+        const bindings = this.doc["bindings"];
+        if (Array.isArray(bindings))
+            bindings.push(b);
+        else
+            this.doc["bindings"] = [b];
+        return this;
+    }
+    /** One `extensions` entry, kept verbatim. */
+    extension(key, value) {
+        this.sub(this.doc, "extensions")[key] = value;
+        return this;
+    }
+    /** Set a top-level member verbatim. For members this builder has no
+     * setter for; the result is validated like any other document (an
+     * unknown member is refused as `unknown_field`). */
+    raw(key, value) {
+        this.doc[key] = value;
+        return this;
+    }
+    /** The document as built, before validation. A copy. */
+    toValue() {
+        return JSON.parse(JSON.stringify(this.doc));
+    }
+    /** Validate (steps 2 to 7) through {@link HostDeclaration.fromValue}. */
+    build() {
+        return HostDeclaration.fromValue(this.doc);
+    }
+}
+exports.DeclarationBuilder = DeclarationBuilder;