@skyold/protocol-engine 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -25,15 +25,16 @@ its own TypeScript build, its own test command, and one runtime dependency:
 concrete Provider Adapters, storage, HTTP frameworks, credential stores, or
 network clients.
 
-The package and its normalized-contract dependency are configured for public
-npm access, but no registry release has been made yet. Therefore:
+The package and its normalized-contract dependency have a public
+`0.1.0-beta.1` release under the `beta` dist-tag. Therefore:
 
 - it is independently embeddable and testable by packages in this repository;
 - its packed runtime surface is independently inspectable;
 - packed tarballs can be installed and exercised by an isolated external
   consumer;
-- public registry availability, a versioned release, and provenance signing are
-  not claimed until the release gate completes.
+- public registry installation has been smoke-tested from an isolated consumer;
+- exact-SHA CI for the release-preparation tree, downstream adoption,
+  provenance signing, and real-Provider acceptance remain separate gates.
 
 The local V1 core implementation is complete against its frozen execution
 boundary. Overall rollout certification is still incomplete: fixture-backed
@@ -302,6 +303,17 @@ selects the protocol Adapter, and returns one versioned execution start:
 - `accepted-job` for durable asynchronous Provider acceptance;
 - `rejected` for not-accepted or acceptance-unknown asynchronous starts.
 
+When a Provider response was received, `providerResponse` carries its status,
+headers, and body bytes as the authoritative result. Successfully parsed and
+semantically validated non-failure stream events carry their exact SSE frame in
+`providerWire`; normalized terminal and event fields are derived observations of
+that same result. Provider errors, malformed or unknown frames, cancellation,
+and bytes after a terminal never use raw passthrough and produce only bounded
+safe egress. Caller-facing direct egress projects headers through
+`projectProviderResponseHeadersForCallerV1`: connection, credential, cookie,
+representation-length/encoding, caching, CORS, rate-limit, and security-policy
+fields remain Host-owned and are not copied from upstream.
+
 Use `engine.jobs.get`, `engine.jobs.list`, and `engine.jobs.cancel` for later
 async-job operations. Persistence, polling, callbacks, materialization, usage,
 and settlement remain Host responsibilities.
@@ -315,25 +327,36 @@ support `get` without pretending to support `list` or `cancel`.
 ### Provider response compatibility
 
 Provider wire responses are an open-world boundary. An Adapter validates and
-extracts the fields understood by its protocol version, ignores additive fields
-in synchronous bodies and known stream frames, and never retains those unknown
-fields in normalized output. This lets a Provider add response metadata without
-breaking an otherwise compatible protocol implementation.
+extracts the fields understood by its protocol version as derived normalized
+facts. For same-protocol egress, status, raw headers, and body bytes remain the
+authoritative response. A recognized non-failure SSE event retains its exact
+validated frame, including additive fields. Unknown event kinds, malformed
+frames, Provider failures, cancellation, opaque passthrough, and post-terminal
+bytes fail closed or use bounded normalized egress; they are never returned as
+raw caller-visible wire. Headers cross a separate caller-safe projection so
+transport or security metadata for one HTTP hop is not mistaken for another.
 
 Compatibility does not turn malformed known facts into success. Missing,
 mistyped, conflicting, duplicated, unsafe, or semantically invalid known fields
-still fail. An unknown stream event kind can alter lifecycle semantics, so it is
-not treated as a harmless additive field and fails unless the protocol Adapter
-explicitly supports it. Parser depth, body-size, URL, base64, index, usage, and
-terminal-consistency limits remain enforced.
+make the derived normalization fail. Parser depth, body-size, URL, base64, index,
+usage, and terminal-consistency limits continue to protect normalization and
+execution; transport or framing failures can of course prevent a complete
+response from being received.
 
 The Engine then validates Adapter outputs before exposing them to a Host. This
 includes sync/stream acceptance, terminal structure and consistency, every
