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

package/README.md

@@ -11,9 +11,9 @@ Core is ORM- and transport-agnostic: it imports neither Prisma nor NestJS. An ap
 ## Install
 
 ```bash
-npx @aventara/cli new my-api     # a new NestJS project with Prisma and Aventara
-npx @aventara/cli init           # or: add Aventara to an existing NestJS 12 project
-npm install @aventara/core       # the package on its own
+npx @aventara/cli@pilot new my-api     # a new NestJS project with Prisma and Aventara
+npx @aventara/cli@pilot init           # or: add Aventara to an existing NestJS 12 project
+npm install @aventara/core@pilot       # the package on its own
 ```
 
 Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.

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

@@ -9,7 +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";
+import { identityHeadersMissing, transportFailure, } from "./protocol-failure.js";
+import { missingIdentityHeaders } from "./protocol-headers.js";
 /**
  * An operation route `/_resources/<resource>/<family>/<variant>` under one
  * client protocol identity: version → hash → Resource → operation. A Resource
@@ -64,9 +65,12 @@ export function transactionsRouteFailure(contracts, protocol) {
  */
 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));
@@ -87,9 +91,12 @@ export function checkOperationRoute(contracts, read) {
  * 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,6 +105,10 @@ export function checkTransactionsRoute(contracts, read) {
         ? { ok: true, protocol: read.protocol }
         : refusedWith(transportFailure("A2012", read.requestId, POST_ONLY));
 }
+/** The `A2000` for a request whose identity headers are not all there, naming the missing ones (pilot.1). */
+function identityFailureOf(read) {
+    return identityHeadersMissing(missingIdentityHeaders(read.headers), read.requestId);
+}
 function refusedWith(response) {
     return { ok: false, response };
 }

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

@@ -1,10 +1,18 @@
 import { type AvProtocolResponse } from "./http-response.encoder.js";
+import type { IdentityHeaderName } from "./protocol-headers.js";
 /**
  * The four transport codes (§13.2): failures of the HTTP request itself, which
  * the protocol answers before any operation exists, so no execution path
  * produces them (N4). Module type — not an entry export.
  */
 export type TransportFailureCode = "A2000" | "A2010" | "A2011" | "A2012";
+/**
+ * pilot.1 — the `400 A2000` answering a request that did not send an identity
+ * header (§12.4; the architect, 2026-10-05): its message names the missing
+ * header or headers, and echoes nothing the request sent (§13.5) — so a
+ * developer calling the API by hand learns what to add.
+ */
+export declare function identityHeadersMissing(missing: readonly IdentityHeaderName[], requestId: string): AvProtocolResponse;
 /**
  * `protocol.failure(code, requestId?)` / `protocol.failure("A2012", requestId,
  * allow)` (§5.9; a bound member, ruled 2026-10-05): a transport code as the

package/dist/protocol/protocol-failure.js

@@ -12,6 +12,18 @@ const TRANSPORT_FAILURE_MESSAGES = Object.freeze({
     A2011: "The request content type is not supported; send application/json.",
     A2012: "The HTTP method is not allowed on this framework route.",
 });
+/**
+ * pilot.1 — the `400 A2000` answering a request that did not send an identity
+ * header (§12.4; the architect, 2026-10-05): its message names the missing
+ * header or headers, and echoes nothing the request sent (§13.5) — so a
+ * developer calling the API by hand learns what to add.
+ */
+export function identityHeadersMissing(missing, requestId) {
+    const named = missing.length === 1
+        ? `The ${missing[0]} header is`
+        : `The ${missing.join(" and ")} headers are`;
+    return encodeOperationResponse(operationFailure("A2000", { message: `${named} missing.` }), requestIdOf({ requestId }));
+}
 /** An HTTP method as RFC 9110 §9.1 spells one: a `token` (§5.6.2). */
 const METHOD_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
 export function transportFailure(code, requestId, allow) {

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

@@ -56,6 +56,14 @@ export declare function headerValue(normalized: Readonly<Record<string, string>>
  * Present includes empty: a header sent with no value was still sent.
  */
 export declare function protocolIdentityOf(normalized: Readonly<Record<string, string>>): ClientProtocolIdentity | undefined;
+/**
+ * The identity headers (§12.4) a request did not send, in the order the
+ * framework sends them — what the `A2000` answering it names (pilot.1).
+ * Empty exactly when {@link protocolIdentityOf} reads an identity.
+ */
+export declare function missingIdentityHeaders(normalized: Readonly<Record<string, string>>): readonly IdentityHeaderName[];
+/** The two identity headers' names, as the framework spells them. */
+export type IdentityHeaderName = (typeof headers)["protocolVersion"] | (typeof headers)["contractHash"];
 /**
  * Q13 (the architect's, 2026-10-04): the request's `Aventara-Request-Id` when
  * it is 1–128 characters of visible ASCII; otherwise `undefined` — the header

package/dist/protocol/protocol-headers.js

@@ -88,6 +88,14 @@ export function protocolIdentityOf(normalized) {
         hash,
     };
 }
+/**
+ * The identity headers (§12.4) a request did not send, in the order the
+ * framework sends them — what the `A2000` answering it names (pilot.1).
+ * Empty exactly when {@link protocolIdentityOf} reads an identity.
+ */
+export function missingIdentityHeaders(normalized) {
+    return [headers.protocolVersion, headers.contractHash].filter((name) => headerValue(normalized, name) === undefined);
+}
 /** Q13's adoptable correlation id: 1–128 characters of visible ASCII (`0x21`–`0x7E`). */
 const ADOPTABLE_REQUEST_ID = /^[\x21-\x7e]{1,128}$/;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/core",
-  "version": "0.1.0-pilot.0",
+  "version": "0.1.0-pilot.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",