castrum 0.7.0 → 0.9.1

package/src/ingress/constants.ts

@@ -1,56 +1,228 @@
 // src/ingress/constants.ts — SINGLE SOURCE OF TRUTH for ingress binary layout constants
-// These are read from the Rust native addon to eliminate duplication across:
+// These are read from Rust to eliminate duplication across:
 //   - src/ingress/index.ts
 //   - bench/servers/ingress-server.ts
 //   - Any future consumers
 //
-// IMPORTANT: Do NOT hardcode these values. They come from Rust's ingress_constants.rs
-// and are typed on the NativeAddon interface (src/native/index.ts).
+// IMPORTANT: Do NOT hardcode these values. They come from Rust's
+// `ingress/output.rs` (the single numeric source), projected to JS via either
+// `ingress_constants.rs` (NAPI) or the C-ABI layout blob `rust/ffi.rs`
+// `IngressLayout` (`castrum_ingress_layout`). Both read the same numbers, so
+// they cannot drift.
 
-import addon from "../native";
+import { getAddon } from '../native'
+import { getBunFFI, type BunFFI } from '../native/ffi'
+
+// Transport: bun:ffi is PRIMARY on Bun, so the layout is read through the
+// C-ABI blob WITHOUT dlopening the napi addon. Node — or forced
+// `CASTRUM_FFI_MODE=napi`, a missing symbol, or a failed bind-time self-test —
+// falls back to the napi addon. This is the ONE module that touches native at
+// import time; everything else in the package stays lazy.
+const ffi = getBunFFI()
+
+// Slot order mirrors the `#[repr(C)] IngressLayout` struct in rust/ffi.rs
+// (38 × u32 LE). Drift is guarded by the Rust unit test
+// `ingress_layout_c_abi_matches_output_source` and by the pinned values in the
+// bun:ffi bind-time self-test (a reorder → self-test fails → napi fallback).
+const SLOT = {
+  OUT_VERDICT: 0,
+  OUT_ERROR_CODE: 1,
+  OUT_STATUS: 2,
+  OUT_FLAGS: 3,
+  OUT_RATE_LIMIT: 4,
+  OUT_RATE_REMAINING: 5,
+  OUT_RATE_RESET: 6,
+  OUT_RETRY_AFTER: 7,
+  OUT_COOKIES_JSON_LEN: 8,
+  OUT_QUERY_JSON_LEN: 9,
+  OUT_HEADER_VARIANT: 10,
+  OUT_BODY_JSON_LEN: 11,
+  OUT_DATA_START: 12,
+  FLAG_HAS_COOKIES: 13,
+  FLAG_HAS_QUERY: 14,
+  FLAG_BODY_VALID_JSON: 15,
+  FLAG_SCHEMA_VALID: 16,
+  FLAG_CORS_ALLOWED: 17,
+  FLAG_IS_PREFLIGHT: 18,
+  FLAG_RATE_LIMITED: 19,
+  FLAG_HTTPS: 20,
+  FLAG_TRUSTED_PROXY: 21,
+  FLAG_BODY_TRUNCATED: 22,
+  HV_JSON: 23,
+  HV_CORS_SIMPLE: 24,
+  HV_CORS_PREFLIGHT: 25,
+  HV_RATE_ACTIVE: 26,
+  HV_RATE_LIMITED: 27,
+  HV_COUNT: 28,
+  ERR_NONE: 29,
+  ERR_CORS_PREFLIGHT: 30,
+  ERR_RATE_LIMITED: 31,
+  ERR_BODY_TOO_LARGE: 32,
+  ERR_INVALID_JSON: 33,
+  ERR_SCHEMA_VALIDATION: 34,
+  ERR_BAD_REQUEST: 35,
+  ERR_REQUEST_TOO_LARGE: 36,
+  ERR_INTERNAL: 37,
+} as const
+
+type Layout = Record<keyof typeof SLOT, number>
+
+/** Read the layout via the bun:ffi C-ABI blob (Bun primary path). */
+function readLayoutViaFfi(ffiLive: BunFFI): Layout {
+  const buf = new Uint8Array(38 * 4)
+  ffiLive.ingressLayout(buf)
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
+  const out = {} as Layout
+  for (const key of Object.keys(SLOT) as (keyof typeof SLOT)[]) {
+    out[key] = view.getUint32(SLOT[key] * 4, true)
+  }
+  return out
+}
+
+/** Read the layout via the napi addon (Node / fallback). */
+function readLayoutViaNapi(): Layout {
+  const addon = getAddon()
+  return {
+    OUT_VERDICT: addon.INGRESS_OUT_VERDICT,
+    OUT_ERROR_CODE: addon.INGRESS_OUT_ERROR_CODE,
+    OUT_STATUS: addon.INGRESS_OUT_STATUS,
+    OUT_FLAGS: addon.INGRESS_OUT_FLAGS,
+    OUT_RATE_LIMIT: addon.INGRESS_OUT_RATE_LIMIT,
+    OUT_RATE_REMAINING: addon.INGRESS_OUT_RATE_REMAINING,
+    OUT_RATE_RESET: addon.INGRESS_OUT_RATE_RESET,
+    OUT_RETRY_AFTER: addon.INGRESS_OUT_RETRY_AFTER,
+    OUT_COOKIES_JSON_LEN: addon.INGRESS_OUT_COOKIES_JSON_LEN,
+    OUT_QUERY_JSON_LEN: addon.INGRESS_OUT_QUERY_JSON_LEN,
+    OUT_HEADER_VARIANT: addon.INGRESS_OUT_HEADER_VARIANT,
+    OUT_BODY_JSON_LEN: addon.INGRESS_OUT_BODY_JSON_LEN,
+    OUT_DATA_START: addon.INGRESS_OUT_DATA_START,
+    FLAG_HAS_COOKIES: addon.INGRESS_FLAG_HAS_COOKIES,
+    FLAG_HAS_QUERY: addon.INGRESS_FLAG_HAS_QUERY,
+    FLAG_BODY_VALID_JSON: addon.INGRESS_FLAG_BODY_VALID_JSON,
+    FLAG_SCHEMA_VALID: addon.INGRESS_FLAG_SCHEMA_VALID,
+    FLAG_CORS_ALLOWED: addon.INGRESS_FLAG_CORS_ALLOWED,
+    FLAG_IS_PREFLIGHT: addon.INGRESS_FLAG_IS_PREFLIGHT,
+    FLAG_RATE_LIMITED: addon.INGRESS_FLAG_RATE_LIMITED,
+    FLAG_HTTPS: addon.INGRESS_FLAG_HTTPS,
+    FLAG_TRUSTED_PROXY: addon.INGRESS_FLAG_TRUSTED_PROXY,
+    FLAG_BODY_TRUNCATED: addon.INGRESS_FLAG_BODY_TRUNCATED,
+    HV_JSON: addon.INGRESS_HV_JSON,
+    HV_CORS_SIMPLE: addon.INGRESS_HV_CORS_SIMPLE,
+    HV_CORS_PREFLIGHT: addon.INGRESS_HV_CORS_PREFLIGHT,
+    HV_RATE_ACTIVE: addon.INGRESS_HV_RATE_ACTIVE,
+    HV_RATE_LIMITED: addon.INGRESS_HV_RATE_LIMITED,
+    HV_COUNT: addon.INGRESS_HV_COUNT,
+    ERR_NONE: addon.INGRESS_ERR_NONE,
+    ERR_CORS_PREFLIGHT: addon.INGRESS_ERR_CORS_PREFLIGHT,
+    ERR_RATE_LIMITED: addon.INGRESS_ERR_RATE_LIMITED,
+    ERR_BODY_TOO_LARGE: addon.INGRESS_ERR_BODY_TOO_LARGE,
+    ERR_INVALID_JSON: addon.INGRESS_ERR_INVALID_JSON,
+    ERR_SCHEMA_VALIDATION: addon.INGRESS_ERR_SCHEMA_VALIDATION,
+    ERR_BAD_REQUEST: addon.INGRESS_ERR_BAD_REQUEST,
+    ERR_REQUEST_TOO_LARGE: addon.INGRESS_ERR_REQUEST_TOO_LARGE,
+    ERR_INTERNAL: addon.INGRESS_ERR_INTERNAL,
+  }
+}
+
+const L: Layout = ffi !== null ? readLayoutViaFfi(ffi) : readLayoutViaNapi()
 
 // ── Output buffer layout ───────────────────────────────────
