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

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

@@ -0,0 +1,125 @@
+/**
+ * The transport-free controller for the integration-config lifecycle write actions
+ * ext-admin-07 uniquely owns — `preview` / `publish` / `rollback` — over the pure
+ * {@link integrationLifecycle} state machine. (The install-status actions
+ * `suspend` / `resume` / `uninstall` already have their own registry-backed routes;
+ * this controller does not duplicate them.)
+ *
+ * It is the seam the Astro route wires real I/O into: loading the current lifecycle
+ * state, resolving the candidate evidence to preview, resolving the policy-06 gate
+ * input to publish, and persisting an advanced state — every effect an injected
+ * dependency, so the controller stays unit-testable against in-memory deps. The pure
+ * transitions decide; this only routes the request to one and maps the result to an
+ * HTTP status. A refusal never persists (the state is returned unchanged), so a
+ * blocked publish leaves the ACTUAL last-good state exactly as loaded.
+ */
+import type { IntegrationCandidateEvidence, IntegrationPromotionGateInput } from "@tot/public-runtime";
+import {
+  stageCandidate,
+  publishCandidate,
+  rollbackIntegration,
+  type TenantIntegrationLifecycleState,
+  type LifecycleResult,
+  type PreviewResult,
+  type LifecycleRefusalReason,
+} from "./integrationLifecycle.js";
+
+/** The write actions this controller owns (status actions live on their own routes). */
+export type LifecycleWriteAction = "preview" | "publish" | "rollback";
+
+export interface LifecycleRequest {
+  action: LifecycleWriteAction;
+  installId: string;
+  /** Opaque audit actor (already pseudonymized by the session resolver). */
+  actor: string;
+  /** `publish` only — optimistic concurrency against the live slot the caller last saw. */
+  expectedLiveRevision?: string | null;
+  /** `rollback` only — explicit known-good revision; omit for "one step back". */
+  targetRevision?: string;
+}
+
+/** Everything the controller needs to reach the world — each an injected effect. */
+export interface LifecycleDeps {
+  /** The current lifecycle state for an install; `null` when not materialized yet. */
+  load(installId: string): Promise<TenantIntegrationLifecycleState | null>;
+  /** Persist an advanced state (called only when a transition applied). */
+  save(state: TenantIntegrationLifecycleState): Promise<void>;
+  /** The candidate evidence to stage for `preview`; `null` when none is prepared. */
+  resolveCandidateEvidence(installId: string): Promise<IntegrationCandidateEvidence | null>;
+  /** The policy-06 gate input for `publish`; `null` when it cannot be materialized. */
+  resolveGate(installId: string): Promise<IntegrationPromotionGateInput | null>;
+}
+
+export interface LifecycleControllerResult {
+  status: number;
+  body: unknown;
+}
+
+/** HTTP status for each pure-core refusal reason — the one fail-closed mapping. */
+const STATUS_BY_REASON: Record<LifecycleRefusalReason, number> = {
+  not_active: 409,
+  no_candidate: 409,
+  version_mismatch: 409,
+  gate_blocked: 422,
+  stale_live: 409,
+  no_known_good: 409,
+  unknown_target: 404,
+  already_removed: 409,
+  not_suspended: 409,
+  invalid_stage: 422,
+  cross_tenant: 403,
+  integrity: 500,
+};
+
+function refusalResponse(result: Exclude<LifecycleResult, { ok: true }>): LifecycleControllerResult {
+  return {
+    status: STATUS_BY_REASON[result.reason],
+    body: { error: result.blockers.join("; "), code: result.reason, event: result.event },
+  };
+}
+
+/**
+ * Execute one lifecycle write action end-to-end: load state, run the pure transition,
+ * and persist ONLY on success. Returns the HTTP status + body the route serializes.
+ * Fail-closed: an unmaterialized install (or a `preview`/`publish` whose evidence/gate
+ * cannot be resolved) is a 409, never a fabricated success.
+ */
+export async function handleLifecycleRequest(
+  deps: LifecycleDeps,
+  req: LifecycleRequest,
+): Promise<LifecycleControllerResult> {
+  const state = await deps.load(req.installId);
+  if (!state) {
+    return { status: 409, body: { error: "integration is not materialized", code: "not_materialized" } };
+  }
+  const ctx = { actor: req.actor };
+
+  if (req.action === "preview") {
+    const evidence = await deps.resolveCandidateEvidence(req.installId);
+    if (!evidence) {
+      return { status: 409, body: { error: "no candidate is prepared to preview", code: "no_candidate" } };
+    }
+    const result: PreviewResult = stageCandidate(state, evidence, ctx);
+    if (!result.ok) return refusalResponse(result);
+    await deps.save(result.state);
+    return { status: 200, body: { event: result.event, diff: result.diff } };
+  }
+
+  if (req.action === "publish") {
+    const gate = await deps.resolveGate(req.installId);
+    if (!gate) {
+      return { status: 409, body: { error: "candidate cannot be gated for promotion", code: "not_materialized" } };
+    }
+    const opts = req.expectedLiveRevision !== undefined ? { expectedLiveRevision: req.expectedLiveRevision } : {};
+    const result = publishCandidate(state, gate, ctx, opts);
+    if (!result.ok) return refusalResponse(result);
+    await deps.save(result.state);
+    return { status: 200, body: { event: result.event, liveRevision: result.state.stages.live?.planRevision ?? null } };
+  }
+
+  const opts = req.targetRevision !== undefined ? { targetRevision: req.targetRevision } : {};
+  const result = rollbackIntegration(state, ctx, opts);
+  if (!result.ok) return refusalResponse(result);
+  await deps.save(result.state);
+  return { status: 200, body: { event: result.event, liveRevision: result.state.stages.live?.planRevision ?? null } };
+}

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