-normalized stream event, plus async start, snapshot, and list result structure.
+normalized stream event, plus async start, snapshot, list, and cancellation
+result structure.
 Normalized event, metadata, terminal, result, usage, Responses, and async-job
-objects are closed schemas: undeclared fields are rejected. Raw Provider
-extensions therefore cannot leak through an Adapter to Host egress, usage, or
-settlement.
+objects are closed schemas: undeclared derived facts are rejected. The explicit
+Provider response envelope is not part of that closed projection. Hosts may use
+only normalized facts for usage or settlement while returning the authoritative
+Provider response to a same-protocol caller.
+
+When an async follow-up receives a complete non-success Provider response, the
+Engine error exposes that validated response in `providerResponse`. Hosts must
+never serialize the whole Engine error or its diagnostic `cause`; they may
+explicitly apply same-protocol egress policy to the response envelope.
 
 Terminal results must match the requested Task kind, and duplicate result,
 terminal, and Responses usage facts must agree when present. A custom Adapter
@@ -371,13 +394,13 @@ No test suite can mathematically guarantee all future Engine functionality.
 TokenForge uses separate proof layers so a narrow unit test is not mistaken for
 complete proxy evidence.
 
-| Layer                       | Command                                                                                                                                                   | What it proves                                                                                                 | What it does not prove                                         |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| Engine package              | `pnpm --dir packages/protocol-engine check`                                                                                                               | Independent build plus core Registry, binding, sync, stream, async-job, validation and Host-equivalence tests. | Concrete Adapter wire formats, Host persistence, live network. |
-| Built-in conformance        | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                             | Every registered built-in family executes through public Engine API with fixture Transports.                   | Provider credentials or current remote behavior.               |
-| Architecture boundary       | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts`                                                                      | Engine dependency isolation, package surface, no raw-forward/direct Adapter bypass, Host neutrality.           | Runtime semantic correctness by itself.                        |
-| Host integration            | Targeted suites for each embedding application and repository `pnpm check`                                                                                | Caller-specific context binding, streams, media persistence, usage and settlement compatibility.               | Exact deployed SHA or live Provider availability.              |
-| Real Provider certification | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS` | Current authenticated Provider behavior for every successful evidence shard.                                   | Deployment, billing correctness, or a missing family.          |
+| Layer                       | Command                                                                                                                                                                                | What it proves                                                                                                        | What it does not prove                                         |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Engine package              | `pnpm --dir packages/protocol-engine check`                                                                                                                                            | Independent build plus core Registry, binding, sync, stream, async-job, validation and Host-equivalence tests.        | Concrete Adapter wire formats, Host persistence, live network. |
+| Built-in conformance        | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                                                          | Every registered built-in family executes through public Engine API with fixture Transports.                          | Provider credentials or current remote behavior.               |
+| Architecture boundary       | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts` (TokenForge source monorepo)                                                                      | Engine dependency isolation, package surface, explicit Provider response ownership through Adapters, Host neutrality. | Runtime semantic correctness by itself.                        |
+| Host integration            | Targeted suites for each embedding application and repository `pnpm check`                                                                                                             | Caller-specific context binding, streams, media persistence, usage and settlement compatibility.                      | Exact deployed SHA or live Provider availability.              |
+| Real Provider certification | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS` (TokenForge source monorepo) | Current authenticated Provider behavior for every successful evidence shard.                                          | Deployment, billing correctness, or a missing family.          |
 
 For a local Engine change, the minimum independent gate is the Engine package
 command. A protocol or Adapter change must also pass built-in conformance. A
@@ -388,9 +411,11 @@ gates.
 
 ## Real-Provider certification
 
-The repository's opt-in certification Host drives this public Engine API and
-the built-in Adapter Registry directly; it does not enter through any product
-application route. A versioned JSON manifest supplies one or more cases for every
+The TokenForge source monorepo ships the opt-in certification Host that drives
+this public Engine API and the built-in Adapter Registry directly; it does not
+enter through any product application route. The certification commands in this
+section run in that monorepo, not in this repository. A versioned JSON manifest
+supplies one or more cases for every
 protocol family returned by `engine.protocolFamilies`, with resolved target and
 capability facts, normalized tasks, secret environment-variable names, exact
 Provider domains, and suite request/time ceilings. Pricing and Provider billing
