pi-codex-marketplace 0.1.0

package/src/journal/active-chains.ts

@@ -0,0 +1,99 @@
+/**
+ * Active Recovery Chains in the Receipt Journal.
+ * See CONTEXT.md: Receipt Resolution, Receipt Journal, Active Recovery Chain.
+ *
+ * Rules:
+ * - A receipt enters an active condition if:
+ *   - summary === 'Pending Application'
+ *   - summary === 'Persistence Indeterminate' or durableOutcome === 'indeterminate'
+ *   - summary === 'Persistence Failed' or durableOutcome === 'failed'
+ *   - has RECEIPT_PERSISTENCE_FAILED finding
+ * - Resolved: a later receipt explicitly recovers this receipt (recoversReceiptId === rootReceiptId)
+ *   and achieves Completed / Completed with diagnostics for the same target state.
+ * - Superseded: a later receipt commits a replacement State Revision (durableOutcome === 'committed'
+ *   and new revision) or explicitly targets superseding.
+ * - Failed retry: appends to the chain, but leaves the active condition UNRESOLVED.
+ */
+
+import { CODE } from '../registration/findings.js';
+import type { AttemptReceipt } from '../registration/receipt.js';
+import type { ActiveCondition, ActiveRecoveryChain } from './types.js';
+
+function getActiveCondition(receipt: AttemptReceipt): ActiveCondition | null {
+  if (receipt.findings.some((f) => f.code === CODE.RECEIPT_PERSISTENCE_FAILED)) {
+    return 'journal-degradation';
+  }
+  if (receipt.summary === 'Persistence Indeterminate' || receipt.durableOutcome === 'indeterminate') {
+    return 'persistence-indeterminate';
+  }
+  if (receipt.summary === 'Persistence Failed' || receipt.durableOutcome === 'failed') {
+    return 'persistence-failed';
+  }
+  if (receipt.summary === 'Pending Application' || receipt.runtimeOutcome === 'pending-application') {
+    return 'pending-application';
+  }
+  return null;
+}
+
+export function findActiveRecoveryChains(
+  receipts: AttemptReceipt[],
+): { activeChains: ActiveRecoveryChain[]; allChains: ActiveRecoveryChain[] } {
+  const chains: ActiveRecoveryChain[] = [];
+
+  for (let i = 0; i < receipts.length; i++) {
+    const rcpt = receipts[i];
+    const condition = getActiveCondition(rcpt);
+
+    // If this receipt is a recovery attempt for an existing chain
+    if (rcpt.recoversReceiptId) {
+      const existingChain = chains.find((c) => c.rootReceiptId === rcpt.recoversReceiptId);
+      if (existingChain) {
+        existingChain.receipts.push(rcpt);
+        if (rcpt.summary === 'Completed' || rcpt.summary === 'Completed with diagnostics') {
+          existingChain.resolved = true;
+          existingChain.resolvedByReceiptId = rcpt.id;
+        }
+        continue;
+      }
+    }
+
+    // If this receipt opened an active condition and wasn't a recovery attempt
+    if (condition) {
+      const chain: ActiveRecoveryChain = {
+        rootReceiptId: rcpt.id,
+        scope: rcpt.scope,
+        condition,
+        stateRevision: rcpt.observedStateRevision ?? rcpt.targetStateRevision ?? rcpt.expectedStateRevision,
+        receipts: [rcpt],
+        resolved: false,
+        superseded: false,
+      };
+      chains.push(chain);
+    }
+
+    // Check if this receipt supersedes any earlier un-resolved chains in the same scope
+    // A replacement commit supersedes previous un-resolved chains
+    if (rcpt.durableOutcome === 'committed' && rcpt.observedStateRevision) {
+      for (const chain of chains) {
+        if (!chain.resolved && !chain.superseded && chain.scope === rcpt.scope && chain.rootReceiptId !== rcpt.id) {
+          // If the commit revision is different/newer than the chain's revision
+          if (rcpt.observedStateRevision !== chain.stateRevision) {
+            chain.superseded = true;
+            chain.supersededByReceiptId = rcpt.id;
+          }
+        }
+      }
+    }
+
+    if (rcpt.supersedesReceiptId) {
+      const targetChain = chains.find((c) => c.rootReceiptId === rcpt.supersedesReceiptId);
+      if (targetChain && !targetChain.resolved) {
+        targetChain.superseded = true;
+        targetChain.supersededByReceiptId = rcpt.id;
+      }
+    }
+  }
+
+  const activeChains = chains.filter((c) => !c.resolved && !c.superseded);
+  return { activeChains, allChains: chains };
+}

