mcard-studio 0.0.0-stage → 0.0.2

package/src/core/processes/witness.ts

@@ -0,0 +1,88 @@
+/**
+ * src/core/processes/witness.ts
+ * Witness & Execution Receipt Projections (Sprint FM-05 / INV-FM-12, INV-FM-18)
+ *
+ * Provides pure presentation projection of execution receipts, VCard witnesses,
+ * and card outputs. Enforces strict fidelity: never synthesizes an output MCard hash
+ * or fake witness record from a receipt hash (GAP-05, INV-FM-18).
+ *
+ * Strictly pure: zero imports from edge, membrane, ui, Node built-ins, or DOM.
+ * Contract D budget: <= 250 LOC.
+ */
+
+import type { KernelEvent } from '../events/kernelEvents';
+
+export type WitnessVerdict = 'pass' | 'bail' | 'pending' | 'unknown';
+
+export interface WitnessViewModel {
+  readonly executionRef: string;
+  readonly receiptHash?: string;
+  readonly outputHash?: string;
+  readonly witnessHash?: string;
+  readonly witnessRefs: readonly string[];
+  readonly verdict: WitnessVerdict;
+  readonly reason?: string;
+}
+
+/**
+ * Projects a sequence of normalized KernelEvents for an execution reference
+ * into a pure presentation WitnessViewModel.
+ */
+export function toWitnessViewModel(
+  events: readonly KernelEvent[],
+  executionRef: string
+): WitnessViewModel {
+  const matchEvent = events.find((e) => 'intentId' in e && e.intentId === executionRef);
+
+  if (!matchEvent) {
+    return {
+      executionRef,
+      witnessRefs: [],
+      verdict: 'pending',
+    };
+  }
+
+  if (matchEvent.kind === 'IntentFailed') {
+    return {
+      executionRef,
+      witnessRefs: [],
+      verdict: 'bail',
+      reason: matchEvent.message,
+    };
+  }
+
+  if (matchEvent.kind === 'ExecutionReceipt') {
+    return {
+      executionRef,
+      receiptHash: matchEvent.receiptHash,
+      outputHash: matchEvent.outputHash, // Strictly preserved as undefined if not returned
+      witnessHash: undefined, // Absent until authoritatively returned or retrievable (GAP-05)
+      witnessRefs: matchEvent.witnessRefs ?? [],
+      verdict: matchEvent.receiptHash ? 'pass' : 'unknown',
+    };
+  }
+
+  if (matchEvent.kind === 'FiberParked') {
+    return {
+      executionRef,
+      witnessRefs: [],
+      verdict: 'pending',
+      reason: `Parked on token ${matchEvent.token}`,
+    };
+  }
+
+  if (matchEvent.kind === 'ActionApplied') {
+    return {
+      executionRef,
+      receiptHash: matchEvent.postHash,
+      witnessRefs: [],
+      verdict: 'pass',
+    };
+  }
+
+  return {
+    executionRef,
+    witnessRefs: [],
+    verdict: 'unknown',
+  };
+}

package/src/core/projection/files/reduce.ts

@@ -0,0 +1,50 @@
+/**
+ * src/core/projection/files/reduce.ts
+ * Pure Files Subreducer (Sprint FM-04 / INV-FM-01, INV-FM-06)
+ *
+ * Folds normalized KernelEvent and UiEvent values into the FilesProjection state.
+ * Strictly pure: zero imports from edge, membrane, ui, Node built-ins, or DOM.
+ * Contract D budget: <= 250 LOC.
+ */
+
+import type { KernelEvent, UiEvent } from '../../events';
+import type { FilesProjection } from '../state';
+
+export function reduceFiles(
+  state: FilesProjection,
+  event: KernelEvent | UiEvent
+): FilesProjection {
+  switch (event.kind) {
+    case 'MCardRead': {
+      if (!event.exists || event.content === undefined) {
+        return state;
+      }
+      const nextContent = new Map(state.contentByHash);
+      nextContent.set(event.hash, event.content);
+      return {
+        ...state,
+        contentByHash: nextContent,
+      };
+    }
+
+    case 'MCardTouched': {
+      const nextHandles = new Map(state.handles);
+      nextHandles.set(event.uri, event.hash);
+      return {
+        ...state,
+        handles: nextHandles,
+        lastTouchedUri: event.uri,
+      };
+    }
+
+    case 'FileSelected': {
+      return {
+        ...state,
+        activeHandle: event.path,
+      };
+    }
+
+    default:
+      return state;
+  }
+}

