pi-codex-marketplace 0.1.0

package/src/bridge-state/migrate.ts

@@ -0,0 +1,261 @@
+/**
+ * Bridge State WAL Migration — schemaVersion binding.
+ *
+ * Closed rules (per CONTEXT.md / Issue #24):
+ * - Versioned JSON schema with `schemaVersion` bound to Bridge Package version.
+ * - Supported forward migrations are applied atomically via WAL (write-ahead log).
+ * - Unknown / newer `schemaVersion` (> CURRENT) is `incompatible` — fail-closed, no auto-migrate, no rollback.
+ * - Downgrade (attempting to persist an older schemaVersion over a newer durable file) never writes back.
+ * - No implicit activation or automatic rollback on migration.
+ * - WAL is per-document (`state.json.wal` sibling), fsynced before commit, replayed on read, cleaned after success.
+ * - Corruption during migration leaves the previous durable revision verifiable or the file treated as Indeterminate.
+ */
+
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { atomicWriteFile } from './atomic.js';
+import { getWalPath } from './paths.js';
+import { parseJson } from './schema.js';
+import { CURRENT_SCHEMA_VERSION, type BridgeState, createEmptyState } from './types.js';
+
+/** Known forward migrations: fromVersion -> migrator. Only migrations listed here are supported. */
+type Migrator = (state: BridgeState) => BridgeState;
+
+const MIGRATIONS: Record<number, Migrator> = {
+  // Future: 1 -> 2 example
+  // 1: (state) => ({ ...state, schemaVersion: 2, registrations: state.registrations.map(...) })
+};
+
+export interface MigrationResult {
+  ok: boolean;
+  state?: BridgeState;
+  migrated?: boolean;
+  /** From version before migration, when migrated. */
+  fromVersion?: number;
+  toVersion?: number;
+  error?: string;
+  code?: 'INCOMPATIBLE_NEWER' | 'UNKNOWN_OLD_VERSION' | 'MIGRATION_FAILED' | 'CORRUPTED' | 'DOWNGRADE_BLOCKED';
+}
+
+/**
+ * Attempt to migrate a parsed BridgeState forward to CURRENT_SCHEMA_VERSION.
+ * Returns:
+ * - ok:true + migrated:false when already current
+ * - ok:true + migrated:true when migrated via known chain
+ * - ok:false with INCOMPATIBLE_NEWER when file is newer than current (do not auto-migrate)
+ * - ok:false with UNKNOWN_OLD_VERSION when no migration path exists for an older version
+ */
+export function migrateForward(state: BridgeState): MigrationResult {
+  const from = state.schemaVersion;
+
+  if (from === CURRENT_SCHEMA_VERSION) {
+    return { ok: true, state, migrated: false, fromVersion: from, toVersion: CURRENT_SCHEMA_VERSION };
+  }
+
+  if (!Number.isInteger(from) || from < 1) {
+    return {
+      ok: false,
+      code: 'CORRUPTED',
+      error: `Invalid schemaVersion ${from} — treated as corrupted`,
+    };
+  }
+
+  if (from > CURRENT_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      code: 'INCOMPATIBLE_NEWER',
+      error: `Incompatible schemaVersion ${from} > supported ${CURRENT_SCHEMA_VERSION} — requires newer Bridge Package (no downgrade write-back)`,
+    };
+  }
+
+  // from < CURRENT: need forward chain
+  let cur: BridgeState = structuredClone(state);
+  let version = from;
+  while (version < CURRENT_SCHEMA_VERSION) {
+    const migrator = MIGRATIONS[version];
+    if (!migrator) {
+      return {
+        ok: false,
+        code: 'UNKNOWN_OLD_VERSION',
+        error: `No supported migration path from schemaVersion ${from} to ${CURRENT_SCHEMA_VERSION} (missing ${version}→${version + 1}) — fail-closed`,
+      };
+    }
+    try {
+      cur = migrator(cur);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return {
+        ok: false,
+        code: 'MIGRATION_FAILED',
+        error: `Migration ${version}→${version + 1} failed: ${msg}`,
+      };
+    }
+    // Migrator must bump schemaVersion exactly by one; enforce closed invariant
+    if (cur.schemaVersion !== version + 1) {
+      return {
+        ok: false,
+        code: 'MIGRATION_FAILED',
+        error: `Migration ${version}→${version + 1} did not set schemaVersion to ${version + 1} (got ${cur.schemaVersion})`,
+      };
+    }
+    version = cur.schemaVersion;
+  }
+
+  return { ok: true, state: cur, migrated: true, fromVersion: from, toVersion: CURRENT_SCHEMA_VERSION };
+}
+
+/**
+ * Downgrade guard: refuse to persist a state whose schemaVersion is older than the durable file.
+ * Returns true if write should be blocked (never write back to an older version).
+ */
+export function isDowngradeAttempt(durableVersion: number, targetVersion: number): boolean {
+  return targetVersion < durableVersion;
+}
+
+/**
+ * WAL helpers — per-document write-ahead log at `state.json.wal`.
+ * The WAL holds the *target* state JSON before the atomic rename, plus a header with from/to versions.
+ * On read, if WAL exists but state.json still holds the old revision, the WAL can be replayed or cleaned.
+ */
+
+interface WalRecord {
+  fromVersion: number;
+  toVersion: number;
+  fromRevision: string;
+  targetState: BridgeState;
+  createdAt: string;
+}
+
+function writeWalSync(statePath: string, record: WalRecord): void {
+  const walPath = getWalPath(statePath);
+  const dir = dirname(statePath);
+  mkdirSync(dir, { recursive: true });
+  const data = JSON.stringify(record, null, 2) + '\n';
+  const fd = openSync(walPath, 'w', 0o600);
+  try {
+    writeSync(fd, data, null, 'utf-8');
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    const dirFd = openSync(dir, 'r');
+    try {
+      fsyncSync(dirFd);
+    } finally {
+      closeSync(dirFd);
+    }
+  } catch {}
+}
+
+function readWalSync(statePath: string): WalRecord | undefined {
+  const walPath = getWalPath(statePath);
+  if (!existsSync(walPath)) return undefined;
+  try {
+    const raw = readFileSync(walPath, 'utf-8');
+    const parsed = JSON.parse(raw) as WalRecord;
+    if (typeof parsed.fromVersion !== 'number' || typeof parsed.toVersion !== 'number' || !parsed.targetState) return undefined;
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}
+
+function removeWalSync(statePath: string): void {
+  const walPath = getWalPath(statePath);
+  if (!existsSync(walPath)) return;
+  try {
+    unlinkSync(walPath);
+  } catch {}
+}
+
+/**
+ * Perform a WAL-guarded migration commit: write WAL, then atomic rename.
+ * Caller must already hold the file lock.
+ * Returns true when the migrated state was durable, false otherwise.
+ */
+export function commitMigratedState(statePath: string, migrated: BridgeState, fromVersion: number, fromRevision: string): boolean {
+  const record: WalRecord = {
+    fromVersion,
+    toVersion: migrated.schemaVersion,
+    fromRevision,
+    targetState: migrated,
+    createdAt: new Date().toISOString(),
+  };
+  try {
+    writeWalSync(statePath, record);
+  } catch {
+    return false;
+  }
+
+  const data = JSON.stringify(migrated, null, 2) + '\n';
+  const result = atomicWriteFile(statePath, data);
+  if (!result.success) {
+    // WAL remains for replay on next read; caller treats as Persistence Failed/Indeterminate
+    return false;
+  }
+
+  // Success: remove WAL
+  try {
+    removeWalSync(statePath);
+  } catch {}
+  return true;
+}
+
+/**
+ * Attempt to replay or clean a stale WAL on read.
+ * If WAL's target matches the current file's revision/version, WAL is just cleaned.
+ * If WAL's source matches the current file but target is newer, WAL target is re-applied (recovery without new confirmation).
+ * In all other cases WAL is removed as orphaned.
+ */
+export function recoverWalIfNeeded(statePath: string, currentState: BridgeState | null): { recovered: boolean; state?: BridgeState } {
+  const wal = readWalSync(statePath);
+  if (!wal) return { recovered: false };
+
+  if (!currentState) {
+    // No durable file — apply WAL target if it looks valid
+    const ok = wal.targetState && wal.targetState.schemaVersion === CURRENT_SCHEMA_VERSION;
+    if (!ok) {
+      removeWalSync(statePath);
+      return { recovered: false };
+    }
+    const data = JSON.stringify(wal.targetState, null, 2) + '\n';
+    const res = atomicWriteFile(statePath, data);
+    if (res.success) {
+      removeWalSync(statePath);
+      return { recovered: true, state: wal.targetState };
+    }
+    return { recovered: false };
+  }
+
+  // File exists; compare
+  if (currentState.schemaVersion === wal.toVersion && currentState.stateRevision === wal.targetState.stateRevision) {
+    // Already applied
+    removeWalSync(statePath);
+    return { recovered: false };
+  }
+  if (currentState.schemaVersion === wal.fromVersion && currentState.stateRevision === wal.fromRevision) {
+    // Replay WAL: durable still holds old revision, WAL holds migrated target
+    const data = JSON.stringify(wal.targetState, null, 2) + '\n';
+    const res = atomicWriteFile(statePath, data);
+    if (res.success) {
+      removeWalSync(statePath);
+      return { recovered: true, state: wal.targetState };
+    }
+    return { recovered: false };
+  }
+
+  // Orphan / mismatch — clean
+  removeWalSync(statePath);
+  return { recovered: false };
+}
+
+/** For tests: expose internals */
+export const _internal = {
+  MIGRATIONS,
+  writeWalSync,
+  readWalSync,
+  removeWalSync,
+  CURRENT_SCHEMA_VERSION,
+};

package/src/bridge-state/paths.ts

@@ -0,0 +1,75 @@
+/**
+ * Dual-path helpers for Bridge State documents.
+ * - Global:  {getAgentDir()}/codex-marketplace/state.json
+ * - Project: {cwd}/.pi/codex-marketplace/state.json
+ *
+ * getAgentDir() mirrors Pi's config.getAgentDir(): honors PI_CODING_AGENT_DIR,
+ * otherwise ~/.pi/agent. Project path uses CONFIG_DIR_NAME ".pi".
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const CONFIG_DIR_NAME = '.pi';
+export const BRIDGE_SUBDIR = 'codex-marketplace';
+export const STATE_FILENAME = 'state.json';
+export const RECEIPTS_FILENAME = 'receipts.jsonl';
+export const LOCK_SUFFIX = '.lock';
+export const WAL_SUFFIX = '.wal';
+export const FENCE_SUFFIX = '.fence';
+
+/** Mirrors pi's getAgentDir() — env PI_CODING_AGENT_DIR wins, else ~/.pi/agent */
+export function getAgentDir(): string {
+  const env = process.env.PI_CODING_AGENT_DIR ?? process.env.PI_AGENT_DIR;
+  if (env && env.trim().length > 0) {
+    // Pi does tilde + normalize; we do minimal
+    if (env.startsWith('~/')) return join(homedir(), env.slice(2));
+    return env;
+  }
+  return join(homedir(), CONFIG_DIR_NAME, 'agent');
+}
+
+export function getGlobalStateDir(agentDir = getAgentDir()): string {
+  return join(agentDir, BRIDGE_SUBDIR);
+}
+
+export function getGlobalStatePath(agentDir = getAgentDir()): string {
+  return join(getGlobalStateDir(agentDir), STATE_FILENAME);
+}
+
+export function getProjectStateDir(cwd: string = process.cwd()): string {
+  return join(cwd, CONFIG_DIR_NAME, BRIDGE_SUBDIR);
+}
+
+export function getProjectStatePath(cwd: string = process.cwd()): string {
+  return join(getProjectStateDir(cwd), STATE_FILENAME);
+}
+
+export function getStatePath(
+  scope: 'global' | 'project',
+  opts: { cwd?: string; agentDir?: string } = {},
+): string {
+  if (scope === 'global') return getGlobalStatePath(opts.agentDir);
+  return getProjectStatePath(opts.cwd);
+}
+
+export function getReceiptsJournalPath(
+  scope: 'global' | 'project',
+  opts: { cwd?: string; agentDir?: string } = {},
+): string {
+  const stateDir = scope === 'global' ? getGlobalStateDir(opts.agentDir) : getProjectStateDir(opts.cwd);
+  return join(stateDir, RECEIPTS_FILENAME);
+}
+
+export function getLockPath(statePath: string): string {
+  return `${statePath}${LOCK_SUFFIX}`;
+}
+
+export function getWalPath(statePath: string): string {
+  return `${statePath}${WAL_SUFFIX}`;
+}
+
+export function getFencePath(statePath: string): string {
+  return `${statePath}${FENCE_SUFFIX}`;
+}
+

package/src/bridge-state/repair.ts

@@ -0,0 +1,185 @@
+/**
+ * Repair State — Recovery Action to verify and repair Bridge State consistency.
+ * See CONTEXT.md: Persistence Indeterminate, Recovery Action.
+ *
+ * Checks whether the state file on disk is readable and schema-valid, and resolves
+ * any active Persistence Indeterminate recovery chain.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { getStatePath } from './paths.js';
+import { parseJson, validateSchema } from './schema.js';
+import type { BridgeState, Scope } from './types.js';
+import { acquireAttemptFence } from '../registration/fence.js';
+import { appendReceipt, readReceiptJournal } from '../journal/journal.js';
+import { createReceipt, type AttemptReceipt } from '../registration/receipt.js';
+import { blocking, CODE, RULE, type ValidationFinding } from '../registration/findings.js';
+
+export interface RepairStateResult {
+  success: boolean;
+  state?: BridgeState;
+  error?: string;
+  receipt: AttemptReceipt;
+}
+
+export async function repairBridgeState(
+  scope: Scope,
+  opts: { cwd?: string; agentDir?: string; fenceTimeoutMs?: number } = {},
+): Promise<RepairStateResult> {
+  const fence = await acquireAttemptFence(scope, opts);
+  if (!fence.ok) {
+    const receipt = createReceipt({
+      kind: 'State Repair',
+      operation: 'Repair State',
+      scope,
+      trigger: `repair state ${scope}`,
+      expectedStateRevision: '?',
+      summary: 'Blocked',
+      findings: [fence.finding!],
+    });
+    await appendReceipt(scope, receipt, opts);
+    return { success: false, error: fence.finding?.outcome, receipt };
+  }
+
+  const handle = fence.handle!;
+  const statePath = getStatePath(scope, opts);
+
+  try {
+    const journal = await readReceiptJournal(scope, opts);
+    const indetChain = journal.activeChains.find(
+      (c) => c.condition === 'persistence-indeterminate' || c.condition === 'journal-degradation',
+    );
+
+    if (!existsSync(statePath)) {
+      // Empty / missing state is valid (reconstructed as revision 0)
+      const receipt = createReceipt({
+        kind: 'State Repair',
+        operation: 'Repair State',
+        scope,
+        trigger: `repair state ${scope}`,
+        expectedStateRevision: '0',
+        observedStateRevision: '0',
+        durableOutcome: 'unchanged',
+        runtimeOutcome: 'none',
+        summary: 'Completed',
+        recoversReceiptId: indetChain?.rootReceiptId,
+      });
+      await appendReceipt(scope, receipt, opts);
+      handle.release();
+      return { success: true, receipt };
+    }
+
+    let content: string;
+    try {
+      content = readFileSync(statePath, 'utf-8');
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      const finding: ValidationFinding = blocking({
+        code: CODE.PERSISTENCE_INDETERMINATE,
+        phase: 'persistence',
+        target: 'attempt',
+        scope,
+        pointer: statePath,
+        rule: RULE.STATE_CORRUPT,
+        outcome: `Failed to read ${statePath}: ${msg}`,
+      });
+      const receipt = createReceipt({
+        kind: 'State Repair',
+        operation: 'Repair State',
+        scope,
+        trigger: `repair state ${scope}`,
+        expectedStateRevision: '?',
+        durableOutcome: 'indeterminate',
+        summary: 'Persistence Indeterminate',
+        findings: [finding],
+      });
+      await appendReceipt(scope, receipt, opts);
+      handle.release();
+      return { success: false, error: msg, receipt };
+    }
+
+    const parsed = parseJson(content);
+    if (!parsed.ok) {
+      const finding: ValidationFinding = blocking({
+        code: CODE.PERSISTENCE_INDETERMINATE,
+        phase: 'persistence',
+        target: 'attempt',
+        scope,
+        pointer: statePath,
+        rule: RULE.STATE_CORRUPT,
+        outcome: `Corrupted JSON: ${parsed.error}`,
+      });
+      const receipt = createReceipt({
+        kind: 'State Repair',
+        operation: 'Repair State',
+        scope,
+        trigger: `repair state ${scope}`,
+        expectedStateRevision: '?',
+        durableOutcome: 'indeterminate',
+        summary: 'Persistence Indeterminate',
+        findings: [finding],
+      });
+      await appendReceipt(scope, receipt, opts);
+      handle.release();
+      return { success: false, error: parsed.error, receipt };
+    }
+
+    const validation = validateSchema(parsed.value);
+    if (!validation.ok) {
+      const finding: ValidationFinding = blocking({
+        code: CODE.PERSISTENCE_INDETERMINATE,
+        phase: 'persistence',
+        target: 'attempt',
+        scope,
+        pointer: statePath,
+        rule: validation.code === 'INCOMPATIBLE_SCHEMA_VERSION' ? RULE.STATE_SCHEMA_UNKNOWN : RULE.STATE_CORRUPT,
+        outcome: `Invalid schema: ${validation.error}`,
+      });
+      const receipt = createReceipt({
+        kind: 'State Repair',
+        operation: 'Repair State',
+        scope,
+        trigger: `repair state ${scope}`,
+        expectedStateRevision: '?',
+        durableOutcome: 'indeterminate',
+        summary: 'Persistence Indeterminate',
+        findings: [finding],
+      });
+      await appendReceipt(scope, receipt, opts);
+      handle.release();
+      return { success: false, error: validation.error, receipt };
+    }
+
+    const validState = parsed.value as BridgeState;
+    const receipt = createReceipt({
+      kind: 'State Repair',
+      operation: 'Repair State',
+      scope,
+      trigger: `repair state ${scope}`,
+      expectedStateRevision: validState.stateRevision,
+      observedStateRevision: validState.stateRevision,
+      durableOutcome: 'unchanged',
+      runtimeOutcome: 'none',
+      summary: 'Completed',
+      recoversReceiptId: indetChain?.rootReceiptId,
+    });
+    await appendReceipt(scope, receipt, opts);
+    handle.release();
+    return { success: true, state: validState, receipt };
+  } catch (e) {
+    handle.release();
+    const msg = e instanceof Error ? e.message : String(e);
+    const receipt = createReceipt({
+      kind: 'State Repair',
+      operation: 'Repair State',
+      scope,
+      trigger: `repair state ${scope}`,
+      expectedStateRevision: '?',
+      durableOutcome: 'indeterminate',
+      summary: 'Persistence Indeterminate',
+    });
+    await appendReceipt(scope, receipt, opts);
+    return { success: false, error: msg, receipt };
+  }
+}

package/src/bridge-state/schema.ts

@@ -0,0 +1,70 @@
+/**
+ * Versioned JSON schema validation for Bridge State.
+ * Closed handling: corrupted or unknown new schemaVersion => treat as
+ * Indeterminate / incompatible, never auto-rollback or auto-migrate forward beyond known versions.
+ */
+
+import { CURRENT_SCHEMA_VERSION, type BridgeState, isBridgeState } from './types.js';
+
+export interface SchemaValidation {
+  ok: boolean;
+  error?: string;
+  code?: 'CORRUPTED_JSON' | 'INVALID_SCHEMA' | 'INCOMPATIBLE_SCHEMA_VERSION';
+}
+
+/** Validate parsed JSON as BridgeState; check schemaVersion compatibility. */
+export function validateSchema(parsed: unknown): SchemaValidation {
+  if (!isBridgeState(parsed)) {
+    return {
+      ok: false,
+      code: 'INVALID_SCHEMA',
+      error:
+        'Invalid Bridge State: expected { schemaVersion:number, stateRevision:string, registrations:[], installations:[], scopeOverrides:[] }',
+    };
+  }
+
+  const state = parsed as BridgeState;
+
+  if (!Number.isInteger(state.schemaVersion) || state.schemaVersion < 1) {
+    return {
+      ok: false,
+      code: 'INVALID_SCHEMA',
+      error: `Invalid schemaVersion: ${state.schemaVersion}`,
+    };
+  }
+
+  if (state.schemaVersion > CURRENT_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      code: 'INCOMPATIBLE_SCHEMA_VERSION',
+      error: `Incompatible schemaVersion ${state.schemaVersion} > supported ${CURRENT_SCHEMA_VERSION} — requires newer Bridge Package`,
+    };
+  }
+
+  // monotonic revision must be numeric string
+  try {
+    BigInt(state.stateRevision);
+  } catch {
+    return {
+      ok: false,
+      code: 'INVALID_SCHEMA',
+      error: `Invalid stateRevision (not numeric opaque): ${state.stateRevision}`,
+    };
+  }
+
+  // scopeOverrides only meaningful for project, but global may have empty — allow both
+  // registrations/installations elements are not deeply validated at scaffold level
+
+  return { ok: true };
+}
+
+/** Check if raw file content parses as JSON, return parsed or error */
+export function parseJson(content: string): { ok: true; value: unknown } | { ok: false; error: string } {
+  try {
+    const value = JSON.parse(content);
+    return { ok: true, value };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, error: `Corrupted JSON: ${msg}` };
+  }
+}