@skyold/protocol-engine 0.1.0-beta.0

package/dist/engine.js

@@ -0,0 +1,352 @@
+import { providerCapabilityFromTarget, validateProviderDispatchInputV2, validateProviderAsyncJobList, validateProviderAsyncJobSnapshot, validateProviderAsyncJobStart, validateProviderExecutionStart, } 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) {
+    const protocolFamilies = protocolFamilyInventory(input.registry);
+    return {
+        apiVersion: PROTOCOL_ENGINE_API_VERSION,
+        protocolFamilies,
+        jobs: {
+            async get(jobInput) {
+                const adapter = await bindAsyncJobAdapter(input.registry, jobInput.binding, jobInput.signal, protocolFamilies, 'get');
+                const snapshot = await callAdapter(() => adapter.get(jobInput.providerJobId, jobInput.signal), jobInput.signal);
+                return {
+                    apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                    snapshot: validateAdapterOutput(() => validateProviderAsyncJobSnapshot(snapshot)),
+                };
+            },
+            async list(jobInput) {
+                const adapter = await bindAsyncJobAdapter(input.registry, jobInput.binding, jobInput.signal, protocolFamilies, 'list');
+                const adapterResult = await callAdapter(() => adapter.list({
+                    pageNum: jobInput.pageNum,
+                    pageSize: jobInput.pageSize,
+                    ...(jobInput.status === undefined ? {} : { status: jobInput.status }),
+                    ...(jobInput.providerJobIds === undefined
+                        ? {}
+                        : { providerJobIds: jobInput.providerJobIds }),
+                }, jobInput.signal), jobInput.signal);
+                const result = validateAdapterOutput(() => validateProviderAsyncJobList(adapterResult));
+                return {
+                    apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                    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 };
+            },
+        },
+        async execute(executionInput) {
+            const binding = executionInput.binding;
+            const capability = validateEngineInput(() => providerCapabilityFromTarget(binding.target));
+            const fixedInput = {
+                task: executionInput.task,
+                capability,
+                target: binding.target,
+                signal: executionInput.signal,
+                ...(executionInput.preparedMedia === undefined
+                    ? {}
+                    : { preparedMedia: executionInput.preparedMedia }),
+            };
+            validateEngineInput(() => validateProviderDispatchInputV2(fixedInput));
+            assertProtocolFamilyDeclared(protocolFamilies, binding.target.capability.protocolFamily);
+            if (executionInput.task.executionMode === 'async') {
+                return executeAsync(input.registry, executionInput, binding, capability);
+            }
+            const factory = requireSyncAdapterFactory(input.registry, binding.target.capability.protocolFamily);
+            const transport = await bindTransport(binding, executionInput.signal);
+            const adapter = bindSyncAdapter(factory, binding, transport);
+            if (!adapterSupports(adapter.supports.bind(adapter), capability, executionInput.signal)) {
+                throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.CAPABILITY_UNSUPPORTED, 'PROVIDER_ADAPTER_UNSUPPORTED_CAPABILITY');
+            }
+            const adapterStart = await callAdapter(() => adapter.start({
+                task: executionInput.task,
+                capability,
+                signal: executionInput.signal,
+                ...(executionInput.preparedMedia === undefined
+                    ? {}
+                    : { preparedMedia: executionInput.preparedMedia }),
+            }), executionInput.signal);
+            const started = validateAdapterOutput(() => validateProviderExecutionStart(adapterStart, executionInput.task.taskKind));
+            if (started.kind === 'sync') {
+                const result = {
+                    apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                    kind: 'response',
+                    acceptance: started.acceptance,
+                    responseMetadata: started.responseMetadata,
+                    terminal: started.terminal,
+                };
+                return result;
+            }
+            return {
+                apiVersion: PROTOCOL_ENGINE_API_VERSION,
+                kind: 'stream',
+                acceptance: started.acceptance,
+                responseMetadata: started.responseMetadata,
+                events: mapStreamErrors(started.events, executionInput.signal),
+                terminal: mapStreamTerminalError(started.terminal, executionInput.signal),
+                abort: (reason) => abortAdapter((abortReason) => started.abort(abortReason), reason),
+            };
+        },
+    };
+}
+function protocolFamilyInventory(registry) {
+    const listed = requireRegistryFactory(() => [...registry.listProtocolFamilies()]);
+    if (listed.some((family) => !isProtocolFamily(family))) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.REGISTRY_INVALID, 'PROVIDER_ADAPTER_REGISTRY_INVALID_PROTOCOL_FAMILY');
+    }
+    if (new Set(listed).size !== listed.length) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.REGISTRY_INVALID, 'PROVIDER_ADAPTER_REGISTRY_DUPLICATE_PROTOCOL_FAMILY');
+    }
+    return Object.freeze(listed.sort());
+}
+function isProtocolFamily(value) {
+    return typeof value === 'string' && /^[^/\s]+\/v\d+$/u.test(value);
+}
+function assertProtocolFamilyDeclared(protocolFamilies, protocolFamily) {
+    if (!protocolFamilies.includes(protocolFamily)) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.PROTOCOL_FAMILY_UNAVAILABLE, 'PROVIDER_ADAPTER_REGISTRY_PROTOCOL_FAMILY_NOT_DECLARED');
+    }
+}
+function requireSyncAdapterFactory(registry, protocolFamily) {
+    const factory = requireRegistryFactory(() => registry.require(protocolFamily));
+    assertFactoryProtocolFamily(factory.protocolFamily, protocolFamily);
+    return factory;
+}
+function requireAsyncAdapterFactory(registry, protocolFamily) {
+    const factory = requireRegistryFactory(() => registry.requireAsync?.(protocolFamily));
+    if (!factory) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.PROTOCOL_FAMILY_UNAVAILABLE, 'PROVIDER_ASYNC_ADAPTER_NOT_CONFIGURED');
+    }
+    assertFactoryProtocolFamily(factory.protocolFamily, protocolFamily);
+    assertAsyncJobOperations(factory.jobOperations);
+    return factory;
+}
+const ASYNC_JOB_OPERATIONS = new Set(['get', 'list', 'cancel']);
+function assertAsyncJobOperations(operations) {
+    if (!Array.isArray(operations) ||
+        operations.some((operation) => !ASYNC_JOB_OPERATIONS.has(operation)) ||
+        new Set(operations).size !== operations.length) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.REGISTRY_INVALID, 'PROVIDER_ASYNC_ADAPTER_JOB_OPERATIONS_INVALID');
+    }
+}
+function assertFactoryProtocolFamily(factoryProtocolFamily, requestedProtocolFamily) {
+    if (factoryProtocolFamily !== requestedProtocolFamily) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.REGISTRY_INVALID, 'PROVIDER_ADAPTER_REGISTRY_FACTORY_PROTOCOL_FAMILY_MISMATCH');
+    }
+}
+async function bindAsyncJobAdapter(registry, binding, signal, protocolFamilies, operation) {
+    const capability = validateEngineInput(() => providerCapabilityFromTarget(binding.target));
+    const protocolFamily = capability.protocolFamily;
+    assertProtocolFamilyDeclared(protocolFamilies, protocolFamily);
+    if (!capability.executionModes.includes('async')) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ASYNC_TARGET_REQUIRED, 'PROVIDER_ASYNC_JOB_TARGET_REQUIRED');
+    }
+    const factory = requireAsyncAdapterFactory(registry, protocolFamily);
+    if (!factory.jobOperations.includes(operation)) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.CAPABILITY_UNSUPPORTED, 'PROVIDER_ASYNC_JOB_OPERATION_UNSUPPORTED');
+    }
+    const transport = await bindTransport(binding, signal);
+    const adapter = bindAsyncAdapter(factory, binding, transport);
+    if (!adapterSupports(adapter.supports.bind(adapter), capability, signal)) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.CAPABILITY_UNSUPPORTED, 'PROVIDER_ADAPTER_UNSUPPORTED_CAPABILITY');
+    }
+    return adapter;
+}
+async function executeAsync(registry, executionInput, binding, capability) {
+    const factory = requireAsyncAdapterFactory(registry, binding.target.capability.protocolFamily);
+    const transport = await bindTransport(binding, executionInput.signal);
+    const adapter = bindAsyncAdapter(factory, binding, transport);
+    if (!adapterSupports(adapter.supports.bind(adapter), capability, executionInput.signal)) {
+        throw protocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.CAPABILITY_UNSUPPORTED, 'PROVIDER_ADAPTER_UNSUPPORTED_CAPABILITY');
+    }
+    const adapterStart = await callAdapter(() => adapter.start({
+        task: executionInput.task,
+        capability,
+        signal: executionInput.signal,
+        ...(executionInput.preparedMedia === undefined
+            ? {}
+            : { preparedMedia: executionInput.preparedMedia }),
+        ...(executionInput.providerCallbackUrl === undefined
+            ? {}
+            : { providerCallbackUrl: executionInput.providerCallbackUrl }),
+    }), executionInput.signal);
+    const started = validateAdapterOutput(() => validateProviderAsyncJobStart(adapterStart));
+    if (started.kind === 'async') {
+        return {
+            apiVersion: PROTOCOL_ENGINE_API_VERSION,
+            kind: 'accepted-job',
+            acceptance: started.acceptance,
+            responseMetadata: started.responseMetadata,
+            providerJobId: started.providerJobId,
+        };
+    }
+    return {
+        apiVersion: PROTOCOL_ENGINE_API_VERSION,
+        kind: 'rejected',
+        acceptance: started.acceptance,
+        responseMetadata: started.responseMetadata,
+        failureCode: started.failureCode,
+        retryable: started.retryable,
+    };
+}
+function requireRegistryFactory(load) {
+    try {
+        return load();
+    }
+    catch (cause) {
+        throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.REGISTRY_INVALID, cause);
+    }
+}
+function bindSyncAdapter(factory, binding, transport) {
+    try {
+        return factory.bind({
+            providerModel: binding.target.providerModel,
+            dispatchProtocolFamily: binding.target.capability.protocolFamily,
+            transport,
+        });
+    }
+    catch (cause) {
+        throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_EXECUTION_FAILED, cause);
+    }
+}
+function bindAsyncAdapter(factory, binding, transport) {
+    try {
+        return factory.bind({
+            providerModel: binding.target.providerModel,
+            dispatchProtocolFamily: binding.target.capability.protocolFamily,
+            transport,
+        });
+    }
+    catch (cause) {
+        throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_EXECUTION_FAILED, cause);
+    }
+}
+async function bindTransport(binding, signal) {
+    try {
+        return await binding.bindTransport(binding.target.connectionRef, signal);
+    }
+    catch (cause) {
+        throw wrapOperationError(PROTOCOL_ENGINE_ERROR_CODES_V1.TRANSPORT_BIND_FAILED, cause, signal);
+    }
+}
+function adapterSupports(supports, capability, signal) {
+    try {
+        return supports(capability);
+    }
+    catch (cause) {
+        throw wrapOperationError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_EXECUTION_FAILED, cause, signal);
+    }
+}
+async function callAdapter(operation, signal) {
+    try {
+        return await operation();
+    }
+    catch (cause) {
+        throw wrapOperationError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_EXECUTION_FAILED, cause, signal);
+    }
+}
+function validateEngineInput(validation) {
+    try {
+        return validation();
+    }
+    catch (cause) {
+        throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.INPUT_INVALID, cause, inputCompatibilityMessage(cause));
+    }
+}
+function validateAdapterOutput(validation) {
+    try {
+        return validation();
+    }
+    catch (cause) {
+        throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID, cause, adapterOutputCompatibilityMessage(cause));
+    }
+}
+async function* mapStreamErrors(events, signal) {
+    try {
+        yield* events;
+    }
+    catch (cause) {
+        const compatibilityMessage = adapterOutputCompatibilityMessage(cause);
+        if (compatibilityMessage !== undefined) {
+            throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID, cause, compatibilityMessage);
+        }
+        throw wrapOperationError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_STREAM_FAILED, cause, signal);
+    }
+}
+async function mapStreamTerminalError(terminal, signal) {
+    try {
+        return await terminal;
+    }
+    catch (cause) {
+        const compatibilityMessage = adapterOutputCompatibilityMessage(cause);
+        if (compatibilityMessage !== undefined) {
+            throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID, cause, compatibilityMessage);
+        }
+        throw wrapOperationError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_STREAM_FAILED, cause, signal);
+    }
+}
+function abortAdapter(abort, reason) {
+    try {
+        abort(reason);
+    }
+    catch (cause) {
+        throw wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_EXECUTION_FAILED, cause);
+    }
+}
+function wrapOperationError(code, cause, signal) {
+    if (isProtocolEngineErrorV1(cause))
+        return cause;
+    if (signal.aborted || (cause instanceof Error && cause.name === 'AbortError')) {
+        return wrapProtocolEngineError(PROTOCOL_ENGINE_ERROR_CODES_V1.ABORTED, cause);
+    }
+    return wrapProtocolEngineError(code, cause);
+}
+function wrapProtocolEngineError(code, cause, compatibilityMessage) {
+    if (isProtocolEngineErrorV1(cause))
+        return cause;
+    return new ProtocolEngineErrorV1(code, {
+        cause,
+        ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
+    });
+}
+function protocolEngineError(code, compatibilityMessage) {
+    return new ProtocolEngineErrorV1(code, {
+        ...(compatibilityMessage === undefined ? {} : { compatibilityMessage }),
+    });
+}
+const INPUT_COMPATIBILITY_MESSAGES = new Set([
+    'CONNECTION_REF_REQUIRED',
+    'PROTOCOL_FAMILY_MISMATCH',
+    'CAPABILITY_PROTOCOL_MISMATCH',
+    'TARGET_CAPABILITY_MISMATCH',
+    'TASK_KIND_MISMATCH',
+    'EXECUTION_MODE_MISMATCH',
+    'INPUT_MODALITY_MISMATCH',
+    'OUTPUT_MODALITY_MISMATCH',
+]);
+const ADAPTER_OUTPUT_COMPATIBILITY_MESSAGES = new Set([
+    'ADAPTER_EXECUTION_START_INVALID',
+    'ADAPTER_STREAM_EVENT_INVALID',
+    'ADAPTER_TERMINAL_INVALID',
+    'ADAPTER_SUCCEEDED_WITHOUT_ACCEPTANCE',
+    'ADAPTER_TERMINAL_TASK_KIND_MISMATCH',
+    'ADAPTER_TERMINAL_USAGE_MISMATCH',
+    'ADAPTER_TERMINAL_RESPONSE_STATUS_MISMATCH',
+    'ADAPTER_ACCEPTANCE_MISMATCH',
+    'ADAPTER_ASYNC_START_INVALID',
+    'ADAPTER_ASYNC_JOB_SNAPSHOT_INVALID',
+    'ADAPTER_ASYNC_JOB_LIST_INVALID',
+]);
+function inputCompatibilityMessage(cause) {
+    return cause instanceof Error && INPUT_COMPATIBILITY_MESSAGES.has(cause.message)
+        ? cause.message
+        : undefined;
+}
+function adapterOutputCompatibilityMessage(cause) {
+    return cause instanceof Error && ADAPTER_OUTPUT_COMPATIBILITY_MESSAGES.has(cause.message)
+        ? cause.message
+        : undefined;
+}

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+import { type ProtocolEngineApiVersion } from './contracts.js';
+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";
+    readonly INPUT_INVALID: "PROTOCOL_ENGINE_INPUT_INVALID";
+    readonly CAPABILITY_UNSUPPORTED: "PROTOCOL_ENGINE_CAPABILITY_UNSUPPORTED";
+    readonly ASYNC_TARGET_REQUIRED: "PROTOCOL_ENGINE_ASYNC_TARGET_REQUIRED";
+    readonly CONNECTION_REF_MISMATCH: "PROTOCOL_ENGINE_CONNECTION_REF_MISMATCH";
+    readonly TRANSPORT_BIND_FAILED: "PROTOCOL_ENGINE_TRANSPORT_BIND_FAILED";
+    readonly ADAPTER_EXECUTION_FAILED: "PROTOCOL_ENGINE_ADAPTER_EXECUTION_FAILED";
+    readonly ADAPTER_OUTPUT_INVALID: "PROTOCOL_ENGINE_ADAPTER_OUTPUT_INVALID";
+    readonly ADAPTER_STREAM_FAILED: "PROTOCOL_ENGINE_ADAPTER_STREAM_FAILED";
+    readonly ABORTED: "PROTOCOL_ENGINE_ABORTED";
+}>;
+export type ProtocolEngineErrorCodeV1 = (typeof PROTOCOL_ENGINE_ERROR_CODES_V1)[keyof typeof PROTOCOL_ENGINE_ERROR_CODES_V1];
+export type ProtocolEngineErrorPhaseV1 = 'configuration' | 'input' | 'transport' | 'adapter' | 'lifecycle';
+export interface ProtocolEngineErrorOptionsV1 {
+    /** Internal diagnostic cause. Hosts must never serialize it to clients. */
+    readonly cause?: unknown;
+    /**
+     * Temporary compatibility message for Hosts that still classify historical
+     * fixed-runtime failures by Error.message. New integrations must use code.
+     */
+    readonly compatibilityMessage?: string;
+}
+/**
+ * Stable V1 failure surface for Engine operations.
+ *
+ * `code`, `phase`, and `apiVersion` are safe classification facts. `cause` is
+ * diagnostic-only and can contain Transport or Adapter details.
+ */
+export declare class ProtocolEngineErrorV1 extends Error {
+    readonly apiVersion: ProtocolEngineApiVersion;
+    readonly code: ProtocolEngineErrorCodeV1;
+    readonly phase: ProtocolEngineErrorPhaseV1;
+    constructor(code: ProtocolEngineErrorCodeV1, options?: ProtocolEngineErrorOptionsV1);
+}
+export declare function isProtocolEngineErrorV1(error: unknown): error is ProtocolEngineErrorV1;

