@tokenoftrust/storefront-runner 2.0.2 → 2.0.4

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

@@ -1,599 +0,0 @@
-/**
- * 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(); }
-  }
-}