package/src/core/projection/index.ts

@@ -0,0 +1,14 @@
+/**
+ * src/core/projection/index.ts
+ * Barrel export for pure projection state model and reducers.
+ * Contract D budget: <= 250 LOC.
+ */
+
+export * from './files/reduce';
+export * from './overlay';
+export * from './processes/reduce';
+export * from './reduce';
+export * from './replay';
+export * from './selectors';
+export * from './shell/reduce';
+export * from './state';

package/src/core/projection/overlay.ts

@@ -0,0 +1,89 @@
+/**
+ * src/core/projection/overlay.ts
+ * Pending-Intent Overlay Operations (Sprint FM-04 / INV-FM-04, INV-FM-06)
+ *
+ * Implements pure overlay lifecycle:
+ *  - dispatch: adds 'pending' intent
+ *  - confirmed: removes overlay (settled)
+ *  - rejected: removes overlay (truth unchanged)
+ *  - timeout/disconnect: marks as 'unknown' until reconciled against authoritative kernel
+ *
+ * Strictly pure: zero imports from edge, membrane, ui, Node built-ins, or DOM.
+ * Contract D budget: <= 250 LOC.
+ */
+
+import type { Intent, IntentId } from '../intents/types';
+import type { PendingIntent, PendingStatus } from './state';
+
+export function addPendingIntent(
+  pending: ReadonlyMap<IntentId, PendingIntent>,
+  intent: Intent,
+  since: number = 0,
+  preview?: unknown
+): ReadonlyMap<IntentId, PendingIntent> {
+  const next = new Map(pending);
+  next.set(intent.id, {
+    intent,
+    status: 'pending',
+    preview,
+    since,
+  });
+  return next;
+}
+
+export function resolvePendingIntent(
+  pending: ReadonlyMap<IntentId, PendingIntent>,
+  intentId: IntentId
+): ReadonlyMap<IntentId, PendingIntent> {
+  if (!pending.has(intentId)) return pending;
+  const next = new Map(pending);
+  next.delete(intentId);
+  return next;
+}
+
+export function rejectPendingIntent(
+  pending: ReadonlyMap<IntentId, PendingIntent>,
+  intentId: IntentId
+): ReadonlyMap<IntentId, PendingIntent> {
+  if (!pending.has(intentId)) return pending;
+  const next = new Map(pending);
+  next.delete(intentId);
+  return next;
+}
+
+export function markPendingUnknown(
+  pending: ReadonlyMap<IntentId, PendingIntent>,
+  intentId: IntentId
+): ReadonlyMap<IntentId, PendingIntent> {
+  const current = pending.get(intentId);
+  if (!current) return pending;
+  const next = new Map(pending);
+  next.set(intentId, {
+    ...current,
+    status: 'unknown',
+  });
+  return next;
+}
+
+export function getPendingIntent(
+  pending: ReadonlyMap<IntentId, PendingIntent>,
+  intentId: IntentId
+): PendingIntent | undefined {
+  return pending.get(intentId);
+}
+
+export function isPending(
+  pending: ReadonlyMap<IntentId, PendingIntent>,
+  intentId: IntentId
+): boolean {
+  return pending.has(intentId);
+}
+
+export function hasPendingStatus(
+  pending: ReadonlyMap<IntentId, PendingIntent>,
+  intentId: IntentId,
+  status: PendingStatus
+): boolean {
+  const item = pending.get(intentId);
+  return item !== undefined && item.status === status;
+}

package/src/core/projection/processes/reduce.ts