-export const OUT_VERDICT: number = addon.INGRESS_OUT_VERDICT;
-export const OUT_ERROR_CODE: number = addon.INGRESS_OUT_ERROR_CODE;
-export const OUT_STATUS: number = addon.INGRESS_OUT_STATUS;
-export const OUT_FLAGS: number = addon.INGRESS_OUT_FLAGS;
-export const OUT_RATE_LIMIT: number = addon.INGRESS_OUT_RATE_LIMIT;
-export const OUT_RATE_REMAINING: number = addon.INGRESS_OUT_RATE_REMAINING;
-export const OUT_RATE_RESET: number = addon.INGRESS_OUT_RATE_RESET;
-export const OUT_RETRY_AFTER: number = addon.INGRESS_OUT_RETRY_AFTER;
-export const OUT_COOKIES_JSON_LEN: number = addon.INGRESS_OUT_COOKIES_JSON_LEN;
-export const OUT_QUERY_JSON_LEN: number = addon.INGRESS_OUT_QUERY_JSON_LEN;
-export const OUT_HEADER_VARIANT: number = addon.INGRESS_OUT_HEADER_VARIANT;
-export const OUT_BODY_JSON_LEN: number = addon.INGRESS_OUT_BODY_JSON_LEN;
-export const OUT_DATA_START: number = addon.INGRESS_OUT_DATA_START;
-
-// ── Flags ──────────────────────────────────────────────────
-export const FLAG_HAS_COOKIES: number = addon.INGRESS_FLAG_HAS_COOKIES;
-export const FLAG_HAS_QUERY: number = addon.INGRESS_FLAG_HAS_QUERY;
-export const FLAG_BODY_VALID_JSON: number = addon.INGRESS_FLAG_BODY_VALID_JSON;
-export const FLAG_SCHEMA_VALID: number = addon.INGRESS_FLAG_SCHEMA_VALID;
-export const FLAG_CORS_ALLOWED: number = addon.INGRESS_FLAG_CORS_ALLOWED;
-export const FLAG_IS_PREFLIGHT: number = addon.INGRESS_FLAG_IS_PREFLIGHT;
-export const FLAG_RATE_LIMITED: number = addon.INGRESS_FLAG_RATE_LIMITED;
-export const FLAG_HTTPS: number = addon.INGRESS_FLAG_HTTPS;
-export const FLAG_TRUSTED_PROXY: number = addon.INGRESS_FLAG_TRUSTED_PROXY;
-export const FLAG_BODY_TRUNCATED: number = addon.INGRESS_FLAG_BODY_TRUNCATED;
-
-// ── Header variant bits ────────────────────────────────────
-export const HV_JSON: number = addon.INGRESS_HV_JSON;
-export const HV_CORS_SIMPLE: number = addon.INGRESS_HV_CORS_SIMPLE;
-export const HV_CORS_PREFLIGHT: number = addon.INGRESS_HV_CORS_PREFLIGHT;
-export const HV_RATE_ACTIVE: number = addon.INGRESS_HV_RATE_ACTIVE;
-export const HV_RATE_LIMITED: number = addon.INGRESS_HV_RATE_LIMITED;
-export const HV_COUNT: number = addon.INGRESS_HV_COUNT;
-
-// ── Error codes ────────────────────────────────────────────
-export const ERR_CODE_NONE: number = addon.INGRESS_ERR_NONE;
-export const ERR_CODE_CORS_PREFLIGHT: number = addon.INGRESS_ERR_CORS_PREFLIGHT;
-export const ERR_CODE_RATE_LIMITED: number = addon.INGRESS_ERR_RATE_LIMITED;
-export const ERR_CODE_BODY_TOO_LARGE: number = addon.INGRESS_ERR_BODY_TOO_LARGE;
-export const ERR_CODE_INVALID_JSON: number = addon.INGRESS_ERR_INVALID_JSON;
-export const ERR_CODE_SCHEMA_VALIDATION: number = addon.INGRESS_ERR_SCHEMA_VALIDATION;
-export const ERR_CODE_BAD_REQUEST: number = addon.INGRESS_ERR_BAD_REQUEST;
-export const ERR_CODE_REQUEST_TOO_LARGE: number = addon.INGRESS_ERR_REQUEST_TOO_LARGE;
-export const ERR_CODE_INTERNAL: number = addon.INGRESS_ERR_INTERNAL;
+// Byte offsets into the fixed header of the native ingress OUTPUT buffer.
+// The header occupies [0, OUT_DATA_START); the cookie/query/body JSON sections
+// follow at OUT_DATA_START (see decode/packed-sections.ts). Read through the
+// C-ABI layout blob (Bun) or napi (Node) — never hardcoded.
+
+/** Offset of the verdict byte (0 = accepted, nonzero = terminal error). */
+export const OUT_VERDICT: number = L.OUT_VERDICT
+/** Offset of the error-code byte (see ERR_CODE_* below). */
+export const OUT_ERROR_CODE: number = L.OUT_ERROR_CODE
+/** Offset of the raw u16 status. */
+export const OUT_STATUS: number = L.OUT_STATUS
+/** Offset of the u32 flags word (see FLAG_* below). */
+export const OUT_FLAGS: number = L.OUT_FLAGS
+/** Offset of the u32 rate-limit budget (U32_MAX = disabled). */
+export const OUT_RATE_LIMIT: number = L.OUT_RATE_LIMIT
+/** Offset of the u32 rate-limit remaining count. */
+export const OUT_RATE_REMAINING: number = L.OUT_RATE_REMAINING
+/** Offset of the u64 rate-limit window reset (ms epoch). */
+export const OUT_RATE_RESET: number = L.OUT_RATE_RESET
+/** Offset of the u64 Retry-After value (ms). */
+export const OUT_RETRY_AFTER: number = L.OUT_RETRY_AFTER
+/** Offset of the u32 cookies-JSON section length. */
+export const OUT_COOKIES_JSON_LEN: number = L.OUT_COOKIES_JSON_LEN
+/** Offset of the u32 query-JSON section length. */
+export const OUT_QUERY_JSON_LEN: number = L.OUT_QUERY_JSON_LEN
+/** Offset of the header-template variant byte (see HV_* below). */
+export const OUT_HEADER_VARIANT: number = L.OUT_HEADER_VARIANT
+/** Offset of the u32 body-JSON section length. */
+export const OUT_BODY_JSON_LEN: number = L.OUT_BODY_JSON_LEN
+/** Byte offset where the variable-length JSON sections begin. */
+export const OUT_DATA_START: number = L.OUT_DATA_START
+
+// ── Flags (bits within the OUT_FLAGS u32) ──────────────────
+/** Request carried a cookie header (cookie-JSON section present). */
+export const FLAG_HAS_COOKIES: number = L.FLAG_HAS_COOKIES
+/** Request carried a query string (query-JSON section present). */
+export const FLAG_HAS_QUERY: number = L.FLAG_HAS_QUERY
+/** The request body parsed as valid JSON. */
+export const FLAG_BODY_VALID_JSON: number = L.FLAG_BODY_VALID_JSON
+/** The request body validated against the ingress schema. */
+export const FLAG_SCHEMA_VALID: number = L.FLAG_SCHEMA_VALID
+/** The CORS engine allowed the request origin. */
+export const FLAG_CORS_ALLOWED: number = L.FLAG_CORS_ALLOWED
+/** The request was a CORS preflight (OPTIONS + request-method). */
+export const FLAG_IS_PREFLIGHT: number = L.FLAG_IS_PREFLIGHT
+/** The request was rate-limited. */
+export const FLAG_RATE_LIMITED: number = L.FLAG_RATE_LIMITED
+/** The request arrived over HTTPS (trusted-proxy scheme). */
+export const FLAG_HTTPS: number = L.FLAG_HTTPS
+/** The request came from a trusted proxy (per the proxy config). */
+export const FLAG_TRUSTED_PROXY: number = L.FLAG_TRUSTED_PROXY
+/** A declared output section overran the buffer (truncated). */
+export const FLAG_BODY_TRUNCATED: number = L.FLAG_BODY_TRUNCATED
+
+// ── Header variant bits (bits within the OUT_HEADER_VARIANT byte) ──
+/** Response body is JSON (`content-type: application/json`). */
+export const HV_JSON: number = L.HV_JSON
+/** CORS simple-request variant (Origin echoed + vary headers). */
+export const HV_CORS_SIMPLE: number = L.HV_CORS_SIMPLE
+/** CORS preflight variant (allow-methods/headers/max-age). */
+export const HV_CORS_PREFLIGHT: number = L.HV_CORS_PREFLIGHT
+/** Rate-limit active variant (`ratelimit-limit` header). */
+export const HV_RATE_ACTIVE: number = L.HV_RATE_ACTIVE
+/** Rate-limited variant (Retry-After emitted). */
+export const HV_RATE_LIMITED: number = L.HV_RATE_LIMITED
+/** Total number of header-variant combinations (32). */
+export const HV_COUNT: number = L.HV_COUNT
+
+// ── Error codes (bytes in OUT_ERROR_CODE) ──────────────────
+/** No error (accepted). */
+export const ERR_CODE_NONE: number = L.ERR_NONE
+/** CORS preflight rejected. */
+export const ERR_CODE_CORS_PREFLIGHT: number = L.ERR_CORS_PREFLIGHT
+/** Rate limit exceeded. */
+export const ERR_CODE_RATE_LIMITED: number = L.ERR_RATE_LIMITED
+/** Request body exceeded the size guard. */
+export const ERR_CODE_BODY_TOO_LARGE: number = L.ERR_BODY_TOO_LARGE
+/** Request body is not valid JSON. */
+export const ERR_CODE_INVALID_JSON: number = L.ERR_INVALID_JSON
+/** Request body failed schema validation. */
+export const ERR_CODE_SCHEMA_VALIDATION: number = L.ERR_SCHEMA_VALIDATION
+/** Malformed request (bad request line / headers). */
+export const ERR_CODE_BAD_REQUEST: number = L.ERR_BAD_REQUEST
+/** Request headers/URL exceeded the configured limits. */
+export const ERR_CODE_REQUEST_TOO_LARGE: number = L.ERR_REQUEST_TOO_LARGE
+/** Internal pipeline failure (maps to 500). */
+export const ERR_CODE_INTERNAL: number = L.ERR_INTERNAL
+
+/**
+ * JS-only error-code sentinel for a request-body read timeout in the async
+ * `createIngress` path.
+ *
+ * The native pipeline never emits this value — it is a JS body-reader error
+ * (`REQUEST_TIMEOUT` from `readBodyWithLimit`) mapped onto the numeric
+ * error-code contract so the shared status/name/message helpers stay
+ * consistent. Deliberately not sourced from Rust (see the header comment:
+ * numeric layout values come from the addon; this one is a JS-level error).
+ */
+export const ERR_CODE_REQUEST_TIMEOUT: number = -1

