pi-codex-marketplace 0.1.0

package/src/lifecycle/update.ts

@@ -0,0 +1,303 @@
+/**
+ * Apply Update — the Lifecycle Operation that replaces one Registration's recorded Validation
+ * Snapshot according to one complete Update Plan and atomically applies every disclosed
+ * same-scope consequence.
+ * See CONTEXT.md: Apply Update, Update Plan, Lifecycle Operation, Rejected as Stale, Attempt Fence.
+ *
+ * Guarantees:
+ * - One single atomic commit: the new snapshot becomes authoritative together with every
+ *   updated / disabled / removed Installation — never a partial application across revisions.
+ * - The exact State Revision bound by the plan is re-verified under CAS; any movement rejects
+ *   the attempt as stale without merging.
+ * - For local sources the candidate fingerprint is re-verified against the live tree before the
+ *   durable mutation (a mismatch is a Blocking Finding — Stale Snapshot never substitutes).
+ * - It never refreshes the source and never silently changes another scope.
+ */
+
+import {
+  acquireAttemptFence,
+} from '../registration/fence.js';
+import { CODE, RULE, blocking, sortFindings, type ValidationFinding } from '../registration/findings.js';
+import { createReceipt, type AttemptReceipt } from '../registration/receipt.js';
+import { buildGitSnapshot, buildLocalSnapshot } from '../registration/snapshot.js';
+import { SourceCache } from '../cache/source-cache.js';
+import { commitBridgeState, readBridgeState } from '../bridge-state/store.js';
+import type { BridgeState } from '../bridge-state/types.js';
+import type { LifecycleFlowOptions, UpdateCandidate } from './refresh.js';
+import type { UpdatePlan } from './update-plan.js';
+
+export type ApplyUpdateOptions = LifecycleFlowOptions;
+
+export type ApplyUpdateOutcome =
+  | { status: 'completed'; receipt: AttemptReceipt; newRevision: string }
+  | { status: 'blocked'; findings: ValidationFinding[]; receipt: AttemptReceipt }
+  | { status: 'rejected-as-stale'; receipt: AttemptReceipt }
+  | { status: 'persistence-failed'; receipt: AttemptReceipt; isIndeterminate: boolean };
+
+function operationFor(plan: UpdatePlan): string {
+  return plan.kind === 'rebind' ? 'Registration Rebind' : 'Apply Update';
+}
+
+function finding(scope: UpdatePlan['scope'], code: string, rule: string, target: ValidationFinding['target'], outcome: string): ValidationFinding {
+  return blocking({ code, rule, target, pointer: '', outcome, scope, phase: 'persistence' });
+}
+
+function blocked(plan: UpdatePlan, findings: ValidationFinding[], observedRevision?: string): ApplyUpdateOutcome {
+  return {
+    status: 'blocked',
+    findings: sortFindings(findings),
+    receipt: createReceipt({
+      operation: operationFor(plan),
+      scope: plan.scope,
+      trigger: `${plan.kind} ${plan.registrationId}`,
+      expectedStateRevision: plan.stateRevision,
+      observedStateRevision: observedRevision,
+      validationSnapshot: plan.candidate.snapshot.fingerprint,
+      summary: 'Blocked',
+      findings,
+    }),
+  };
+}
+
+function stale(plan: UpdatePlan, outcomeText: string, observedRevision?: string): ApplyUpdateOutcome {
+  return {
+    status: 'rejected-as-stale',
+    receipt: createReceipt({
+      operation: operationFor(plan),
+      scope: plan.scope,
+      trigger: `${plan.kind} ${plan.registrationId}`,
+      expectedStateRevision: plan.stateRevision,
+      observedStateRevision: observedRevision,
+      validationSnapshot: plan.candidate.snapshot.fingerprint,
+      summary: 'Rejected as Stale',
+      findings: [finding(plan.scope, CODE.REJECTED_AS_STALE, RULE.REJECTED_AS_STALE, 'attempt', outcomeText)],
+      stateChanged: false,
+    }),
+  };
+}
+
+/** Draft the whole disclosed consequence set in one state transform — committed once or not at all. */
+function draftNextState(state: BridgeState, plan: UpdatePlan): BridgeState {
+  const candidate: UpdateCandidate = plan.candidate;
+  const registrations = state.registrations.map((registration) => {
+    if (registration.id !== plan.registrationId) return registration;
+    const next = {
+      ...registration,
+      marketplaceName: candidate.marketplaceName || registration.marketplaceName,
+      validationSnapshot: candidate.snapshot.fingerprint,
+      snapshotBinds: {
+        profile: candidate.snapshot.profile,
+        ruleset: candidate.snapshot.ruleset,
+        budget: candidate.snapshot.budget,
+      },
+    };
+    if (candidate.resolvedRevision) next.resolvedRevision = candidate.resolvedRevision;
+    if (plan.rebindSource) {
+      next.sourceKind = plan.rebindSource.sourceKind;
+      next.source = plan.rebindSource.source;
+      next.sourceKey = plan.rebindSource.sourceKey;
+      next.canonicalLocator = plan.rebindSource.canonicalLocator;
+      next.gitSelector = plan.rebindSource.gitSelector;
+      next.resolvedRevision = plan.rebindSource.resolvedRevision;
+    }
+    return next;
+  });
+
+  let installations = [...state.installations];
+  for (const entry of plan.entries) {
+    if (entry.choice === 'remove') {
+      installations = installations.filter((installation) => installation.id !== entry.installationId);
+      continue;
+    }
+    installations = installations.map((installation) => {
+      if (installation.id !== entry.installationId) return installation;
+      if (entry.choice === 'disable') return { ...installation, installationState: 'disabled' as const };
+      return {
+        ...installation,
+        installationState: entry.installationState,
+        validationSnapshot: entry.newSnapshot!.fingerprint,
+        snapshotBinds: {
+          profile: entry.newSnapshot!.profile,
+          ruleset: entry.newSnapshot!.ruleset,
+          budget: entry.newSnapshot!.budget,
+        },
+        marketplaceEntryId: entry.newMarketplaceEntryId ?? installation.marketplaceEntryId,
+        manifestName: entry.manifestName ?? installation.manifestName,
+      };
+    });
+  }
+
+  return { ...state, registrations, installations };
+}
+
+/**
+ * Commit one complete Update Plan atomically. The plan must come from `buildUpdatePlan`; this
+ * function performs no disclosure of its own — everything it will do was disclosed by the plan.
+ */
+export async function applyUpdate(plan: UpdatePlan, opts: ApplyUpdateOptions = {}): Promise<ApplyUpdateOutcome> {
+  const read = await readBridgeState(plan.scope, { cwd: opts.cwd, agentDir: opts.agentDir });
+  if (read.status !== 'ok' && read.status !== 'missing') {
+    const indeterminate = true;
+    return {
+      status: 'persistence-failed',
+      isIndeterminate: indeterminate,
+      receipt: createReceipt({
+        operation: operationFor(plan),
+        scope: plan.scope,
+        trigger: `${plan.kind} ${plan.registrationId}`,
+        expectedStateRevision: plan.stateRevision,
+        validationSnapshot: plan.candidate.snapshot.fingerprint,
+        summary: 'Persistence Indeterminate',
+        findings: [finding(plan.scope, CODE.PERSISTENCE_INDETERMINATE, 'PERSIST-01', 'attempt', read.error ?? 'Bridge State is not readable; neither previous nor target verifiable')],
+        stateChanged: false,
+      }),
+    };
+  }
+  const state = read.state!;
+
+  // Project Trust gates every Project Scope mutation.
+  if (plan.scope === 'project' && opts.projectTrusted !== true) {
+    return blocked(plan, [
+      blocking({
+        code: CODE.PROJECT_TRUST_DENIED,
+        rule: RULE.PROJECT_TRUST_DENIED,
+        target: 'attempt',
+        pointer: '',
+        outcome: 'Project Trust is not granted by the Pi host; no Project Scope Lifecycle Operation may mutate Bridge State',
+        scope: plan.scope,
+        phase: 'admission',
+      }),
+    ], state.stateRevision);
+  }
+
+  if (!state.registrations.some((registration) => registration.id === plan.registrationId)) {
+    return blocked(plan, [
+      blocking({
+        code: CODE.REGISTRATION_NOT_FOUND,
+        rule: RULE.REGISTRATION_NOT_FOUND,
+        target: 'registration',
+        pointer: '',
+        outcome: `Registration '${plan.registrationId}' is no longer in ${plan.scope} Bridge State`,
+        scope: plan.scope,
+        phase: 'admission',
+      }),
+    ], state.stateRevision);
+  }
+
+  if (state.stateRevision !== plan.stateRevision) {
+    return stale(
+      plan,
+      `State Revision changed since the Update Plan was built (${plan.stateRevision} → ${state.stateRevision}); rebuild the plan after a fresh Marketplace Refresh`,
+      state.stateRevision,
+    );
+  }
+
+  // Fingerprint must still match before durable state mutation. Local sources are re-walked;
+  // Git candidates are verified against the fingerprint-addressed Source Cache entry (#22).
+  if (plan.candidate.snapshot.sourceKey.kind === 'local') {
+    const revalidated = buildLocalSnapshot(plan.candidate.snapshot.sourceKey.canonicalPath!, plan.candidate.snapshot.sourceKey, plan.scope);
+    if (!revalidated.ok || !revalidated.snapshot || revalidated.snapshot.fingerprint !== plan.candidate.snapshot.fingerprint) {
+      return stale(
+        plan,
+        'Validation Snapshot fingerprint changed since the Update Candidate was produced (source drifted); run a fresh Marketplace Refresh and rebuild the plan',
+      );
+    }
+  } else {
+    // Git candidates verify against the fingerprint-addressed Source Cache (default-constructed
+    // so pin hygiene and verification never depend on caller injection). Fail-closed: an absent
+    // or mismatching cached tree rejects the attempt as stale — never an unverified apply.
+    const cache = opts.cache ?? new SourceCache({ agentDir: opts.agentDir });
+    const hit = await cache.hitExact(plan.candidate.snapshot.fingerprint);
+    if (!hit) {
+      return stale(
+        plan,
+        'No cached tree verifies the Update Candidate fingerprint (evicted or never retained); run a fresh Marketplace Refresh and rebuild the plan',
+      );
+    }
+    const revalidated = buildGitSnapshot(hit.path, plan.candidate.snapshot.sourceKey, plan.scope, {
+      canonicalLocator: plan.candidate.canonicalLocator ?? plan.candidate.snapshot.canonicalLocator ?? '',
+      resolvedRevision: plan.candidate.resolvedRevision ?? plan.candidate.snapshot.resolvedRevision ?? '',
+      selectorCanonical: plan.candidate.selectorCanonical ?? plan.candidate.snapshot.selectorCanonical ?? '',
+    });
+    if (!revalidated.ok || !revalidated.snapshot || revalidated.snapshot.fingerprint !== plan.candidate.snapshot.fingerprint) {
+      return stale(
+        plan,
+        'Cached Git tree no longer hashes to the Update Candidate fingerprint (source drift); run a fresh Marketplace Refresh and rebuild the plan',
+      );
+    }
+  }
+
+  const fence = await acquireAttemptFence(plan.scope, {
+    cwd: opts.cwd,
+    agentDir: opts.agentDir,
+    fenceTimeoutMs: opts.fenceTimeoutMs,
+  });
+  if (!fence.ok) return blocked(plan, [fence.finding!], plan.stateRevision);
+
+  try {
+    const write = await commitBridgeState(
+      plan.scope,
+      (current) => draftNextState(current, plan),
+      { cwd: opts.cwd, agentDir: opts.agentDir, lockTimeoutMs: opts.fenceTimeoutMs, expectedStateRevision: plan.stateRevision },
+    );
+
+    if (write.isStale) {
+      return stale(
+        plan,
+        `State Revision changed under the Attempt Fence (${plan.stateRevision} → ${write.observedRevision ?? '?'}); rebuild the plan after a fresh Marketplace Refresh`,
+        write.observedRevision,
+      );
+    }
+
+    if (!write.success) {
+      const summary = write.isIndeterminate ? 'Persistence Indeterminate' : 'Persistence Failed';
+      return {
+        status: 'persistence-failed',
+        isIndeterminate: write.isIndeterminate ?? false,
+        receipt: createReceipt({
+          operation: operationFor(plan),
+          scope: plan.scope,
+          trigger: `${plan.kind} ${plan.registrationId}`,
+          expectedStateRevision: plan.stateRevision,
+          targetStateRevision: '?',
+          validationSnapshot: plan.candidate.snapshot.fingerprint,
+          summary,
+          findings: [
+            finding(
+              plan.scope,
+              write.isIndeterminate ? CODE.PERSISTENCE_INDETERMINATE : CODE.PERSISTENCE_FAILED,
+              write.isIndeterminate ? 'PERSIST-01' : 'PERSIST-02',
+              'attempt',
+              write.error ?? summary,
+            ),
+          ],
+          stateChanged: false,
+        }),
+      };
+    }
+
+    const newRevision = write.newRevision!;
+    // The Update Candidate has been applied: its pending-cache pin is no longer needed
+    // (the new Registration/Installation snapshots now pin the fingerprint via Bridge State).
+    (opts.cache ?? new SourceCache({ agentDir: opts.agentDir })).clearPendingUpdate(plan.scope, plan.registrationId);
+    const diagnostics = plan.entries.some((entry) => entry.choice === 'remove' || entry.currentState === 'disabled');
+    return {
+      status: 'completed',
+      newRevision,
+      receipt: createReceipt({
+        operation: operationFor(plan),
+        scope: plan.scope,
+        trigger: `${plan.kind} ${plan.registrationId}`,
+        expectedStateRevision: plan.stateRevision,
+        targetStateRevision: newRevision,
+        observedStateRevision: newRevision,
+        validationSnapshot: plan.candidate.snapshot.fingerprint,
+        summary: diagnostics ? 'Completed with diagnostics' : 'Completed',
+        findings: [],
+        stateChanged: true,
+      }),
+    };
+  } finally {
+    fence.handle!.release();
+  }
+}

