@try-works/dsh-recursive-mode 0.1.2 → 0.1.4

package/src/snapshot.ts

@@ -0,0 +1,104 @@
+/**
+ * snapshotWorkspace(root): fold the filesystem into the RecursiveProjection whole value.
+ *
+ * SP2 R1 (live-route) — the ONLY projection path. The board/strip read this through
+ * the host HTTP/SSE route; cold resume and every GET are a FRESH fs read (the route
+ * never serves a cached/stale snapshot). Per-workspace: root is the resolved
+ * control-plane root (cwd == workspace root, cwd == subdir, or cwd == repo root).
+ *
+ * Phase-lock facts (lockedAt/lockHash) are enriched from lock receipts because
+ * foldRun PhaseState carries no lock fields; state comes from getArtifactState.
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { discoverRuns } from './run.ts'
+import { foldRun } from './status.ts'
+import { getLockStatus, receiptPath, readReceipt } from './lock.ts'
+import type { RecursiveProjection, RecursiveRunCard, RecursivePhaseRow, RecursiveRunState } from './types.ts'
+
+/** One locked-phase fact from a lock receipt (artifacts/<file>.receipt.json). */
+interface LockFacts {
+  lockedAt?: string
+  lockHash?: string
+}
+
+/** Resolve a run's lock facts for one artifact file (receipt first, status fallback). */
+function lockFactsOf(runDir: string, artifact: string): LockFacts {
+  const receipt = readReceipt(runDir, artifact)
+  if (receipt && typeof receipt.locked_at === 'string' && typeof receipt.artifact_hash === 'string') {
+    return {
+      lockedAt: receipt.locked_at,
+      lockHash: receipt.artifact_hash,
+    }
+  }
+  // No usable receipt: fall back to the artifact's own LockedAt/LockHash fields.
+  const status = getLockStatus(join(runDir, artifact))
+  if (status !== 'LOCKED') return {}
+  return {
+    lockedAt: new Date(0).toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    lockHash: '0'.repeat(64),
+  }
+}
+
+/** One phase row from a run's folded status (locked facts enriched). */
+function phaseRowOf(runDir: string, key: string, file: string, status: string): RecursivePhaseRow {
+  const row: RecursivePhaseRow = { phase: key, status }
+  if (status === 'LOCKED') {
+    const facts = lockFactsOf(runDir, file)
+    if (facts.lockedAt !== undefined) row.lockedAt = facts.lockedAt
+    if (facts.lockHash !== undefined) row.lockHash = facts.lockHash
+  }
+  return row
+}
+
+/**
+ * Fold one run directory into a RecursiveRunCard (the wire shape the board renders).
+ * Runs that no longer exist on disk are omitted (the fs is the source of truth).
+ */
+export function foldRunCard(runDir: string, runId: string, worktreeRoot: string): RecursiveRunCard {
+  const status = foldRun(runDir, runId)
+  // Wire contract parity (deleted projection.ts): phases are keyed by FILENAME
+  // (the recursive/phase event carried phase: '03-implementation-summary.md'),
+  // which is what derive.ts phaseGroupOf parses. phase.key ('03', '00R', '00W')
+  // would never match the filename regex and would break columnForRun/cardFacts.
+  const phases: Record<string, RecursivePhaseRow> = {}
+  for (const phase of status.phases) {
+    if (phase.exists) phases[phase.file] = phaseRowOf(runDir, phase.file, phase.file, phase.status)
+  }
+  const state = runStateOf(status)
+  return {
+    runId,
+    worktreeRoot,
+    phases,
+    state,
+    tampers: {},
+    subagents: {},
+  }
+}
+
+/**
+ * Derive the run-level state from the folded status. The fs stores no run-level
+ * state file, so the honest mapping is: 'complete' when every non-optional phase
+ * exists and is lock-valid, else 'active'. Transient facts (gateBlocked, tamper,
+ * subagent activity) are NOT fs-recoverable and read as absent (recorded
+ * limitation; future enhancement).
+ */
+function runStateOf(status: ReturnType<typeof foldRun>): RecursiveRunState {
+  const mandatory = status.phases.filter(p => !p.optional)
+  const complete = mandatory.every(p => p.exists && p.lockValid)
+  return complete ? 'complete' : 'active'
+}
+
+/**
+ * Fold every run under <root>/.recursive/run/ into the projection, grouped by
+ * worktree root then runId. A fresh fs read on every call (cold-resume live).
+ */
+export function snapshotWorkspace(root: string): RecursiveProjection {
+  const projection: RecursiveProjection = {}
+  for (const runId of discoverRuns(root)) {
+    const runDir = join(root, '.recursive', 'run', runId)
+    projection[root] ??= {}
+    projection[root][runId] = foldRunCard(runDir, runId, root)
+  }
+  return projection
+}