package/src/journal/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './active-chains.js';
+export * from './journal.js';

package/src/journal/journal.ts

@@ -0,0 +1,215 @@
+/**
+ * Receipt Journal implementation — append-only durable history of Attempt Receipts.
+ * See CONTEXT.md: Receipt Journal, Attempt Receipt, Receipt Resolution.
+ *
+ * File location:
+ * - Global:  {getAgentDir()}/codex-marketplace/receipts.jsonl
+ * - Project: {cwd}/.pi/codex-marketplace/receipts.jsonl
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, openSync, closeSync, fsyncSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { atomicWriteFile } from '../bridge-state/atomic.js';
+import { getReceiptsJournalPath } from '../bridge-state/paths.js';
+import type { Scope } from '../bridge-state/types.js';
+import { CODE, notice, RULE, type ValidationFinding } from '../registration/findings.js';
+import type { AttemptReceipt } from '../registration/receipt.js';
+import { findActiveRecoveryChains } from './active-chains.js';
+import type {
+  JournalAppendResult,
+  JournalPruneResult,
+  JournalReadResult,
+} from './types.js';
+
+export interface JournalOptions {
+  cwd?: string;
+  agentDir?: string;
+}
+
+/** Append an Attempt Receipt to the scope's Receipt Journal with fsync durability. */
+export async function appendReceipt(
+  scope: Scope,
+  receipt: AttemptReceipt,
+  opts: JournalOptions = {},
+): Promise<JournalAppendResult> {
+  const journalPath = getReceiptsJournalPath(scope, opts);
+  try {
+    mkdirSync(dirname(journalPath), { recursive: true });
+    const line = JSON.stringify(receipt) + '\n';
+    appendFileSync(journalPath, line, 'utf-8');
+
+    // fsync file for durability
+    try {
+      const fd = openSync(journalPath, 'r');
+      try {
+        fsyncSync(fd);
+      } finally {
+        closeSync(fd);
+      }
+    } catch {}
+
+    return { success: true };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    const finding: ValidationFinding = notice({
+      code: CODE.RECEIPT_PERSISTENCE_FAILED,
+      phase: 'post-commit',
+      target: 'attempt',
+      scope,
+      pointer: journalPath,
+      rule: RULE.RECEIPT_PERSISTENCE_FAILED,
+      outcome: `Failed to persist Attempt Receipt to journal: ${msg}`,
+    });
+    return { success: false, error: msg, finding };
+  }
+}
+
+/** Read the scope's Receipt Journal, parsing line-by-line with tolerance for single-line corruptions. */
+export async function readReceiptJournal(
+  scope: Scope,
+  opts: JournalOptions = {},
+): Promise<JournalReadResult> {
+  const journalPath = getReceiptsJournalPath(scope, opts);
+
+  if (!existsSync(journalPath)) {
+    return {
+      receipts: [],
+      activeChains: [],
+      allChains: [],
+      corruptedLineCount: 0,
+      isDegraded: false,
+      findings: [],
+    };
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(journalPath, 'utf-8');
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+      receipts: [],
+      activeChains: [],
+      allChains: [],
+      corruptedLineCount: 1,
+      isDegraded: true,
+      findings: [
+        notice({
+          code: CODE.RECEIPT_CORRUPT,
+          phase: 'post-commit',
+          target: 'attempt',
+          scope,
+          pointer: journalPath,
+          rule: RULE.RECEIPT_CORRUPT,
+          outcome: `Failed to read receipts journal: ${msg}`,
+        }),
+      ],
+      error: msg,
+    };
+  }
+
+  const lines = content.split('\n');
+  const receipts: AttemptReceipt[] = [];
+  const findings: ValidationFinding[] = [];
+  let corruptedLineCount = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.length === 0) continue;
+
+    try {
+      const parsed = JSON.parse(line);
+      if (typeof parsed === 'object' && parsed !== null && typeof parsed.id === 'string' && typeof parsed.summary === 'string') {
+        receipts.push(parsed as AttemptReceipt);
+      } else {
+        corruptedLineCount++;
+        findings.push(
+          notice({
+            code: CODE.RECEIPT_CORRUPT,
+            phase: 'post-commit',
+            target: 'attempt',
+            scope,
+            pointer: `${journalPath}:${i + 1}`,
+            rule: RULE.RECEIPT_CORRUPT,
+            outcome: `Corrupted receipt line ${i + 1}: missing required receipt fields`,
+          }),
+        );
+      }
+    } catch (e) {
+      corruptedLineCount++;
+      findings.push(
+        notice({
+          code: CODE.RECEIPT_CORRUPT,
+          phase: 'post-commit',
+          target: 'attempt',
+          scope,
+          pointer: `${journalPath}:${i + 1}`,
+          rule: RULE.RECEIPT_CORRUPT,
+          outcome: `Corrupted receipt line ${i + 1}: invalid JSON`,
+        }),
+      );
+    }
+  }
+
+  const { activeChains, allChains } = findActiveRecoveryChains(receipts);
+  const isDegraded = corruptedLineCount > 0;
+
+  return {
+    receipts,
+    activeChains,
+    allChains,
+    corruptedLineCount,
+    isDegraded,
+    findings,
+  };
+}
+
+/** Prune resolved receipts outside active chains while preserving ALL active recovery chains. */
+export async function pruneReceiptJournal(
+  scope: Scope,
+  keepCount = 100,
+  opts: JournalOptions = {},
+): Promise<JournalPruneResult> {
+  const current = await readReceiptJournal(scope, opts);
+  const activeReceiptIds = new Set<string>();
+
+  for (const chain of current.activeChains) {
+    for (const r of chain.receipts) {
+      activeReceiptIds.add(r.id);
+    }
+  }
+
+  const outsideActive: AttemptReceipt[] = [];
+  for (const r of current.receipts) {
+    if (!activeReceiptIds.has(r.id)) {
+      outsideActive.push(r);
+    }
+  }
+
+  // Keep latest N outside active chains
+  const retainOutside = outsideActive.slice(-keepCount);
+  const retainOutsideIds = new Set(retainOutside.map((r) => r.id));
+
+  // Build final retained receipts preserving chronological order
+  const retained = current.receipts.filter(
+    (r) => activeReceiptIds.has(r.id) || retainOutsideIds.has(r.id),
+  );
+
+  const prunedCount = current.receipts.length - retained.length;
+  const journalPath = getReceiptsJournalPath(scope, opts);
+
+  const content = retained.map((r) => JSON.stringify(r)).join('\n') + (retained.length > 0 ? '\n' : '');
+  mkdirSync(dirname(journalPath), { recursive: true });
+  atomicWriteFile(journalPath, content);
+
+  return { prunedCount, retainedCount: retained.length };
+}
+
+/** Reconstruct or initialize the Receipt Journal from state. */
+export async function reconstructJournalFromState(
+  scope: Scope,
+  opts: JournalOptions = {},
+): Promise<JournalReadResult> {
+  return readReceiptJournal(scope, opts);
+}

