@ophirai/sdk 0.1.0

package/dist/messages.js

@@ -0,0 +1,262 @@
+import { v4 as uuidv4 } from 'uuid';
+import { METHODS, DEFAULT_CONFIG, OphirError, OphirErrorCode } from '@ophirai/protocol';
+import { signMessage, agreementHash } from './signing.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Validate that a string is non-empty. */
+function requireNonEmpty(value, name) {
+    if (!value || typeof value !== 'string' || value.trim().length === 0) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, `${name} must be a non-empty string`);
+    }
+}
+/** Validate that a string looks like a UUID. */
+function requireUUID(value, name) {
+    requireNonEmpty(value, name);
+    if (!UUID_RE.test(value)) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, `${name} must be a valid UUID, got: ${value}`);
+    }
+}
+/** Compute an ISO 8601 expiration timestamp from a TTL in milliseconds. */
+function expiresAt(ttlMs) {
+    return new Date(Date.now() + ttlMs).toISOString();
+}
+/** Wrap params in a JSON-RPC 2.0 request envelope with a UUID id. */
+function rpcEnvelope(method, params) {
+    return { jsonrpc: '2.0', method, id: uuidv4(), params };
+}
+/**
+ * Build a signed RFQ (Request for Quote) message. Signs the RFQ with the buyer's Ed25519 key
+ * so that sellers can verify the buyer authorized this request.
+ *
+ * @throws {OphirError} if buyer identity fields are missing.
+ * @throws {OphirError} if secretKey is not 64 bytes.
+ *
+ * @example
+ * ```typescript
+ * const rfq = buildRFQ({
+ *   buyer: { agent_id: 'did:key:z6Mk...', endpoint: 'https://buyer.example.com' },
+ *   service: { category: 'inference' },
+ *   budget: { max_price_per_unit: '0.01', currency: 'USDC', unit: 'request' },
+ *   secretKey: keypair.secretKey,
+ * });
+ * ```
+ */
+export function buildRFQ(params) {
+    requireNonEmpty(params.buyer.agent_id, 'buyer.agent_id');
+    requireNonEmpty(params.buyer.endpoint, 'buyer.endpoint');
+    if (params.secretKey.length !== 64) {
+        throw new OphirError(OphirErrorCode.INVALID_SIGNATURE, `Invalid secret key length: expected 64, got ${params.secretKey.length}`);
+    }
+    const unsigned = {
+        rfq_id: uuidv4(),
+        buyer: params.buyer,
+        service: params.service,
+        budget: params.budget,
+        sla_requirements: params.sla,
+        negotiation_style: 'rfq',
+        max_rounds: params.maxRounds ?? DEFAULT_CONFIG.max_negotiation_rounds,
+        expires_at: expiresAt(params.ttlMs ?? DEFAULT_CONFIG.rfq_timeout_ms),
+        accepted_payments: params.acceptedPayments,
+    };
+    const signature = signMessage(unsigned, params.secretKey);
+    const rfqParams = { ...unsigned, signature };
+    return rpcEnvelope(METHODS.RFQ, rfqParams);
+}
+/**
+ * Build a signed Quote response message. Signs the quote with the seller's Ed25519 key.
+ *
+ * @throws {OphirError} if rfqId or seller identity fields are missing.
+ *
+ * @example
+ * ```typescript
+ * const quote = buildQuote({
+ *   rfqId: 'a1b2c3d4-...',
+ *   seller: { agent_id: 'did:key:z6Mk...', endpoint: 'https://seller.example.com' },
+ *   pricing: { price_per_unit: '0.005', currency: 'USDC', unit: 'request', pricing_model: 'fixed' },
+ *   secretKey: keypair.secretKey,
+ * });
+ * ```
+ */
+export function buildQuote(params) {
+    requireNonEmpty(params.rfqId, 'rfqId');
+    requireNonEmpty(params.seller.agent_id, 'seller.agent_id');
+    requireNonEmpty(params.seller.endpoint, 'seller.endpoint');
+    if (params.secretKey.length !== 64) {
+        throw new OphirError(OphirErrorCode.INVALID_SIGNATURE, `Invalid secret key length: expected 64, got ${params.secretKey.length}`);
+    }
+    const unsigned = {
+        quote_id: uuidv4(),
+        rfq_id: params.rfqId,
+        seller: params.seller,
+        pricing: params.pricing,
+        sla_offered: params.sla,
+        execution: params.execution,
+        escrow_requirement: params.escrow,
+        expires_at: expiresAt(params.ttlMs ?? DEFAULT_CONFIG.quote_timeout_ms),
+    };
+    const signature = signMessage(unsigned, params.secretKey);
+    const quoteParams = { ...unsigned, signature };
+    return rpcEnvelope(METHODS.QUOTE, quoteParams);
+}
+/**
+ * Build a signed counter-offer message. Signs with the sender's Ed25519 key.
+ *
+ * @throws {OphirError} if rfqId, inResponseTo, or from.agent_id are missing.
+ *
+ * @example
+ * ```typescript
+ * const counter = buildCounter({
+ *   rfqId: 'a1b2c3d4-...',
+ *   inResponseTo: 'e5f6g7h8-...',
+ *   round: 1,
+ *   from: { agent_id: 'did:key:z6Mk...', role: 'buyer' },
+ *   modifications: { price_per_unit: '0.008' },
+ *   secretKey: keypair.secretKey,
+ * });
+ * ```
+ */
+export function buildCounter(params) {
+    requireNonEmpty(params.rfqId, 'rfqId');
+    requireNonEmpty(params.inResponseTo, 'inResponseTo');
+    requireNonEmpty(params.from.agent_id, 'from.agent_id');
+    if (params.secretKey.length !== 64) {
+        throw new OphirError(OphirErrorCode.INVALID_SIGNATURE, `Invalid secret key length: expected 64, got ${params.secretKey.length}`);
+    }
+    const unsigned = {
+        counter_id: uuidv4(),
+        rfq_id: params.rfqId,
+        in_response_to: params.inResponseTo,
+        round: params.round,
+        from: params.from,
+        modifications: params.modifications,
+        justification: params.justification,
+        expires_at: expiresAt(params.ttlMs ?? DEFAULT_CONFIG.counter_timeout_ms),
+    };
+    const signature = signMessage(unsigned, params.secretKey);
+    const counterParams = { ...unsigned, signature };
+    return rpcEnvelope(METHODS.COUNTER, counterParams);
+}
+/**
+ * Build an Accept message with agreement hash and buyer signature.
+ *
+ * Validates that finalTerms contains the required fields: price_per_unit, currency, and unit.
+ *
+ * @throws {OphirError} if rfqId, acceptingMessageId, or required finalTerms fields are missing.
+ *
+ * @example
+ * ```typescript
+ * const accept = buildAccept({
+ *   rfqId: 'a1b2c3d4-...',
+ *   acceptingMessageId: 'e5f6g7h8-...',
+ *   finalTerms: { price_per_unit: '0.01', currency: 'USDC', unit: 'request' },
+ *   buyerSecretKey: keypair.secretKey,
+ * });
+ * ```
+ */
+export function buildAccept(params) {
+    requireNonEmpty(params.rfqId, 'rfqId');
+    requireNonEmpty(params.acceptingMessageId, 'acceptingMessageId');
+    if (!params.finalTerms || typeof params.finalTerms !== 'object') {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'finalTerms must be a non-null object');
+    }
+    if (!params.finalTerms.price_per_unit || !params.finalTerms.currency || !params.finalTerms.unit) {
+        throw new OphirError(OphirErrorCode.INVALID_MESSAGE, 'finalTerms must contain price_per_unit, currency, and unit');
+    }
+    if (params.buyerSecretKey.length !== 64) {
+        throw new OphirError(OphirErrorCode.INVALID_SIGNATURE, `Invalid buyer secret key length: expected 64, got ${params.buyerSecretKey.length}`);
+    }
+    const hash = agreementHash(params.finalTerms);
+    const unsigned = {
+        agreement_id: uuidv4(),
+        rfq_id: params.rfqId,
+        accepting_message_id: params.acceptingMessageId,
+        final_terms: params.finalTerms,
+        agreement_hash: hash,
+    };
+    const buyerSig = signMessage(unsigned, params.buyerSecretKey);
+    const acceptParams = {
+        ...unsigned,
+        buyer_signature: buyerSig,
+        ...(params.sellerSignature ? { seller_signature: params.sellerSignature } : {}),
+    };
+    return rpcEnvelope(METHODS.ACCEPT, acceptParams);
+}
+/**
+ * Build a signed Reject message to decline a negotiation. Signs with the rejecting
+ * agent's Ed25519 key so that receivers can verify the rejection is authorized.
+ *
+ * @throws {OphirError} if rfqId, rejectingMessageId, reason, or agentId are empty.
+ * @throws {OphirError} if secretKey is not 64 bytes.
+ *
+ * @example
+ * ```typescript
+ * const reject = buildReject({
+ *   rfqId: 'a1b2c3d4-...',
+ *   rejectingMessageId: 'e5f6g7h8-...',
+ *   reason: 'Price too high',
+ *   agentId: 'did:key:z6Mk...',
+ *   secretKey: keypair.secretKey,
+ * });
+ * ```
+ */
+export function buildReject(params) {
+    requireNonEmpty(params.rfqId, 'rfqId');
+    requireNonEmpty(params.rejectingMessageId, 'rejectingMessageId');
+    requireNonEmpty(params.reason, 'reason');
+    requireNonEmpty(params.agentId, 'agentId');
+    if (params.secretKey.length !== 64) {
+        throw new OphirError(OphirErrorCode.INVALID_SIGNATURE, `Invalid secret key length: expected 64, got ${params.secretKey.length}`);
+    }
+    const unsigned = {
+        rfq_id: params.rfqId,
+        rejecting_message_id: params.rejectingMessageId,
+        reason: params.reason,
+        from: { agent_id: params.agentId },
+    };
+    const signature = signMessage(unsigned, params.secretKey);
+    const rejectParams = { ...unsigned, signature };
+    return rpcEnvelope(METHODS.REJECT, rejectParams);
+}
+/**
+ * Build a signed Dispute message with violation evidence.
+ *
+ * @throws {OphirError} if agreementId, filedBy.agent_id, requestedRemedy, or escrowAction are empty.
+ *
+ * @example
+ * ```typescript
+ * const dispute = buildDispute({
+ *   agreementId: 'a1b2c3d4-...',
+ *   filedBy: { agent_id: 'did:key:z6Mk...', role: 'buyer' },
+ *   violation: {
+ *     sla_metric: 'uptime_pct',
+ *     agreed_value: 99.9,
+ *     observed_value: 95.0,
+ *     measurement_window: '24h',
+ *     evidence_hash: 'abc123',
+ *   },
+ *   requestedRemedy: 'Full refund',
+ *   escrowAction: 'release_to_buyer',
+ *   secretKey: keypair.secretKey,
+ * });
+ * ```
+ */
+export function buildDispute(params) {
+    requireNonEmpty(params.agreementId, 'agreementId');
+    requireNonEmpty(params.filedBy.agent_id, 'filedBy.agent_id');
+    requireNonEmpty(params.requestedRemedy, 'requestedRemedy');
+    requireNonEmpty(params.escrowAction, 'escrowAction');
+    if (params.secretKey.length !== 64) {
+        throw new OphirError(OphirErrorCode.INVALID_SIGNATURE, `Invalid secret key length: expected 64, got ${params.secretKey.length}`);
+    }
+    const unsigned = {
+        dispute_id: uuidv4(),
+        agreement_id: params.agreementId,
+        filed_by: params.filedBy,
+        violation: params.violation,
+        requested_remedy: params.requestedRemedy,
+        escrow_action: params.escrowAction,
+        lockstep_report: params.lockstepReport,
+    };
+    const signature = signMessage(unsigned, params.secretKey);
+    const disputeParams = { ...unsigned, signature };
+    return rpcEnvelope(METHODS.DISPUTE, disputeParams);
+}

