pi-codex-marketplace 0.1.0

package/src/installation/flow.ts

@@ -0,0 +1,443 @@
+/**
+ * Plugin Installation lifecycle seam.
+ *
+ * A preflight holds the scope Attempt Fence and binds the exact State Revision plus Validation
+ * Snapshot. `Install Disabled` commits immediately after that disclosure; `Install and Enable`
+ * and disabled → enabled require a separate, explicit Activation Confirmation.
+ */
+
+import type { CompatiblePlugin } from '../compatibility/profile.js';
+import { commitBridgeState, readBridgeState } from '../bridge-state/store.js';
+import type { Installation, Registration, Scope } from '../bridge-state/types.js';
+import { CODE, RULE, blocking, hasBlocking, sortFindings, type ValidationFinding } from '../registration/findings.js';
+import { acquireAttemptFence, type AttemptFenceHandle } from '../registration/fence.js';
+import { createReceipt, type AttemptReceipt } from '../registration/receipt.js';
+import { appendReceipt } from '../journal/journal.js';
+import type { ValidationSnapshot } from '../registration/snapshot.js';
+import { inspectMarketplaceEntries } from './inspection.js';
+
+export interface InstallationFlowOptions {
+  cwd?: string;
+  agentDir?: string;
+  projectTrusted?: boolean;
+  fenceTimeoutMs?: number;
+  /** Integration synchronization seam; production callers leave this undefined. */
+  beforeDisableCommit?: () => void | Promise<void>;
+  beforeInstallationCommit?: () => void | Promise<void>;
+}
+
+export interface PluginInstallationPreflight {
+  scope: Scope;
+  registration: Registration;
+  plugin: CompatiblePlugin;
+  snapshot: ValidationSnapshot;
+  stateRevision: string;
+  findings: ValidationFinding[];
+  /** Exact activation material rendered by the TUI before an Activation Confirmation. */
+  disclosure: { plugin: CompatiblePlugin; projectedPrecedence: 'Pi → Project Scope → Global Scope'; findings: ValidationFinding[] };
+  fence: AttemptFenceHandle;
+  terminal: boolean;
+  operation: 'install' | 'enable';
+  existingInstallation?: Installation;
+}
+
+export type InstallationOutcome =
+  | { status: 'completed'; installation: Installation; receipt: AttemptReceipt; newRevision: string }
+  | { status: 'declined'; receipt: AttemptReceipt }
+  | { status: 'blocked'; findings: ValidationFinding[]; receipt: AttemptReceipt }
+  | { status: 'rejected-as-stale'; receipt: AttemptReceipt }
+  | { status: 'persistence-failed'; receipt: AttemptReceipt; isIndeterminate: boolean };
+
+export type InstallationPreflightResult =
+  | { ok: true; preflight: PluginInstallationPreflight }
+  | { ok: false; outcome: InstallationOutcome };
+
+type LifecycleOperation = 'install' | 'enable' | 'disable';
+
+function receiptOperation(operation: LifecycleOperation): string {
+  return operation === 'install' ? 'Plugin Installation'
+    : operation === 'enable' ? 'Plugin Enablement'
+      : 'Plugin Disablement';
+}
+
+function triggerFor(operation: LifecycleOperation, registrationId: string, entryId: string): string {
+  return operation === 'disable' ? `disable ${entryId}` : `${operation} ${registrationId}#${entryId}`;
+}
+
+async function blocked(
+  operation: LifecycleOperation,
+  scope: Scope,
+  registrationId: string,
+  entryId: string,
+  revision: string,
+  findings: ValidationFinding[],
+  fence: AttemptFenceHandle | null = null,
+  opts: InstallationFlowOptions = {},
+): Promise<InstallationPreflightResult> {
+  fence?.release();
+  const receipt = createReceipt({
+    operation: receiptOperation(operation),
+    scope,
+    trigger: triggerFor(operation, registrationId, entryId),
+    expectedStateRevision: revision,
+    summary: 'Blocked',
+    findings,
+  });
+  await appendReceipt(scope, receipt, opts);
+  return {
+    ok: false,
+    outcome: {
+      status: 'blocked',
+      findings,
+      receipt,
+    },
+  };
+}
+
+function scopeDenied(scope: Scope, opts: InstallationFlowOptions): ValidationFinding | undefined {
+  if (scope !== 'project' || opts.projectTrusted === true) return undefined;
+  return blocking({
+    code: CODE.PROJECT_TRUST_DENIED,
+    rule: RULE.PROJECT_TRUST_DENIED,
+    target: 'installation',
+    pointer: '',
+    outcome: 'Project Trust is not granted by the Pi host; no Project Scope Lifecycle Operation may mutate Bridge State',
+    scope,
+    phase: 'admission',
+  });
+}
+
+function operationFinding(
+  scope: Scope,
+  code: string,
+  rule: string,
+  outcome: string,
+  target: ValidationFinding['target'] = 'installation',
+  phase: ValidationFinding['phase'] = 'validation',
+): ValidationFinding {
+  return blocking({ code, rule, target, pointer: '', outcome, scope, phase });
+}
+
+async function makePreflight(
+  scope: Scope,
+  registrationId: string,
+  entryPointer: string,
+  opts: InstallationFlowOptions,
+  operation: 'install' | 'enable',
+  existingInstallation?: Installation,
+): Promise<InstallationPreflightResult> {
+  const read = await readBridgeState(scope, { cwd: opts.cwd, agentDir: opts.agentDir });
+  if (read.status !== 'ok' && read.status !== 'missing') {
+    const receipt = createReceipt({
+      operation: receiptOperation(operation),
+      scope,
+      trigger: triggerFor(operation, registrationId, entryPointer),
+      expectedStateRevision: '?',
+      summary: 'Persistence Indeterminate',
+      findings: [operationFinding(scope, CODE.PERSISTENCE_INDETERMINATE, 'PERSIST-01', read.error ?? 'Bridge State is not readable', 'attempt', 'persistence')],
+    });
+    await appendReceipt(scope, receipt, opts);
+    return { ok: false, outcome: { status: 'persistence-failed', receipt, isIndeterminate: true } };
+  }
+  const state = read.state!;
+  const trust = scopeDenied(scope, opts);
+  if (trust) return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [trust], null, opts);
+  const registration = state.registrations.find((item) => item.id === registrationId);
+  if (!registration) {
+    return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [
+      operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, `Registration '${registrationId}' is not in ${scope} Bridge State`, 'registration'),
+    ], null, opts);
+  }
+  if (registration.sourceKind !== 'local' || !registration.source) {
+    return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [
+      operationFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'This Registration has no retained local Validation Snapshot tree; Git Installation waits for the Source Cache lifecycle', 'registration'),
+    ], null, opts);
+  }
+
+  const fenceResult = await acquireAttemptFence(scope, { cwd: opts.cwd, agentDir: opts.agentDir, fenceTimeoutMs: opts.fenceTimeoutMs, projectTrusted: opts.projectTrusted });
+  if (!fenceResult.ok) return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [fenceResult.finding!], null, opts);
+  const fence = fenceResult.handle!;
+
+  try {
+    const inspection = inspectMarketplaceEntries(registration, scope);
+    const inspected = inspection.entries.find((item) => item.entry.entryId === entryPointer);
+    const rejectedFindings = inspected?.findings ?? (inspection.findings.length > 0 ? inspection.findings : [
+      operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, `Marketplace Entry '${entryPointer}' is Unavailable`, 'entry'),
+    ]);
+    if (!inspected || !inspection.snapshot || !inspected.plugin || inspected.unavailableReason || hasBlocking(inspected.findings)) {
+      return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, rejectedFindings, fence, opts);
+    }
+    const findings = inspected.findings;
+    const plugin = inspected.plugin;
+    const installationId = `${scope}/${plugin.id}`;
+    const currentInstallation = state.installations.find((item) => item.id === installationId);
+    if (operation === 'install' && currentInstallation) {
+      return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [
+        operationFinding(scope, CODE.INSTALLATION_ALREADY_EXISTS, RULE.INSTALLATION_ALREADY_EXISTS, `Installation '${installationId}' already exists; use enable or disable lifecycle actions`),
+      ], fence, opts);
+    }
+    if (operation === 'enable' && (!currentInstallation || currentInstallation.installationState !== 'disabled')) {
+      return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [
+        operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, `Disabled Installation '${installationId}' is no longer current`),
+      ], fence, opts);
+    }
+    return {
+      ok: true,
+      preflight: {
+        scope,
+        registration,
+        plugin,
+        snapshot: inspection.snapshot,
+        stateRevision: state.stateRevision,
+        findings,
+        disclosure: { plugin, projectedPrecedence: 'Pi → Project Scope → Global Scope', findings },
+        fence,
+        terminal: false,
+        operation,
+        existingInstallation: currentInstallation,
+      },
+    };
+  } catch (error) {
+    return blocked(operation, scope, registrationId, entryPointer, state.stateRevision, [
+      operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, error instanceof Error ? error.message : String(error)),
+    ], fence, opts);
+  }
+}
+
+function disclosureText(value: string): string {
+  return JSON.stringify(value);
+}
+
+export function installationDisclosure(preflight: PluginInstallationPreflight): string {
+  const plugin = preflight.plugin;
+  const lines = [
+    `Scope: ${preflight.scope}`,
+    `Plugin: ${disclosureText(plugin.manifestName)} (${disclosureText(plugin.id)})`,
+    `Source: ${disclosureText(preflight.registration.source ?? preflight.registration.canonicalLocator ?? 'unavailable')}`,
+    `Marketplace Entry: ${disclosureText(plugin.marketplaceEntryId)}`,
+    `State Revision: ${preflight.stateRevision}`,
+    `Validation Snapshot: ${preflight.snapshot.fingerprint.slice(0, 16)}…`,
+    `Classification: Compatible`,
+    `Projected precedence: Pi → Project Scope → Global Scope`,
+    `Skills: ${plugin.skills.length}`,
+  ];
+  for (const skill of plugin.skills) {
+    lines.push(`  ${disclosureText(skill.name)} · ${skill.invocationPolicy} · resources: ${skill.resources.length === 0 ? 'none' : skill.resources.map(disclosureText).join(', ')}`);
+  }
+  lines.push(`Findings: ${preflight.findings.length === 0 ? 'none' : preflight.findings.map((finding) => `${finding.classification} ${finding.code}: ${disclosureText(finding.outcome)}`).join(' | ')}`);
+  return lines.join('\n');
+}
+
+export async function preflightPluginInstallation(
+  scope: Scope,
+  registrationId: string,
+  entryPointer: string,
+  opts: InstallationFlowOptions = {},
+): Promise<InstallationPreflightResult> {
+  return makePreflight(scope, registrationId, entryPointer, opts, 'install');
+}
+
+async function rejectedAsStale(preflight: PluginInstallationPreflight, outcome: string, opts: InstallationFlowOptions = {}): Promise<InstallationOutcome> {
+  preflight.fence.release();
+  const receipt = createReceipt({
+    operation: receiptOperation(preflight.operation),
+    scope: preflight.scope,
+    trigger: triggerFor(preflight.operation, preflight.registration.id, preflight.plugin.marketplaceEntryId),
+    expectedStateRevision: preflight.stateRevision,
+    validationSnapshot: preflight.snapshot.fingerprint,
+    summary: 'Rejected as Stale',
+    findings: [blocking({
+      code: CODE.REJECTED_AS_STALE,
+      rule: RULE.REJECTED_AS_STALE,
+      target: 'installation',
+      pointer: '',
+      outcome,
+      scope: preflight.scope,
+      phase: 'persistence',
+    })],
+  });
+  await appendReceipt(preflight.scope, receipt, opts);
+  return {
+    status: 'rejected-as-stale',
+    receipt,
+  };
+}
+
+/** Confirm either path. Enabled state is impossible without explicit Activation Confirmation. */
+export async function confirmPluginInstallation(
+  preflight: PluginInstallationPreflight,
+  targetState: 'enabled' | 'disabled',
+  activationConfirmedOrOpts: boolean | InstallationFlowOptions = false,
+  maybeOpts: InstallationFlowOptions = {},
+): Promise<InstallationOutcome> {
+  const activationConfirmed = typeof activationConfirmedOrOpts === 'boolean' ? activationConfirmedOrOpts : false;
+  const opts = typeof activationConfirmedOrOpts === 'boolean' ? maybeOpts : activationConfirmedOrOpts;
+  if (preflight.terminal) {
+    const result = await blocked(preflight.operation, preflight.scope, preflight.registration.id, preflight.plugin.marketplaceEntryId, preflight.stateRevision, [
+      operationFinding(preflight.scope, CODE.ATTEMPT_IN_PROGRESS, RULE.ATTEMPT_IN_PROGRESS, 'attempt already reached a terminal outcome', 'attempt', 'admission'),
+    ], null, opts);
+    if (!result.ok) return result.outcome;
+    throw new Error('unreachable blocked Installation preflight result');
+  }
+  preflight.terminal = true;
+  if (targetState === 'enabled' && !activationConfirmed) {
+    preflight.fence.release();
+    const receipt = createReceipt({
+      operation: receiptOperation(preflight.operation),
+      scope: preflight.scope,
+      trigger: triggerFor(preflight.operation, preflight.registration.id, preflight.plugin.marketplaceEntryId),
+      expectedStateRevision: preflight.stateRevision,
+      validationSnapshot: preflight.snapshot.fingerprint,
+      summary: 'Declined',
+      findings: [blocking({
+        code: CODE.ACTIVATION_CONFIRMATION_REQUIRED,
+        rule: RULE.ACTIVATION_CONFIRMATION_REQUIRED,
+        target: 'installation',
+        pointer: '',
+        outcome: 'Install and Enable requires a separate explicit Activation Confirmation (default No)',
+        scope: preflight.scope,
+        phase: 'admission',
+      })],
+    });
+    await appendReceipt(preflight.scope, receipt, opts);
+    return {
+      status: 'declined',
+      receipt,
+    };
+  }
+  const current = await readBridgeState(preflight.scope, { cwd: opts.cwd, agentDir: opts.agentDir });
+  if (current.status !== 'ok' && current.status !== 'missing') {
+    preflight.fence.release();
+    const receipt = createReceipt({ operation: receiptOperation(preflight.operation), scope: preflight.scope, trigger: triggerFor(preflight.operation, preflight.registration.id, preflight.plugin.marketplaceEntryId), expectedStateRevision: preflight.stateRevision, validationSnapshot: preflight.snapshot.fingerprint, summary: 'Persistence Indeterminate', findings: [operationFinding(preflight.scope, CODE.PERSISTENCE_INDETERMINATE, 'PERSIST-01', current.error ?? 'Bridge State is not readable', 'attempt', 'persistence')] });
+    await appendReceipt(preflight.scope, receipt, opts);
+    return { status: 'persistence-failed', isIndeterminate: true, receipt };
+  }
+  if (current.state!.stateRevision !== preflight.stateRevision) {
+    return rejectedAsStale(preflight, 'State Revision changed since Installation disclosure; re-run preflight and confirmation', opts);
+  }
+  const fresh = inspectMarketplaceEntries(preflight.registration, preflight.scope);
+  if (!fresh.snapshot || fresh.snapshot.fingerprint !== preflight.snapshot.fingerprint) {
+    return rejectedAsStale(preflight, 'Validation Snapshot changed since Installation disclosure; re-run preflight and confirmation', opts);
+  }
+  const installation: Installation = {
+    id: `${preflight.scope}/${preflight.plugin.id}`,
+    pluginId: preflight.plugin.id,
+    installationState: targetState,
+    registrationId: preflight.registration.id,
+    marketplaceEntryId: preflight.plugin.marketplaceEntryId,
+    validationSnapshot: preflight.snapshot.fingerprint,
+    snapshotBinds: { profile: preflight.snapshot.profile, ruleset: preflight.snapshot.ruleset, budget: preflight.snapshot.budget },
+    manifestName: preflight.plugin.manifestName,
+  };
+  await opts.beforeInstallationCommit?.();
+  const write = await commitBridgeState(preflight.scope, (state) => ({
+    ...state,
+    installations: preflight.operation === 'enable'
+      ? state.installations.map((item) => item.id === installation.id ? installation : item)
+      : [...state.installations, installation],
+  }), { cwd: opts.cwd, agentDir: opts.agentDir, lockTimeoutMs: opts.fenceTimeoutMs, expectedStateRevision: preflight.stateRevision });
+  if (write.isStale) return rejectedAsStale(preflight, 'State Revision changed after Installation confirmation; re-run preflight and confirmation', opts);
+  preflight.fence.release();
+  if (!write.success) {
+    const summary = write.isIndeterminate ? 'Persistence Indeterminate' : 'Persistence Failed';
+    const receipt = createReceipt({ operation: receiptOperation(preflight.operation), scope: preflight.scope, trigger: triggerFor(preflight.operation, preflight.registration.id, preflight.plugin.marketplaceEntryId), expectedStateRevision: preflight.stateRevision, validationSnapshot: preflight.snapshot.fingerprint, summary, findings: [] });
+    await appendReceipt(preflight.scope, receipt, opts);
+    return {
+      status: 'persistence-failed',
+      isIndeterminate: write.isIndeterminate ?? false,
+      receipt,
+    };
+  }
+  const receipt = createReceipt({ operation: receiptOperation(preflight.operation), scope: preflight.scope, trigger: triggerFor(preflight.operation, preflight.registration.id, preflight.plugin.marketplaceEntryId), expectedStateRevision: preflight.stateRevision, targetStateRevision: write.newRevision, observedStateRevision: write.newRevision, validationSnapshot: preflight.snapshot.fingerprint, summary: preflight.findings.length > 0 ? 'Completed with diagnostics' : 'Completed', findings: preflight.findings, stateChanged: true });
+  await appendReceipt(preflight.scope, receipt, opts);
+  return {
+    status: 'completed',
+    installation,
+    newRevision: write.newRevision!,
+    receipt,
+  };
+}
+
+export async function preflightPluginEnable(scope: Scope, installationId: string, opts: InstallationFlowOptions = {}): Promise<InstallationPreflightResult> {
+  const read = await readBridgeState(scope, { cwd: opts.cwd, agentDir: opts.agentDir });
+  if (read.status !== 'ok' && read.status !== 'missing') {
+    const receipt = createReceipt({ operation: receiptOperation('enable'), scope, trigger: `enable ${installationId}`, expectedStateRevision: '?', summary: 'Persistence Indeterminate', findings: [operationFinding(scope, CODE.PERSISTENCE_INDETERMINATE, 'PERSIST-01', read.error ?? 'Bridge State is not readable', 'attempt', 'persistence')] });
+    await appendReceipt(scope, receipt, opts);
+    return { ok: false, outcome: { status: 'persistence-failed', receipt, isIndeterminate: true } };
+  }
+  const existing = read.state?.installations.find((item) => item.id === installationId);
+  if (!existing?.registrationId || !existing.marketplaceEntryId) {
+    return blocked('enable', scope, 'unknown', installationId, read.state?.stateRevision ?? '?', [
+      operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, `Disabled Installation '${installationId}' has no revalidatable provenance`),
+    ], null, opts);
+  }
+  const prefix = `${existing.registrationId}/`;
+  const entryPointer = existing.marketplaceEntryId.startsWith(prefix)
+    ? existing.marketplaceEntryId.slice(existing.marketplaceEntryId.indexOf('/plugins/'))
+    : existing.marketplaceEntryId;
+  return makePreflight(scope, existing.registrationId, entryPointer, opts, 'enable', existing);
+}
+
+export async function confirmPluginEnable(preflight: PluginInstallationPreflight, activationConfirmed: boolean, opts: InstallationFlowOptions = {}): Promise<InstallationOutcome> {
+  return confirmPluginInstallation(preflight, 'enabled', activationConfirmed, opts);
+}
+
+export async function disablePluginInstallation(scope: Scope, installationId: string, opts: InstallationFlowOptions = {}): Promise<InstallationOutcome> {
+  const trust = scopeDenied(scope, opts);
+  if (trust) {
+    const result = await blocked('disable', scope, 'unknown', installationId, '?', [trust], null, opts);
+    if (!result.ok) return result.outcome;
+    throw new Error('unreachable blocked Installation preflight result');
+  }
+  const fence = await acquireAttemptFence(scope, { cwd: opts.cwd, agentDir: opts.agentDir, fenceTimeoutMs: opts.fenceTimeoutMs, projectTrusted: opts.projectTrusted });
+  if (!fence.ok) {
+    const result = await blocked('disable', scope, 'unknown', installationId, '?', [fence.finding!], null, opts);
+    if (!result.ok) return result.outcome;
+    throw new Error('unreachable blocked Installation preflight result');
+  }
+  const read = await readBridgeState(scope, { cwd: opts.cwd, agentDir: opts.agentDir });
+  if (read.status !== 'ok' && read.status !== 'missing') {
+    fence.handle!.release();
+    const receipt = createReceipt({ operation: receiptOperation('disable'), scope, trigger: triggerFor('disable', 'unknown', installationId), expectedStateRevision: '?', summary: 'Persistence Indeterminate', findings: [operationFinding(scope, CODE.PERSISTENCE_INDETERMINATE, 'PERSIST-01', read.error ?? 'Bridge State is not readable', 'attempt', 'persistence')] });
+    await appendReceipt(scope, receipt, opts);
+    return { status: 'persistence-failed', isIndeterminate: true, receipt };
+  }
+  const state = read.state!;
+  const installation = state.installations.find((item) => item.id === installationId);
+  if (!installation) {
+    const result = await blocked('disable', scope, 'unknown', installationId, state.stateRevision, [operationFinding(scope, CODE.INSTALLATION_NOT_FOUND, RULE.INSTALLATION_NOT_FOUND, `Installation '${installationId}' was not found`)], fence.handle!, opts);
+    if (!result.ok) return result.outcome;
+    throw new Error('unreachable blocked Installation preflight result');
+  }
+  await opts.beforeDisableCommit?.();
+  const write = await commitBridgeState(scope, (state) => ({
+    ...state,
+    installations: state.installations.map((item) => item.id === installationId ? { ...item, installationState: 'disabled' } : item),
+  }), { cwd: opts.cwd, agentDir: opts.agentDir, lockTimeoutMs: opts.fenceTimeoutMs, expectedStateRevision: state.stateRevision });
+  fence.handle!.release();
+  if (write.isStale) {
+    const receipt = createReceipt({
+      operation: receiptOperation('disable'),
+      scope,
+      trigger: triggerFor('disable', 'unknown', installationId),
+      expectedStateRevision: state.stateRevision,
+      observedStateRevision: write.observedRevision,
+      summary: 'Rejected as Stale',
+      findings: [operationFinding(scope, CODE.REJECTED_AS_STALE, RULE.REJECTED_AS_STALE, 'State Revision changed after disablement admission; re-run the lifecycle operation', 'installation', 'persistence')],
+    });
+    await appendReceipt(scope, receipt, opts);
+    return {
+      status: 'rejected-as-stale',
+      receipt,
+    };
+  }
+  if (!write.success) {
+    const receipt = createReceipt({ operation: receiptOperation('disable'), scope, trigger: triggerFor('disable', 'unknown', installationId), expectedStateRevision: state.stateRevision, summary: write.isIndeterminate ? 'Persistence Indeterminate' : 'Persistence Failed' });
+    await appendReceipt(scope, receipt, opts);
+    return { status: 'persistence-failed', isIndeterminate: write.isIndeterminate ?? false, receipt };
+  }
+  const disabled = { ...installation, installationState: 'disabled' as const };
+  const receipt = createReceipt({ operation: receiptOperation('disable'), scope, trigger: triggerFor('disable', 'unknown', installationId), expectedStateRevision: state.stateRevision, targetStateRevision: write.newRevision, observedStateRevision: write.newRevision, summary: 'Completed', stateChanged: true });
+  await appendReceipt(scope, receipt, opts);
+  return { status: 'completed', installation: disabled, newRevision: write.newRevision!, receipt };
+}