package/src/journal/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Receipt Journal types.
+ * See CONTEXT.md: Receipt Journal, Attempt Receipt, Receipt Resolution.
+ */
+
+import type { Scope } from '../bridge-state/types.js';
+import type { ValidationFinding } from '../registration/findings.js';
+import type { AttemptReceipt } from '../registration/receipt.js';
+
+export type ActiveCondition =
+  | 'pending-application'
+  | 'persistence-indeterminate'
+  | 'persistence-failed'
+  | 'journal-degradation';
+
+export interface ActiveRecoveryChain {
+  /** Root receipt that entered the active condition. */
+  rootReceiptId: string;
+  scope: Scope;
+  condition: ActiveCondition;
+  stateRevision: string;
+  /** All receipts in this chain (root + follow-up attempts). */
+  receipts: AttemptReceipt[];
+  resolved: boolean;
+  resolvedByReceiptId?: string;
+  superseded: boolean;
+  supersededByReceiptId?: string;
+}
+
+export interface JournalReadResult {
+  receipts: AttemptReceipt[];
+  activeChains: ActiveRecoveryChain[];
+  allChains: ActiveRecoveryChain[];
+  corruptedLineCount: number;
+  isDegraded: boolean;
+  findings: ValidationFinding[];
+  error?: string;
+}
+
+export interface JournalAppendResult {
+  success: boolean;
+  error?: string;
+  finding?: ValidationFinding;
+}
+
+export interface JournalPruneResult {
+  prunedCount: number;
+  retainedCount: number;
+}