package/dist/negotiation.d.ts

@@ -0,0 +1,113 @@
+import type { NegotiationState, RFQParams, QuoteParams, CounterParams } from '@ophirai/protocol';
+import type { Agreement } from './types.js';
+/**
+ * Tracks the state of a single negotiation from RFQ through completion or rejection.
+ *
+ * All state transitions are validated against the protocol's canonical state machine
+ * defined in `@ophirai/protocol` using `isValidTransition()`. Invalid transitions
+ * throw `OphirError` with code `INVALID_STATE_TRANSITION`.
+ */
+export declare class NegotiationSession {
+    readonly rfqId: string;
+    state: NegotiationState;
+    readonly rfq: RFQParams;
+    quotes: QuoteParams[];
+    counters: CounterParams[];
+    agreement?: Agreement;
+    rejectionReason?: string;
+    currentRound: number;
+    maxRounds: number;
+    createdAt: Date;
+    updatedAt: Date;
+    timeouts: Map<NegotiationState, number>;
+    private escrowAddress?;
+    constructor(rfq: RFQParams, maxRounds?: number);
+    /** Add a received quote to this session and transition state to QUOTES_RECEIVED.
+     *
+     * Can be called from RFQ_SENT (first quote triggers transition),
+     * QUOTES_RECEIVED (additional quotes accumulate without re-transitioning),
+     * or COUNTERING (seller's response quote during counter-offer flow).
+     *
+     * @param quote - The quote parameters received from a seller agent
+     * @throws {OphirError} When the session is not in a state that accepts quotes
+     */
+    addQuote(quote: QuoteParams): void;
+    /** Add a counter-offer and increment the negotiation round.
+     * @param counter - The counter-offer parameters
+     * @throws {OphirError} When the transition from the current state to COUNTERING is not valid
+     * @throws {OphirError} When the current round exceeds the maximum allowed rounds
+     * @example
+     * ```typescript
+     * session.addCounter({ rfq_id: 'rfq_1', counter_id: 'ctr_1', ...terms });
+     * ```
+     */
+    addCounter(counter: CounterParams): void;
+    /** Accept the negotiation with a finalized agreement and transition to ACCEPTED.
+     * @param agreement - The finalized agreement terms both parties have agreed upon
+     * @throws {OphirError} When the transition from the current state to ACCEPTED is not valid
+     * @example
+     * ```typescript
+     * session.accept({ agreement_id: 'agr_1', terms, sla, payment });
+     * ```
+     */
+    accept(agreement: Agreement): void;
+    /** Reject the negotiation with a human-readable reason and transition to REJECTED.
+     *
+     * Valid from: RFQ_SENT, QUOTES_RECEIVED, COUNTERING, ACCEPTED (per protocol spec).
+     * @param reason - Human-readable explanation for why the negotiation was rejected
+     * @throws {OphirError} When the transition from the current state to REJECTED is not valid
+     */
+    reject(reason: string): void;
+    /** Record that escrow has been funded on-chain and transition to ESCROWED.
+     * @param escrowAddress - The on-chain address where escrow funds are held
+     * @throws {OphirError} When the transition from the current state to ESCROWED is not valid
+     */
+    escrowFunded(escrowAddress: string): void;
+    /** Activate the agreement so the seller begins service delivery.
+     * @throws {OphirError} When the transition from the current state to ACTIVE is not valid
+     */
+    activate(): void;
+    /** Mark the agreement as successfully completed and transition to COMPLETED.
+     * @throws {OphirError} When the transition from the current state to COMPLETED is not valid
+     */
+    complete(): void;
+    /** Transition to DISPUTED state to claim an SLA violation.
+     * @throws {OphirError} When the transition from the current state to DISPUTED is not valid
+     */
+    dispute(): void;
+    /** Mark a dispute as resolved and transition to RESOLVED.
+     * @throws {OphirError} When the transition from the current state to RESOLVED is not valid
+     */
+    resolve(): void;
+    /** Get the on-chain escrow address, if set.
+     * @returns The escrow address, or undefined if escrow has not been funded
+     */
+    getEscrowAddress(): string | undefined;
+    /** Check if the current state has exceeded its configured timeout.
+     * @returns True if the time elapsed since the last transition exceeds the state timeout
+     */
+    isExpired(): boolean;
+    /** Check if the session is in a terminal state (COMPLETED, REJECTED, or RESOLVED).
+     * @returns True if the session has reached a terminal state
+     */
+    isTerminal(): boolean;
+    /** Get the set of valid next states from the current state.
+     * @returns Read-only array of states that can be transitioned to
+     */
+    getValidNextStates(): readonly NegotiationState[];
+    /** Serialize session state to a plain object for logging or persistence.
+     * @returns A plain object containing all session fields with dates as ISO strings
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Validate a state transition against the protocol's canonical state machine.
+     * Uses `isValidTransition()` from `@ophirai/protocol` as the single source of truth.
+     *
+     * @param targetState - The state to transition to
+     * @param action - The action name for error messages
+     * @throws {OphirError} INVALID_STATE_TRANSITION if the transition is not allowed
+     */
+    private enforceTransition;
+    /** Apply a validated state transition. */
+    private applyTransition;
+}

