@ophirai/sdk 0.1.0

package/dist/server.js

@@ -0,0 +1,149 @@
+import express from 'express';
+import { OphirError } from '@ophirai/protocol';
+/**
+ * Express-based JSON-RPC 2.0 server for receiving Ophir negotiation messages.
+ * Dispatches incoming requests to registered method handlers.
+ */
+export class NegotiationServer {
+    app;
+    handlers = new Map();
+    server;
+    boundPort;
+    constructor() {
+        this.app = express();
+        this.app.use(express.json());
+        this.app.post('/', async (req, res) => {
+            if (!req.body || typeof req.body !== 'object') {
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    id: null,
+                    error: { code: -32700, message: 'Parse error: request body must be a JSON object' },
+                });
+                return;
+            }
+            const { jsonrpc, method, params, id } = req.body;
+            if (jsonrpc !== '2.0') {
+                res.json({
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    error: { code: -32600, message: 'Invalid Request: jsonrpc must be "2.0"' },
+                });
+                return;
+            }
+            if (!method || typeof method !== 'string') {
+                res.json({
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    error: { code: -32600, message: 'Invalid Request: method must be a string' },
+                });
+                return;
+            }
+            const handler = this.handlers.get(method);
+            if (!handler) {
+                // Notifications (no id) get no response
+                if (id === undefined) {
+                    res.status(204).end();
+                    return;
+                }
+                res.json({
+                    jsonrpc: '2.0',
+                    id,
+                    error: { code: -32601, message: `Method not found: ${method}` },
+                });
+                return;
+            }
+            try {
+                const result = await handler(params);
+                // Notifications get no response
+                if (id === undefined) {
+                    res.status(204).end();
+                    return;
+                }
+                res.json({ jsonrpc: '2.0', id, result });
+            }
+            catch (err) {
+                if (id === undefined) {
+                    res.status(204).end();
+                    return;
+                }
+                const isOphirError = err instanceof OphirError;
+                res.json({
+                    jsonrpc: '2.0',
+                    id,
+                    error: {
+                        code: isOphirError ? -32000 : -32603,
+                        message: err instanceof Error ? err.message : 'Internal error',
+                        data: isOphirError
+                            ? { ophir_code: err.code, ...err.data }
+                            : undefined,
+                    },
+                });
+            }
+        });
+    }
+    /** Register an async handler for a JSON-RPC method name.
+     * @param method - The JSON-RPC method name to handle (e.g. "ophir.propose")
+     * @param handler - Async function that receives params and returns the result
+     * @returns void
+     * @example
+     * ```typescript
+     * server.handle('ophir.propose', async (params) => {
+     *   return { accepted: true };
+     * });
+     * ```
+     */
+    handle(method, handler) {
+        this.handlers.set(method, handler);
+    }
+    /** Start listening for JSON-RPC requests on the given port.
+     * @param port - The TCP port to bind to; pass 0 for an OS-assigned port
+     * @returns Resolves when the server is ready to accept connections
+     * @example
+     * ```typescript
+     * const server = new NegotiationServer();
+     * await server.listen(3000);
+     * console.log('Listening on port', server.getPort());
+     * ```
+     */
+    async listen(port) {
+        return new Promise((resolve) => {
+            this.server = this.app.listen(port, () => {
+                if (this.server) {
+                    const addr = this.server.address();
+                    if (addr && typeof addr === 'object') {
+                        this.boundPort = addr.port;
+                    }
+                }
+                resolve();
+            });
+        });
+    }
+    /** Get the actual bound port (useful when port 0 was passed to listen).
+     * @returns The bound port number, or undefined if the server is not listening
+     * @example
+     * ```typescript
+     * await server.listen(0);
+     * const port = server.getPort(); // e.g. 49152
+     * ```
+     */
+    getPort() {
+        return this.boundPort;
+    }
+    /** Stop the server and close all connections.
+     * @returns Resolves when the server has fully shut down
+     * @throws {Error} When the underlying HTTP server fails to close
+     * @example
+     * ```typescript
+     * await server.close();
+     * ```
+     */
+    async close() {
+        return new Promise((resolve, reject) => {
+            if (!this.server) {
+                resolve();
+                return;
+            }
+            this.server.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+}

package/dist/signing.d.ts

@@ -0,0 +1,98 @@
+import type { FinalTerms } from '@ophirai/protocol';
+/**
+ * JCS (RFC 8785) canonicalization using json-stable-stringify.
+ * Produces deterministic JSON output regardless of key insertion order.
+ * Handles nested objects, arrays, nulls, numbers, and booleans.
+ * Undefined values are excluded (standard JSON.stringify behavior).
+ *
+ * @param obj - The value to canonicalize. Must be a JSON-serializable value
+ *   (object, array, string, number, boolean, or null). Throws on undefined,
+ *   functions, or symbols.
+ * @returns A deterministic JSON string with sorted keys.
+ * @throws {OphirError} INVALID_MESSAGE if the input cannot be serialized
+ *   (undefined, function, symbol, or circular reference).
+ *
+ * @example
+ * ```typescript
+ * const canonical = canonicalize({ z: 1, a: 2 });
+ * // '{"a":2,"z":1}'
+ * ```
+ */
+export declare function canonicalize(obj: unknown): string;
+/**
+ * Ed25519 sign canonical bytes. Returns base64-encoded signature.
+ *
+ * @param canonicalBytes - The data to sign as a Uint8Array.
+ * @param secretKey - The 64-byte Ed25519 secret key.
+ * @throws {OphirError} if canonicalBytes is not a Uint8Array.
+ * @throws {OphirError} if secretKey is not 64 bytes.
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('hello ophir');
+ * const signature = sign(data, keypair.secretKey);
+ * ```
+ */
+export declare function sign(canonicalBytes: Uint8Array, secretKey: Uint8Array): string;
+/**
+ * Verify base64-encoded Ed25519 signature against public key.
+ * Returns false (never throws) on any invalid input.
+ *
+ * @param canonicalBytes - The data that was signed as a Uint8Array.
+ * @param signature - The base64-encoded signature string.
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @throws never
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('hello ophir');
+ * const valid = verify(data, signature, keypair.publicKey);
+ * // true or false
+ * ```
+ */
+export declare function verify(canonicalBytes: Uint8Array, signature: string, publicKey: Uint8Array): boolean;
+/**
+ * SHA-256 hash of canonicalized final terms, returned as hex string.
+ * Used as the agreement_hash that both parties commit to.
+ *
+ * Validates that finalTerms contains the required fields: price_per_unit, currency, and unit.
+ *
+ * @throws {OphirError} if finalTerms is missing required fields.
+ *
+ * @example
+ * ```typescript
+ * const hash = agreementHash({ price_per_unit: '0.01', currency: 'USDC', unit: 'request' });
+ * // '3a7f...' (64-char hex string)
+ * ```
+ */
+export declare function agreementHash(finalTerms: FinalTerms): string;
+/**
+ * Canonicalize params object, sign with Ed25519, return base64 signature.
+ *
+ * @param params - The object to canonicalize and sign. Must not be null or undefined.
+ * @param secretKey - The 64-byte Ed25519 secret key.
+ * @throws {OphirError} if params is null or undefined.
+ * @throws {OphirError} if secretKey is not 64 bytes.
+ *
+ * @example
+ * ```typescript
+ * const sig = signMessage({ rfq_id: 'rfq-001', price: '10.00' }, keypair.secretKey);
+ * ```
+ */
+export declare function signMessage(params: unknown, secretKey: Uint8Array): string;
+/**
+ * Canonicalize params object, verify Ed25519 signature.
+ * Returns false (never throws) on invalid signature or null/undefined params.
+ *
+ * @param params - The object that was signed.
+ * @param signature - The base64-encoded signature string.
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @throws never
+ *
+ * @example
+ * ```typescript
+ * const valid = verifyMessage({ rfq_id: 'rfq-001', price: '10.00' }, sig, keypair.publicKey);
+ * // true or false
+ * ```
+ */
+export declare function verifyMessage(params: unknown, signature: string, publicKey: Uint8Array): boolean;

package/dist/signing.js

@@ -0,0 +1,165 @@
+import nacl from 'tweetnacl';
+import stringify from 'json-stable-stringify';
+import { createHash } from 'node:crypto';
+import { OphirError, OphirErrorCode } from '@ophirai/protocol';
+/**
+ * JCS (RFC 8785) canonicalization using json-stable-stringify.
+ * Produces deterministic JSON output regardless of key insertion order.
+ * Handles nested objects, arrays, nulls, numbers, and booleans.
+ * Undefined values are excluded (standard JSON.stringify behavior).
+ *
+ * @param obj - The value to canonicalize. Must be a JSON-serializable value
+ *   (object, array, string, number, boolean, or null). Throws on undefined,
+ *   functions, or symbols.
+ * @returns A deterministic JSON string with sorted keys.
+ * @throws {OphirError} INVALID_MESSAGE if the input cannot be serialized
+ *   (undefined, function, symbol, or circular reference).
+ *
+ * @example
+ * ```typescript
+ * const canonical = canonicalize({ z: 1, a: 2 });
+ * // '{"a":2,"z":1}'
+ * ```
+ */
+export function canonicalize(obj) {
+    if (obj === undefined) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'Cannot canonicalize undefined — value must be JSON-serializable');
+    }
+    if (typeof obj === 'function' || typeof obj === 'symbol') {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, `Cannot canonicalize ${typeof obj} — value must be JSON-serializable`);
+    }
+    const result = stringify(obj);
+    if (result === undefined) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'Canonicalization failed — input may contain circular references');
+    }
+    return result;
+}
+/**
+ * Ed25519 sign canonical bytes. Returns base64-encoded signature.
+ *
+ * @param canonicalBytes - The data to sign as a Uint8Array.
+ * @param secretKey - The 64-byte Ed25519 secret key.
+ * @throws {OphirError} if canonicalBytes is not a Uint8Array.
+ * @throws {OphirError} if secretKey is not 64 bytes.
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('hello ophir');
+ * const signature = sign(data, keypair.secretKey);
+ * ```
+ */
+export function sign(canonicalBytes, secretKey) {
+    if (!(canonicalBytes instanceof Uint8Array)) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'canonicalBytes must be a Uint8Array');
+    }
+    if (secretKey.length !== nacl.sign.secretKeyLength) {
+        throw new OphirError(OphirErrorCode.INVALID_SIGNATURE, `Invalid secret key length: expected ${nacl.sign.secretKeyLength}, got ${secretKey.length}`);
+    }
+    const sig = nacl.sign.detached(canonicalBytes, secretKey);
+    return Buffer.from(sig).toString('base64');
+}
+/**
+ * Verify base64-encoded Ed25519 signature against public key.
+ * Returns false (never throws) on any invalid input.
+ *
+ * @param canonicalBytes - The data that was signed as a Uint8Array.
+ * @param signature - The base64-encoded signature string.
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @throws never
+ *
+ * @example
+ * ```typescript
+ * const data = new TextEncoder().encode('hello ophir');
+ * const valid = verify(data, signature, keypair.publicKey);
+ * // true or false
+ * ```
+ */
+export function verify(canonicalBytes, signature, publicKey) {
+    try {
+        if (!(canonicalBytes instanceof Uint8Array)) {
+            return false;
+        }
+        if (publicKey.length !== nacl.sign.publicKeyLength) {
+            return false;
+        }
+        const sigBytes = Buffer.from(signature, 'base64');
+        if (sigBytes.length !== nacl.sign.signatureLength) {
+            return false;
+        }
+        return nacl.sign.detached.verify(canonicalBytes, sigBytes, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * SHA-256 hash of canonicalized final terms, returned as hex string.
+ * Used as the agreement_hash that both parties commit to.
+ *
+ * Validates that finalTerms contains the required fields: price_per_unit, currency, and unit.
+ *
+ * @throws {OphirError} if finalTerms is missing required fields.
+ *
+ * @example
+ * ```typescript
+ * const hash = agreementHash({ price_per_unit: '0.01', currency: 'USDC', unit: 'request' });
+ * // '3a7f...' (64-char hex string)
+ * ```
+ */
+export function agreementHash(finalTerms) {
+    if (!finalTerms || typeof finalTerms !== 'object') {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'finalTerms must be a non-null object');
+    }
+    if (!finalTerms.price_per_unit || !finalTerms.currency || !finalTerms.unit) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'finalTerms must contain price_per_unit, currency, and unit');
+    }
+    const canonical = canonicalize(finalTerms);
+    return createHash('sha256').update(canonical).digest('hex');
+}
+/**
+ * Canonicalize params object, sign with Ed25519, return base64 signature.
+ *
+ * @param params - The object to canonicalize and sign. Must not be null or undefined.
+ * @param secretKey - The 64-byte Ed25519 secret key.
+ * @throws {OphirError} if params is null or undefined.
+ * @throws {OphirError} if secretKey is not 64 bytes.
+ *
+ * @example
+ * ```typescript
+ * const sig = signMessage({ rfq_id: 'rfq-001', price: '10.00' }, keypair.secretKey);
+ * ```
+ */
+export function signMessage(params, secretKey) {
+    if (params === null || params === undefined) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'params must not be null or undefined');
+    }
+    const canonical = canonicalize(params);
+    const bytes = new TextEncoder().encode(canonical);
+    return sign(bytes, secretKey);
+}
+/**
+ * Canonicalize params object, verify Ed25519 signature.
+ * Returns false (never throws) on invalid signature or null/undefined params.
+ *
+ * @param params - The object that was signed.
+ * @param signature - The base64-encoded signature string.
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @throws never
+ *
+ * @example
+ * ```typescript
+ * const valid = verifyMessage({ rfq_id: 'rfq-001', price: '10.00' }, sig, keypair.publicKey);
+ * // true or false
+ * ```
+ */
+export function verifyMessage(params, signature, publicKey) {
+    if (!signature || typeof signature !== 'string') {
+        return false;
+    }
+    if (params === null || params === undefined) {
+        return false;
+    }
+    const canonical = canonicalize(params);
+    const bytes = new TextEncoder().encode(canonical);
+    return verify(bytes, signature, publicKey);
+}