package/src/projection/collision.ts

@@ -0,0 +1,120 @@
+/**
+ * Runtime Skill Collision — resolution over Pi's flat skill namespace by exact
+ * Skill Descriptor name. See CONTEXT.md: Runtime Skill Collision, Projected Skill.
+ *
+ * Pure and skill-granular only: the result never changes Plugin classification or
+ * Projected Plugin determination. Candidates resolve per exact name in
+ * `Pi → Project Scope → Global Scope` order; all same-scope Bridge colliders are
+ * unavailable; only a surviving higher-layer skill reserves the name, so a lower-layer
+ * candidate survives whenever no higher-layer skill does.
+ */
+
+export type CollisionLayer = 'pi' | 'project' | 'global';
+
+export interface SkillCandidate {
+  /** Namespace layer the candidate comes from. */
+  layer: CollisionLayer;
+  /** Exact Skill Descriptor name (the contested flat-namespace key). */
+  name: string;
+  /** Canonical Skill ID = Plugin ID + descriptor name. */
+  skillId: string;
+  pluginId: string;
+}
+
+/** Skill-granular denial record for one contested exact name. */
+export interface SkillCollisionFindingInfo {
+  name: string;
+  /** Skill IDs denied because they collide within their own scope layer. */
+  unavailableSkillIds: string[];
+  /** The surviving candidate that reserves the name, when one exists. */
+  reservedBy?: { layer: CollisionLayer; skillId: string };
+}
+
+export interface CollisionResolution {
+  survivors: SkillCandidate[];
+  findings: SkillCollisionFindingInfo[];
+}
+
+function dedupeBySkillId(candidates: SkillCandidate[]): SkillCandidate[] {
+  const seen = new Set<string>();
+  return candidates.filter((item) => {
+    if (seen.has(item.skillId)) return false;
+    seen.add(item.skillId);
+    return true;
+  });
+}
+
+/**
+ * Resolve every exact-name group independently under the layered rules.
+ * Pre-existing Pi skills are host-owned: a Pi-layer claim reserves the name for all
+ * Bridge candidates, and Pi-vs-Pi duplicates are outside Bridge adjudication.
+ */
+export function resolveRuntimeSkillCollisions(candidates: SkillCandidate[]): CollisionResolution {
+  const byName = new Map<string, SkillCandidate[]>();
+  for (const item of candidates) {
+    const group = byName.get(item.name);
+    if (group) group.push(item);
+    else byName.set(item.name, [item]);
+  }
+
+  const survivors: SkillCandidate[] = [];
+  const findings: SkillCollisionFindingInfo[] = [];
+
+  for (const [name, group] of [...byName.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const bridge = group.filter((item) => item.layer !== 'pi');
+    const piClaims = group.some((item) => item.layer === 'pi');
+
+    if (piClaims) {
+      // Only a surviving higher-layer skill reserves the name — the Pi layer does here.
+      // Every Bridge candidate below is denied at skill granularity.
+      const piSurvivors = group.filter((item) => item.layer === 'pi');
+      if (bridge.length > 0) {
+        findings.push({
+          name,
+          unavailableSkillIds: bridge.map((item) => item.skillId).sort((a, b) => a.localeCompare(b)),
+          reservedBy: piSurvivors[0] ? { layer: 'pi', skillId: piSurvivors[0].skillId } : undefined,
+        });
+      }
+      survivors.push(...piSurvivors);
+      continue;
+    }
+
+    let denied: string[] = [];
+    let projectNameUnreserved = false;
+
+    const projectCandidates = dedupeBySkillId(group.filter((item) => item.layer === 'project'));
+    const globalCandidates = dedupeBySkillId(group.filter((item) => item.layer === 'global'));
+
+    if (projectCandidates.length > 1) {
+      // All same-scope Bridge colliders are unavailable; nobody reserves the name,
+      // so lower-layer candidates survive.
+      denied.push(...projectCandidates.map((item) => item.skillId));
+      projectNameUnreserved = true;
+    } else if (projectCandidates.length === 1) {
+      survivors.push(projectCandidates[0]!);
+      if (globalCandidates.length > 0) {
+        findings.push({
+          name,
+          unavailableSkillIds: globalCandidates.map((item) => item.skillId).sort((a, b) => a.localeCompare(b)),
+          reservedBy: { layer: 'project', skillId: projectCandidates[0]!.skillId },
+        });
+      }
+      continue;
+    }
+
+    if (projectNameUnreserved || projectCandidates.length === 0) {
+      const survivingGlobal = dedupeBySkillId(globalCandidates);
+      if (survivingGlobal.length > 1) {
+        denied.push(...survivingGlobal.map((item) => item.skillId));
+      } else {
+        survivors.push(...survivingGlobal);
+      }
+    }
+
+    if (denied.length > 0) {
+      findings.push({ name, unavailableSkillIds: [...new Set(denied)].sort((a, b) => a.localeCompare(b)) });
+    }
+  }
+
+  return { survivors, findings };
+}

package/src/projection/effective-state.ts

@@ -0,0 +1,182 @@
+/**
+ * Effective State — computed project view of inherited Global Scope records,
+ * Project Scope additions, and ID-keyed Scope Overrides.
+ * See CONTEXT.md: Effective State, Scope Override, Project Trust, Installation State, Installed Plugin.
+ *
+ * This is a pure read-time computation over the two authoritative Bridge State documents.
+ * Nothing here is persisted: no merged state document exists. Only enabled Installations
+ * participate, an enabled project Installation of an inherited global Plugin ID takes
+ * precedence over the retained global Installation, and no selected record's independently
+ * persisted provenance is merged or mutated — each record carries exactly what its own
+ * scope's document holds.
+ */
+
+import type { BridgeState, Installation, Registration } from '../bridge-state/types.js';
+
+export type EffectiveSourceScope = 'global' | 'project';
+
+export interface EffectiveRegistration extends Registration {
+  sourceScope: EffectiveSourceScope;
+}
+
+export interface EffectiveInstallation extends Installation {
+  sourceScope: EffectiveSourceScope;
+}
+
+/** Why one inherited Global Scope record does not participate in this Effective State. */
+export interface SuppressedGlobalRecord {
+  kind: 'registration' | 'installation';
+  /** Canonical Registration ID or Installation ID of the suppressed record. */
+  targetId: string;
+  pluginId?: string;
+  reason: 'scope-override-registration' | 'scope-override-installation' | 'project-precedence';
+  /** For precedence suppression: the project Installation that supersedes the global one. */
+  supersededBy?: string;
+}
+
+/**
+ * Project Scope records stored in the project document but excluded from Effective State:
+ * Project Trust not granted, or an invalid duplicate of an inherited Registration ID.
+ */
+export interface ExcludedProjectRecord {
+  kind: 'registration' | 'installation' | 'scope-override';
+  id: string;
+  reason: 'project-trust-not-granted' | 'invalid-duplicate-registration-id';
+}
+
+export interface EffectiveState {
+  registrations: EffectiveRegistration[];
+  installations: EffectiveInstallation[];
+  suppressed: SuppressedGlobalRecord[];
+  excluded: ExcludedProjectRecord[];
+}
+
+export interface EffectiveStateOptions {
+  /**
+   * Pi host-owned Project Trust. Defaults to false: project records remain stored but are
+   * excluded, and overrides do not participate, until the host grants trust.
+   */
+  projectTrusted?: boolean;
+}
+
+/**
+ * Compute the Effective State from both scope documents. Pure — never mutates inputs and
+ * never persists anything; callers recompute after every read or commit.
+ */
+export function computeEffectiveState(
+  globalState: BridgeState,
+  projectState: BridgeState,
+  opts: EffectiveStateOptions = {},
+): EffectiveState {
+  const projectTrusted = opts.projectTrusted === true;
+  const suppressed: SuppressedGlobalRecord[] = [];
+  const excluded: ExcludedProjectRecord[] = [];
+
+  // Without Project Trust every project-side record stays durable but non-participating.
+  if (!projectTrusted) {
+    for (const registration of projectState.registrations) {
+      excluded.push({ kind: 'registration', id: registration.id, reason: 'project-trust-not-granted' });
+    }
+    for (const installation of projectState.installations) {
+      excluded.push({ kind: 'installation', id: installation.id, reason: 'project-trust-not-granted' });
+    }
+    for (const override of projectState.scopeOverrides) {
+      const id = `${override.kind}/${override.targetId}`;
+      excluded.push({ kind: 'scope-override', id, reason: 'project-trust-not-granted' });
+    }
+    return {
+      registrations: globalState.registrations.map((registration) => ({ ...registration, sourceScope: 'global' })),
+      installations: globalState.installations
+        .filter((installation) => installation.installationState === 'enabled')
+        .map((installation) => ({ ...installation, sourceScope: 'global' })),
+      suppressed,
+      excluded,
+    };
+  }
+
+  // Overrides are keyed by canonical Registration ID / Installation ID and suppress only
+  // inherited Global Scope records.
+  const overriddenRegistrationIds = new Set(
+    projectState.scopeOverrides.filter((o) => o.kind === 'registration').map((o) => o.targetId),
+  );
+  const overriddenInstallationIds = new Set(
+    projectState.scopeOverrides.filter((o) => o.kind === 'installation').map((o) => o.targetId),
+  );
+
+  const survivingGlobalRegistrations = globalState.registrations.filter((registration) => {
+    if (!overriddenRegistrationIds.has(registration.id)) return true;
+    suppressed.push({ kind: 'registration', targetId: registration.id, reason: 'scope-override-registration' });
+    return false;
+  });
+
+  // A project record that duplicates a global Registration ID is invalid rather than an
+  // override; it stays durable but cannot participate in Effective State.
+  const globalRegistrationIds = new Set(survivingGlobalRegistrations.map((registration) => registration.id));
+  const projectRegistrations = projectState.registrations.filter((registration) => {
+    if (!globalRegistrationIds.has(registration.id)) return true;
+    excluded.push({ kind: 'registration', id: registration.id, reason: 'invalid-duplicate-registration-id' });
+    return false;
+  });
+
+  // A Registration Override suppresses its whole marketplace subtree: every Installation
+  // supplied by that Registration disappears with it.
+  const survivingGlobalInstallations: Installation[] = [];
+  for (const installation of globalState.installations) {
+    if (installation.registrationId && overriddenRegistrationIds.has(installation.registrationId)) {
+      suppressed.push({
+        kind: 'installation',
+        targetId: installation.id,
+        pluginId: installation.pluginId,
+        reason: 'scope-override-registration',
+      });
+      continue;
+    }
+    if (overriddenInstallationIds.has(installation.id)) {
+      suppressed.push({
+        kind: 'installation',
+        targetId: installation.id,
+        pluginId: installation.pluginId,
+        reason: 'scope-override-installation',
+      });
+      continue;
+    }
+    survivingGlobalInstallations.push(installation);
+  }
+
+  // Only enabled Installations ever participate; a disabled project Installation neither
+  // participates nor supersedes its inherited global twin.
+  const enabledProjectInstallations = projectState.installations.filter(
+    (installation) => installation.installationState === 'enabled',
+  );
+  const projectPluginIds = new Set(enabledProjectInstallations.map((installation) => installation.pluginId));
+
+  for (const installation of survivingGlobalInstallations) {
+    if (installation.installationState !== 'enabled') continue;
+    if (!projectPluginIds.has(installation.pluginId)) continue;
+    const supersedingId = enabledProjectInstallations.find((item) => item.pluginId === installation.pluginId)!.id;
+    suppressed.push({
+      kind: 'installation',
+      targetId: installation.id,
+      pluginId: installation.pluginId,
+      reason: 'project-precedence',
+      supersededBy: supersedingId,
+    });
+  }
+
+  const supersededIds = new Set(suppressed.filter((s) => s.reason === 'project-precedence').map((s) => s.targetId));
+
+  return {
+    registrations: [
+      ...survivingGlobalRegistrations.map((registration): EffectiveRegistration => ({ ...registration, sourceScope: 'global' })),
+      ...projectRegistrations.map((registration): EffectiveRegistration => ({ ...registration, sourceScope: 'project' })),
+    ],
+    installations: [
+      ...survivingGlobalInstallations
+        .filter((installation) => installation.installationState === 'enabled' && !supersededIds.has(installation.id))
+        .map((installation): EffectiveInstallation => ({ ...installation, sourceScope: 'global' })),
+      ...enabledProjectInstallations.map((installation): EffectiveInstallation => ({ ...installation, sourceScope: 'project' })),
+    ],
+    suppressed,
+    excluded,
+  };
+}

package/src/projection/index.ts

@@ -0,0 +1,4 @@
+export * from './effective-state.js';
+export * from './collision.js';
+export * from './overrides.js';
+export * from './project.js';