package/dist/negotiation.js

@@ -0,0 +1,214 @@
+import { OphirError, OphirErrorCode, DEFAULT_CONFIG, isValidTransition, isTerminalState, getValidNextStates } from '@ophirai/protocol';
+const DEFAULT_TIMEOUTS = {
+    RFQ_SENT: DEFAULT_CONFIG.rfq_timeout_ms,
+    QUOTES_RECEIVED: DEFAULT_CONFIG.quote_timeout_ms,
+    COUNTERING: DEFAULT_CONFIG.counter_timeout_ms,
+};
+/**
+ * Tracks the state of a single negotiation from RFQ through completion or rejection.
+ *
+ * All state transitions are validated against the protocol's canonical state machine
+ * defined in `@ophirai/protocol` using `isValidTransition()`. Invalid transitions
+ * throw `OphirError` with code `INVALID_STATE_TRANSITION`.
+ */
+export class NegotiationSession {
+    rfqId;
+    state;
+    rfq;
+    quotes = [];
+    counters = [];
+    agreement;
+    rejectionReason;
+    currentRound = 0;
+    maxRounds;
+    createdAt;
+    updatedAt;
+    timeouts;
+    escrowAddress;
+    constructor(rfq, maxRounds) {
+        this.rfqId = rfq.rfq_id;
+        this.rfq = rfq;
+        this.state = 'RFQ_SENT';
+        this.maxRounds = maxRounds ?? rfq.max_rounds ?? DEFAULT_CONFIG.max_negotiation_rounds;
+        this.createdAt = new Date();
+        this.updatedAt = new Date();
+        this.timeouts = new Map();
+        for (const [state, ms] of Object.entries(DEFAULT_TIMEOUTS)) {
+            this.timeouts.set(state, ms);
+        }
+    }
+    /** Add a received quote to this session and transition state to QUOTES_RECEIVED.
+     *
+     * Can be called from RFQ_SENT (first quote triggers transition),
+     * QUOTES_RECEIVED (additional quotes accumulate without re-transitioning),
+     * or COUNTERING (seller's response quote during counter-offer flow).
+     *
+     * @param quote - The quote parameters received from a seller agent
+     * @throws {OphirError} When the session is not in a state that accepts quotes
+     */
+    addQuote(quote) {
+        // Allow accumulating quotes while already in QUOTES_RECEIVED (same-state is a no-op transition)
+        if (this.state === 'QUOTES_RECEIVED') {
+            this.quotes.push(quote);
+            this.updatedAt = new Date();
+            return;
+        }
+        // During countering, a seller's response quote is part of the counter-offer flow.
+        // Accumulate it without changing state (COUNTERING → COUNTERING is valid).
+        if (this.state === 'COUNTERING') {
+            this.quotes.push(quote);
+            this.updatedAt = new Date();
+            return;
+        }
+        this.enforceTransition('QUOTES_RECEIVED', 'addQuote');
+        this.quotes.push(quote);
+        this.applyTransition('QUOTES_RECEIVED');
+    }
+    /** Add a counter-offer and increment the negotiation round.
+     * @param counter - The counter-offer parameters
+     * @throws {OphirError} When the transition from the current state to COUNTERING is not valid
+     * @throws {OphirError} When the current round exceeds the maximum allowed rounds
+     * @example
+     * ```typescript
+     * session.addCounter({ rfq_id: 'rfq_1', counter_id: 'ctr_1', ...terms });
+     * ```
+     */
+    addCounter(counter) {
+        this.enforceTransition('COUNTERING', 'addCounter');
+        this.currentRound++;
+        if (this.currentRound > this.maxRounds) {
+            throw new OphirError(OphirErrorCode.MAX_ROUNDS_EXCEEDED, `Round ${this.currentRound} exceeds max ${this.maxRounds}`);
+        }
+        this.counters.push(counter);
+        this.applyTransition('COUNTERING');
+    }
+    /** Accept the negotiation with a finalized agreement and transition to ACCEPTED.
+     * @param agreement - The finalized agreement terms both parties have agreed upon
+     * @throws {OphirError} When the transition from the current state to ACCEPTED is not valid
+     * @example
+     * ```typescript
+     * session.accept({ agreement_id: 'agr_1', terms, sla, payment });
+     * ```
+     */
+    accept(agreement) {
+        this.enforceTransition('ACCEPTED', 'accept');
+        this.agreement = agreement;
+        this.applyTransition('ACCEPTED');
+    }
+    /** Reject the negotiation with a human-readable reason and transition to REJECTED.
+     *
+     * Valid from: RFQ_SENT, QUOTES_RECEIVED, COUNTERING, ACCEPTED (per protocol spec).
+     * @param reason - Human-readable explanation for why the negotiation was rejected
+     * @throws {OphirError} When the transition from the current state to REJECTED is not valid
+     */
+    reject(reason) {
+        this.enforceTransition('REJECTED', 'reject');
+        this.rejectionReason = reason;
+        this.applyTransition('REJECTED');
+    }
+    /** Record that escrow has been funded on-chain and transition to ESCROWED.
+     * @param escrowAddress - The on-chain address where escrow funds are held
+     * @throws {OphirError} When the transition from the current state to ESCROWED is not valid
+     */
+    escrowFunded(escrowAddress) {
+        this.enforceTransition('ESCROWED', 'escrowFunded');
+        this.escrowAddress = escrowAddress;
+        this.applyTransition('ESCROWED');
+    }
+    /** Activate the agreement so the seller begins service delivery.
+     * @throws {OphirError} When the transition from the current state to ACTIVE is not valid
+     */
+    activate() {
+        this.enforceTransition('ACTIVE', 'activate');
+        this.applyTransition('ACTIVE');
+    }
+    /** Mark the agreement as successfully completed and transition to COMPLETED.
+     * @throws {OphirError} When the transition from the current state to COMPLETED is not valid
+     */
+    complete() {
+        this.enforceTransition('COMPLETED', 'complete');
+        this.applyTransition('COMPLETED');
+    }
+    /** Transition to DISPUTED state to claim an SLA violation.
+     * @throws {OphirError} When the transition from the current state to DISPUTED is not valid
+     */
+    dispute() {
+        this.enforceTransition('DISPUTED', 'dispute');
+        this.applyTransition('DISPUTED');
+    }
+    /** Mark a dispute as resolved and transition to RESOLVED.
+     * @throws {OphirError} When the transition from the current state to RESOLVED is not valid
+     */
+    resolve() {
+        this.enforceTransition('RESOLVED', 'resolve');
+        this.applyTransition('RESOLVED');
+    }
+    /** Get the on-chain escrow address, if set.
+     * @returns The escrow address, or undefined if escrow has not been funded
+     */
+    getEscrowAddress() {
+        return this.escrowAddress;
+    }
+    /** Check if the current state has exceeded its configured timeout.
+     * @returns True if the time elapsed since the last transition exceeds the state timeout
+     */
+    isExpired() {
+        const timeout = this.timeouts.get(this.state);
+        if (timeout === undefined)
+            return false;
+        return Date.now() - this.updatedAt.getTime() > timeout;
+    }
+    /** Check if the session is in a terminal state (COMPLETED, REJECTED, or RESOLVED).
+     * @returns True if the session has reached a terminal state
+     */
+    isTerminal() {
+        return isTerminalState(this.state);
+    }
+    /** Get the set of valid next states from the current state.
+     * @returns Read-only array of states that can be transitioned to
+     */
+    getValidNextStates() {
+        return getValidNextStates(this.state);
+    }
+    /** Serialize session state to a plain object for logging or persistence.
+     * @returns A plain object containing all session fields with dates as ISO strings
+     */
+    toJSON() {
+        return {
+            rfqId: this.rfqId,
+            state: this.state,
+            rfq: this.rfq,
+            quotes: this.quotes,
+            counters: this.counters,
+            agreement: this.agreement,
+            rejectionReason: this.rejectionReason,
+            currentRound: this.currentRound,
+            maxRounds: this.maxRounds,
+            escrowAddress: this.escrowAddress,
+            createdAt: this.createdAt.toISOString(),
+            updatedAt: this.updatedAt.toISOString(),
+        };
+    }
+    /**
+     * Validate a state transition against the protocol's canonical state machine.
+     * Uses `isValidTransition()` from `@ophirai/protocol` as the single source of truth.
+     *
+     * @param targetState - The state to transition to
+     * @param action - The action name for error messages
+     * @throws {OphirError} INVALID_STATE_TRANSITION if the transition is not allowed
+     */
+    enforceTransition(targetState, action) {
+        if (isTerminalState(this.state)) {
+            throw new OphirError(OphirErrorCode.INVALID_STATE_TRANSITION, `Cannot ${action}: session is in terminal state ${this.state}`, { currentState: this.state, targetState });
+        }
+        if (!isValidTransition(this.state, targetState)) {
+            const validNext = getValidNextStates(this.state);
+            throw new OphirError(OphirErrorCode.INVALID_STATE_TRANSITION, `Cannot ${action} from state ${this.state}. Valid transitions: ${validNext.join(', ')}`, { currentState: this.state, targetState, validTransitions: [...validNext] });
+        }
+    }
+    /** Apply a validated state transition. */
+    applyTransition(to) {
+        this.state = to;
+        this.updatedAt = new Date();
+    }
+}