@agilno-tech/rivet 0.1.0-alpha.0

package/src/models/protocols.js

@@ -0,0 +1,208 @@
+// Text-only wire protocols. Transport, authorization and cost policy belong to the runtime.
+const HOSTS = {
+  anthropic: 'https://api.anthropic.com',
+  openai: 'https://api.openai.com',
+  gemini: 'https://generativelanguage.googleapis.com',
+};
+function fail() {
+  const error = new Error('Model protocol input or response is unsupported or invalid.');
+  error.code = 'ERR_MODEL_PROTOCOL';
+  error.safeMessage = error.message;
+  throw error;
+}
+function ensure(value) { if (!value) fail(); }
+function snapshot(input) {
+  let nodes = 0;
+  const copy = (value, depth = 0) => {
+    ensure(++nodes <= 20000 && depth <= 24);
+    if (value === null || typeof value === 'boolean' || typeof value === 'string') return value;
+    if (typeof value === 'number') { ensure(Number.isFinite(value)); return value; }
+    ensure(value && typeof value === 'object');
+    const array = Array.isArray(value);
+    ensure(Object.getPrototypeOf(value) === (array ? Array.prototype : Object.prototype)
+      || (!array && Object.getPrototypeOf(value) === null));
+    const output = array ? [] : {};
+    if (array) ensure(value.length <= 20000 && Object.keys(value).length === value.length);
+    for (const key of Reflect.ownKeys(value)) {
+      if (array && key === 'length') continue;
+      ensure(typeof key === 'string' && !['__proto__', 'constructor', 'prototype'].includes(key));
+      if (array) ensure(/^(0|[1-9][0-9]*)$/.test(key) && Number(key) < value.length);
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      ensure(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+      output[key] = copy(descriptor.value, depth + 1);
+    }
+    return output;
+  };
+  const value = copy(input);
+  ensure(Buffer.byteLength(JSON.stringify(value)) <= 1024 * 1024);
+  return value;
+}
+function tokenCount(value) { ensure(Number.isSafeInteger(value) && value >= 0); return value; }
+function nonempty(value, maximum) {
+  ensure(typeof value === 'string' && value.trim().length > 0 && Buffer.byteLength(value) <= maximum);
+  return value;
+}
+function settings(input) {
+  const value = snapshot(input);
+  ensure(Object.keys(value).every(key => ['provider','model','endpoint','credentialEnv','timeoutMs','maxOutputTokens','maxCostUsd'].includes(key)));
+  ensure(['anthropic','openai','gemini','ollama','openai-compatible'].includes(value.provider));
+  nonempty(value.model, 800);
+  ensure(!/[\u0000-\u001f\u007f]/.test(value.model));
+  ensure(Number.isSafeInteger(value.maxOutputTokens) && value.maxOutputTokens > 0 && value.maxOutputTokens <= 1000000);
+  return value;
+}
+function baseUrl(profile) {
+  const base = HOSTS[profile.provider];
+  if (base) {
+    ensure(profile.endpoint === undefined || profile.endpoint === base || profile.endpoint === `${base}/`);
+    return base;
+  }
+  ensure(typeof profile.endpoint === 'string' && profile.endpoint.length <= 2048 && !/[\u0000-\u0020\u007f]/.test(profile.endpoint));
+  const url = new URL(profile.endpoint);
+  const local = ['127.0.0.1','localhost','[::1]'].includes(url.hostname);
+  ensure(!url.username && !url.password && !url.search && !url.hash);
+  ensure(url.protocol === 'https:' || (url.protocol === 'http:' && local));
+  if (profile.provider === 'ollama') ensure(local && url.pathname === '/');
+  return url.href.replace(/\/$/, '');
+}
+export function buildModelRequest(input, prompt, credential) {
+  try {
+    const profile = settings(input);
+    nonempty(prompt, 65536);
+    const base = baseUrl(profile);
+    const headers = { 'content-type': 'application/json' };
+    if (credential !== undefined) ensure(typeof credential === 'string' && credential.length > 0
+      && credential.length <= 8192 && !/[\u0000-\u0020\u007f]/.test(credential));
+    if (HOSTS[profile.provider]) ensure(credential !== undefined);
+    const { model, maxOutputTokens } = profile;
+    const messages = [{ role: 'user', content: prompt }];
+    let url; let body;
+    switch (profile.provider) {
+      case 'anthropic':
+        url = `${base}/v1/messages`;
+        Object.assign(headers, { 'x-api-key': credential, 'anthropic-version': '2023-06-01' });
+        body = { model, max_tokens: maxOutputTokens, messages };
+        break;
+      case 'openai':
+        url = `${base}/v1/responses`; headers.authorization = `Bearer ${credential}`;
+        body = { model, input: prompt, max_output_tokens: maxOutputTokens, store: false };
+        break;
+      case 'gemini':
+        url = `${base}/v1beta/models/${encodeURIComponent(model)}:generateContent`;
+        headers['x-goog-api-key'] = credential;
+        body = { contents: [{ role: 'user', parts: [{ text: prompt }] }], generationConfig: { maxOutputTokens } };
+        break;
+      case 'ollama':
+        url = `${base}/api/chat`;
+        body = { model, messages, stream: false, options: { num_predict: maxOutputTokens } };
+        break;
+      case 'openai-compatible':
+        url = `${base}/chat/completions`;
+        if (credential !== undefined) headers.authorization = `Bearer ${credential}`;
+        body = { model, messages, max_tokens: maxOutputTokens, stream: false };
+        break;
+    }
+    return { url, headers, body };
+  } catch { fail(); }
+}
+function fields(value, allowed) {
+  ensure(value && typeof value === 'object' && !Array.isArray(value));
+  ensure(Object.keys(value).every(key => allowed.includes(key)));
+}
+function noCalls(message) {
+  ensure(message && message.role === 'assistant');
+  ensure(message.tool_calls === undefined || (Array.isArray(message.tool_calls) && message.tool_calls.length === 0));
+  ensure(message.function_call === undefined || message.function_call === null);
+  ensure(message.refusal === undefined || message.refusal === null);
+}
+export function parseModelResponse(input, data) {
+  try {
+    const profile = settings(input);
+    const response = snapshot(data);
+    ensure(response && typeof response === 'object' && !Array.isArray(response) && !response.error);
+    let text; let model = response.model; let inputTokens; let outputTokens;
+    switch (profile.provider) {
+      case 'anthropic': {
+        ensure(response.type === 'message' && response.role === 'assistant' && response.stop_reason === 'end_turn');
+        ensure(Array.isArray(response.content) && response.content.length > 0);
+        text = response.content.map(part => {
+          fields(part, ['type','text','citations']);
+          ensure(part.type === 'text'); return nonempty(part.text, 262144);
+        }).join('');
+        inputTokens = tokenCount(response.usage?.input_tokens)
+          + tokenCount(response.usage?.cache_creation_input_tokens ?? 0)
+          + tokenCount(response.usage?.cache_read_input_tokens ?? 0);
+        outputTokens = tokenCount(response.usage?.output_tokens);
+        break;
+      }
+      case 'openai': {
+        ensure(response.status === 'completed' && !response.error && !response.incomplete_details);
+        ensure(Array.isArray(response.output) && response.output.length > 0);
+        text = response.output.map(item => {
+          if (item.type === 'reasoning') {
+            fields(item, ['type','id','summary','content','encrypted_content','status']);
+            ensure(item.status === undefined || item.status === 'completed');
+            if (item.summary !== undefined) { ensure(Array.isArray(item.summary)); for (const part of item.summary) { fields(part,['type','text']);ensure(part.type === 'summary_text' && typeof part.text === 'string'); } }
+            if (item.content !== undefined) { ensure(Array.isArray(item.content));for (const part of item.content) { fields(part,['type','text']);ensure(part.type === 'reasoning_text' && typeof part.text === 'string'); } }
+            return '';
+          }
+          fields(item, ['type','id','status','role','content','phase']);
+          ensure(item.type === 'message' && item.role === 'assistant' && item.status === 'completed');
+          ensure(Array.isArray(item.content) && item.content.length > 0);
+          return item.content.map(part => {
+            fields(part,['type','text','annotations','logprobs']);
+            ensure(part.type === 'output_text'); return nonempty(part.text,262144);
+          }).join('');
+        }).join('');
+        inputTokens = tokenCount(response.usage?.input_tokens);
+        outputTokens = tokenCount(response.usage?.output_tokens);
+        if (response.usage?.output_tokens_details?.reasoning_tokens !== undefined) {
+          ensure(tokenCount(response.usage.output_tokens_details.reasoning_tokens) <= outputTokens);
+        }
+        break;
+      }
+      case 'gemini': {
+        ensure(!response.promptFeedback?.blockReason && Array.isArray(response.candidates) && response.candidates.length === 1);
+        const candidate = response.candidates[0];
+        ensure(candidate.finishReason === 'STOP' && candidate.content?.role === 'model' && Array.isArray(candidate.content.parts));
+        ensure(!candidate.safetyRatings?.some(rating => rating.blocked === true));
+        if (candidate.content.parts.some(part => part.thought === true)) tokenCount(response.usageMetadata?.thoughtsTokenCount);
+        text = candidate.content.parts.map(part => {
+          fields(part,['text','thought','thoughtSignature']);
+          ensure(part.thought === undefined || typeof part.thought === 'boolean');
+          const content = nonempty(part.text,262144);return part.thought === true ? '' : content;
+        }).join('');
+        model = response.modelVersion;
+        inputTokens = tokenCount(response.usageMetadata?.promptTokenCount);
+        outputTokens = tokenCount(response.usageMetadata?.candidatesTokenCount) + tokenCount(response.usageMetadata?.thoughtsTokenCount ?? 0);
+        break;
+      }
+      case 'ollama':
+        ensure(response.done === true && response.done_reason === 'stop');
+        fields(response.message, ['role','content','thinking','tool_calls']);
+        noCalls(response.message);
+        ensure(response.message.thinking === undefined || typeof response.message.thinking === 'string');
+        text = response.message.content;
+        inputTokens = tokenCount(response.prompt_eval_count); outputTokens = tokenCount(response.eval_count);
+        break;
+      case 'openai-compatible': {
+        ensure(Array.isArray(response.choices) && response.choices.length === 1);
+        const choice = response.choices[0];
+        ensure(choice.finish_reason === 'stop'); noCalls(choice.message);
+        fields(choice.message,['role','content','refusal','tool_calls','function_call','annotations','audio']);
+        ensure(choice.message.audio === undefined || choice.message.audio === null);
+        text = choice.message.content;
+        inputTokens = tokenCount(response.usage?.prompt_tokens); outputTokens = tokenCount(response.usage?.completion_tokens);
+        if (response.usage?.completion_tokens_details?.reasoning_tokens !== undefined) {
+          ensure(tokenCount(response.usage.completion_tokens_details.reasoning_tokens) <= outputTokens);
+        }
+        break;
+      }
+    }
+    nonempty(text,262144); nonempty(model,800);
+    ensure(!/[\u0000-\u001f\u007f]/.test(model));
+    tokenCount(inputTokens); tokenCount(outputTokens);
+    ensure(outputTokens <= profile.maxOutputTokens);
+    return { text, model, usage: { inputTokens, outputTokens } };
+  } catch { fail(); }
+}

package/src/models/registry.js

@@ -0,0 +1,83 @@
+const ID = /^[a-z][a-z0-9-]{0,63}$/;
+const ENV = /^[A-Z][A-Z0-9_]{1,127}$/;
+const BUILTINS = [
+  { id: 'anthropic', label: 'Anthropic API', kind: 'api', protocol: 'anthropic-messages' },
+  { id: 'openai', label: 'OpenAI API', kind: 'api', protocol: 'openai-responses' },
+  { id: 'gemini', label: 'Google Gemini API', kind: 'api', protocol: 'gemini-content' },
+  { id: 'ollama', label: 'Ollama local models', kind: 'local', protocol: 'ollama-chat', allowLocalHttp: true },
+  { id: 'openai-compatible', label: 'OpenAI-compatible endpoint', kind: 'api', protocol: 'openai-chat', allowLocalHttp: true },
+  { id: 'claude-code', label: 'Claude Code harness', kind: 'harness', protocol: 'claude-cli', execution: 'adapter-available' },
+  { id: 'codex', label: 'Codex harness', kind: 'harness', protocol: 'codex-cli', execution: 'adapter-available' },
+];
+
+function record(input, allowed, message) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) throw new TypeError(message);
+  const output = {};
+  for (const key of Reflect.ownKeys(input)) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (!allowed.includes(key) || !descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) throw new TypeError(message);
+    output[key] = descriptor.value;
+  }
+  return output;
+}
+
+function descriptor(input) {
+  const message = 'Invalid model adapter';
+  const value = record(input, ['id', 'label', 'kind', 'protocol', 'capabilities', 'execution', 'allowLocalHttp'], message);
+  if (typeof value.id !== 'string' || !ID.test(value.id) || typeof value.label !== 'string' || !value.label.trim() || value.label.length > 120
+    || /[\u0000-\u001f\u007f]/.test(value.label)
+    || !['api', 'local', 'harness'].includes(value.kind) || typeof value.protocol !== 'string' || !ID.test(value.protocol)
+    || !['planned', 'adapter-available'].includes(value.execution)
+    || (value.allowLocalHttp !== undefined && typeof value.allowLocalHttp !== 'boolean')
+    || !Array.isArray(value.capabilities) || value.capabilities.length < 1 || value.capabilities.length > 32
+    || value.capabilities.some(item => typeof item !== 'string' || !ID.test(item))
+    || new Set(value.capabilities).size !== value.capabilities.length) throw new TypeError(message);
+  return Object.freeze({ ...value, capabilities: Object.freeze([...value.capabilities]), liveVerified: false });
+}
+
+function endpoint(value, provider) {
+  try {
+    if (typeof value !== 'string' || value.length > 2048 || /[\u0000-\u0020\u007f]/.test(value)) throw new Error();
+    const url = new URL(value);
+    const local = ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+    if (url.username || url.password || url.search || url.hash
+      || (url.protocol !== 'https:' && !(url.protocol === 'http:' && local && provider.allowLocalHttp))) throw new Error();
+    return url.href;
+  } catch { throw new TypeError('Invalid model profile'); }
+}
+
+export function createModelRegistry() {
+  const providers = new Map();
+  const register = input => {
+    const provider = descriptor(input);
+    if (providers.has(provider.id)) throw new TypeError('Model adapter already registered');
+    providers.set(provider.id, provider);
+    return provider;
+  };
+  for (const provider of BUILTINS) register({ capabilities: ['text'], execution: 'adapter-available', ...provider });
+
+  return Object.freeze({
+    register,
+    list: () => Object.freeze([...providers.values()]),
+    resolve(input, options = {}) {
+      const message = 'Invalid model profile';
+      const value = record(input, ['provider', 'model', 'endpoint', 'credentialEnv', 'timeoutMs', 'maxOutputTokens', 'maxCostUsd'], message);
+      const provider = providers.get(value.provider);
+      if (!provider || typeof value.model !== 'string' || !value.model.trim() || value.model.length > 200
+        || /[\u0000-\u001f\u007f]/.test(value.model)
+        || !Number.isSafeInteger(value.timeoutMs) || value.timeoutMs < 1 || value.timeoutMs > 3_600_000
+        || !Number.isSafeInteger(value.maxOutputTokens) || value.maxOutputTokens < 1 || value.maxOutputTokens > 1_000_000
+        || (value.credentialEnv !== undefined && (typeof value.credentialEnv !== 'string' || !ENV.test(value.credentialEnv)))
+        || (value.maxCostUsd !== undefined && (!Number.isFinite(value.maxCostUsd) || value.maxCostUsd <= 0 || value.maxCostUsd > 10_000))) throw new TypeError(message);
+      const settings = record(options, ['requiredCapabilities'], message);
+      const required = settings.requiredCapabilities ?? [];
+      if (!Array.isArray(required) || required.length > 32 || required.some(item => typeof item !== 'string' || !ID.test(item))) throw new TypeError(message);
+      if (required.some(capability => !provider.capabilities.includes(capability))) throw new TypeError('Missing model capability');
+      const profile = Object.freeze({ ...value, ...(value.endpoint === undefined ? {} : { endpoint: endpoint(value.endpoint, provider) }) });
+      // Registry validation is not an authentication, executable, or live model probe.
+      const reasons = Object.freeze([provider.execution === 'planned' ? 'adapter-not-implemented' : 'requires-runtime-check']);
+      return Object.freeze({ provider, profile, ready: false, reasons });
+    },
+  });
+}