package/lib/client/node.d.ts

@@ -1,71 +0,0 @@
-/**
- * Conversation run node (Phase D R7, §11.6): a structural ConversationNodeDefinition
- * over the recursive/* event family, keyed by runId + worktreeRoot. One compact,
- * live node per run in the Chat view. PURE fold (no React) — the renderer lives
- * in slots.ts.
- *
- * The real ConversationNodeDefinition contract arrives from
- * @deepseek-ai/dsh-client-runtime/client at compose time; the structural shape
- * here is type-compatible with the cookbook surface (match/start/update/
- * buildViewNode + target/kind). The host links the bundle's exports to the real
- * runtime identities.
- */
-import type { ClientSessionEvent } from './contract.ts';
-export declare const RECURSIVE_NODE_KIND = "recursive/run";
-/** The chat-node payload the renderer receives (pure derived state). */
-export interface RecursiveNodeData {
-    readonly runId: string;
-    readonly worktreeRoot: string;
-    readonly state: string;
-    readonly currentPhase: string | null;
-    readonly lockedCount: number;
-    readonly totalPhases: number;
-    readonly tampered: boolean;
-    readonly gateBlocked: boolean;
-    readonly mergedToRepoRoot?: string;
-}
-/** Pure fold state for one run node. */
-export interface RecursiveNodeState {
-    runId: string;
-    worktreeRoot: string;
-    state: string;
-    phases: Record<string, {
-        phase: string;
-        status: string;
-    }>;
-    tampered: boolean;
-    gateBlocked: boolean;
-    mergedToRepoRoot?: string;
-}
-/** Extract a stable (runId, worktreeRoot) business id + lifecycle role from one event. */
-export declare function matchRecursiveNode(event: ClientSessionEvent): {
-    id: string;
-    role: 'start' | 'update';
-} | null;
-/** Fold one recursive/* event into the node state. */
-export declare function foldRecursiveNode(s: RecursiveNodeState | undefined, event: ClientSessionEvent): RecursiveNodeState;
-/** The structural ConversationNodeDefinition (host links to the real contract). */
-export declare const recursiveNodeDefinition: {
-    kind: string;
-    target: string;
-    match: typeof matchRecursiveNode;
-    start: (_ctx: unknown, match: {
-        event: ClientSessionEvent;
-    }) => RecursiveNodeState;
-    update: (ctx: {
-        state: RecursiveNodeState;
-    }, match: {
-        event: ClientSessionEvent;
-    }) => RecursiveNodeState;
-    buildViewNode: (ctx: {
-        key: string;
-        id: string;
-        state?: RecursiveNodeState;
-    }) => {
-        key: string;
-        kind: string;
-        id: string;
-        target: string;
-        data: RecursiveNodeData;
-    } | null;
-};

package/lib/events.d.ts