@@ -434,6 +459,7 @@ Host can perform a one-request, read-only diagnostic through `engine.jobs.list`
 without creating another task:
 
 ```bash
+# Run in the TokenForge source monorepo (apps/acceptance), not in this repository.
 pnpm --filter @tokenforge/acceptance diagnose:protocol-engine-real-async \
   --manifest /protected/path/async-shard.json \
   --env-file /protected/path/provider.env \
@@ -451,6 +477,7 @@ exhausted after the Provider had accepted the task, recover that exact submitted
 task without creating another one:
 
 ```bash
+# Run in the TokenForge source monorepo (apps/acceptance), not in this repository.
 pnpm --filter @tokenforge/acceptance recover:protocol-engine-real-shard \
   --manifest /protected/path/async-shard.json \
   --failure-evidence /protected/path/polling-exhausted.json \

package/README.zh-CN.md

@@ -12,12 +12,13 @@
 
 引擎是一个独立的 workspace package，提供唯一的包根 ESM API、独立的 TypeScript 构建和测试命令，且只有一个运行时依赖：`@skyold/model-protocol`。它不依赖任何 TokenForge Host、具体 Provider Adapter、存储、HTTP 框架、凭证仓库或网络客户端。
 
-该包及其规范化协议依赖已经配置公开 npm 元数据，但尚未执行 registry 首次发布。因此，当前可以确认的是：
+该包及其规范化协议依赖已通过 `beta` dist-tag 公开发布为 `0.1.0-beta.1`。因此，当前可以确认的是：
 
 - 仓库内其他 package 可以独立嵌入并测试它；
 - 可以独立检查它的打包运行时边界；
 - 打包 tarball 已可由隔离的外部消费者安装与验证；
-- 在发布门禁完成前，不承诺公共 registry 可用性、版本化发布或来源签名。
+- 已从隔离消费者通过公共 registry 安装并完成运行 smoke；
+- 发布准备树的 exact-SHA CI、下游采用、来源签名和真实 Provider 验收仍是独立门禁。
 
 本地 V1 核心已经完成并冻结在既定执行边界内。整体上线认证尚未完成：九种内置协议族的 fixture conformance 已全部通过，当前已有七种协议的真实 Provider 成功证据；`openai-embeddings/v1` 和 `openai-images/v1` 仍待真实成功认证。公开发布、exact-SHA CI 和部署属于独立交付门禁，不是把 Host 业务逻辑加入引擎的理由。
 