package/src/models/transport.js

@@ -0,0 +1,59 @@
+import { request as httpRequest } from 'node:http';
+import { createProviderHttpClient } from '../adapters/http.js';
+import { createNodeProviderTransport } from '../adapters/node-transport.js';
+import { createModelJsonBody, providerWireBytes } from '../adapters/contract.js';
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
+
+// Local model calls deliberately bypass public-only DNS policy, but only for an
+// explicitly selected HTTP loopback destination. No DNS, proxy, redirect or Unix
+// socket selection is exposed. HTTPS loopback is not supported in this slice.
+async function loopbackJson(url, headers, body, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) { reject(new Error('Model request cancelled')); return; }
+    const request = httpRequest({
+      protocol: 'http:', hostname: url.hostname === '[::1]' ? '::1' : '127.0.0.1',
+      port: url.port || 80, method: 'POST', path: url.pathname,
+      headers: { ...headers, host: url.host, 'accept-encoding': 'identity' }, agent: false, signal,
+    }, response => {
+      const fail = () => { response.destroy(); reject(new Error('Invalid model response')); };
+      if (!Number.isInteger(response.statusCode) || response.statusCode < 200 || response.statusCode >= 300
+        || !/^application\/(?:[A-Za-z0-9.+-]+\+)?json(?:\s*;|$)/i.test(response.headers['content-type'] ?? '')
+        || (response.headers['content-encoding'] && response.headers['content-encoding'] !== 'identity')) { fail(); return; }
+      const length = response.headers['content-length'];
+      if (length !== undefined && (!/^\d+$/.test(length) || Number(length) > MAX_RESPONSE_BYTES)) { fail(); return; }
+      const chunks = []; let bytes = 0;
+      response.on('data', chunk => {
+        bytes += chunk.length;
+        if (bytes > MAX_RESPONSE_BYTES) { fail(); return; }
+        chunks.push(chunk);
+      });
+      response.on('error', reject);
+      response.on('aborted', () => reject(new Error('Incomplete model response')));
+      response.on('end', () => {
+        if (bytes > MAX_RESPONSE_BYTES) return;
+        try { resolve(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)))); }
+        catch { reject(new Error('Invalid model response')); }
+      });
+    });
+    request.on('error', reject);
+    request.end(body);
+  });
+}
+
+export async function requestModelJson({ provider, request, timeoutMs, signal, transport }) {
+  const url = new URL(request.url);
+  if (url.username || url.password || url.search || url.hash) throw new Error('Invalid model destination');
+  const wireBody = createModelJsonBody({ provider, payload: request.body });
+  if (LOOPBACK.has(url.hostname)) {
+    if (!['ollama', 'openai-compatible'].includes(provider) || url.protocol !== 'http:' || transport !== undefined)
+      throw new Error('Unsupported local model destination');
+    return loopbackJson(url, request.headers, providerWireBytes(wireBody), signal);
+  }
+  if (url.protocol !== 'https:') throw new Error('Invalid model destination');
+  const http = createProviderHttpClient({
+    provider, baseUrl: url.origin, transport: transport ?? createNodeProviderTransport(),
+    headers: request.headers, timeoutMs, maxResponseBytes: MAX_RESPONSE_BYTES,
+  });
+  return (await http.request({ method: 'POST', path: url.pathname, wireBody, signal })).data;
+}

