@hegemonart/get-design-done 1.31.0 → 1.32.0

package/scripts/lib/event-stream/index.ts

@@ -1,197 +1,29 @@
-// scripts/lib/event-stream/index.ts — public API for the Phase 20+
-// telemetry stream (Plan 20-06, SDK-08).
+// scripts/lib/event-stream/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Consumers import ONLY from this file. The internal parts
-// (`./types.ts`, `./writer.ts`, `./emitter.ts`) are implementation
-// detail; changing them without updating this export surface is a
-// breaking change for downstream plans (20-05 MCP handlers, 20-13 hooks).
+// Thin deprecation shim. The real implementation moved to
+// sdk/event-stream/index.ts in Plan 31-5-04 (SDK consolidation). This file
+// is re-created at the OLD path so undocumented EXTERNAL importers (anyone
+// who reached into node_modules/@hegemonart/get-design-done/scripts/lib/
+// event-stream/index.ts directly) keep working for one minor grace window.
 //
-// Surface:
-//   * appendEvent(ev)          — persist + broadcast one event
-//   * getWriter(opts?)         — lazy singleton EventWriter
-//   * getBus()                 — lazy singleton EventBus
-//   * reset()                  — clear module-level singletons (tests)
-//   * types                    — BaseEvent, KnownEvent, and every pre-
-//                                registered subtype (StateMutationEvent,
-//                                StateTransitionEvent, …).
-
-import { hostname } from 'node:os';
-
-import { EventBus } from './emitter.ts';
-import type { Unsubscribe, EventHandler } from './emitter.ts';
-import { EventWriter } from './writer.ts';
-import type { WriterOptions } from './writer.ts';
-import type { BaseEvent, EventMeta } from './types.ts';
-
-export type {
-  BaseEvent,
-  EventMeta,
-  KnownEvent,
-  StateMutationEvent,
-  StateTransitionEvent,
-  StageEnteredEvent,
-  StageExitedEvent,
-  HookFiredEvent,
-  ErrorEvent,
-  WaveStartedEvent,
-  WaveCompletedEvent,
-  BlockerAddedEvent,
-  DecisionAddedEvent,
-  MustHaveAddedEvent,
-  ParallelismVerdictEvent,
-  CostUpdateEvent,
-  RateLimitEvent,
-  ApiRetryEvent,
-  CompactBoundaryEvent,
-  McpProbeEvent,
-  ReflectionProposedEvent,
-  ConnectionStatusChangeEvent,
-  ToolCallStartedEvent,
-  ToolCallCompletedEvent,
-  AgentSpawnEvent,
-  AgentOutcomeEvent,
-  // Phase 27 / Plan 27-08 — peer-CLI delegation events (D-09).
-  RuntimeRole,
-  PeerCallStartedEvent,
-  PeerCallCompleteEvent,
-  PeerCallFailedEvent,
-} from './types.ts';
-export {
-  KNOWN_EVENT_TYPES,
-  // Phase 27 / Plan 27-08 — symbolic constants for peer-CLI event names.
-  PEER_CALL_STARTED,
-  PEER_CALL_COMPLETE,
-  PEER_CALL_FAILED,
-  PEER_CALL_EVENT_TYPES,
-  DEFAULT_RUNTIME_ROLE,
-} from './types.ts';
-export { EventBus } from './emitter.ts';
-export type { EventHandler, Unsubscribe } from './emitter.ts';
-export { EventWriter, DEFAULT_EVENTS_PATH, DEFAULT_MAX_LINE_BYTES } from './writer.ts';
-export type { WriterOptions } from './writer.ts';
-export { readEvents, aggregate } from './reader.ts';
-export type { ReadEventsOptions, AggregateResult } from './reader.ts';
-
-/**
- * Lazily-constructed module-level singletons. `getWriter()` honors the
- * first `opts` it receives; subsequent calls with different options are
- * ignored. Tests that need to vary options across runs should call
- * {@link reset} between runs.
- */
-let defaultWriter: EventWriter | null = null;
-let defaultBus: EventBus | null = null;
-/**
- * Cached host name. `os.hostname()` is cheap but not free (syscall on
- * some platforms) and we stamp it onto every event; compute once.
- */
-let cachedHost: string | null = null;
-
-/**
- * Return the module-level default writer, constructing it on first
- * call. Passing `opts` on subsequent calls is a no-op (the first
- * caller wins); that matches the "single shared file per process"
- * intent.
- */
-export function getWriter(opts?: WriterOptions): EventWriter {
-  if (defaultWriter === null) {
-    // Honor GDD_EVENTS_PATH env var as the first-choice default path
-    // when the caller doesn't pass an explicit `opts.path`. Lets test
-    // harnesses and Plan 21-11's E2E subprocess steer the on-disk
-    // stream into a fixture-specific directory without chdir'ing the
-    // entire process. Explicit `opts.path` always wins.
-    const envPath: string | undefined = process.env['GDD_EVENTS_PATH'];
-    const finalOpts: WriterOptions =
-      opts?.path === undefined && envPath !== undefined && envPath.length > 0
-        ? { ...(opts ?? {}), path: envPath }
-        : (opts ?? {});
-    defaultWriter = new EventWriter(finalOpts);
-  }
-  return defaultWriter;
-}
-
-/** Return the module-level default bus, constructing it on first call. */
-export function getBus(): EventBus {
-  if (defaultBus === null) {
-    defaultBus = new EventBus();
-  }
-  return defaultBus;
-}
-
-/**
- * Persist `ev` to the on-disk JSONL stream AND broadcast it to the
- * in-process bus. This is the normal emission path for every Phase 20+
- * event producer.
- *
- * Ordering:
- *   1. Stamp `_meta` (pid/host/source) if the caller didn't supply it.
- *   2. Persist via `getWriter().append(ev)` — sync, never throws.
- *   3. Broadcast via `getBus().emit(ev.type, ev)` AND `emit('*', ev)`
- *      so typed subscribers and `subscribeAll` observers both see it.
- *
- * Bus emission can still throw if a subscriber handler throws; we
- * intentionally surface that rather than silently swallowing, since a
- * failing handler is a programming bug, not an expected runtime
- * condition. Plan 20-13's hooks wrap their handler bodies defensively
- * for this reason.
- */
-export function appendEvent(ev: BaseEvent): void {
-  // Stamp writer-injected metadata if absent. We don't clone the full
-  // event — callers typically build it fresh per emission — but we do
-  // need to ensure `_meta` is present by the time we persist.
-  if (ev._meta === undefined) {
-    if (cachedHost === null) {
-      try {
-        cachedHost = hostname();
-      } catch {
-        cachedHost = 'unknown';
-      }
-    }
-    const meta: EventMeta = {
-      pid: process.pid,
-      host: cachedHost,
-      source: 'event-stream',
-    };
-    ev._meta = meta;
-  }
-
-  // Persist first. Bus emission is synchronous; if a subscriber throws
-  // after we've persisted, the durable record is already safe.
-  getWriter().append(ev);
-
-  const bus = getBus();
-  bus.emit(ev.type, ev);
-  bus.emit('*', ev);
-}
-
-/**
- * Reset module-level singletons. Intended for tests that want a fresh
- * writer (e.g. pointed at a new temp directory) or a fresh bus (e.g.
- * to assert isolation between test cases).
- *
- * Safe to call from production code but the intended caller is a test.
- * `appendEvent()` will lazily reconstruct both singletons on the next
- * emission.
- */
-export function reset(): void {
-  if (defaultBus !== null) {
-    defaultBus.removeAllListeners();
-  }
-  defaultWriter = null;
-  defaultBus = null;
-}
-
-// Re-export `subscribe`/`subscribeAll` convenience: some callers only
-// need to subscribe, not emit, and `getBus().subscribe(…)` reads fine
-// but the shorter form keeps consumer code terse.
-/** Convenience: subscribe to one event type on the default bus. */
-export function subscribe<T extends BaseEvent = BaseEvent>(
-  type: T['type'],
-  handler: EventHandler<T>,
-): Unsubscribe {
-  return getBus().subscribe<T>(type, handler);
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
+//
+// Runs under --experimental-strip-types, so `export *` re-export is
+// strip-types-clean.
+
+import { emitWarning } from 'node:process';
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/lib/event-stream/index.ts is deprecated; import sdk/event-stream instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-/** Convenience: subscribe to every event on the default bus. */
-export function subscribeAll(handler: EventHandler<BaseEvent>): Unsubscribe {
-  return getBus().subscribeAll(handler);
-}
+export * from '../../../sdk/event-stream/index.ts';

package/scripts/lib/gdd-errors/index.ts

@@ -1,218 +1,29 @@
-// scripts/lib/gdd-errors/index.ts — unified GDD error taxonomy.
+// scripts/lib/gdd-errors/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Three classes exactly — mirrors the GSD errors.ts discipline:
+// Thin deprecation shim. The real implementation moved to sdk/errors/index.ts
+// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
+// path so undocumented EXTERNAL importers (anyone who reached into
+// node_modules/@hegemonart/get-design-done/scripts/lib/gdd-errors/index.ts
+// directly) keep working for one minor grace window.
 //
-//   * ValidationError       — throw at boundary; "fix your input"
-//   * StateConflictError    — throw; lockfile contention or transition guard
-//                             failed; retryable by upstream
-//   * OperationFailedError  — return in data.error; "couldn't complete in
-//                             this state"; expected failure mode the caller
-//                             should branch on, not crash on
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
 //
-// MCP tool handlers place OperationFailedError instances into data.error
-// so the model can see and reason about them. ValidationError and
-// StateConflictError are thrown (non-zero exit path).
-//
-// Plan 20-01 introduced LockAcquisitionError and TransitionGateFailed as
-// local Error subclasses; this module re-exports taxonomy-compliant
-// versions so the existing `gdd-state` surface (tests + consumers) keeps
-// working unchanged. Plan 20-05 wires `toToolError` into MCP tool
-// handlers; Plan 20-06 emits error events to the telemetry stream.
-
-/** Short machine-readable code. Example: "VALIDATION_MISSING_FIELD". */
-export type GDDErrorCode = string;
-
-/**
- * Abstract base class — every GDD taxonomy error inherits from this.
- *
- * Subclasses set a literal `kind` discriminant so `classify()` can
- * branch on it without `instanceof` chains, and `toJSON()` produces a
- * lossless payload for tool-result transport.
- */
-export abstract class GDDError extends Error {
-  abstract readonly kind: 'validation' | 'state_conflict' | 'operation_failed';
-  readonly code: GDDErrorCode;
-  readonly context: Readonly<Record<string, unknown>>;
-
-  constructor(
-    message: string,
-    code: GDDErrorCode,
-    context: Record<string, unknown> = {},
-  ) {
-    super(message);
-    this.code = code;
-    this.context = Object.freeze({ ...context });
-    // Set .name to the concrete subclass name (LockAcquisitionError,
-    // ValidationError, etc.) so error serialization is human-meaningful.
-    this.name = new.target.name;
-  }
-
-  /**
-   * Serialize to a plain object safe for JSON.stringify. Round-trips
-   * through JSON without loss of `name`, `kind`, `code`, `message`, or
-   * `context`. Does NOT include the stack trace — MCP tool handlers do
-   * not forward stacks to the model.
-   */
-  toJSON(): {
-    name: string;
-    kind: GDDError['kind'];
-    code: GDDErrorCode;
-    message: string;
-    context: Readonly<Record<string, unknown>>;
-  } {
-    return {
-      name: this.name,
-      kind: this.kind,
-      code: this.code,
-      message: this.message,
-      context: this.context,
-    };
-  }
-}
-
-/**
- * Throw at boundary when the caller's input is malformed.
- *
- * Example: MCP tool handler receives an argument that fails schema
- * validation; the correct response is `throw new ValidationError(...)`
- * so the harness catches it and returns a structured error to the model.
- * The model should fix its input and retry.
- */
-export class ValidationError extends GDDError {
-  readonly kind = 'validation' as const;
-  constructor(
-    message: string,
-    code: GDDErrorCode = 'VALIDATION',
-    context?: Record<string, unknown>,
-  ) {
-    super(message, code, context);
-  }
-}
-
-/**
- * Throw when a concurrency primitive or transition guard vetoes the
- * operation. Retryable by upstream — the caller may try again after a
- * backoff, or surface the blocker to the operator.
- *
- * Examples: lockfile contention (LockAcquisitionError), transition
- * gate failure (TransitionGateFailed).
- */
-export class StateConflictError extends GDDError {
-  readonly kind = 'state_conflict' as const;
-  constructor(
-    message: string,
-    code: GDDErrorCode = 'STATE_CONFLICT',
-    context?: Record<string, unknown>,
-  ) {
-    super(message, code, context);
-  }
+// Runs under --experimental-strip-types, so `export *` re-export is
+// strip-types-clean.
+
+import { emitWarning } from 'node:process';
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/lib/gdd-errors/index.ts is deprecated; import sdk/errors instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-/**
- * Return as `data.error` — do NOT throw. This is the expected failure
- * mode the caller should branch on: the operation is well-formed, the
- * state is valid, but the specific request cannot complete right now.
- *
- * Example: "try to advance to `design`, but no plan exists yet" — the
- * model should be told, not crashed on.
- */
-export class OperationFailedError extends GDDError {
-  readonly kind = 'operation_failed' as const;
-  constructor(
-    message: string,
-    code: GDDErrorCode = 'OPERATION_FAILED',
-    context?: Record<string, unknown>,
-  ) {
-    super(message, code, context);
-  }
-}
-
-// -----------------------------------------------------------------------
-// Plan 20-01 compatibility re-exports.
-//
-// These keep the `gdd-state` module's public surface stable post-refactor:
-// - LockAcquisitionError — lockfile contention (plan 20-01 lockfile.ts)
-// - TransitionGateFailed — transition gate veto (plan 20-01 transition())
-// Both are StateConflictError subclasses (retryable / contention-class
-// errors).
-// -----------------------------------------------------------------------
-
-/**
- * Error thrown when `acquire()` cannot obtain the lockfile within
- * `maxWaitMs`. Carries the contents of the offending lockfile (as
- * text — may be JSON, may be garbage if corrupted) so callers can
- * surface them to operators.
- *
- * The `lockPath` and `lockContents` instance properties are preserved
- * from the Plan 20-01 shape for API compat; they're also stored in
- * the frozen `context` object for uniform GDDError serialization.
- */
-export class LockAcquisitionError extends StateConflictError {
-  readonly lockPath: string;
-  readonly lockContents: string;
-  readonly waitedMs: number;
-  constructor(
-    lockPath: string,
-    lockContents: string,
-    waitedMs: number,
-    context?: Record<string, unknown>,
-  ) {
-    super(
-      `failed to acquire lock at ${lockPath} after ${waitedMs}ms; current holder: ${lockContents}`,
-      'LOCK_ACQUISITION',
-      { ...context, lockPath, lockContents, waitedMs },
-    );
-    this.lockPath = lockPath;
-    this.lockContents = lockContents;
-    this.waitedMs = waitedMs;
-  }
-}
-
-/**
- * Error thrown when a transition gate vetoes a stage advance. Carries
- * the frozen list of blocker messages so callers can surface them to
- * operators or retry after resolving.
- *
- * The `blockers` instance property is preserved from the Plan 20-01
- * shape (readonly string[]) for API compat; it's also mirrored into
- * the frozen `context` object for uniform GDDError serialization.
- */
-export class TransitionGateFailed extends StateConflictError {
-  readonly blockers: readonly string[];
-  readonly toStage: string;
-  constructor(
-    toStage: string,
-    blockers: string[],
-    context?: Record<string, unknown>,
-  ) {
-    super(
-      `transition to "${toStage}" blocked by gate: ${blockers.join('; ') || '(no detail)'}`,
-      'TRANSITION_GATE_FAILED',
-      { ...context, toStage, blockers: [...blockers] },
-    );
-    this.toStage = toStage;
-    this.blockers = Object.freeze([...blockers]);
-  }
-}
-
-/**
- * Error thrown by STATE.md `parse()` when the input cannot be
- * interpreted. `ValidationError` semantics: the caller (likely the
- * operator or an upstream generator) gave us malformed input — fix
- * your STATE.md and retry.
- *
- * The `line` instance property points at the 1-indexed line in the
- * source markdown where the parser gave up. It's also mirrored into
- * the frozen `context` object.
- */
-export class ParseError extends ValidationError {
-  readonly line: number;
-  constructor(message: string, line: number, context?: Record<string, unknown>) {
-    super(
-      `STATE.md parse error at line ${line}: ${message}`,
-      'PARSE_ERROR',
-      { ...context, line },
-    );
-    this.line = line;
-  }
-}
+export * from '../../../sdk/errors/index.ts';

package/scripts/lib/gdd-state/index.ts

@@ -1,167 +1,29 @@
-// scripts/lib/gdd-state/index.ts — public API for the gdd-state module.
+// scripts/lib/gdd-state/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// This is the ONLY file consumers should import from. The module exposes
-// exactly five surface-level names:
-//   * read(path)                    — parse STATE.md from disk
-//   * mutate(path, fn)              — atomic read-modify-write under a lock
-//   * transition(path, toStage)     — gate + stage-advance helper
-//   * ParsedState (type)            — consumer-visible shape
-//   * Stage (type)                  — stage enum
+// Thin deprecation shim. The real implementation moved to sdk/state/index.ts
+// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
+// path so undocumented EXTERNAL importers (anyone who reached into
+// node_modules/@hegemonart/get-design-done/scripts/lib/gdd-state/index.ts
+// directly) keep working for one minor grace window.
 //
-// Plan 20-02 wired the real transition gates in via `gateFor(from, to)`
-// imported from `./gates.ts`. Plan 20-04 migrated the error classes
-// (TransitionGateFailed, LockAcquisitionError, ParseError) to the
-// unified `gdd-errors` taxonomy — `types.ts` re-exports them verbatim
-// so consumers of `gdd-state` need no changes.
-
-import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
-
-import { acquire } from './lockfile.ts';
-import { parse } from './parser.ts';
-import { serialize } from './mutator.ts';
-import { gateFor } from './gates.ts';
-import {
-  TransitionGateFailed,
-  isStage,
-  type ParsedState,
-  type Stage,
-  type TransitionResult,
-} from './types.ts';
-
-export type { ParsedState, Stage } from './types.ts';
-export { TransitionGateFailed, LockAcquisitionError, ParseError } from './types.ts';
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
+//
+// Runs under --experimental-strip-types, so `export *` re-export is
+// strip-types-clean.
 
-/**
- * Read STATE.md from disk and return the parsed state.
- *
- * Shared-read: no lock is taken. Reads are snapshot-safe for markdown
- * (the OS guarantees a coherent view even if a writer is mid-rename —
- * we either see the old file or the new file, never a torn write,
- * because `mutate()` uses atomic rename).
- */
-export async function read(path: string): Promise<ParsedState> {
-  const raw: string = readFileSync(path, 'utf8');
-  return parse(raw).state;
-}
+import { emitWarning } from 'node:process';
 
-/**
- * Atomic read-modify-write on STATE.md.
- *
- * Flow:
- *   1. Acquire sibling `.lock` file (PID+timestamp advisory lock).
- *   2. Read current contents.
- *   3. Apply `fn`.
- *   4. Serialize to a `.tmp` file next to `path`.
- *   5. `renameSync(.tmp, path)` — POSIX-atomic; on Windows EPERM means
- *      a scanner held it briefly, retry once.
- *   6. Release the lock (in `finally` — released even on mid-fn throw).
- *
- * Crash between write and rename is benign: STATE.md is untouched; the
- * `.tmp` file is orphaned (cleaned up on the next acquire by the caller).
- */
-export async function mutate(
-  path: string,
-  fn: (s: ParsedState) => ParsedState,
-): Promise<ParsedState> {
-  const release = await acquire(path);
-  const tmpPath: string = `${path}.tmp`;
-  try {
-    const raw: string = readFileSync(path, 'utf8');
-    const { state, raw_bodies, raw_frontmatter, block_gaps, line_ending } =
-      parse(raw);
-    // Deep-clone so the consumer's fn cannot mutate the state we just
-    // parsed (defensive — apply() does this too for pure callers).
-    const clone = structuredClone(state);
-    const next = fn(clone);
-    const out = serialize(next, {
-      raw_frontmatter,
-      raw_bodies,
-      block_gaps,
-      line_ending,
-    });
-    writeFileSync(tmpPath, out, 'utf8');
-    try {
-      renameSync(tmpPath, path);
-    } catch (err) {
-      // Windows EPERM retry — AV / indexer holding STATE.md briefly.
-      const code =
-        typeof err === 'object' && err !== null && 'code' in err
-          ? (err as { code?: unknown }).code
-          : undefined;
-      if (code === 'EPERM' || code === 'EBUSY') {
-        await new Promise((r) => setTimeout(r, 50));
-        renameSync(tmpPath, path);
-      } else {
-        throw err;
-      }
-    }
-    return next;
-  } catch (err) {
-    // Clean up the orphaned tmp file on failure so we don't pollute.
-    try {
-      if (existsSync(tmpPath)) unlinkSync(tmpPath);
-    } catch {
-      // best-effort; a leftover tmp file does not corrupt STATE.md.
-    }
-    throw err;
-  } finally {
-    await release();
-  }
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/lib/gdd-state/index.ts is deprecated; import sdk/state instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-/**
- * Advance to `toStage` under the locked RMW protocol.
- *
- * Steps:
- *   1. Read current state (outside the lock) to pass to the gate.
- *   2. Resolve the gate via `gateFor(position.stage, toStage)`.
- *        - `null` → TransitionGateFailed "Invalid transition" (skip-stage,
- *          backward, same-stage, or from outside the Stage union).
- *   3. Invoke the gate. If `pass: false`, throw TransitionGateFailed with
- *      the gate's blockers verbatim.
- *   4. If `pass: true`, mutate STATE.md under the lock:
- *        - frontmatter.stage = toStage
- *        - position.stage = toStage
- *        - frontmatter.last_checkpoint = now (ISO)
- *        - timestamps[`${toStage}_started_at`] = now (ISO)
- *
- * Returns the updated state plus the gate response (for callers that
- * want to log blockers — on pass, `blockers` is always `[]`).
- */
-export async function transition(
-  path: string,
-  toStage: Stage,
-): Promise<TransitionResult> {
-  // Read (outside the lock) to pass current state to the gate — the
-  // mutate() below will re-read under the lock before applying changes.
-  // This two-phase pattern matches the GSD reference implementation.
-  const beforeMutate = await read(path);
-  const from: string = beforeMutate.position.stage;
-  // `position.stage` is typed as `string` in ParsedState (parser tolerates
-  // `scan` and other pre-brief values). Narrow it to `Stage` before asking
-  // the gate registry — anything outside the union is an invalid FROM.
-  if (!isStage(from)) {
-    throw new TransitionGateFailed(toStage, [
-      `Invalid transition: from="${from}" is not a recognized Stage`,
-    ]);
-  }
-  const gate = gateFor(from, toStage);
-  if (gate === null) {
-    throw new TransitionGateFailed(toStage, [
-      `Invalid transition: ${from} → ${toStage}`,
-    ]);
-  }
-  const gateResult = gate(beforeMutate);
-  if (!gateResult.pass) {
-    throw new TransitionGateFailed(toStage, gateResult.blockers);
-  }
-  const nowIso: string = new Date().toISOString();
-  const nextState = await mutate(path, (s): ParsedState => {
-    s.frontmatter.stage = toStage;
-    s.frontmatter.last_checkpoint = nowIso;
-    s.position.stage = toStage;
-    s.timestamps[`${toStage}_started_at`] = nowIso;
-    return s;
-  });
-  return { pass: true, blockers: gateResult.blockers, state: nextState };
-}
+export * from '../../../sdk/state/index.ts';