package/src/ingress/context.ts

@@ -0,0 +1,136 @@
+// src/ingress/context.ts — Result snapshotting + synthetic/error context
+// builders for the async ingress API.
+
+import type { ResponseBuildContext } from './headers/fast-templates'
+import { buildTerminalResponse } from './response/terminal'
+import { ERR_CODE_INTERNAL, ERR_CODE_RATE_LIMITED, HV_JSON, HV_CORS_SIMPLE } from './constants'
+import type { IngressOptions, IngressResult, IngressContext } from './types'
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/**
+ * Deep-snapshot a result so the caller can use it after `run()` returns.
+ *
+ * Note on aliasing: the returned `body` field aliases the request body buffer
+ * (`r.body`) — it is NOT copied — while `bodyJson()` returns a stable copy
+ * (captured once at snapshot time, safe after the live result is invalidated).
+ * In the async `createIngress` path the aliased buffer is the fully-
+ * materialized request body, which lives as long as the request and is never
+ * reused, so the alias is safe. Treat `body` as read-only; use `bodyJson()`
+ * for a defensive copy.
+ */
+export function snapshotResult(r: IngressResult): IngressResult {
+  const cookies = r.cookiesJson()
+  const query = r.queryJson()
+  const bodyJson = r.bodyJson().slice()
+  const body = r.body
+
+  return {
+    status: r.status,
+    verdict: r.verdict,
+    flags: r.flags,
+    errorCode: r.errorCode,
+    terminal: r.terminal,
+    ok: r.ok,
+    https: r.https,
+    trustedProxy: r.trustedProxy,
+    hasCookies: r.hasCookies,
+    hasQuery: r.hasQuery,
+    bodyValidJson: r.bodyValidJson,
+    schemaValid: r.schemaValid,
+    corsAllowed: r.corsAllowed,
+    isPreflight: r.isPreflight,
+    rateLimited: r.rateLimited,
+    rateLimit: r.rateLimit,
+    rateRemaining: r.rateRemaining,
+    rateResetMs: r.rateResetMs,
+    retryAfterMs: r.retryAfterMs,
+    body,
+    headerVariant: r.headerVariant,
+    requestId: r.requestId,
+    bodyTruncated: r.bodyTruncated,
+
+    cookiesJson: () => cookies,
+    queryJson: () => query,
+    bodyJson: () => bodyJson,
+  }
+}
+
+/** Build a synthetic (terminal) context for body-size / error short-circuits. */
+export function syntheticContext(
+  req: Request,
+  requestId: string,
+  options: IngressOptions,
+  responseCtx: ResponseBuildContext,
+  status: number,
+  errorCode: number,
+): IngressContext {
+  const corsAllowed = staticCorsAllowed(options, req)
+  const variant = HV_JSON | (corsAllowed ? HV_CORS_SIMPLE : 0)
+
+  const base: IngressResult = {
+    status,
+    verdict: 1,
+    flags: 0,
+    errorCode,
+    terminal: true,
+    ok: false,
+    https: options.https === true,
+    trustedProxy: options.trustProxy === true || options.trustedProxies?.enabled === true,
+    hasCookies: false,
+    hasQuery: false,
+    bodyValidJson: false,
+    schemaValid: false,
+    corsAllowed,
+    isPreflight: false,
+    rateLimited: errorCode === ERR_CODE_RATE_LIMITED,
+    rateLimit: options.rateLimit?.limit ?? 0,
+    rateRemaining: 0,
+    rateResetMs: 0,
+    retryAfterMs: 0,
+    body: EMPTY_BODY,
+    headerVariant: variant,
+    requestId,
+    bodyTruncated: false,
+
+    cookiesJson: () => '{}',
+    queryJson: () => '{}',
+    bodyJson: () => EMPTY_BODY,
+  }
+
+  return {
+    ...base,
+    response: buildTerminalResponse(responseCtx, base, req, requestId),
+  }
+}
+
+/** Build the internal-error context (status 500). */
+export function internalContext(
+  req: Request,
+  requestId: string,
+  options: IngressOptions,
+  responseCtx: ResponseBuildContext,
+): IngressContext {
+  return syntheticContext(req, requestId, options, responseCtx, 500, ERR_CODE_INTERNAL)
+}
+
+/** Statically determine whether the configured CORS policy allows `req`. */
+export function staticCorsAllowed(options: IngressOptions, req: Request): boolean {
+  const cors = options.cors
+  if (!cors) return false
+
+  const origin = req.headers.get('origin')
+  if (!origin) return false
+
+  const list = cors.allowOrigin
+
+  if (!list || list.length === 0) {
+    return cors.allowCredentials !== true
+  }
+
+  if (list.includes('*')) {
+    return cors.allowCredentials !== true
+  }
+
+  return list.includes(origin)
+}

