@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

package/apps/storefront/src/lib/apps/consentConfigStore.ts

@@ -0,0 +1,228 @@
+/**
+ * The merchant consent configuration store — the durable spine behind ext-admin-03.
+ * It persists a tenant's consent configuration as an APPEND-ONLY revision history and
+ * the demonstrated-CMP-demand ledger, and reads back exactly the shapes the pure
+ * ext-policy-03 layer consumes.
+ *
+ * Two acceptance properties are schema-level, not conventions:
+ *   - AUDITED — every save is a new immutable revision that names its actor and time;
+ *     nothing is mutated in place, so the revision list IS the audit trail.
+ *   - REVERSIBLE — a revert is a forward-only new revision that copies a prior config
+ *     and records `revertedFrom`; history is never rewritten, and rolling back leaves
+ *     its own audited entry.
+ *
+ * Pure over the `Queryable` seam (same shape `CandidateStore`/`OrdersStore` use), so it
+ * runs unchanged against real D1 in the Worker (`fromD1(env.STOREFRONT_APPS_DB)`) and an
+ * in-memory `node:sqlite` in tests. This is the DATA MODEL + repository API only — the
+ * validation (`validateConsentConfig`) and the broker materialization
+ * (`toTenantConsentPolicy`/`buildTenantConsentBroker`) live in `@tot/public-runtime`;
+ * this store persists already-validated JSON and never re-derives policy.
+ */
+import type { Queryable } from "../d1/catalog.js";
+import type { CmpDemandLedger, TenantConsentConfig } from "@tot/public-runtime";
+
+/** One persisted consent-config revision — an immutable audit-trail entry. */
+export interface ConsentConfigRevision {
+  id: string;
+  tenantId: string;
+  /** Monotonic per tenant; the largest is the current config. */
+  revision: number;
+  config: TenantConsentConfig;
+  /** Opaque actor id — never PII. */
+  actor: string;
+  note: string | null;
+  /** The source revision when this one is a revert, else null. */
+  revertedFrom: number | null;
+  createdAt: string;
+}
+
+/** Save a new revision of a tenant's (already-validated) consent configuration. */
+export interface SaveConsentConfigInput {
+  tenantId: string;
+  config: TenantConsentConfig;
+  actor: string;
+  note?: string | null;
+}
+
+/** Revert a tenant's consent configuration to a prior revision (forward-only). */
+export interface RevertConsentConfigInput {
+  tenantId: string;
+  /** The revision whose config to restore as a NEW revision. */
+  toRevision: number;
+  actor: string;
+  note?: string | null;
+}
+
+/** Record demonstrated demand for a CMP adapter from one tenant. */
+export interface RecordCmpDemandInput {
+  tenantId: string;
+  adapterId: string;
+  source?: string | null;
+}
+
+interface RevisionRow {
+  id: string;
+  tenant_id: string;
+  revision: number;
+  config: string;
+  actor: string;
+  note: string | null;
+  reverted_from: number | null;
+  created_at: string;
+}
+
+interface DemandRow {
+  id: string;
+  tenant_id: string;
+  adapter_id: string;
+  source: string | null;
+  at: string;
+}
+
+function toRevision(row: RevisionRow): ConsentConfigRevision {
+  return {
+    id: row.id,
+    tenantId: row.tenant_id,
+    revision: row.revision,
+    config: JSON.parse(row.config) as TenantConsentConfig,
+    actor: row.actor,
+    note: row.note,
+    revertedFrom: row.reverted_from,
+    createdAt: row.created_at,
+  };
+}
+
+export class ConsentConfigStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly now: () => string = () => new Date().toISOString(),
+    private readonly newId: () => string = () => crypto.randomUUID(),
+  ) {}
+
+  /**
+   * Append a new revision of a tenant's consent config. The revision number is
+   * assigned as `MAX(revision)+1` for that tenant; the UNIQUE `(tenant_id, revision)`
+   * index makes a concurrent double-assignment fail loudly rather than overwrite an
+   * earlier entry. The prior revisions are never touched — the history is the audit.
+   */
+  async saveRevision(input: SaveConsentConfigInput): Promise<ConsentConfigRevision> {
+    return this.appendRevision(input.tenantId, input.config, input.actor, input.note ?? null, null);
+  }
+
+  /**
+   * Restore a prior revision as a NEW revision (forward-only revert). Reads the target
+   * revision's config and appends it again with `revertedFrom` set — so a rollback is
+   * itself an audited entry and no history is rewritten. Throws if the target is absent.
+   */
+  async revertTo(input: RevertConsentConfigInput): Promise<ConsentConfigRevision> {
+    const target = await this.getRevision(input.tenantId, input.toRevision);
+    if (!target) {
+      throw new Error(
+        `Cannot revert tenant "${input.tenantId}" to revision ${input.toRevision}: no such revision.`,
+      );
+    }
+    const note = input.note ?? `Revert to revision ${input.toRevision}.`;
+    return this.appendRevision(input.tenantId, target.config, input.actor, note, input.toRevision);
+  }
+
+  private async appendRevision(
+    tenantId: string,
+    config: TenantConsentConfig,
+    actor: string,
+    note: string | null,
+    revertedFrom: number | null,
+  ): Promise<ConsentConfigRevision> {
+    const maxRow = await this.db.first<{ max_revision: number | null }>(
+      `SELECT MAX(revision) AS max_revision FROM consent_config_revisions WHERE tenant_id = ?`,
+      tenantId,
+    );
+    const revision = (maxRow?.max_revision ?? 0) + 1;
+    const createdAt = this.now();
+    await this.db.run(
+      `INSERT INTO consent_config_revisions
+         (id, tenant_id, revision, config, actor, note, reverted_from, created_at)
+       VALUES (?,?,?,?,?,?,?,?)`,
+      `ccr_${this.newId()}`,
+      tenantId,
+      revision,
+      JSON.stringify(config),
+      actor,
+      note,
+      revertedFrom,
+      createdAt,
+    );
+    const row = await this.db.first<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ? AND revision = ?`,
+      tenantId,
+      revision,
+    );
+    return toRevision(row!);
+  }
+
+  /** The current (latest) revision of a tenant's consent config, or null if none saved. */
+  async currentRevision(tenantId: string): Promise<ConsentConfigRevision | null> {
+    const row = await this.db.first<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ?
+        ORDER BY revision DESC LIMIT 1`,
+      tenantId,
+    );
+    return row ? toRevision(row) : null;
+  }
+
+  /** A specific revision, or null if absent. */
+  async getRevision(tenantId: string, revision: number): Promise<ConsentConfigRevision | null> {
+    const row = await this.db.first<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ? AND revision = ?`,
+      tenantId,
+      revision,
+    );
+    return row ? toRevision(row) : null;
+  }
+
+  /** A tenant's full revision history, newest first — the audit trail. */
+  async listRevisions(tenantId: string): Promise<ConsentConfigRevision[]> {
+    const rows = await this.db.all<RevisionRow>(
+      `SELECT * FROM consent_config_revisions WHERE tenant_id = ? ORDER BY revision DESC`,
+      tenantId,
+    );
+    return rows.map(toRevision);
+  }
+
+  /**
+   * Record demonstrated demand for a CMP adapter from one tenant. Idempotent per
+   * `(tenant, adapter)` — a tenant re-asking updates the recorded time/source on the
+   * SAME row and never inflates the distinct-tenant demand count.
+   */
+  async recordCmpDemand(input: RecordCmpDemandInput): Promise<void> {
+    await this.db.run(
+      `INSERT INTO consent_cmp_demand (id, tenant_id, adapter_id, source, at)
+       VALUES (?,?,?,?,?)
+       ON CONFLICT(tenant_id, adapter_id) DO UPDATE SET
+         source = excluded.source,
+         at = excluded.at`,
+      `cmd_${this.newId()}`,
+      input.tenantId,
+      input.adapterId,
+      input.source ?? null,
+      this.now(),
+    );
+  }
+
+  /**
+   * The whole demand ledger, in the `@tot/public-runtime` shape — passed straight into
+   * `validateConsentConfig` so a CMP choice is admitted only from demonstrated demand.
+   */
+  async demandLedger(): Promise<CmpDemandLedger> {
+    const rows = await this.db.all<DemandRow>(
+      `SELECT * FROM consent_cmp_demand ORDER BY adapter_id ASC, tenant_id ASC`,
+    );
+    return {
+      signals: rows.map((r) => ({
+        adapterId: r.adapter_id,
+        tenantPublicId: r.tenant_id,
+        at: r.at,
+        source: r.source ?? undefined,
+      })),
+    };
+  }
+}

package/apps/storefront/src/lib/apps/gtmMigrationInstall.ts

@@ -0,0 +1,447 @@
+/**
+ * Pure, transport-free orchestration for the review->install path of the GTM
+ * migration assistant: turn a reviewed, stored `MigrationDraftV1` into a
+ * DISABLED desired managed-analytics install/revision, strictly through WS1's
+ * pinned PUBLIC contract (`@tot/public-runtime`'s managed-analytics v1).
+ *
+ * SECURITY / PRODUCT CONTRACT (a reviewer WILL reject violations):
+ *   - Consumes ONLY the pinned PUBLIC managed-analytics v1 contract — its
+ *     request/response TYPES and its VALIDATORS. It never reimplements WS1's
+ *     schemas or server, never imports a private module, never touches a
+ *     database, config, tenant, or materializer, and never calls a live API
+ *     directly: every backend effect goes through the injected
+ *     {@link Ws1ManagedAnalyticsClient} interface (typed by pinned types), so
+ *     the whole module is unit-testable against a FAKE client with no transport.
+ *   - LOAD-BY-ID: the caller passes a draft `id`; this module LOADS the stored
+ *     draft from WS1 (`getMigrationDraft`) and re-validates it through the
+ *     pinned `validateMigrationDraftV1`. A caller can NEVER submit a hand-crafted
+ *     draft object past review — translated/untrusted draft data is not accepted.
+ *   - DISABLED-ONLY: the produced install is created with `status:"disabled"`
+ *     and its revision is a `status:"draft"` — enforced by the pinned
+ *     `CreateIntegrationInstallBody` literal AND re-asserted on the response.
+ *     This path CANNOT candidate/publish/activate/enable in the same request:
+ *     the injected client interface deliberately OMITS
+ *     `setIntegrationInstallStatus` (and every other enable/publish/mutate-draft
+ *     op), so enabling is not even type-reachable from here.
+ *   - The adapter VERSION the install needs is resolved from WS1's own catalog
+ *     (`getAdapterDefinition`), never trusted from the caller.
+ *
+ * Pure: no I/O of its own, no globals, no `Date.now`. Same inputs + same client
+ * responses -> same decision.
+ */
+import {
+  MANAGED_ANALYTICS_API_VERSION,
+  snapshotManagedAnalyticsDeclarativeInput,
+  validateApiErrorEnvelope,
+  validateGetIntegrationInstallRequest,
+  validateGetMigrationDraftRequest,
+  validateMigrationDraftV1,
+  stableIntegrationStringify,
+  validateAdapterDefinition,
+  validateIntegrationInstall,
+  validateIntegrationRevisionV1,
+  validateCreateIntegrationInstallRequest,
+  validateReviseIntegrationInstallRequest,
+  type OpaquePublicId,
+  type IntegrationInstall,
+  type IntegrationRevisionV1,
+  type ManagedAnalyticsErrorCode,
+  type ApiSuccess,
+  type ApiErrorEnvelope,
+  type GetMigrationDraftRequest,
+  type GetMigrationDraftResponse,
+  type MigrationDraftV1,
+  type AdapterDefinition,
+  type GetAdapterDefinitionRequest,
+  type GetAdapterDefinitionResponse,
+  type GetIntegrationInstallRequest,
+  type GetIntegrationInstallResponse,
+  type CreateIntegrationInstallRequest,
+  type CreateIntegrationInstallResponse,
+  type ReviseIntegrationInstallRequest,
+  type ReviseIntegrationInstallResponse,
+} from "@tot/public-runtime";
+
+/**
+ * The MINIMAL WS1 backend seam this path needs, typed entirely by the pinned
+ * contract's request/response types. It is a strict SUBSET of the pinned
+ * `ManagedAnalyticsApiV1Client`: reads used to load the draft + resolve the
+ * adapter version + (for a revise) bind the target install and observe its CAS
+ * state, plus the two SAFE writes that yield a disabled install/revision. It intentionally
+ * exposes NO `setIntegrationInstallStatus`, `deleteIntegrationInstall`,
+ * `createMigrationDraft`, `updateMigrationDraft`, or `deleteMigrationDraft` — so
+ * enabling/publishing/activating and any draft mutation are type-impossible from
+ * this module. Any concrete pinned client (HTTP at the edge) structurally
+ * satisfies it; tests inject a fake.
+ */
+export interface Ws1ManagedAnalyticsClient {
+  getMigrationDraft(request: GetMigrationDraftRequest): Promise<GetMigrationDraftResponse>;
+  getAdapterDefinition(request: GetAdapterDefinitionRequest): Promise<GetAdapterDefinitionResponse>;
+  getIntegrationInstall(request: GetIntegrationInstallRequest): Promise<GetIntegrationInstallResponse>;
+  createIntegrationInstall(request: CreateIntegrationInstallRequest): Promise<CreateIntegrationInstallResponse>;
+  reviseIntegrationInstall(request: ReviseIntegrationInstallRequest): Promise<ReviseIntegrationInstallResponse>;
+}
+
+/** Everything the orchestration needs; the draft is referenced BY ID, never by value. */
+export interface ReviewInstallInput {
+  /** The stored draft's opaque id — the server loads it; a draft object is never accepted. */
+  readonly draftId: OpaquePublicId;
+  /**
+   * Optional existing DISABLED install to revise into a new draft revision. When
+   * absent, a NEW disabled install is created. A non-disabled target is refused.
+   */
+  readonly targetInstallId?: OpaquePublicId;
+  /**
+   * The original CAS revision for a revise. A retry MUST reuse this value with
+   * the same idempotency key even when the target read now shows the committed
+   * `expectedRevision + 1`; otherwise WS1 correctly treats the changed request
+   * as an idempotency conflict.
+   */
+  readonly expectedRevision?: number;
+  /** Stable opaque idempotency key for the write/retry (>=8 chars, per the pinned mutation envelope). */
+  readonly idempotencyKey: OpaquePublicId;
+  /** Correlation id echoed on every result for support/audit. */
+  readonly correlationId: string;
+}
+
+export interface ReviewInstallOk {
+  readonly ok: true;
+  readonly correlationId: string;
+  /** Always `status:"disabled"` — re-asserted against the pinned validator. */
+  readonly install: IntegrationInstall;
+  /** Always `status:"draft"` — the newly created desired revision. */
+  readonly revision: IntegrationRevisionV1;
+  /** The one validated catalog snapshot whose version was used for this revision. */
+  readonly adapter: AdapterDefinition;
+  readonly idempotencyReplayed: boolean;
+}
+
+export interface ReviewInstallErr {
+  readonly ok: false;
+  readonly correlationId: string;
+  /** HTTP-ish status the route surfaces directly. */
+  readonly status: number;
+  /** A safe, redacted operator message — never raw input. */
+  readonly error: string;
+  /** The pinned error code when the failure came from WS1; a local code otherwise. */
+  readonly code?: ManagedAnalyticsErrorCode | "safety_refused";
+}
+
+export type ReviewInstallResult = ReviewInstallOk | ReviewInstallErr;
+
+const V = MANAGED_ANALYTICS_API_VERSION;
+
+/** Map a pinned `ApiErrorEnvelope`'s code to an HTTP status without forwarding its message. */
+const STATUS_BY_ERROR_CODE: Record<ManagedAnalyticsErrorCode, number> = {
+  invalid_request: 400,
+  unauthorized: 401,
+  forbidden: 403,
+  not_found: 404,
+  validation_failed: 422,
+  unsupported_version: 400,
+  stale_revision: 409,
+  idempotency_conflict: 409,
+  adapter_deprecated: 409,
+  conflict: 409,
+  internal_error: 502,
+};
+
+function fail(correlationId: string, status: number, error: string, code?: ReviewInstallErr["code"]): ReviewInstallErr {
+  return { ok: false, correlationId, status, error, code };
+}
+
+type ClientCall<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly result: ReviewInstallErr };
+
+/** Collapse rejected client promises to one stable response without inspecting the rejection. */
+async function callWs1<T>(operation: () => Promise<T>, correlationId: string): Promise<ClientCall<T>> {
+  try {
+    return { ok: true, value: await operation() };
+  } catch {
+    return {
+      ok: false,
+      result: fail(
+        correlationId,
+        502,
+        "The Integration Management API request failed safely.",
+        "internal_error",
+      ),
+    };
+  }
+}
+
+/**
+ * True when a pinned API result is the error envelope (its discriminant is
+ * `error`). `MutationSuccess<T>` is a subtype of `ApiSuccess<T>`, so a mutation
+ * response narrows through this guard too, keeping `idempotencyReplayed` on the
+ * success branch.
+ */
+function mapApiError(res: ApiErrorEnvelope, correlationId: string): ReviewInstallErr {
+  const { code } = res.error;
+  return fail(correlationId, STATUS_BY_ERROR_CODE[code] ?? 502, `The Integration Management API returned ${code}.`, code);
+}
+
+type PreparedApiResponse<T> =
+  | { readonly ok: true; readonly value: ApiSuccess<T> & Readonly<Record<string, unknown>> }
+  | { readonly ok: false; readonly result: ReviewInstallErr };
+
+/** Snapshot and validate the response envelope before any property access. */
+export function prepareWs1ApiResponse<T>(
+  input: unknown,
+  correlationId: string,
+  kind: "read" | "mutation" = "read",
+): PreparedApiResponse<T> {
+  const prepared = snapshotManagedAnalyticsDeclarativeInput<Record<string, unknown>>(input);
+  if (!prepared.ok) {
+    return { ok: false, result: fail(correlationId, 502, "The Integration Management API returned an unsafe response.", "internal_error") };
+  }
+  const value = prepared.value;
+  if (Object.prototype.hasOwnProperty.call(value, "error")) {
+    const checked = validateApiErrorEnvelope(value);
+    if (!checked.ok) {
+      return { ok: false, result: fail(correlationId, 502, "The Integration Management API returned an invalid error response.", "internal_error") };
+    }
+    return { ok: false, result: mapApiError(checked.value, correlationId) };
+  }
+  const expectedKeys = kind === "mutation"
+    ? ["apiVersion", "data", "idempotencyReplayed", "requestId"]
+    : ["apiVersion", "data", "requestId"];
+  const actualKeys = Object.keys(value).sort();
+  const requestIdCheck = validateApiErrorEnvelope({
+    apiVersion: V,
+    requestId: value["requestId"],
+    error: { code: "internal_error", message: "Internal error." },
+  });
+  const data = value["data"];
+  if (
+    stableIntegrationStringify(actualKeys) !== stableIntegrationStringify(expectedKeys) ||
+    value["apiVersion"] !== V ||
+    !requestIdCheck.ok ||
+    (kind === "mutation" && typeof value["idempotencyReplayed"] !== "boolean") ||
+    data === null ||
+    typeof data !== "object" ||
+    Array.isArray(data)
+  ) {
+    return { ok: false, result: fail(correlationId, 502, "The Integration Management API returned an invalid success response.", "internal_error") };
+  }
+  return { ok: true, value: value as ApiSuccess<T> & Readonly<Record<string, unknown>> };
+}
+
+/**
+ * Convert a reviewed, stored migration draft into a DISABLED desired install +
+ * draft revision, entirely through the pinned WS1 contract. Never enables,
+ * publishes, or activates. Returns a safe error (never throws on WS1 failures)
+ * for: an unknown draft id, a stored draft that fails the pinned validator, an
+ * unknown/deprecated adapter, a non-disabled revise target, a request that fails
+ * the pinned request validator, or a response that comes back not-disabled.
+ */
+export async function reviewInstallDraft(
+  client: Ws1ManagedAnalyticsClient,
+  input: ReviewInstallInput,
+  expectedDraftSnapshot?: MigrationDraftV1,
+): Promise<ReviewInstallResult> {
+  const { draftId, targetInstallId, idempotencyKey, correlationId } = input;
+
+  // Validate every caller-selected read identity through the pinned public
+  // contract before ANY client call. Besides the opaque-id grammar/length cap,
+  // these validators run the shared PII/secret/URL/code safety scan, preventing
+  // hostile identifiers from crossing even the injected transport boundary.
+  const draftReq: GetMigrationDraftRequest = { apiVersion: V, query: { draftId } };
+  const draftReqCheck = validateGetMigrationDraftRequest(draftReq);
+  if (!draftReqCheck.ok) {
+    return fail(correlationId, 422, "The requested draft identifier failed contract validation.", "validation_failed");
+  }
+  const installReqCheck = targetInstallId === undefined
+    ? undefined
+    : validateGetIntegrationInstallRequest({ apiVersion: V, query: { installId: targetInstallId } });
+  if (installReqCheck !== undefined && !installReqCheck.ok) {
+    return fail(correlationId, 422, "The requested install identifier failed contract validation.", "validation_failed");
+  }
+
+  // 1. LOAD the stored draft BY ID (never from caller-supplied data).
+  const draftCall = await callWs1(
+    () => client.getMigrationDraft(draftReqCheck.value),
+    correlationId,
+  );
+  if (!draftCall.ok) return draftCall.result;
+  const draftRes = prepareWs1ApiResponse<MigrationDraftV1>(draftCall.value, correlationId);
+  if (!draftRes.ok) return draftRes.result;
+  const draftCheck = validateMigrationDraftV1(draftRes.value.data);
+  if (!draftCheck.ok) {
+    return fail(correlationId, 422, "The stored draft failed contract validation.", "validation_failed");
+  }
+  const draft = draftCheck.value;
+  if (draft.draftId !== draftReqCheck.value.query.draftId) {
+    return fail(correlationId, 409, "The stored migration draft did not match the requested draft.", "safety_refused");
+  }
+  if (expectedDraftSnapshot !== undefined && stableIntegrationStringify(draft) !== stableIntegrationStringify(expectedDraftSnapshot)) {
+    return fail(correlationId, 409, "The stored migration draft changed after the reviewed create response.", "safety_refused");
+  }
+
+  // A revise target is bound by id, adapter, and retry-compatible CAS state
+  // before catalog resolution or any write.
+  let targetInstall: IntegrationInstall | undefined;
+  let targetAlreadyAdvanced = false;
+  if (targetInstallId !== undefined && installReqCheck?.ok) {
+    const installCall = await callWs1(
+      () => client.getIntegrationInstall(installReqCheck.value),
+      correlationId,
+    );
+    if (!installCall.ok) return installCall.result;
+    const installRes = prepareWs1ApiResponse<IntegrationInstall>(installCall.value, correlationId);
+    if (!installRes.ok) return installRes.result;
+    const targetCheck = validateIntegrationInstall(installRes.value.data);
+    if (!targetCheck.ok) {
+      return fail(correlationId, 502, "The target install failed contract validation.", "internal_error");
+    }
+    if (targetCheck.value.installId !== installReqCheck.value.query.installId) {
+      return fail(correlationId, 409, "The stored install did not match the requested target.", "safety_refused");
+    }
+    if (targetCheck.value.status !== "disabled") {
+      return fail(correlationId, 409, "The target install is not disabled; this path only revises a disabled install.", "conflict");
+    }
+    if (targetCheck.value.adapterId !== draft.proposedAdapterId) {
+      return fail(correlationId, 409, "The target install adapter did not match the reviewed draft.", "safety_refused");
+    }
+    if (
+      input.expectedRevision !== undefined &&
+      targetCheck.value.revision !== input.expectedRevision &&
+      targetCheck.value.revision !== input.expectedRevision + 1
+    ) {
+      return fail(correlationId, 409, "The target install revision no longer matches this review attempt.", "conflict");
+    }
+    targetAlreadyAdvanced = input.expectedRevision !== undefined &&
+      targetCheck.value.revision === input.expectedRevision + 1;
+    targetInstall = targetCheck.value;
+  }
+
+  // 2. Resolve the adapter VERSION from WS1's catalog — never trust the caller.
+  const adapterReq: GetAdapterDefinitionRequest = { apiVersion: V, query: { adapterId: draft.proposedAdapterId } };
+  const adapterCall = await callWs1(() => client.getAdapterDefinition(adapterReq), correlationId);
+  if (!adapterCall.ok) return adapterCall.result;
+  const adapterRes = prepareWs1ApiResponse<AdapterDefinition>(adapterCall.value, correlationId);
+  if (!adapterRes.ok) return adapterRes.result;
+  const adapterCheck = validateAdapterDefinition(adapterRes.value.data);
+  if (!adapterCheck.ok) {
+    return fail(correlationId, 502, "The adapter definition failed contract validation.", "internal_error");
+  }
+  const adapter = adapterCheck.value;
+  if (adapter.adapterId !== draft.proposedAdapterId) {
+    return fail(correlationId, 409, "The adapter snapshot did not match the reviewed draft.", "safety_refused");
+  }
+  if (adapter.availability === "deprecated") {
+    return fail(correlationId, 409, "The proposed adapter is deprecated and cannot take a new install.", "adapter_deprecated");
+  }
+
+  // 3a. REVISE an existing DISABLED install into a new draft revision.
+  if (targetInstall !== undefined) {
+    const expectedRevision = input.expectedRevision ?? targetInstall.revision;
+    const reviseReq: ReviseIntegrationInstallRequest = {
+      apiVersion: V,
+      idempotencyKey,
+      expectedRevision,
+      body: {
+        installId: targetInstall.installId,
+        adapterVersion: adapter.adapterVersion,
+        configuration: draft.proposedConfiguration,
+      },
+    };
+    const reqCheck = validateReviseIntegrationInstallRequest(reviseReq);
+    if (!reqCheck.ok) {
+      return fail(correlationId, 422, "The constructed revise request failed contract validation.", "validation_failed");
+    }
+    const reviseCall = await callWs1(() => client.reviseIntegrationInstall(reviseReq), correlationId);
+    if (!reviseCall.ok) return reviseCall.result;
+    return finalize(
+      reviseCall.value,
+      correlationId,
+      adapter,
+      draft.proposedConfiguration,
+      expectedRevision,
+      targetInstall.installId,
+      targetAlreadyAdvanced,
+    );
+  }
+
+  // 3b. CREATE a NEW install, forced DISABLED by the pinned body literal.
+  const createReq: CreateIntegrationInstallRequest = {
+    apiVersion: V,
+    idempotencyKey,
+    expectedRevision: 0,
+    body: {
+      adapterId: draft.proposedAdapterId,
+      adapterVersion: adapter.adapterVersion,
+      configuration: draft.proposedConfiguration,
+      status: "disabled",
+    },
+  };
+  const createCheck = validateCreateIntegrationInstallRequest(createReq);
+  if (!createCheck.ok) {
+    return fail(correlationId, 422, "The constructed install request failed contract validation.", "validation_failed");
+  }
+  const createCall = await callWs1(() => client.createIntegrationInstall(createReq), correlationId);
+  if (!createCall.ok) return createCall.result;
+  return finalize(createCall.value, correlationId, adapter, draft.proposedConfiguration);
+}
+
+/**
+ * Validate a create/revise mutation response and REFUSE anything that is not a
+ * disabled install with a draft revision — defense-in-depth so a misbehaving
+ * backend can never hand this path an enabled/active result. Creates require a
+ * coherent install revision / candidate sequence pair but do not assume `1`:
+ * WS1 may revive a tombstoned adapter at its preserved history's next revision.
+ */
+function finalize(
+  res: CreateIntegrationInstallResponse | ReviseIntegrationInstallResponse,
+  correlationId: string,
+  adapter: AdapterDefinition,
+  expectedConfiguration: Readonly<Record<string, string | boolean | number>>,
+  expectedPriorRevision?: number,
+  expectedInstallId?: OpaquePublicId,
+  requireIdempotencyReplay = false,
+): ReviewInstallResult {
+  const prepared = prepareWs1ApiResponse<{ install: IntegrationInstall; revision: IntegrationRevisionV1 }>(
+    res,
+    correlationId,
+    "mutation",
+  );
+  if (!prepared.ok) return prepared.result;
+  const idempotencyReplayed = prepared.value["idempotencyReplayed"];
+  if (typeof idempotencyReplayed !== "boolean") {
+    return fail(correlationId, 502, "The Integration Management API returned an invalid mutation response.", "internal_error");
+  }
+  const installCheck = validateIntegrationInstall(prepared.value.data.install);
+  const revisionCheck = validateIntegrationRevisionV1(prepared.value.data.revision);
+  if (!installCheck.ok || !revisionCheck.ok) {
+    return fail(correlationId, 502, "The install response failed contract validation.", "internal_error");
+  }
+  if (installCheck.value.status !== "disabled") {
+    return fail(correlationId, 409, "Refusing a result whose install is not disabled.", "safety_refused");
+  }
+  if (revisionCheck.value.status !== "draft") {
+    return fail(correlationId, 409, "Refusing a result whose revision is not a draft.", "safety_refused");
+  }
+  if (
+    installCheck.value.adapterId !== adapter.adapterId ||
+    revisionCheck.value.adapterId !== adapter.adapterId ||
+    revisionCheck.value.adapterVersion !== adapter.adapterVersion ||
+    revisionCheck.value.installId !== installCheck.value.installId ||
+    stableIntegrationStringify(revisionCheck.value.configuration) !== stableIntegrationStringify(expectedConfiguration) ||
+    (requireIdempotencyReplay && !idempotencyReplayed) ||
+    installCheck.value.revision !== revisionCheck.value.sequence ||
+    (expectedPriorRevision !== undefined && installCheck.value.revision !== expectedPriorRevision + 1) ||
+    (expectedInstallId !== undefined && installCheck.value.installId !== expectedInstallId) ||
+    (expectedInstallId === undefined && installCheck.value.activeRevisionId !== null)
+  ) {
+    return fail(correlationId, 409, "Refusing an install result that differs from the reviewed candidate.", "safety_refused");
+  }
+  return {
+    ok: true,
+    correlationId,
+    install: installCheck.value,
+    revision: revisionCheck.value,
+    adapter,
+    idempotencyReplayed,
+  };
+}