@@ -0,0 +1,185 @@
+/**
+ * src/core/projection/processes/reduce.ts
+ * Pure Processes Subreducer (Sprint FM-08 / INV-FM-18, INV-FM-22)
+ *
+ * Folds normalized KernelEvent and UiEvent values into the ProcessProjection state.
+ * Strictly pure: zero imports from edge, membrane, ui, Node built-ins, or DOM.
+ * Contract D budget: <= 250 LOC.
+ */
+
+import type { KernelEvent, UiEvent } from '../../events';
+import type {
+  ExecutionObservation,
+  ParkedContinuationView,
+  ProcessProjection,
+  ProcessReceipt,
+  ProcessRecord,
+} from '../state';
+
+export function reduceProcesses(
+  state: ProcessProjection,
+  event: KernelEvent | UiEvent
+): ProcessProjection {
+  switch (event.kind) {
+    case 'ExecutionReceipt': {
+      const nextReceipts = new Map(state.receiptsByIntent);
+      const receipt: ProcessReceipt = {
+        receiptHash: event.receiptHash,
+        outputHash: event.outputHash,
+        witnessRefs: event.witnessRefs,
+      };
+      nextReceipts.set(event.intentId, receipt);
+
+      let nextProcesses = state.processes;
+      if (event.fiberId) {
+        const procMap = new Map(state.processes);
+        const record: ProcessRecord = {
+          status: 'completed',
+          exitCode: 0,
+        };
+        procMap.set(event.fiberId, record);
+        nextProcesses = procMap;
+      }
+
+      // Update observed execution
+      const nextExecutions = new Map(state.executions);
+      const existing = nextExecutions.get(event.intentId);
+      const observation: ExecutionObservation = {
+        intentId: event.intentId,
+        pcardRef: existing?.pcardRef || '',
+        inputRef: existing?.inputRef || '',
+        status: 'receipt',
+        receivedAt: (event as any).timestamp ?? (event as any).receivedAt ?? existing?.receivedAt,
+        receiptHash: event.receiptHash,
+        outputHash: event.outputHash,
+        witnessRefs: event.witnessRefs,
+        fiberId: event.fiberId,
+      };
+      nextExecutions.set(event.intentId, observation);
+
+      return {
+        ...state,
+        receiptsByIntent: nextReceipts,
+        processes: nextProcesses,
+        executions: nextExecutions,
+      };
+    }
+
+    case 'FiberParked': {
+      const nextParked = new Map(state.parkedTokens);
+      nextParked.set(event.token, {
+        fiberId: event.fiberId,
+        parkedAt: 0,
+      });
+
+      let nextProcesses = state.processes;
+      if (event.fiberId) {
+        const procMap = new Map(state.processes);
+        procMap.set(event.fiberId, { status: 'parked' });
+        nextProcesses = procMap;
+      }
+
+      const nextContinuations = new Map(state.continuations);
+      const continuationView: ParkedContinuationView = {
+        token: event.token,
+        prompt: (event as any).prompt,
+        turnId: (event as any).turnId,
+        expiresAt: (event as any).expiresAt,
+      };
+      nextContinuations.set(event.token, continuationView);
+
+      const nextExecutions = new Map(state.executions);
+      for (const [id, obs] of nextExecutions.entries()) {
+        if (obs.fiberId === event.fiberId || obs.status === 'submitting') {
+          nextExecutions.set(id, { ...obs, status: 'parked' });
+        }
+      }
+
+      return {
+        ...state,
+        parkedTokens: nextParked,
+        processes: nextProcesses,
+        activeFiberId: event.fiberId ?? state.activeFiberId,
+        continuations: nextContinuations,
+        executions: nextExecutions,
+      };
+    }
+
+    case 'ContinuationResumed': {
+      const nextParked = new Map(state.parkedTokens);
+      nextParked.delete(event.token);
+
+      const nextContinuations = new Map(state.continuations);
+      nextContinuations.delete(event.token);
+
+      const nextReceipts = new Map(state.receiptsByIntent);
+      if (event.receiptHash) {
+        nextReceipts.set(event.intentId, { receiptHash: event.receiptHash });
+      }
+
+      return {
+        ...state,
+        parkedTokens: nextParked,
+        receiptsByIntent: nextReceipts,
+        continuations: nextContinuations,
+      };
+    }
+
+    case 'ActionApplied': {
+      const nextReceipts = new Map(state.receiptsByIntent);
+      if (event.postHash) {
+        nextReceipts.set(event.intentId, { receiptHash: event.postHash });
+      }
+      return {
+        ...state,
+        receiptsByIntent: nextReceipts,
+      };
+    }
+
+    case 'IntentFailed': {
+      const nextExecutions = new Map(state.executions);
+      const existing = nextExecutions.get(event.intentId);
+      if (existing) {
+        nextExecutions.set(event.intentId, {
+          ...existing,
+          status: 'failed',
+          error: { code: 'FAILED', message: event.message || (event as any).reason || 'Intent failed' },
+        });
+      }
+      return {
+        ...state,
+        executions: nextExecutions,
+      };
+    }
+
+    default: {
+      // Support custom timeout / submitting extensions
+      const anyEvt = event as any;
+      if (anyEvt.kind === 'ExecutionSubmitting' && anyEvt.intentId) {
+        const nextExecutions = new Map(state.executions);
+        nextExecutions.set(anyEvt.intentId, {
+          intentId: anyEvt.intentId,
+          pcardRef: anyEvt.pcardRef || '',
+          inputRef: anyEvt.inputRef || '',
+          status: 'submitting',
+        });
+        return { ...state, executions: nextExecutions };
+      }
+
+      if (anyEvt.kind === 'ExecutionTimeout' && anyEvt.intentId) {
+        const nextExecutions = new Map(state.executions);
+        const existing = nextExecutions.get(anyEvt.intentId);
+        if (existing) {
+          nextExecutions.set(anyEvt.intentId, { ...existing, status: 'unknown' });
+        }
+        return { ...state, executions: nextExecutions };
+      }
+
+      if (anyEvt.kind === 'MarkingUpdated' && anyEvt.marking) {
+        return { ...state, marking: anyEvt.marking };
+      }
+
+      return state;
+    }
+  }
+}