@@ -1,173 +0,0 @@
-/**
- * recursive/* session events (Phase D R1, PROPOSAL 11.2/11.6): the complete
- * durable event vocabulary the projection folds, the board renders, and the
- * conversation node correlates. Every payload carries a non-empty
- * { runId, worktreeRoot } so the whole plane is worktree-aware and the
- * projection can group runs by their control-plane root (binding
- * workspace-scoping invariant, run 03 R1).
- *
- * Events are LOG-ONLY (no live mirror): the projection unit (projection.ts)
- * is the only derived view. Payloads are plain JSON and declared on the
- * SessionEventMap merge via @deepseek-ai/dsh-session/types.
- *
- * The pure constructor helpers below enforce the runId + non-empty
- * worktreeRoot invariant at emit time, so a malformed event fails loud at
- * the emit site instead of silently landing cross-workspace.
- */
-import type { RecursiveRunState } from './types.ts';
-/** Declare the recursive/* event family on the session event map (merge-extensible). */
-declare module '@deepseek-ai/dsh-session/types' {
-    interface SessionEventMap {
-        /**
-         * A transition the lifecycle driver is ABOUT to validate/commit (logged
-         * before any file write). The pre-step gate reads this as the caller of the
-         * transition set — never a projection event (log-only internal signal).
-         */
-        'recursive/phase-intent': {
-            runId: string;
-            worktreeRoot: string;
-            targetArtifact: string;
-            kind: 'lock' | 'reopen' | 'advance';
-            evidence?: Record<string, unknown>;
-        };
-        /** A run was created/bootstrapped in this workspace. */
-        'recursive/run-created': {
-            runId: string;
-            worktreeRoot: string;
-            template?: string;
-            repo?: string;
-        };
-        /** A phase transition committed (validate -> commit -> flush -> emit). */
-        'recursive/phase': {
-            runId: string;
-            worktreeRoot: string;
-            phase: string;
-            status: string;
-        };
-        /** A phase artifact was locked (lock hash + timestamp recorded). */
-        'recursive/phase-locked': {
-            runId: string;
-            worktreeRoot: string;
-            phase: string;
-            lockedAt: string;
-            lockHash: string;
-        };
-        /** A transition's gate predicate failed (rejected in strict, warned in advisory). */
-        'recursive/gate-blocked': {
-            runId: string;
-            worktreeRoot: string;
-            phase: string;
-            failures: string[];
-            kind: string;
-        };
-        /** fs/observed detected a change to a locked artifact outside a tool call. */
-        'recursive/tamper': {
-            runId: string;
-            worktreeRoot: string;
-            path: string;
-            reason: string;
-        };
-        /** A run was merged back to the repo root (conversation history re-keys). */
-        'recursive/run-merged': {
-            runId: string;
-            worktreeRoot: string;
-            repoRoot: string;
-        };
-        /** Run-level lifecycle flag (active/paused/blocked/complete + reason). */
-        'recursive/run-state': {
-            runId: string;
-            worktreeRoot: string;
-            state: RecursiveRunState;
-            reason?: string;
-        };
-        /** A subagent started for this run. */
-        'recursive/subagent-start': {
-            runId: string;
-            worktreeRoot: string;
-            childId: string;
-            role: string;
-            provider: string;
-        };
-        /** A subagent finished for this run. */
-        'recursive/subagent-end': {
-            runId: string;
-            worktreeRoot: string;
-            childId: string;
-            role: string;
-            provider: string;
-            status: 'running' | 'done' | 'failed';
-        };
-    }
-}
-/** Enforce the runId + non-empty worktreeRoot invariant at emit time. */
-export declare function requireRunKey(runId: string, worktreeRoot: string): void;
-export interface PhaseIntentInput {
-    runId: string;
-    worktreeRoot: string;
-    targetArtifact: string;
-    kind: 'lock' | 'reopen' | 'advance';
-    evidence?: Record<string, unknown>;
-}
-export interface RunCreatedInput {
-    runId: string;
-    worktreeRoot: string;
-    template?: string;
-    repo?: string;
-}
-export interface PhaseInput {
-    runId: string;
-    worktreeRoot: string;
-    phase: string;
-    status: string;
-}
-export interface PhaseLockedInput {
-    runId: string;
-    worktreeRoot: string;
-    phase: string;
-    lockedAt: string;
-    lockHash: string;
-}
-export interface GateBlockedInput {
-    runId: string;
-    worktreeRoot: string;
-    phase: string;
-    failures: string[];
-    kind: string;
-}
-export interface TamperInput {
-    runId: string;
-    worktreeRoot: string;
-    path: string;
-    reason: string;
-}
-export interface RunMergedInput {
-    runId: string;
-    worktreeRoot: string;
-    repoRoot: string;
-}
-export interface RunStateInput {
-    runId: string;
-    worktreeRoot: string;
-    state: RecursiveRunState;
-    reason?: string;
-}
-export interface SubagentInput {
-    runId: string;
-    worktreeRoot: string;
-    childId: string;
-    role: string;
-    provider: string;
-}
-export interface SubagentEndInput extends SubagentInput {
-    status: 'running' | 'done' | 'failed';
-}
-export declare function phaseIntent(data: PhaseIntentInput): PhaseIntentInput;
-export declare function runCreated(data: RunCreatedInput): RunCreatedInput;
-export declare function phase(data: PhaseInput): PhaseInput;
-export declare function phaseLocked(data: PhaseLockedInput): PhaseLockedInput;
-export declare function gateBlocked(data: GateBlockedInput): GateBlockedInput;
-export declare function tamper(data: TamperInput): TamperInput;
-export declare function runMerged(data: RunMergedInput): RunMergedInput;
-export declare function runState(data: RunStateInput): RunStateInput;
-export declare function subagentStart(data: SubagentInput): SubagentInput;
-export declare function subagentEnd(data: SubagentEndInput): SubagentEndInput;