package/src/lifecycle/index.ts

@@ -0,0 +1,5 @@
+export * from './refresh.js';
+export * from './update-plan.js';
+export * from './update.js';
+export * from './rebind.js';
+export * from './removal.js';

package/src/lifecycle/rebind.ts

@@ -0,0 +1,290 @@
+/**
+ * Registration Rebind — explicit replacement of a Marketplace Registration's source locator or
+ * Git Selector under the preserved Registration ID.
+ * See CONTEXT.md: Registration Rebind, Update Plan, Apply Update, Source Key.
+ *
+ * The rebind preflight is a non-mutating validation of the REPLACEMENT source: fresh validation,
+ * a fresh Registration Confirmation and a complete Update Plan are required before the atomic
+ * commit performed by `applyUpdate` (plan kind `rebind`). Prior activation consent never carries
+ * over. Duplicate detection runs against every OTHER Registration in the scope.
+ */
+
+import { readBridgeState } from '../bridge-state/store.js';
+import type { Registration, Scope } from '../bridge-state/types.js';
+import { inspectMarketplaceEntries } from '../installation/inspection.js';
+import {
+  CODE,
+  RULE,
+  blocking,
+  sortFindings,
+  type ValidationFinding,
+} from '../registration/findings.js';
+import {
+  acquireGitSource,
+  cleanupAcquisition,
+  type GitExecutor,
+} from '../registration/git-acquisition.js';
+import { normalizeGitLocator } from '../registration/git-locator.js';
+import {
+  normalizeGitSelector,
+  type GitSelectorInput,
+} from '../registration/git-selector.js';
+import { createReceipt, type AttemptReceipt } from '../registration/receipt.js';
+import { findDuplicateRegistration, sourceKeyForLocalRoot } from '../registration/registration.js';
+import { buildGitSnapshot, buildLocalSnapshot } from '../registration/snapshot.js';
+import { gitSourceKey, type SourceKey } from '../registration/source-key.js';
+import type { GitSelectorInput as StoredSelectorInput } from '../registration/git-selector.js';
+import type { LifecycleFlowOptions, UpdateCandidate } from './refresh.js';
+import { marketplaceNameOf, selectorInputFromStored } from './refresh.js';
+import type { RebindSourceAttributes } from './update-plan.js';
+
+export type RebindTarget =
+  | { kind: 'local'; rootPath: string }
+  | { kind: 'git'; locator: string; selector: GitSelectorInput | string };
+
+export interface RebindPreflightOk {
+  candidate: UpdateCandidate;
+  /** Observed State Revision the Update Plan must bind. */
+  stateRevision: string;
+  rebindSource: RebindSourceAttributes;
+}
+
+export type RebindPreflightResult =
+  | { ok: true; preflight: RebindPreflightOk }
+  | {
+      ok: false;
+      outcome:
+        | { status: 'blocked'; findings: ValidationFinding[]; receipt: AttemptReceipt }
+        | { status: 'persistence-failed'; findings: ValidationFinding[]; receipt: AttemptReceipt; isIndeterminate: boolean };
+    };
+
+const OPERATION = 'Registration Rebind';
+
+function blocked(scope: Scope, trigger: string, revision: string, findings: ValidationFinding[], validationSnapshot?: string): RebindPreflightResult {
+  return {
+    ok: false,
+    outcome: {
+      status: 'blocked',
+      findings: sortFindings(findings),
+      receipt: createReceipt({
+        operation: OPERATION,
+        scope,
+        trigger,
+        expectedStateRevision: revision,
+        validationSnapshot,
+        summary: 'Blocked',
+        findings,
+      }),
+    },
+  };
+}
+
+/**
+ * Inspection only reads the Registration's identity (id) when an explicit root + base snapshot
+ * are given, so a minimal record suffices without any cast.
+ */
+function identityProbe(registrationId: string): Registration {
+  return { id: registrationId };
+}
+
+/**
+ * Validate a replacement Marketplace Source for one existing Registration. Non-mutating: no fence,
+ * no writes; consent and atomic application happen through the Update Plan and `applyUpdate`.
+ */
+export async function preflightRebind(
+  scope: Scope,
+  registrationId: string,
+  target: RebindTarget,
+  opts: LifecycleFlowOptions = {},
+): Promise<RebindPreflightResult> {
+  const read = await readBridgeState(scope, { cwd: opts.cwd, agentDir: opts.agentDir });
+  if (read.status !== 'ok' && read.status !== 'missing') {
+    const findings: ValidationFinding[] = [
+      blocking({
+        code: CODE.PERSISTENCE_INDETERMINATE,
+        rule: 'PERSIST-01',
+        target: 'attempt',
+        pointer: '',
+        outcome: read.error ?? 'Bridge State is not readable; neither previous nor target verifiable',
+        scope,
+        phase: 'persistence',
+      }),
+    ];
+    return {
+      ok: false,
+      outcome: {
+        status: 'persistence-failed',
+        findings,
+        receipt: createReceipt({ operation: OPERATION, scope, trigger: `rebind ${registrationId}`, expectedStateRevision: '?', summary: 'Persistence Indeterminate', findings }),
+        isIndeterminate: true,
+      },
+    };
+  }
+  const state = read.state!;
+  const revision = state.stateRevision;
+  const registration = state.registrations.find((item) => item.id === registrationId);
+  if (!registration) {
+    return blocked(scope, `rebind ${registrationId}`, revision, [
+      blocking({ code: CODE.REGISTRATION_NOT_FOUND, rule: RULE.REGISTRATION_NOT_FOUND, target: 'registration', pointer: '', outcome: `Registration '${registrationId}' is not in ${scope} Bridge State`, scope, phase: 'admission' }),
+    ]);
+  }
+
+  // Duplicate detection runs against every OTHER Registration — the rebound one keeps its identity.
+  const others = state.registrations.filter((item) => item.id !== registrationId);
+  if (target.kind === 'local') {
+    return rebindToLocal(scope, registrationId, target.rootPath, others, revision, registration.validationSnapshot);
+  }
+  return rebindToGit(scope, registrationId, target.locator, target.selector, others, revision, registration.validationSnapshot, opts);
+}
+
+function rebindToLocal(
+  scope: Scope,
+  registrationId: string,
+  rootPath: string,
+  others: Registration[],
+  revision: string,
+  recordedSnapshot?: string,
+): RebindPreflightResult {
+  const trigger = `rebind ${registrationId}`;
+  const keyRes = sourceKeyForLocalRoot(rootPath, scope);
+  if (!keyRes.ok) return blocked(scope, trigger, revision, keyRes.findings, recordedSnapshot);
+  const sourceKey = keyRes.sourceKey!;
+
+  const dup = findDuplicateRegistration(scope, sourceKey, others);
+  if (dup.duplicate) return blocked(scope, trigger, revision, [dup.finding!], recordedSnapshot);
+
+  const snap = buildLocalSnapshot(sourceKey.canonicalPath!, sourceKey, scope);
+  if (!snap.ok || !snap.snapshot) return blocked(scope, trigger, revision, snap.findings, recordedSnapshot);
+
+  const inspection = inspectMarketplaceEntries(identityProbe(registrationId), scope, {
+    root: sourceKey.canonicalPath!,
+    baseSnapshot: snap.snapshot,
+    ignoreRecordedDrift: true,
+  });
+  const name = marketplaceNameOf(registrationId, inspection.marketplaceId);
+  if (!inspection.marketplaceId || inspection.findings.some((f) => f.classification === 'blocking')) {
+    return blocked(scope, trigger, revision, inspection.findings.length > 0 ? inspection.findings : [
+      blocking({ code: CODE.CATALOG_MISSING, rule: RULE.CATALOG_MISSING, target: 'catalog', pointer: '', outcome: 'replacement source has no readable Marketplace Catalog', scope, phase: 'validation' }),
+    ], snap.snapshot.fingerprint);
+  }
+
+  const candidate: UpdateCandidate = {
+    scope,
+    registrationId,
+    stateRevision: revision,
+    recordedFingerprint: undefined,
+    snapshot: snap.snapshot,
+    marketplaceName: name,
+    catalog: { name, entries: inspection.entries.map((item) => item.entry) },
+    inspection,
+    sourceKey,
+  };
+
+  return {
+    ok: true,
+    preflight: {
+      candidate,
+      stateRevision: revision,
+      rebindSource: { sourceKind: 'local', source: sourceKey.canonicalPath!, sourceKey },
+    },
+  };
+}
+
+async function rebindToGit(
+  scope: Scope,
+  registrationId: string,
+  locatorInput: string,
+  selectorInput: GitSelectorInput | string,
+  others: Registration[],
+  revision: string,
+  recordedSnapshot: string | undefined,
+  opts: LifecycleFlowOptions,
+): Promise<RebindPreflightResult> {
+  const trigger = `rebind ${registrationId}`;
+  const locRes = normalizeGitLocator(locatorInput, scope);
+  if (!locRes.ok) return blocked(scope, trigger, revision, locRes.findings, recordedSnapshot);
+
+  let selRes;
+  if (typeof selectorInput === 'string') {
+    selRes = await import('../registration/git-selector.js').then((m) => m.parseGitSelectorString(selectorInput, scope));
+  } else {
+    selRes = normalizeGitSelector(selectorInput as StoredSelectorInput, scope);
+  }
+  if (!selRes.ok) return blocked(scope, trigger, revision, selRes.findings, recordedSnapshot);
+  const selector = selRes.selector!;
+
+  const sourceKey = gitSourceKey(locRes.locator!, selector);
+
+  const dup = findDuplicateRegistration(scope, sourceKey, others);
+  if (dup.duplicate) return blocked(scope, trigger, revision, [dup.finding!]);
+
+  const acq = await acquireGitSource({
+    scope,
+    locator: locRes.locator!,
+    selector,
+    executor: opts.executor,
+  });
+  if (!acq.ok) return blocked(scope, trigger, revision, acq.findings, recordedSnapshot);
+
+  try {
+    const resolvedRevision = acq.resolvedRevision!;
+    const boundKey: SourceKey = {
+      ...sourceKey,
+      resolvedRevision,
+      canonicalUrl: locRes.locator!.canonicalUrl,
+      selector: selector.canonical,
+    };
+    const snap = buildGitSnapshot(acq.acquiredPath!, boundKey, scope, {
+      canonicalLocator: locRes.locator!.canonicalUrl,
+      resolvedRevision,
+      selectorCanonical: selector.canonical,
+    });
+    if (!snap.ok || !snap.snapshot) return blocked(scope, trigger, revision, snap.findings, recordedSnapshot);
+
+    const inspection = inspectMarketplaceEntries(identityProbe(registrationId), scope, {
+      root: acq.acquiredPath!,
+      baseSnapshot: snap.snapshot,
+      ignoreRecordedDrift: true,
+    });
+    const name = marketplaceNameOf(registrationId, inspection.marketplaceId);
+    if (!inspection.marketplaceId || inspection.findings.some((f) => f.classification === 'blocking')) {
+      return blocked(scope, trigger, revision, inspection.findings, snap.snapshot.fingerprint);
+    }
+
+    const candidate: UpdateCandidate = {
+      scope,
+      registrationId,
+      stateRevision: revision,
+      recordedFingerprint: undefined,
+      snapshot: snap.snapshot,
+      marketplaceName: name,
+      catalog: { name, entries: inspection.entries.map((item) => item.entry) },
+      inspection,
+      sourceKey: boundKey,
+      canonicalLocator: locRes.locator!.canonicalUrl,
+      resolvedRevision,
+      selectorCanonical: selector.canonical,
+    };
+
+    return {
+      ok: true,
+      preflight: {
+        candidate,
+        stateRevision: revision,
+        rebindSource: {
+          sourceKind: 'git',
+          source: locRes.locator!.canonicalUrl,
+          sourceKey: boundKey,
+          canonicalLocator: locRes.locator!.canonicalUrl,
+          gitSelector: { kind: selector.kind, canonical: selector.canonical, raw: selector.raw },
+          resolvedRevision,
+        },
+      },
+    };
+  } finally {
+    cleanupAcquisition(acq.acquiredPath!);
+  }
+}
+
+// Re-exported for callers reconstructing selectors from persisted state.
+export { selectorInputFromStored };