package/src/core/projection/reduce.ts

@@ -0,0 +1,125 @@
+/**
+ * src/core/projection/reduce.ts
+ * Root Projection Reducer (Sprint FM-04 / INV-FM-01, INV-FM-04, INV-FM-06)
+ *
+ * Deterministic pure fold of normalized kernel events, UI events, and intent lifecycle events.
+ * Replaying the same event log produces byte-identical state (INV-FM-06).
+ * Strictly pure: zero imports from edge, membrane, ui, Node built-ins, or DOM.
+ * Contract D budget: <= 250 LOC.
+ */
+
+import type { KernelEvent, UiEvent } from '../events';
+import type { Intent, IntentId } from '../intents/types';
+import { reduceFiles } from './files/reduce';
+import {
+  addPendingIntent,
+  markPendingUnknown,
+  rejectPendingIntent,
+  resolvePendingIntent,
+} from './overlay';
+import { reduceProcesses } from './processes/reduce';
+import { reduceShell } from './shell/reduce';
+import type { StudioState } from './state';
+
+export type ProjectionEvent =
+  | KernelEvent
+  | UiEvent
+  | { readonly kind: 'IntentDispatched'; readonly intent: Intent; readonly preview?: unknown; readonly since?: number }
+  | { readonly kind: 'IntentMarkedUnknown'; readonly intentId: IntentId }
+  | { readonly kind: 'IntentReconciled'; readonly intentId: IntentId; readonly outcome: 'committed' | 'uncommitted'; readonly hash?: string; readonly uri?: string };
+
+export function reduce(state: StudioState, event: ProjectionEvent): StudioState {
+  switch (event.kind) {
+    case 'IntentDispatched': {
+      return {
+        ...state,
+        pending: addPendingIntent(
+          state.pending,
+          event.intent,
+          event.since ?? 0,
+          event.preview
+        ),
+      };
+    }
+
+    case 'IntentMarkedUnknown': {
+      return {
+        ...state,
+        pending: markPendingUnknown(state.pending, event.intentId),
+      };
+    }
+
+    case 'IntentReconciled': {
+      let nextFiles = state.files;
+      if (event.outcome === 'committed' && event.uri && event.hash) {
+        const nextHandles = new Map(state.files.handles);
+        nextHandles.set(event.uri, event.hash);
+        nextFiles = {
+          ...state.files,
+          handles: nextHandles,
+          lastTouchedUri: event.uri,
+        };
+      }
+      return {
+        ...state,
+        files: nextFiles,
+        pending: resolvePendingIntent(state.pending, event.intentId),
+      };
+    }
+
+    case 'MCardRead':
+    case 'MCardTouched':
+    case 'ExecutionReceipt':
+    case 'FiberParked':
+    case 'ContinuationResumed':
+    case 'ActionApplied':
+    case 'IntentFailed': {
+      // Settle pending overlay
+      let nextPending = state.pending;
+      if (event.kind === 'IntentFailed') {
+        nextPending = rejectPendingIntent(state.pending, event.intentId);
+      } else {
+        nextPending = resolvePendingIntent(state.pending, event.intentId);
+      }
+
+      // Fold subreducers
+      const nextFiles = reduceFiles(state.files, event);
+      const nextProcesses = reduceProcesses(state.processes, event);
+      const nextShell = reduceShell(state.shell, event);
+
+      return {
+        files: nextFiles,
+        processes: nextProcesses,
+        shell: nextShell,
+        pending: nextPending,
+      };
+    }
+
+    // UI Events (presentation-local only; never alter authoritative MCard truth)
+    case 'TabSelected':
+    case 'TabClosed':
+    case 'TabMoved':
+    case 'LayoutChanged':
+    case 'ViewletToggled':
+    case 'FileSelected':
+    case 'TreeItemToggled':
+    case 'ExplorerFilterChanged':
+    case 'HydrateUiState': {
+      const nextFiles = reduceFiles(state.files, event);
+      const nextProcesses = reduceProcesses(state.processes, event);
+      const nextShell = reduceShell(state.shell, event);
+
+      return {
+        files: nextFiles,
+        processes: nextProcesses,
+        shell: nextShell,
+        pending: state.pending,
+      };
+    }
+
+    default: {
+      const _exhaustive: never = event;
+      return state;
+    }
+  }
+}