package/src/ingress/decode/baked-result.ts

@@ -0,0 +1,121 @@
+// src/ingress/decode/baked-result.ts — Zero-alloc result decoder (pre-baked
+// path).
+//
+// Decodes the native Ingress packed output (OUT_* layout in ./constants.ts)
+// into the pre-baked handler result, which carries the benchmark wire format
+// ({"ok":false,"error":{...}}).
+//
+// NOTE: this is the pre-baked-path decoder with its own status normalization.
+// The fast path has its own decoder (./fast-result.ts) — do not unify them
+// (see AGENTS.md). The two decoders DO share their section/rate-limit plumbing
+// via ./result-base.ts.
+
+import {
+  OUT_VERDICT,
+  OUT_FLAGS,
+  OUT_RATE_LIMIT,
+  OUT_RATE_REMAINING,
+  OUT_COOKIES_JSON_LEN,
+  OUT_QUERY_JSON_LEN,
+  OUT_HEADER_VARIANT,
+  OUT_BODY_JSON_LEN,
+  OUT_DATA_START,
+  FLAG_BODY_VALID_JSON,
+  FLAG_SCHEMA_VALID,
+  FLAG_CORS_ALLOWED,
+  FLAG_IS_PREFLIGHT,
+  FLAG_RATE_LIMITED,
+  FLAG_TRUSTED_PROXY,
+  FLAG_BODY_TRUNCATED,
+  HV_JSON,
+  ERR_CODE_INTERNAL as ERROR_CODE_INTERNAL,
+} from '../constants'
+import { sectionLayout } from './packed-sections'
+import { isValidResponseStatus } from '../status'
+import { IngressResultBase } from './result-base'
+
+/** Zero-alloc, reusable result decoder for the pre-baked handler path. */
+export class BakedIngressResult extends IngressResultBase {
+  refresh(buf: Uint8Array, body: Uint8Array, view: DataView): void {
+    // Defensive: the native core always writes the full fixed header
+    // (>= OUT_DATA_START bytes) before returning `written`. The cached
+    // whole-buffer DataView (see viewForArrayBuffer) would otherwise decode
+    // stale bytes if this contract is ever violated — treat as internal error.
+    if (buf.byteLength < OUT_DATA_START) {
+      this.setInternalError()
+      return
+    }
+    this.body = body
+
+    const h0 = view.getUint32(OUT_VERDICT, true)
+    const h1 = view.getUint32(OUT_FLAGS, true)
+    const h2 = view.getUint32(OUT_RATE_LIMIT, true)
+    const h3 = view.getUint32(OUT_RATE_REMAINING, true)
+
+    const cookiesLenRaw = view.getUint32(OUT_COOKIES_JSON_LEN, true)
+    const queryLenRaw = view.getUint32(OUT_QUERY_JSON_LEN, true)
+    const headerVariant = view.getUint8(OUT_HEADER_VARIANT)
+    const bodyJsonLenRaw = view.getUint32(OUT_BODY_JSON_LEN, true)
+
+    // Bounds-checked section offsets shared with the fast decoder: a
+    // malformed/truncated buffer can never produce slices past its end.
+    const layout = sectionLayout(buf.byteLength, cookiesLenRaw, queryLenRaw, bodyJsonLenRaw)
+
+    if (h0 === 0 && h1 === 0) {
+      this.verdict = 1
+      this.errorCode = ERROR_CODE_INTERNAL
+      this.status = 500
+    } else {
+      this.verdict = h0 & 0xff
+      this.errorCode = (h0 >>> 8) & 0xff
+
+      const rawStatus = (h0 >>> 16) & 0xffff
+      // Reuse the shared status-validity helper instead of re-inlining the
+      // 101/200-599 check (single source of truth in ../status.ts).
+      this.status = isValidResponseStatus(rawStatus) ? rawStatus : 500
+    }
+
+    const flags = h1
+
+    this.rateRemaining = h3
+
+    this.setRateWindow(h2, (flags & FLAG_RATE_LIMITED) !== 0, view)
+
+    this.headerVariant = headerVariant
+
+    // The baked path trusts the already-clamped section lengths, so pass the
+    // safe body len here (the fast path re-checks bounds on read instead).
+    this.setSections(buf, layout, layout.safeBodyJsonLen)
+
+    this.updateOkTerminal()
+
+    this.isPreflight = (flags & FLAG_IS_PREFLIGHT) !== 0
+    this.corsAllowed = (flags & FLAG_CORS_ALLOWED) !== 0
+    this.rateLimited = (flags & FLAG_RATE_LIMITED) !== 0
+    this.trustedProxy = (flags & FLAG_TRUSTED_PROXY) !== 0
+    this.bodyValidJson = (flags & FLAG_BODY_VALID_JSON) !== 0
+    this.schemaValid = (flags & FLAG_SCHEMA_VALID) !== 0
+
+    this.bodyTruncated = (flags & FLAG_BODY_TRUNCATED) !== 0 || layout.truncated
+  }
+
+  invalidate(): void {
+    // The baked empty state is neutral (0/0/0) — exactly what resetShared sets.
+    this.resetShared()
+  }
+
+  setInternalError(): void {
+    this.invalidate()
+    this.status = 500
+    this.verdict = 1
+    this.errorCode = ERROR_CODE_INTERNAL
+    this.headerVariant = HV_JSON
+    this.terminal = true
+    this.ok = false
+  }
+
+  bodyJson(copy: boolean): Uint8Array {
+    const slice = this.bodyJsonSlice()
+    return (copy ? slice.slice() : slice) as Uint8Array
+  }
+}