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

package/src/events.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 function requireRunKey(runId: string, worktreeRoot: string): void {
-  if (typeof runId !== 'string' || runId.trim() === '') {
-    throw new Error('recursive event requires a non-empty runId')
-  }
-  if (typeof worktreeRoot !== 'string' || worktreeRoot.trim() === '') {
-    throw new Error('recursive event requires a non-empty worktreeRoot')
-  }
-}
-
-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 function phaseIntent(data: PhaseIntentInput): PhaseIntentInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, targetArtifact: data.targetArtifact, kind: data.kind, ...(data.evidence === undefined ? {} : { evidence: data.evidence }) }
-}
-
-export function runCreated(data: RunCreatedInput): RunCreatedInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, ...(data.template === undefined ? {} : { template: data.template }), ...(data.repo === undefined ? {} : { repo: data.repo }) }
-}
-
-export function phase(data: PhaseInput): PhaseInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, phase: data.phase, status: data.status }
-}
-
-export function phaseLocked(data: PhaseLockedInput): PhaseLockedInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, phase: data.phase, lockedAt: data.lockedAt, lockHash: data.lockHash }
-}
-
-export function gateBlocked(data: GateBlockedInput): GateBlockedInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, phase: data.phase, failures: data.failures, kind: data.kind }
-}
-
-export function tamper(data: TamperInput): TamperInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, path: data.path, reason: data.reason }
-}
-
-export function runMerged(data: RunMergedInput): RunMergedInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, repoRoot: data.repoRoot }
-}
-
-export function runState(data: RunStateInput): RunStateInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, state: data.state, ...(data.reason === undefined ? {} : { reason: data.reason }) }
-}
-
-export function subagentStart(data: SubagentInput): SubagentInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, childId: data.childId, role: data.role, provider: data.provider }
-}
-
-export function subagentEnd(data: SubagentEndInput): SubagentEndInput {
-  requireRunKey(data.runId, data.worktreeRoot)
-  return { runId: data.runId, worktreeRoot: data.worktreeRoot, childId: data.childId, role: data.role, provider: data.provider, status: data.status }
-}

package/src/projection.ts