package/src/core/projection/replay.ts

@@ -0,0 +1,93 @@
+/**
+ * src/core/projection/replay.ts
+ * Pure History Replay Engine (Sprint FM-04 / INV-FM-01, INV-FM-02)
+ *
+ * Derives presentation views purely from a verified historical timeline.
+ * Zero savepoints, zero storage mutations, zero client-side rollback (INV-FM-04).
+ * Strictly pure: zero imports from edge, membrane, ui, Node built-ins, or DOM.
+ * Contract D budget: <= 250 LOC.
+ */
+
+import { reduceFiles } from './files/reduce';
+import { type ProjectionEvent, reduce } from './reduce';
+import type { FilesProjection, StudioState } from './state';
+import { createInitialStudioState } from './state';
+
+export interface HistoricalHandleRecord {
+  readonly uri: string;
+  readonly hash: string;
+  readonly timestamp: number;
+  readonly author?: string;
+  readonly content?: string;
+}
+
+export interface ReplayTimeline {
+  readonly uri: string;
+  readonly totalCheckpoints: number;
+  readonly history: readonly HistoricalHandleRecord[];
+}
+
+/**
+ * Deterministically folds an ordered sequence of events into a new StudioState.
+ */
+export function replayEvents(
+  initialState: StudioState = createInitialStudioState(),
+  events: readonly ProjectionEvent[]
+): StudioState {
+  return events.reduce((state, event) => reduce(state, event), initialState);
+}
+
+/**
+ * Replays handle history up to targetIndex (inclusive) to derive the historical FilesProjection.
+ */
+export function replayTimelineAt(
+  timeline: ReplayTimeline,
+  targetIndex: number
+): { readonly current: HistoricalHandleRecord | null; readonly projection: FilesProjection } {
+  if (
+    !timeline.history ||
+    timeline.history.length === 0 ||
+    targetIndex < 0 ||
+    targetIndex >= timeline.history.length
+  ) {
+    return {
+      current: null,
+      projection: createInitialStudioState().files,
+    };
+  }
+
+  let files: FilesProjection = createInitialStudioState().files;
+
+  for (let i = 0; i <= targetIndex; i++) {
+    const record = timeline.history[i];
+    files = reduceFiles(files, {
+      kind: 'MCardTouched',
+      intentId: `replay-${i}`,
+      uri: record.uri,
+      hash: record.hash,
+    });
+    if (record.content !== undefined) {
+      files = reduceFiles(files, {
+        kind: 'MCardRead',
+        intentId: `replay-read-${i}`,
+        hash: record.hash,
+        exists: true,
+        content: record.content,
+      });
+    }
+  }
+
+  return {
+    current: timeline.history[targetIndex],
+    projection: files,
+  };
+}
+
+/**
+ * Validates whether history is available from the authoritative kernel source.
+ */
+export function isHistoryAvailable(
+  history: readonly unknown[] | null | undefined
+): history is readonly unknown[] {
+  return Array.isArray(history) && history.length > 0;
+}