package/dist/sla.d.ts

@@ -0,0 +1,95 @@
+import type { SLARequirement } from '@ophirai/protocol';
+/** Pre-built SLA templates for common AI service categories. */
+export declare const SLA_TEMPLATES: {
+    readonly inference_realtime: () => SLARequirement;
+    readonly inference_batch: () => SLARequirement;
+    readonly data_processing: () => SLARequirement;
+    readonly code_generation: () => SLARequirement;
+    readonly translation: () => SLARequirement;
+};
+/** Per-metric comparison detail between two SLA offers. */
+export interface SLAComparisonDetail {
+    metric: string;
+    a_value: number;
+    b_value: number;
+    better: 'a' | 'b' | 'tie';
+}
+/** Overall result of comparing two SLA requirements. */
+export interface SLAComparisonResult {
+    winner: 'a' | 'b' | 'tie';
+    details: SLAComparisonDetail[];
+}
+/** Compare two SLA requirements metric-by-metric and determine which is better overall.
+ * @param a - First SLA requirement to compare
+ * @param b - Second SLA requirement to compare
+ * @returns Comparison result with per-metric details and an overall winner
+ * @throws {OphirError} When either SLA requirement is missing a metrics array
+ * @example
+ * ```typescript
+ * const result = compareSLAs(sellerSLA, buyerSLA);
+ * if (result.winner === 'a') console.log('Seller offers better terms');
+ * ```
+ */
+export declare function compareSLAs(a: SLARequirement, b: SLARequirement): SLAComparisonResult;
+/** An unmet SLA metric requirement with the gap between offered and required values. */
+export interface SLAGap {
+    metric: string;
+    required: number;
+    offered: number;
+    gap: number;
+}
+/** Result of checking whether an offered SLA meets required thresholds. */
+export interface SLAMeetsResult {
+    meets: boolean;
+    gaps: SLAGap[];
+}
+/** Check if an offered SLA meets all required metric thresholds.
+ * @param offered - The SLA being offered by the seller
+ * @param required - The SLA requirements demanded by the buyer
+ * @returns Whether all requirements are met, with detailed gaps for any unmet metrics
+ * @throws {OphirError} When either SLA requirement is missing a metrics array
+ * @example
+ * ```typescript
+ * const { meets, gaps } = meetsSLARequirements(sellerSLA, buyerSLA);
+ * if (!meets) gaps.forEach(g => console.log(`${g.metric} off by ${g.gap}`));
+ * ```
+ */
+export declare function meetsSLARequirements(offered: SLARequirement, required: SLARequirement): SLAMeetsResult;
+/** A Lockstep behavioral check derived from an SLA metric. */
+export interface LockstepBehavioralCheck {
+    metric: string;
+    operator: string;
+    threshold: number;
+    measurement_method: string;
+    measurement_window: string;
+}
+/** Lockstep verification spec derived from SLA terms. */
+export interface LockstepVerificationSpec {
+    version: string;
+    agreement_id: string;
+    agreement_hash: string;
+    behavioral_checks: LockstepBehavioralCheck[];
+    dispute_resolution: {
+        method: string;
+        timeout_hours?: number;
+        arbitrator?: string;
+    };
+}
+/** Convert an SLA requirement into a Lockstep behavioral verification spec.
+ * @param sla - The SLA requirement containing metrics and dispute resolution terms
+ * @param agreement - The agreement identifiers to bind the spec to
+ * @param agreement.agreement_id - Unique identifier for the agreement
+ * @param agreement.agreement_hash - Content hash of the agreement for integrity verification
+ * @returns A Lockstep verification spec with behavioral checks derived from each SLA metric
+ * @example
+ * ```typescript
+ * const spec = slaToLockstepSpec(sla, {
+ *   agreement_id: 'agr_123',
+ *   agreement_hash: '0xabc...',
+ * });
+ * ```
+ */
+export declare function slaToLockstepSpec(sla: SLARequirement, agreement: {
+    agreement_id: string;
+    agreement_hash: string;
+}): LockstepVerificationSpec;

