@agentplat/runtime 0.3.0-beta.2 → 0.3.0-beta.4

package/dist/cognitive-adapter.js

@@ -0,0 +1,813 @@
+import { PortableAgentErrorV1 } from "./adapter-errors.js";
+import { normalizeAdapterManifestV1 } from "./adapter-validation.js";
+export const COGNITIVE_AGENT_ADAPTER_SCHEMA_VERSION_V2 = 2;
+export const COGNITIVE_OPERATION_KINDS_V2 = Object.freeze([
+    "observe",
+    "plan",
+    "memory_query",
+    "memory_mutation",
+    "tool",
+    "alignment",
+    "intervention",
+]);
+export const COGNITIVE_EFFECTFUL_OPERATION_KINDS_V2 = Object.freeze([
+    "memory_mutation",
+    "tool",
+]);
+export class InMemoryCognitiveSessionStateStoreV2 {
+    #states = new Map();
+    #operations = new Map();
+    #revisionClaims = new Map();
+    async load(sessionId) {
+        const state = this.#states.get(sessionId);
+        return state ? immutable(state) : null;
+    }
+    async save(state, expectedRevision) {
+        const current = this.#states.get(state.sessionId);
+        if (expectedRevision !== null &&
+            this.#revisionClaims.has(durableRevisionKey(state.tenantId, state.sessionId, expectedRevision)))
+            return false;
+        if ((expectedRevision === null &&
+            (current !== undefined || state.revision !== 0)) ||
+            (expectedRevision !== null &&
+                (!current ||
+                    current.revision !== expectedRevision ||
+                    state.revision !== expectedRevision + 1)))
+            return false;
+        this.#states.set(state.sessionId, immutable(state));
+        return true;
+    }
+    async loadOperation(input) {
+        const operation = this.#operations.get(durableOperationKey(input.tenantId, input.sessionId, input.operationId));
+        return operation ? immutable(operation) : null;
+    }
+    async prepareOperation(input) {
+        const operation = input.operation;
+        const operationKey = durableOperationKey(operation.tenantId, operation.sessionId, operation.operationId);
+        const revisionKey = durableRevisionKey(operation.tenantId, operation.sessionId, operation.expectedSessionRevision);
+        const current = this.#states.get(operation.sessionId);
+        if (this.#operations.has(operationKey) ||
+            this.#revisionClaims.has(revisionKey) ||
+            !current ||
+            current.tenantId !== operation.tenantId ||
+            current.agentId !== operation.agentId ||
+            current.revision !== operation.expectedSessionRevision ||
+            current.stateDigest !== operation.previousStateDigest)
+            return false;
+        this.#operations.set(operationKey, immutable(operation));
+        this.#revisionClaims.set(revisionKey, operationKey);
+        return true;
+    }
+    async commitOperation(input) {
+        const operation = input.operation;
+        const operationKey = durableOperationKey(operation.tenantId, operation.sessionId, operation.operationId);
+        const revisionKey = durableRevisionKey(operation.tenantId, operation.sessionId, operation.expectedSessionRevision);
+        const prepared = this.#operations.get(operationKey);
+        const current = this.#states.get(operation.sessionId);
+        const outcome = operation.outcome;
+        if (input.expectedOperationRevision !== 0 ||
+            !prepared ||
+            prepared.status !== "prepared" ||
+            prepared.journalRevision !== input.expectedOperationRevision ||
+            !sameDurableOperationIdentity(prepared, operation) ||
+            this.#revisionClaims.get(revisionKey) !== operationKey ||
+            !current ||
+            current.tenantId !== operation.tenantId ||
+            current.agentId !== operation.agentId ||
+            current.revision !== operation.expectedSessionRevision ||
+            current.stateDigest !== operation.previousStateDigest ||
+            outcome.state.tenantId !== operation.tenantId ||
+            outcome.state.sessionId !== operation.sessionId ||
+            outcome.state.agentId !== operation.agentId ||
+            outcome.state.revision !== operation.expectedSessionRevision + 1 ||
+            outcome.receipt.operationId !== operation.operationId ||
+            outcome.receipt.previousStateDigest !== current.stateDigest ||
+            outcome.result.operationId !== operation.operationId ||
+            outcome.state.receipts.at(-1)?.receiptDigest !==
+                outcome.receipt.receiptDigest)
+            return false;
+        this.#states.set(operation.sessionId, immutable(outcome.state));
+        this.#operations.set(operationKey, immutable(operation));
+        return true;
+    }
+}
+/**
+ * Revision-checked cognitive operation host. It serializes no hidden reasoning,
+ * bounds session receipts, and uses a separate durable outcome journal only for
+ * adapters that advertise effectful operations.
+ */
+export class CognitiveAgentRuntimeV2 {
+    #adapter;
+    #guard;
+    #integrity;
+    #store;
+    #durableStore;
+    #effectSink;
+    #maximumCommitAttempts;
+    #activeSessions = new Set();
+    constructor(options) {
+        validateManifest(options.adapter?.manifest);
+        if (!options.adapter.portable ||
+            typeof options.adapter.execute !== "function")
+            invalid("cognitive adapter implementation is required");
+        if (!options.guard || typeof options.guard.authorize !== "function")
+            invalid("cognitive operation guard is required");
+        this.#adapter = options.adapter;
+        this.#guard = options.guard;
+        this.#integrity =
+            options.integrity ?? createWebCryptoCognitiveIntegrityV2();
+        this.#store = options.store ?? new InMemoryCognitiveSessionStateStoreV2();
+        const effectCapable = options.adapter.manifest.operations.some((operation) => COGNITIVE_EFFECTFUL_OPERATION_KINDS_V2.includes(operation));
+        if (effectCapable) {
+            if (!options.store || !durableOperationStore(options.store))
+                throw new PortableAgentErrorV1("ADAPTER_INCOMPATIBLE", "effectful cognitive operations require an explicit durable operation store");
+            if (options.adapter.effectSink?.protocol !== "idempotent_effect_sink_v2" ||
+                typeof options.adapter.effectSink.lookup !== "function" ||
+                typeof options.adapter.effectSink.apply !== "function")
+                throw new PortableAgentErrorV1("ADAPTER_INCOMPATIBLE", "effectful cognitive operations require an idempotent effect sink with lookup");
+            this.#durableStore = options.store;
+            this.#effectSink = options.adapter.effectSink;
+        }
+        else {
+            this.#durableStore = null;
+            this.#effectSink = null;
+        }
+        this.#maximumCommitAttempts = boundedInteger(options.maximumCommitAttempts ?? 4, "maximumCommitAttempts", 1, 32);
+    }
+    async createSession(input) {
+        identifier(input.tenantId, "tenantId");
+        identifier(input.sessionId, "sessionId");
+        identifier(input.agentId, "agentId");
+        const manifest = this.#adapter.manifest;
+        const body = {
+            schemaVersion: 2,
+            tenantId: input.tenantId,
+            sessionId: input.sessionId,
+            agentId: input.agentId,
+            adapterId: manifest.adapterId,
+            adapterVersion: manifest.adapterVersion,
+            implementationId: manifest.implementationId,
+            revision: 0,
+            logicalTimeHighWaterMs: 0,
+            receipts: [],
+        };
+        const state = immutable({
+            ...body,
+            stateDigest: await this.#integrity.digest("cognitive-session-state-v2", body),
+        });
+        if (!(await this.#store.save(state, null)))
+            throw new PortableAgentErrorV1("STATE_CONFLICT", "cognitive session exists");
+        return state;
+    }
+    async getSession(sessionId) {
+        identifier(sessionId, "sessionId");
+        const state = await this.#store.load(sessionId);
+        return state === null
+            ? null
+            : validateCognitiveSessionStateV2(state, this.#integrity, this.#adapter.manifest.maximumReceiptHistory);
+    }
+    async execute(requestInput, context) {
+        const request = await this.#validateRequest(requestInput);
+        if (context.tenant.tenantId !== request.tenantId)
+            invalid("tenant context does not match cognitive operation");
+        if (context.signal.aborted)
+            throw new PortableAgentErrorV1("CONFLICT", "operation aborted");
+        if (this.#activeSessions.has(request.sessionId))
+            throw new PortableAgentErrorV1("STATE_CONFLICT", "session operation is already active");
+        this.#activeSessions.add(request.sessionId);
+        try {
+            return this.#durableStore
+                ? await this.#executeDurably(request, context, this.#durableStore)
+                : await this.#executeDirectly(request, context);
+        }
+        finally {
+            this.#activeSessions.delete(request.sessionId);
+        }
+    }
+    async #executeDirectly(request, context) {
+        const current = await this.#currentSession(request);
+        if (current.receipts.some((item) => item.operationId === request.operationId))
+            throw new PortableAgentErrorV1("STATE_CONFLICT", "operation identifier was already committed");
+        this.#assertRequestPosition(current, request);
+        await this.#authorize(request);
+        const result = await this.#adapter.execute(request, context);
+        await this.#validateResult(request, result);
+        const outcome = await this.#createOutcome(current, request, result);
+        for (let attempt = 0; attempt < this.#maximumCommitAttempts; attempt += 1)
+            if (await this.#store.save(outcome.state, current.revision))
+                return outcome;
+        throw new PortableAgentErrorV1("STATE_CONFLICT", "commit attempts exhausted");
+    }
+    async #executeDurably(request, context, store) {
+        const requestDigest = await this.#requestDigest(request);
+        const idempotencyKey = await this.#integrity.digest("cognitive-effect-idempotency-v2", {
+            tenantId: request.tenantId,
+            sessionId: request.sessionId,
+            operationId: request.operationId,
+        });
+        for (let attempt = 0; attempt < this.#maximumCommitAttempts; attempt += 1) {
+            const existing = await store.loadOperation(request);
+            if (existing) {
+                const operation = await this.#validatedDurableOperation(existing, request, requestDigest, idempotencyKey);
+                if (operation.status === "applied")
+                    return this.#replayedOutcome(request, operation.outcome);
+                return this.#resumePreparedOperation(request, context, store, operation);
+            }
+            const current = await this.#currentSession(request);
+            if (current.receipts.some((item) => item.operationId === request.operationId))
+                throw new PortableAgentErrorV1("STATE_INVALID", "committed operation is missing its durable journal record");
+            this.#assertRequestPosition(current, request);
+            await this.#authorize(request);
+            const preparedBody = {
+                schemaVersion: 2,
+                tenantId: request.tenantId,
+                sessionId: request.sessionId,
+                agentId: request.agentId,
+                operationId: request.operationId,
+                operation: request.operation,
+                adapterId: this.#adapter.manifest.adapterId,
+                adapterVersion: this.#adapter.manifest.adapterVersion,
+                implementationId: this.#adapter.manifest.implementationId,
+                requestDigest,
+                idempotencyKey,
+                expectedSessionRevision: request.expectedRevision,
+                previousStateDigest: current.stateDigest,
+                preparedAtLogicalMs: request.logicalTimeMs,
+                status: "prepared",
+                journalRevision: 0,
+                outcome: null,
+            };
+            const prepared = immutable({
+                ...preparedBody,
+                recordDigest: await this.#integrity.digest("cognitive-durable-operation-v2", preparedBody),
+            });
+            if (await store.prepareOperation({ operation: prepared }))
+                return this.#resumePreparedOperation(request, context, store, prepared);
+        }
+        throw new PortableAgentErrorV1("STATE_CONFLICT", "durable operation reservation attempts exhausted");
+    }
+    async #resumePreparedOperation(request, context, store, prepared) {
+        const current = await this.#currentSession(request);
+        if (current.revision !== prepared.expectedSessionRevision ||
+            current.stateDigest !== prepared.previousStateDigest)
+            throw new PortableAgentErrorV1("STATE_CONFLICT", "prepared cognitive operation lost its session revision");
+        const effectful = COGNITIVE_EFFECTFUL_OPERATION_KINDS_V2.includes(request.operation);
+        let result;
+        if (effectful) {
+            const sink = this.#effectSink;
+            if (!sink)
+                throw new PortableAgentErrorV1("ADAPTER_INCOMPATIBLE", "effect sink is unavailable");
+            const invocation = immutable({
+                schemaVersion: 2,
+                idempotencyKey: prepared.idempotencyKey,
+                requestDigest: prepared.requestDigest,
+            });
+            const recovered = await sink.lookup({ request, invocation }, context);
+            if (recovered) {
+                result = recovered;
+            }
+            else {
+                if (context.signal.aborted)
+                    throw new PortableAgentErrorV1("CONFLICT", "operation aborted");
+                // A prepared claim can outlive the authority that created it. Recheck
+                // control immediately before starting an effect; reconciliation of an
+                // already-applied sink receipt remains allowed without a second effect.
+                await this.#authorize(request);
+                result = await sink.apply({ request, invocation }, context);
+            }
+        }
+        else {
+            await this.#authorize(request);
+            result = await this.#adapter.execute(request, context);
+        }
+        await this.#validateResult(request, result);
+        const outcome = await this.#createOutcome(current, request, result);
+        const { recordDigest: _preparedDigest, ...preparedBody } = prepared;
+        const appliedBody = {
+            ...preparedBody,
+            status: "applied",
+            journalRevision: 1,
+            outcome,
+        };
+        const applied = immutable({
+            ...appliedBody,
+            recordDigest: await this.#integrity.digest("cognitive-durable-operation-v2", appliedBody),
+        });
+        for (let attempt = 0; attempt < this.#maximumCommitAttempts; attempt += 1) {
+            if (await store.commitOperation({
+                operation: applied,
+                expectedOperationRevision: 0,
+            }))
+                return outcome;
+            const raced = await store.loadOperation(request);
+            if (raced) {
+                const validated = await this.#validatedDurableOperation(raced, request, prepared.requestDigest, prepared.idempotencyKey);
+                if (validated.status === "applied")
+                    return this.#replayedOutcome(request, validated.outcome);
+            }
+        }
+        throw new PortableAgentErrorV1("STATE_CONFLICT", "durable operation commit attempts exhausted");
+    }
+    async #createOutcome(current, request, result) {
+        const receiptBody = {
+            schemaVersion: 2,
+            operationId: request.operationId,
+            operation: request.operation,
+            sessionId: request.sessionId,
+            agentId: request.agentId,
+            revision: current.revision + 1,
+            logicalTimeMs: request.logicalTimeMs,
+            payloadDigest: request.payloadDigest,
+            metadataDigest: request.metadataDigest,
+            outputDigest: result.outputDigest,
+            authorityDigest: request.authorityDigest,
+            roleBindingDigest: request.roleBindingDigest,
+            ...(request.controlPlaneDigest === undefined
+                ? {}
+                : { controlPlaneDigest: request.controlPlaneDigest }),
+            implementationId: this.#adapter.manifest.implementationId,
+            status: result.status,
+            reasonCode: result.reasonCode,
+            controlSurface: result.controlSurface,
+            previousStateDigest: current.stateDigest,
+        };
+        const receipt = immutable({
+            ...receiptBody,
+            receiptDigest: await this.#integrity.digest("cognitive-operation-receipt-v2", receiptBody),
+        });
+        const retained = [...current.receipts, receipt].slice(-this.#adapter.manifest.maximumReceiptHistory);
+        const stateBody = {
+            ...current,
+            revision: current.revision + 1,
+            logicalTimeHighWaterMs: request.logicalTimeMs,
+            receipts: retained,
+        };
+        const { stateDigest: _priorDigest, ...digestable } = stateBody;
+        const state = immutable({
+            ...stateBody,
+            stateDigest: await this.#integrity.digest("cognitive-session-state-v2", digestable),
+        });
+        return immutable({ result, receipt, state });
+    }
+    async #currentSession(request) {
+        const current = await this.getSession(request.sessionId);
+        if (!current)
+            throw new PortableAgentErrorV1("NOT_FOUND", "session not found");
+        this.#assertBinding(current, request);
+        return current;
+    }
+    async #replayedOutcome(request, outcome) {
+        const current = await this.#currentSession(request);
+        if (current.revision < outcome.state.revision ||
+            (current.revision === outcome.state.revision &&
+                current.stateDigest !== outcome.state.stateDigest))
+            throw new PortableAgentErrorV1("STATE_INVALID", "durable cognitive operation and session state diverged");
+        return outcome;
+    }
+    #assertRequestPosition(current, request) {
+        if (current.revision !== request.expectedRevision)
+            throw new PortableAgentErrorV1("STATE_CONFLICT", "session revision conflict");
+        if (request.logicalTimeMs < current.logicalTimeHighWaterMs)
+            invalid("operation logical time is below the session high-water mark");
+    }
+    async #authorize(request) {
+        const authorization = await this.#guard.authorize({
+            manifest: this.#adapter.manifest,
+            request,
+        });
+        if (!authorization.allowed)
+            throw new PortableAgentErrorV1("CONTROL_DENIED", `cognitive operation denied: ${authorization.reasonCode}`);
+    }
+    async #requestDigest(request) {
+        const body = {
+            schemaVersion: request.schemaVersion,
+            operationId: request.operationId,
+            operation: request.operation,
+            tenantId: request.tenantId,
+            sessionId: request.sessionId,
+            agentId: request.agentId,
+            expectedRevision: request.expectedRevision,
+            logicalTimeMs: request.logicalTimeMs,
+            payloadDigest: request.payloadDigest,
+            metadataDigest: request.metadataDigest,
+            authorityDigest: request.authorityDigest,
+            roleBindingDigest: request.roleBindingDigest,
+            ...(request.controlPlaneDigest === undefined
+                ? {}
+                : { controlPlaneDigest: request.controlPlaneDigest }),
+        };
+        return this.#integrity.digest("cognitive-operation-request-v2", body);
+    }
+    async #validatedDurableOperation(input, request, requestDigest, idempotencyKey) {
+        if (!input || input.schemaVersion !== 2)
+            invalid("durable cognitive operation schema is invalid");
+        exactKeys(input, [
+            "adapterId",
+            "adapterVersion",
+            "agentId",
+            "expectedSessionRevision",
+            "idempotencyKey",
+            "implementationId",
+            "journalRevision",
+            "operation",
+            "operationId",
+            "outcome",
+            "preparedAtLogicalMs",
+            "previousStateDigest",
+            "recordDigest",
+            "requestDigest",
+            "schemaVersion",
+            "sessionId",
+            "status",
+            "tenantId",
+        ], "durable cognitive operation");
+        identifier(input.tenantId, "operation.tenantId");
+        identifier(input.sessionId, "operation.sessionId");
+        identifier(input.agentId, "operation.agentId");
+        identifier(input.operationId, "operation.operationId");
+        identifier(input.adapterId, "operation.adapterId");
+        token(input.adapterVersion, "operation.adapterVersion", 128);
+        identifier(input.implementationId, "operation.implementationId");
+        if (!COGNITIVE_OPERATION_KINDS_V2.includes(input.operation))
+            invalid("durable cognitive operation kind is invalid");
+        digest(input.requestDigest, "operation.requestDigest");
+        digest(input.idempotencyKey, "operation.idempotencyKey");
+        digest(input.previousStateDigest, "operation.previousStateDigest");
+        digest(input.recordDigest, "operation.recordDigest");
+        boundedInteger(input.expectedSessionRevision, "operation.expectedSessionRevision", 0, 1_000_000_000);
+        boundedInteger(input.preparedAtLogicalMs, "operation.preparedAtLogicalMs", 0, Number.MAX_SAFE_INTEGER);
+        const { recordDigest, ...body } = input;
+        if ((await this.#integrity.digest("cognitive-durable-operation-v2", body)) !== recordDigest)
+            invalid("durable cognitive operation digest is invalid");
+        if (input.tenantId !== request.tenantId ||
+            input.sessionId !== request.sessionId ||
+            input.operationId !== request.operationId ||
+            input.adapterId !== this.#adapter.manifest.adapterId ||
+            input.adapterVersion !== this.#adapter.manifest.adapterVersion ||
+            input.implementationId !== this.#adapter.manifest.implementationId ||
+            input.idempotencyKey !== idempotencyKey)
+            invalid("durable cognitive operation binding is invalid");
+        if (input.requestDigest !== requestDigest)
+            throw new PortableAgentErrorV1("STATE_CONFLICT", "operation identifier request digest conflicts with its reservation");
+        if (input.agentId !== request.agentId ||
+            input.operation !== request.operation ||
+            input.expectedSessionRevision !== request.expectedRevision ||
+            input.preparedAtLogicalMs !== request.logicalTimeMs)
+            invalid("durable cognitive operation request binding is invalid");
+        if (input.status === "prepared") {
+            if (input.journalRevision !== 0 || input.outcome !== null)
+                invalid("prepared cognitive operation state is invalid");
+            return immutable(input);
+        }
+        if (input.status !== "applied" ||
+            input.journalRevision !== 1 ||
+            !input.outcome)
+            invalid("applied cognitive operation state is invalid");
+        exactKeys(input.outcome, ["receipt", "result", "state"], "durable cognitive operation outcome");
+        await this.#validateResult(request, input.outcome.result);
+        const state = await validateCognitiveSessionStateV2(input.outcome.state, this.#integrity, this.#adapter.manifest.maximumReceiptHistory);
+        this.#assertBinding(state, request);
+        const receipt = input.outcome.receipt;
+        if (!receipt || receipt.schemaVersion !== 2)
+            invalid("durable cognitive operation receipt is invalid");
+        const { receiptDigest, ...receiptBody } = receipt;
+        if ((await this.#integrity.digest("cognitive-operation-receipt-v2", receiptBody)) !== receiptDigest)
+            invalid("durable cognitive operation receipt digest is invalid");
+        const retained = state.receipts.at(-1);
+        if (receipt.operationId !== request.operationId ||
+            receipt.operation !== request.operation ||
+            receipt.sessionId !== request.sessionId ||
+            receipt.agentId !== request.agentId ||
+            receipt.revision !== request.expectedRevision + 1 ||
+            receipt.logicalTimeMs !== request.logicalTimeMs ||
+            receipt.payloadDigest !== request.payloadDigest ||
+            receipt.metadataDigest !== request.metadataDigest ||
+            receipt.authorityDigest !== request.authorityDigest ||
+            receipt.roleBindingDigest !== request.roleBindingDigest ||
+            receipt.controlPlaneDigest !== request.controlPlaneDigest ||
+            receipt.implementationId !== this.#adapter.manifest.implementationId ||
+            receipt.outputDigest !== input.outcome.result.outputDigest ||
+            receipt.status !== input.outcome.result.status ||
+            receipt.reasonCode !== input.outcome.result.reasonCode ||
+            receipt.controlSurface !== input.outcome.result.controlSurface ||
+            receipt.previousStateDigest !== input.previousStateDigest ||
+            state.revision !== request.expectedRevision + 1 ||
+            retained?.receiptDigest !== receipt.receiptDigest)
+            invalid("applied cognitive operation outcome binding is invalid");
+        return immutable(input);
+    }
+    async #validateRequest(request) {
+        if (!request || request.schemaVersion !== 2)
+            invalid("request schema is invalid");
+        exactKeys(request, [
+            "agentId",
+            "authorityDigest",
+            ...(request.controlPlaneDigest === undefined
+                ? []
+                : ["controlPlaneDigest"]),
+            "expectedRevision",
+            "logicalTimeMs",
+            "metadata",
+            "metadataDigest",
+            "operation",
+            "operationId",
+            "payload",
+            "payloadDigest",
+            "roleBindingDigest",
+            "schemaVersion",
+            "sessionId",
+            "tenantId",
+        ], "cognitive operation request");
+        identifier(request.operationId, "operationId");
+        identifier(request.tenantId, "tenantId");
+        identifier(request.sessionId, "sessionId");
+        identifier(request.agentId, "agentId");
+        digest(request.payloadDigest, "payloadDigest");
+        digest(request.metadataDigest, "metadataDigest");
+        digest(request.authorityDigest, "authorityDigest");
+        digest(request.roleBindingDigest, "roleBindingDigest");
+        if (request.controlPlaneDigest !== undefined)
+            digest(request.controlPlaneDigest, "controlPlaneDigest");
+        boundedInteger(request.expectedRevision, "expectedRevision", 0, 1_000_000_000);
+        boundedInteger(request.logicalTimeMs, "logicalTimeMs", 0, Number.MAX_SAFE_INTEGER);
+        if (!COGNITIVE_OPERATION_KINDS_V2.includes(request.operation))
+            invalid("operation kind is unsupported");
+        if (!this.#adapter.manifest.operations.includes(request.operation))
+            throw new PortableAgentErrorV1("ADAPTER_INCOMPATIBLE", `adapter does not implement ${request.operation}`);
+        const encoded = `${canonicalJson(request.payload)}${canonicalJson(request.metadata)}`;
+        if (new TextEncoder().encode(encoded).byteLength >
+            this.#adapter.manifest.maximumOperationBytes)
+            invalid("operation payload exceeds adapter limit");
+        const actual = await this.#integrity.digest("cognitive-operation-payload-v2", request.payload);
+        if (actual !== request.payloadDigest)
+            invalid("operation payload digest mismatch");
+        const actualMetadata = await this.#integrity.digest("cognitive-operation-metadata-v2", request.metadata);
+        if (actualMetadata !== request.metadataDigest)
+            invalid("operation metadata digest mismatch");
+        return immutable(request);
+    }
+    async #validateResult(request, result) {
+        if (!result ||
+            result.schemaVersion !== 2 ||
+            result.operationId !== request.operationId)
+            invalid("adapter returned an invalid cognitive result");
+        exactKeys(result, [
+            "controlSurface",
+            "operationId",
+            "output",
+            "outputDigest",
+            "reasonCode",
+            "schemaVersion",
+            "status",
+        ], "cognitive operation result");
+        if (!["completed", "refused", "abstained", "failed"].includes(result.status))
+            invalid("cognitive result status is invalid");
+        token(result.reasonCode, "reasonCode", 160);
+        digest(result.outputDigest, "outputDigest");
+        if (result.controlSurface !== null &&
+            !this.#adapter.manifest.controlSurfaces.includes(result.controlSurface))
+            invalid("adapter returned an undeclared control surface");
+        if (new TextEncoder().encode(canonicalJson(result.output)).byteLength >
+            this.#adapter.manifest.maximumResultBytes)
+            invalid("cognitive result exceeds adapter limit");
+        const actual = await this.#integrity.digest("cognitive-operation-output-v2", result.output);
+        if (actual !== result.outputDigest)
+            invalid("cognitive result digest mismatch");
+    }
+    #assertBinding(state, request) {
+        const manifest = this.#adapter.manifest;
+        if (state.tenantId !== request.tenantId ||
+            state.agentId !== request.agentId ||
+            state.adapterId !== manifest.adapterId ||
+            state.adapterVersion !== manifest.adapterVersion ||
+            state.implementationId !== manifest.implementationId)
+            invalid("cognitive session binding mismatch");
+    }
+}
+export async function validateCognitiveSessionStateV2(input, integrity, maximumReceiptHistory) {
+    if (!input || input.schemaVersion !== 2)
+        invalid("cognitive session state schema is invalid");
+    if (!integrity || typeof integrity.digest !== "function")
+        invalid("cognitive integrity implementation is required");
+    identifier(input.tenantId, "state.tenantId");
+    identifier(input.sessionId, "state.sessionId");
+    identifier(input.agentId, "state.agentId");
+    identifier(input.adapterId, "state.adapterId");
+    token(input.adapterVersion, "state.adapterVersion", 128);
+    identifier(input.implementationId, "state.implementationId");
+    boundedInteger(input.revision, "state.revision", 0, 1_000_000_000);
+    boundedInteger(input.logicalTimeHighWaterMs, "state.logicalTimeHighWaterMs", 0, Number.MAX_SAFE_INTEGER);
+    boundedInteger(maximumReceiptHistory, "maximumReceiptHistory", 1, 100_000);
+    if (input.receipts.length > maximumReceiptHistory)
+        invalid("cognitive receipt retention exceeded");
+    const operationIds = new Set();
+    let prior = null;
+    for (const receipt of input.receipts) {
+        if (!receipt || receipt.schemaVersion !== 2)
+            invalid("cognitive receipt schema is invalid");
+        identifier(receipt.operationId, "receipt.operationId");
+        if (operationIds.has(receipt.operationId))
+            invalid("cognitive receipt operation is duplicated");
+        operationIds.add(receipt.operationId);
+        if (!COGNITIVE_OPERATION_KINDS_V2.includes(receipt.operation))
+            invalid("cognitive receipt operation is invalid");
+        identifier(receipt.sessionId, "receipt.sessionId");
+        identifier(receipt.agentId, "receipt.agentId");
+        if (receipt.sessionId !== input.sessionId ||
+            receipt.agentId !== input.agentId)
+            invalid("cognitive receipt session binding is invalid");
+        boundedInteger(receipt.revision, "receipt.revision", 1, input.revision);
+        boundedInteger(receipt.logicalTimeMs, "receipt.logicalTimeMs", 0, input.logicalTimeHighWaterMs);
+        for (const [label, value] of Object.entries({
+            payloadDigest: receipt.payloadDigest,
+            metadataDigest: receipt.metadataDigest,
+            outputDigest: receipt.outputDigest,
+            authorityDigest: receipt.authorityDigest,
+            roleBindingDigest: receipt.roleBindingDigest,
+            previousStateDigest: receipt.previousStateDigest,
+            receiptDigest: receipt.receiptDigest,
+        }))
+            digest(value, label);
+        if (receipt.controlPlaneDigest !== undefined)
+            digest(receipt.controlPlaneDigest, "controlPlaneDigest");
+        identifier(receipt.implementationId, "receipt.implementationId");
+        if (receipt.implementationId !== input.implementationId)
+            invalid("cognitive receipt implementation binding is invalid");
+        if (!["completed", "refused", "abstained", "failed"].includes(receipt.status))
+            invalid("cognitive receipt status is invalid");
+        token(receipt.reasonCode, "receipt.reasonCode", 160);
+        if (receipt.controlSurface !== null &&
+            ![
+                "context",
+                "memory",
+                "tool",
+                "output",
+                "action",
+                "representation",
+            ].includes(receipt.controlSurface))
+            invalid("cognitive receipt control surface is invalid");
+        if (prior &&
+            (receipt.revision !== prior.revision + 1 ||
+                receipt.logicalTimeMs < prior.logicalTimeMs))
+            invalid("cognitive receipt sequence is invalid");
+        const { receiptDigest, ...body } = receipt;
+        if ((await integrity.digest("cognitive-operation-receipt-v2", body)) !== receiptDigest)
+            invalid("cognitive receipt digest is invalid");
+        prior = receipt;
+    }
+    if ((input.revision === 0) !== (input.receipts.length === 0) ||
+        (prior !== null && prior.revision !== input.revision))
+        invalid("cognitive session revision and receipts differ");
+    const { stateDigest, ...body } = input;
+    digest(stateDigest, "stateDigest");
+    if ((await integrity.digest("cognitive-session-state-v2", body)) !== stateDigest)
+        invalid("cognitive session state digest is invalid");
+    return immutable(input);
+}
+export async function createCognitiveOperationRequestV2(input, integrity = createWebCryptoCognitiveIntegrityV2()) {
+    if (!integrity || typeof integrity.digest !== "function")
+        invalid("cognitive integrity implementation is required");
+    return immutable({
+        ...input,
+        payloadDigest: await integrity.digest("cognitive-operation-payload-v2", input.payload),
+        metadataDigest: await integrity.digest("cognitive-operation-metadata-v2", input.metadata),
+    });
+}
+export function createWebCryptoCognitiveIntegrityV2() {
+    return Object.freeze({
+        async digest(domain, value) {
+            token(domain, "digest domain", 160);
+            if (!globalThis.crypto?.subtle)
+                throw new PortableAgentErrorV1("ADAPTER_INCOMPATIBLE", "Web Crypto SHA-256 is unavailable");
+            const material = new TextEncoder().encode(`${domain}\u0000${canonicalJson(value)}`);
+            const hashed = await globalThis.crypto.subtle.digest("SHA-256", material);
+            return `sha256:${[...new Uint8Array(hashed)]
+                .map((byte) => byte.toString(16).padStart(2, "0"))
+                .join("")}`;
+        },
+    });
+}
+function validateManifest(manifest) {
+    if (!manifest || manifest.schemaVersion !== 2)
+        invalid("cognitive manifest is invalid");
+    identifier(manifest.adapterId, "adapterId");
+    token(manifest.adapterVersion, "adapterVersion", 128);
+    identifier(manifest.implementationId, "implementationId");
+    normalizeAdapterManifestV1(manifest.portable);
+    if (manifest.portable.adapterId !== manifest.adapterId ||
+        manifest.portable.adapterVersion !== manifest.adapterVersion ||
+        manifest.portable.implementationId !== manifest.implementationId)
+        invalid("portable and cognitive manifests are not bound to one implementation");
+    canonicalUnique(manifest.operations, COGNITIVE_OPERATION_KINDS_V2, "operations");
+    canonicalUnique(manifest.controlSurfaces, [
+        "context",
+        "memory",
+        "tool",
+        "output",
+        "action",
+        "representation",
+    ], "controlSurfaces");
+    boundedInteger(manifest.maximumOperationBytes, "maximumOperationBytes", 1_024, 67_108_864);
+    boundedInteger(manifest.maximumResultBytes, "maximumResultBytes", 1_024, 67_108_864);
+    boundedInteger(manifest.maximumReceiptHistory, "maximumReceiptHistory", 1, 100_000);
+    if (typeof manifest.supportsBlackBoxControl !== "boolean" ||
+        typeof manifest.supportsRepresentationControl !== "boolean" ||
+        typeof manifest.supportsMultimodalState !== "boolean")
+        invalid("cognitive manifest support flags are invalid");
+    if (manifest.supportsBlackBoxControl &&
+        !manifest.controlSurfaces.some((item) => ["context", "memory", "tool"].includes(item)))
+        invalid("black-box control requires a declared black-box surface");
+    if (manifest.supportsRepresentationControl &&
+        !manifest.controlSurfaces.includes("representation"))
+        invalid("representation control requires the representation surface");
+}
+function canonicalUnique(values, allowed, label) {
+    if (!Array.isArray(values) ||
+        values.length === 0 ||
+        values.length > allowed.length)
+        invalid(`${label} are invalid`);
+    const normalized = [...new Set(values)].sort();
+    if (normalized.length !== values.length ||
+        normalized.some((value, index) => value !== values[index]) ||
+        normalized.some((value) => !allowed.includes(value)))
+        invalid(`${label} must be canonical, unique and supported`);
+}
+function identifier(value, label) {
+    if (typeof value !== "string" ||
+        !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,239}$/.test(value))
+        invalid(`${label} is invalid`);
+}
+function token(value, label, maximum) {
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        value.length > maximum ||
+        /[\u0000-\u001f]/u.test(value))
+        invalid(`${label} is invalid`);
+}
+function digest(value, label) {
+    if (typeof value !== "string" || !/^sha256:[a-f0-9]{64}$/.test(value))
+        invalid(`${label} must be a SHA-256 digest`);
+}
+function boundedInteger(value, label, minimum, maximum) {
+    if (!Number.isSafeInteger(value) ||
+        value < minimum ||
+        value > maximum)
+        invalid(`${label} is outside its supported range`);
+    return value;
+}
+function exactKeys(value, keys, label) {
+    if (Object.keys(value).sort().join("\u0000") !== [...keys].sort().join("\u0000"))
+        invalid(`${label} has unsupported fields`);
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+        .join(",")}}`;
+}
+function durableOperationStore(value) {
+    const candidate = value;
+    return (typeof candidate.loadOperation === "function" &&
+        typeof candidate.prepareOperation === "function" &&
+        typeof candidate.commitOperation === "function");
+}
+function durableOperationKey(tenantId, sessionId, operationId) {
+    return `${tenantId}\u0000${sessionId}\u0000${operationId}`;
+}
+function durableRevisionKey(tenantId, sessionId, revision) {
+    return `${tenantId}\u0000${sessionId}\u0000${revision}`;
+}
+function sameDurableOperationIdentity(prepared, applied) {
+    return (prepared.tenantId === applied.tenantId &&
+        prepared.sessionId === applied.sessionId &&
+        prepared.agentId === applied.agentId &&
+        prepared.operationId === applied.operationId &&
+        prepared.operation === applied.operation &&
+        prepared.adapterId === applied.adapterId &&
+        prepared.adapterVersion === applied.adapterVersion &&
+        prepared.implementationId === applied.implementationId &&
+        prepared.requestDigest === applied.requestDigest &&
+        prepared.idempotencyKey === applied.idempotencyKey &&
+        prepared.expectedSessionRevision === applied.expectedSessionRevision &&
+        prepared.previousStateDigest === applied.previousStateDigest &&
+        prepared.preparedAtLogicalMs === applied.preparedAtLogicalMs);
+}
+function immutable(value) {
+    return deepFreeze(structuredClone(value));
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreeze(item);
+    }
+    return value;
+}
+function invalid(message) {
+    throw new PortableAgentErrorV1("STATE_INVALID", message);
+}
+//# sourceMappingURL=cognitive-adapter.js.map