package/dist/errors.js

@@ -0,0 +1,68 @@
+import { PROTOCOL_ENGINE_API_VERSION } from './contracts.js';
+export const PROTOCOL_ENGINE_ERROR_CODES_V1 = Object.freeze({
+    REGISTRY_INVALID: 'PROTOCOL_ENGINE_REGISTRY_INVALID',
+    PROTOCOL_FAMILY_UNAVAILABLE: 'PROTOCOL_ENGINE_PROTOCOL_FAMILY_UNAVAILABLE',
+    INPUT_INVALID: 'PROTOCOL_ENGINE_INPUT_INVALID',
+    CAPABILITY_UNSUPPORTED: 'PROTOCOL_ENGINE_CAPABILITY_UNSUPPORTED',
+    ASYNC_TARGET_REQUIRED: 'PROTOCOL_ENGINE_ASYNC_TARGET_REQUIRED',
+    CONNECTION_REF_MISMATCH: 'PROTOCOL_ENGINE_CONNECTION_REF_MISMATCH',
+    TRANSPORT_BIND_FAILED: 'PROTOCOL_ENGINE_TRANSPORT_BIND_FAILED',
+    ADAPTER_EXECUTION_FAILED: 'PROTOCOL_ENGINE_ADAPTER_EXECUTION_FAILED',
+    ADAPTER_OUTPUT_INVALID: 'PROTOCOL_ENGINE_ADAPTER_OUTPUT_INVALID',
+    ADAPTER_STREAM_FAILED: 'PROTOCOL_ENGINE_ADAPTER_STREAM_FAILED',
+    ABORTED: 'PROTOCOL_ENGINE_ABORTED',
+});
+/**
+ * Stable V1 failure surface for Engine operations.
+ *
+ * `code`, `phase`, and `apiVersion` are safe classification facts. `cause` is
+ * diagnostic-only and can contain Transport or Adapter details.
+ */
+export class ProtocolEngineErrorV1 extends Error {
+    apiVersion = PROTOCOL_ENGINE_API_VERSION;
+    code;
+    phase;
+    constructor(code, options = {}) {
+        super(options.compatibilityMessage ?? code, { cause: options.cause });
+        this.name = 'ProtocolEngineErrorV1';
+        this.code = code;
+        this.phase = phaseForCode(code);
+    }
+}
+export function isProtocolEngineErrorV1(error) {
+    const candidate = error;
+    return (error instanceof ProtocolEngineErrorV1 ||
+        (candidate instanceof Error &&
+            candidate.name === 'ProtocolEngineErrorV1' &&
+            candidate.apiVersion === PROTOCOL_ENGINE_API_VERSION &&
+            typeof candidate.code === 'string' &&
+            isProtocolEngineErrorCodeV1(candidate.code) &&
+            typeof candidate.phase === 'string' &&
+            isProtocolEngineErrorPhaseV1(candidate.phase)));
+}
+function phaseForCode(code) {
+    switch (code) {
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.REGISTRY_INVALID:
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.PROTOCOL_FAMILY_UNAVAILABLE:
+            return 'configuration';
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.INPUT_INVALID:
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.CAPABILITY_UNSUPPORTED:
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.ASYNC_TARGET_REQUIRED:
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.CONNECTION_REF_MISMATCH:
+            return 'input';
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.TRANSPORT_BIND_FAILED:
+            return 'transport';
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_EXECUTION_FAILED:
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_OUTPUT_INVALID:
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.ADAPTER_STREAM_FAILED:
+            return 'adapter';
+        case PROTOCOL_ENGINE_ERROR_CODES_V1.ABORTED:
+            return 'lifecycle';
+    }
+}
+function isProtocolEngineErrorCodeV1(value) {
+    return Object.values(PROTOCOL_ENGINE_ERROR_CODES_V1).some((code) => code === value);
+}
+function isProtocolEngineErrorPhaseV1(value) {
+    return ['configuration', 'input', 'transport', 'adapter', 'lifecycle'].includes(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createProtocolEngineV1 } from './engine.js';
+export { PROTOCOL_ENGINE_ERROR_CODES_V1, ProtocolEngineErrorV1, isProtocolEngineErrorV1, type ProtocolEngineErrorCodeV1, type ProtocolEngineErrorOptionsV1, type ProtocolEngineErrorPhaseV1, } from './errors.js';
+export { createProtocolEngineTargetBindingV1, type CreateProtocolEngineTargetBindingInputV1, } from './target-binding.js';
+export { PROTOCOL_ENGINE_API_VERSION, type ProtocolEngineAcceptedJobV1, type ProtocolEngineAdapterRegistryPortV1, type ProtocolEngineApiVersion, type ProtocolEngineAsyncJobCancellationV1, type ProtocolEngineAsyncJobInputV1, type ProtocolEngineAsyncJobListRequestV1, type ProtocolEngineAsyncJobListResultV1, type ProtocolEngineAsyncJobObservationV1, type ProtocolEngineAsyncJobsV1, type ProtocolEngineDispatchTargetV1, type ProtocolEngineExecuteInputV1, type ProtocolEngineExecutionV1, type ProtocolEngineRejectedV1, type ProtocolEngineResponseV1, type ProtocolEngineStreamV1, type ProtocolEngineTargetBindingV1, type ProtocolEngineV1, } from './contracts.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createProtocolEngineV1 } from './engine.js';
+export { PROTOCOL_ENGINE_ERROR_CODES_V1, ProtocolEngineErrorV1, isProtocolEngineErrorV1, } from './errors.js';
+export { createProtocolEngineTargetBindingV1, } from './target-binding.js';
+export { PROTOCOL_ENGINE_API_VERSION, } from './contracts.js';

package/dist/target-binding.d.ts

@@ -0,0 +1,12 @@
+import type { ProviderTransport } from '@skyold/model-protocol';
+import type { ProtocolEngineDispatchTargetV1, ProtocolEngineTargetBindingV1 } from './contracts.js';
+export interface CreateProtocolEngineTargetBindingInputV1 {
+    readonly target: ProtocolEngineDispatchTargetV1;
+    readonly bindTransport: (signal: AbortSignal) => Promise<ProviderTransport> | ProviderTransport;
+}
+/**
+ * Builds the reusable Host-to-Engine binding and makes the target connection
+ * reference authoritative. Host policy supplies credentials and Transport;
+ * Engine callers cannot substitute a different connection reference.
+ */
+export declare function createProtocolEngineTargetBindingV1(input: CreateProtocolEngineTargetBindingInputV1): ProtocolEngineTargetBindingV1;

package/dist/target-binding.js

@@ -0,0 +1,29 @@
+import { PROTOCOL_ENGINE_ERROR_CODES_V1, ProtocolEngineErrorV1 } from './errors.js';
+/**
+ * Builds the reusable Host-to-Engine binding and makes the target connection
+ * reference authoritative. Host policy supplies credentials and Transport;
+ * Engine callers cannot substitute a different connection reference.
+ */
+export function createProtocolEngineTargetBindingV1(input) {
+    const target = immutableSnapshot(input.target);
+    const authoritativeConnectionRef = target.connectionRef;
+    const bindTransport = input.bindTransport;
+    return Object.freeze({
+        target,
+        async bindTransport(connectionRef, signal) {
+            if (connectionRef !== authoritativeConnectionRef) {
+                throw new ProtocolEngineErrorV1(PROTOCOL_ENGINE_ERROR_CODES_V1.CONNECTION_REF_MISMATCH);
+            }
+            return bindTransport(signal);
+        },
+    });
+}
+function immutableSnapshot(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map((item) => immutableSnapshot(item)));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, immutableSnapshot(item)])));
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@skyold/protocol-engine",
+  "version": "0.1.0-beta.0",
+  "description": "Host-neutral execution kernel for normalized AI provider protocols.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/contracts.d.ts",
+    "dist/contracts.js",
+    "dist/engine.d.ts",
+    "dist/engine.js",
+    "dist/errors.d.ts",
+    "dist/errors.js",
+    "dist/index.d.ts",
+    "dist/index.js",
+    "dist/target-binding.d.ts",
+    "dist/target-binding.js",
+    "README.zh-CN.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tokenforgegateway/tokenforge-protocol-engine.git",
+    "directory": "packages/protocol-engine"
+  },
+  "bugs": {
+    "url": "https://github.com/tokenforgegateway/tokenforge-protocol-engine/issues"
+  },
+  "homepage": "https://github.com/tokenforgegateway/tokenforge-protocol-engine#readme",
+  "keywords": [
+    "ai",
+    "llm",
+    "protocol",
+    "adapter",
+    "gateway",
+    "tokenforge"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@skyold/model-protocol": "^0.1.0-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "typescript": "5.9.3",
+    "vitest": "2.1.9"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "check": "pnpm build && pnpm test",
+    "test": "vitest run"
+  }
+}