@hegemonart/get-design-done 1.56.0 → 1.57.1

package/sdk/state/index.ts

@@ -13,10 +13,32 @@
 // (TransitionGateFailed, LockAcquisitionError, ParseError) to the
 // unified `gdd-errors` taxonomy — `types.ts` re-exports them verbatim
 // so consumers of `gdd-state` need no changes.
+//
+// Phase 57 (Plan 57-06 Round 2-D): dual-write to SQLite when migration
+// is active for this state file. The public API signatures are FROZEN
+// (SC#5) — only the persistence path branches internally.
+//
+// Migration-active gate:
+//   migrationActive(statePath) === true
+//     iff BACKEND==='sqlite' AND existsSync(<dir(statePath)>/state.sqlite)
+//
+// When false (the universal default for un-migrated projects and all
+// existing Phase-20 tests that use temp STATE.md paths), every function
+// behaves EXACTLY as before Phase 57: pure markdown path, byte-identical,
+// same lockfile, same events.
 
-import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+  existsSync,
+  statSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
-import { acquire } from './lockfile.ts';
+import { acquire, acquireSqliteLock } from './lockfile.ts';
 import { parse } from './parser.ts';
 import { serialize } from './mutator.ts';
 import { gateFor } from './gates.ts';
@@ -31,15 +53,173 @@ import {
 export type { ParsedState, Stage } from './types.ts';
 export { TransitionGateFailed, LockAcquisitionError, ParseError } from './types.ts';
 
+// ---------------------------------------------------------------------------
+// Phase 57: package-root resolver (walk-up from sdk/state/index.ts location).
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk up from `startDir` to find the package root (directory with
+ * package.json named '@hegemonart/get-design-done').
+ * Falls back to the first directory that has any package.json, then null.
+ */
+function _findPackageRoot(startDir: string): string | null {
+  let dir = resolve(startDir);
+  let firstWithPkg: string | null = null;
+  for (let i = 0; i < 12; i++) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const pkg = require(pkgPath) as { name?: string };
+        if (firstWithPkg === null) firstWithPkg = dir;
+        if (pkg.name === '@hegemonart/get-design-done') return dir;
+      } catch {
+        if (firstWithPkg === null) firstWithPkg = dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return firstWithPkg;
+}
+
+// ---------------------------------------------------------------------------
+// Phase 57: backend probe (loaded once via require, memoized).
+// state-backend.cjs is a CommonJS module; require() works from .ts under
+// Node 22 --experimental-strip-types (only type-erasable syntax is used).
+// ---------------------------------------------------------------------------
+
+interface StateBackendMod {
+  Database: ((...args: unknown[]) => unknown) | null;
+  BACKEND: 'sqlite' | 'markdown';
+  sqlitePath: (projectRoot: string) => string;
+  openStateDb: (p: string, opts?: { readonly?: boolean }) => StateDb;
+}
+
+interface StateDb {
+  close(): void;
+  prepare(sql: string): { get(...args: unknown[]): unknown; all(...args: unknown[]): unknown[]; run(...args: unknown[]): unknown };
+  transaction(fn: () => void): () => void;
+  pragma(s: string): unknown;
+  exec(s: string): void;
+}
+
+/** null = not yet loaded, false = failed to load, StateBackendMod = loaded */
+let _backendCache: StateBackendMod | null | false = null;
+
+function _loadBackend(): StateBackendMod | null {
+  if (_backendCache !== null) return _backendCache === false ? null : _backendCache as StateBackendMod;
+  try {
+    const pkgRoot = _findPackageRoot(__dirname);
+    if (pkgRoot === null) { _backendCache = false; return null; }
+    const backendPath = join(pkgRoot, 'scripts', 'lib', 'state', 'state-backend.cjs');
+    if (!existsSync(backendPath)) { _backendCache = false; return null; }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    _backendCache = require(backendPath) as StateBackendMod;
+    return _backendCache as StateBackendMod;
+  } catch {
+    _backendCache = false;
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Phase 57: state-store loader (async, cached after first successful load).
+// state-store.cjs itself does dynamic imports of .ts SDK files, so we load
+// it via dynamic import (not require) to stay in async context.
+// ---------------------------------------------------------------------------
+
+interface StateStoreMod {
+  appendDecision: (...args: unknown[]) => Promise<unknown>;
+  getDecisions: (...args: unknown[]) => unknown[];
+  setPosition: (...args: unknown[]) => Promise<unknown>;
+  getPosition: (...args: unknown[]) => unknown;
+  backendName: () => string;
+  [key: string]: unknown;
+}
+
+let _storeCache: StateStoreMod | null | false = null;
+
+async function _loadStore(): Promise<StateStoreMod | null> {
+  if (_storeCache !== null) return _storeCache === false ? null : _storeCache as StateStoreMod;
+  try {
+    const pkgRoot = _findPackageRoot(__dirname);
+    if (pkgRoot === null) { _storeCache = false; return null; }
+    const storePath = join(pkgRoot, 'scripts', 'lib', 'state', 'state-store.cjs');
+    if (!existsSync(storePath)) { _storeCache = false; return null; }
+    const mod = await import(pathToFileURL(storePath).href);
+    _storeCache = mod as StateStoreMod;
+    return _storeCache as StateStoreMod;
+  } catch {
+    _storeCache = false;
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Phase 57: migration-active gate.
+//
+// migrationActive(statePath) === true  iff:
+//   1. BACKEND === 'sqlite'   (better-sqlite3 + FTS5 available, env not forcing markdown)
+//   2. existsSync(join(dirname(statePath), 'state.sqlite'))
+//
+// The sibling check uses dirname(statePath) directly so every temp-dir test
+// that creates a STATE.md WITHOUT a sibling state.sqlite is correctly NOT
+// considered migrated — this is the universal default.
+//
+// This gate is what keeps all existing Phase-20 tests green with better-sqlite3
+// present: they use temp paths with no state.sqlite sibling, so migrationActive
+// returns false and the pure-markdown path runs byte-identically.
+// ---------------------------------------------------------------------------
+
+function migrationActive(statePath: string): boolean {
+  const backend = _loadBackend();
+  if (backend === null || backend.BACKEND !== 'sqlite') return false;
+  const sqliteSibling = join(dirname(statePath), 'state.sqlite');
+  if (!existsSync(sqliteSibling)) return false;
+  // BUG-07: a DIRECTORY named state.sqlite would cause existsSync to return true,
+  // and then every mutate() would throw when trying to open it as a database.
+  // Guard: if the path is a directory, treat migration as inactive.
+  try {
+    if (statSync(sqliteSibling).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Return the path to the sibling state.sqlite for a given STATE.md path.
+ * This is always `<dirname(statePath)>/state.sqlite`.
+ * Exported for use by tests and lockfile helpers.
+ */
+export function sqlitePathFor(statePath: string): string {
+  return join(dirname(statePath), 'state.sqlite');
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
 /**
  * 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).
+ * Phase 57 dual-write: when migration is active, reads the on-disk STATE.md
+ * (which the dual-write path keeps byte-equal with SQLite state), then parses
+ * it. This matches the pre-Phase-57 behavior of this function and keeps the
+ * returned ParsedState shape identical whether reading via SQLite or markdown.
+ *
+ * Shared-read: no lock is taken. Reads are snapshot-safe (atomic rename by
+ * `mutate()` means we either see the old file or the new file, never a torn
+ * write).
  */
 export async function read(path: string): Promise<ParsedState> {
+  // Phase 57: both paths parse the on-disk STATE.md (the dual-write path
+  // maintains STATE.md as a byte-equal render of SQLite state). No behavioral
+  // difference; the branch is here for future extension (e.g., reading directly
+  // from SQLite without touching disk). The returned ParsedState is identical
+  // whether migration is active or not.
   const raw: string = readFileSync(path, 'utf8');
   return parse(raw).state;
 }
@@ -47,13 +227,19 @@ export async function read(path: string): Promise<ParsedState> {
 /**
  * Atomic read-modify-write on STATE.md.
  *
- * Flow:
+ * Phase 57 dual-write: when migration is active for this statePath, acquires
+ * the SQLite sibling lock BEFORE the STATE.md lock (R9 deadlock-free
+ * ordering), then after applying fn() serializes to markdown and writes
+ * atomically (same .tmp+rename path). The on-disk STATE.md is always the
+ * byte-equal rendered form, so SQLite stays consistent via the R8 freshness
+ * guard on the next state-store operation.
+ *
+ * When migration is inactive, behavior is EXACTLY as pre-Phase-57:
  *   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.
+ *   5. `renameSync(.tmp, path)` — POSIX-atomic; Windows EPERM 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
@@ -62,6 +248,20 @@ export async function read(path: string): Promise<ParsedState> {
 export async function mutate(
   path: string,
   fn: (s: ParsedState) => ParsedState,
+): Promise<ParsedState> {
+  if (migrationActive(path)) {
+    return _mutateSqliteActive(path, fn);
+  }
+  return _mutateMarkdown(path, fn);
+}
+
+/**
+ * Pure markdown mutate path (pre-Phase-57 behavior, unchanged).
+ * Called when migrationActive() === false.
+ */
+async function _mutateMarkdown(
+  path: string,
+  fn: (s: ParsedState) => ParsedState,
 ): Promise<ParsedState> {
   const release = await acquire(path);
   const tmpPath: string = `${path}.tmp`;
@@ -69,8 +269,6 @@ export async function mutate(
     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, {
@@ -97,11 +295,10 @@ export async function mutate(
     }
     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.
+      // best-effort cleanup.
     }
     throw err;
   } finally {
@@ -109,6 +306,69 @@ export async function mutate(
   }
 }
 
+/**
+ * SQLite-active mutate path (Phase 57, migrationActive() === true).
+ *
+ * Lock ordering per R9: acquire state.sqlite.lock BEFORE STATE.md.lock
+ * (deadlock-free). Both released in finally.
+ *
+ * Write strategy: serialize next state to markdown, write atomically
+ * (.tmp + rename). This keeps STATE.md byte-equal with the last parsed
+ * state. The R8 freshness guard in state-store detects the sha-change on
+ * the next state-store call and re-syncs SQLite from the markdown SoT.
+ * This avoids duplicating state-store's row-level write logic here while
+ * still keeping SQLite eventually consistent.
+ */
+async function _mutateSqliteActive(
+  path: string,
+  fn: (s: ParsedState) => ParsedState,
+): Promise<ParsedState> {
+  const sqlitePath = join(dirname(path), 'state.sqlite');
+  // Acquire SQLite lock first (R9: state.sqlite.lock before STATE.md.lock).
+  const releaseSqliteLock = await acquireSqliteLock(sqlitePath);
+  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);
+    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) {
+      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) {
+    try {
+      if (existsSync(tmpPath)) unlinkSync(tmpPath);
+    } catch {
+      // best-effort cleanup.
+    }
+    throw err;
+  } finally {
+    await release();
+    await releaseSqliteLock();
+  }
+}
+
 /**
  * Advance to `toStage` under the locked RMW protocol.
  *
@@ -125,6 +385,10 @@ export async function mutate(
  *        - frontmatter.last_checkpoint = now (ISO)
  *        - timestamps[`${toStage}_started_at`] = now (ISO)
  *
+ * Phase 57: the gate evaluation + stamping logic is unchanged. The
+ * persistence path branches via `mutate()` which applies the
+ * migration-active gate internally.
+ *
  * Returns the updated state plus the gate response (for callers that
  * want to log blockers — on pass, `blockers` is always `[]`).
  */

package/sdk/state/lockfile.ts

@@ -230,3 +230,51 @@ function getErrnoCode(err: unknown): string | undefined {
 function sleep(ms: number): Promise<void> {
   return new Promise<void>((resolve) => setTimeout(resolve, ms));
 }
+
+// ---------------------------------------------------------------------------
+// Phase 57 (Plan 57-06 Round 2-D): SQLite sibling lock.
+//
+// R9 requirement: when both STATE.md.lock and state.sqlite.lock are needed,
+// acquire state.sqlite.lock BEFORE STATE.md.lock (deadlock-free ordering).
+//
+// The SQLite lock file is `${sqlitePath}.lock` (i.e. state.sqlite.lock),
+// using the SAME acquire algorithm and the SAME {pid,host,acquired_at}
+// payload as the existing STATE.md.lock. This reuses the entire acquire()
+// code path — callers just pass the SQLite path instead of the markdown path.
+//
+// Callers in sdk/state/index.ts follow the mandated ordering:
+//   1. acquireSqliteLock(state.sqlite)   → releaseSqlite
+//   2. acquire(STATE.md)                  → releaseMarkdown
+//   3. ... do work ...
+//   4. releaseMarkdown()
+//   5. releaseSqlite()
+//
+// This function is a thin alias for acquire() with documentation that
+// enforces the ordering contract. It is exported separately so consumers
+// can't accidentally use it without understanding the ordering requirement.
+// ---------------------------------------------------------------------------
+
+/**
+ * Acquire the advisory lock for `state.sqlite` at `${sqlitePath}.lock`.
+ *
+ * Uses the SAME acquire algorithm and `{pid, host, acquired_at}` payload
+ * as the existing `acquire()` for STATE.md.lock.
+ *
+ * ORDERING RULE (R9, deadlock-free): when both locks are needed, ALWAYS
+ * acquire `state.sqlite.lock` BEFORE `STATE.md.lock`. Never acquire them
+ * in the opposite order.
+ *
+ * @param sqlitePath  absolute path to `state.sqlite` (NOT the `.lock` file —
+ *                    the lock file is derived as `${sqlitePath}.lock`).
+ * @param opts        same AcquireOptions as `acquire()`.
+ * @throws LockAcquisitionError when `maxWaitMs` elapses without acquiring.
+ */
+export async function acquireSqliteLock(
+  sqlitePath: string,
+  opts: AcquireOptions = {},
+): Promise<LockRelease> {
+  // Delegate entirely to the existing acquire() implementation. The lock
+  // file ends up at `${sqlitePath}.lock` (e.g. `.design/state.sqlite.lock`),
+  // exactly matching R9's specification.
+  return acquire(sqlitePath, opts);
+}

package/sdk/state/schema.sql

@@ -0,0 +1,218 @@
+-- sdk/state/schema.sql - Phase 57 SQLite State Backbone.
+-- PINNED DDL: all executors align to this exact schema.
+-- Created by Executor A; consumed by state-backend, migrate-to-sqlite, render-markdown,
+-- and any downstream reader that opens state.sqlite.
+--
+-- All tables use CREATE TABLE IF NOT EXISTS so this file is safely re-executed
+-- (openStateDb calls loadSchema on every open).
+--
+-- FTS5 virtual tables are in a separate section at the bottom.
+-- state-backend.cjs executes that section ONLY when _sqliteOk (better-sqlite3 + fts5
+-- probe passed). A no-fts5 build creates all base tables without issue.
+--
+-- Column sources annotated per CONTEXT.md "Shared contracts".
+
+-- ---------------------------------------------------------------------------
+-- Base tables
+-- ---------------------------------------------------------------------------
+
+-- state_position: mirrors the <position> block + frontmatter fields of STATE.md.
+-- One row per cycle_id; the active cycle is the most recent updated_at.
+CREATE TABLE IF NOT EXISTS state_position (
+  cycle_id            TEXT PRIMARY KEY,   -- cycle: field from frontmatter
+  stage               TEXT,               -- stage: (scan/explore/decide/build/verify/operate)
+  wave                INTEGER,            -- wave: (integer progress within stage)
+  task_progress       TEXT,               -- e.g. "3/7" from <position> block
+  status              TEXT,               -- status: field from <position>
+  branch              TEXT,               -- branch: field from <position>
+  raw_frontmatter     TEXT,               -- verbatim frontmatter text (for byte-equal round-trip)
+  body_preamble       TEXT,               -- text between frontmatter and first block (for round-trip)
+  body_trailer        TEXT,               -- text after last block (for round-trip)
+  line_ending         TEXT DEFAULT '\n',  -- '\n' or '\r\n' (for round-trip)
+  last_render_sha256  TEXT,               -- sha256 of the last rendered STATE.md (R8 freshness guard)
+  updated_at          TEXT                -- ISO 8601 timestamp of last SQLite write
+);
+
+-- decisions: mirrors <decisions> block lines.
+-- Composite PRIMARY KEY (cycle_id, id) so D-NN identifiers recur across cycles (R11).
+CREATE TABLE IF NOT EXISTS decisions (
+  id                  TEXT NOT NULL,      -- e.g. D-01, D-02 (stable within cycle)
+  cycle_id            TEXT NOT NULL,      -- FK -> state_position.cycle_id
+  phase_id            TEXT,               -- phase tag from the decision line (if any)
+  status              TEXT CHECK(status IN ('locked', 'tentative')),
+  body_md             TEXT,               -- the decision text (markdown)
+  tags                TEXT,               -- JSON array of tag strings
+  ordinal             INTEGER NOT NULL,   -- explicit emit order (preserved on conflict per R11)
+  raw_line            TEXT,               -- verbatim source line (prevents reformat drift, R6)
+  created_at          TEXT,               -- ISO 8601 (preserved on conflict per R11)
+  last_referenced_at  TEXT,               -- ISO 8601 last time this decision was referenced
+  PRIMARY KEY (cycle_id, id),
+  FOREIGN KEY (cycle_id) REFERENCES state_position(cycle_id)
+);
+CREATE INDEX IF NOT EXISTS idx_decisions_cycle ON decisions(cycle_id);
+
+-- blockers: mirrors <blockers> block lines.
+-- AUTOINCREMENT id; stable composite is [stage][date] for UPSERT (R11).
+CREATE TABLE IF NOT EXISTS blockers (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  cycle_id    TEXT,               -- FK -> state_position.cycle_id
+  stage       TEXT,               -- stage label from "[stage][date]: text"
+  date        TEXT,               -- date string from blocker line (YYYY-MM-DD or ISO)
+  severity    TEXT,               -- optional severity tag
+  body_md     TEXT,               -- blocker text
+  ordinal     INTEGER NOT NULL,   -- emit order
+  raw_line    TEXT,               -- verbatim source line (R6 - parser THROWS on malformed)
+  resolved_at TEXT,               -- ISO 8601 when resolved (NULL = unresolved)
+  FOREIGN KEY (cycle_id) REFERENCES state_position(cycle_id)
+);
+CREATE INDEX IF NOT EXISTS idx_blockers_cycle ON blockers(cycle_id);
+
+-- must_haves: mirrors <must_haves> block checklist items.
+-- Composite PRIMARY KEY (cycle_id, id) so M-NN identifiers recur across cycles (R11).
+CREATE TABLE IF NOT EXISTS must_haves (
+  id       TEXT NOT NULL,        -- e.g. M-01, M-02 (stable within cycle)
+  cycle_id TEXT NOT NULL,        -- FK -> state_position.cycle_id
+  body_md  TEXT,                 -- item text
+  status   TEXT CHECK(status IN ('pending', 'pass', 'fail')),
+  ordinal  INTEGER NOT NULL,     -- emit order
+  raw_line TEXT,                 -- verbatim source line
+  PRIMARY KEY (cycle_id, id),
+  FOREIGN KEY (cycle_id) REFERENCES state_position(cycle_id)
+);
+CREATE INDEX IF NOT EXISTS idx_must_haves_cycle ON must_haves(cycle_id);
+
+-- plans: mirrors <plans> block entries (one row per plan file reference).
+CREATE TABLE IF NOT EXISTS plans (
+  id           TEXT PRIMARY KEY,   -- plan filename as stable key
+  phase_id     TEXT,               -- phase identifier
+  status       TEXT,               -- pending/active/complete
+  body_md      TEXT,               -- plan description text
+  ordinal      INTEGER,            -- emit order
+  completed_at TEXT                -- ISO 8601 (NULL = not yet complete)
+);
+CREATE INDEX IF NOT EXISTS idx_plans_phase ON plans(phase_id);
+
+-- findings: Phase 22 / Phase 52 research findings stored across cycles.
+CREATE TABLE IF NOT EXISTS findings (
+  id           TEXT PRIMARY KEY,   -- stable finding id
+  source_agent TEXT,               -- agent that produced the finding
+  cycle_id     TEXT,               -- FK -> state_position.cycle_id
+  phase_id     TEXT,               -- phase the finding came from
+  pillar       TEXT,               -- pillar category (e.g. architecture/security/perf)
+  severity     TEXT,               -- critical/high/medium/low/info
+  confidence   REAL,               -- 0.0-1.0
+  body_md      TEXT,               -- finding body (markdown)
+  applied      INTEGER DEFAULT 0,  -- 0 = not yet applied, 1 = applied
+  created_at   TEXT,               -- ISO 8601
+  FOREIGN KEY (cycle_id) REFERENCES state_position(cycle_id)
+);
+CREATE INDEX IF NOT EXISTS idx_findings_cycle ON findings(cycle_id);
+
+-- design_debt: mirrors <design_debt> block entries.
+CREATE TABLE IF NOT EXISTS design_debt (
+  id        TEXT PRIMARY KEY,   -- stable id
+  category  TEXT,               -- debt category
+  instances TEXT,               -- JSON array of affected instances/files
+  priority  TEXT,               -- critical/high/medium/low
+  status    TEXT                -- open/acknowledged/resolved
+);
+
+-- recall_records: Phase 19.5 recall store mirror (extended for Phase 57).
+-- The standalone Phase 19.5 design-search store keeps working as the fallback;
+-- this table is populated by migrate-to-sqlite and updated on dual-write.
+CREATE TABLE IF NOT EXISTS recall_records (
+  id         TEXT PRIMARY KEY,   -- stable recall id
+  cycle_id   TEXT,               -- FK -> state_position.cycle_id
+  kind       TEXT,               -- recall kind (finding/decision/note/...)
+  body_md    TEXT,               -- recall body
+  tags       TEXT,               -- JSON array of tag strings
+  created_at TEXT,               -- ISO 8601
+  FOREIGN KEY (cycle_id) REFERENCES state_position(cycle_id)
+);
+CREATE INDEX IF NOT EXISTS idx_recall_cycle ON recall_records(cycle_id);
+
+-- instincts: Phase 51 instinct-store mirror (created empty in Wave A; populated by migrate).
+-- The standalone Phase 51 instinct-store keeps working as the fallback;
+-- merge-and-retire is a v1.58 concern (documented deferral).
+CREATE TABLE IF NOT EXISTS instincts (
+  id          TEXT PRIMARY KEY,   -- stable instinct id
+  scope       TEXT,               -- project / global
+  domain      TEXT,               -- intake/explore/decide/build/verify/operate/utility
+  body_md     TEXT,               -- instinct body (markdown)
+  confidence  REAL,               -- 0.0-1.0 posterior mean
+  cycles_seen INTEGER,            -- number of cycles this instinct has been observed
+  project_ids TEXT,               -- JSON array of project ids (sha8)
+  last_seen   TEXT                -- ISO 8601 date last surfaced
+);
+
+-- sessions: runtime session records (Phase 22 / worktree awareness).
+CREATE TABLE IF NOT EXISTS sessions (
+  id         TEXT PRIMARY KEY,   -- session id (UUID or opaque string)
+  runtime    TEXT,               -- runtime name (claude-code / gemini / codex / ...)
+  harness    TEXT,               -- harness identifier
+  started_at TEXT,               -- ISO 8601
+  ended_at   TEXT                -- ISO 8601 (NULL = still active)
+);
+
+-- worktree_state: per-worktree active state (Phase 49 / parallel executor awareness).
+CREATE TABLE IF NOT EXISTS worktree_state (
+  path            TEXT PRIMARY KEY,   -- absolute worktree path
+  branch          TEXT,               -- current branch in worktree
+  owns_session_id TEXT,               -- FK -> sessions.id (advisory; may be NULL)
+  updated_at      TEXT                -- ISO 8601
+);
+
+-- conflict_incidents: detected concurrent-write conflict events.
+CREATE TABLE IF NOT EXISTS conflict_incidents (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  files       TEXT,               -- JSON array of conflicting file paths
+  session_ids TEXT,               -- JSON array of session ids involved
+  detected_at TEXT                -- ISO 8601
+);
+
+-- _meta: schema-level key/value store.
+-- Holds schema_version and last_render_sha256 (mirror of state_position for fast lookup).
+CREATE TABLE IF NOT EXISTS _meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT
+);
+
+-- _block_meta: per-cycle, per-block rendering metadata for byte-equal round-trip (R6).
+-- Stores the gap (blank lines) before each block, the raw verbatim block body,
+-- and emit ordinal so unstructured blocks (connections/timestamps/parallelism_decision/todos)
+-- round-trip exactly.
+CREATE TABLE IF NOT EXISTS _block_meta (
+  cycle_id TEXT    NOT NULL,   -- FK -> state_position.cycle_id
+  block    TEXT    NOT NULL,   -- block name (decisions/blockers/must_haves/position/...)
+  gap      TEXT,               -- blank lines preceding the block open tag (for emit order)
+  raw_body TEXT,               -- verbatim raw body of the block (for unstructured blocks)
+  ordinal  INTEGER,            -- emit ordinal (position in BLOCK_ORDER for this cycle)
+  PRIMARY KEY (cycle_id, block),
+  FOREIGN KEY (cycle_id) REFERENCES state_position(cycle_id)
+);
+
+-- ---------------------------------------------------------------------------
+-- FTS5 virtual tables (execute ONLY when _sqliteOk - better-sqlite3 + fts5 probe passed)
+-- state-backend.cjs splits on the marker comment below and executes this
+-- section separately, guarded by the _sqliteOk flag.
+-- ---------------------------------------------------------------------------
+-- GDD_FTS5_SECTION_START
+
+-- decisions_fts: full-text search over decision body and tags.
+-- Uses trigram tokenizer for partial-match queries (like instinct-store FTS5).
+CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts
+  USING fts5(id UNINDEXED, body_md, tags, tokenize='trigram');
+
+-- findings_fts: full-text search over finding body and pillar.
+CREATE VIRTUAL TABLE IF NOT EXISTS findings_fts
+  USING fts5(id UNINDEXED, body_md, pillar, tokenize='trigram');
+
+-- recall_fts: full-text search over recall record body and tags.
+CREATE VIRTUAL TABLE IF NOT EXISTS recall_fts
+  USING fts5(id UNINDEXED, body_md, tags, tokenize='trigram');
+
+-- instincts_fts: full-text search over instinct body and domain (mirrors instinct-store).
+CREATE VIRTUAL TABLE IF NOT EXISTS instincts_fts
+  USING fts5(id UNINDEXED, body_md, domain, tokenize='trigram');
+
+-- GDD_FTS5_SECTION_END