@aventara/core 0.1.0-pilot.0 → 0.1.0-pilot.2

package/dist/protocol/absent-route.responder.js

@@ -9,14 +9,8 @@ import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
 import { transactionsUnavailableFailure } from "../transactions/transaction-plan-validator.js";
 import { CONTRACT_ROUTE, GET_ONLY, isProtocolPath, operationRouteSegments, POST_ONLY, readRequest, TRANSACTIONS_ROUTE, } from "./http-request.reader.js";
 import { encodeOperationResponse, } from "./http-response.encoder.js";
-import { transportFailure } from "./protocol-failure.js";
-/**
- * An operation route `/_resources/<resource>/<family>/<variant>` under one
- * client protocol identity: version → hash → Resource → operation. A Resource
- * key is matched exactly (§12.6) and only as the ClientContract's own key; a
- * family/variant pair only when it is a standard operation the Resource
- * advertises, read through `isOperationVariantAvailable` alone (§4).
- */
+import { identityHeadersMissing, transportFailure, } from "./protocol-failure.js";
+import { missingIdentityHeaders } from "./protocol-headers.js";
 export function resolveOperationRoute(contracts, protocol, route) {
     const identityFailure = protocolIdentityFailure(contracts, protocol);
     if (identityFailure !== undefined) {
@@ -40,33 +34,20 @@ export function resolveOperationRoute(contracts, protocol, route) {
     }
     return { ok: true, operation };
 }
-/**
- * The `/_transactions` route under one client protocol identity: version →
- * hash → the ClientContract's transaction capability. The route exists only
- * when that capability is `"interactive"` (A4) — tested against the value
- * itself, as `protocol.surface()` tests it — and is otherwise absent with
- * core's own refusal of a plan (`A2002`, `V1006` at `["operations"]`, M17).
- * `undefined` when the route is there.
- */
 export function transactionsRouteFailure(contracts, protocol) {
     return (protocolIdentityFailure(contracts, protocol) ??
         (contracts.client.transactions === "interactive"
             ? undefined
             : transactionsUnavailableFailure()));
 }
-/**
- * An operation route's checks before its body (decoder steps 2–4): the path
- * (`A2000` unless `/_resources/<r>/<f>/<v>`, each segment decodable and none
- * empty), the identity headers' presence (`A2000`), then
- * {@link resolveOperationRoute} — version, hash, Resource, operation — and the
- * method (`A2012`, `Allow: POST`). One sequence for both route styles (Q12):
- * `decodeOperation` reads the body only after it passes, `answerAbsent` never.
- */
 export function checkOperationRoute(contracts, read) {
     const segments = operationRouteSegments(read.request.path);
-    if (segments === undefined || read.protocol === undefined) {
+    if (segments === undefined) {
         return refusedWith(transportFailure("A2000", read.requestId));
     }
+    if (read.protocol === undefined) {
+        return refusedWith(identityFailureOf(read));
+    }
     const route = resolveOperationRoute(contracts, read.protocol, segments);
     if (!route.ok) {
         return refusedWith(encodeOperationResponse(route.failure, read.requestId));
@@ -80,16 +61,13 @@ export function checkOperationRoute(contracts, read) {
         }
         : refusedWith(transportFailure("A2012", read.requestId, POST_ONLY));
 }
-/**
- * `/_transactions`' checks before its body: the path (`A2000` unless exactly
- * `/_transactions`), the identity headers' presence (`A2000`), then
- * {@link transactionsRouteFailure} — version, hash, `"interactive"` — and the
- * method (`A2012`, `Allow: POST`).
- */
 export function checkTransactionsRoute(contracts, read) {
-    if (read.request.path !== TRANSACTIONS_ROUTE || read.protocol === undefined) {
+    if (read.request.path !== TRANSACTIONS_ROUTE) {
         return refusedWith(transportFailure("A2000", read.requestId));
     }
+    if (read.protocol === undefined) {
+        return refusedWith(identityFailureOf(read));
+    }
     const absent = transactionsRouteFailure(contracts, read.protocol);
     if (absent !== undefined) {
         return refusedWith(encodeOperationResponse(absent, read.requestId));
@@ -98,33 +76,12 @@ export function checkTransactionsRoute(contracts, read) {
         ? { ok: true, protocol: read.protocol }
         : refusedWith(transportFailure("A2012", read.requestId, POST_ONLY));
 }
+function identityFailureOf(read) {
+    return identityHeadersMissing(missingIdentityHeaders(read.headers), read.requestId);
+}
 function refusedWith(response) {
     return { ok: false, response };
 }
-/**
- * `protocol.answerAbsent(request)` (§5.9, Q2's O3; S10) — the fallback a host
- * that mounts one route per `protocol.surface()` entry mounts for every path
- * it did not. Never a catch-all into framework handling: it reads no body,
- * runs no pipeline, calls no Adapter, and takes only the compiled Contracts.
- * In order:
- *
- * 1. a value that is not an `AvProtocolRequest` → `400 A2000`, minted id;
- * 2. a path outside the protocol's underscore namespace (§12.1) →
- *    `undefined`: the host answers it itself — `/favicon.ico` is not the
- *    framework's (the architect, 2026-10-05);
- * 3. `/_contract`: any method but `GET` → `405 A2012` with `Allow: GET`; no
- *    identity header is read (§12.4);
- * 4. `/_transactions`, or else an operation route: exactly what the catch-all
- *    host's decoder answers before its body — path syntax and identity
- *    presence (`A2000`), version (`A2006`), hash (`A2005`), Resource
- *    (`A2001`), operation or the `"none"` capability (`A2002`), method
- *    (`A2012`, `Allow: POST`) — each core's own envelope;
- * 5. a route that EXISTS, reached with its own method — the host mounted
- *    only part of the surface — → `500 A3000`: a host wiring bug made
- *    visible, never a silent 404 (the architect, 2026-10-05).
- *
- * Every framework answer echoes `Aventara-Request-Id` (Q13).
- */
 export function answerAbsentRequest(contracts, received) {
     const read = readRequest(received);
     if (!read.ok) {
@@ -144,7 +101,6 @@ export function answerAbsentRequest(contracts, received) {
         : checkOperationRoute(contracts, read);
     return route.ok ? unmounted(read.requestId) : route.response;
 }
-/** A mounted route's request at the fallback: the framework failed to route it. */
 function unmounted(requestId) {
     return encodeOperationResponse(operationFailure("A3000", { message: INTERNAL_FAILURE_MESSAGE }), requestId);
 }

package/dist/protocol/av-protocol.d.ts

@@ -1,12 +1,12 @@
 /**
  * The members of `AvProtocol`, as this module's own named exports. The entry
- * (`./index.ts`) publishes this module whole as the namespace `AvProtocol`
- * (P5): the language freezes a module namespace, and a bundler drops the
- * members a consumer does not read.
+ * (`./index.ts`) publishes this module whole as the namespace `AvProtocol`: the
+ * language freezes a module namespace, and a bundler drops the members a consumer
+ * does not read.
  *
- * Re-exports only — no logic lives here. Every member is pinned, by name and
- * by type, in `./index.test-d.ts`, whose exact `keyof` set fails when a member
- * is added or removed without a row.
+ * Re-exports only — no logic lives here. Every member is pinned, by name and by
+ * type, in `./index.test-d.ts`, whose exact `keyof` set fails when a member is
+ * added or removed without a row.
  */
 export { normalizeEntrypoint } from "../config/entrypoint.normalizer.js";
 export { scalarFormats } from "../contracts/wire-scalar-format.js";

package/dist/protocol/av-protocol.js

@@ -1,13 +1,3 @@
-/**
- * The members of `AvProtocol`, as this module's own named exports. The entry
- * (`./index.ts`) publishes this module whole as the namespace `AvProtocol`
- * (P5): the language freezes a module namespace, and a bundler drops the
- * members a consumer does not read.
- *
- * Re-exports only — no logic lives here. Every member is pinned, by name and
- * by type, in `./index.test-d.ts`, whose exact `keyof` set fails when a member
- * is added or removed without a row.
- */
 export { normalizeEntrypoint } from "../config/entrypoint.normalizer.js";
 export { scalarFormats } from "../contracts/wire-scalar-format.js";
 export { httpStatus } from "./http-status.table.js";

package/dist/protocol/contract-document.responder.d.ts

@@ -2,10 +2,9 @@ import type { ClientContract } from "../contracts/contract.js";
 import type { AvProtocolRequest } from "./http-request.decoder.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
 /**
- * The served ClientContract, written once per binding: its JCS-canonical
- * bytes (RFC 8785, Q8) and its entity tag, the quoted contract hash (§12.5).
- * The bytes include `protocol.hash`, although the hash's own input excludes
- * it (M22).
+ * The served ClientContract, written once per binding: its JCS-canonical bytes and
+ * its entity tag, the quoted contract hash. The bytes include `protocol.hash`,
+ * although the hash's own input excludes it.
  */
 export type ContractDocument = {
     readonly body: string;
@@ -14,22 +13,20 @@ export type ContractDocument = {
 /** The bound ClientContract as the document `_contract` serves. */
 export declare function contractDocumentOf(client: ClientContract): ContractDocument;
 /**
- * `protocol.encodeContract(request)` (§5.9, Q8; S11): the `GET
- * <entrypoint>/_contract` responder. In order:
+ * `protocol.encodeContract(request)`: the `GET <entrypoint>/_contract` responder.
+ * In order:
  *
- * 1. a value that is not an `AvProtocolRequest` → `400 A2000` under a minted
- *    id (as the decoders answer it);
- * 2. the request id: `Aventara-Request-Id` adopted per Q13, else minted;
- * 3. a path other than `/_contract` → `400 A2000` (path syntax this route
- *    cannot read, as a decoder answers one);
+ * 1. a value that is not an `AvProtocolRequest` → `400 A2000` under a minted id
+ *    (as the decoders answer it);
+ * 3. a path other than `/_contract` → `400 A2000` (path syntax this route cannot
+ *    read, as a decoder answers one);
  * 4. a method other than `GET` → `405 A2012` with `Allow: GET`;
- * 5. `If-None-Match` matching the document's entity tag — RFC 9110 §13.1.2's
- *    weak comparison, over a comma-separated list, or `*` — → `304 Not
- *    Modified`, no body, still carrying `ETag` and `Cache-Control` (§15.4.5);
- *    otherwise `200` with the canonical bytes, `ETag`, `Cache-Control:
- *    no-cache` and `Content-Type: application/json`.
+ * 5. `If-None-Match` matching the document's entity tag — RFC 9110 §13.1.2's weak
+ *    comparison, over a comma-separated list, or `*` — → `304 Not Modified`, no
+ *    body, still carrying `ETag` and `Cache-Control`; otherwise `200` with the
+ *    canonical bytes, `ETag`, `Cache-Control: no-cache` and `Content-Type:
+ *    application/json`.
  *
- * No identity header is required or read (§12.4: the contract GET is the
- * discovery mechanism), and the body is never read.
+ * No identity header is required or read, and the body is never read.
  */
 export declare function encodeContractRequest(document: ContractDocument, received: AvProtocolRequest): AvProtocolResponse;

package/dist/protocol/contract-document.responder.js

@@ -2,32 +2,12 @@ import { canonicalizeContract } from "../contracts/contract-canonicalizer.js";
 import { CONTRACT_ROUTE, GET_ONLY, readRequest, } from "./http-request.reader.js";
 import { transportFailure } from "./protocol-failure.js";
 import { headers, headerValue } from "./protocol-headers.js";
-/** The bound ClientContract as the document `_contract` serves. */
 export function contractDocumentOf(client) {
     return Object.freeze({
         body: canonicalizeContract(client),
         etag: `"${client.protocol.hash}"`,
     });
 }
-/**
- * `protocol.encodeContract(request)` (§5.9, Q8; S11): the `GET
- * <entrypoint>/_contract` responder. In order:
- *
- * 1. a value that is not an `AvProtocolRequest` → `400 A2000` under a minted
- *    id (as the decoders answer it);
- * 2. the request id: `Aventara-Request-Id` adopted per Q13, else minted;
- * 3. a path other than `/_contract` → `400 A2000` (path syntax this route
- *    cannot read, as a decoder answers one);
- * 4. a method other than `GET` → `405 A2012` with `Allow: GET`;
- * 5. `If-None-Match` matching the document's entity tag — RFC 9110 §13.1.2's
- *    weak comparison, over a comma-separated list, or `*` — → `304 Not
- *    Modified`, no body, still carrying `ETag` and `Cache-Control` (§15.4.5);
- *    otherwise `200` with the canonical bytes, `ETag`, `Cache-Control:
- *    no-cache` and `Content-Type: application/json`.
- *
- * No identity header is required or read (§12.4: the contract GET is the
- * discovery mechanism), and the body is never read.
- */
 export function encodeContractRequest(document, received) {
     const read = readRequest(received);
     if (!read.ok) {
@@ -53,20 +33,7 @@ export function encodeContractRequest(document, received) {
             body: document.body,
         };
 }
-/**
- * One member of an `If-None-Match` list (RFC 9110 §5.6.1, §8.8.3): optional
- * whitespace, an optional entity tag — `W/` optional, then an opaque tag of
- * `etagc` between quotes — optional whitespace, then a comma or the end. An
- * empty member is allowed, as the list rule allows it.
- */
 const IF_NONE_MATCH_MEMBER = /[ \t]*(?:(?:W\/)?("[\x21\x23-\x7e\x80-\xff]*"))?[ \t]*(,|$)/y;
-/**
- * Whether `If-None-Match` names the current representation: `*`, or a list
- * holding an entity tag whose opaque tag equals `etag`'s — the WEAK
- * comparison (RFC 9110 §8.8.3.2), which `If-None-Match` uses (§13.1.2), so a
- * `W/` prefix does not matter. A value that is not a well-formed list matches
- * nothing; an absent header matches nothing.
- */
 function noneMatchHolds(value, etag) {
     if (value === undefined) {
         return false;

package/dist/protocol/http-request.decoder.d.ts

@@ -3,20 +3,19 @@ import type { ClientOperationRequest } from "../runtime/operation-request.js";
 import type { ClientTransactionRequest } from "../transactions/transaction-request.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
 /**
- * One HTTP request as a host hands it to the protocol: what the decoders
- * (`protocol.decodeOperation` / `decodeTransaction`, S7) read, and what each
- * row of the fixture corpus carries as its `request`.
+ * One HTTP request as a host hands it to the protocol: what the decoders read, and
+ * what each row of the fixture corpus carries as its `request`.
  *
- * Host-independent by construction: no host's request object, only the four
- * facts every host can supply.
+ * Host-independent by construction: no host's request object, only the four facts
+ * every host can supply.
  */
 export type AvProtocolRequest = {
     /** The HTTP method as received. Anything but `POST` on a framework route is `A2012`. */
     readonly method: string;
     /**
-     * The request path RELATIVE to the configured entrypoint, as received (not
-     * yet URL-decoded): `/_resources/users/find/many`, `/_transactions`,
-     * `/_contract` (§12.1) — the space `protocol.surface()`'s paths live in.
+     * The request path RELATIVE to the configured entrypoint, as received (not yet
+     * URL-decoded): `/_resources/users/find/many`, `/_transactions`, `/_contract` —
+     * the space `protocol.surface()`'s paths live in.
      */
     readonly path: string;
     /**
@@ -26,16 +25,15 @@ export type AvProtocolRequest = {
      */
     readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
     /**
-     * The body, in one of two explicitly named arms (Q11) — the decoder never
-     * guesses which one it was given:
+     * The body, in one of two explicitly named arms — the decoder never guesses which
+     * one it was given:
      *
-     * - `raw`: the decoded body (after content decoding, §20.1) as received,
-     *   bytes or text. The decoder enforces all of it: the size limit
-     *   (`A2010`), the content type (`A2011`), JSON syntax and the body's
-     *   shape (`A2000`). An absent body is zero bytes (`""`).
-     * - `parsed`: a value the host's own JSON parser already produced. Size,
-     *   content type and JSON syntax were the host's to enforce before the
-     *   decoder ran; the decoder still refuses a non-object shape (`A2000`).
+     * - `raw`: the decoded body as received, bytes or text. The decoder enforces all
+     *   of it: the size limit (`A2010`), the content type (`A2011`), JSON syntax and
+     *   the body's shape (`A2000`). An absent body is zero bytes (`""`).
+     * - `parsed`: a value the host's own JSON parser already produced. Size, content
+     *   type and JSON syntax were the host's to enforce before the decoder ran; the
+     *   decoder still refuses a non-object shape (`A2000`).
      */
     readonly body: {
         readonly kind: "raw";
@@ -46,10 +44,10 @@ export type AvProtocolRequest = {
     };
 };
 /**
- * What a decoder answers (§5.9, R2): the request core executes, or the
- * framework response that answers the HTTP request instead — and, either way,
- * the request id it runs or is answered under, which the host passes to the
- * encoder: `protocol.encodeOperation(response, decoded.requestId)`.
+ * What a decoder answers: the request core executes, or the framework response
+ * that answers the HTTP request instead — and, either way, the request id it runs
+ * or is answered under, which the host passes to the encoder:
+ * `protocol.encodeOperation(response, decoded.requestId)`.
  */
 type Decoded<Request> = {
     readonly ok: true;
@@ -69,55 +67,51 @@ export type DecodedOperationRequest = Extract<DecodedOperation, {
 /** What `protocol.decodeTransaction` answers. */
 export type DecodedTransaction = Decoded<ClientTransactionRequest>;
 /**
- * `protocol.decodeOperation(request)` — one operation route's HTTP request as
- * the client-origin request `framework.execute` takes, or its answer.
+ * `protocol.decodeOperation(request)` — one operation route's HTTP request as the
+ * client-origin request `framework.execute` takes, or its answer.
  *
- * Total over ANY value (the director, 2026-10-05): a value that is not an
- * `AvProtocolRequest` at all — not an object, a missing or mistyped member, a
- * member behind a getter or trap that throws — is malformed, `A2000` under a
- * minted id, before anything else is read; nothing it carries is believed.
- * Otherwise, in order, each step answering before the next runs:
+ * Total over ANY value: a value that is not an `AvProtocolRequest` at all — not an
+ * object, a missing or mistyped member, a member behind a getter or trap that
+ * throws — is malformed, `A2000` under a minted id, before anything else is read;
+ * nothing it carries is believed. Otherwise, in order, each step answering before
+ * the next runs:
  *
- * 1. the request id: `Aventara-Request-Id` adopted when it is 1–128 visible
- *    ASCII characters, otherwise minted by core's one helper — never a
- *    refusal (Q13, Q10);
+ * 1. the request id: `Aventara-Request-Id` adopted when it is 1–128 visible ASCII
+ *    characters, otherwise minted by core's one helper — never a refusal;
  * 2. the path: `/_resources/<resource>/<family>/<variant>`, each segment
  *    URL-decoded once and none empty, or `A2000`;
- * 3. identity and absence, with no body read: a request missing either
- *    identity header is malformed (`A2000`; the architect, 2026-10-05); then
- *    the protocol version (`A2006`), the ClientContract hash (`A2005`), the
- *    Resource (`A2001`) and the operation (`A2002`), each core's own
- *    envelope — so an unadvertised triple never reaches `execute`, in either
- *    route style (Q12, Q2's O3);
- * 4. the method: anything but `POST` is `A2012`, carrying `Allow: POST`
- *    (RFC 9110 §15.5.6);
- * 5. the body (Q11). On the RAW arm the decoder enforces all of it: the
- *    content type must be `application/json` (`A2011`; parameters are not
- *    read), the decoded byte count must not exceed the ClientContract's
- *    `limits.maxRequestBytes` (`A2010`, §20.1), and the bytes must be UTF-8
- *    JSON (`A2000`). On the PARSED arm the host's own parser already read the
- *    bytes, so size, content type and JSON syntax were the HOST's to enforce —
- *    answering its parser's failures with `protocol.failure` — and the decoder
- *    checks none of them. Both arms then refuse a body that is not a JSON
- *    object — an array, a scalar, `null`, or none (`A2000`). One gap is the
- *    host's by construction: a parser that turns an absent body into `{}`
- *    makes absence indistinguishable from `{}`, which is valid.
+ * 3. identity and absence, with no body read: a request missing either identity
+ *    header is malformed; then the protocol version (`A2006`), the ClientContract
+ *    hash (`A2005`), the Resource (`A2001`) and the operation (`A2002`), each
+ *    core's own envelope — so an unadvertised triple never reaches `execute`, in
+ *    either route style;
+ * 4. the method: anything but `POST` is `A2012`, carrying `Allow: POST` (RFC 9110
+ *    §15.5.6);
+ * 5. the body. On the RAW arm the decoder enforces all of it: the content type
+ *    must be `application/json` (`A2011`; parameters are not read), the decoded
+ *    byte count must not exceed the ClientContract's `limits.maxRequestBytes`, and
+ *    the bytes must be UTF-8 JSON (`A2000`). On the PARSED arm the host's own
+ *    parser already read the bytes, so size, content type and JSON syntax were the
+ *    HOST's to enforce — answering its parser's failures with `protocol.failure` —
+ *    and the decoder checks none of them. Both arms then refuse a body that is not
+ *    a JSON object — an array, a scalar, `null`, or none (`A2000`). One gap is the
+ *    host's by construction: a parser that turns an absent body into `{}` makes
+ *    absence indistinguishable from `{}`, which is valid.
  *
- * The request is client origin, always (P4): nothing the caller sends spells
- * application origin. `transport` carries `POST` and the request's headers
- * (Q7). The body is the operation's arguments verbatim (§12.3): the decoder
- * never reads into it, so routing metadata in it is core's to refuse (N16),
- * and a parsed body reaches core as the same object.
+ * The request is client origin, always: nothing the caller sends spells
+ * application origin. `transport` carries `POST` and the request's headers. The
+ * body is the operation's arguments verbatim: the decoder never reads into it, so
+ * routing metadata in it is core's to refuse, and a parsed body reaches core as
+ * the same object.
  */
 export declare function decodeOperationRequest(contracts: FrameworkContracts, received: AvProtocolRequest): DecodedOperation;
 /**
  * `protocol.decodeTransaction(request)` — the `/_transactions` request as the
- * client-origin plan request `framework.executeTransaction` takes, or its
- * answer. The same steps as {@link decodeOperationRequest}, with the path
- * exactly `/_transactions` and its absence being a ClientContract without
- * interactive transactions (`A2002` at `["operations"]`, M17). Every step of
- * the plan then runs under ClientContract rules (R1): the plan is client
- * origin and cannot say otherwise. The body is the plan verbatim.
+ * client-origin plan request `framework.executeTransaction` takes, or its answer.
+ * The same steps as {@link decodeOperationRequest}, with the path exactly
+ * `/_transactions` and its absence being a ClientContract without interactive
+ * transactions. Every step of the plan then runs under ClientContract rules: the
+ * plan is client origin and cannot say otherwise. The body is the plan verbatim.
  */
 export declare function decodeTransactionRequest(contracts: FrameworkContracts, received: AvProtocolRequest): DecodedTransaction;
 export {};

package/dist/protocol/http-request.decoder.js

@@ -2,47 +2,6 @@ import { checkOperationRoute, checkTransactionsRoute, } from "./absent-route.res
 import { readRequest } from "./http-request.reader.js";
 import { transportFailure, } from "./protocol-failure.js";
 import { headerValue } from "./protocol-headers.js";
-/**
- * `protocol.decodeOperation(request)` — one operation route's HTTP request as
- * the client-origin request `framework.execute` takes, or its answer.
- *
- * Total over ANY value (the director, 2026-10-05): a value that is not an
- * `AvProtocolRequest` at all — not an object, a missing or mistyped member, a
- * member behind a getter or trap that throws — is malformed, `A2000` under a
- * minted id, before anything else is read; nothing it carries is believed.
- * Otherwise, in order, each step answering before the next runs:
- *
- * 1. the request id: `Aventara-Request-Id` adopted when it is 1–128 visible
- *    ASCII characters, otherwise minted by core's one helper — never a
- *    refusal (Q13, Q10);
- * 2. the path: `/_resources/<resource>/<family>/<variant>`, each segment
- *    URL-decoded once and none empty, or `A2000`;
- * 3. identity and absence, with no body read: a request missing either
- *    identity header is malformed (`A2000`; the architect, 2026-10-05); then
- *    the protocol version (`A2006`), the ClientContract hash (`A2005`), the
- *    Resource (`A2001`) and the operation (`A2002`), each core's own
- *    envelope — so an unadvertised triple never reaches `execute`, in either
- *    route style (Q12, Q2's O3);
- * 4. the method: anything but `POST` is `A2012`, carrying `Allow: POST`
- *    (RFC 9110 §15.5.6);
- * 5. the body (Q11). On the RAW arm the decoder enforces all of it: the
- *    content type must be `application/json` (`A2011`; parameters are not
- *    read), the decoded byte count must not exceed the ClientContract's
- *    `limits.maxRequestBytes` (`A2010`, §20.1), and the bytes must be UTF-8
- *    JSON (`A2000`). On the PARSED arm the host's own parser already read the
- *    bytes, so size, content type and JSON syntax were the HOST's to enforce —
- *    answering its parser's failures with `protocol.failure` — and the decoder
- *    checks none of them. Both arms then refuse a body that is not a JSON
- *    object — an array, a scalar, `null`, or none (`A2000`). One gap is the
- *    host's by construction: a parser that turns an absent body into `{}`
- *    makes absence indistinguishable from `{}`, which is valid.
- *
- * The request is client origin, always (P4): nothing the caller sends spells
- * application origin. `transport` carries `POST` and the request's headers
- * (Q7). The body is the operation's arguments verbatim (§12.3): the decoder
- * never reads into it, so routing metadata in it is core's to refuse (N16),
- * and a parsed body reaches core as the same object.
- */
 export function decodeOperationRequest(contracts, received) {
     const read = readRequest(received);
     if (!read.ok) {
@@ -69,15 +28,6 @@ export function decodeOperationRequest(contracts, received) {
         }
         : refused(body.response, read.requestId);
 }
-/**
- * `protocol.decodeTransaction(request)` — the `/_transactions` request as the
- * client-origin plan request `framework.executeTransaction` takes, or its
- * answer. The same steps as {@link decodeOperationRequest}, with the path
- * exactly `/_transactions` and its absence being a ClientContract without
- * interactive transactions (`A2002` at `["operations"]`, M17). Every step of
- * the plan then runs under ClientContract rules (R1): the plan is client
- * origin and cannot say otherwise. The body is the plan verbatim.
- */
 export function decodeTransactionRequest(contracts, received) {
     const read = readRequest(received);
     if (!read.ok) {
@@ -105,21 +55,15 @@ export function decodeTransactionRequest(contracts, received) {
 function refused(response, requestId) {
     return { ok: false, response, requestId };
 }
-/** Q7: every client request carries `POST` and its headers, one spelling. */
 function transportOf(read) {
     return { method: "POST", headers: read.headers };
 }
-/**
- * Step 5, after the route checks passed: the body as a JSON object, or the
- * answer refusing it. Only the raw arm is measured, typed and parsed (Q11).
- */
 function readBody(read, contracts) {
     const code = bodyValue(read.request.body, headerValue(read.headers, "content-type"), contracts.client.limits.maxRequestBytes);
     return typeof code === "string"
         ? { ok: false, response: transportFailure(code, read.requestId) }
         : { ok: true, value: code.value };
 }
-/** The body's JSON object, or the transport code that refuses it. */
 function bodyValue(body, contentType, maxRequestBytes) {
     if (body.kind === "parsed") {
         return isJsonObject(body.value) ? { value: body.value } : "A2000";
@@ -143,18 +87,12 @@ function bodyValue(body, contentType, maxRequestBytes) {
     }
     return isJsonObject(value) ? { value } : "A2000";
 }
-/** `application/json`, in any case; parameters (`; charset=…`) are not read. */
 function isJsonMediaType(contentType) {
     return (contentType
         ?.split(";")[0]
         ?.replace(/^[ \t]+|[ \t]+$/g, "")
         .toLowerCase() === "application/json");
 }
-/**
- * An object that is not a list (§12.6: a JSON array, scalar, `null` or absent
- * body is invalid). Read without touching the value's own members, so a
- * parsed body is never traversed; a revoked proxy is no object.
- */
 function isJsonObject(value) {
     try {
         return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/protocol/http-request.reader.d.ts

@@ -2,27 +2,27 @@ import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
 import type { OperationRouteSegments } from "./absent-route.responder.js";
 import type { AvProtocolRequest } from "./http-request.decoder.js";
 import type { AvProtocolResponse } from "./http-response.encoder.js";
-/** `POST <entrypoint>/_transactions` (§12.1). */
+/** `POST <entrypoint>/_transactions`. */
 export declare const TRANSACTIONS_ROUTE = "/_transactions";
-/** `GET <entrypoint>/_contract` (§12.1, §12.5). */
+/** `GET <entrypoint>/_contract`. */
 export declare const CONTRACT_ROUTE = "/_contract";
-/** The methods an operation or `/_transactions` route accepts: `POST`, only (§12.2). */
+/** The methods an operation or `/_transactions` route accepts: `POST`, only. */
 export declare const POST_ONLY: readonly string[];
-/** The methods the contract route accepts: `GET`, only (§12.2). */
+/** The methods the contract route accepts: `GET`, only. */
 export declare const GET_ONLY: readonly string[];
 /**
  * Whether a path lies in the protocol's namespace: underscore-prefixed paths
- * beneath the entrypoint are reserved for framework facilities; every other
- * path is the host's (§12.1).
+ * beneath the entrypoint are reserved for framework facilities; every other path
+ * is the host's.
  */
 export declare function isProtocolPath(path: string): boolean;
 /** A request the protocol could read, with what every route reads off it first. */
 export type ReadRequest = {
     readonly ok: true;
     readonly request: AvProtocolRequest;
-    /** Names lower-cased, repeated values joined (Q7). */
+    /** Names lower-cased, repeated values joined. */
     readonly headers: Readonly<Record<string, string>>;
-    /** Adopted from `Aventara-Request-Id` (Q13), else minted (Q10). */
+    /** Adopted from `Aventara-Request-Id`, else minted. */
     readonly requestId: string;
     /** `undefined` when either identity header is absent (`A2000`). */
     readonly protocol: ClientProtocolIdentity | undefined;
@@ -34,13 +34,12 @@ export type UnreadableRequest = {
     readonly requestId: string;
 };
 /**
- * The host's value read as a request, or — when it is not an
- * `AvProtocolRequest` at all — the `400 A2000` answering it, under a minted
- * id (the director, 2026-10-05).
+ * The host's value read as a request, or — when it is not an `AvProtocolRequest`
+ * at all — the `400 A2000` answering it, under a minted id.
  */
 export declare function readRequest(received: unknown): ReadRequest | UnreadableRequest;
 /**
- * The three segments of an operation route, each URL-decoded and none empty
- * (§12.6 refuses an empty-resource route); `undefined` when it is not one.
+ * The three segments of an operation route, each URL-decoded and none empty;
+ * `undefined` when it is not one.
  */
 export declare function operationRouteSegments(path: string): OperationRouteSegments | undefined;