package/src/installation/index.ts

@@ -0,0 +1 @@
+export * from './flow.js';

package/src/installation/inspection.ts

@@ -0,0 +1,129 @@
+/** Read-only Marketplace Entry inspection.
+ *
+ * This is deliberately separate from lifecycle preflight: it never acquires an Attempt Fence,
+ * creates a receipt, or reads Bridge State.  One bounded snapshot and one catalog parse produce
+ * all browse results for a Marketplace.
+ */
+
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { classifyPlugin, type CompatiblePlugin } from '../compatibility/profile.js';
+import type { Registration, Scope } from '../bridge-state/types.js';
+import type { MarketplaceEntry } from '../registration/catalog.js';
+import { parseCatalog } from '../registration/catalog.js';
+import { resolveContained } from '../registration/contained.js';
+import { CODE, RULE, blocking, hasBlocking, sortFindings, type ValidationFinding } from '../registration/findings.js';
+import { localSourceKey } from '../registration/source-key.js';
+import { bindCapturedMaterial, buildLocalSnapshot, type ValidationSnapshot } from '../registration/snapshot.js';
+import { BUDGET } from '../registration/budget.js';
+
+export interface InspectedMarketplaceEntry {
+  entry: MarketplaceEntry;
+  plugin?: CompatiblePlugin;
+  findings: ValidationFinding[];
+  unavailableReason?: string;
+}
+
+export interface MarketplaceInspection {
+  entries: InspectedMarketplaceEntry[];
+  findings: ValidationFinding[];
+  marketplaceId?: string;
+  snapshot?: ValidationSnapshot;
+  /** Fingerprint of the inspected source tree alone, before activation-material binding.
+   *  Registrations persist exactly this value at confirmation (their preflight snapshot is
+   *  the unbound tree fingerprint from buildLocalSnapshot); Source Drift compares against it. */
+  treeFingerprint?: string;
+}
+
+export interface InspectionOptions {
+  /** Inspect this explicit root with this caller-bound base Validation Snapshot (e.g. a Git acquisition tree) instead of deriving a local one from the Registration. */
+  root?: string;
+  baseSnapshot?: ValidationSnapshot;
+  /** Suppress the recorded-snapshot drift Blocking Finding — Refresh compares fingerprints explicitly instead. */
+  ignoreRecordedDrift?: boolean;
+}
+
+function inspectionFinding(scope: Scope, code: string, rule: string, target: ValidationFinding['target'], outcome: string): ValidationFinding {
+  return blocking({ code, rule, target, pointer: '', outcome, scope, phase: 'validation' });
+}
+
+/** Inspect every Marketplace Entry once. All filesystem work occurs after a bounded snapshot. */
+export function inspectMarketplaceEntries(registration: Registration, scope: Scope, opts: InspectionOptions = {}): MarketplaceInspection {
+  const override = Boolean(opts.root && opts.baseSnapshot);
+  let root: string;
+  let snapshotResult: { ok: boolean; snapshot?: ValidationSnapshot; findings: ValidationFinding[] };
+  if (override) {
+    root = opts.root!;
+    snapshotResult = { ok: true, snapshot: opts.baseSnapshot, findings: [] };
+  } else {
+    if (registration.sourceKind !== 'local' || !registration.source) {
+      return { entries: [], findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', 'Git Source Cache lifecycle is not available yet')] };
+    }
+    const key = localSourceKey(registration.source);
+    if (!key.ok) return { entries: [], findings: [inspectionFinding(scope, CODE.SOURCE_REACQUISITION_REQUIRED, RULE.SOURCE_REACQUISITION_REQUIRED, 'registration', key.error ?? 'Marketplace Root cannot be revalidated')] };
+    root = key.sourceKey!.canonicalPath!;
+    const catalogPath = join(root, '.agents', 'plugins', 'marketplace.json');
+    try {
+      if (lstatSync(catalogPath).size > BUDGET.maxCatalogBytes) {
+        return { entries: [], findings: [inspectionFinding(scope, CODE.BUDGET_EXCEEDED, RULE.BUDGET_EXCEEDED, 'catalog', `Validation Budget exceeded: catalog exceeds ${BUDGET.maxCatalogBytes} bytes`)] };
+      }
+    } catch {
+      // The catalog read below provides the stable catalog-missing finding.
+    }
+    snapshotResult = buildLocalSnapshot(root, key.sourceKey!, scope);
+    if (!snapshotResult.ok) return { entries: [], findings: snapshotResult.findings };
+  }
+
+  const catalogPath = join(root, '.agents', 'plugins', 'marketplace.json');
+
+  let catalogRaw: string;
+  let catalogValue: unknown;
+  try {
+    const bytes = readFileSync(catalogPath);
+    if (bytes.length > BUDGET.maxCatalogBytes) return { entries: [], snapshot: snapshotResult.snapshot, findings: [inspectionFinding(scope, CODE.BUDGET_EXCEEDED, RULE.BUDGET_EXCEEDED, 'catalog', `Validation Budget exceeded: catalog exceeds ${BUDGET.maxCatalogBytes} bytes`)] };
+    catalogRaw = bytes.toString('utf8');
+    catalogValue = JSON.parse(catalogRaw);
+  } catch {
+    return { entries: [], snapshot: snapshotResult.snapshot, findings: [inspectionFinding(scope, CODE.CATALOG_MISSING, RULE.CATALOG_MISSING, 'catalog', 'Marketplace Catalog cannot be read')] };
+  }
+  const parsed = parseCatalog(catalogValue, { scope });
+  if (!parsed.catalog) return { entries: [], snapshot: snapshotResult.snapshot, findings: parsed.findings };
+  const marketplaceId = `${registration.id}/${parsed.catalog.name}`;
+  const drift = !opts.ignoreRecordedDrift && registration.validationSnapshot && registration.validationSnapshot !== snapshotResult.snapshot!.fingerprint
+    ? [inspectionFinding(scope, CODE.REJECTED_AS_STALE, RULE.REJECTED_AS_STALE_SNAPSHOT, 'registration', 'Registered Validation Snapshot no longer matches the source tree; Marketplace Refresh is required')]
+    : [];
+  const material = createHash('sha256');
+  material.update('catalog\u001f').update(catalogRaw).update('\u001e');
+  const classifications = new Map<string, ReturnType<typeof classifyPlugin>>();
+  const draft = parsed.catalog.entries.map((entry) => {
+    if (!entry.available || entry.type !== 'local' || !entry.path) return { entry, findings: [], unavailableReason: entry.unavailableReason ?? 'unsupported source kind' };
+    const contained = resolveContained(root, entry.path, 'directory');
+    if (contained.outcome.kind !== 'ok') return { entry, findings: [], unavailableReason: 'cannot resolve Plugin' };
+    let baseClassification = classifications.get(contained.outcome.canonicalPath);
+    if (!baseClassification) {
+      baseClassification = classifyPlugin(contained.outcome.canonicalPath, { scope, marketplaceId, marketplaceEntryId: `${marketplaceId}${entry.entryId}` });
+      classifications.set(contained.outcome.canonicalPath, baseClassification);
+    }
+    const classification = baseClassification.plugin
+      ? { ...baseClassification, plugin: { ...baseClassification.plugin, marketplaceEntryId: `${marketplaceId}${entry.entryId}` } }
+      : baseClassification;
+    material.update(`entry:${entry.entryId}\u001f`).update(classification.captureFingerprint).update('\u001e');
+    return { entry, plugin: classification.plugin, identity: classification.identity, findings: classification.findings };
+  });
+  const snapshot = bindCapturedMaterial(snapshotResult.snapshot!, material.digest('hex'));
+  const identities = new Map<string, number>();
+  for (const item of draft) if (item.identity) identities.set(item.identity, (identities.get(item.identity) ?? 0) + 1);
+  const entries = draft.map((item): InspectedMarketplaceEntry => {
+    const collision = item.identity && (identities.get(item.identity) ?? 0) > 1
+      ? [inspectionFinding(scope, CODE.PLUGIN_ID_COLLISION, RULE.PLUGIN_ID_COLLISION, 'plugin', `Plugin ID '${item.identity}' collides with another Marketplace Entry; neither entry is activatable`)]
+      : [];
+    const catalogFindings = parsed.findings.filter((finding) => finding.target !== 'entry' || finding.pointer === item.entry.entryId);
+    const findings = sortFindings([...catalogFindings, ...item.findings, ...collision, ...drift, ...snapshotResult.findings]);
+    const unavailableReason = item.unavailableReason
+      ?? (hasBlocking(findings) || !item.plugin ? findings.find((finding) => finding.classification === 'blocking')?.outcome ?? 'incompatible' : undefined);
+    return { entry: item.entry, plugin: item.plugin, findings, unavailableReason };
+  });
+  return { entries, findings: sortFindings([...parsed.findings, ...drift, ...snapshotResult.findings]), marketplaceId, snapshot, treeFingerprint: snapshotResult.snapshot!.fingerprint };
+}