package/lib/projection.d.ts

@@ -1,29 +0,0 @@
-import type { ZodType } from 'zod';
-import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
-import type { RecursiveProjection } from './types.ts';
-/** Declare the 'recursive' projection key on the shared type table. */
-declare module '@deepseek-ai/dsh-session-projection/types' {
-    interface SessionProjectionMap {
-        /** Runs grouped by worktree root, then runId. */
-        recursive: RecursiveProjection;
-    }
-}
-/** Structural event shape the pure fold reads (unit-testable without a session). */
-export interface RecursiveEventLike {
-    type: string;
-    data?: Record<string, unknown>;
-}
-/** Mutable fold accumulator (private to the pure fold; never leaks). */
-export interface RecursiveFoldState {
-    /** The workspace control-plane root this unit is scoped to ('' = accept all). */
-    workspaceRoot: string;
-    /** Runs grouped by worktree root then runId. */
-    byWorktree: RecursiveProjection;
-}
-export declare function emptyRecursiveFoldState(workspaceRoot?: string): RecursiveFoldState;
-/** Whether a worktreeRoot is inside (or equal to) the workspace root. */
-export declare function isInsideWorkspace(worktreeRoot: string, workspaceRoot: string): boolean;
-export declare function foldRecursiveProjection(state: RecursiveFoldState, event: RecursiveEventLike): RecursiveFoldState;
-export declare const recursiveProjectionSchema: ZodType<RecursiveProjection>;
-/** The registered projection unit (key 'recursive'). */
-export declare const recursiveProjectionUnit: ProjectionDefinition<'recursive', RecursiveFoldState>;

package/src/client/node.ts