@@ -225,17 +226,21 @@ try {
 - `accepted-job`：Provider 已持久接受异步任务；
 - `rejected`：异步启动未被接受，或接受状态未知。
 
+只要已经收到 Provider 响应，`providerResponse` 就以权威结果的身份携带状态码、响应头和 body 原始字节。成功解析并通过语义校验的非失败流事件会通过 `providerWire` 携带其精确 SSE frame；规范化 terminal 和 event 是对同一结果的派生观察。Provider error、malformed/unknown frame、取消、opaque passthrough 和终态后的字节一律不得 raw passthrough，只能产生有界的安全下行。面向调用方的 direct egress 还会通过 `projectProviderResponseHeadersForCallerV1` 投影响应头：连接级、凭证、Cookie、表示长度/编码、缓存、CORS、限流和安全策略字段都由 Host 持有，不能从上游直接复制。
+
 后续异步任务操作使用 `engine.jobs.get`、`engine.jobs.list` 和 `engine.jobs.cancel`。持久化、轮询、回调、物化、用量和结算仍是 Host 职责。
 
 异步 Adapter factory 通过 `jobOperations` 声明支持的后续操作。引擎会在绑定 Transport 前，以 `PROTOCOL_ENGINE_CAPABILITY_UNSUPPORTED` 拒绝未声明的操作。因此协议可以保留真实生命周期差异：例如，一个协议可以支持 `get`，而不需要伪装成支持 `list` 或 `cancel`。
 
 ### Provider response 兼容原则
 
-Provider wire response 是开放世界边界。Adapter 校验并提取当前协议版本理解的字段，忽略同步 body 和已知 stream frame 中新增的附加字段，且不会把这些未知字段保留到规范化输出中。这样 Provider 新增响应元数据时，不会破坏原本兼容的协议实现。
+Provider wire response 是开放世界边界。Adapter 会把当前协议版本理解的字段提取为派生的规范化事实；对于同协议下行，状态码、原始响应头和 body 原始字节仍是权威结果。已识别的非失败 SSE 事件会保留其通过校验的精确 frame，包括附加字段。未知事件类型、malformed frame、Provider failure、取消、opaque passthrough 和终态后字节必须 fail closed 或使用有界的规范化下行，绝不能作为 raw wire 返回调用方。响应头另行经过 caller-safe 投影，避免把上一段 HTTP 连接或安全元数据误用于下一段连接。
+
+兼容不代表把已知字段异常当作成功。已知字段缺失、类型错误、冲突、重复、不安全或语义无效会导致派生归一化失败。解析深度、body 大小、URL、base64、index、usage 和终态一致性限制继续保护归一化与执行；Transport 或 framing 失败则可能使完整响应根本无法被接收。
 
-兼容不代表把已知字段异常当作成功。已知字段缺失、类型错误、冲突、重复、不安全或语义无效仍然失败。未知 stream event kind 可能改变生命周期语义，不能视为无害附加字段；除非协议 Adapter 明确支持，否则必须失败。解析深度、body 大小、URL、base64、index、usage 和终态一致性限制继续生效。
+随后，引擎会在向 Host 暴露结果前校验 Adapter 输出，包括同步/流式接受结果、终态结构与一致性、每个规范化流事件，以及异步启动、snapshot、列表和取消结果结构。规范化 event、metadata、terminal、result、usage、Responses 和异步任务对象仍是封闭 schema：未声明的派生事实会被拒绝。显式 Provider response envelope 不属于这个封闭投影；Host 可以只用规范化事实处理用量或结算，同时把权威 Provider 响应返回给同协议调用者。
 
-随后，引擎会在向 Host 暴露结果前校验 Adapter 输出，包括同步/流式接受结果、终态结构与一致性、每个规范化流事件，以及异步启动、snapshot 和列表结果结构。规范化 event、metadata、terminal、result、usage、Responses 和异步任务对象都是封闭 schema：未声明字段会被拒绝。因此 Provider 原始扩展字段不能穿过 Adapter 泄漏到 Host egress、用量或结算流程。
+异步后续操作收到完整的非成功 Provider 响应时，引擎错误会在 `providerResponse` 中暴露经过校验的响应。Host 绝不能序列化整个引擎错误或诊断用 `cause`；只能显式地对该响应 envelope 应用同协议 egress 策略。
 
 终态 result 必须与请求的 Task kind 一致；当 result、terminal 和 Responses 中重复出现 usage 事实时，它们必须一致。自定义 Adapter 不能依赖 TypeScript 类型断言绕过 V1 运行时契约，也不能让 Host egress 和结算观察到不同事实。
 
@@ -251,19 +256,19 @@ Provider wire response 是开放世界边界。Adapter 校验并提取当前协
 
 任何测试套件都无法在数学意义上保证未来全部引擎功能。TokenForge 把证明拆分为不同层级，避免把一个狭窄单元测试误认为完整 proxy 证据。
 
-| 层级               | 命令                                                                                                                                                      | 能证明                                                                           | 不能证明                                        |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- |
-| 引擎 package       | `pnpm --dir packages/protocol-engine check`                                                                                                               | 独立构建，以及 Registry、binding、同步、流式、异步任务、校验和 Host 等价性测试。 | 具体 Adapter wire 格式、Host 持久化、真实网络。 |
-| 内置 conformance   | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                             | 每个已注册内置协议族均通过公共 Engine API 和 fixture Transport 执行。            | Provider 凭证或当前远端行为。                   |
-| 架构边界           | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts`                                                                      | 引擎依赖隔离、package surface、禁止 raw-forward/直接绕过 Adapter、Host 中立性。  | 单独证明运行时语义正确。                        |
-| Host 集成          | 各嵌入应用的定向测试与仓库 `pnpm check`                                                                                                                   | 相应调用方的上下文绑定、流式、媒体持久化、用量与结算兼容。                       | exact-SHA 部署或真实 Provider 可用性。          |
-| 真实 Provider 认证 | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS` | 每个成功证据分片对应的当前、已认证 Provider 行为。                               | 部署、计费正确性或缺失协议族。                  |
+| 层级               | 命令                                                                                                                                                                                          | 能证明                                                                           | 不能证明                                        |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------- |
+| 引擎 package       | `pnpm --dir packages/protocol-engine check`                                                                                                                                                   | 独立构建，以及 Registry、binding、同步、流式、异步任务、校验和 Host 等价性测试。 | 具体 Adapter wire 格式、Host 持久化、真实网络。 |
+| 内置 conformance   | `pnpm --filter @skyold/provider-adapters test -- src/conformance/runtime-conformance.test.ts`                                                                                                 | 每个已注册内置协议族均通过公共 Engine API 和 fixture Transport 执行。            | Provider 凭证或当前远端行为。                   |
+| 架构边界           | `pnpm --filter @tokenforge/acceptance test -- src/L1-kernel/import-boundary.test.ts`（在 TokenForge 源 monorepo 中执行）                                                                      | 引擎依赖隔离、package surface、经 Adapter 显式承载 Provider 响应、Host 中立性。  | 单独证明运行时语义正确。                        |
+| Host 集成          | 各嵌入应用的定向测试与仓库 `pnpm check`                                                                                                                                                       | 相应调用方的上下文绑定、流式、媒体持久化、用量与结算兼容。                       | exact-SHA 部署或真实 Provider 可用性。          |
+| 真实 Provider 认证 | `pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run --env-file .env --ack-real-provider-calls I_AUTHORIZE_REAL_PROVIDER_CALLS`（在 TokenForge 源 monorepo 中执行） | 每个成功证据分片对应的当前、已认证 Provider 行为。                               | 部署、计费正确性或缺失协议族。                  |
 
 本地修改引擎时，最低独立门禁是引擎 package 命令。协议或 Adapter 变更还必须通过内置 conformance。Host 集成变更还必须通过受影响 Host 的测试。只有 Registry 清单中所有协议族都取得真实 Provider 成功证据，且实际交付的 exact SHA 通过 CI 和部署门禁，整个目标才算完成。
 
 ## 真实 Provider 认证
 
-仓库内的 opt-in 认证 Host 会直接驱动这套公共 Engine API 和内置 Adapter Registry，不经过任何产品应用的 route。版本化 JSON manifest 为 `engine.protocolFamilies` 返回的每个协议族提供一个或多个 case，其中包含已解析 target 与 capability 事实、规范化 task、密钥环境变量名、精确 Provider 域名，以及 suite 请求/时长上限。定价和 Provider 计费刻意不属于引擎契约或认证事实。
+TokenForge 源 monorepo 内的 opt-in 认证 Host 会直接驱动这套公共 Engine API 和内置 Adapter Registry，不经过任何产品应用的 route。本节的认证命令都在该 monorepo 中执行，不在本仓库执行。版本化 JSON manifest 为 `engine.protocolFamilies` 返回的每个协议族提供一个或多个 case，其中包含已解析 target 与 capability 事实、规范化 task、密钥环境变量名、精确 Provider 域名，以及 suite 请求/时长上限。定价和 Provider 计费刻意不属于引擎契约或认证事实。
 
 默认只做离线校验：
 
@@ -286,6 +291,7 @@ pnpm certify:protocol-engine-real --manifest /protected/path/suite.json --run \
 对于已被接受且支持 list 的异步 target，Acceptance Host 可以通过 `engine.jobs.list` 执行一次只读诊断，不会创建新任务：
 
 ```bash
+# 在 TokenForge 源 monorepo（apps/acceptance）中执行，不在本仓库执行。
 pnpm --filter @tokenforge/acceptance diagnose:protocol-engine-real-async \
   --manifest /protected/path/async-shard.json \
   --env-file /protected/path/provider.env \
@@ -298,6 +304,7 @@ pnpm --filter @tokenforge/acceptance diagnose:protocol-engine-real-async \
 当支持 list 的异步分片已经被 Provider 接受、但认证仅因有界轮询耗尽而停止时，可以恢复这一笔已提交任务，而不创建第二笔任务：
 
 ```bash
+# 在 TokenForge 源 monorepo（apps/acceptance）中执行，不在本仓库执行。
 pnpm --filter @tokenforge/acceptance recover:protocol-engine-real-shard \
   --manifest /protected/path/async-shard.json \
   --failure-evidence /protected/path/polling-exhausted.json \

package/dist/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { AdapterTerminalOutcome, NormalizedStreamEventV1, PreparedMediaExecutionInputV2, ProtocolFamily, ProviderAsyncJobListInputV2, ProviderAsyncJobSnapshotV2, ProviderAsyncJobAdapterFactory, ProviderAcceptanceFacts, ProviderAdapterFactory, ProviderDispatchTargetV2, ProviderResponseMetadata, ProviderTransport, TaskEnvelopeV2 } from '@skyold/model-protocol';
+import type { AdapterTerminalOutcome, NormalizedStreamEventV1, PreparedMediaExecutionInputV2, ProtocolFamily, ProviderAsyncJobListInputV2, ProviderAsyncJobSnapshotV2, ProviderAsyncJobAdapterFactory, ProviderAcceptanceFacts, ProviderAdapterFactory, ProviderDispatchTargetV2, ProviderResponseMetadata, ProviderWireResponseV1, ProviderTransport, TaskEnvelopeV2 } from '@skyold/model-protocol';
 export declare const PROTOCOL_ENGINE_API_VERSION: "tokenforge-protocol-engine/v1";
 export type ProtocolEngineApiVersion = typeof PROTOCOL_ENGINE_API_VERSION;
 export type ProtocolEngineDispatchTargetV1 = ProviderDispatchTargetV2;
@@ -22,6 +22,7 @@ interface ProtocolEngineExecutionBaseV1 {
     readonly apiVersion: ProtocolEngineApiVersion;
     readonly acceptance: ProviderAcceptanceFacts;
     readonly responseMetadata: ProviderResponseMetadata;
+    readonly providerResponse?: ProviderWireResponseV1;
 }
 export interface ProtocolEngineResponseV1 extends ProtocolEngineExecutionBaseV1 {
     readonly kind: 'response';
@@ -70,11 +71,13 @@ export interface ProtocolEngineAsyncJobObservationV1 {
 }
 export interface ProtocolEngineAsyncJobListResultV1 {
     readonly apiVersion: ProtocolEngineApiVersion;
+    readonly providerResponse?: ProviderWireResponseV1;
     readonly items: readonly ProviderAsyncJobSnapshotV2[];
     readonly total: number;
 }
 export interface ProtocolEngineAsyncJobCancellationV1 {
     readonly apiVersion: ProtocolEngineApiVersion;
+    readonly providerResponse?: ProviderWireResponseV1;
 }
 export interface ProtocolEngineAsyncJobsV1 {
     get(input: ProtocolEngineAsyncJobInputV1): Promise<ProtocolEngineAsyncJobObservationV1>;

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { providerCapabilityFromTarget, validateProviderDispatchInputV2, validateProviderAsyncJobList, validateProviderAsyncJobSnapshot, validateProviderAsyncJobStart, validateProviderExecutionStart, } from '@skyold/model-protocol';
+import { isProviderWireResponseErrorV1, providerCapabilityFromTarget, validateProviderDispatchInputV2, validateProviderAsyncJobList, validateProviderAsyncJobSnapshot, validateProviderAsyncJobStart, validateProviderExecutionStart, validateProviderWireResponseV1, } from '@skyold/model-protocol';
 import { PROTOCOL_ENGINE_API_VERSION, } from './contracts.js';
 import { PROTOCOL_ENGINE_ERROR_CODES_V1, ProtocolEngineErrorV1, isProtocolEngineErrorV1, } from './errors.js';
 export function createProtocolEngineV1(input) {
@@ -28,14 +28,23 @@ export function createProtocolEngineV1(input) {
                 const result = validateAdapterOutput(() => validateProviderAsyncJobList(adapterResult));
                 return {
                     apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                    ...(result.providerResponse === undefined
+                        ? {}
+                        : { providerResponse: result.providerResponse }),
                     items: result.items,
                     total: result.total,
                 };
             },
             async cancel(jobInput) {
                 const adapter = await bindAsyncJobAdapter(input.registry, jobInput.binding, jobInput.signal, protocolFamilies, 'cancel');
-                await callAdapter(() => adapter.cancel(jobInput.providerJobId, jobInput.signal), jobInput.signal);
-                return { apiVersion: PROTOCOL_ENGINE_API_VERSION };
+                const adapterResult = await callAdapter(() => adapter.cancel(jobInput.providerJobId, jobInput.signal), jobInput.signal);
+                const providerResponse = adapterResult === undefined
+                    ? undefined
+                    : validateAdapterOutput(() => validateProviderWireResponseV1(adapterResult));
+                return {
+                    apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                    ...(providerResponse === undefined ? {} : { providerResponse }),
+                };
             },
         },
         async execute(executionInput) {
@@ -76,6 +85,9 @@ export function createProtocolEngineV1(input) {
                     kind: 'response',
                     acceptance: started.acceptance,
                     responseMetadata: started.responseMetadata,
+                    ...(started.providerResponse === undefined
+                        ? {}
+                        : { providerResponse: started.providerResponse }),
                     terminal: started.terminal,
                 };
                 return result;
@@ -180,6 +192,9 @@ async function executeAsync(registry, executionInput, binding, capability) {
             kind: 'accepted-job',
             acceptance: started.acceptance,
             responseMetadata: started.responseMetadata,
+            ...(started.providerResponse === undefined
+                ? {}
+                : { providerResponse: started.providerResponse }),
             providerJobId: started.providerJobId,
         };
     }
@@ -188,6 +203,9 @@ async function executeAsync(registry, executionInput, binding, capability) {
         kind: 'rejected',
         acceptance: started.acceptance,
         responseMetadata: started.responseMetadata,
+        ...(started.providerResponse === undefined
+            ? {}
+            : { providerResponse: started.providerResponse }),
         failureCode: started.failureCode,
         retryable: started.retryable,
     };
@@ -298,20 +316,44 @@ function abortAdapter(abort, reason) {
 }
 function wrapOperationError(code, cause, signal) {
     if (isProtocolEngineErrorV1(cause))
-        return cause;
+        return validateProtocolEngineError(cause);
     if (signal.aborted || (cause instanceof Error && cause.name === 'AbortError')) {
         return wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ABORTED, cause);
     }
+    if (isProviderWireResponseErrorV1(cause)) {
+        try {
+            const providerResponse = validateProviderWireResponseV1(cause.providerResponse);
+            return new ProtocolEngineErrorV1(code, { cause, providerResponse });
+        }
+        catch (validationCause) {
+            return wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID, validationCause, adapterOutputCompatibilityMessage(validationCause));
+        }
+    }
     return wrapProtocolEngineError(code, cause);
 }
 function wrapProtocolEngineError(code, cause, compatibilityMessage) {
     if (isProtocolEngineErrorV1(cause))
-        return cause;
+        return validateProtocolEngineError(cause);
     return new ProtocolEngineErrorV1(code, {
         cause,
         ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
     });
 }
+function validateProtocolEngineError(cause) {
+    if (cause.providerResponse === undefined)
+        return cause;
+    try {
+        validateProviderWireResponseV1(cause.providerResponse);
+        return cause;
+    }
+    catch (validationCause) {
+        const compatibilityMessage = adapterOutputCompatibilityMessage(validationCause);
+        return new ProtocolEngineErrorV1(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID, {
+            cause: validationCause,
+            ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
+        });
+    }
+}
 function protocolEngineError(code, compatibilityMessage) {
     return new ProtocolEngineErrorV1(code, {
         ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
@@ -339,6 +381,7 @@ const ADAPTER_OUTPUT_COMPATIBILITY_MESSAGES = new Set([
     'ADAPTER_ASYNC_START_INVALID',
     'ADAPTER_ASYNC_JOB_SNAPSHOT_INVALID',
     'ADAPTER_ASYNC_JOB_LIST_INVALID',
+    'ADAPTER_PROVIDER_RESPONSE_INVALID',
 ]);
 function inputCompatibilityMessage(cause) {
     return cause instanceof Error && INPUT_COMPATIBILITY_MESSAGES.has(cause.message)

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import { type ProtocolEngineApiVersion } from './contracts.js';
+import type { ProviderWireResponseV1 } from '@skyold/model-protocol';
 export declare const PROTOCOL_ENGINE_ERROR_CODES_V1: Readonly<{
     readonly REGISTRY_INVALID: "PROTOCOL_ENGINE_REGISTRY_INVALID";
     readonly PROTOCOL_FAMILY_UNAVAILABLE: "PROTOCOL_ENGINE_PROTOCOL_FAMILY_UNAVAILABLE";
@@ -17,6 +18,8 @@ export type ProtocolEngineErrorPhaseV1 = 'configuration' | 'input' | 'transport'
 export interface ProtocolEngineErrorOptionsV1 {
     /** Internal diagnostic cause. Hosts must never serialize it to clients. */
     readonly cause?: unknown;
+    /** Complete Provider response available for explicit same-protocol Host egress. */
+    readonly providerResponse?: ProviderWireResponseV1;
     /**
      * Temporary compatibility message for Hosts that still classify historical
      * fixed-runtime failures by Error.message. New integrations must use code.
@@ -33,6 +36,7 @@ export declare class ProtocolEngineErrorV1 extends Error {
     readonly apiVersion: ProtocolEngineApiVersion;
     readonly code: ProtocolEngineErrorCodeV1;
     readonly phase: ProtocolEngineErrorPhaseV1;
+    readonly providerResponse?: ProviderWireResponseV1;
     constructor(code: ProtocolEngineErrorCodeV1, options?: ProtocolEngineErrorOptionsV1);
 }
 export declare function isProtocolEngineErrorV1(error: unknown): error is ProtocolEngineErrorV1;

package/dist/errors.js

@@ -22,11 +22,15 @@ export class ProtocolEngineErrorV1 extends Error {
     apiVersion = PROTOCOL_ENGINE_API_VERSION;
     code;
     phase;
+    providerResponse;
     constructor(code, options = {}) {
         super(options.compatibilityMessage ?? code, { cause: options.cause });
         this.name = 'ProtocolEngineErrorV1';
         this.code = code;
         this.phase = phaseForCode(code);
+        if (options.providerResponse !== undefined) {
+            this.providerResponse = options.providerResponse;
+        }
     }
 }
 export function isProtocolEngineErrorV1(error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyold/protocol-engine",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "description": "Host-neutral execution kernel for normalized AI provider protocols.",
   "license": "Apache-2.0",
   "type": "module",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@skyold/model-protocol": "^0.1.0-beta.0"
+    "@skyold/model-protocol": "^0.1.0-beta.1"
   },
   "devDependencies": {
     "@types/node": "22.19.19",