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

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

@@ -0,0 +1,599 @@
+/**
+ * Managed analytics API v1 facade over the canonical app registry authorities.
+ * Installs live in `app_installs`; live versions in `app_version_snapshots`;
+ * candidate history in `app_audit_log`; inert drafts in their narrow store;
+ * retries in the existing `idempotency_keys` ledger.
+ */
+import {
+  MANAGED_ANALYTICS_API_VERSION, MANAGED_ANALYTICS_SCHEMA_VERSION,
+  getPlatformAdapter, platformAdapterCatalog, sha256Hex,
+  buildPlatformAdapterDeclaration, validateIntegrationManifest,
+  resolveEffectivePlan, compileIntegrationCspFromPlan,
+  collectDeclaredCspProfiles, ENVIRONMENT_SCHEMA_VERSION,
+  validateManagedAnalyticsSafePayload,
+  validateApiErrorEnvelope, validateIntegrationInstall,
+  validateAdapterDefinition, validateIntegrationRevisionV1, validateMigrationDraftV1,
+  validateCreateMigrationDraftRequest, validateUpdateMigrationDraftRequest,
+  validateDeleteMigrationDraftRequest, validateCreateIntegrationInstallRequest,
+  validateReviseIntegrationInstallRequest, validateSetIntegrationInstallStatusRequest,
+  validateDeleteIntegrationInstallRequest,
+  snapshotManagedAnalyticsDeclarativeInput,
+  type AdapterConfigValue, type AdapterDefinition, type ApiErrorEnvelope,
+  type ApiResult, type CreateIntegrationInstallRequest,
+  type CreateMigrationDraftRequest, type DeleteIntegrationInstallRequest,
+  type DeleteMigrationDraftRequest, type IntegrationInstall,
+  type IntegrationRevisionV1, type ListAdapterDefinitionsRequest,
+  type ListIntegrationInstallsRequest, type MigrationDraftV1,
+  type MutationResult, type ReviseIntegrationInstallRequest,
+  type SetIntegrationInstallStatusRequest, type UpdateMigrationDraftRequest,
+  type IntegrationManifest,
+} from "@tot/public-runtime";
+import type { Queryable, QueryStatement } from "../d1/catalog.js";
+import { AppVersionStore, type AppVersionFacets } from "./appVersionStore.js";
+
+export type ManagedAnalyticsOperation =
+  | "listAdapterDefinitions" | "getAdapterDefinition"
+  | "listIntegrationInstalls" | "getIntegrationInstall"
+  | "listIntegrationRevisions" | "getIntegrationRevision"
+  | "getMigrationDraft" | "createMigrationDraft" | "updateMigrationDraft"
+  | "deleteMigrationDraft" | "createIntegrationInstall"
+  | "reviseIntegrationInstall" | "setIntegrationInstallStatus"
+  | "deleteIntegrationInstall";
+
+export const MANAGED_ANALYTICS_READ_OPERATIONS: ReadonlySet<ManagedAnalyticsOperation> = new Set([
+  "listAdapterDefinitions", "getAdapterDefinition", "listIntegrationInstalls",
+  "getIntegrationInstall", "listIntegrationRevisions", "getIntegrationRevision",
+  "getMigrationDraft",
+]);
+
+export interface ManagedAnalyticsActorContext { tenantId: string; actor: string }
+interface Effects { digest: string; cspOrigins: string[]; subscriptions: string[]; cacheIdentity: string }
+interface CandidateRecord { revision: IntegrationRevisionV1; digest: string; effects: Effects; approvedAt: string }
+interface StoredCandidate extends CandidateRecord {
+  manifest: IntegrationManifest;
+  facets: AppVersionFacets;
+  /** Immutable activated snapshot selected by a revise-to-prior-config rollback. */
+  rollbackFromSeq?: number;
+}
+interface InstallRow {
+  install_id: string; app_id: string; app_version: string; tenant_id: string;
+  env: string; status: string; scopes: string; manifest: string;
+  webhook_endpoint: string | null; widget_placements: string; install_actor: string;
+  managed_kind: string | null; managed_revision: number; managed_active_revision_id: string | null;
+  managed_candidate: string | null;
+  created_at: string; updated_at: string;
+}
+interface AuditRow { id: string; event: string; detail: string; at: string }
+interface DraftRow { draft_id: string; tenant_id: string; revision: number; state: string; record: string; created_at: string; updated_at: string }
+interface IdempotencyRow { body_hash: string; response_body: string }
+type CandidateValidation =
+  | { ok: true; effects: Effects; facets: AppVersionFacets; manifest: IntegrationManifest }
+  | { ok: false; details: Array<{ path: string; code: string; message: string }> };
+interface MutationPlan<T> {
+  response: MutationResult<T>;
+  statements: QueryStatement[];
+  casStillCurrent?: () => Promise<boolean>;
+}
+
+const KIND = "managed-analytics-v1";
+/**
+ * Preserve UUID entropy while preventing any contract-visible identifier from
+ * accidentally resembling a phone/card number to the frozen value canary.
+ * Underscores are PUBLIC_ID-safe and split every hexadecimal run at four chars.
+ */
+export function managedAnalyticsOpaqueId(prefix: string, uuid = crypto.randomUUID()): string {
+  const hex = uuid.replaceAll("-", "");
+  if (!/^[0-9a-f]{32}$/i.test(hex)) throw new TypeError("Managed analytics entropy must be a UUID.");
+  return `${prefix}_${hex.match(/.{1,4}/g)!.join("_")}`;
+}
+function requestId(): string { return managedAnalyticsOpaqueId("req"); }
+function publicId(prefix: string): string { return managedAnalyticsOpaqueId(prefix); }
+function stableValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, child]) => [key, stableValue(child)]),
+  );
+  return value;
+}
+function canonicalJson(value: unknown): string { return JSON.stringify(stableValue(value)); }
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return canonicalJson(Object.keys(value).sort()) === canonicalJson([...keys].sort());
+}
+function validatesReplayData(operation: ManagedAnalyticsOperation, data: unknown): boolean {
+  if (operation === "createMigrationDraft" || operation === "updateMigrationDraft") {
+    return validateMigrationDraftV1(data).ok;
+  }
+  if (operation === "setIntegrationInstallStatus") return validateIntegrationInstall(data).ok;
+  if (operation === "createIntegrationInstall" || operation === "reviseIntegrationInstall") {
+    const value = record(data);
+    return !!value && exactKeys(value, ["install", "revision"]) &&
+      validateIntegrationInstall(value["install"]).ok && validateIntegrationRevisionV1(value["revision"]).ok;
+  }
+  if (operation === "deleteMigrationDraft" || operation === "deleteIntegrationInstall") {
+    const value = record(data);
+    return !!value && exactKeys(value, ["deleted"]) && value["deleted"] === true;
+  }
+  return false;
+}
+function validatesPage(data: unknown, itemValidator: (item: unknown) => { ok: boolean }): boolean {
+  const value = record(data);
+  if (!value || !Array.isArray(value["items"]) || !exactKeys(value, value["nextCursor"] === undefined ? ["items"] : ["items", "nextCursor"])) return false;
+  if (value["nextCursor"] !== undefined && !validOpaqueId(value["nextCursor"])) return false;
+  return value["items"].every((item) => itemValidator(item).ok);
+}
+function validOpaqueId(value: unknown): boolean {
+  return validateApiErrorEnvelope({ apiVersion: "v1", requestId: value, error: { code: "internal_error", message: "Internal error." } }).ok;
+}
+function validSafeOpaqueId(value: unknown): value is string {
+  return typeof value === "string" && validOpaqueId(value) && validateManagedAnalyticsSafePayload(value).ok;
+}
+function validIdempotencyKey(value: unknown): value is string {
+  return validSafeOpaqueId(value) && value.length >= 8 && value.length <= 128;
+}
+function validatesOutboundData(operation: ManagedAnalyticsOperation, data: unknown): boolean {
+  switch (operation) {
+    case "listAdapterDefinitions": return validatesPage(data, validateAdapterDefinition);
+    case "getAdapterDefinition": return validateAdapterDefinition(data).ok;
+    case "listIntegrationInstalls": return validatesPage(data, validateIntegrationInstall);
+    case "getIntegrationInstall": return validateIntegrationInstall(data).ok;
+    case "listIntegrationRevisions": return validatesPage(data, validateIntegrationRevisionV1);
+    case "getIntegrationRevision": return validateIntegrationRevisionV1(data).ok;
+    case "getMigrationDraft": return validateMigrationDraftV1(data).ok;
+    default: return validatesReplayData(operation, data);
+  }
+}
+
+/** Final frozen-wire guard and detached value used by persistence/routes. */
+export function sanitizeManagedAnalyticsOutbound(operation: ManagedAnalyticsOperation, input: unknown): unknown | null {
+  const safe = validateManagedAnalyticsSafePayload(input);
+  if (!safe.ok) return null;
+  const envelope = record(safe.value);
+  if (!envelope) return null;
+  if (Object.prototype.hasOwnProperty.call(envelope, "error")) return validateApiErrorEnvelope(envelope).ok ? safe.value : null;
+  const mutation = !MANAGED_ANALYTICS_READ_OPERATIONS.has(operation);
+  const keys = mutation ? ["apiVersion", "requestId", "data", "idempotencyReplayed"] : ["apiVersion", "requestId", "data"];
+  if (!exactKeys(envelope, keys) || envelope["apiVersion"] !== "v1" || !validOpaqueId(envelope["requestId"])) return null;
+  if (mutation && typeof envelope["idempotencyReplayed"] !== "boolean") return null;
+  return validatesOutboundData(operation, envelope["data"]) ? safe.value : null;
+}
+export function validateManagedAnalyticsOutbound(operation: ManagedAnalyticsOperation, input: unknown): boolean {
+  return sanitizeManagedAnalyticsOutbound(operation, input) !== null;
+}
+function success<T>(data: T): ApiResult<T> {
+  return { apiVersion: MANAGED_ANALYTICS_API_VERSION, requestId: requestId(), data };
+}
+function mutationSuccess<T>(data: T): MutationResult<T> {
+  return { apiVersion: MANAGED_ANALYTICS_API_VERSION, requestId: requestId(), data, idempotencyReplayed: false };
+}
+function error(code: ApiErrorEnvelope["error"]["code"], message: string, details?: ApiErrorEnvelope["error"]["details"]): ApiErrorEnvelope {
+  return { apiVersion: MANAGED_ANALYTICS_API_VERSION, requestId: requestId(), error: { code, message, ...(details?.length ? { details } : {}) } };
+}
+function notFound(): ApiErrorEnvelope { return error("not_found", "The requested resource was not found."); }
+function stale(): ApiErrorEnvelope { return error("stale_revision", "The resource changed; refresh and retry."); }
+function internalError(): ApiErrorEnvelope { return error("internal_error", "The integration service could not complete the request."); }
+function parseCandidate(row: InstallRow): StoredCandidate | null {
+  return row.managed_candidate ? JSON.parse(row.managed_candidate) as StoredCandidate : null;
+}
+function parseLive(row: InstallRow): IntegrationManifest | null {
+  const value = JSON.parse(row.manifest) as unknown;
+  const valid = validateIntegrationManifest(value);
+  return valid.ok ? valid.value : null;
+}
+function publicInstall(row: InstallRow): IntegrationInstall {
+  const live = parseLive(row);
+  const value: IntegrationInstall = {
+    schemaVersion: MANAGED_ANALYTICS_SCHEMA_VERSION, installId: row.install_id,
+    adapterId: row.app_id, status: row.status === "active" && live ? "enabled" : "disabled",
+    activeRevisionId: row.managed_active_revision_id, revision: row.managed_revision,
+    createdAt: row.created_at, updatedAt: row.updated_at,
+  };
+  const validated = validateIntegrationInstall(value);
+  if (!validated.ok) throw new Error("Managed analytics install failed persisted-data validation.");
+  return validated.value;
+}
+/**
+ * Build the public managed-analytics adapter catalog from the canonical platform
+ * adapter cards. Exported for read-only/offline contract proofs; callers receive
+ * detached data and no tenant or persistence authority.
+ */
+export function managedAnalyticsAdapterDefinitions(): AdapterDefinition[] {
+  return platformAdapterCatalog().map((card) => ({
+    schemaVersion: MANAGED_ANALYTICS_SCHEMA_VERSION, adapterId: card.adapterId,
+    adapterVersion: "1.0.0", displayName: card.name, description: card.purpose,
+    availability: "available",
+    configuration: [{ key: "destinationId", label: card.idLabel, description: "Public destination identifier used by this reviewed adapter.", kind: "string", required: true }],
+    eventTypes: [...card.eventTypes], consentPurposes: [...card.consentPurposes],
+    collectionOrigins: [...card.cspOrigins].sort(),
+  }));
+}
+const CATALOG = managedAnalyticsAdapterDefinitions();
+const CATALOG_BY_ID: Readonly<Record<string, AdapterDefinition>> = Object.assign(
+  Object.create(null) as Record<string, AdapterDefinition>,
+  Object.fromEntries(CATALOG.map((item) => [item.adapterId, item])),
+);
+function page<T extends Record<I, string>, I extends string>(items: T[], id: I, query: { cursor?: string; limit?: number }) {
+  const found = query.cursor ? items.findIndex((item) => item[id] === query.cursor) : -1;
+  const start = found < 0 ? 0 : found + 1;
+  const limit = Math.min(query.limit ?? 50, 100);
+  const selected = items.slice(start, start + limit);
+  return { items: selected, ...(start + limit < items.length && selected.length ? { nextCursor: selected.at(-1)![id] } : {}) };
+}
+
+/** Pure validation and declarative effect compilation; performs no I/O. */
+export async function validateManagedAnalyticsCandidate(input: {
+  adapterId: string; adapterVersion: string; configuration: Record<string, AdapterConfigValue>;
+}, tenantPublicId = "managed-validation.invalid"): Promise<CandidateValidation> {
+  const definition = Object.prototype.hasOwnProperty.call(CATALOG_BY_ID, input.adapterId)
+    ? CATALOG_BY_ID[input.adapterId] : undefined;
+  if (!definition) return { ok: false, details: [{ path: "body.adapterId", code: "unknown_adapter", message: "Unknown adapter." }] };
+  if (definition.adapterVersion !== input.adapterVersion) return { ok: false, details: [{ path: "body.adapterVersion", code: "unknown_version", message: "Unknown adapter version." }] };
+  const keys = Object.keys(input.configuration);
+  if (keys.length !== 1 || keys[0] !== "destinationId") return { ok: false, details: [{ path: "body.configuration", code: "configuration_shape", message: "Configuration does not match the adapter definition." }] };
+  const destinationId = input.configuration.destinationId;
+  const platform = getPlatformAdapter(input.adapterId);
+  if (typeof destinationId !== "string" || !platform?.validateId(destinationId)) return { ok: false, details: [{ path: "body.configuration.destinationId", code: "format", message: "Destination identifier has an invalid format." }] };
+  const safe = validateManagedAnalyticsSafePayload({ adapterId: input.adapterId, adapterVersion: input.adapterVersion, configuration: input.configuration });
+  if (!safe.ok) return { ok: false, details: safe.violations };
+  // The frozen public candidate body is the only value scanned by the safety
+  // validator above. The auth-derived tenant scope is a separate materializer
+  // argument and can therefore never become an unpublished request field.
+  const tenantId = tenantPublicId;
+  const built = buildPlatformAdapterDeclaration({
+    adapterId: input.adapterId,
+    ids: { live: destinationId },
+    tenantPublicId: tenantId,
+    environment: {
+      schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+      siteSurface: "admin",
+      environment: "live",
+      canonicalHost: tenantId,
+      revision: "managed-analytics-v1",
+    },
+  });
+  if (!built.ok) return { ok: false, details: built.violations.map(({ path, code, message }) => ({ path: path ? `body.${path}` : "body", code, message })) };
+  const manifest = validateIntegrationManifest(built.declaration.manifest);
+  if (!manifest.ok) return { ok: false, details: manifest.violations };
+  const resolved = resolveEffectivePlan({ tenantPublicId: tenantId, environment: {
+    schemaVersion: ENVIRONMENT_SCHEMA_VERSION, siteSurface: "admin", environment: "live",
+    canonicalHost: tenantId, revision: "managed-analytics-v1",
+  }, declarations: [built.declaration] });
+  if (!resolved.ok) return { ok: false, details: resolved.violations };
+  const compiled = compileIntegrationCspFromPlan(resolved.value, collectDeclaredCspProfiles([built.declaration]));
+  if (!compiled.ok) return { ok: false, details: compiled.violations };
+  const cspOrigins = [...new Set(Object.values(compiled.value.additions).flatMap((origins) => origins ?? []))].sort();
+  const integration = resolved.value.integrations.find((item) => item.appId === input.adapterId)!;
+  const digest = manifest.value.app.digest;
+  const effects: Effects = { digest, cspOrigins, subscriptions: [...built.card.eventTypes], cacheIdentity: `managed-analytics:${digest}` };
+  return { ok: true, effects, manifest: manifest.value, facets: {
+    appVersion: integration.version, digest, executionTier: integration.executionTier,
+    entry: integration.entry, publicConfig: { ...input.configuration },
+    contributions: [...resolved.value.contributions], scopes: [], consent: integration.consent,
+    cspOrigins,
+  } };
+}
+
+/** Thin v1 facade; canonical registry/version/audit/idempotency tables are authority. */
+export class ManagedAnalyticsApiV1Facade {
+  private readonly versions: AppVersionStore;
+  constructor(private readonly db: Queryable, private readonly now: () => string = () => new Date().toISOString()) {
+    this.versions = new AppVersionStore(db, now);
+  }
+  listAdapterDefinitions(request: ListAdapterDefinitionsRequest) { return success(page(CATALOG, "adapterId", request.query)); }
+  getAdapterDefinition(adapterId: string): ApiResult<AdapterDefinition> {
+    const found = Object.prototype.hasOwnProperty.call(CATALOG_BY_ID, adapterId) ? CATALOG_BY_ID[adapterId] : undefined;
+    return found ? success(found) : notFound();
+  }
+  async listIntegrationInstalls(ctx: ManagedAnalyticsActorContext, request: ListIntegrationInstallsRequest) {
+    try {
+      const rows = await this.db.all<InstallRow>(`SELECT * FROM app_installs WHERE tenant_id = ? AND managed_kind = ? AND status != 'uninstalled' ORDER BY created_at, install_id`, ctx.tenantId, KIND);
+      return success(page(rows.map(publicInstall), "installId", request.query));
+    } catch { return internalError(); }
+  }
+  async getIntegrationInstall(ctx: ManagedAnalyticsActorContext, installId: string) {
+    try {
+      const row = await this.ownedInstall(ctx.tenantId, installId);
+      return row ? success(publicInstall(row)) : notFound();
+    } catch { return internalError(); }
+  }
+  async listIntegrationRevisions(ctx: ManagedAnalyticsActorContext, installId: string, query: { cursor?: string; limit?: number }) {
+    try {
+      const row = await this.ownedInstall(ctx.tenantId, installId);
+      if (!row) return notFound();
+      return success(page(await this.revisions(row), "revisionId", query));
+    } catch { return internalError(); }
+  }
+  async getIntegrationRevision(ctx: ManagedAnalyticsActorContext, installId: string, revisionId: string) {
+    try {
+      const row = await this.ownedInstall(ctx.tenantId, installId);
+      if (!row) return notFound();
+      const found = (await this.revisions(row)).find((item) => item.revisionId === revisionId);
+      return found ? success(found) : notFound();
+    } catch { return internalError(); }
+  }
+  async getMigrationDraft(ctx: ManagedAnalyticsActorContext, draftId: string) {
+    try {
+      const draft = await this.loadDraft(ctx.tenantId, draftId);
+      return draft?.open ? success(draft.draft) : notFound();
+    } catch { return internalError(); }
+  }
+
+  async createMigrationDraft(ctx: ManagedAnalyticsActorContext, request: CreateMigrationDraftRequest) {
+    const snapshot = snapshotManagedAnalyticsDeclarativeInput<CreateMigrationDraftRequest>(request);
+    if (!snapshot.ok) return error("validation_failed", "The request failed validation.", snapshot.violations);
+    const prepared = validateCreateMigrationDraftRequest(snapshot.value);
+    if (!prepared.ok) return this.rejectInvalidMutation<MigrationDraftV1>(ctx, "createMigrationDraft", snapshot.value, prepared.violations);
+    request = prepared.value;
+    return this.idempotent(ctx, "createMigrationDraft", request, this.tenantScope(ctx), async () => {
+      if (request.expectedRevision !== 0) return { response: stale(), statements: [] };
+      const now = this.now();
+      const draft: MigrationDraftV1 = { schemaVersion: 1, draftId: publicId("migration"), revision: 1, source: "approved-migration", status: "draft", enabled: false, publishes: false, proposedAdapterId: request.body.proposedAdapterId, proposedConfiguration: { ...request.body.proposedConfiguration }, findings: [...request.body.findings], createdAt: now, updatedAt: now };
+      const safe = validateManagedAnalyticsSafePayload(draft);
+      if (!safe.ok) return { response: error("validation_failed", "The migration draft failed validation.", safe.violations), statements: [] };
+      return { response: mutationSuccess(draft), statements: [
+        { sql: `INSERT INTO integration_migration_drafts (draft_id, tenant_id, revision, state, record, created_at, updated_at) VALUES (?,?,?,'open',?,?,?)`, params: [draft.draftId, ctx.tenantId, draft.revision, JSON.stringify(draft), now, now] },
+        this.auditStatement(draft.draftId, ctx, "managed_analytics.migration_draft_created", { revision: draft.revision }),
+      ] };
+    });
+  }
+  async updateMigrationDraft(ctx: ManagedAnalyticsActorContext, request: UpdateMigrationDraftRequest) {
+    const snapshot = snapshotManagedAnalyticsDeclarativeInput<UpdateMigrationDraftRequest>(request);
+    if (!snapshot.ok) return error("validation_failed", "The request failed validation.", snapshot.violations);
+    const prepared = validateUpdateMigrationDraftRequest(snapshot.value);
+    if (!prepared.ok) return this.rejectInvalidMutation<MigrationDraftV1>(ctx, "updateMigrationDraft", snapshot.value, prepared.violations, "draftId");
+    request = prepared.value;
+    const scope = request.body.draftId;
+    return this.idempotent(ctx, "updateMigrationDraft", request, scope, async () => {
+      const current = await this.loadDraft(ctx.tenantId, scope);
+      if (!current?.open) return { response: notFound(), statements: [] };
+      if (current.draft.revision !== request.expectedRevision) return { response: stale(), statements: [] };
+      const draft: MigrationDraftV1 = { ...current.draft, proposedAdapterId: request.body.proposedAdapterId, proposedConfiguration: { ...request.body.proposedConfiguration }, findings: [...request.body.findings], revision: current.draft.revision + 1, updatedAt: this.now() };
+      const safe = validateManagedAnalyticsSafePayload(draft);
+      if (!safe.ok) return { response: error("validation_failed", "The migration draft failed validation.", safe.violations), statements: [] };
+      const update: QueryStatement = { sql: `UPDATE integration_migration_drafts SET revision = ?, record = ?, updated_at = ? WHERE draft_id = ? AND tenant_id = ? AND state = 'open' AND revision = ?`, params: [draft.revision, JSON.stringify(draft), draft.updatedAt, scope, ctx.tenantId, request.expectedRevision] };
+      return { response: mutationSuccess(draft), statements: [update, this.auditStatement(scope, ctx, "managed_analytics.migration_draft_updated", { revision: draft.revision }, true)], casStillCurrent: async () => { const latest = await this.loadDraft(ctx.tenantId, scope); return latest?.open === true && latest.draft.revision === request.expectedRevision; } };
+    });
+  }
+  async deleteMigrationDraft(ctx: ManagedAnalyticsActorContext, request: DeleteMigrationDraftRequest) {
+    const snapshot = snapshotManagedAnalyticsDeclarativeInput<DeleteMigrationDraftRequest>(request);
+    if (!snapshot.ok) return error("validation_failed", "The request failed validation.", snapshot.violations);
+    const prepared = validateDeleteMigrationDraftRequest(snapshot.value);
+    if (!prepared.ok) return this.rejectInvalidMutation<{ deleted: true }>(ctx, "deleteMigrationDraft", snapshot.value, prepared.violations, "draftId");
+    request = prepared.value;
+    const scope = request.body.draftId;
+    return this.idempotent(ctx, "deleteMigrationDraft", request, scope, async () => {
+      const current = await this.loadDraft(ctx.tenantId, scope);
+      if (!current?.open) return { response: notFound(), statements: [] };
+      if (current.draft.revision !== request.expectedRevision) return { response: stale(), statements: [] };
+      const revision = current.draft.revision + 1;
+      const update: QueryStatement = { sql: `UPDATE integration_migration_drafts SET revision = ?, state = 'rejected', updated_at = ? WHERE draft_id = ? AND tenant_id = ? AND state = 'open' AND revision = ?`, params: [revision, this.now(), scope, ctx.tenantId, request.expectedRevision] };
+      return { response: mutationSuccess({ deleted: true as const }), statements: [update, this.auditStatement(scope, ctx, "managed_analytics.migration_draft_rejected", { revision }, true)], casStillCurrent: async () => { const latest = await this.loadDraft(ctx.tenantId, scope); return latest?.open === true && latest.draft.revision === request.expectedRevision; } };
+    });
+  }
+
+  async createIntegrationInstall(ctx: ManagedAnalyticsActorContext, request: CreateIntegrationInstallRequest) {
+    const snapshot = snapshotManagedAnalyticsDeclarativeInput<CreateIntegrationInstallRequest>(request);
+    if (!snapshot.ok) return error("validation_failed", "The request failed validation.", snapshot.violations);
+    const prepared = validateCreateIntegrationInstallRequest(snapshot.value);
+    if (!prepared.ok) return this.rejectInvalidMutation<{ install: IntegrationInstall; revision: IntegrationRevisionV1 }>(ctx, "createIntegrationInstall", snapshot.value, prepared.violations);
+    request = prepared.value;
+    return this.idempotent(ctx, "createIntegrationInstall", request, this.tenantScope(ctx), async () => {
+      if (request.expectedRevision !== 0) return { response: stale(), statements: [] };
+      const validated = await validateManagedAnalyticsCandidate(request.body, ctx.tenantId);
+      if (!validated.ok) return { response: error("validation_failed", "The integration revision failed validation.", validated.details), statements: [] };
+      const existing = await this.adapterSlot(ctx.tenantId, request.body.adapterId);
+      if (existing && (existing.managed_kind !== KIND || existing.status !== "uninstalled")) {
+        return { response: error("conflict", "This adapter is already configured."), statements: [] };
+      }
+      const now = this.now();
+      const installId = existing?.install_id ?? publicId("integration");
+      const nextRevision = existing ? existing.managed_revision + 1 : 1;
+      const revision: IntegrationRevisionV1 = { schemaVersion: 1, revisionId: publicId("revision"), installId, adapterId: request.body.adapterId, adapterVersion: request.body.adapterVersion, sequence: nextRevision, status: "draft", configuration: { ...request.body.configuration }, createdAt: now };
+      const candidate: StoredCandidate = { revision, digest: validated.effects.digest, effects: validated.effects, manifest: validated.manifest, facets: validated.facets, approvedAt: now };
+      const install: IntegrationInstall = { schemaVersion: 1, installId, adapterId: request.body.adapterId, status: "disabled", activeRevisionId: null, revision: nextRevision, createdAt: existing?.created_at ?? now, updatedAt: now };
+      const statements: QueryStatement[] = [
+        existing
+          ? { sql: `UPDATE app_installs SET app_version = ?, status = 'suspended', scopes = '[]', manifest = '{}', webhook_endpoint = NULL, widget_placements = '[]', install_actor = ?, managed_active_revision_id = NULL, managed_candidate = ?, managed_revision = ?, updated_at = ? WHERE install_id = ? AND app_id = ? AND tenant_id = ? AND env = 'production' AND managed_kind = ? AND status = 'uninstalled' AND managed_revision = ?`, params: [request.body.adapterVersion, ctx.actor, JSON.stringify(candidate), nextRevision, now, installId, request.body.adapterId, ctx.tenantId, KIND, existing.managed_revision] }
+          : { sql: `INSERT INTO app_installs (install_id, app_id, app_version, tenant_id, env, status, scopes, manifest, webhook_endpoint, widget_placements, install_actor, managed_kind, managed_revision, managed_candidate, created_at, updated_at) VALUES (?,?,?,?,?,'suspended','[]','{}',NULL,'[]',?,?,?,?,?,?)`, params: [installId, request.body.adapterId, request.body.adapterVersion, ctx.tenantId, "production", ctx.actor, KIND, nextRevision, JSON.stringify(candidate), now, now] },
+        this.auditStatement(installId, ctx, "managed_analytics.candidate_staged", { revision, digest: candidate.digest }, existing !== null),
+      ];
+      return {
+        response: mutationSuccess({ install, revision }),
+        statements,
+        ...(existing ? { casStillCurrent: () => this.installStillTombstoned(ctx.tenantId, installId, existing.managed_revision) } : {}),
+      };
+    });
+  }
+  async reviseIntegrationInstall(ctx: ManagedAnalyticsActorContext, request: ReviseIntegrationInstallRequest) {
+    const snapshot = snapshotManagedAnalyticsDeclarativeInput<ReviseIntegrationInstallRequest>(request);
+    if (!snapshot.ok) return error("validation_failed", "The request failed validation.", snapshot.violations);
+    const prepared = validateReviseIntegrationInstallRequest(snapshot.value);
+    if (!prepared.ok) return this.rejectInvalidMutation<{ install: IntegrationInstall; revision: IntegrationRevisionV1 }>(ctx, "reviseIntegrationInstall", snapshot.value, prepared.violations, "installId");
+    request = prepared.value;
+    return this.idempotent(ctx, "reviseIntegrationInstall", request, request.body.installId, async () => {
+      const row = await this.ownedInstall(ctx.tenantId, request.body.installId);
+      if (!row) return { response: notFound(), statements: [] };
+      if (row.managed_revision !== request.expectedRevision) return { response: stale(), statements: [] };
+      const validated = await validateManagedAnalyticsCandidate({ adapterId: row.app_id, adapterVersion: request.body.adapterVersion, configuration: request.body.configuration }, ctx.tenantId);
+      if (!validated.ok) return { response: error("validation_failed", "The integration revision failed validation.", validated.details), statements: [] };
+      const now = this.now();
+      const revision: IntegrationRevisionV1 = { schemaVersion: 1, revisionId: publicId("revision"), installId: row.install_id, adapterId: row.app_id, adapterVersion: request.body.adapterVersion, sequence: row.managed_revision + 1, status: "draft", configuration: { ...request.body.configuration }, createdAt: now };
+      const priorApproved = (await this.versions.listVersions(row.install_id)).find((snapshot) =>
+        snapshot.appVersion === request.body.adapterVersion &&
+        canonicalJson(snapshot.facets.publicConfig) === canonicalJson(request.body.configuration) &&
+        snapshot.facets.digest === validated.effects.digest);
+      const candidate: StoredCandidate = { revision, digest: validated.effects.digest, effects: validated.effects, manifest: validated.manifest, facets: validated.facets, approvedAt: now, ...(priorApproved ? { rollbackFromSeq: priorApproved.seq } : {}) };
+      const install = { ...publicInstall(row), revision: row.managed_revision + 1, updatedAt: now };
+      const update: QueryStatement = { sql: `UPDATE app_installs SET managed_candidate = ?, managed_revision = ?, updated_at = ? WHERE install_id = ? AND tenant_id = ? AND managed_kind = ? AND managed_revision = ? AND status != 'uninstalled'`, params: [JSON.stringify(candidate), install.revision, now, row.install_id, ctx.tenantId, KIND, request.expectedRevision] };
+      return { response: mutationSuccess({ install, revision }), statements: [update, this.auditStatement(row.install_id, ctx, "managed_analytics.candidate_staged", { revision, digest: candidate.digest }, true)], casStillCurrent: () => this.installStillCurrent(ctx.tenantId, row.install_id, request.expectedRevision) };
+    });
+  }
+
+  async setIntegrationInstallStatus(ctx: ManagedAnalyticsActorContext, request: SetIntegrationInstallStatusRequest) {
+    const snapshot = snapshotManagedAnalyticsDeclarativeInput<SetIntegrationInstallStatusRequest>(request);
+    if (!snapshot.ok) return error("validation_failed", "The request failed validation.", snapshot.violations);
+    const prepared = validateSetIntegrationInstallStatusRequest(snapshot.value);
+    if (!prepared.ok) return this.rejectInvalidMutation<IntegrationInstall>(ctx, "setIntegrationInstallStatus", snapshot.value, prepared.violations, "installId");
+    request = prepared.value;
+    return this.idempotent(ctx, "setIntegrationInstallStatus", request, request.body.installId, async () => {
+      const row = await this.ownedInstall(ctx.tenantId, request.body.installId);
+      if (!row) return { response: notFound(), statements: [] };
+      if (row.managed_revision !== request.expectedRevision) return { response: stale(), statements: [] };
+      const now = this.now(); const nextRevision = row.managed_revision + 1;
+      if (request.body.status === "disabled") {
+        if (row.status === "suspended") {
+          return { response: mutationSuccess(publicInstall(row)), statements: [] };
+        }
+        const update: QueryStatement = { sql: `UPDATE app_installs SET status = 'suspended', managed_revision = ?, updated_at = ? WHERE install_id = ? AND tenant_id = ? AND managed_kind = ? AND managed_revision = ? AND status != 'uninstalled'`, params: [nextRevision, now, row.install_id, ctx.tenantId, KIND, request.expectedRevision] };
+        const install = { ...publicInstall(row), status: "disabled" as const, revision: nextRevision, updatedAt: now };
+        return { response: mutationSuccess(install), statements: [update, this.auditStatement(row.install_id, ctx, "managed_analytics.suspended", {}, true)], casStillCurrent: () => this.installStillCurrent(ctx.tenantId, row.install_id, request.expectedRevision) };
+      }
+      const candidate = parseCandidate(row); const existingLive = parseLive(row);
+      if (!candidate && !existingLive) return { response: error("conflict", "No approved candidate is available to publish."), statements: [] };
+      if (!candidate && existingLive) {
+        const current = await this.versions.currentVersion(row.install_id);
+        const validated = current ? await validateManagedAnalyticsCandidate({ adapterId: row.app_id, adapterVersion: current.appVersion, configuration: current.facets.publicConfig as Record<string, AdapterConfigValue> }, ctx.tenantId) : null;
+        if (!validated?.ok || validated.effects.digest !== current?.facets.digest || validated.manifest.app.digest !== existingLive.app.digest || !row.managed_active_revision_id) return { response: error("conflict", "The approved live digest no longer matches."), statements: [] };
+        if (row.status === "active") {
+          return { response: mutationSuccess(publicInstall(row)), statements: [] };
+        }
+        const update: QueryStatement = { sql: `UPDATE app_installs SET status = 'active', managed_revision = ?, updated_at = ? WHERE install_id = ? AND tenant_id = ? AND managed_kind = ? AND managed_revision = ? AND status = 'suspended'`, params: [nextRevision, now, row.install_id, ctx.tenantId, KIND, request.expectedRevision] };
+        const install = { ...publicInstall(row), status: "enabled" as const, revision: nextRevision, updatedAt: now };
+        return { response: mutationSuccess(install), statements: [update, this.auditStatement(row.install_id, ctx, "managed_analytics.resumed", { revisionId: row.managed_active_revision_id, digest: current.facets.digest }, true)], casStillCurrent: () => this.installStillCurrent(ctx.tenantId, row.install_id, request.expectedRevision) };
+      }
+      const approved = await validateManagedAnalyticsCandidate({ adapterId: candidate!.revision.adapterId, adapterVersion: candidate!.revision.adapterVersion, configuration: candidate!.revision.configuration }, ctx.tenantId);
+      if (!approved.ok || approved.effects.digest !== candidate!.digest || canonicalJson(approved.manifest) !== canonicalJson(candidate!.manifest)) return { response: error("conflict", "The approved candidate digest no longer matches."), statements: [] };
+      const planned = candidate!.rollbackFromSeq !== undefined
+        ? await this.versions.planRollbackTo({ installId: row.install_id, toSeq: candidate!.rollbackFromSeq, actor: ctx.actor, note: "managed-analytics rollback publish" })
+        : await this.versions.planRetainVersion({ installId: row.install_id, tenantId: ctx.tenantId, facets: candidate!.facets, actor: ctx.actor, note: "managed-analytics publish" });
+      const update: QueryStatement = { sql: `UPDATE app_installs SET status = 'active', app_version = ?, manifest = ?, managed_active_revision_id = ?, managed_candidate = NULL, managed_revision = ?, updated_at = ? WHERE install_id = ? AND tenant_id = ? AND managed_kind = ? AND managed_revision = ? AND status != 'uninstalled'`, params: [candidate!.revision.adapterVersion, JSON.stringify(candidate!.manifest), candidate!.revision.revisionId, nextRevision, now, row.install_id, ctx.tenantId, KIND, request.expectedRevision] };
+      const install: IntegrationInstall = { ...publicInstall(row), status: "enabled", activeRevisionId: candidate!.revision.revisionId, revision: nextRevision, updatedAt: now };
+      return { response: mutationSuccess(install), statements: [update, this.auditStatement(row.install_id, ctx, "managed_analytics.published", { revisionId: candidate!.revision.revisionId, digest: candidate!.digest }, true), planned.statement], casStillCurrent: () => this.installStillCurrent(ctx.tenantId, row.install_id, request.expectedRevision) };
+    });
+  }
+  async deleteIntegrationInstall(ctx: ManagedAnalyticsActorContext, request: DeleteIntegrationInstallRequest) {
+    const snapshot = snapshotManagedAnalyticsDeclarativeInput<DeleteIntegrationInstallRequest>(request);
+    if (!snapshot.ok) return error("validation_failed", "The request failed validation.", snapshot.violations);
+    const prepared = validateDeleteIntegrationInstallRequest(snapshot.value);
+    if (!prepared.ok) return this.rejectInvalidMutation<{ deleted: true }>(ctx, "deleteIntegrationInstall", snapshot.value, prepared.violations, "installId");
+    request = prepared.value;
+    return this.idempotent(ctx, "deleteIntegrationInstall", request, request.body.installId, async () => {
+      const row = await this.ownedInstall(ctx.tenantId, request.body.installId);
+      if (!row) return { response: notFound(), statements: [] };
+      if (row.managed_revision !== request.expectedRevision) return { response: stale(), statements: [] };
+      const now = this.now();
+      const update: QueryStatement = { sql: `UPDATE app_installs SET status = 'uninstalled', app_version = 'removed', scopes = '[]', manifest = '{}', webhook_endpoint = NULL, widget_placements = '[]', managed_active_revision_id = NULL, managed_candidate = NULL, managed_revision = ?, updated_at = ? WHERE install_id = ? AND tenant_id = ? AND managed_kind = ? AND managed_revision = ? AND status != 'uninstalled'`, params: [row.managed_revision + 1, now, row.install_id, ctx.tenantId, KIND, request.expectedRevision] };
+      return { response: mutationSuccess({ deleted: true as const }), statements: [update, this.auditStatement(row.install_id, ctx, "managed_analytics.removed", {}, true)], casStillCurrent: () => this.installStillCurrent(ctx.tenantId, row.install_id, request.expectedRevision) };
+    });
+  }
+
+  private async ownedInstall(tenantId: string, installId: string): Promise<InstallRow | null> {
+    return this.db.first<InstallRow>(`SELECT * FROM app_installs WHERE install_id = ? AND tenant_id = ? AND managed_kind = ? AND status != 'uninstalled'`, installId, tenantId, KIND);
+  }
+  private async adapterSlot(tenantId: string, adapterId: string): Promise<InstallRow | null> {
+    return this.db.first<InstallRow>(`SELECT * FROM app_installs WHERE app_id = ? AND tenant_id = ? AND env = 'production'`, adapterId, tenantId);
+  }
+  private async installStillTombstoned(tenantId: string, installId: string, revision: number): Promise<boolean> {
+    const row = await this.db.first<Pick<InstallRow, "status" | "managed_kind" | "managed_revision">>(
+      `SELECT status, managed_kind, managed_revision FROM app_installs WHERE install_id = ? AND tenant_id = ?`,
+      installId,
+      tenantId,
+    );
+    return row?.status === "uninstalled" && row.managed_kind === KIND && row.managed_revision === revision;
+  }
+  private async installStillCurrent(tenantId: string, installId: string, revision: number): Promise<boolean> {
+    return (await this.ownedInstall(tenantId, installId))?.managed_revision === revision;
+  }
+  private async revisions(row: InstallRow): Promise<IntegrationRevisionV1[]> {
+    const audits = await this.db.all<AuditRow>(`SELECT id, event, detail, at FROM app_audit_log WHERE install_id = ? AND tenant_id = ? AND event = 'managed_analytics.candidate_staged' ORDER BY at, id`, row.install_id, row.tenant_id);
+    const liveId = row.managed_active_revision_id; const candidateId = parseCandidate(row)?.revision.revisionId ?? null;
+    return audits.map((audit) => {
+      const detail = JSON.parse(audit.detail) as unknown;
+      const safe = validateManagedAnalyticsSafePayload(detail);
+      const revision = detail && typeof detail === "object" && !Array.isArray(detail)
+        ? validateIntegrationRevisionV1((detail as Record<string, unknown>)["revision"])
+        : { ok: false as const, violations: [] };
+      if (!safe.ok || !revision.ok || revision.value.installId !== row.install_id) {
+        throw new Error("Managed analytics revision failed persisted-data validation.");
+      }
+      return revision.value;
+    })
+      .map((revision) => ({ ...revision, status: revision.revisionId === liveId ? "active" : revision.revisionId === candidateId ? "draft" : "superseded" }));
+  }
+  private async loadDraft(tenantId: string, draftId: string): Promise<{ draft: MigrationDraftV1; open: boolean } | null> {
+    const row = await this.db.first<DraftRow>(`SELECT * FROM integration_migration_drafts WHERE draft_id = ? AND tenant_id = ? AND state = 'open'`, draftId, tenantId);
+    if (!row) return null;
+    const draft = validateMigrationDraftV1(JSON.parse(row.record) as unknown);
+    if (!draft.ok || draft.value.draftId !== row.draft_id || draft.value.revision !== row.revision) {
+      throw new Error("Managed analytics draft failed persisted-data validation.");
+    }
+    return { draft: draft.value, open: true };
+  }
+  private tenantScope(ctx: ManagedAnalyticsActorContext): string { return `managed-analytics-tenant:${ctx.tenantId}`; }
+  private async rejectInvalidMutation<T>(
+    ctx: ManagedAnalyticsActorContext,
+    operation: ManagedAnalyticsOperation,
+    snapshot: unknown,
+    violations: NonNullable<ApiErrorEnvelope["error"]["details"]>,
+    resourceKey?: "draftId" | "installId",
+  ): Promise<MutationResult<T>> {
+    const request = record(snapshot);
+    const rejected = error("validation_failed", "The request failed validation.", violations);
+    if (!request || !validIdempotencyKey(request["idempotencyKey"])) {
+      return error("validation_failed", "The request failed validation.");
+    }
+    const body = record(request["body"]);
+    const resourceId = resourceKey && body ? body[resourceKey] : undefined;
+    const scope = resourceKey && validSafeOpaqueId(resourceId) ? resourceId : this.tenantScope(ctx);
+    return this.idempotent<T>(ctx, operation, request as { idempotencyKey: string }, scope, async () => ({ response: rejected, statements: [] }));
+  }
+  private auditStatement(installId: string, ctx: ManagedAnalyticsActorContext, event: string, detail: Record<string, unknown>, assertPreviousChange = false, id = publicId("audit")): QueryStatement {
+    return { sql: `INSERT INTO app_audit_log (id, install_id, tenant_id, event, actor, trace_id, detail, at) VALUES (${assertPreviousChange ? "CASE WHEN changes() = 1 THEN ? ELSE NULL END" : "?"},?,?,?,?,NULL,?,?)`, params: [id, installId, ctx.tenantId, event, ctx.actor, JSON.stringify(detail), this.now()] };
+  }
+  private async idempotent<T>(ctx: ManagedAnalyticsActorContext, operation: ManagedAnalyticsOperation, request: { idempotencyKey: string }, scope: string, planMutation: () => Promise<MutationPlan<T>>): Promise<MutationResult<T>> {
+    const key = `${operation}:${request.idempotencyKey}`; const digest = await sha256Hex(canonicalJson(request));
+    // `idempotency_keys.install_id` is a generic resource-scope column, not a
+    // foreign key. Hash the authenticated tenant together with the public
+    // resource scope so replay is impossible before (or without) an ownership
+    // read, even when another tenant knows both an id and a retry key.
+    const ledgerScope = `managed-analytics:${await sha256Hex(canonicalJson([ctx.tenantId, scope]))}`;
+    const prior = await this.db.first<IdempotencyRow>(`SELECT body_hash, response_body FROM idempotency_keys WHERE install_id = ? AND idempotency_key = ?`, ledgerScope, key);
+    if (prior) return this.replay<T>(prior, digest, operation);
+    const plan = await planMutation();
+    // The ledger is itself a persisted outbound-response authority. Refuse to
+    // store anything that the frozen v1 response contract would reject, even
+    // if a future mutation planner accidentally constructs an unsafe value.
+    const outbound = sanitizeManagedAnalyticsOutbound(operation, plan.response);
+    if (!outbound) return internalError();
+    const persistedResponse = outbound as MutationResult<T>;
+    if (!this.db.batch) throw new Error("Atomic D1 batch support is required.");
+    const ledger: QueryStatement = { sql: `INSERT INTO idempotency_keys (install_id, idempotency_key, body_hash, response_body, created_at) VALUES (?,?,?,?,?)`, params: [ledgerScope, key, digest, JSON.stringify(persistedResponse), this.now()] };
+    try {
+      await this.db.batch([ledger, ...plan.statements]);
+      return persistedResponse;
+    } catch (cause) {
+      const raced = await this.db.first<IdempotencyRow>(`SELECT body_hash, response_body FROM idempotency_keys WHERE install_id = ? AND idempotency_key = ?`, ledgerScope, key);
+      if (raced) return this.replay<T>(raced, digest, operation);
+      if (plan.casStillCurrent && !(await plan.casStillCurrent())) return stale();
+      throw cause;
+    }
+  }
+  private replay<T>(row: IdempotencyRow, digest: string, operation: ManagedAnalyticsOperation): MutationResult<T> {
+    if (row.body_hash !== digest) return error("idempotency_conflict", "The idempotency key was already used for a different request.");
+    try {
+      const parsed = JSON.parse(row.response_body) as unknown;
+      const response = record(parsed);
+      if (!response) return internalError();
+      if (Object.prototype.hasOwnProperty.call(response, "error")) {
+        const validated = validateApiErrorEnvelope(response);
+        return validated.ok ? validated.value : internalError();
+      }
+      const outbound = sanitizeManagedAnalyticsOutbound(operation, response);
+      if (!outbound) return internalError();
+      return { ...(outbound as MutationResult<T>), idempotencyReplayed: true };
+    } catch { return internalError(); }
+  }
+}