package/dist/sla.js

@@ -0,0 +1,187 @@
+import { OphirError, OphirErrorCode } from '@ophirai/protocol';
+/** Pre-built SLA templates for common AI service categories. */
+export const SLA_TEMPLATES = {
+    inference_realtime: () => ({
+        metrics: [
+            { name: 'p99_latency_ms', target: 500, comparison: 'lte' },
+            { name: 'uptime_pct', target: 99.9, comparison: 'gte' },
+            { name: 'accuracy_pct', target: 95, comparison: 'gte' },
+        ],
+        dispute_resolution: { method: 'lockstep_verification', timeout_hours: 24 },
+    }),
+    inference_batch: () => ({
+        metrics: [
+            { name: 'throughput_rpm', target: 1000, comparison: 'gte' },
+            { name: 'accuracy_pct', target: 97, comparison: 'gte' },
+            { name: 'error_rate_pct', target: 1, comparison: 'lte' },
+        ],
+        dispute_resolution: { method: 'lockstep_verification', timeout_hours: 48 },
+    }),
+    data_processing: () => ({
+        metrics: [
+            { name: 'throughput_rpm', target: 500, comparison: 'gte' },
+            { name: 'uptime_pct', target: 99.5, comparison: 'gte' },
+            { name: 'error_rate_pct', target: 2, comparison: 'lte' },
+        ],
+        dispute_resolution: { method: 'automatic_escrow', timeout_hours: 24 },
+    }),
+    code_generation: () => ({
+        metrics: [
+            { name: 'p99_latency_ms', target: 5000, comparison: 'lte' },
+            { name: 'accuracy_pct', target: 90, comparison: 'gte' },
+            { name: 'uptime_pct', target: 99, comparison: 'gte' },
+        ],
+        dispute_resolution: { method: 'lockstep_verification', timeout_hours: 24 },
+    }),
+    translation: () => ({
+        metrics: [
+            { name: 'accuracy_pct', target: 95, comparison: 'gte' },
+            { name: 'p99_latency_ms', target: 3000, comparison: 'lte' },
+            { name: 'uptime_pct', target: 99, comparison: 'gte' },
+        ],
+        dispute_resolution: { method: 'lockstep_verification', timeout_hours: 24 },
+    }),
+};
+function metricKey(m) {
+    return m.name === 'custom' && m.custom_name ? m.custom_name : m.name;
+}
+/** Compare two SLA requirements metric-by-metric and determine which is better overall.
+ * @param a - First SLA requirement to compare
+ * @param b - Second SLA requirement to compare
+ * @returns Comparison result with per-metric details and an overall winner
+ * @throws {OphirError} When either SLA requirement is missing a metrics array
+ * @example
+ * ```typescript
+ * const result = compareSLAs(sellerSLA, buyerSLA);
+ * if (result.winner === 'a') console.log('Seller offers better terms');
+ * ```
+ */
+export function compareSLAs(a, b) {
+    if (!a?.metrics || !b?.metrics) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'Both SLA requirements must have a metrics array');
+    }
+    const aMap = new Map(a.metrics.map((m) => [metricKey(m), m]));
+    const bMap = new Map(b.metrics.map((m) => [metricKey(m), m]));
+    const allKeys = new Set([...aMap.keys(), ...bMap.keys()]);
+    const details = [];
+    let aWins = 0;
+    let bWins = 0;
+    for (const key of allKeys) {
+        const am = aMap.get(key);
+        const bm = bMap.get(key);
+        if (!am || !bm)
+            continue;
+        const aVal = am.target;
+        const bVal = bm.target;
+        let better;
+        if (aVal === bVal) {
+            better = 'tie';
+        }
+        else if (am.comparison === 'lte') {
+            // Lower is better for lte metrics
+            better = aVal < bVal ? 'a' : 'b';
+        }
+        else {
+            // Higher is better for gte/eq metrics
+            better = aVal > bVal ? 'a' : 'b';
+        }
+        if (better === 'a')
+            aWins++;
+        if (better === 'b')
+            bWins++;
+        details.push({ metric: key, a_value: aVal, b_value: bVal, better });
+    }
+    const winner = aWins > bWins ? 'a' : bWins > aWins ? 'b' : 'tie';
+    return { winner, details };
+}
+/** Check if an offered SLA meets all required metric thresholds.
+ * @param offered - The SLA being offered by the seller
+ * @param required - The SLA requirements demanded by the buyer
+ * @returns Whether all requirements are met, with detailed gaps for any unmet metrics
+ * @throws {OphirError} When either SLA requirement is missing a metrics array
+ * @example
+ * ```typescript
+ * const { meets, gaps } = meetsSLARequirements(sellerSLA, buyerSLA);
+ * if (!meets) gaps.forEach(g => console.log(`${g.metric} off by ${g.gap}`));
+ * ```
+ */
+export function meetsSLARequirements(offered, required) {
+    if (!offered?.metrics || !required?.metrics) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'Both SLA requirements must have a metrics array');
+    }
+    const offeredMap = new Map(offered.metrics.map((m) => [metricKey(m), m]));
+    const gaps = [];
+    for (const req of required.metrics) {
+        const key = metricKey(req);
+        const off = offeredMap.get(key);
+        if (!off) {
+            gaps.push({ metric: key, required: req.target, offered: 0, gap: req.target });
+            continue;
+        }
+        if (req.comparison === 'lte') {
+            // Offered must be <= required target
+            if (off.target > req.target) {
+                gaps.push({
+                    metric: key,
+                    required: req.target,
+                    offered: off.target,
+                    gap: off.target - req.target,
+                });
+            }
+        }
+        else if (req.comparison === 'gte') {
+            // Offered must be >= required target
+            if (off.target < req.target) {
+                gaps.push({
+                    metric: key,
+                    required: req.target,
+                    offered: off.target,
+                    gap: req.target - off.target,
+                });
+            }
+        }
+        else if (req.comparison === 'eq') {
+            if (off.target !== req.target) {
+                gaps.push({
+                    metric: key,
+                    required: req.target,
+                    offered: off.target,
+                    gap: Math.abs(req.target - off.target),
+                });
+            }
+        }
+    }
+    return { meets: gaps.length === 0, gaps };
+}
+/** Convert an SLA requirement into a Lockstep behavioral verification spec.
+ * @param sla - The SLA requirement containing metrics and dispute resolution terms
+ * @param agreement - The agreement identifiers to bind the spec to
+ * @param agreement.agreement_id - Unique identifier for the agreement
+ * @param agreement.agreement_hash - Content hash of the agreement for integrity verification
+ * @returns A Lockstep verification spec with behavioral checks derived from each SLA metric
+ * @example
+ * ```typescript
+ * const spec = slaToLockstepSpec(sla, {
+ *   agreement_id: 'agr_123',
+ *   agreement_hash: '0xabc...',
+ * });
+ * ```
+ */
+export function slaToLockstepSpec(sla, agreement) {
+    return {
+        version: '1.0',
+        agreement_id: agreement.agreement_id,
+        agreement_hash: agreement.agreement_hash,
+        behavioral_checks: sla.metrics.map((m) => ({
+            metric: metricKey(m),
+            operator: m.comparison,
+            threshold: m.target,
+            measurement_method: m.measurement_method ?? 'rolling_average',
+            measurement_window: m.measurement_window ?? '1h',
+        })),
+        dispute_resolution: sla.dispute_resolution ?? {
+            method: 'automatic_escrow',
+            timeout_hours: 24,
+        },
+    };
+}