@@ -1,156 +0,0 @@
-/**
- * Conversation run node (Phase D R7, §11.6): a structural ConversationNodeDefinition
- * over the recursive/* event family, keyed by runId + worktreeRoot. One compact,
- * live node per run in the Chat view. PURE fold (no React) — the renderer lives
- * in slots.ts.
- *
- * The real ConversationNodeDefinition contract arrives from
- * @deepseek-ai/dsh-client-runtime/client at compose time; the structural shape
- * here is type-compatible with the cookbook surface (match/start/update/
- * buildViewNode + target/kind). The host links the bundle's exports to the real
- * runtime identities.
- */
-import type { ClientSessionEvent } from './contract.ts'
-import type { RecursiveRunCard } from '../types.ts'
-
-export const RECURSIVE_NODE_KIND = 'recursive/run'
-
-/** The chat-node payload the renderer receives (pure derived state). */
-export interface RecursiveNodeData {
-  readonly runId: string
-  readonly worktreeRoot: string
-  readonly state: string
-  readonly currentPhase: string | null
-  readonly lockedCount: number
-  readonly totalPhases: number
-  readonly tampered: boolean
-  readonly gateBlocked: boolean
-  readonly mergedToRepoRoot?: string
-}
-
-/** Pure fold state for one run node. */
-export interface RecursiveNodeState {
-  runId: string
-  worktreeRoot: string
-  state: string
-  phases: Record<string, { phase: string; status: string }>
-  tampered: boolean
-  gateBlocked: boolean
-  mergedToRepoRoot?: string
-}
-
-const GROUP_ORDER: readonly string[] = ['00', '01', '01.5', '02', '03', '03.5', '04', '05', '06', '07', '08']
-const GROUP_INDEX = new Map(GROUP_ORDER.map((g, i) => [g, i]))
-
-function phaseGroupOf(phase: string): string | null {
-  const m = /^(\d{2}(?:\.\d)?)(?:-|$)/.exec(phase)
-  return m ? m[1] : null
-}
-
-function currentPhaseOf(phases: Record<string, { phase: string; status: string }>): string | null {
-  let best: string | null = null
-  let bestIdx = -1
-  for (const key of Object.keys(phases)) {
-    const g = phaseGroupOf(key)
-    if (g === null) continue
-    const idx = GROUP_INDEX.get(g) ?? -1
-    if (idx > bestIdx) { bestIdx = idx; best = key }
-  }
-  return best
-}
-
-function nodeDataOf(s: RecursiveNodeState): RecursiveNodeData {
-  const lockedCount = Object.values(s.phases).filter(p => p.status === 'LOCKED').length
-  return {
-    runId: s.runId,
-    worktreeRoot: s.worktreeRoot,
-    state: s.state,
-    currentPhase: currentPhaseOf(s.phases),
-    lockedCount,
-    totalPhases: Object.keys(s.phases).length,
-    tampered: s.tampered,
-    gateBlocked: s.gateBlocked,
-    ...(s.mergedToRepoRoot === undefined ? {} : { mergedToRepoRoot: s.mergedToRepoRoot }),
-  }
-}
-
-/** Extract a stable (runId, worktreeRoot) business id + lifecycle role from one event. */
-export function matchRecursiveNode(event: ClientSessionEvent): { id: string; role: 'start' | 'update' } | null {
-  if (typeof event.type !== 'string' || !event.type.startsWith('recursive/')) return null
-  const data = event.data ?? {}
-  const runId = typeof data.runId === 'string' ? data.runId : ''
-  const worktreeRoot = typeof data.worktreeRoot === 'string' ? data.worktreeRoot : ''
-  if (runId === '' || worktreeRoot === '') return null
-  return { id: worktreeRoot + '\u0000' + runId, role: event.type === 'recursive/run-created' ? 'start' : 'update' }
-}
-
-/** Fold one recursive/* event into the node state. */
-export function foldRecursiveNode(s: RecursiveNodeState | undefined, event: ClientSessionEvent): RecursiveNodeState {
-  const data = event.data ?? {}
-  const runId = typeof data.runId === 'string' ? data.runId : ''
-  const worktreeRoot = typeof data.worktreeRoot === 'string' ? data.worktreeRoot : ''
-  const base: RecursiveNodeState = s ?? {
-    runId,
-    worktreeRoot,
-    state: 'active',
-    phases: {},
-    tampered: false,
-    gateBlocked: false,
-  }
-
-  switch (event.type) {
-    case 'recursive/run-created':
-      base.runId = runId
-      base.worktreeRoot = worktreeRoot
-      return base
-    case 'recursive/phase': {
-      const phase = String(data.phase ?? '')
-      if (phase !== '') base.phases[phase] = { phase, status: String(data.status ?? '') }
-      return base
-    }
-    case 'recursive/phase-locked': {
-      const phase = String(data.phase ?? '')
-      if (phase !== '') base.phases[phase] = { phase, status: 'LOCKED' }
-      return base
-    }
-    case 'recursive/gate-blocked':
-      base.gateBlocked = true
-      return base
-    case 'recursive/tamper':
-      base.tampered = true
-      return base
-    case 'recursive/run-state':
-      base.state = typeof data.state === 'string' ? data.state : base.state
-      return base
-    case 'recursive/run-merged': {
-      const repoRoot = typeof data.repoRoot === 'string' ? data.repoRoot : ''
-      if (repoRoot !== '') {
-        base.mergedToRepoRoot = repoRoot
-        base.worktreeRoot = repoRoot
-      }
-      return base
-    }
-    default:
-      return base
-  }
-}
-
-/** The structural ConversationNodeDefinition (host links to the real contract). */
-export const recursiveNodeDefinition = {
-  kind: RECURSIVE_NODE_KIND,
-  target: 'chat',
-  match: matchRecursiveNode,
-  start: (_ctx: unknown, match: { event: ClientSessionEvent }): RecursiveNodeState => foldRecursiveNode(undefined, match.event),
-  update: (ctx: { state: RecursiveNodeState }, match: { event: ClientSessionEvent }): RecursiveNodeState => foldRecursiveNode(ctx.state, match.event),
-  buildViewNode: (ctx: { key: string; id: string; state?: RecursiveNodeState }) => {
-    const state = ctx.state
-    if (state === undefined) return null
-    return {
-      key: ctx.key,
-      kind: RECURSIVE_NODE_KIND,
-      id: ctx.id,
-      target: 'chat',
-      data: nodeDataOf(state),
-    }
-  },
-}