@@ -1,237 +0,0 @@
-/**
- * recursive session projection unit (Phase D R2/R9, PROPOSAL 11.2/11.4): the
- * pure fold that maps SessionEvent[] -> per-run wire-JSON, grouped by
- * worktree root first then runId. The board, inspector, node, and strip all
- * render from this whole value; the client NEVER scrapes /.recursive/run/.
- *
- * The unit is three pure synchronous functions (init/apply/view) plus a zod
- * schema + stateVersion (the session-projection ProjectionDefinition
- * contract). apply returns the same state reference for unrelated events
- * (Object.is zero-work rule), so non-recursive sessions cost nothing.
- *
- * Worktree scoping (binding invariant, run 03 R1): the fold only commits a
- * recursive/* event whose worktreeRoot is INSIDE the workspace control-plane
- * root captured at registration; out-of-workspace events are dropped.
- *
- * The core fold is structural (RecursiveEventLike) so it is unit-testable
- * without a live session; the ProjectionDefinition adapts the framework's
- * SessionEvent to it.
- */
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { z as zod } from 'zod'
-import type { ZodType } from 'zod'
-import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
-import type { RecursiveProjection, RecursiveRunCard, RecursiveRunState, RecursivePhaseRow, RecursiveGateBlock, RecursiveTamper, RecursiveSubagent } 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 function emptyRecursiveFoldState(workspaceRoot = ''): RecursiveFoldState {
-  // B6: the unit itself has no session/agent to learn the workspace root from —
-  // init() is synchronous and receives no context. The EMITTERS are the scope
-  // authority: they resolve the control-plane root per-call and never append a
-  // cross-workspace event. workspaceRoot = '' (accept-all) is therefore a
-  // per-session safety default, not a no-op: (a) each session's projection cell
-  // is its own workspace (the log belongs to one agent), and (b) the re-key
-  // guard still refuses a merge whose repoRoot falls outside the captured
-  // root. A host that registers a session-scoped root may still pass it; the
-  // default is the per-session invariant, not a cross-workspace hole.
-  return { workspaceRoot, byWorktree: {} }
-}
-
-/** Whether a worktreeRoot is inside (or equal to) the workspace root. */
-export function isInsideWorkspace(worktreeRoot: string, workspaceRoot: string): boolean {
-  if (workspaceRoot === '') return true
-  const w = worktreeRoot.replace(/\\/g, '/').replace(/\/$/, '')
-  const r = workspaceRoot.replace(/\\/g, '/').replace(/\/$/, '')
-  return w === r || w.startsWith(r + '/')
-}
-
-function ensureCard(state: RecursiveFoldState, runId: string, worktreeRoot: string): RecursiveRunCard {
-  let tree = state.byWorktree[worktreeRoot]
-  if (tree === undefined) {
-    tree = {}
-    state.byWorktree[worktreeRoot] = tree
-  }
-  let card = tree[runId]
-  if (card === undefined) {
-    card = { runId, worktreeRoot, phases: {}, state: 'active', tampers: {}, subagents: {} }
-    tree[runId] = card
-  }
-  return card
-}
-
-function asRunState(value: unknown): RecursiveRunState {
-  return value === 'new' || value === 'active' || value === 'paused' || value === 'blocked' || value === 'complete'
-    ? value as RecursiveRunState
-    : 'active'
-}
-
-/** Pure transition: previous state + one committed event -> next state. */
-/** Internal transition signals (never commit into the projection). */
-const INTERNAL_RECURSIVE_EVENTS = new Set(['recursive/phase-intent'])
-
-export function foldRecursiveProjection(state: RecursiveFoldState, event: RecursiveEventLike): RecursiveFoldState {
-  const type = event.type
-  if (typeof type !== 'string' || !type.startsWith('recursive/')) return state
-  if (INTERNAL_RECURSIVE_EVENTS.has(type)) return state
-  const data = event.data ?? {}
-  const runId = typeof data.runId === 'string' ? data.runId : ''
-  const worktreeRoot = typeof data.worktreeRoot === 'string' ? data.worktreeRoot : ''
-  if (runId === '' || worktreeRoot === '') return state
-  // Binding workspace-scoping invariant: drop out-of-workspace events.
-  if (!isInsideWorkspace(worktreeRoot, state.workspaceRoot)) return state
-
-  const card = ensureCard(state, runId, worktreeRoot)
-
-  switch (type) {
-    case 'recursive/run-created': {
-      if (typeof data.template === 'string') card.template = data.template
-      if (typeof data.repo === 'string') card.repo = data.repo
-      return state
-    }
-    case 'recursive/phase': {
-      const phase = String(data.phase ?? '')
-      if (phase === '') return state
-      const row: RecursivePhaseRow = card.phases[phase] ?? { phase, status: String(data.status ?? '') }
-      row.status = String(data.status ?? '')
-      card.phases[phase] = row
-      return state
-    }
-    case 'recursive/phase-locked': {
-      const phase = String(data.phase ?? '')
-      if (phase === '') return state
-      const row: RecursivePhaseRow = card.phases[phase] ?? { phase, status: 'LOCKED' }
-      row.status = 'LOCKED'
-      row.lockedAt = String(data.lockedAt ?? '')
-      row.lockHash = String(data.lockHash ?? '')
-      card.phases[phase] = row
-      return state
-    }
-    case 'recursive/gate-blocked': {
-      const gate: RecursiveGateBlock = {
-        failures: Array.isArray(data.failures) ? data.failures.map(String) : [],
-        kind: String(data.kind ?? ''),
-      }
-      card.gateBlocked = gate
-      return state
-    }
-    case 'recursive/tamper': {
-      const path = String(data.path ?? '')
-      if (path === '') return state
-      const t: RecursiveTamper = { path, reason: String(data.reason ?? '') }
-      card.tampers[path] = t
-      return state
-    }
-    case 'recursive/run-merged': {
-      const repoRoot = typeof data.repoRoot === 'string' ? data.repoRoot : ''
-      if (repoRoot === '') return state
-      // R9: a merged run is listed under the repo root, not the stale worktree
-      // path. Re-key by moving the card across the outer group — but only when
-      // the repo root itself is inside the workspace (binding invariant);
-      // otherwise the merge note is recorded without crossing scope.
-      card.mergedToRepoRoot = repoRoot
-      if (isInsideWorkspace(repoRoot, state.workspaceRoot)) {
-        const tree = state.byWorktree[worktreeRoot]
-        if (tree !== undefined && tree[runId] === card) {
-          delete tree[runId]
-          if (Object.keys(tree).length === 0) delete state.byWorktree[worktreeRoot]
-        }
-        const target = state.byWorktree[repoRoot] ?? (state.byWorktree[repoRoot] = {})
-        target[runId] = card
-        // The card's own worktreeRoot now reflects the merge target.
-        card.worktreeRoot = repoRoot
-      }
-      return state
-    }
-    case 'recursive/run-state': {
-      card.state = asRunState(data.state)
-      if (typeof data.reason === 'string') card.stateReason = data.reason
-      return state
-    }
-    case 'recursive/subagent-start':
-    case 'recursive/subagent-end': {
-      const childId = String(data.childId ?? '')
-      if (childId === '') return state
-      const sub: RecursiveSubagent = card.subagents[childId] ?? {
-        childId,
-        role: String(data.role ?? ''),
-        provider: String(data.provider ?? ''),
-      }
-      sub.role = String(data.role ?? sub.role)
-      sub.provider = String(data.provider ?? sub.provider)
-      if (type === 'recursive/subagent-end') {
-        sub.status = (data.status === 'running' || data.status === 'done' || data.status === 'failed')
-          ? data.status as 'running' | 'done' | 'failed'
-          : 'done'
-      }
-      card.subagents[childId] = sub
-      return state
-    }
-    default:
-      return state
-  }
-}
-
-/** Wire-payload schema (view output) — plain-JSON validation before it leaves the host. */
-const recursivePhaseRowSchema = zod.object({
-  phase: zod.string(),
-  status: zod.string(),
-  lockedAt: zod.string().optional(),
-  lockHash: zod.string().optional(),
-})
-
-const recursiveSubagentSchema = zod.object({
-  childId: zod.string(),
-  role: zod.string(),
-  provider: zod.string(),
-  status: zod.enum(['running', 'done', 'failed']).optional(),
-})
-
-const recursiveRunCardSchema = zod.object({
-  runId: zod.string(),
-  worktreeRoot: zod.string(),
-  repo: zod.string().optional(),
-  template: zod.string().optional(),
-  phases: zod.record(zod.string(), recursivePhaseRowSchema),
-  state: zod.enum(['new', 'active', 'paused', 'blocked', 'complete']),
-  stateReason: zod.string().optional(),
-  gateBlocked: zod.object({ failures: zod.array(zod.string()), kind: zod.string() }).optional(),
-  tampers: zod.record(zod.string(), zod.object({ path: zod.string(), reason: zod.string() })),
-  subagents: zod.record(zod.string(), recursiveSubagentSchema),
-  mergedToRepoRoot: zod.string().optional(),
-})
-
-export const recursiveProjectionSchema: ZodType<RecursiveProjection> = zod.record(
-  zod.string(),
-  zod.record(zod.string(), recursiveRunCardSchema),
-)
-
-/** The registered projection unit (key 'recursive'). */
-export const recursiveProjectionUnit: ProjectionDefinition<'recursive', RecursiveFoldState> = {
-  key: 'recursive',
-  schema: recursiveProjectionSchema,
-  init: () => emptyRecursiveFoldState(),
-  apply: (state, event: SessionEvent) => foldRecursiveProjection(state, event as RecursiveEventLike),
-  view: (state) => state.byWorktree,
-  stateVersion: 1,
-}