@@ -0,0 +1,563 @@
+/**
+ * The effective integration admin read model (ext-admin-02) — the tenant-scoped
+ * data behind ext-admin-01's `/admin#integrations` IA.
+ *
+ * This assembler COMPOSES the already-materialized runtime contracts into one safe
+ * admin view: the tenant's desired config, the resolved effective plan
+ * (ext-kernel-03), its compiled CSP additions (ext-policy-02), the consent snapshot
+ * (ext-policy-03), the elevated-integration assurance decision (ext-policy-05), the
+ * pending candidate evidence + promotion verdict (ext-kernel-06), and the recorded
+ * known-good version. Like the resolver it consumes, it is PURE and SYNCHRONOUS over
+ * already-materialized inputs — materializing them is the control plane's job (the
+ * route below), composing them into a safe view is this function's.
+ *
+ * It holds five safety properties by construction, one per acceptance clause:
+ *   1. TENANT-SCOPED — every input's tenant is asserted equal to the resolved scope;
+ *      a foreign plan/evidence/assurance/install is a fail-closed violation, so a
+ *      mis-plumbed control plane can never leak another tenant's state. (The route
+ *      is the first gate: a vendor/other tenant is denied before assembly.)
+ *   2. SECRETS REDACTED — desired config is the one raw tenant-input surface; its
+ *      secret-named keys are DROPPED (their paths recorded, never their values), and
+ *      the whole assembled model is re-scanned with {@link findForbiddenFields} as
+ *      defense in depth: any surviving secret field fails the assembly closed.
+ *   3. DESIRED-vs-EFFECTIVE EXPLICIT — {@link DesiredEffectiveDrift} names each field
+ *      whose desired input differs from what is effectively serving, and marks a
+ *      desired config that has not materialized into any effective plan at all.
+ *   4. CANDIDATE / STAGED / LIVE UNMISTAKABLE — the pending candidate and the serving
+ *      effective state are SEPARATE typed slots that are never merged; each carries
+ *      its own lifecycle stage, and a candidate that claims the live stage is a
+ *      fail-closed violation (a candidate is never live).
+ *   5. ROLLBACK ACCURATE — {@link RollbackAvailability} is available only when a real
+ *      known-good live version is recorded, and it says whether that target is already
+ *      the effective version (a rollback that would change nothing).
+ */
+import type { AppInstallStatus } from "./registryService.js";
+import {
+  type IntegrationAuthorityTier,
+  type IntegrationInstallStatus,
+  type IntegrationInventoryItem,
+  type IntegrationDetailView,
+  type IntegrationEffectiveAuthority,
+  type IntegrationDiagnosticIssue,
+  type IntegrationOwner,
+} from "./integrationsView.js";
+import {
+  findForbiddenFields,
+  isForbiddenKey,
+  decideAssurance,
+  verifyCandidatePromotable,
+  INTEGRATION_CSP_DIRECTIVES,
+  type ContractResult,
+  type ContractViolation,
+  type EffectivePlan,
+  type CompiledIntegrationCsp,
+  type IntegrationCspAdditions,
+  type ConsentSnapshot,
+  type ConsentPurpose,
+  type IntegrationEnvironment,
+  type ExecutionTier,
+  type ComplianceAssuranceRecord,
+  type AssuranceDecisionContext,
+  type AssuranceSurface,
+  type AssuranceClassification,
+  type AssuranceDenialReason,
+  type IntegrationCandidateEvidence,
+  type ServedObservation,
+} from "@tot/public-runtime";
+
+/** A lifecycle stage — the same closed set the runtime environment uses. */
+export type IntegrationLifecycleStage = IntegrationEnvironment;
+
+/**
+ * What is CURRENTLY SERVING for this install — the ACTUAL/effective state. It carries
+ * its OWN stage (`local`/`staged`/`live`) and is a slot distinct from the candidate:
+ * the two are never merged, so a reviewer can never mistake the pending candidate for
+ * what is live.
+ */
+export interface EffectiveIntegrationState {
+  stage: IntegrationLifecycleStage;
+  planRevision: string;
+  version: string;
+  cspOrigins: string[];
+  consentEligible: ConsentPurpose[];
+}
+
+/**
+ * The PENDING candidate under review — always the `candidate` stage (asserted; a
+ * candidate is never live) and always its own slot, so it is never conflated with the
+ * effective serving state.
+ */
+export interface CandidateIntegrationState {
+  stage: "candidate";
+  planRevision: string;
+  version: string;
+  promotable: boolean;
+  blockers: string[];
+}
+
+/** The tenant's DESIRED (input) configuration, with secret-named keys already redacted. */
+export interface DesiredIntegrationState {
+  version: string;
+  config: Record<string, unknown>;
+}
+
+/** One field whose desired input differs from what is effectively serving. */
+export interface DesiredEffectiveChange {
+  field: string;
+  desired: unknown;
+  effective: unknown;
+}
+
+/** Whether the desired input matches the effective serving state, made explicit. */
+export interface DesiredEffectiveDrift {
+  /** True only when an effective plan exists AND every desired field matches it. */
+  inSync: boolean;
+  /** True when a desired config exists but nothing has materialized into an effective plan yet. */
+  unmaterialized: boolean;
+  changes: DesiredEffectiveChange[];
+}
+
+/** Accurate rollback availability — reflects a real recorded known-good live version. */
+export interface RollbackAvailability {
+  available: boolean;
+  targetVersion: string | null;
+  targetRevision: string | null;
+  /** True when the known-good target is already the effective version (a no-op rollback). */
+  isCurrent: boolean;
+  reason: string;
+}
+
+/** The elevated-integration assurance state, decided fail-closed by ext-policy-05. */
+export interface AssuranceReadState {
+  surface: AssuranceSurface;
+  classification: AssuranceClassification;
+  approved: boolean;
+  outsideGuarantee: boolean;
+  denials: AssuranceDenialReason[];
+}
+
+/** One assembled read-model row: the full effective view of one install. */
+export interface IntegrationReadModelItem {
+  installId: string;
+  appId: string;
+  purpose: string;
+  /** Coarse admin-display status derived from the raw install status + lifecycle slots. */
+  status: IntegrationInstallStatus;
+  /** The raw install-record status — kept DISTINCT from the derived display status. */
+  installStatus: AppInstallStatus;
+  authorityTier: IntegrationAuthorityTier;
+  effective: EffectiveIntegrationState | null;
+  candidate: CandidateIntegrationState | null;
+  desired: DesiredIntegrationState;
+  drift: DesiredEffectiveDrift;
+  effectiveAuthority: IntegrationEffectiveAuthority | null;
+  assurance: AssuranceReadState | null;
+  rollback: RollbackAvailability;
+  diagnostics: IntegrationDiagnosticIssue[];
+  /** Desired-config key paths withheld because they name secret material — never the values. */
+  redactedFields: string[];
+  lastActivity: { actor: string; at: string } | null;
+}
+
+/** The full tenant-scoped admin read model for one lifecycle stage. */
+export interface IntegrationAdminReadModel {
+  tenantPublicId: string;
+  stage: IntegrationLifecycleStage;
+  items: IntegrationReadModelItem[];
+}
+
+/** One install's already-materialized input; every nullable slot is an honest "not yet". */
+export interface IntegrationReadModelInputItem {
+  install: {
+    installId: string;
+    appId: string;
+    appVersion: string;
+    tenantId: string;
+    status: AppInstallStatus;
+  };
+  /** Plain-language purpose for the inventory row — never an internal adapter name. */
+  purpose: string;
+  /** The tenant's DESIRED config input (raw; secret-named keys are redacted here). */
+  desiredConfig: Record<string, unknown>;
+  /** The install's declared authority tier, used until an effective plan resolves one. */
+  declaredTier?: IntegrationAuthorityTier;
+  /** The EFFECTIVE resolved plan currently serving this tenant/stage, or null if unmaterialized. */
+  effectivePlan?: EffectivePlan | null;
+  /** Compiled CSP bound to the effective plan (its `planRevision` must match), or null. */
+  effectiveCsp?: CompiledIntegrationCsp | null;
+  /** The consent snapshot the effective plan filters against, or null. */
+  consentSnapshot?: ConsentSnapshot | null;
+  /** The elevated-integration assurance record + decision context, when one resolved. */
+  assurance?: { record: ComplianceAssuranceRecord; context: AssuranceDecisionContext } | null;
+  /** The pending candidate: its evidence + what a mount actually served (for parity), when any. */
+  candidate?: { evidence: IntegrationCandidateEvidence; served?: ServedObservation | null } | null;
+  /** The recorded known-good live version to roll back to, or null if none ever lived. */
+  knownGood?: { version: string; revision: string } | null;
+  /** Extra developer diagnostics the control plane already derived. */
+  diagnostics?: IntegrationDiagnosticIssue[];
+  lastActivity?: { actor: string; at: string } | null;
+}
+
+export interface AssembleReadModelInput {
+  /** The auth-resolved tenant scope. Every item MUST belong to it. */
+  tenantPublicId: string;
+  /** The lifecycle stage this admin view is resolved for. */
+  stage: IntegrationLifecycleStage;
+  items: readonly IntegrationReadModelInputItem[];
+}
+
+/** Map a runtime execution tier to the admin authority-tier vocabulary. */
+function mapExecutionTier(tier: ExecutionTier): IntegrationAuthorityTier {
+  return tier === "sandbox" ? "sandbox-broker" : tier;
+}
+
+/** Recursively drop secret-named keys, recording their paths — never their values. */
+function redactForbidden(
+  value: Record<string, unknown>,
+  base = "",
+): { config: Record<string, unknown>; redacted: string[] } {
+  const out: Record<string, unknown> = {};
+  const redacted: string[] = [];
+  for (const [key, child] of Object.entries(value)) {
+    const path = base ? `${base}.${key}` : key;
+    if (isForbiddenKey(key)) {
+      redacted.push(path);
+      continue;
+    }
+    if (isPlainRecord(child)) {
+      const nested = redactForbidden(child, path);
+      out[key] = nested.config;
+      redacted.push(...nested.redacted);
+    } else {
+      out[key] = child;
+    }
+  }
+  return { config: out, redacted };
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Sorted, deduped exact origins across all contributable directives. */
+function flattenCspOrigins(additions: IntegrationCspAdditions | undefined): string[] {
+  if (!additions) return [];
+  const set = new Set<string>();
+  for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+    for (const origin of additions[directive] ?? []) set.add(origin);
+  }
+  return [...set].sort();
+}
+
+/** The coarse admin-display status — derived, never the raw install status. */
+function deriveDisplayStatus(
+  installStatus: AppInstallStatus,
+  effective: EffectiveIntegrationState | null,
+  candidate: CandidateIntegrationState | null,
+  diagnostics: readonly IntegrationDiagnosticIssue[],
+): IntegrationInstallStatus {
+  if (installStatus === "suspended" || installStatus === "uninstalled") return "suspended";
+  if (diagnostics.some((d) => d.severity === "blocking")) return "error";
+  if (effective && effective.stage === "live") return "live";
+  if (candidate || effective) return "preview-ready";
+  return "configuring";
+}
+
+/**
+ * Assemble the tenant-scoped effective integration read model from already-materialized
+ * inputs. Fail-closed: a cross-tenant input, a candidate that claims the live stage, or
+ * any secret field surviving into the assembled model yields violations and NO model.
+ */
+export function assembleIntegrationReadModel(
+  input: AssembleReadModelInput,
+): ContractResult<IntegrationAdminReadModel> {
+  const violations: ContractViolation[] = [];
+  const scope = input.tenantPublicId;
+
+  if (typeof scope !== "string" || scope.length === 0) {
+    violations.push({ path: "tenantPublicId", code: "type", message: "tenantPublicId must be a non-empty string." });
+    return { ok: false, violations };
+  }
+
+  const items: IntegrationReadModelItem[] = [];
+
+  input.items.forEach((raw, index) => {
+    const path = `items[${index}]`;
+
+    // 1. TENANT SCOPE — every materialized input must belong to the resolved scope.
+    if (raw.install.tenantId !== scope) {
+      violations.push({
+        path: `${path}.install.tenantId`,
+        code: "cross_tenant",
+        message: `Install "${raw.install.installId}" is scoped to "${raw.install.tenantId}", not "${scope}".`,
+      });
+    }
+    if (raw.effectivePlan && raw.effectivePlan.tenantPublicId !== scope) {
+      violations.push({
+        path: `${path}.effectivePlan.tenantPublicId`,
+        code: "cross_tenant",
+        message: `Effective plan is scoped to "${raw.effectivePlan.tenantPublicId}", not "${scope}".`,
+      });
+    }
+    if (raw.candidate && raw.candidate.evidence.tenantPublicId !== scope) {
+      violations.push({
+        path: `${path}.candidate.tenantPublicId`,
+        code: "cross_tenant",
+        message: `Candidate evidence is scoped to "${raw.candidate.evidence.tenantPublicId}", not "${scope}".`,
+      });
+    }
+    if (raw.assurance && raw.assurance.record.tenantPublicId !== scope) {
+      violations.push({
+        path: `${path}.assurance.tenantPublicId`,
+        code: "cross_tenant",
+        message: `Assurance record is scoped to "${raw.assurance.record.tenantPublicId}", not "${scope}".`,
+      });
+    }
+
+    const diagnostics: IntegrationDiagnosticIssue[] = [...(raw.diagnostics ?? [])];
+
+    // 2. SECRETS — redact the raw desired input; keep only the withheld paths.
+    const { config: desiredConfig, redacted } = redactForbidden(raw.desiredConfig ?? {});
+    const desired: DesiredIntegrationState = { version: raw.install.appVersion, config: desiredConfig };
+
+    // 4. EFFECTIVE slot — what is serving now (its own stage).
+    const plan = raw.effectivePlan ?? null;
+    const planIntegration = plan?.integrations.find((i) => i.appId === raw.install.appId) ?? null;
+    let effective: EffectiveIntegrationState | null = null;
+    let effectiveAuthority: IntegrationEffectiveAuthority | null = null;
+    if (plan) {
+      if (raw.effectiveCsp && raw.effectiveCsp.planRevision !== plan.planRevision) {
+        diagnostics.push({
+          severity: "blocking",
+          summary: "The compiled CSP does not match the version currently serving.",
+          copyableDetail: `Compiled CSP is bound to plan revision "${raw.effectiveCsp.planRevision}" but the effective plan resolved to "${plan.planRevision}".`,
+        });
+      }
+      const cspOrigins = flattenCspOrigins(raw.effectiveCsp?.additions);
+      const consentEligible = raw.consentSnapshot?.eligiblePurposes ?? [];
+      effective = {
+        stage: plan.environment.environment,
+        planRevision: plan.planRevision,
+        version: planIntegration?.version ?? raw.install.appVersion,
+        cspOrigins,
+        consentEligible: [...consentEligible],
+      };
+      if (planIntegration) {
+        effectiveAuthority = {
+          authorityTier: mapExecutionTier(planIntegration.executionTier),
+          cspOrigins,
+          hasElevatedPiiScope: planIntegration.executionTier === "elevated-parent",
+          consentPurposeIds: [...plan.consentNeeds],
+        };
+      }
+      // A destination that depends on a purpose not yet eligible is a real, surfaced gap.
+      if (raw.consentSnapshot) {
+        for (const purpose of plan.consentNeeds) {
+          if (!raw.consentSnapshot.eligiblePurposes.includes(purpose as ConsentPurpose)) {
+            diagnostics.push({
+              severity: "warning",
+              summary: `This integration depends on "${purpose}" consent, which is not currently granted.`,
+              copyableDetail: `consentNeeds includes "${purpose}" but the resolved consent snapshot ${raw.consentSnapshot.snapshotId} does not make it eligible.`,
+            });
+          }
+        }
+      }
+    }
+
+    // 4. CANDIDATE slot — the pending candidate, always its own stage, never live.
+    let candidate: CandidateIntegrationState | null = null;
+    if (raw.candidate) {
+      const evidence = raw.candidate.evidence;
+      const stage = evidence.environment.environment;
+      if (stage === "live") {
+        violations.push({
+          path: `${path}.candidate.stage`,
+          code: "candidate_is_live",
+          message: `Candidate evidence reports the live stage; a candidate is never live.`,
+        });
+      }
+      const verdict = verifyCandidatePromotable(evidence, raw.candidate.served ?? null);
+      const candVersion = evidence.integrations.find((i) => i.appId === raw.install.appId)?.version ?? evidence.planRevision;
+      candidate = {
+        stage: "candidate",
+        planRevision: evidence.planRevision,
+        version: candVersion,
+        promotable: verdict.ok,
+        blockers: verdict.blockers,
+      };
+      for (const blocker of verdict.blockers) {
+        diagnostics.push({
+          severity: "warning",
+          summary: "This candidate is not yet ready to publish.",
+          copyableDetail: blocker,
+        });
+      }
+    }
+
+    // 3. DESIRED-vs-EFFECTIVE drift, explicit field-by-field.
+    const drift = computeDrift(desired, plan, planIntegration, raw.install.appId);
+
+    // ext-policy-05 assurance decision (composed here, not re-implemented).
+    let assurance: AssuranceReadState | null = null;
+    if (raw.assurance) {
+      const decision = decideAssurance(raw.assurance.record, raw.assurance.context);
+      assurance = {
+        surface: raw.assurance.record.surface,
+        classification: raw.assurance.record.classification,
+        approved: decision.ok,
+        outsideGuarantee: decision.ok ? decision.outsideGuarantee : false,
+        denials: decision.ok ? [] : decision.denials.map((d) => d.reason),
+      };
+      if (!decision.ok) {
+        for (const denial of decision.denials) {
+          diagnostics.push({
+            severity: "blocking",
+            summary: "This integration's compliance assurance is not approved.",
+            copyableDetail: denial.subject ? `${denial.reason} (${denial.subject})` : denial.reason,
+          });
+        }
+      }
+    }
+
+    // 5. ROLLBACK availability — accurate against a real recorded known-good version.
+    const knownGood =
+      raw.knownGood ??
+      (raw.assurance
+        ? { version: raw.assurance.record.rollback.knownGoodVersion, revision: raw.assurance.record.rollback.knownGoodRevision }
+        : null);
+    const rollback = deriveRollback(knownGood, effective);
+
+    if (drift.unmaterialized && Object.keys(desired.config).length > 0) {
+      diagnostics.push({
+        severity: "warning",
+        summary: "The desired configuration has not been published to an effective version yet.",
+        copyableDetail: `Desired config for "${raw.install.appId}" has no resolved effective plan; nothing is serving it.`,
+      });
+    }
+
+    const status = deriveDisplayStatus(raw.install.status, effective, candidate, diagnostics);
+
+    items.push({
+      installId: raw.install.installId,
+      appId: raw.install.appId,
+      purpose: raw.purpose,
+      status,
+      installStatus: raw.install.status,
+      authorityTier: planIntegration ? mapExecutionTier(planIntegration.executionTier) : raw.declaredTier ?? "sandbox-broker",
+      effective,
+      candidate,
+      desired,
+      drift,
+      effectiveAuthority,
+      assurance,
+      rollback,
+      diagnostics,
+      redactedFields: redacted,
+      lastActivity: raw.lastActivity ?? null,
+    });
+  });
+
+  const model: IntegrationAdminReadModel = { tenantPublicId: scope, stage: input.stage, items };
+
+  // 2. SECRETS — defense in depth: no secret field may survive anywhere in the model.
+  for (const violation of findForbiddenFields(model, "readModel")) violations.push(violation);
+
+  if (violations.length > 0) return { ok: false, violations };
+  return { ok: true, value: model };
+}
+
+/** Explicit desired-vs-effective diff. Unmaterialized when nothing is serving the desired config. */
+function computeDrift(
+  desired: DesiredIntegrationState,
+  plan: EffectivePlan | null,
+  planIntegration: EffectivePlan["integrations"][number] | null,
+  appId: string,
+): DesiredEffectiveDrift {
+  if (!plan || !planIntegration) {
+    return { inSync: false, unmaterialized: true, changes: [] };
+  }
+  const effectiveConfig = plan.publicConfig[appId] ?? {};
+  const changes: DesiredEffectiveChange[] = [];
+
+  if (desired.version !== planIntegration.version) {
+    changes.push({ field: "version", desired: desired.version, effective: planIntegration.version });
+  }
+
+  const keys = new Set([...Object.keys(desired.config), ...Object.keys(effectiveConfig)]);
+  for (const key of [...keys].sort()) {
+    const d = desired.config[key];
+    const e = effectiveConfig[key];
+    if (JSON.stringify(d) !== JSON.stringify(e)) {
+      changes.push({ field: `config.${key}`, desired: d, effective: e });
+    }
+  }
+
+  return { inSync: changes.length === 0, unmaterialized: false, changes };
+}
+
+/** Rollback availability is true only for a real recorded known-good version. */
+function deriveRollback(
+  knownGood: { version: string; revision: string } | null,
+  effective: EffectiveIntegrationState | null,
+): RollbackAvailability {
+  if (!knownGood) {
+    return {
+      available: false,
+      targetVersion: null,
+      targetRevision: null,
+      isCurrent: false,
+      reason: "No version has gone live yet; there is no known-good version to roll back to.",
+    };
+  }
+  const isCurrent = effective != null && effective.version === knownGood.version;
+  return {
+    available: true,
+    targetVersion: knownGood.version,
+    targetRevision: knownGood.revision,
+    isCurrent,
+    reason: isCurrent
+      ? "The current version is the known-good version; a rollback would change nothing."
+      : `A known-good version (${knownGood.version}) is available to roll back to.`,
+  };
+}
+
+/**
+ * Project a read-model item onto ext-admin-01's inventory-row view type. The
+ * inventory environment is the effective serving stage when one exists, else the
+ * admin view's resolved stage.
+ */
+export function projectInventoryItem(
+  item: IntegrationReadModelItem,
+  stage: IntegrationLifecycleStage,
+): IntegrationInventoryItem {
+  return {
+    installId: item.installId,
+    appId: item.appId,
+    purpose: item.purpose,
+    status: item.status,
+    environment: item.effective?.stage ?? stage,
+    authorityTier: item.authorityTier,
+    lastActivity: item.lastActivity,
+  };
+}
+
+/**
+ * Project a read-model item onto ext-admin-01's detail view — only once an effective
+ * authority has resolved (a still-configuring install has none). The tenant owns every
+ * desired-config field it supplied.
+ */
+export function projectDetailView(
+  item: IntegrationReadModelItem,
+  stage: IntegrationLifecycleStage,
+): IntegrationDetailView | null {
+  if (!item.effectiveAuthority) return null;
+  const fieldOwners: Record<string, IntegrationOwner> = {};
+  for (const key of Object.keys(item.desired.config)) fieldOwners[key] = "tenant";
+  return {
+    ...projectInventoryItem(item, stage),
+    fieldOwners,
+    effectiveAuthority: item.effectiveAuthority,
+    diagnostics: item.diagnostics,
+    rollbackAvailable: item.rollback.available,
+  };
+}