@happyvertical/smrt-sales 0.40.0 → 0.40.2

package/dist/chunks/agreements-DbzW1Pcq.js

@@ -0,0 +1,1640 @@
+import { SmrtCollection, SmrtObject, crossPackageRef, field, foreignKey, smrt } from "@happyvertical/smrt-core";
+import { TenantScoped, requireTenantId, tenantId } from "@happyvertical/smrt-tenancy";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/agreements/types.ts
+var AGREEMENT_EXECUTION_STATUSES = [
+	"prepared",
+	"sent",
+	"delivered",
+	"viewed",
+	"partially_signed",
+	"completed",
+	"declined",
+	"cancelled",
+	"expired",
+	"failed"
+];
+function sanitizeSignerIntent(signers) {
+	return signers.map((signer) => ({
+		name: signer.name,
+		email: signer.email,
+		...signer.role ? { role: signer.role } : {},
+		...signer.order !== void 0 ? { order: signer.order } : {},
+		authenticationMethod: signer.authentication?.method ?? "none"
+	}));
+}
+function sanitizeSignerEvidence(signers) {
+	return signers.map((signer) => ({
+		...signer.id ? { id: signer.id } : {},
+		name: signer.name,
+		email: signer.email,
+		...signer.role ? { role: signer.role } : {},
+		...signer.order !== void 0 ? { order: signer.order } : {},
+		status: signer.status,
+		...signer.authenticationMethod ? { authenticationMethod: signer.authenticationMethod } : {},
+		...signer.viewed !== void 0 ? { viewed: signer.viewed } : {},
+		...signer.deliveryFailed !== void 0 ? { deliveryFailed: signer.deliveryFailed } : {}
+	}));
+}
+function coerceAgreementDate(value) {
+	if (value == null) return null;
+	if (value instanceof Date) return value;
+	if (typeof value === "string" || typeof value === "number") {
+		const date = new Date(value);
+		return Number.isNaN(date.getTime()) ? null : date;
+	}
+	return null;
+}
+//#endregion
+//#region src/agreements/models/AgreementExecution.ts
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp$2(target, key, result);
+	return result;
+};
+var persistedExecutionIdentity = /* @__PURE__ */ new WeakMap();
+var AgreementExecution = class extends SmrtObject {
+	tenantId = "";
+	provider = "";
+	/** Non-secret provider account/region reference used for operations. */
+	providerAccountRef = "";
+	/** SDK/SMRT secret-store reference only; never a credential value. */
+	credentialRef = "";
+	idempotencyKey = "";
+	sourceKind = "";
+	sourceId = "";
+	sourceVersion = 1;
+	sourceAssetId = "";
+	sourceSha256 = "";
+	sourceSizeBytes = 0;
+	requestIntentSha256 = "";
+	title = "";
+	signerIntent = "[]";
+	providerRequestId = "";
+	providerRequestKey = null;
+	status = "prepared";
+	expiresAt = null;
+	cancellationReason = "";
+	lastProviderEventAt = null;
+	lastReconciledAt = null;
+	completedAt = null;
+	effectiveFrom = null;
+	effectiveTo = null;
+	/**
+	* Opaque prior-evidence provenance copied into the immutable result.
+	* The authoritative relationship is on ExecutedAgreement; making this
+	* mutable orchestration hint a foreign key would create a registry cycle.
+	*/
+	supersedesExecutedAgreementId = "";
+	signedDocumentAssetId = "";
+	signedDocumentSha256 = "";
+	signedDocumentSizeBytes = 0;
+	signedDocumentMediaType = "";
+	signedDocumentFilename = "";
+	auditTrailAssetId = "";
+	auditTrailSha256 = "";
+	auditTrailSizeBytes = 0;
+	auditTrailMediaType = "";
+	auditTrailFilename = "";
+	attemptCount = 0;
+	/** Operation id holding the current provider-create lease. */
+	createLeaseId = "";
+	/** A crashed create attempt stops fencing recovery after this instant. */
+	createLeaseExpiresAt = null;
+	lastError = "";
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.provider !== void 0) this.provider = options.provider;
+		if (options.providerAccountRef !== void 0) this.providerAccountRef = options.providerAccountRef;
+		if (options.credentialRef !== void 0) this.credentialRef = options.credentialRef;
+		if (options.idempotencyKey !== void 0) this.idempotencyKey = options.idempotencyKey;
+		if (options.sourceKind !== void 0) this.sourceKind = options.sourceKind;
+		if (options.sourceId !== void 0) this.sourceId = options.sourceId;
+		if (options.sourceVersion !== void 0) this.sourceVersion = options.sourceVersion;
+		if (options.sourceAssetId !== void 0) this.sourceAssetId = options.sourceAssetId;
+		if (options.sourceSha256 !== void 0) this.sourceSha256 = options.sourceSha256;
+		if (options.sourceSizeBytes !== void 0) this.sourceSizeBytes = options.sourceSizeBytes;
+		if (options.requestIntentSha256 !== void 0) this.requestIntentSha256 = options.requestIntentSha256;
+		if (options.title !== void 0) this.title = options.title;
+		if (options.signerIntent !== void 0) this.signerIntent = options.signerIntent;
+		if (options.providerRequestId !== void 0) this.providerRequestId = options.providerRequestId;
+		if (options.providerRequestKey !== void 0) this.providerRequestKey = options.providerRequestKey;
+		this.syncProviderRequestKey();
+		if (options.status !== void 0) this.status = options.status;
+		if (options.expiresAt !== void 0) this.expiresAt = coerceAgreementDate(options.expiresAt);
+		if (options.cancellationReason !== void 0) this.cancellationReason = options.cancellationReason;
+		if (options.lastProviderEventAt !== void 0) this.lastProviderEventAt = coerceAgreementDate(options.lastProviderEventAt);
+		if (options.lastReconciledAt !== void 0) this.lastReconciledAt = coerceAgreementDate(options.lastReconciledAt);
+		if (options.completedAt !== void 0) this.completedAt = coerceAgreementDate(options.completedAt);
+		if (options.effectiveFrom !== void 0) this.effectiveFrom = coerceAgreementDate(options.effectiveFrom);
+		if (options.effectiveTo !== void 0) this.effectiveTo = coerceAgreementDate(options.effectiveTo);
+		if (options.supersedesExecutedAgreementId !== void 0) this.supersedesExecutedAgreementId = options.supersedesExecutedAgreementId;
+		if (options.signedDocumentAssetId !== void 0) this.signedDocumentAssetId = options.signedDocumentAssetId;
+		if (options.signedDocumentSha256 !== void 0) this.signedDocumentSha256 = options.signedDocumentSha256;
+		if (options.signedDocumentSizeBytes !== void 0) this.signedDocumentSizeBytes = options.signedDocumentSizeBytes;
+		if (options.signedDocumentMediaType !== void 0) this.signedDocumentMediaType = options.signedDocumentMediaType;
+		if (options.signedDocumentFilename !== void 0) this.signedDocumentFilename = options.signedDocumentFilename;
+		if (options.auditTrailAssetId !== void 0) this.auditTrailAssetId = options.auditTrailAssetId;
+		if (options.auditTrailSha256 !== void 0) this.auditTrailSha256 = options.auditTrailSha256;
+		if (options.auditTrailSizeBytes !== void 0) this.auditTrailSizeBytes = options.auditTrailSizeBytes;
+		if (options.auditTrailMediaType !== void 0) this.auditTrailMediaType = options.auditTrailMediaType;
+		if (options.auditTrailFilename !== void 0) this.auditTrailFilename = options.auditTrailFilename;
+		if (options.attemptCount !== void 0) this.attemptCount = options.attemptCount;
+		if (options.createLeaseId !== void 0) this.createLeaseId = options.createLeaseId;
+		if (options.createLeaseExpiresAt !== void 0) this.createLeaseExpiresAt = coerceAgreementDate(options.createLeaseExpiresAt);
+		if (options.lastError !== void 0) this.lastError = options.lastError;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	async initialize() {
+		await super.initialize();
+		this.expiresAt = coerceAgreementDate(this.expiresAt);
+		this.lastProviderEventAt = coerceAgreementDate(this.lastProviderEventAt);
+		this.lastReconciledAt = coerceAgreementDate(this.lastReconciledAt);
+		this.completedAt = coerceAgreementDate(this.completedAt);
+		this.effectiveFrom = coerceAgreementDate(this.effectiveFrom);
+		this.effectiveTo = coerceAgreementDate(this.effectiveTo);
+		this.createLeaseExpiresAt = coerceAgreementDate(this.createLeaseExpiresAt);
+		if (this.isPersisted) persistedExecutionIdentity.set(this, this.captureIdentity());
+		return this;
+	}
+	async save() {
+		const captured = persistedExecutionIdentity.get(this);
+		if (captured) this.assertBoundValueUnchanged("provider request", captured.providerRequestId, this.providerRequestId);
+		this.syncProviderRequestKey();
+		if (captured) {
+			if (captured.intent !== this.serializeIntent()) throw new Error(`AgreementExecution ${this.id ?? "<new>"}: execution identity is immutable`);
+			this.assertBoundValueUnchanged("provider request key", captured.providerRequestKey ?? "", this.providerRequestKey ?? "");
+			this.assertBoundValueUnchanged("signed document evidence", captured.signedDocumentEvidence, this.serializeSignedDocumentEvidence());
+			this.assertBoundValueUnchanged("audit trail evidence", captured.auditTrailEvidence, this.serializeAuditTrailEvidence());
+		}
+		const saved = await super.save();
+		persistedExecutionIdentity.set(this, this.captureIdentity());
+		return saved;
+	}
+	getSignerIntent() {
+		try {
+			const value = JSON.parse(this.signerIntent);
+			return Array.isArray(value) ? value : [];
+		} catch {
+			return [];
+		}
+	}
+	captureIdentity() {
+		return {
+			intent: this.serializeIntent(),
+			providerRequestId: this.providerRequestId,
+			providerRequestKey: this.providerRequestKey,
+			signedDocumentEvidence: this.serializeSignedDocumentEvidence(),
+			auditTrailEvidence: this.serializeAuditTrailEvidence()
+		};
+	}
+	serializeIntent() {
+		return JSON.stringify({
+			tenantId: this.tenantId,
+			provider: this.provider,
+			providerAccountRef: this.providerAccountRef,
+			credentialRef: this.credentialRef,
+			idempotencyKey: this.idempotencyKey,
+			sourceKind: this.sourceKind,
+			sourceId: this.sourceId,
+			sourceVersion: this.sourceVersion,
+			sourceAssetId: this.sourceAssetId,
+			sourceSha256: this.sourceSha256,
+			sourceSizeBytes: this.sourceSizeBytes,
+			requestIntentSha256: this.requestIntentSha256,
+			title: this.title,
+			signerIntent: this.signerIntent,
+			effectiveFrom: this.effectiveFrom?.toISOString() ?? null,
+			effectiveTo: this.effectiveTo?.toISOString() ?? null,
+			supersedesExecutedAgreementId: this.supersedesExecutedAgreementId,
+			metadata: this.metadata
+		});
+	}
+	serializeSignedDocumentEvidence() {
+		if (!this.signedDocumentAssetId) return "";
+		return JSON.stringify({
+			assetId: this.signedDocumentAssetId,
+			sha256: this.signedDocumentSha256,
+			sizeBytes: this.signedDocumentSizeBytes,
+			mediaType: this.signedDocumentMediaType,
+			filename: this.signedDocumentFilename
+		});
+	}
+	serializeAuditTrailEvidence() {
+		if (!this.auditTrailAssetId) return "";
+		return JSON.stringify({
+			assetId: this.auditTrailAssetId,
+			sha256: this.auditTrailSha256,
+			sizeBytes: this.auditTrailSizeBytes,
+			mediaType: this.auditTrailMediaType,
+			filename: this.auditTrailFilename
+		});
+	}
+	assertBoundValueUnchanged(label, captured, current) {
+		if (captured && captured !== current) throw new Error(`AgreementExecution ${this.id ?? "<new>"}: ${label} is immutable once bound`);
+	}
+	syncProviderRequestKey() {
+		if (!this.providerRequestId) {
+			this.providerRequestKey = null;
+			return;
+		}
+		if (!this.tenantId || !this.provider) throw new Error("AgreementExecution provider request binding requires tenant and provider");
+		const expected = `${this.tenantId}:${this.provider}:${this.providerRequestId}`;
+		if (this.providerRequestKey && this.providerRequestKey !== expected) throw new Error(`AgreementExecution ${this.id ?? "<new>"}: provider request key does not match its binding`);
+		this.providerRequestKey = expected;
+	}
+};
+__decorateClass$2([tenantId()], AgreementExecution.prototype, "tenantId", 2);
+__decorateClass$2([field({ required: true })], AgreementExecution.prototype, "provider", 2);
+__decorateClass$2([field({ required: true })], AgreementExecution.prototype, "idempotencyKey", 2);
+__decorateClass$2([field({ required: true })], AgreementExecution.prototype, "sourceKind", 2);
+__decorateClass$2([field({ required: true })], AgreementExecution.prototype, "sourceId", 2);
+__decorateClass$2([crossPackageRef("@happyvertical/smrt-assets:Asset")], AgreementExecution.prototype, "sourceAssetId", 2);
+__decorateClass$2([field({
+	type: "text",
+	nullable: true,
+	unique: true
+})], AgreementExecution.prototype, "providerRequestKey", 2);
+__decorateClass$2([crossPackageRef("@happyvertical/smrt-assets:Asset")], AgreementExecution.prototype, "signedDocumentAssetId", 2);
+__decorateClass$2([crossPackageRef("@happyvertical/smrt-assets:Asset")], AgreementExecution.prototype, "auditTrailAssetId", 2);
+AgreementExecution = __decorateClass$2([TenantScoped({ mode: "required" }), smrt({
+	conflictColumns: ["tenant_id", "idempotency_key"],
+	api: false,
+	mcp: false,
+	cli: false
+})], AgreementExecution);
+//#endregion
+//#region src/agreements/collections/AgreementExecutionCollection.ts
+var AgreementExecutionCollection = class extends SmrtCollection {
+	static _itemClass = AgreementExecution;
+	async findByIdempotencyKey(idempotencyKey) {
+		return (await this.list({
+			where: { idempotencyKey },
+			limit: 1
+		}))[0] ?? null;
+	}
+	async findByProviderRequest(provider, providerRequestId) {
+		return (await this.list({
+			where: {
+				provider,
+				providerRequestId
+			},
+			limit: 1
+		}))[0] ?? null;
+	}
+	/**
+	* Atomically claim an expired or cleared provider-create lease.
+	*
+	* The explicit tenant predicate and expected-state predicates make the raw
+	* compare-and-swap fail closed across workers. `RETURNING id` is used
+	* because not every database adapter reports affected-row counts reliably.
+	*/
+	async claimCreateAttempt(input) {
+		if (requireTenantId() !== input.tenantId) throw new Error("AgreementExecution create-lease tenant mismatch");
+		const claimed = (await this._db.query(`UPDATE ${this.tableName}
+          SET attempt_count = attempt_count + 1,
+              status = ?,
+              last_error = '',
+              create_lease_id = ?,
+              create_lease_expires_at = ?
+        WHERE id = ?
+          AND tenant_id = ?
+          AND attempt_count = ?
+          AND status = ?
+          AND COALESCE(last_error, '') = ?
+          AND COALESCE(create_lease_id, '') = ?
+          AND (provider_request_id IS NULL OR provider_request_id = '')
+          AND (create_lease_expires_at IS NULL OR create_lease_expires_at <= ?)
+        RETURNING id`, "prepared", input.operationId, input.leaseExpiresAt.toISOString(), input.executionId, input.tenantId, input.expectedAttemptCount, input.expectedStatus, input.expectedLastError, input.expectedLeaseId, input.now.toISOString())).rows[0];
+		if (typeof claimed?.id !== "string") return null;
+		return await this.get({ id: claimed.id });
+	}
+	/**
+	* Persist a provider-create result only while the caller still owns its
+	* lease. This prevents a slow, expired attempt from overwriting a newer
+	* recovery attempt after returning from the provider.
+	*/
+	async completeCreateAttempt(input) {
+		this.assertCreateAttemptTenant(input.tenantId);
+		const providerRequestKey = `${input.tenantId}:${input.provider}:${input.providerRequestId}`;
+		const result = await this._db.query(`UPDATE ${this.tableName}
+          SET provider_request_id = ?,
+              provider_request_key = ?,
+              status = ?,
+              expires_at = ?,
+              last_error = '',
+              create_lease_id = '',
+              create_lease_expires_at = NULL
+        WHERE id = ?
+          AND tenant_id = ?
+          AND provider = ?
+          AND COALESCE(create_lease_id, '') = ?
+          AND (provider_request_id IS NULL OR provider_request_id = '')
+        RETURNING id`, input.providerRequestId, providerRequestKey, input.status, input.expiresAt?.toISOString() ?? null, input.executionId, input.tenantId, input.provider, input.operationId);
+		return await this.getReturnedExecution(result);
+	}
+	/** Record a create failure only while the caller still owns its lease. */
+	async failCreateAttempt(input) {
+		this.assertCreateAttemptTenant(input.tenantId);
+		const result = await this._db.query(`UPDATE ${this.tableName}
+          SET status = ?,
+              last_error = ?,
+              create_lease_id = '',
+              create_lease_expires_at = NULL
+        WHERE id = ?
+          AND tenant_id = ?
+          AND COALESCE(create_lease_id, '') = ?
+          AND (provider_request_id IS NULL OR provider_request_id = '')
+        RETURNING id`, "failed", input.lastError, input.executionId, input.tenantId, input.operationId);
+		return await this.getReturnedExecution(result);
+	}
+	/** Bind an adopted provider request without saving a stale object snapshot. */
+	async bindProviderRequest(input) {
+		this.assertCreateAttemptTenant(input.tenantId);
+		const providerRequestKey = `${input.tenantId}:${input.provider}:${input.providerRequestId}`;
+		const result = await this._db.query(`UPDATE ${this.tableName}
+          SET provider_request_id = ?,
+              provider_request_key = ?
+        WHERE id = ?
+          AND tenant_id = ?
+          AND provider = ?
+          AND (provider_request_id IS NULL OR provider_request_id = '' OR provider_request_id = ?)
+        RETURNING id`, input.providerRequestId, providerRequestKey, input.executionId, input.tenantId, input.provider, input.providerRequestId);
+		return await this.getReturnedExecution(result);
+	}
+	/**
+	* Apply provider lifecycle state only while status still matches the
+	* caller's snapshot and the candidate observation is not older than the
+	* persisted provider event. Service retries re-read the winner before
+	* deciding whether the candidate state remains monotonic.
+	*/
+	async compareAndSetLifecycle(input) {
+		this.assertCreateAttemptTenant(input.tenantId);
+		const result = await this._db.query(`UPDATE ${this.tableName}
+          SET status = ?,
+              expires_at = ?,
+              cancellation_reason = ?,
+              last_provider_event_at = ?,
+              last_reconciled_at = ?,
+              completed_at = ?,
+              last_error = ''
+        WHERE id = ?
+          AND tenant_id = ?
+          AND status = ?
+          AND (last_provider_event_at IS NULL OR last_provider_event_at <= ?)
+        RETURNING id`, input.status, input.expiresAt?.toISOString() ?? null, input.cancellationReason, input.lastProviderEventAt.toISOString(), input.lastReconciledAt?.toISOString() ?? null, input.completedAt?.toISOString() ?? null, input.executionId, input.tenantId, input.expectedStatus, input.lastProviderEventAt.toISOString());
+		return await this.getReturnedExecution(result);
+	}
+	/** Increment audit attempts without writing any lifecycle columns. */
+	async incrementAttemptCount(tenantId, executionId) {
+		this.assertCreateAttemptTenant(tenantId);
+		const result = await this._db.query(`UPDATE ${this.tableName}
+          SET attempt_count = attempt_count + 1
+        WHERE id = ?
+          AND tenant_id = ?
+        RETURNING id`, executionId, tenantId);
+		const execution = await this.getReturnedExecution(result);
+		if (!execution) throw new Error(`AgreementExecution '${executionId}' was not found`);
+		return execution;
+	}
+	/** Update failure diagnostics without writing a stale lifecycle snapshot. */
+	async updateLastError(input) {
+		this.assertCreateAttemptTenant(input.tenantId);
+		const result = await this._db.query(`UPDATE ${this.tableName}
+          SET last_error = ?
+        WHERE id = ?
+          AND tenant_id = ?
+        RETURNING id`, input.lastError, input.executionId, input.tenantId);
+		const execution = await this.getReturnedExecution(result);
+		if (!execution) throw new Error(`AgreementExecution '${input.executionId}' was not found`);
+		return execution;
+	}
+	/**
+	* Bind one immutable evidence artifact with a tenant-fenced compare-and-swap.
+	* Concurrent finalizers can only publish one asset identity for each kind.
+	*/
+	async bindEvidenceArtifact(input) {
+		this.assertCreateAttemptTenant(input.tenantId);
+		const columns = input.kind === "signed_document" ? {
+			assetId: "signed_document_asset_id",
+			sha256: "signed_document_sha256",
+			sizeBytes: "signed_document_size_bytes",
+			mediaType: "signed_document_media_type",
+			filename: "signed_document_filename"
+		} : {
+			assetId: "audit_trail_asset_id",
+			sha256: "audit_trail_sha256",
+			sizeBytes: "audit_trail_size_bytes",
+			mediaType: "audit_trail_media_type",
+			filename: "audit_trail_filename"
+		};
+		const result = await this._db.query(`UPDATE ${this.tableName}
+          SET ${columns.assetId} = ?,
+              ${columns.sha256} = ?,
+              ${columns.sizeBytes} = ?,
+              ${columns.mediaType} = ?,
+              ${columns.filename} = ?
+        WHERE id = ?
+          AND tenant_id = ?
+          AND provider_request_id IS NOT NULL
+          AND provider_request_id <> ''
+          AND ${columns.assetId} IS NULL
+        RETURNING id`, input.assetId, input.sha256, input.sizeBytes, input.mediaType, input.filename, input.executionId, input.tenantId);
+		return await this.getReturnedExecution(result);
+	}
+	async findBySource(sourceKind, sourceId) {
+		return await this.list({
+			where: {
+				sourceKind,
+				sourceId
+			},
+			orderBy: "source_version DESC"
+		});
+	}
+	assertCreateAttemptTenant(tenantId) {
+		if (requireTenantId() !== tenantId) throw new Error("AgreementExecution create-lease tenant mismatch");
+	}
+	async getReturnedExecution(result) {
+		const returned = result.rows?.[0];
+		if (typeof returned?.id !== "string") return null;
+		return await this.get({ id: returned.id });
+	}
+};
+//#endregion
+//#region src/agreements/models/AgreementExecutionEvent.ts
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp$1(target, key, result);
+	return result;
+};
+var persistedEventState = /* @__PURE__ */ new WeakMap();
+var AgreementExecutionEvent = class extends SmrtObject {
+	tenantId = "";
+	executionId = "";
+	provider = "";
+	providerEventId = "";
+	eventOrigin = "provider_webhook";
+	operationId = "";
+	dedupeKey = "";
+	orderingKey = "";
+	eventType = "";
+	status = "prepared";
+	occurredAt = /* @__PURE__ */ new Date();
+	receivedAt = /* @__PURE__ */ new Date();
+	payloadSha256 = "";
+	signerEvidence = "[]";
+	payload = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.executionId !== void 0) this.executionId = options.executionId;
+		if (options.provider !== void 0) this.provider = options.provider;
+		if (options.providerEventId !== void 0) this.providerEventId = options.providerEventId;
+		if (options.eventOrigin !== void 0) this.eventOrigin = options.eventOrigin;
+		if (options.operationId !== void 0) this.operationId = options.operationId;
+		if (options.dedupeKey !== void 0) this.dedupeKey = options.dedupeKey;
+		if (options.orderingKey !== void 0) this.orderingKey = options.orderingKey;
+		if (options.eventType !== void 0) this.eventType = options.eventType;
+		if (options.status !== void 0) this.status = options.status;
+		if (options.occurredAt !== void 0) this.occurredAt = coerceAgreementDate(options.occurredAt) ?? /* @__PURE__ */ new Date();
+		if (options.receivedAt !== void 0) this.receivedAt = coerceAgreementDate(options.receivedAt) ?? /* @__PURE__ */ new Date();
+		if (options.payloadSha256 !== void 0) this.payloadSha256 = options.payloadSha256;
+		if (options.signerEvidence !== void 0) this.signerEvidence = options.signerEvidence;
+		if (options.payload !== void 0) this.payload = options.payload;
+	}
+	async initialize() {
+		await super.initialize();
+		this.occurredAt = coerceAgreementDate(this.occurredAt) ?? /* @__PURE__ */ new Date();
+		this.receivedAt = coerceAgreementDate(this.receivedAt) ?? /* @__PURE__ */ new Date();
+		if (this.isPersisted) persistedEventState.set(this, this.serializeState());
+		return this;
+	}
+	async save() {
+		const captured = persistedEventState.get(this);
+		if (captured !== void 0 && captured !== this.serializeState()) throw new Error(`AgreementExecutionEvent ${this.id ?? "<new>"}: verified events are immutable`);
+		if (captured === void 0 && !this.isPersisted) this.requireInsertOnSave();
+		const result = await super.save();
+		persistedEventState.set(this, this.serializeState());
+		return result;
+	}
+	serializeState() {
+		return JSON.stringify({
+			tenantId: this.tenantId,
+			executionId: this.executionId,
+			provider: this.provider,
+			providerEventId: this.providerEventId,
+			eventOrigin: this.eventOrigin,
+			operationId: this.operationId,
+			dedupeKey: this.dedupeKey,
+			orderingKey: this.orderingKey,
+			eventType: this.eventType,
+			status: this.status,
+			occurredAt: this.occurredAt.toISOString(),
+			receivedAt: this.receivedAt.toISOString(),
+			payloadSha256: this.payloadSha256,
+			signerEvidence: this.signerEvidence,
+			payload: this.payload
+		});
+	}
+};
+__decorateClass$1([tenantId()], AgreementExecutionEvent.prototype, "tenantId", 2);
+__decorateClass$1([foreignKey("AgreementExecution", { required: true })], AgreementExecutionEvent.prototype, "executionId", 2);
+__decorateClass$1([field({ required: true })], AgreementExecutionEvent.prototype, "dedupeKey", 2);
+AgreementExecutionEvent = __decorateClass$1([TenantScoped({ mode: "required" }), smrt({
+	conflictColumns: ["tenant_id", "dedupe_key"],
+	api: false,
+	mcp: false,
+	cli: false
+})], AgreementExecutionEvent);
+//#endregion
+//#region src/agreements/collections/AgreementExecutionEventCollection.ts
+var AgreementExecutionEventCollection = class extends SmrtCollection {
+	static _itemClass = AgreementExecutionEvent;
+	async findByDedupeKey(dedupeKey) {
+		return (await this.list({
+			where: { dedupeKey },
+			limit: 1
+		}))[0] ?? null;
+	}
+	async recordVerified(options) {
+		if (!options.dedupeKey) throw new Error("AgreementExecutionEvent requires a dedupe key");
+		const occurredAt = coerceAgreementDate(options.occurredAt);
+		if (!occurredAt) throw new Error("AgreementExecutionEvent requires a valid occurredAt");
+		const receivedAt = coerceAgreementDate(options.receivedAt);
+		if (!receivedAt) throw new Error("AgreementExecutionEvent requires a valid receivedAt");
+		const existing = await this.findByDedupeKey(options.dedupeKey);
+		if (existing) {
+			this.assertSameVerifiedEvent(existing, options, occurredAt);
+			return {
+				event: existing,
+				created: false
+			};
+		}
+		const { occurredAt: _occurredAt, receivedAt: _receivedAt, ...rest } = options;
+		try {
+			return {
+				event: await this.create({
+					...rest,
+					occurredAt,
+					receivedAt,
+					_insertOnly: true
+				}),
+				created: true
+			};
+		} catch (error) {
+			const raced = await this.findByDedupeKey(options.dedupeKey);
+			if (!raced) throw error;
+			this.assertSameVerifiedEvent(raced, options, occurredAt);
+			return {
+				event: raced,
+				created: false
+			};
+		}
+	}
+	assertSameVerifiedEvent(existing, options, occurredAt) {
+		if (existing.executionId !== options.executionId || existing.provider !== options.provider || existing.providerEventId !== (options.providerEventId ?? "") || existing.eventOrigin !== (options.eventOrigin ?? "provider_webhook") || existing.operationId !== (options.operationId ?? "") || existing.orderingKey !== (options.orderingKey ?? "") || existing.eventType !== (options.eventType ?? "") || existing.status !== options.status || existing.occurredAt.toISOString() !== occurredAt.toISOString() || existing.payloadSha256 !== (options.payloadSha256 ?? "") || existing.signerEvidence !== (options.signerEvidence ?? "[]") || existing.payload !== (options.payload ?? "{}")) throw new Error(`AgreementExecutionEvent dedupe key '${options.dedupeKey}' collides with different verified evidence`);
+	}
+	async findByExecution(executionId) {
+		return await this.list({
+			where: { executionId },
+			orderBy: "occurred_at ASC"
+		});
+	}
+	async findProviderEventsByExecution(executionId) {
+		return await this.list({
+			where: {
+				executionId,
+				eventOrigin: "provider_webhook"
+			},
+			orderBy: "occurred_at ASC"
+		});
+	}
+};
+//#endregion
+//#region src/agreements/models/ExecutedAgreement.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp(target, key, result);
+	return result;
+};
+var persistedAgreementState = /* @__PURE__ */ new WeakMap();
+var ExecutedAgreement = class extends SmrtObject {
+	tenantId = "";
+	executionId = "";
+	sourceKind = "";
+	sourceId = "";
+	sourceVersion = 1;
+	sourceAssetId = "";
+	sourceSha256 = "";
+	sourceSizeBytes = 0;
+	signedDocumentAssetId = "";
+	signedDocumentSha256 = "";
+	signedDocumentSizeBytes = 0;
+	signedDocumentMediaType = "";
+	signedDocumentFilename = "";
+	auditTrailAssetId = "";
+	auditTrailSha256 = "";
+	auditTrailSizeBytes = 0;
+	auditTrailMediaType = "";
+	auditTrailFilename = "";
+	signerEvidence = "[]";
+	acceptedAt = /* @__PURE__ */ new Date();
+	effectiveFrom = null;
+	effectiveTo = null;
+	supersedesExecutedAgreementId = "";
+	metadata = "{}";
+	constructor(options = {}) {
+		super(options);
+		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+		if (options.executionId !== void 0) this.executionId = options.executionId;
+		if (options.sourceKind !== void 0) this.sourceKind = options.sourceKind;
+		if (options.sourceId !== void 0) this.sourceId = options.sourceId;
+		if (options.sourceVersion !== void 0) this.sourceVersion = options.sourceVersion;
+		if (options.sourceAssetId !== void 0) this.sourceAssetId = options.sourceAssetId;
+		if (options.sourceSha256 !== void 0) this.sourceSha256 = options.sourceSha256;
+		if (options.sourceSizeBytes !== void 0) this.sourceSizeBytes = options.sourceSizeBytes;
+		if (options.signedDocumentAssetId !== void 0) this.signedDocumentAssetId = options.signedDocumentAssetId;
+		if (options.signedDocumentSha256 !== void 0) this.signedDocumentSha256 = options.signedDocumentSha256;
+		if (options.signedDocumentSizeBytes !== void 0) this.signedDocumentSizeBytes = options.signedDocumentSizeBytes;
+		if (options.signedDocumentMediaType !== void 0) this.signedDocumentMediaType = options.signedDocumentMediaType;
+		if (options.signedDocumentFilename !== void 0) this.signedDocumentFilename = options.signedDocumentFilename;
+		if (options.auditTrailAssetId !== void 0) this.auditTrailAssetId = options.auditTrailAssetId;
+		if (options.auditTrailSha256 !== void 0) this.auditTrailSha256 = options.auditTrailSha256;
+		if (options.auditTrailSizeBytes !== void 0) this.auditTrailSizeBytes = options.auditTrailSizeBytes;
+		if (options.auditTrailMediaType !== void 0) this.auditTrailMediaType = options.auditTrailMediaType;
+		if (options.auditTrailFilename !== void 0) this.auditTrailFilename = options.auditTrailFilename;
+		if (options.signerEvidence !== void 0) this.signerEvidence = options.signerEvidence;
+		if (options.acceptedAt !== void 0) this.acceptedAt = coerceAgreementDate(options.acceptedAt) ?? /* @__PURE__ */ new Date();
+		if (options.effectiveFrom !== void 0) this.effectiveFrom = coerceAgreementDate(options.effectiveFrom);
+		if (options.effectiveTo !== void 0) this.effectiveTo = coerceAgreementDate(options.effectiveTo);
+		if (options.supersedesExecutedAgreementId !== void 0) this.supersedesExecutedAgreementId = options.supersedesExecutedAgreementId;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	async initialize() {
+		await super.initialize();
+		this.acceptedAt = coerceAgreementDate(this.acceptedAt) ?? /* @__PURE__ */ new Date();
+		this.effectiveFrom = coerceAgreementDate(this.effectiveFrom);
+		this.effectiveTo = coerceAgreementDate(this.effectiveTo);
+		if (this.isPersisted) persistedAgreementState.set(this, this.serializeState());
+		return this;
+	}
+	isEffectiveAt(at) {
+		return !(this.effectiveFrom && at < this.effectiveFrom || this.effectiveTo && at > this.effectiveTo);
+	}
+	async save() {
+		const captured = persistedAgreementState.get(this);
+		if (captured !== void 0 && captured !== this.serializeState()) throw new Error(`ExecutedAgreement ${this.id ?? "<new>"}: executed agreements are immutable; create a versioned amendment`);
+		if (captured === void 0 && !this.isPersisted) this.requireInsertOnSave();
+		const result = await super.save();
+		persistedAgreementState.set(this, this.serializeState());
+		return result;
+	}
+	serializeState() {
+		return JSON.stringify({
+			tenantId: this.tenantId,
+			executionId: this.executionId,
+			sourceKind: this.sourceKind,
+			sourceId: this.sourceId,
+			sourceVersion: this.sourceVersion,
+			sourceAssetId: this.sourceAssetId,
+			sourceSha256: this.sourceSha256,
+			sourceSizeBytes: this.sourceSizeBytes,
+			signedDocumentAssetId: this.signedDocumentAssetId,
+			signedDocumentSha256: this.signedDocumentSha256,
+			signedDocumentSizeBytes: this.signedDocumentSizeBytes,
+			signedDocumentMediaType: this.signedDocumentMediaType,
+			signedDocumentFilename: this.signedDocumentFilename,
+			auditTrailAssetId: this.auditTrailAssetId,
+			auditTrailSha256: this.auditTrailSha256,
+			auditTrailSizeBytes: this.auditTrailSizeBytes,
+			auditTrailMediaType: this.auditTrailMediaType,
+			auditTrailFilename: this.auditTrailFilename,
+			signerEvidence: this.signerEvidence,
+			acceptedAt: this.acceptedAt.toISOString(),
+			effectiveFrom: this.effectiveFrom?.toISOString() ?? null,
+			effectiveTo: this.effectiveTo?.toISOString() ?? null,
+			supersedesExecutedAgreementId: this.supersedesExecutedAgreementId,
+			metadata: this.metadata
+		});
+	}
+};
+__decorateClass([tenantId()], ExecutedAgreement.prototype, "tenantId", 2);
+__decorateClass([foreignKey("AgreementExecution", { required: true })], ExecutedAgreement.prototype, "executionId", 2);
+__decorateClass([field({ required: true })], ExecutedAgreement.prototype, "sourceKind", 2);
+__decorateClass([field({ required: true })], ExecutedAgreement.prototype, "sourceId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-assets:Asset")], ExecutedAgreement.prototype, "sourceAssetId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-assets:Asset")], ExecutedAgreement.prototype, "signedDocumentAssetId", 2);
+__decorateClass([crossPackageRef("@happyvertical/smrt-assets:Asset")], ExecutedAgreement.prototype, "auditTrailAssetId", 2);
+__decorateClass([foreignKey("ExecutedAgreement")], ExecutedAgreement.prototype, "supersedesExecutedAgreementId", 2);
+ExecutedAgreement = __decorateClass([TenantScoped({ mode: "required" }), smrt({
+	conflictColumns: ["tenant_id", "execution_id"],
+	api: { include: ["list", "get"] },
+	mcp: { include: ["list", "get"] },
+	cli: false
+})], ExecutedAgreement);
+//#endregion
+//#region src/agreements/collections/ExecutedAgreementCollection.ts
+var ExecutedAgreementCollection = class extends SmrtCollection {
+	static _itemClass = ExecutedAgreement;
+	async findByExecution(executionId) {
+		return (await this.list({
+			where: { executionId },
+			limit: 1
+		}))[0] ?? null;
+	}
+	async createImmutable(options) {
+		if (!options.executionId) throw new Error("ExecutedAgreement requires an executionId");
+		this.assertCompleteEvidence(options);
+		const existing = await this.findByExecution(options.executionId);
+		if (existing) {
+			this.assertSameEvidence(existing, options);
+			return {
+				agreement: existing,
+				created: false
+			};
+		}
+		const { acceptedAt, effectiveFrom, effectiveTo, ...rest } = options;
+		try {
+			return {
+				agreement: await this.create({
+					...rest,
+					...acceptedAt !== void 0 ? { acceptedAt: coerceAgreementDate(acceptedAt) ?? /* @__PURE__ */ new Date() } : {},
+					...effectiveFrom !== void 0 ? { effectiveFrom: coerceAgreementDate(effectiveFrom) } : {},
+					...effectiveTo !== void 0 ? { effectiveTo: coerceAgreementDate(effectiveTo) } : {},
+					_insertOnly: true
+				}),
+				created: true
+			};
+		} catch (error) {
+			const raced = await this.findByExecution(options.executionId);
+			if (!raced) throw error;
+			this.assertSameEvidence(raced, options);
+			return {
+				agreement: raced,
+				created: false
+			};
+		}
+	}
+	assertSameEvidence(existing, options) {
+		const acceptedAt = coerceAgreementDate(options.acceptedAt);
+		const effectiveFrom = coerceAgreementDate(options.effectiveFrom);
+		const effectiveTo = coerceAgreementDate(options.effectiveTo);
+		if (existing.sourceKind !== options.sourceKind || existing.sourceId !== options.sourceId || existing.sourceVersion !== options.sourceVersion || existing.sourceAssetId !== options.sourceAssetId || existing.sourceSha256 !== (options.sourceSha256 ?? "") || existing.sourceSizeBytes !== options.sourceSizeBytes || existing.signedDocumentAssetId !== options.signedDocumentAssetId || existing.signedDocumentSha256 !== (options.signedDocumentSha256 ?? "") || existing.signedDocumentSizeBytes !== options.signedDocumentSizeBytes || existing.signedDocumentMediaType !== options.signedDocumentMediaType || existing.signedDocumentFilename !== options.signedDocumentFilename || existing.auditTrailAssetId !== options.auditTrailAssetId || existing.auditTrailSha256 !== (options.auditTrailSha256 ?? "") || existing.auditTrailSizeBytes !== options.auditTrailSizeBytes || existing.auditTrailMediaType !== options.auditTrailMediaType || existing.auditTrailFilename !== options.auditTrailFilename || existing.signerEvidence !== options.signerEvidence || existing.acceptedAt.toISOString() !== acceptedAt?.toISOString() || (existing.effectiveFrom?.toISOString() ?? null) !== (effectiveFrom?.toISOString() ?? null) || (existing.effectiveTo?.toISOString() ?? null) !== (effectiveTo?.toISOString() ?? null) || (existing.supersedesExecutedAgreementId ?? "") !== (options.supersedesExecutedAgreementId ?? "") || existing.metadata !== (options.metadata ?? "{}")) throw new Error(`ExecutedAgreement execution '${options.executionId}' collides with different immutable evidence`);
+	}
+	assertCompleteEvidence(options) {
+		for (const [label, value] of [
+			["sourceKind", options.sourceKind],
+			["sourceId", options.sourceId],
+			["sourceAssetId", options.sourceAssetId],
+			["sourceSha256", options.sourceSha256],
+			["signedDocumentAssetId", options.signedDocumentAssetId],
+			["signedDocumentSha256", options.signedDocumentSha256],
+			["signedDocumentMediaType", options.signedDocumentMediaType],
+			["signedDocumentFilename", options.signedDocumentFilename],
+			["auditTrailAssetId", options.auditTrailAssetId],
+			["auditTrailSha256", options.auditTrailSha256],
+			["auditTrailMediaType", options.auditTrailMediaType],
+			["auditTrailFilename", options.auditTrailFilename],
+			["signerEvidence", options.signerEvidence]
+		]) if (typeof value !== "string" || !value) throw new Error(`ExecutedAgreement requires ${label}`);
+		if (typeof options.sourceVersion !== "number" || !Number.isSafeInteger(options.sourceVersion) || options.sourceVersion < 1) throw new Error("ExecutedAgreement requires a positive sourceVersion");
+		for (const [label, value] of [
+			["sourceSizeBytes", options.sourceSizeBytes],
+			["signedDocumentSizeBytes", options.signedDocumentSizeBytes],
+			["auditTrailSizeBytes", options.auditTrailSizeBytes]
+		]) if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) throw new Error(`ExecutedAgreement requires a positive ${label}`);
+		if (!coerceAgreementDate(options.acceptedAt)) throw new Error("ExecutedAgreement requires a valid acceptedAt");
+		try {
+			const signers = JSON.parse(options.signerEvidence ?? "");
+			if (!Array.isArray(signers) || signers.length === 0 || signers.some((signer) => !signer || typeof signer !== "object" || signer.status !== "signed")) throw new Error("incomplete");
+		} catch {
+			throw new Error("ExecutedAgreement requires non-empty signed signerEvidence");
+		}
+	}
+	async findVersionsBySource(sourceKind, sourceId) {
+		return await this.list({
+			where: {
+				sourceKind,
+				sourceId
+			},
+			orderBy: "source_version DESC"
+		});
+	}
+	async effectiveForSource(sourceKind, sourceId, at = /* @__PURE__ */ new Date()) {
+		return (await this.findVersionsBySource(sourceKind, sourceId)).find((agreement) => agreement.isEffectiveAt(at)) ?? null;
+	}
+};
+//#endregion
+//#region src/agreements/services/AgreementExecutionService.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+	"completed",
+	"declined",
+	"cancelled",
+	"expired",
+	"failed"
+]);
+var STATUS_PROGRESS = /* @__PURE__ */ new Map([
+	["prepared", 0],
+	["sent", 1],
+	["delivered", 2],
+	["viewed", 3],
+	["partially_signed", 4]
+]);
+var DEFAULT_CREATE_LEASE_DURATION_MS = 300 * 1e3;
+var AgreementExecutionService = class {
+	constructor(deps) {
+		this.deps = deps;
+		this.now = deps.now ?? (() => /* @__PURE__ */ new Date());
+		this.createLeaseDurationMs = deps.createLeaseDurationMs ?? DEFAULT_CREATE_LEASE_DURATION_MS;
+		if (!Number.isFinite(this.createLeaseDurationMs) || this.createLeaseDurationMs <= 0) throw new Error("Agreement execution create lease must be positive");
+	}
+	deps;
+	now;
+	createLeaseDurationMs;
+	async createExecution(input) {
+		this.assertTenant(input.tenantId);
+		this.assertProviderCapabilities();
+		this.assertCreateInput(input);
+		const sourceBytes = await readByteSource(input.document.data);
+		if (sourceBytes.byteLength === 0) throw new Error("Agreement execution document must not be empty");
+		const sourceSha256 = sha256(sourceBytes);
+		const effectiveFrom = normalizeOptionalAgreementDate(input.effectiveFrom, "effectiveFrom");
+		const effectiveTo = normalizeOptionalAgreementDate(input.effectiveTo, "effectiveTo");
+		if (effectiveFrom && effectiveTo && effectiveTo < effectiveFrom) throw new Error("Agreement execution effectiveTo must not precede effectiveFrom");
+		const requestIntentSha256 = hashRequestIntent(input, this.deps.provider.capabilities.id, sourceSha256, effectiveFrom, effectiveTo);
+		const existing = await this.deps.executions.findByIdempotencyKey(input.idempotencyKey);
+		if (existing) {
+			this.assertSameIntent(existing, input, requestIntentSha256);
+			return await this.resumeOrReplayCreate(existing, input, sourceBytes);
+		}
+		const sourceAsset = await this.deps.assets.storeSourceAsset(input.document.name, sourceBytes, {
+			mimeType: input.document.mediaType,
+			typeSlug: "agreement-source",
+			sourceType: "agreement-execution",
+			externalId: input.idempotencyKey,
+			metadata: {
+				sourceKind: input.sourceKind,
+				sourceId: input.sourceId,
+				sourceVersion: input.sourceVersion,
+				sha256: sourceSha256
+			}
+		});
+		this.assertTenantValue(sourceAsset.tenantId, input.tenantId, "source asset");
+		if (!sourceAsset.id) throw new Error("Stored source Asset has no id");
+		const operationId = randomUUID();
+		const createLeaseExpiresAt = this.newCreateLeaseExpiry();
+		let execution;
+		try {
+			execution = await this.deps.executions.create({
+				tenantId: input.tenantId,
+				provider: this.deps.provider.capabilities.id,
+				providerAccountRef: input.providerAccountRef ?? "",
+				credentialRef: input.credentialRef ?? "",
+				idempotencyKey: input.idempotencyKey,
+				sourceKind: input.sourceKind,
+				sourceId: input.sourceId,
+				sourceVersion: input.sourceVersion,
+				sourceAssetId: sourceAsset.id,
+				sourceSha256,
+				sourceSizeBytes: sourceBytes.byteLength,
+				requestIntentSha256,
+				title: input.title,
+				signerIntent: JSON.stringify(sanitizeSignerIntent(input.signers)),
+				status: "prepared",
+				effectiveFrom,
+				effectiveTo,
+				supersedesExecutedAgreementId: input.supersedesExecutedAgreementId ?? "",
+				metadata: JSON.stringify(input.metadata ?? {}),
+				attemptCount: 1,
+				createLeaseId: operationId,
+				createLeaseExpiresAt,
+				_insertOnly: true
+			});
+		} catch (error) {
+			const raced = await this.deps.executions.findByIdempotencyKey(input.idempotencyKey);
+			if (!raced || raced.sourceAssetId !== sourceAsset.id) await this.removeStoredAsset(sourceAsset);
+			if (!raced) throw error;
+			this.assertSameIntent(raced, input, requestIntentSha256);
+			return await this.resumeOrReplayCreate(raced, input, sourceBytes);
+		}
+		try {
+			await this.ensureAssetAssociation("AgreementExecution", execution.id ?? "", sourceAsset.id, "source_document");
+		} catch (error) {
+			await this.failOwnedCreateAttempt(execution, operationId, summarizeError(error, false));
+			throw error;
+		}
+		return await this.sendProviderRequest(execution, input, sourceBytes, operationId);
+	}
+	async sendProviderRequest(execution, input, sourceBytes, operationId) {
+		if (execution.createLeaseId !== operationId) throw new Error(`AgreementExecution ${execution.id}: provider-create lease is not owned by this operation`);
+		try {
+			await this.recordOperationAudit(execution, operationId, "create.started", "system", { attemptCount: execution.attemptCount });
+		} catch (error) {
+			await this.failOwnedCreateAttempt(execution, operationId, summarizeError(error, false));
+			throw error;
+		}
+		let request;
+		let providerResponded = false;
+		try {
+			request = await this.deps.provider.createRequest({
+				tenantId: input.tenantId,
+				idempotencyKey: input.idempotencyKey,
+				title: input.title,
+				...input.message ? { message: input.message } : {},
+				documents: [{
+					name: input.document.name,
+					mediaType: input.document.mediaType,
+					data: sourceBytes
+				}],
+				signers: input.signers,
+				...input.signingOrder !== void 0 ? { signingOrder: input.signingOrder } : {},
+				...input.expiresInDays !== void 0 ? { expiresInDays: input.expiresInDays } : {},
+				metadata: {
+					...input.metadata ?? {},
+					smrtExecutionId: execution.id ?? "",
+					smrtSourceKind: input.sourceKind,
+					smrtSourceId: input.sourceId,
+					smrtSourceVersion: String(input.sourceVersion),
+					smrtSourceSha256: execution.sourceSha256
+				},
+				...input.signal ? { signal: input.signal } : {}
+			});
+			providerResponded = true;
+			this.assertProviderRequest(request, input.tenantId);
+			await this.assertProviderRequestAvailable(execution, request.id);
+			const completed = await this.deps.executions.completeCreateAttempt({
+				tenantId: input.tenantId,
+				executionId: execution.id ?? "",
+				operationId,
+				provider: execution.provider,
+				providerRequestId: request.id,
+				status: request.status,
+				expiresAt: request.expiresAt ?? null
+			});
+			if (completed) execution = completed;
+			else {
+				const latest = await this.requireExecution(execution.id ?? "");
+				if (latest.providerRequestId !== request.id) throw new Error(`AgreementExecution ${execution.id}: provider-create lease ownership changed before the provider result was persisted; reconcile the current attempt`);
+				execution = latest;
+			}
+		} catch (error) {
+			const mayHaveSucceeded = providerResponded || requestMayHaveSucceeded(error);
+			const lastError = summarizeError(error, mayHaveSucceeded);
+			execution = await this.failOwnedCreateAttempt(execution, operationId, lastError);
+			await this.recordOperationAudit(execution, operationId, mayHaveSucceeded ? "create.uncertain" : "create.failed", "provider_operation", { error: lastError });
+			throw error;
+		}
+		await this.recordOperationAudit(execution, operationId, "create.succeeded", "provider_operation", { providerRequestId: request.id });
+		return this.result(execution, execution.attemptCount > 1);
+	}
+	async resumeOrReplayCreate(execution, input, sourceBytes) {
+		if (execution.providerRequestId) return this.result(execution, true);
+		const now = this.now();
+		if (this.isCreateLeaseActive(execution, now)) return this.result(execution, true);
+		const abandonedCreate = this.isAbandonedCreate(execution);
+		if (abandonedCreate && !this.deps.provider.capabilities.providerEnforcedIdempotency) throw new Error(`AgreementExecution ${execution.id}: the provider-create lease expired without a confirmed request id; reconcile or adopt the provider request before retrying`);
+		if (!abandonedCreate && !this.canSafelyRetryCreate(execution)) throw new Error(`AgreementExecution ${execution.id}: the prior provider create has no confirmed request id; reconcile or adopt the provider request before retrying`);
+		await this.ensureAssetAssociation("AgreementExecution", execution.id ?? "", execution.sourceAssetId, "source_document");
+		const operationId = randomUUID();
+		const claimed = await this.deps.executions.claimCreateAttempt({
+			tenantId: input.tenantId,
+			executionId: execution.id ?? "",
+			expectedAttemptCount: execution.attemptCount,
+			expectedLeaseId: execution.createLeaseId,
+			expectedStatus: execution.status,
+			expectedLastError: execution.lastError,
+			operationId,
+			leaseExpiresAt: this.newCreateLeaseExpiry(now),
+			now
+		});
+		if (!claimed) {
+			const latest = await this.requireExecution(execution.id ?? "");
+			if (latest.providerRequestId || this.isCreateLeaseActive(latest, this.now())) return this.result(latest, true);
+			throw new Error(`AgreementExecution ${execution.id}: provider-create state changed while claiming recovery; retry the operation`);
+		}
+		return await this.sendProviderRequest(claimed, input, sourceBytes, operationId);
+	}
+	/**
+	* Bind an operator-reconciled provider request after an uncertain create.
+	* This is the safe recovery path for providers without atomic idempotency.
+	*/
+	async adoptProviderRequest(input) {
+		this.assertTenant(input.tenantId);
+		let execution = await this.requireExecution(input.executionId);
+		if (execution.providerRequestId && execution.providerRequestId !== input.providerRequestId) throw new Error(`AgreementExecution ${execution.id} is already bound to a different provider request`);
+		const started = await this.beginAuditedOperation(execution, "adopt", "operator");
+		execution = started.execution;
+		const { operationId } = started;
+		try {
+			const request = await this.deps.provider.getRequest({
+				tenantId: input.tenantId,
+				requestId: input.providerRequestId,
+				...input.signal ? { signal: input.signal } : {}
+			});
+			this.assertProviderRequest(request, input.tenantId, input.providerRequestId);
+			await this.assertProviderRequestAvailable(execution, request.id);
+			const linkedExecutionId = request.metadata?.smrtExecutionId;
+			if (linkedExecutionId && linkedExecutionId !== execution.id) throw new Error(`Provider request '${request.id}' belongs to a different agreement execution`);
+			execution = await this.bindProviderRequest(execution, request.id);
+			const observedAt = this.now();
+			execution = await this.applyProviderState(execution, request, observedAt, { lastReconciledAt: observedAt });
+			await this.completeAuditedOperation(execution, operationId, "adopt", { providerRequestId: request.id });
+			return this.result(execution, false);
+		} catch (error) {
+			await this.failAuditedOperation(execution, operationId, "adopt", error, false);
+			throw error;
+		}
+	}
+	async reconcile(input) {
+		this.assertTenant(input.tenantId);
+		let execution = await this.requireExecution(input.executionId);
+		this.requireProviderRequestId(execution);
+		const started = await this.beginAuditedOperation(execution, "reconcile", "system");
+		execution = started.execution;
+		const { operationId } = started;
+		try {
+			const request = await this.deps.provider.getRequest({
+				tenantId: input.tenantId,
+				requestId: execution.providerRequestId,
+				...input.signal ? { signal: input.signal } : {}
+			});
+			this.assertProviderRequest(request, input.tenantId, execution.providerRequestId);
+			const observedAt = this.now();
+			execution = await this.applyProviderState(execution, request, observedAt, { lastReconciledAt: observedAt });
+			if (execution.status === "completed") await this.finalizeExecution(execution);
+			await this.completeAuditedOperation(execution, operationId, "reconcile", { providerStatus: request.status });
+			return this.result(execution, false);
+		} catch (error) {
+			await this.failAuditedOperation(execution, operationId, "reconcile", error, false);
+			throw error;
+		}
+	}
+	async cancel(input) {
+		this.assertTenant(input.tenantId);
+		if (!input.reason.trim()) throw new Error("Cancellation reason is required");
+		let execution = await this.requireExecution(input.executionId);
+		this.requireProviderRequestId(execution);
+		if (execution.status === "cancelled") return this.result(execution, true);
+		this.assertNonTerminalOperation(execution, "cancel");
+		const started = await this.beginAuditedOperation(execution, "cancel", "operator", { reason: input.reason });
+		execution = started.execution;
+		const { operationId } = started;
+		let providerResponded = false;
+		try {
+			this.assertNonTerminalOperation(execution, "cancel");
+			const request = await this.deps.provider.cancelRequest({
+				tenantId: input.tenantId,
+				requestId: execution.providerRequestId,
+				reason: input.reason,
+				...input.signal ? { signal: input.signal } : {}
+			});
+			providerResponded = true;
+			this.assertProviderRequest(request, input.tenantId, execution.providerRequestId);
+			execution = await this.applyProviderState(execution, request, this.now(), { cancellationReason: input.reason });
+			await this.completeAuditedOperation(execution, operationId, "cancel", { providerStatus: request.status });
+			return this.result(execution, false);
+		} catch (error) {
+			await this.failAuditedOperation(execution, operationId, "cancel", error, true, providerResponded);
+			throw error;
+		}
+	}
+	async extendExpiry(input) {
+		this.assertTenant(input.tenantId);
+		let execution = await this.requireExecution(input.executionId);
+		this.requireProviderRequestId(execution);
+		this.assertNonTerminalOperation(execution, "extend expiry for");
+		const started = await this.beginAuditedOperation(execution, "extend_expiry", "operator", { expiresAt: normalizeRequiredAgreementDate(input.expiresAt).toISOString() });
+		execution = started.execution;
+		const { operationId } = started;
+		let providerResponded = false;
+		try {
+			this.assertNonTerminalOperation(execution, "extend expiry for");
+			const request = await this.deps.provider.extendExpiry({
+				tenantId: input.tenantId,
+				requestId: execution.providerRequestId,
+				expiresAt: input.expiresAt,
+				...input.warnPrior !== void 0 ? { warnPrior: input.warnPrior } : {},
+				...input.signal ? { signal: input.signal } : {}
+			});
+			providerResponded = true;
+			this.assertProviderRequest(request, input.tenantId, execution.providerRequestId);
+			execution = await this.applyProviderState(execution, request, this.now());
+			await this.completeAuditedOperation(execution, operationId, "extend_expiry", { expiresAt: request.expiresAt?.toISOString() ?? null });
+			return this.result(execution, false);
+		} catch (error) {
+			await this.failAuditedOperation(execution, operationId, "extend_expiry", error, true, providerResponded);
+			throw error;
+		}
+	}
+	async ingestWebhook(input) {
+		this.assertTenant(input.tenantId);
+		const providerEvent = this.deps.provider.parseWebhook({
+			payload: input.payload,
+			signature: input.signature
+		});
+		this.assertTenantValue(providerEvent.tenantId, input.tenantId, "verified webhook");
+		if (providerEvent.provider !== this.deps.provider.capabilities.id) throw new Error("Verified webhook provider does not match the adapter");
+		let execution = await this.deps.executions.findByProviderRequest(providerEvent.provider, providerEvent.requestId);
+		if (!execution) throw new Error(`No AgreementExecution is bound to provider request '${providerEvent.requestId}'`);
+		const dedupeKey = `${input.tenantId}:${providerEvent.provider}:${providerEvent.replay.deduplicationKey}`;
+		const recorded = await this.deps.events.recordVerified({
+			tenantId: input.tenantId,
+			executionId: execution.id ?? "",
+			provider: providerEvent.provider,
+			providerEventId: providerEvent.id,
+			eventOrigin: "provider_webhook",
+			dedupeKey,
+			orderingKey: providerEvent.replay.orderingKey,
+			eventType: providerEvent.type,
+			status: providerEvent.status,
+			occurredAt: providerEvent.createdAt,
+			receivedAt: this.now(),
+			payloadSha256: sha256(Buffer.from(input.payload, "utf8")),
+			signerEvidence: JSON.stringify(sanitizeSignerEvidence(providerEvent.signers)),
+			payload: input.payload
+		});
+		execution = await this.persistLifecycleState(execution, {
+			status: providerEvent.status,
+			observedAt: providerEvent.createdAt,
+			completedAt: providerEvent.status === "completed" ? providerEvent.createdAt : void 0
+		});
+		let executedAgreement = null;
+		if (execution.status === "completed") {
+			const started = await this.beginAuditedOperation(execution, "finalize", "system", { providerEventId: providerEvent.id });
+			execution = started.execution;
+			const { operationId } = started;
+			try {
+				executedAgreement = await this.finalizeExecution(execution, providerEvent);
+				await this.completeAuditedOperation(execution, operationId, "finalize", { executedAgreementId: executedAgreement.id ?? "" });
+			} catch (error) {
+				await this.failAuditedOperation(execution, operationId, "finalize", error, false);
+				throw error;
+			}
+		}
+		return {
+			executionId: execution.id ?? "",
+			eventId: recorded.event.id ?? "",
+			replayed: !recorded.created,
+			...executedAgreement?.id ? { executedAgreementId: executedAgreement.id } : {}
+		};
+	}
+	async finalizeExecution(execution, verifiedEvent) {
+		this.assertTenant(execution.tenantId);
+		const existing = await this.deps.executedAgreements.findByExecution(execution.id ?? "");
+		if (existing) {
+			await this.ensureExecutedAgreementAssociations(existing);
+			return existing;
+		}
+		this.requireProviderRequestId(execution);
+		const request = await this.deps.provider.getRequest({
+			tenantId: execution.tenantId,
+			requestId: execution.providerRequestId
+		});
+		this.assertProviderRequest(request, execution.tenantId, execution.providerRequestId);
+		if (request.status !== "completed") throw new Error(`Provider request '${request.id}' is '${request.status}', not completed`);
+		execution = (await this.ensureEvidenceArtifact(execution, "signed_document")).execution;
+		const auditResult = await this.ensureEvidenceArtifact(execution, "audit_trail");
+		execution = await this.requireExecution(auditResult.execution.id ?? "");
+		const signed = this.requireStoredArtifactMetadata(execution, "signed_document");
+		const audit = this.requireStoredArtifactMetadata(execution, "audit_trail");
+		const signerEvidence = sanitizeSignerEvidence(request.signers);
+		const acceptedAt = execution.completedAt ?? verifiedEvent?.createdAt ?? this.now();
+		const created = await this.deps.executedAgreements.createImmutable({
+			tenantId: execution.tenantId,
+			executionId: execution.id ?? "",
+			sourceKind: execution.sourceKind,
+			sourceId: execution.sourceId,
+			sourceVersion: execution.sourceVersion,
+			sourceAssetId: execution.sourceAssetId,
+			sourceSha256: execution.sourceSha256,
+			sourceSizeBytes: execution.sourceSizeBytes,
+			signedDocumentAssetId: signed.assetId,
+			signedDocumentSha256: signed.sha256,
+			signedDocumentSizeBytes: signed.sizeBytes,
+			signedDocumentMediaType: signed.mediaType,
+			signedDocumentFilename: signed.filename,
+			auditTrailAssetId: audit.assetId,
+			auditTrailSha256: audit.sha256,
+			auditTrailSizeBytes: audit.sizeBytes,
+			auditTrailMediaType: audit.mediaType,
+			auditTrailFilename: audit.filename,
+			signerEvidence: JSON.stringify(signerEvidence),
+			acceptedAt,
+			effectiveFrom: execution.effectiveFrom ?? acceptedAt,
+			effectiveTo: execution.effectiveTo,
+			supersedesExecutedAgreementId: execution.supersedesExecutedAgreementId,
+			metadata: execution.metadata
+		});
+		await this.ensureExecutedAgreementAssociations(created.agreement);
+		return created.agreement;
+	}
+	async ensureEvidenceArtifact(execution, kind) {
+		const existing = this.getStoredArtifactMetadata(execution, kind);
+		if (existing) {
+			await this.ensureAssetAssociation("AgreementExecution", execution.id ?? "", existing.assetId, kind);
+			return {
+				execution,
+				metadata: existing
+			};
+		}
+		const stored = await this.retrieveAndStoreArtifact(execution, kind);
+		let bound;
+		try {
+			bound = await this.deps.executions.bindEvidenceArtifact({
+				tenantId: execution.tenantId,
+				executionId: execution.id ?? "",
+				kind,
+				...stored.metadata
+			});
+		} catch (error) {
+			const latest = await this.requireExecution(execution.id ?? "");
+			if (this.getStoredArtifactMetadata(latest, kind)?.assetId !== stored.asset.id) await this.removeStoredAsset(stored.asset);
+			throw error;
+		}
+		if (!bound) {
+			await this.removeStoredAsset(stored.asset);
+			bound = await this.requireExecution(execution.id ?? "");
+		}
+		const metadata = this.requireStoredArtifactMetadata(bound, kind);
+		await this.ensureAssetAssociation("AgreementExecution", bound.id ?? "", metadata.assetId, kind);
+		return {
+			execution: bound,
+			metadata
+		};
+	}
+	async retrieveAndStoreArtifact(execution, kind) {
+		const artifact = await this.deps.provider.downloadArtifact({
+			tenantId: execution.tenantId,
+			requestId: execution.providerRequestId,
+			kind
+		});
+		this.assertArtifact(artifact, execution, kind);
+		const bytes = await readReadableStream(artifact.stream);
+		if (bytes.byteLength === 0) throw new Error(`Downloaded ${kind} artifact was empty`);
+		const computed = sha256(bytes);
+		if (computed !== (await artifact.sha256).toLowerCase()) throw new Error(`Downloaded ${kind} hash did not match the SDK evidence hash`);
+		const asset = await this.deps.assets.storeSourceAsset(artifact.filename, bytes, {
+			mimeType: artifact.mediaType,
+			typeSlug: "agreement-evidence",
+			sourceType: execution.provider,
+			externalId: `${execution.providerRequestId}:${kind}`,
+			metadata: {
+				executionId: execution.id,
+				provider: execution.provider,
+				providerRequestId: execution.providerRequestId,
+				artifactKind: kind,
+				sha256: computed,
+				retrievedAt: artifact.retrievedAt.toISOString()
+			}
+		});
+		this.assertTenantValue(asset.tenantId, execution.tenantId, `${kind} asset`);
+		if (!asset.id) throw new Error(`Stored ${kind} Asset has no id`);
+		return {
+			asset,
+			metadata: {
+				assetId: asset.id,
+				sha256: computed,
+				sizeBytes: bytes.byteLength,
+				filename: artifact.filename,
+				mediaType: artifact.mediaType
+			}
+		};
+	}
+	getStoredArtifactMetadata(execution, kind) {
+		const metadata = kind === "signed_document" ? {
+			assetId: execution.signedDocumentAssetId,
+			sha256: execution.signedDocumentSha256,
+			sizeBytes: execution.signedDocumentSizeBytes,
+			mediaType: execution.signedDocumentMediaType,
+			filename: execution.signedDocumentFilename
+		} : {
+			assetId: execution.auditTrailAssetId,
+			sha256: execution.auditTrailSha256,
+			sizeBytes: execution.auditTrailSizeBytes,
+			mediaType: execution.auditTrailMediaType,
+			filename: execution.auditTrailFilename
+		};
+		if (!metadata.assetId) return null;
+		if (!metadata.sha256 || !Number.isSafeInteger(metadata.sizeBytes) || metadata.sizeBytes < 1 || !metadata.mediaType || !metadata.filename) throw new Error(`AgreementExecution ${execution.id}: ${kind} evidence is incomplete`);
+		return metadata;
+	}
+	requireStoredArtifactMetadata(execution, kind) {
+		const metadata = this.getStoredArtifactMetadata(execution, kind);
+		if (!metadata) throw new Error(`AgreementExecution ${execution.id}: ${kind} evidence was not bound`);
+		return metadata;
+	}
+	async removeStoredAsset(asset) {
+		await this.deps.assets.store.remove(asset);
+	}
+	async ensureExecutedAgreementAssociations(agreement) {
+		if (!agreement.id) throw new Error("ExecutedAgreement has no id");
+		await this.ensureAssetAssociation("ExecutedAgreement", agreement.id, agreement.sourceAssetId, "source_document");
+		await this.ensureAssetAssociation("ExecutedAgreement", agreement.id, agreement.signedDocumentAssetId, "signed_document");
+		await this.ensureAssetAssociation("ExecutedAgreement", agreement.id, agreement.auditTrailAssetId, "audit_trail");
+	}
+	async applyProviderState(execution, request, observedAt, options = {}) {
+		return await this.persistLifecycleState(execution, {
+			status: request.status,
+			observedAt,
+			enforceEventOrder: false,
+			...request.expiresAt ? { expiresAt: request.expiresAt } : {},
+			...options.cancellationReason !== void 0 ? { cancellationReason: options.cancellationReason } : {},
+			...options.lastReconciledAt ? { lastReconciledAt: options.lastReconciledAt } : {},
+			...request.status === "completed" ? { completedAt: observedAt } : {}
+		});
+	}
+	async persistLifecycleState(execution, input) {
+		const executionId = execution.id ?? "";
+		let current = await this.requireExecution(executionId);
+		for (let attempt = 0; attempt < 8; attempt += 1) {
+			if (input.enforceEventOrder !== false && current.lastProviderEventAt && input.observedAt < current.lastProviderEventAt) return current;
+			if (!canAdvanceStatus(current.status, input.status)) return current;
+			const persistedObservedAt = input.enforceEventOrder === false && current.lastProviderEventAt && current.lastProviderEventAt > input.observedAt ? current.lastProviderEventAt : input.observedAt;
+			const updated = await this.deps.executions.compareAndSetLifecycle({
+				tenantId: current.tenantId,
+				executionId,
+				expectedStatus: current.status,
+				status: input.status,
+				expiresAt: input.expiresAt ?? current.expiresAt,
+				cancellationReason: input.cancellationReason ?? current.cancellationReason,
+				lastProviderEventAt: persistedObservedAt,
+				lastReconciledAt: input.lastReconciledAt ?? current.lastReconciledAt,
+				completedAt: input.status === "completed" ? current.completedAt ?? input.completedAt ?? input.observedAt : current.completedAt
+			});
+			if (updated) return updated;
+			current = await this.requireExecution(executionId);
+		}
+		throw new Error(`AgreementExecution ${executionId}: lifecycle state remained contended; retry the operation`);
+	}
+	assertProviderRequest(request, tenantId, expectedRequestId) {
+		this.assertTenantValue(request.tenantId, tenantId, "provider request");
+		if (request.provider !== this.deps.provider.capabilities.id) throw new Error("Provider request does not match the configured adapter");
+		if (!request.id) throw new Error("Provider request has no id");
+		if (expectedRequestId && request.id !== expectedRequestId) throw new Error(`Provider returned request '${request.id}' while '${expectedRequestId}' was requested`);
+	}
+	assertArtifact(artifact, execution, kind) {
+		this.assertTenantValue(artifact.tenantId, execution.tenantId, kind);
+		if (artifact.provider !== execution.provider || artifact.requestId !== execution.providerRequestId || artifact.kind !== kind) throw new Error(`Downloaded ${kind} does not match its execution`);
+	}
+	assertProviderCapabilities() {
+		const caps = this.deps.provider.capabilities;
+		if (!caps.supportsWebhooks || !caps.supportsCancellation || !caps.supportsExpiryExtension || !caps.supportsSignedDocument || !caps.supportsAuditTrail) throw new Error(`Signature provider '${caps.id}' lacks required agreement-execution capabilities`);
+	}
+	assertSameIntent(existing, input, requestIntentSha256) {
+		if (existing.provider !== this.deps.provider.capabilities.id || existing.sourceKind !== input.sourceKind || existing.sourceId !== input.sourceId || existing.sourceVersion !== input.sourceVersion || existing.title !== input.title || existing.requestIntentSha256 !== requestIntentSha256) throw new Error(`Idempotency key '${input.idempotencyKey}' belongs to a different agreement execution`);
+	}
+	assertCreateInput(input) {
+		for (const [label, value] of [
+			["idempotencyKey", input.idempotencyKey],
+			["sourceKind", input.sourceKind],
+			["sourceId", input.sourceId],
+			["title", input.title],
+			["document.name", input.document.name],
+			["document.mediaType", input.document.mediaType]
+		]) if (!value.trim()) throw new Error(`Agreement execution ${label} is required`);
+		if (!Number.isSafeInteger(input.sourceVersion) || input.sourceVersion < 1) throw new Error("Agreement execution sourceVersion must be a positive integer");
+		if (input.expiresInDays !== void 0 && (!Number.isSafeInteger(input.expiresInDays) || input.expiresInDays < 1)) throw new Error("Agreement execution expiresInDays must be a positive integer");
+		if (input.credentialRef && !/^[a-z][a-z0-9+.-]*:\/\//i.test(input.credentialRef)) throw new Error("Agreement execution credentialRef must be a secret-store reference URI");
+		if (input.signers.length === 0) throw new Error("Agreement execution requires at least one signer");
+	}
+	async requireExecution(id) {
+		const execution = await this.deps.executions.get({ id });
+		if (!execution) throw new Error(`AgreementExecution '${id}' was not found`);
+		return execution;
+	}
+	requireProviderRequestId(execution) {
+		if (!execution.providerRequestId) throw new Error(`AgreementExecution ${execution.id}: provider request is not confirmed; reconcile or adopt it first`);
+	}
+	async assertProviderRequestAvailable(execution, providerRequestId) {
+		const bound = await this.deps.executions.findByProviderRequest(execution.provider, providerRequestId);
+		if (bound && bound.id !== execution.id) throw new Error(`Provider request '${providerRequestId}' is already bound to another AgreementExecution`);
+	}
+	async bindProviderRequest(execution, providerRequestId) {
+		if (execution.providerRequestId === providerRequestId) return execution;
+		const bound = await this.deps.executions.bindProviderRequest({
+			tenantId: execution.tenantId,
+			executionId: execution.id ?? "",
+			provider: execution.provider,
+			providerRequestId
+		});
+		if (!bound) {
+			const current = await this.requireExecution(execution.id ?? "");
+			if (current.providerRequestId === providerRequestId) return current;
+			throw new Error(`AgreementExecution ${execution.id}: provider request binding changed concurrently`);
+		}
+		return bound;
+	}
+	canSafelyRetryCreate(execution) {
+		if (execution.attemptCount === 0 && execution.status === "prepared") return true;
+		try {
+			return JSON.parse(execution.lastError).requestMayHaveSucceeded === false;
+		} catch {
+			return false;
+		}
+	}
+	isAbandonedCreate(execution) {
+		return execution.status === "prepared" && execution.attemptCount > 0 && !execution.providerRequestId && !execution.lastError;
+	}
+	isCreateLeaseActive(execution, at) {
+		return Boolean(this.isAbandonedCreate(execution) && execution.createLeaseId && execution.createLeaseExpiresAt && execution.createLeaseExpiresAt.getTime() > at.getTime());
+	}
+	newCreateLeaseExpiry(from = this.now()) {
+		return new Date(from.getTime() + this.createLeaseDurationMs);
+	}
+	async failOwnedCreateAttempt(execution, operationId, lastError) {
+		return await this.deps.executions.failCreateAttempt({
+			tenantId: execution.tenantId,
+			executionId: execution.id ?? "",
+			operationId,
+			lastError
+		}) ?? await this.requireExecution(execution.id ?? "");
+	}
+	async ensureAssetAssociation(ownerType, ownerId, assetId, role) {
+		if (!ownerId || !assetId) throw new Error(`Cannot link ${role}: owner and Asset ids are required`);
+		await this.deps.assets.associations.attach(`@happyvertical/smrt-sales:${ownerType}`, ownerId, assetId, { role });
+	}
+	async beginAuditedOperation(execution, operation, origin, metadata = {}) {
+		const current = await this.deps.executions.incrementAttemptCount(execution.tenantId, execution.id ?? "");
+		const operationId = randomUUID();
+		try {
+			await this.recordOperationAudit(current, operationId, `${operation}.started`, origin, {
+				attemptCount: current.attemptCount,
+				...metadata
+			});
+		} catch (error) {
+			await this.deps.executions.updateLastError({
+				tenantId: current.tenantId,
+				executionId: current.id ?? "",
+				lastError: summarizeError(error, false)
+			});
+			throw error;
+		}
+		return {
+			execution: current,
+			operationId
+		};
+	}
+	async completeAuditedOperation(execution, operationId, operation, metadata) {
+		await this.recordOperationAudit(execution, operationId, `${operation}.succeeded`, "provider_operation", metadata);
+	}
+	async failAuditedOperation(execution, operationId, operation, error, mayMutateProvider, providerMutationConfirmed = false) {
+		const current = await this.deps.executions.updateLastError({
+			tenantId: execution.tenantId,
+			executionId: execution.id ?? "",
+			lastError: summarizeError(error)
+		});
+		const uncertain = mayMutateProvider && (providerMutationConfirmed || isPotentiallyUncertain(error));
+		await this.recordOperationAudit(current, operationId, `${operation}.${uncertain ? "uncertain" : "failed"}`, "provider_operation", { error: current.lastError });
+	}
+	async recordOperationAudit(execution, operationId, eventType, eventOrigin, metadata) {
+		const occurredAt = this.now();
+		const payload = JSON.stringify(metadata);
+		await this.deps.events.recordVerified({
+			tenantId: execution.tenantId,
+			executionId: execution.id ?? "",
+			provider: execution.provider,
+			providerEventId: "",
+			eventOrigin,
+			operationId,
+			dedupeKey: `${execution.tenantId}:${execution.provider}:operation:${operationId}:${eventType}`,
+			orderingKey: execution.providerRequestId || execution.id || operationId,
+			eventType: `operation.${eventType}`,
+			status: execution.status,
+			occurredAt,
+			receivedAt: occurredAt,
+			payloadSha256: sha256(Buffer.from(payload, "utf8")),
+			signerEvidence: "[]",
+			payload
+		});
+	}
+	assertNonTerminalOperation(execution, operation) {
+		if (TERMINAL_STATUSES.has(execution.status)) throw new Error(`Cannot ${operation} terminal AgreementExecution ${execution.id} in status '${execution.status}'`);
+	}
+	result(execution, replayed) {
+		return {
+			executionId: execution.id ?? "",
+			...execution.providerRequestId ? { providerRequestId: execution.providerRequestId } : {},
+			status: execution.status,
+			replayed
+		};
+	}
+	assertTenant(expected) {
+		this.assertTenantValue(requireTenantId(), expected, "tenant context");
+	}
+	assertTenantValue(actual, expected, context) {
+		if (actual !== expected) throw new Error(`Agreement execution tenant mismatch for ${context}: expected '${expected}'`);
+	}
+};
+function sha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+function hashRequestIntent(input, provider, sourceSha256, effectiveFrom, effectiveTo) {
+	const sortedMetadata = Object.fromEntries(Object.entries(input.metadata ?? {}).sort(([left], [right]) => left.localeCompare(right)));
+	return sha256(Buffer.from(JSON.stringify({
+		provider,
+		providerAccountRef: input.providerAccountRef ?? "",
+		credentialRef: input.credentialRef ?? "",
+		sourceKind: input.sourceKind,
+		sourceId: input.sourceId,
+		sourceVersion: input.sourceVersion,
+		sourceSha256,
+		documentName: input.document.name,
+		documentMediaType: input.document.mediaType,
+		title: input.title,
+		messageSha256: input.message ? sha256(Buffer.from(input.message, "utf8")) : "",
+		signers: input.signers.map((signer) => ({
+			...sanitizeSignerIntent([signer])[0],
+			privateMessageSha256: signer.privateMessage ? sha256(Buffer.from(signer.privateMessage, "utf8")) : "",
+			phoneSha256: signer.authentication?.phone ? sha256(Buffer.from(`${signer.authentication.phone.countryCode}:${signer.authentication.phone.number}`, "utf8")) : "",
+			identityVerification: signer.authentication?.identityVerification ?? null,
+			fields: signer.fields.map((field) => ({
+				id: field.id,
+				type: field.type,
+				page: field.page,
+				bounds: field.bounds,
+				required: field.required ?? true,
+				valueSha256: field.value ? sha256(Buffer.from(field.value, "utf8")) : ""
+			}))
+		})),
+		signingOrder: input.signingOrder ?? false,
+		expiresInDays: input.expiresInDays ?? null,
+		effectiveFrom: effectiveFrom?.toISOString() ?? null,
+		effectiveTo: effectiveTo?.toISOString() ?? null,
+		supersedesExecutedAgreementId: input.supersedesExecutedAgreementId ?? "",
+		metadata: sortedMetadata
+	}), "utf8"));
+}
+function normalizeOptionalAgreementDate(value, label) {
+	if (value == null) return null;
+	const date = coerceAgreementDate(value);
+	if (!date) throw new Error(`Agreement execution ${label} is invalid`);
+	return date;
+}
+function normalizeRequiredAgreementDate(value) {
+	const date = coerceAgreementDate(value);
+	if (!date) throw new Error("Agreement execution expiresAt is invalid");
+	return date;
+}
+async function readByteSource(source) {
+	if (source instanceof Uint8Array) return Buffer.from(source);
+	if (isReadableStream(source)) return await readReadableStream(source);
+	const chunks = [];
+	for await (const chunk of source) chunks.push(chunk);
+	return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
+}
+async function readReadableStream(stream) {
+	const reader = stream.getReader();
+	const chunks = [];
+	try {
+		while (true) {
+			const result = await reader.read();
+			if (result.done) break;
+			chunks.push(Buffer.from(result.value));
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return Buffer.concat(chunks);
+}
+function isReadableStream(value) {
+	return typeof value.getReader === "function";
+}
+function summarizeError(error, requestMayHaveSucceededOverride) {
+	const candidate = error && typeof error === "object" ? error : {};
+	return JSON.stringify({
+		name: typeof candidate.name === "string" ? candidate.name : "Error",
+		...typeof candidate.code === "string" ? { code: candidate.code } : {},
+		...typeof candidate.status === "number" ? { status: candidate.status } : {},
+		...typeof candidate.retryable === "boolean" ? { retryable: candidate.retryable } : {},
+		...requestMayHaveSucceededOverride !== void 0 ? { requestMayHaveSucceeded: requestMayHaveSucceededOverride } : typeof candidate.requestMayHaveSucceeded === "boolean" ? { requestMayHaveSucceeded: candidate.requestMayHaveSucceeded } : {}
+	});
+}
+function requestMayHaveSucceeded(error) {
+	return Boolean(error && typeof error === "object" && error.requestMayHaveSucceeded === true);
+}
+function isPotentiallyUncertain(error) {
+	if (requestMayHaveSucceeded(error)) return true;
+	return Boolean(error && typeof error === "object" && error.retryable === true);
+}
+function canAdvanceStatus(current, next) {
+	if (current === next) return true;
+	if (current === "failed") return true;
+	if (TERMINAL_STATUSES.has(current)) return false;
+	if (TERMINAL_STATUSES.has(next)) return true;
+	return (STATUS_PROGRESS.get(next) ?? -1) >= (STATUS_PROGRESS.get(current) ?? -1);
+}
+//#endregion
+export { AgreementExecutionEvent as a, AGREEMENT_EXECUTION_STATUSES as c, sanitizeSignerIntent as d, AgreementExecutionEventCollection as i, coerceAgreementDate as l, ExecutedAgreementCollection as n, AgreementExecutionCollection as o, ExecutedAgreement as r, AgreementExecution as s, AgreementExecutionService as t, sanitizeSignerEvidence as u };
+
+//# sourceMappingURL=agreements-DbzW1Pcq.js.map