package/src/policy/approvals.js

@@ -0,0 +1,251 @@
+const APPROVAL_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const ACTION_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+const receipts = new WeakSet();
+const registries = new WeakMap();
+
+export class ApprovalPolicyError extends Error {
+  constructor(reason = 'invalid-approval') {
+    super('Approval policy input is invalid.');
+    this.name = 'ApprovalPolicyError';
+    this.code = 'ERR_APPROVAL_POLICY';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+
+function fail(reason) { throw new ApprovalPolicyError(reason); }
+
+function captureObject(value, allowed, required, reason) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(reason);
+  let keys;
+  try { keys = Reflect.ownKeys(value); } catch { fail(reason); }
+  if (keys.some(key => typeof key !== 'string' || !allowed.has(key))) fail(reason);
+  const result = Object.create(null);
+  try {
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor?.enumerable) fail(reason);
+      result[key] = value[key];
+    }
+  } catch (error) {
+    if (error instanceof ApprovalPolicyError) throw error;
+    fail(reason);
+  }
+  if (required.some(key => !Object.hasOwn(result, key))) fail(reason);
+  return result;
+}
+
+function validId(value) {
+  return typeof value === 'string' && value.length <= 64 && APPROVAL_ID.test(value);
+}
+
+function validAction(value) {
+  return typeof value === 'string' && value.length <= 100 && ACTION_ID.test(value);
+}
+
+function validResource(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 1_024 && !/[\u0000\r\n]/.test(value);
+}
+
+function timestampMs(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) fail('invalid-expiry');
+  const result = Date.parse(value);
+  if (!Number.isSafeInteger(result) || new Date(result).toISOString() !== value) fail('invalid-expiry');
+  return result;
+}
+
+function fingerprint(receipt) {
+  return JSON.stringify([
+    receipt.id, receipt.approverId, receipt.approverPrincipal, receipt.subjectId,
+    receipt.action, receipt.resource, receipt.policyId, receipt.decision,
+    receipt.expiresAt, receipt.singleUse,
+  ]);
+}
+
+export function createApprovalRegistry(input) {
+  try {
+    const value = captureObject(input, new Set(['approvers']), ['approvers'], 'invalid-registry');
+    if (!Array.isArray(value.approvers)) fail('invalid-registry');
+    const length = value.approvers.length;
+    if (!Number.isSafeInteger(length) || length < 1 || length > 64) fail('invalid-registry');
+    const approvers = new Map();
+    for (let index = 0; index < length; index += 1) {
+      if (!Object.hasOwn(value.approvers, index)) fail('invalid-registry');
+      const approver = captureObject(value.approvers[index], new Set(['id', 'principal']), ['id', 'principal'], 'invalid-registry');
+      if (!validId(approver.id) || !['human', 'agent'].includes(approver.principal) || approvers.has(approver.id)) fail('invalid-registry');
+      approvers.set(approver.id, approver.principal);
+    }
+    const registry = Object.freeze(Object.create(null));
+    registries.set(registry, { approvers, records: new Map(), consumed: new Set(), pending: new Map() });
+    return registry;
+  } catch (error) {
+    if (error instanceof ApprovalPolicyError) throw error;
+    fail('invalid-registry');
+  }
+}
+
+export function createApprovalReceipt(input) {
+  try {
+    const value = captureObject(input, new Set([
+      'id', 'approverId', 'approverPrincipal', 'subjectId', 'action', 'resource', 'policyId',
+      'decision', 'expiresAt', 'singleUse',
+    ]), [
+      'id', 'approverId', 'approverPrincipal', 'subjectId', 'action', 'resource', 'policyId',
+      'decision', 'expiresAt', 'singleUse',
+    ], 'invalid-approval');
+    if (!validId(value.id) || !validId(value.approverId) || !validId(value.subjectId)) fail('invalid-identity');
+    if (!['human', 'agent'].includes(value.approverPrincipal)) fail('invalid-approver-principal');
+    if (!validAction(value.action) || !validAction(value.policyId)) fail('invalid-policy-binding');
+    if (!validResource(value.resource)) fail('invalid-resource');
+    if (!['approved', 'rejected'].includes(value.decision)) fail('invalid-decision');
+    timestampMs(value.expiresAt);
+    if (typeof value.singleUse !== 'boolean') fail('invalid-single-use');
+    if (value.approverId === value.subjectId) fail('self-approval');
+    const receipt = Object.freeze({
+      id: value.id,
+      approverId: value.approverId,
+      approverPrincipal: value.approverPrincipal,
+      subjectId: value.subjectId,
+      action: value.action,
+      resource: value.resource,
+      policyId: value.policyId,
+      decision: value.decision,
+      expiresAt: value.expiresAt,
+      singleUse: value.singleUse,
+    });
+    receipts.add(receipt);
+    return receipt;
+  } catch (error) {
+    if (error instanceof ApprovalPolicyError) throw error;
+    fail('invalid-approval');
+  }
+}
+
+function result(valid, reason, receiptId) {
+  return Object.freeze({ valid, reason, ...(receiptId ? { receiptId } : {}) });
+}
+
+export function verifyApproval(receipt, requestInput, optionsInput) {
+  try {
+    if (!receipts.has(receipt)) return result(false, 'untrusted-approval');
+    const request = captureObject(requestInput, new Set([
+      'subjectId', 'action', 'resource', 'policyId',
+    ]), ['subjectId', 'action', 'resource', 'policyId'], 'invalid-request');
+    const options = captureObject(optionsInput, new Set([
+      'registry', 'expectedApproverId', 'requireHumanApprover', 'requireSingleUse', 'nowMs',
+    ]), ['registry', 'expectedApproverId', 'requireHumanApprover', 'nowMs'], 'invalid-options');
+    const registry = registries.get(options.registry);
+    if (!registry) fail('invalid-approval-registry');
+    if (!validId(options.expectedApproverId) || typeof options.requireHumanApprover !== 'boolean') fail('invalid-approval-authority');
+    if (options.requireSingleUse !== undefined && typeof options.requireSingleUse !== 'boolean') fail('invalid-approval-authority');
+    if (!Number.isSafeInteger(options.nowMs) || options.nowMs < 0) fail('invalid-clock');
+    if (!validId(request.subjectId) || !validAction(request.action) || !validAction(request.policyId) || !validResource(request.resource)) fail('invalid-request');
+
+    const receiptFingerprint = fingerprint(receipt);
+    const registered = registry.records.get(receipt.id);
+    if (registered !== undefined && registered !== receiptFingerprint) return result(false, 'approval-id-collision', receipt.id);
+    if (receipt.singleUse && registry.consumed.has(receipt.id)) return result(false, 'approval-consumed', receipt.id);
+    if (registry.pending.has(receipt.id)) return result(false, 'approval-pending', receipt.id);
+    if (receipt.decision !== 'approved') return result(false, 'approval-rejected', receipt.id);
+    if (timestampMs(receipt.expiresAt) <= options.nowMs) return result(false, 'approval-expired', receipt.id);
+    if (receipt.approverId !== options.expectedApproverId) return result(false, 'approval-authority-mismatch', receipt.id);
+    const configuredPrincipal = registry.approvers.get(options.expectedApproverId);
+    if (!configuredPrincipal || configuredPrincipal !== receipt.approverPrincipal) return result(false, 'approval-authority-mismatch', receipt.id);
+    if (options.requireHumanApprover && configuredPrincipal !== 'human') return result(false, 'approval-authority-mismatch', receipt.id);
+    if (options.requireSingleUse && !receipt.singleUse) return result(false, 'approval-must-be-single-use', receipt.id);
+    if (
+      receipt.subjectId !== request.subjectId || receipt.action !== request.action
+      || receipt.resource !== request.resource || receipt.policyId !== request.policyId
+    ) return result(false, 'approval-binding-mismatch', receipt.id);
+
+    registry.records.set(receipt.id, receiptFingerprint);
+    if (receipt.singleUse) registry.consumed.add(receipt.id);
+    return result(true, 'approval-valid', receipt.id);
+  } catch (error) {
+    if (error instanceof ApprovalPolicyError) throw error;
+    fail('invalid-approval');
+  }
+}
+
+export function claimApproval(receipt, requestInput, optionsInput) {
+  try {
+    if (!receipts.has(receipt)) return result(false, 'untrusted-approval');
+    const request = captureObject(requestInput, new Set([
+      'subjectId', 'action', 'resource', 'policyId',
+    ]), ['subjectId', 'action', 'resource', 'policyId'], 'invalid-request');
+    const options = captureObject(optionsInput, new Set([
+      'registry', 'expectedApproverId', 'requireHumanApprover', 'requireSingleUse', 'nowMs',
+    ]), ['registry', 'expectedApproverId', 'requireHumanApprover', 'nowMs'], 'invalid-options');
+    const registry = registries.get(options.registry);
+    if (!registry) fail('invalid-approval-registry');
+    if (!validId(options.expectedApproverId) || typeof options.requireHumanApprover !== 'boolean') fail('invalid-approval-authority');
+    if (options.requireSingleUse !== undefined && typeof options.requireSingleUse !== 'boolean') fail('invalid-approval-authority');
+    if (!Number.isSafeInteger(options.nowMs) || options.nowMs < 0) fail('invalid-clock');
+    if (!validId(request.subjectId) || !validAction(request.action) || !validAction(request.policyId) || !validResource(request.resource)) fail('invalid-request');
+
+    const receiptFingerprint = fingerprint(receipt);
+    const registered = registry.records.get(receipt.id);
+    if (registered !== undefined && registered !== receiptFingerprint) return result(false, 'approval-id-collision', receipt.id);
+    if (receipt.singleUse && registry.consumed.has(receipt.id)) return result(false, 'approval-consumed', receipt.id);
+    if (registry.pending.has(receipt.id)) return result(false, 'approval-pending', receipt.id);
+    if (receipt.decision !== 'approved') return result(false, 'approval-rejected', receipt.id);
+    if (timestampMs(receipt.expiresAt) <= options.nowMs) return result(false, 'approval-expired', receipt.id);
+    if (receipt.approverId !== options.expectedApproverId) return result(false, 'approval-authority-mismatch', receipt.id);
+    const configuredPrincipal = registry.approvers.get(options.expectedApproverId);
+    if (!configuredPrincipal || configuredPrincipal !== receipt.approverPrincipal) return result(false, 'approval-authority-mismatch', receipt.id);
+    if (options.requireHumanApprover && configuredPrincipal !== 'human') return result(false, 'approval-authority-mismatch', receipt.id);
+    if (options.requireSingleUse && !receipt.singleUse) return result(false, 'approval-must-be-single-use', receipt.id);
+    if (receipt.subjectId !== request.subjectId || receipt.action !== request.action
+      || receipt.resource !== request.resource || receipt.policyId !== request.policyId) {
+      return result(false, 'approval-binding-mismatch', receipt.id);
+    }
+
+    const token = Object.freeze(Object.create(null));
+    registry.pending.set(receipt.id, token);
+    let active = true;
+    let finalized = false;
+    const priorRecord = registry.records.get(receipt.id);
+    const priorConsumed = registry.consumed.has(receipt.id);
+    const claim = {
+      valid: true,
+      reason: 'approval-claimed',
+      receiptId: receipt.id,
+      finalize() {
+        if (!active || finalized || registry.pending.get(receipt.id) !== token) return false;
+        registry.records.set(receipt.id, receiptFingerprint);
+        if (receipt.singleUse) registry.consumed.add(receipt.id);
+        finalized = true;
+        return true;
+      },
+      publish() {
+        if (!active || !finalized || registry.pending.get(receipt.id) !== token) return false;
+        registry.pending.delete(receipt.id);
+        active = false;
+        return true;
+      },
+      rollback() {
+        if (!active || !finalized || registry.pending.get(receipt.id) !== token) return false;
+        if (priorRecord === undefined) registry.records.delete(receipt.id);
+        else registry.records.set(receipt.id, priorRecord);
+        if (!priorConsumed) registry.consumed.delete(receipt.id);
+        registry.pending.delete(receipt.id);
+        active = false;
+        return true;
+      },
+      commit() {
+        if (!this.finalize()) return false;
+        return this.publish();
+      },
+      release() {
+        if (!active || finalized || registry.pending.get(receipt.id) !== token) return false;
+        registry.pending.delete(receipt.id);
+        active = false;
+        return true;
+      },
+    };
+    return Object.freeze(claim);
+  } catch (error) {
+    if (error instanceof ApprovalPolicyError) throw error;
+    fail('invalid-approval');
+  }
+}