@aventara/client 0.0.0-stage → 0.1.0-pilot.0

package/dist/config/config.resolver.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { AvProtocol } from "@aventara/core/protocol";
+/** The identity function that gives a `framework.client.ts` its type (§15.2). */
+export function defineClientConfig(config) {
+    return config;
+}
+/** Names an environment variable to be read from the resolved cascade (§15.2). */
+export function env(name) {
+    return { kind: "env", name };
+}
+/**
+ * The configuration cannot be resolved. The message is the whole diagnosis — the
+ * CLI prints it and exits non-zero; no stack is owed for a user's mistake.
+ */
+export class ClientConfigError extends Error {
+    name = "ClientConfigError";
+}
+/**
+ * Resolves a config against an already-resolved cascade. Pure: it reads no
+ * file and no global, so it is tested against literal inputs.
+ */
+export function resolveClientConfig(input) {
+    const entrypoint = resolveValue("entrypoint", input.config.entrypoint, input.cascade);
+    const generateAt = resolveValue("generateAt", input.config.generateAt, input.cascade);
+    return {
+        entrypoint: resolveEntrypoint(entrypoint),
+        generateAt: path.resolve(input.configDirectory, generateAt),
+        mode: input.cascade.mode,
+    };
+}
+function resolveValue(field, value, cascade) {
+    if (typeof value === "string") {
+        if (value === "")
+            throw new ClientConfigError(`${field} is empty.`);
+        return value;
+    }
+    const resolved = cascade.env[value.name];
+    if (resolved === undefined || resolved === "") {
+        throw new ClientConfigError(`${field} reads ${value.name}, which is not set in the process environment ` +
+            `or in any of ${cascade.candidates.join(", ")} (mode "${cascade.mode}").`);
+    }
+    return resolved;
+}
+/**
+ * The refusal's closing clause: what an entrypoint is. Never the value itself —
+ * an entrypoint may carry credentials.
+ */
+const ENTRYPOINT_IS = "it must be the origin plus a mount path";
+/**
+ * An entrypoint value resolved to its canonical form (F-822, architect's
+ * decision 2026-10-04; Q15). The URL half is this function's: whitespace (which
+ * the URL parser would trim or drop unseen), a value that is not an absolute
+ * URL, a scheme other than http(s), credentials (Q5, architect 2026-10-05), a
+ * query or fragment (even an empty one, which the parser forgets), and a `..`
+ * segment (which the parser would resolve away) are refused here, reading the
+ * value as written.
+ *
+ * The mount-path half is core's: the path AS WRITTEN — before `URL` has turned
+ * a backslash into a slash, resolved a `.` segment away or percent-encoded a
+ * character — goes to `AvProtocol.normalizeEntrypoint`, the rule the server's
+ * config resolution applies, so the two halves of F-822 cannot disagree
+ * (`entrypoint.parity.spec.ts`). Only its slash spelling is coerced — `api`,
+ * `/api/` and `//api//` are one intent, `/api` — and root is `""`.
+ *
+ * @throws ClientConfigError in one sentence that does not echo the value.
+ */
+export function resolveEntrypoint(value) {
+    if (/\s/u.test(value)) {
+        throw new ClientConfigError(`entrypoint contains whitespace; ${ENTRYPOINT_IS}, written without spaces, tabs or line breaks.`);
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ClientConfigError("entrypoint is not an absolute URL; it must be the deployed origin plus mount path.");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new ClientConfigError(`entrypoint must use http: or https:, not ${url.protocol}`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new ClientConfigError("entrypoint must not carry credentials: the platform's fetch refuses a URL that " +
+            "includes them, and the entrypoint is embedded in the generated client, which ships — " +
+            "authenticate through a custom fetch instead.");
+    }
+    if (value.includes("?") || value.includes("#")) {
+        throw new ClientConfigError("entrypoint must not carry a query or fragment; it is the origin plus mount path only.");
+    }
+    // Over the whole URL, authority included — wider than the mount-path rule,
+    // which refuses a `..` too — so a `..` anywhere keeps its shipped message.
+    if (value.split(/[/\\]/u).some(isDotDotSegment)) {
+        throw new ClientConfigError(`entrypoint's mount path has a .. segment; ${ENTRYPOINT_IS}, with no dot segments.`);
+    }
+    const normalized = AvProtocol.normalizeEntrypoint(writtenMountPath(value));
+    if (!normalized.ok) {
+        throw new ClientConfigError(`entrypoint's mount path ${normalized.message}.`);
+    }
+    const deployment = new URL(url.href);
+    deployment.pathname = "/";
+    return { deployment, path: normalized.path };
+}
+/**
+ * The mount path of an http(s) URL exactly as written: everything after the
+ * scheme, the slashes that follow it, and the authority. The authority ends
+ * where WHATWG URL parsing ends it for a special scheme — at the first `/`,
+ * `\`, `?` or `#` — so this is the text the parser turns into `pathname`,
+ * before it does.
+ */
+function writtenMountPath(value) {
+    return value.replace(/^[A-Za-z][A-Za-z0-9+.-]*:[/\\]*[^/\\?#]*/u, "");
+}
+/**
+ * The entrypoint as one absolute URL with no trailing slash — the form the
+ * emitted transport joins its routes to (§12.1), and the default a generated
+ * client embeds (§15.2, Q5: `generated/metadata.ts`'s `DEFAULT_ENTRYPOINT`).
+ * Root is the bare origin.
+ */
+export function entrypointHref(entrypoint) {
+    const url = new URL(entrypoint.deployment.href);
+    url.pathname = entrypoint.path === "" ? "/" : entrypoint.path;
+    return url.href.replace(/\/$/, "");
+}
+/** `..`, spelled as WHATWG URL resolution recognises it: `.` or `%2e`, any case. */
+function isDotDotSegment(segment) {
+    return /^(?:\.|%2e){2}$/iu.test(segment);
+}

package/dist/config/env.cascade.d.ts

@@ -0,0 +1,84 @@
+/**
+ * §15.2's `.env` cascade, resolved into a returned record.
+ *
+ * Precedence, highest first: the existing process environment
+ * > `.env.<mode>.local` > `.env.<mode>` > `.env.local` > `.env`.
+ *
+ * # Why a returned record, and not `process.loadEnvFile`
+ *
+ * Measured on Node v24.20.0, `process.loadEnvFile` is first-write-wins and never
+ * overrides an existing value — the right semantics — but it is the wrong
+ * mechanism here, for three reasons that were measured rather than argued:
+ *
+ * 1. It writes into the live `process.env`. A resolution that mutates the global
+ *    leaks across tests and across invocations in one process; a suite that
+ *    passes alone and fails in sequence is exactly that leak.
+ * 2. It reports an unreadable file (`EACCES`) as `ENOENT`. Catching `ENOENT`
+ *    from it would treat a `.env` the user cannot read as a `.env` that is not
+ *    there — a silent wrong answer.
+ * 3. It silently drops lines that are not assignments. So does `util.parseEnv`;
+ *    neither has a notion of a malformed file.
+ *
+ * So each file is read with `readFileSync` (whose error code is the truth),
+ * parsed with `util.parseEnv` (the same parser `loadEnvFile` uses — pinned by a
+ * parity test), checked for lines the parser would discard, and folded
+ * first-write-wins over the candidates in priority order. Nothing global is
+ * read or written: the process environment is an INPUT.
+ */
+/** A resolved environment: names to values, never `undefined`. */
+export type EnvRecord = Readonly<Record<string, string>>;
+/** The process environment as Node types it: values may be `undefined`. */
+export type ProcessEnvInput = Readonly<Record<string, string | undefined>>;
+/** The mode used when neither an explicit mode nor `NODE_ENV` supplies one. */
+export declare const DEFAULT_ENV_MODE = "development";
+/**
+ * Reads one candidate file. Returns `undefined` only when the file does not
+ * exist; any other failure throws. The seam exists so resolution can be tested
+ * without a filesystem — the default reads from disk.
+ */
+export type EnvFileReader = (filePath: string) => string | undefined;
+export interface EnvCascadeInput {
+    /** The directory the five candidates are looked up in. */
+    readonly directory: string;
+    /** A snapshot of the process environment. Never mutated. */
+    readonly processEnv: ProcessEnvInput;
+    /** An explicit mode; otherwise `NODE_ENV`, otherwise `development`. */
+    readonly mode?: string;
+    readonly read?: EnvFileReader;
+}
+export interface EnvCascadeResolution {
+    readonly mode: string;
+    readonly env: EnvRecord;
+    /** The candidate file names, highest precedence first. */
+    readonly candidates: readonly string[];
+    /** The candidates that existed and were read, highest precedence first. */
+    readonly loaded: readonly string[];
+}
+/** A candidate exists but could not be read, or contains a discarded line. */
+export declare class EnvFileError extends Error {
+    readonly filePath: string;
+    readonly reason: "unreadable" | "malformed";
+    readonly name = "EnvFileError";
+    constructor(filePath: string, reason: "unreadable" | "malformed", detail: string);
+}
+/** The four file candidates for a mode, highest precedence first. */
+export declare function envCascadeCandidates(mode: string): readonly string[];
+export declare function resolveEnvMode(processEnv: ProcessEnvInput, explicit?: string): string;
+export declare function resolveEnvCascade(input: EnvCascadeInput): EnvCascadeResolution;
+/** Reads a candidate from disk; `ENOENT` alone means "not there". */
+export declare function readEnvFileFromDisk(filePath: string): string | undefined;
+/**
+ * Parses one file's content. A file whose content holds a line the parser would
+ * silently discard is malformed: the user wrote something they expect to take
+ * effect, and it would not. The error names the line number, never its content
+ * — a `.env` line is as likely as not to be a secret.
+ */
+export declare function parseEnvFile(filePath: string, content: string): Record<string, string>;
+/**
+ * The 1-based number of the first line `util.parseEnv` would drop, or
+ * `undefined`. Mirrors the parser's line model: blank and `#` lines are
+ * skipped, an optional `export ` prefix is allowed, and a value opening with a
+ * quote runs to the next matching quote anywhere later in the content —
+ * spanning lines — or, when there is none, to the end of its own line.
+ */
+export declare function firstDiscardedLine(content: string): number | undefined;

package/dist/config/env.cascade.js

@@ -0,0 +1,126 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseEnv } from "node:util";
+/** The mode used when neither an explicit mode nor `NODE_ENV` supplies one. */
+export const DEFAULT_ENV_MODE = "development";
+/** A candidate exists but could not be read, or contains a discarded line. */
+export class EnvFileError extends Error {
+    filePath;
+    reason;
+    name = "EnvFileError";
+    constructor(filePath, reason, detail) {
+        super(`${filePath}: ${detail}`);
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+/** The four file candidates for a mode, highest precedence first. */
+export function envCascadeCandidates(mode) {
+    return [`.env.${mode}.local`, `.env.${mode}`, ".env.local", ".env"];
+}
+export function resolveEnvMode(processEnv, explicit) {
+    if (explicit !== undefined && explicit !== "")
+        return explicit;
+    const nodeEnv = processEnv.NODE_ENV;
+    return nodeEnv !== undefined && nodeEnv !== "" ? nodeEnv : DEFAULT_ENV_MODE;
+}
+export function resolveEnvCascade(input) {
+    const mode = resolveEnvMode(input.processEnv, input.mode);
+    const read = input.read ?? readEnvFileFromDisk;
+    const candidates = envCascadeCandidates(mode);
+    const env = {};
+    for (const [name, value] of Object.entries(input.processEnv)) {
+        if (value !== undefined)
+            env[name] = value;
+    }
+    const loaded = [];
+    // Highest precedence first: under first-write-wins, the first source to
+    // define a name owns it. Reversing this loop inverts the precedence.
+    for (const candidate of candidates) {
+        const filePath = path.join(input.directory, candidate);
+        const content = read(filePath);
+        if (content === undefined)
+            continue;
+        loaded.push(candidate);
+        for (const [name, value] of Object.entries(parseEnvFile(filePath, content))) {
+            if (!Object.hasOwn(env, name))
+                env[name] = value;
+        }
+    }
+    return { mode, env: Object.freeze(env), candidates, loaded };
+}
+/** Reads a candidate from disk; `ENOENT` alone means "not there". */
+export function readEnvFileFromDisk(filePath) {
+    try {
+        return readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return undefined;
+        const code = isErrnoException(error) ? error.code : undefined;
+        throw new EnvFileError(filePath, "unreadable", `exists but cannot be read (${code ?? "unknown error"})`);
+    }
+}
+/**
+ * Parses one file's content. A file whose content holds a line the parser would
+ * silently discard is malformed: the user wrote something they expect to take
+ * effect, and it would not. The error names the line number, never its content
+ * — a `.env` line is as likely as not to be a secret.
+ */
+export function parseEnvFile(filePath, content) {
+    const source = content.startsWith("") ? content.slice(1) : content;
+    const discarded = firstDiscardedLine(source);
+    if (discarded !== undefined) {
+        throw new EnvFileError(filePath, "malformed", `line ${discarded} is not a NAME=value assignment and would be ignored`);
+    }
+    return parseEnv(source);
+}
+const QUOTES = new Set(['"', "'", "`"]);
+/**
+ * The 1-based number of the first line `util.parseEnv` would drop, or
+ * `undefined`. Mirrors the parser's line model: blank and `#` lines are
+ * skipped, an optional `export ` prefix is allowed, and a value opening with a
+ * quote runs to the next matching quote anywhere later in the content —
+ * spanning lines — or, when there is none, to the end of its own line.
+ */
+export function firstDiscardedLine(content) {
+    let offset = 0;
+    while (offset < content.length) {
+        const lineEnd = endOfLine(content, offset);
+        const line = content.slice(offset, lineEnd);
+        const raw = line.trim();
+        if (raw !== "" && !raw.startsWith("#")) {
+            const assignment = raw.startsWith("export ")
+                ? raw.slice("export ".length)
+                : raw;
+            const equals = assignment.indexOf("=");
+            if (equals === -1 || assignment.slice(0, equals).trim() === "") {
+                return lineNumberAt(content, offset);
+            }
+            let valueStart = offset + line.indexOf("=") + 1;
+            while (content[valueStart] === " " || content[valueStart] === "\t") {
+                valueStart += 1;
+            }
+            const quote = content[valueStart];
+            if (quote !== undefined && QUOTES.has(quote)) {
+                const closing = content.indexOf(quote, valueStart + 1);
+                if (closing !== -1) {
+                    offset = endOfLine(content, closing) + 1;
+                    continue;
+                }
+            }
+        }
+        offset = lineEnd + 1;
+    }
+    return undefined;
+}
+function endOfLine(content, from) {
+    const newline = content.indexOf("\n", from);
+    return newline === -1 ? content.length : newline;
+}
+function lineNumberAt(content, offset) {
+    return content.slice(0, offset).split("\n").length;
+}
+function isErrnoException(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/contract/contract.acceptance.d.ts

@@ -0,0 +1,77 @@
+import { type ClientContract } from "@aventara/core";
+/**
+ * §15.3's validation steps over a fetched body, in the specification's order, as
+ * one decision (plan §7, group 2): protocol support (§19.1), then ClientContract
+ * structure, then the advertised hash recomputed and compared (§19.2).
+ *
+ * # The structure check is core's, never a second implementation
+ *
+ * What a ClientContract IS belongs to core, so the structure step is core's
+ * `validateClientContractStructure` and nothing here restates a member, a kind or
+ * a vocabulary. Before it, a body with a valid envelope and a malformed member —
+ * `resources: { Spell: 5 }` — reached core's canonicalizer, which reads members
+ * without validating them, and escaped as a plain `TypeError` and a stack.
+ *
+ * # Protocol support is judged first, from a read rather than a rule
+ *
+ * A body from a protocol this generator does not speak may have a different
+ * structure, and "unsupported" is then the true and useful answer. So the
+ * advertised version is READ — leniently, never judged — and judged against the
+ * supported set before any structure is. A body whose version cannot be read at
+ * all goes on to the structure step, which names what is wrong with it.
+ *
+ * # A value, not a throw site
+ *
+ * M3's rule — failure is a message and an exit code, never a stack — needs both to
+ * be typed members, so a rejection is the `ContractRejected` arm carrying its
+ * sentence and its exit code, and `ContractProtocolError` is built from it only
+ * where generation stops.
+ *
+ * # The hash is core's, never a second implementation
+ *
+ * The advertised `protocol.hash` is recomputed with `computeClientContractHash` —
+ * the function the compiler stamps it with (M6a) — and compared. A hash computed
+ * here would be a second source of the Contract's identity.
+ *
+ * # Bodies the hash cannot be recomputed over (S0)
+ *
+ * The ClientContract type admits values RFC 8785 cannot encode, and a valid JSON
+ * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses to
+ * a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can have
+ * stamped a hash over such a body — its own canonicalizer would have refused — so it
+ * is refused at THIS step, as `hash-mismatch` with its own sentence and core's path,
+ * never let escape as a stack. Both values are ones the ClientContract TYPE admits
+ * (`number`, `string`), so core's structure check accepts them by design; what
+ * fails is §19.2's recompute. ONLY that class is caught: anything else thrown while
+ * hashing is not a known property of the input, and keeps its stack as a defect.
+ */
+/** The protocol versions this generator speaks (§19.1: support is explicit). */
+export declare const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet<number>;
+/** Closed at three (plan §7): §19.1, §19.2, and §15.3's structure step. */
+export type ContractRejectionReason = "protocol-unsupported" | "hash-mismatch" | "structure-invalid";
+export type ContractAccepted = {
+    readonly accepted: true;
+    /**
+     * Trusted to the depth this step checks: core's structure check and the hash.
+     * It is the erased ClientContract (ADR 0009): no capability is interpreted here
+     * (plan §1).
+     */
+    readonly contract: ClientContract;
+};
+export type ContractRejected = {
+    readonly accepted: false;
+    readonly reason: ContractRejectionReason;
+    /** A sentence for the person running generate: what is wrong, and what to do. */
+    readonly message: string;
+    /** The process exit code generation stops with. Never 0. */
+    readonly exitCode: number;
+};
+export type ContractAcceptance = ContractAccepted | ContractRejected;
+export declare function acceptClientContract(body: unknown): Promise<ContractAcceptance>;
+/** The refusal that stops generation, carrying the rejection's reason and sentence. */
+export declare class ContractProtocolError extends Error {
+    readonly name = "ContractProtocolError";
+    readonly reason: ContractRejectionReason;
+    readonly exitCode: number;
+    constructor(rejection: ContractRejected, contractUrl: string);
+}

package/dist/contract/contract.acceptance.js

@@ -0,0 +1,124 @@
+import { AVENTARA_PROTOCOL_VERSION, CanonicalJsonError, computeClientContractHash, validateClientContractStructure, } from "@aventara/core";
+/**
+ * §15.3's validation steps over a fetched body, in the specification's order, as
+ * one decision (plan §7, group 2): protocol support (§19.1), then ClientContract
+ * structure, then the advertised hash recomputed and compared (§19.2).
+ *
+ * # The structure check is core's, never a second implementation
+ *
+ * What a ClientContract IS belongs to core, so the structure step is core's
+ * `validateClientContractStructure` and nothing here restates a member, a kind or
+ * a vocabulary. Before it, a body with a valid envelope and a malformed member —
+ * `resources: { Spell: 5 }` — reached core's canonicalizer, which reads members
+ * without validating them, and escaped as a plain `TypeError` and a stack.
+ *
+ * # Protocol support is judged first, from a read rather than a rule
+ *
+ * A body from a protocol this generator does not speak may have a different
+ * structure, and "unsupported" is then the true and useful answer. So the
+ * advertised version is READ — leniently, never judged — and judged against the
+ * supported set before any structure is. A body whose version cannot be read at
+ * all goes on to the structure step, which names what is wrong with it.
+ *
+ * # A value, not a throw site
+ *
+ * M3's rule — failure is a message and an exit code, never a stack — needs both to
+ * be typed members, so a rejection is the `ContractRejected` arm carrying its
+ * sentence and its exit code, and `ContractProtocolError` is built from it only
+ * where generation stops.
+ *
+ * # The hash is core's, never a second implementation
+ *
+ * The advertised `protocol.hash` is recomputed with `computeClientContractHash` —
+ * the function the compiler stamps it with (M6a) — and compared. A hash computed
+ * here would be a second source of the Contract's identity.
+ *
+ * # Bodies the hash cannot be recomputed over (S0)
+ *
+ * The ClientContract type admits values RFC 8785 cannot encode, and a valid JSON
+ * body produces two of them: `1e999` parses to `Infinity`, and `"\ud800"` parses to
+ * a lone surrogate. Core rejects both with `CanonicalJsonError`. No server can have
+ * stamped a hash over such a body — its own canonicalizer would have refused — so it
+ * is refused at THIS step, as `hash-mismatch` with its own sentence and core's path,
+ * never let escape as a stack. Both values are ones the ClientContract TYPE admits
+ * (`number`, `string`), so core's structure check accepts them by design; what
+ * fails is §19.2's recompute. ONLY that class is caught: anything else thrown while
+ * hashing is not a known property of the input, and keeps its stack as a defect.
+ */
+/** The protocol versions this generator speaks (§19.1: support is explicit). */
+export const SUPPORTED_PROTOCOL_VERSIONS = new Set([
+    AVENTARA_PROTOCOL_VERSION,
+]);
+/** A refused contract stops generation; the adapter CLI's precedent is 1 (M3). */
+const REFUSED_EXIT_CODE = 1;
+const CHECK_ENTRYPOINT = "Check that the entrypoint is the deployed Aventara entrypoint (origin plus mount path).";
+export async function acceptClientContract(body) {
+    const version = advertisedProtocolVersion(body);
+    if (version !== undefined && !SUPPORTED_PROTOCOL_VERSIONS.has(version)) {
+        return reject("protocol-unsupported", `the deployment speaks Aventara protocol version ${version}, and this generator ` +
+            `supports only ${describeSupported()}. Use a generator release that supports protocol ` +
+            `version ${version}. A client running against this deployment meets the same ` +
+            "fact as A2006 PROTOCOL_MISMATCH.");
+    }
+    const structure = validateClientContractStructure(body);
+    if (!structure.valid) {
+        return reject("structure-invalid", `it is not a ClientContract: ${structure.message}. ${CHECK_ENTRYPOINT}`);
+    }
+    const contract = structure.contract;
+    let recomputed;
+    try {
+        recomputed = await computeClientContractHash(contract);
+    }
+    catch (error) {
+        if (!(error instanceof CanonicalJsonError)) {
+            throw error;
+        }
+        return reject("hash-mismatch", `it holds a value canonical JSON cannot represent (${error.message}), so its ` +
+            "advertised hash cannot be verified. No Aventara server stamps a hash over such a " +
+            `body. ${CHECK_ENTRYPOINT}`);
+    }
+    if (recomputed !== contract.protocol.hash) {
+        return reject("hash-mismatch", `its advertised hash ${contract.protocol.hash} does not match its contents, which ` +
+            `hash to ${recomputed}. The contract changed after the server stamped it; check for ` +
+            "a proxy or cache rewriting the response, then generate again.");
+    }
+    return { accepted: true, contract };
+}
+/** The refusal that stops generation, carrying the rejection's reason and sentence. */
+export class ContractProtocolError extends Error {
+    name = "ContractProtocolError";
+    reason;
+    exitCode;
+    constructor(rejection, contractUrl) {
+        super(`The ClientContract from ${contractUrl} was refused: ${rejection.message}`);
+        this.reason = rejection.reason;
+        this.exitCode = rejection.exitCode;
+    }
+}
+/**
+ * `protocol.version` where the body states a number there, `undefined` otherwise.
+ * A read, not a rule: it judges nothing, and a body it cannot read a version from
+ * is left for the structure step to describe.
+ */
+function advertisedProtocolVersion(body) {
+    if (!isJsonObject(body) || !Object.hasOwn(body, "protocol")) {
+        return undefined;
+    }
+    const protocol = body.protocol;
+    if (!isJsonObject(protocol) || !Object.hasOwn(protocol, "version")) {
+        return undefined;
+    }
+    return typeof protocol.version === "number" ? protocol.version : undefined;
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function reject(reason, message) {
+    return { accepted: false, reason, message, exitCode: REFUSED_EXIT_CODE };
+}
+function describeSupported() {
+    const versions = [...SUPPORTED_PROTOCOL_VERSIONS];
+    return versions.length === 1
+        ? `version ${versions[0]}`
+        : `versions ${versions.join(", ")}`;
+}

package/dist/contract/contract.fetcher.d.ts

@@ -0,0 +1,64 @@
+import type { ClientEntrypoint } from "../config/client-config.interface.js";
+/**
+ * §12.5's discovery request: one `GET <entrypoint>/_contract`, with no headers —
+ * §12.4: *"The contract GET itself requires neither header because it is the
+ * discovery mechanism."* The entrypoint is the CLIENT config's URL (§15.2,
+ * resolved in S2), not the server's mount-path setting.
+ *
+ * # Transport, and only transport
+ *
+ * This file's success is "a JSON value arrived". It does not judge the value: a
+ * body that is a JSON array is still a successful fetch, and refusing it is
+ * `contract.acceptance.ts`'s job. Every way of failing to produce a JSON value is a
+ * `ContractTransportError`, a different class from `ContractProtocolError`,
+ * because the two have different remedies — reach the deployment, versus regenerate
+ * or upgrade against what it served — and a message that blurs them sends the
+ * developer to the wrong one.
+ *
+ * `fetch` is injected, so the transport is tested without a server; the default is
+ * the platform's.
+ */
+/** The part of a `Response` the fetcher reads. */
+export type ContractResponse = Pick<Response, "ok" | "status" | "text">;
+/** The `fetch` the fetcher calls. `globalThis.fetch` satisfies it. */
+export type ContractFetch = (url: URL, init: {
+    readonly method: "GET";
+    readonly headers?: Readonly<Record<string, string>>;
+}) => Promise<ContractResponse>;
+/**
+ * What a conditional GET answers when the served ClientContract is the one named
+ * (`304 Not Modified`, Phase 10 Q8): no body, nothing to judge.
+ */
+export declare const CONTRACT_NOT_MODIFIED: unique symbol;
+export type ContractTransportFailureReason = 
+/** No response at all: DNS, refused connection, TLS, abort. */
+"request-failed"
+/** A response that is not 2xx — nothing was served for the protocol to judge. */
+ | "http-status"
+/** A 2xx response whose body could not be read to the end. */
+ | "body-unreadable"
+/** A body that is not JSON — an HTML page, an empty body, a truncation. */
+ | "body-not-json";
+export declare class ContractTransportError extends Error {
+    readonly reason: ContractTransportFailureReason;
+    readonly name = "ContractTransportError";
+    constructor(reason: ContractTransportFailureReason, message: string, options?: ErrorOptions);
+}
+/**
+ * `<entrypoint>/_contract`: the canonical mount path and the route, concatenated.
+ * The path's canonical form is resolution's (F-822) — root is `""` — so the join
+ * repairs nothing and special-cases nothing. URL resolution would be wrong here:
+ * `new URL("_contract", "https://h/api")` replaces `api`.
+ */
+export declare function contractUrlOf(entrypoint: ClientEntrypoint): URL;
+/** The URL as it may be printed: credentials in the entrypoint never are. */
+export declare function displayUrl(url: URL): string;
+/**
+ * GETs the ClientContract and returns the parsed body, unjudged — or, when
+ * `ifNoneMatch` (a quoted contract hash, the deployment's entity tag) is sent and
+ * the deployment answers `304`, {@link CONTRACT_NOT_MODIFIED} (Phase 12-rest Q6).
+ * A `304` to a request that sent none is no answer, like any other non-2xx.
+ *
+ * @throws ContractTransportError when no JSON value arrives.
+ */
+export declare function fetchClientContractBody(entrypoint: ClientEntrypoint, fetch?: ContractFetch, ifNoneMatch?: string): Promise<unknown>;