ygl-trees 0.66.0 → 0.69.0

package/dist/packages/core/database/src/db.js

@@ -46,351 +46,351 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const text_1 = require("../../text/src/text");
 exports.SCHEMA_VERSION = 9;
-exports.SCHEMA_SQL = `
--- ---------------------------------------------------------------- meta
--- runtime state the tool writes itself (current selections, bookkeeping);
--- user-tunable settings live in config
-CREATE TABLE IF NOT EXISTS meta (
-  key   TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-);
-
--- ---------------------------------------------------------------- config (v6)
--- user-tunable settings; registry (defaults/types/notes) in src/config.ts.
--- Reads fall back to defaults — an empty table is a valid state.
-CREATE TABLE IF NOT EXISTS config (
-  key     TEXT PRIMARY KEY,
-  value   TEXT NOT NULL DEFAULT '',
-  note    TEXT DEFAULT '',
-  updated TEXT NOT NULL
-);
-
--- ---------------------------------------------------------------- skills (L1/L2/L3)
-CREATE TABLE IF NOT EXISTS skills (
-  id          TEXT PRIMARY KEY,
-  name        TEXT NOT NULL UNIQUE,
-  version     TEXT DEFAULT '0.1.0',
-  description TEXT NOT NULL DEFAULT '',   -- L1: what + when, always in context
-  body        TEXT NOT NULL DEFAULT '',   -- L2: instructions, loaded on activation
-  tags        TEXT DEFAULT '',
-  origin      TEXT DEFAULT '',            -- where it came from (path/repo)
-  enabled     INTEGER NOT NULL DEFAULT 1,
-  hits        INTEGER NOT NULL DEFAULT 0, -- how often an agent matched it
-  created     TEXT NOT NULL,
-  updated     TEXT NOT NULL
-);
-CREATE TABLE IF NOT EXISTS skill_refs (          -- L3: loaded on demand
-  id       TEXT PRIMARY KEY,
-  skill_id TEXT NOT NULL REFERENCES skills(id) ON DELETE CASCADE,
-  path     TEXT NOT NULL,
-  content  TEXT NOT NULL DEFAULT ''
-);
-CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5(
-  id UNINDEXED, name, description, tags, ngram, tokenize='unicode61'
-);
-
--- ---------------------------------------------------------------- projects
-CREATE TABLE IF NOT EXISTS projects (
-  id         TEXT PRIMARY KEY,
-  name       TEXT NOT NULL UNIQUE,
-  question   TEXT NOT NULL DEFAULT '',
-  inclusion  TEXT DEFAULT '',
-  exclusion  TEXT DEFAULT '',
-  status     TEXT NOT NULL DEFAULT 'active',
-  created    TEXT NOT NULL,
-  updated    TEXT NOT NULL
-);
-
--- ---------------------------------------------------------------- research: queries
-CREATE TABLE IF NOT EXISTS queries (
-  id           TEXT PRIMARY KEY,
-  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
-  text         TEXT NOT NULL,
-  engine       TEXT DEFAULT '',
-  status       TEXT NOT NULL DEFAULT 'pending',  -- pending|done
-  note         TEXT DEFAULT '',
-  content_hash TEXT NOT NULL DEFAULT '',         -- sha1(text): idempotent writes
-  created      TEXT NOT NULL
-);
-
--- ---------------------------------------------------------------- research: sources
--- query <-> source association: which search query recalled which source
--- (schema v4; pure additive, no migration needed beyond CREATE IF NOT EXISTS)
-CREATE TABLE IF NOT EXISTS query_sources (
-  query_id  TEXT NOT NULL REFERENCES queries(id) ON DELETE CASCADE,
-  source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
-  note      TEXT DEFAULT '',
-  created   TEXT NOT NULL,
-  PRIMARY KEY (query_id, source_id)
-);
-
-CREATE TABLE IF NOT EXISTS sources (
-  id           TEXT PRIMARY KEY,
-  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
-  url          TEXT DEFAULT '',
-  title        TEXT NOT NULL DEFAULT '',
-  url_hash     TEXT NOT NULL,
-  content_hash TEXT NOT NULL DEFAULT '',
-  abstract     TEXT DEFAULT '',
-  content      TEXT DEFAULT '',
-  engine       TEXT DEFAULT '',
-  relevance    INTEGER NOT NULL DEFAULT 0,   -- 0..5 screening score
-  confidence   TEXT NOT NULL DEFAULT 'B',    -- A|B|C source trust grade
-  tags         TEXT DEFAULT '',
-  created      TEXT NOT NULL DEFAULT '',
-  retrieved_at TEXT NOT NULL,
-  UNIQUE(project_id, url_hash)
-);
-CREATE VIRTUAL TABLE IF NOT EXISTS sources_fts USING fts5(
-  id UNINDEXED, title, abstract, content, ngram, tokenize='unicode61'
-);
-
--- ---------------------------------------------------------------- research: evidence
-CREATE TABLE IF NOT EXISTS evidence (
-  id           TEXT PRIMARY KEY,
-  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
-  source_id    TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
-  quote        TEXT NOT NULL,
-  note         TEXT DEFAULT '',
-  locator      TEXT DEFAULT '',   -- page / section / offset
-  content_hash TEXT NOT NULL DEFAULT '',  -- sha1(quote): idempotent writes
-  created      TEXT NOT NULL
-);
-CREATE VIRTUAL TABLE IF NOT EXISTS evidence_fts USING fts5(
-  id UNINDEXED, quote, ngram, tokenize='unicode61'
-);
-
--- ---------------------------------------------------------------- research: claims
-CREATE TABLE IF NOT EXISTS claims (
-  id           TEXT PRIMARY KEY,
-  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
-  text         TEXT NOT NULL,
-  status       TEXT NOT NULL DEFAULT 'unverified', -- unverified|supported|refuted|contested
-  confidence   TEXT NOT NULL DEFAULT 'B',
-  content_hash TEXT NOT NULL DEFAULT '',           -- sha1(text): idempotent writes
-  created      TEXT NOT NULL,
-  updated      TEXT NOT NULL DEFAULT ''
-);
-CREATE TABLE IF NOT EXISTS claim_evidence (
-  claim_id    TEXT NOT NULL REFERENCES claims(id) ON DELETE CASCADE,
-  evidence_id TEXT NOT NULL REFERENCES evidence(id) ON DELETE CASCADE,
-  stance      TEXT NOT NULL DEFAULT 'supports',  -- supports|refutes
-  PRIMARY KEY (claim_id, evidence_id)
-);
-
--- ---------------------------------------------------------------- production
-CREATE TABLE IF NOT EXISTS artifacts (
-  id         TEXT PRIMARY KEY,
-  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
-  kind       TEXT NOT NULL DEFAULT 'section',  -- outline|section|report|note|spec|design|task
-  title      TEXT NOT NULL DEFAULT '',
-  format     TEXT NOT NULL DEFAULT 'markdown',
-  content    TEXT NOT NULL DEFAULT '',
-  version    INTEGER NOT NULL DEFAULT 1,
-  created    TEXT NOT NULL,
-  updated    TEXT NOT NULL DEFAULT '',
-  meta       TEXT NOT NULL DEFAULT ''          -- v8 JSON envelope: task {"status"}, design {"design_type"}
-);
-
--- ---------------------------------------------------------------- knowledge base
-CREATE TABLE IF NOT EXISTS kb_notes (
-  id            TEXT PRIMARY KEY,
-  title         TEXT NOT NULL,
-  body          TEXT NOT NULL DEFAULT '',
-  source_url    TEXT DEFAULT '',
-  origin        TEXT DEFAULT '',       -- 'artifact:<id>' | 'note' | 'skill:<id>'
-  tags          TEXT DEFAULT '',
-  confidence    TEXT NOT NULL DEFAULT 'B',
-  reuse         INTEGER NOT NULL DEFAULT 0,
-  content_hash  TEXT NOT NULL DEFAULT '',  -- sha1(title+body): idempotent writes
-  created       TEXT NOT NULL,
-  updated       TEXT NOT NULL
-);
-CREATE VIRTUAL TABLE IF NOT EXISTS kb_fts USING fts5(
-  id UNINDEXED, title, tags, ngram, tokenize='unicode61'
-);
-CREATE TABLE IF NOT EXISTS kb_links (
-  from_id TEXT NOT NULL REFERENCES kb_notes(id) ON DELETE CASCADE,
-  to_id   TEXT NOT NULL REFERENCES kb_notes(id) ON DELETE CASCADE,
-  rel     TEXT NOT NULL DEFAULT 'related',
-  PRIMARY KEY (from_id, to_id, rel)
-);
-
--- ================================================================ TECH TREE MODEL
--- A node model covering four things:
---   1. parent/child structure      -> node_edges (adjacency, source of truth)
---   2. associations per node       -> node_edges.rel + relations (multi-kind)
---   3. required vs optional gates  -> node_edges.required + node_conditions
---   4. indexes for fast queries    -> node_closure (transitive), node_fts, idx_*
-CREATE TABLE IF NOT EXISTS trees (
-  id         TEXT PRIMARY KEY,
-  project_id TEXT REFERENCES projects(id) ON DELETE CASCADE,
-  name       TEXT NOT NULL UNIQUE,
-  note       TEXT DEFAULT '',
-  created    TEXT NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS nodes (
-  id         TEXT PRIMARY KEY,
-  tree_id    TEXT NOT NULL REFERENCES trees(id) ON DELETE CASCADE,
-  key        TEXT NOT NULL,                  -- stable id used in save files
-  name       TEXT NOT NULL,
-  kind       TEXT NOT NULL DEFAULT 'tech',   -- tech|skill|upgrade|building|era
-  tier       INTEGER NOT NULL DEFAULT 0,     -- era / depth band for layout
-  cost       REAL NOT NULL DEFAULT 0,
-  cost_unit  TEXT DEFAULT '',
-  payload    TEXT DEFAULT '',                -- JSON: effects, unlocks, metadata
-  tags       TEXT DEFAULT '',
-  created    TEXT NOT NULL,
-  UNIQUE(tree_id, key)
-);
-CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
-  id UNINDEXED, key, name, tags, ngram, tokenize='unicode61'
-);
-CREATE INDEX IF NOT EXISTS idx_nodes_tree ON nodes(tree_id);
-CREATE INDEX IF NOT EXISTS idx_nodes_tier ON nodes(tree_id, tier);
-
--- Adjacency list: the faithful source of truth for the DAG.
---   rel       parent->child semantics: prereq | unlock | excludes | enables
---   mode      how multiple parents combine: AND | OR | XOR | NOT
---   required  1 = must pass (gating)  0 = optional (bonus / discount only)
-CREATE TABLE IF NOT EXISTS node_edges (
-  id         TEXT PRIMARY KEY,
-  tree_id    TEXT NOT NULL REFERENCES trees(id) ON DELETE CASCADE,
-  parent_id  TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  child_id   TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  rel        TEXT NOT NULL DEFAULT 'prereq',
-  mode       TEXT NOT NULL DEFAULT 'AND',
-  required   INTEGER NOT NULL DEFAULT 1,
-  min_level  INTEGER NOT NULL DEFAULT 1,
-  weight     REAL NOT NULL DEFAULT 1,
-  note       TEXT DEFAULT '',
-  created    TEXT NOT NULL DEFAULT '',
-  UNIQUE(parent_id, child_id, rel)
-);
-CREATE INDEX IF NOT EXISTS idx_edge_child  ON node_edges(child_id);
-CREATE INDEX IF NOT EXISTS idx_edge_parent ON node_edges(parent_id);
-CREATE INDEX IF NOT EXISTS idx_edge_req    ON node_edges(child_id, required);
-
--- Closure table: transitive index for ancestor/descendant queries.
--- depth 0 = self row, 1 = direct parent, n = n-th ancestor.
-CREATE TABLE IF NOT EXISTS node_closure (
-  tree_id    TEXT NOT NULL,
-  ancestor   TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  descendant TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  depth      INTEGER NOT NULL,
-  PRIMARY KEY (ancestor, descendant)
-);
-CREATE INDEX IF NOT EXISTS idx_closure_desc ON node_closure(descendant);
-CREATE INDEX IF NOT EXISTS idx_closure_anc  ON node_closure(ancestor);
-
--- Non-structural gates: conditions that are not other nodes.
--- required=1 blocks unlock; required=0 only modifies cost / grants bonus.
-CREATE TABLE IF NOT EXISTS node_conditions (
-  id       TEXT PRIMARY KEY,
-  node_id  TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  name     TEXT NOT NULL,
-  kind     TEXT NOT NULL DEFAULT 'flag',   -- flag|resource|level|quest|time|expr
-  expr     TEXT NOT NULL DEFAULT '',       -- evaluated against a runtime state
-  op       TEXT NOT NULL DEFAULT '>=',     -- >= | == | <= | != | has
-  value    TEXT NOT NULL DEFAULT '',
-  required INTEGER NOT NULL DEFAULT 1,
-  effect   TEXT NOT NULL DEFAULT 'gate',   -- gate | cost_mul | bonus
-  weight   REAL NOT NULL DEFAULT 1,
-  note     TEXT DEFAULT '',
-  created  TEXT NOT NULL DEFAULT ''
-);
-CREATE INDEX IF NOT EXISTS idx_cond_node ON node_conditions(node_id);
-CREATE INDEX IF NOT EXISTS idx_cond_req  ON node_conditions(node_id, required);
--- (node_conditions.created is added by upgrade8to9 for existing DBs; new DBs get it from upgrade8to9 too since SCHEMA_SQL doesn't declare it inline)
-
--- Runtime state per context (save slot / player / run).
-CREATE TABLE IF NOT EXISTS node_state (
-  tree_id  TEXT NOT NULL REFERENCES trees(id) ON DELETE CASCADE,
-  context  TEXT NOT NULL DEFAULT 'default',
-  node_id  TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  status   TEXT NOT NULL DEFAULT 'locked',  -- locked|available|unlocked
-  level    INTEGER NOT NULL DEFAULT 0,
-  progress REAL NOT NULL DEFAULT 0,
-  updated  TEXT NOT NULL,
-  PRIMARY KEY (tree_id, context, node_id)
-);
-CREATE INDEX IF NOT EXISTS idx_state_ctx    ON node_state(tree_id, context);
-CREATE INDEX IF NOT EXISTS idx_state_status ON node_state(tree_id, context, status);
-
--- Denormalized index on nodes, refreshed by the 'node index' command.
--- topo_order lets "can I research this" skip recursive traversal.
-CREATE TABLE IF NOT EXISTS node_index (
-  tree_id     TEXT PRIMARY KEY REFERENCES trees(id) ON DELETE CASCADE,
-  topo_order  TEXT NOT NULL DEFAULT '',   -- JSON array of node ids
-  tiers       TEXT NOT NULL DEFAULT '',   -- JSON: tier -> [node ids]
-  in_degree   TEXT NOT NULL DEFAULT '',   -- JSON: node id -> required parent count
-  built_at    TEXT NOT NULL,
-  dirty       INTEGER NOT NULL DEFAULT 1
-);
-
--- ---------------------------------------------------------------- generic graph
-CREATE TABLE IF NOT EXISTS relations (
-  id       TEXT PRIMARY KEY,
-  src_type TEXT NOT NULL, src_id TEXT NOT NULL,
-  dst_type TEXT NOT NULL, dst_id TEXT NOT NULL,
-  rel      TEXT NOT NULL DEFAULT 'related',
-  weight   REAL NOT NULL DEFAULT 1,
-  created  TEXT NOT NULL DEFAULT '',
-  UNIQUE(src_type, src_id, dst_type, dst_id, rel)
-);
-
--- ---------------------------------------------------------------- scheduling
-CREATE TABLE IF NOT EXISTS jobs (
-  id            TEXT PRIMARY KEY,
-  title         TEXT NOT NULL,
-  command       TEXT NOT NULL,
-  every_minutes INTEGER DEFAULT 0,
-  at            TEXT DEFAULT '',     -- one-shot ISO datetime
-  enabled       INTEGER NOT NULL DEFAULT 1,
-  runs          INTEGER NOT NULL DEFAULT 0,
-  last_run      TEXT DEFAULT '',
-  status        TEXT NOT NULL DEFAULT 'pending',
-  created       TEXT NOT NULL
-);
-CREATE TABLE IF NOT EXISTS runs (
-  id       TEXT PRIMARY KEY,
-  job_id   TEXT NOT NULL REFERENCES jobs(id) ON DELETE CASCADE,
-  started  TEXT NOT NULL,
-  finished TEXT DEFAULT '',
-  rc       INTEGER,
-  output   TEXT DEFAULT ''
-);
-
--- ---------------------------------------------------------------- audit log
-CREATE TABLE IF NOT EXISTS events (
-  id        TEXT PRIMARY KEY,
-  ts        TEXT NOT NULL,
-  actor     TEXT NOT NULL DEFAULT 'cli',
-  kind      TEXT NOT NULL,
-  entity    TEXT DEFAULT '',
-  entity_id TEXT DEFAULT '',
-  payload   TEXT DEFAULT '',
-  level     TEXT NOT NULL DEFAULT 'info'   -- v7 telemetry severity: info|warn|error
-);
-
-CREATE INDEX IF NOT EXISTS idx_sources_project  ON sources(project_id);
-CREATE INDEX IF NOT EXISTS idx_evidence_project ON evidence(project_id);
-CREATE INDEX IF NOT EXISTS idx_claims_project   ON claims(project_id);
-CREATE INDEX IF NOT EXISTS idx_artifacts_proj   ON artifacts(project_id);
-CREATE INDEX IF NOT EXISTS idx_events_ts        ON events(ts);
-CREATE INDEX IF NOT EXISTS idx_jobs_enabled     ON jobs(enabled);
-
--- idempotent-write uniqueness (schema v3; named indexes serve both fresh
--- installs and v2 upgrades — keep CREATE TABLEs free of inline UNIQUE)
-CREATE UNIQUE INDEX IF NOT EXISTS uq_queries_content  ON queries(project_id, content_hash);
-CREATE UNIQUE INDEX IF NOT EXISTS uq_evidence_content ON evidence(source_id, content_hash);
-CREATE UNIQUE INDEX IF NOT EXISTS uq_claims_content   ON claims(project_id, content_hash);
-CREATE UNIQUE INDEX IF NOT EXISTS uq_kb_content       ON kb_notes(content_hash);
-
--- v5: skill refs add upserts ON CONFLICT(skill_id, path) — the unique index
--- it depends on was missing since v1 (the command errored on first use)
-CREATE UNIQUE INDEX IF NOT EXISTS uq_skill_refs ON skill_refs(skill_id, path);
+exports.SCHEMA_SQL = `
+-- ---------------------------------------------------------------- meta
+-- runtime state the tool writes itself (current selections, bookkeeping);
+-- user-tunable settings live in config
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- ---------------------------------------------------------------- config (v6)
+-- user-tunable settings; registry (defaults/types/notes) in src/config.ts.
+-- Reads fall back to defaults — an empty table is a valid state.
+CREATE TABLE IF NOT EXISTS config (
+  key     TEXT PRIMARY KEY,
+  value   TEXT NOT NULL DEFAULT '',
+  note    TEXT DEFAULT '',
+  updated TEXT NOT NULL
+);
+
+-- ---------------------------------------------------------------- skills (L1/L2/L3)
+CREATE TABLE IF NOT EXISTS skills (
+  id          TEXT PRIMARY KEY,
+  name        TEXT NOT NULL UNIQUE,
+  version     TEXT DEFAULT '0.1.0',
+  description TEXT NOT NULL DEFAULT '',   -- L1: what + when, always in context
+  body        TEXT NOT NULL DEFAULT '',   -- L2: instructions, loaded on activation
+  tags        TEXT DEFAULT '',
+  origin      TEXT DEFAULT '',            -- where it came from (path/repo)
+  enabled     INTEGER NOT NULL DEFAULT 1,
+  hits        INTEGER NOT NULL DEFAULT 0, -- how often an agent matched it
+  created     TEXT NOT NULL,
+  updated     TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS skill_refs (          -- L3: loaded on demand
+  id       TEXT PRIMARY KEY,
+  skill_id TEXT NOT NULL REFERENCES skills(id) ON DELETE CASCADE,
+  path     TEXT NOT NULL,
+  content  TEXT NOT NULL DEFAULT ''
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS skills_fts USING fts5(
+  id UNINDEXED, name, description, tags, ngram, tokenize='unicode61'
+);
+
+-- ---------------------------------------------------------------- projects
+CREATE TABLE IF NOT EXISTS projects (
+  id         TEXT PRIMARY KEY,
+  name       TEXT NOT NULL UNIQUE,
+  question   TEXT NOT NULL DEFAULT '',
+  inclusion  TEXT DEFAULT '',
+  exclusion  TEXT DEFAULT '',
+  status     TEXT NOT NULL DEFAULT 'active',
+  created    TEXT NOT NULL,
+  updated    TEXT NOT NULL
+);
+
+-- ---------------------------------------------------------------- research: queries
+CREATE TABLE IF NOT EXISTS queries (
+  id           TEXT PRIMARY KEY,
+  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  text         TEXT NOT NULL,
+  engine       TEXT DEFAULT '',
+  status       TEXT NOT NULL DEFAULT 'pending',  -- pending|done
+  note         TEXT DEFAULT '',
+  content_hash TEXT NOT NULL DEFAULT '',         -- sha1(text): idempotent writes
+  created      TEXT NOT NULL
+);
+
+-- ---------------------------------------------------------------- research: sources
+-- query <-> source association: which search query recalled which source
+-- (schema v4; pure additive, no migration needed beyond CREATE IF NOT EXISTS)
+CREATE TABLE IF NOT EXISTS query_sources (
+  query_id  TEXT NOT NULL REFERENCES queries(id) ON DELETE CASCADE,
+  source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+  note      TEXT DEFAULT '',
+  created   TEXT NOT NULL,
+  PRIMARY KEY (query_id, source_id)
+);
+
+CREATE TABLE IF NOT EXISTS sources (
+  id           TEXT PRIMARY KEY,
+  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  url          TEXT DEFAULT '',
+  title        TEXT NOT NULL DEFAULT '',
+  url_hash     TEXT NOT NULL,
+  content_hash TEXT NOT NULL DEFAULT '',
+  abstract     TEXT DEFAULT '',
+  content      TEXT DEFAULT '',
+  engine       TEXT DEFAULT '',
+  relevance    INTEGER NOT NULL DEFAULT 0,   -- 0..5 screening score
+  confidence   TEXT NOT NULL DEFAULT 'B',    -- A|B|C source trust grade
+  tags         TEXT DEFAULT '',
+  created      TEXT NOT NULL DEFAULT '',
+  retrieved_at TEXT NOT NULL,
+  UNIQUE(project_id, url_hash)
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS sources_fts USING fts5(
+  id UNINDEXED, title, abstract, content, ngram, tokenize='unicode61'
+);
+
+-- ---------------------------------------------------------------- research: evidence
+CREATE TABLE IF NOT EXISTS evidence (
+  id           TEXT PRIMARY KEY,
+  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  source_id    TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+  quote        TEXT NOT NULL,
+  note         TEXT DEFAULT '',
+  locator      TEXT DEFAULT '',   -- page / section / offset
+  content_hash TEXT NOT NULL DEFAULT '',  -- sha1(quote): idempotent writes
+  created      TEXT NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS evidence_fts USING fts5(
+  id UNINDEXED, quote, ngram, tokenize='unicode61'
+);
+
+-- ---------------------------------------------------------------- research: claims
+CREATE TABLE IF NOT EXISTS claims (
+  id           TEXT PRIMARY KEY,
+  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  text         TEXT NOT NULL,
+  status       TEXT NOT NULL DEFAULT 'unverified', -- unverified|supported|refuted|contested
+  confidence   TEXT NOT NULL DEFAULT 'B',
+  content_hash TEXT NOT NULL DEFAULT '',           -- sha1(text): idempotent writes
+  created      TEXT NOT NULL,
+  updated      TEXT NOT NULL DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS claim_evidence (
+  claim_id    TEXT NOT NULL REFERENCES claims(id) ON DELETE CASCADE,
+  evidence_id TEXT NOT NULL REFERENCES evidence(id) ON DELETE CASCADE,
+  stance      TEXT NOT NULL DEFAULT 'supports',  -- supports|refutes
+  PRIMARY KEY (claim_id, evidence_id)
+);
+
+-- ---------------------------------------------------------------- production
+CREATE TABLE IF NOT EXISTS artifacts (
+  id         TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  kind       TEXT NOT NULL DEFAULT 'section',  -- outline|section|report|note|spec|design|task
+  title      TEXT NOT NULL DEFAULT '',
+  format     TEXT NOT NULL DEFAULT 'markdown',
+  content    TEXT NOT NULL DEFAULT '',
+  version    INTEGER NOT NULL DEFAULT 1,
+  created    TEXT NOT NULL,
+  updated    TEXT NOT NULL DEFAULT '',
+  meta       TEXT NOT NULL DEFAULT ''          -- v8 JSON envelope: task {"status"}, design {"design_type"}
+);
+
+-- ---------------------------------------------------------------- knowledge base
+CREATE TABLE IF NOT EXISTS kb_notes (
+  id            TEXT PRIMARY KEY,
+  title         TEXT NOT NULL,
+  body          TEXT NOT NULL DEFAULT '',
+  source_url    TEXT DEFAULT '',
+  origin        TEXT DEFAULT '',       -- 'artifact:<id>' | 'note' | 'skill:<id>'
+  tags          TEXT DEFAULT '',
+  confidence    TEXT NOT NULL DEFAULT 'B',
+  reuse         INTEGER NOT NULL DEFAULT 0,
+  content_hash  TEXT NOT NULL DEFAULT '',  -- sha1(title+body): idempotent writes
+  created       TEXT NOT NULL,
+  updated       TEXT NOT NULL
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS kb_fts USING fts5(
+  id UNINDEXED, title, tags, ngram, tokenize='unicode61'
+);
+CREATE TABLE IF NOT EXISTS kb_links (
+  from_id TEXT NOT NULL REFERENCES kb_notes(id) ON DELETE CASCADE,
+  to_id   TEXT NOT NULL REFERENCES kb_notes(id) ON DELETE CASCADE,
+  rel     TEXT NOT NULL DEFAULT 'related',
+  PRIMARY KEY (from_id, to_id, rel)
+);
+
+-- ================================================================ TECH TREE MODEL
+-- A node model covering four things:
+--   1. parent/child structure      -> node_edges (adjacency, source of truth)
+--   2. associations per node       -> node_edges.rel + relations (multi-kind)
+--   3. required vs optional gates  -> node_edges.required + node_conditions
+--   4. indexes for fast queries    -> node_closure (transitive), node_fts, idx_*
+CREATE TABLE IF NOT EXISTS trees (
+  id         TEXT PRIMARY KEY,
+  project_id TEXT REFERENCES projects(id) ON DELETE CASCADE,
+  name       TEXT NOT NULL UNIQUE,
+  note       TEXT DEFAULT '',
+  created    TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS nodes (
+  id         TEXT PRIMARY KEY,
+  tree_id    TEXT NOT NULL REFERENCES trees(id) ON DELETE CASCADE,
+  key        TEXT NOT NULL,                  -- stable id used in save files
+  name       TEXT NOT NULL,
+  kind       TEXT NOT NULL DEFAULT 'tech',   -- tech|skill|upgrade|building|era
+  tier       INTEGER NOT NULL DEFAULT 0,     -- era / depth band for layout
+  cost       REAL NOT NULL DEFAULT 0,
+  cost_unit  TEXT DEFAULT '',
+  payload    TEXT DEFAULT '',                -- JSON: effects, unlocks, metadata
+  tags       TEXT DEFAULT '',
+  created    TEXT NOT NULL,
+  UNIQUE(tree_id, key)
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  id UNINDEXED, key, name, tags, ngram, tokenize='unicode61'
+);
+CREATE INDEX IF NOT EXISTS idx_nodes_tree ON nodes(tree_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_tier ON nodes(tree_id, tier);
+
+-- Adjacency list: the faithful source of truth for the DAG.
+--   rel       parent->child semantics: prereq | unlock | excludes | enables
+--   mode      how multiple parents combine: AND | OR | XOR | NOT
+--   required  1 = must pass (gating)  0 = optional (bonus / discount only)
+CREATE TABLE IF NOT EXISTS node_edges (
+  id         TEXT PRIMARY KEY,
+  tree_id    TEXT NOT NULL REFERENCES trees(id) ON DELETE CASCADE,
+  parent_id  TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  child_id   TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  rel        TEXT NOT NULL DEFAULT 'prereq',
+  mode       TEXT NOT NULL DEFAULT 'AND',
+  required   INTEGER NOT NULL DEFAULT 1,
+  min_level  INTEGER NOT NULL DEFAULT 1,
+  weight     REAL NOT NULL DEFAULT 1,
+  note       TEXT DEFAULT '',
+  created    TEXT NOT NULL DEFAULT '',
+  UNIQUE(parent_id, child_id, rel)
+);
+CREATE INDEX IF NOT EXISTS idx_edge_child  ON node_edges(child_id);
+CREATE INDEX IF NOT EXISTS idx_edge_parent ON node_edges(parent_id);
+CREATE INDEX IF NOT EXISTS idx_edge_req    ON node_edges(child_id, required);
+
+-- Closure table: transitive index for ancestor/descendant queries.
+-- depth 0 = self row, 1 = direct parent, n = n-th ancestor.
+CREATE TABLE IF NOT EXISTS node_closure (
+  tree_id    TEXT NOT NULL,
+  ancestor   TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  descendant TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  depth      INTEGER NOT NULL,
+  PRIMARY KEY (ancestor, descendant)
+);
+CREATE INDEX IF NOT EXISTS idx_closure_desc ON node_closure(descendant);
+CREATE INDEX IF NOT EXISTS idx_closure_anc  ON node_closure(ancestor);
+
+-- Non-structural gates: conditions that are not other nodes.
+-- required=1 blocks unlock; required=0 only modifies cost / grants bonus.
+CREATE TABLE IF NOT EXISTS node_conditions (
+  id       TEXT PRIMARY KEY,
+  node_id  TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  name     TEXT NOT NULL,
+  kind     TEXT NOT NULL DEFAULT 'flag',   -- flag|resource|level|quest|time|expr
+  expr     TEXT NOT NULL DEFAULT '',       -- evaluated against a runtime state
+  op       TEXT NOT NULL DEFAULT '>=',     -- >= | == | <= | != | has
+  value    TEXT NOT NULL DEFAULT '',
+  required INTEGER NOT NULL DEFAULT 1,
+  effect   TEXT NOT NULL DEFAULT 'gate',   -- gate | cost_mul | bonus
+  weight   REAL NOT NULL DEFAULT 1,
+  note     TEXT DEFAULT '',
+  created  TEXT NOT NULL DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS idx_cond_node ON node_conditions(node_id);
+CREATE INDEX IF NOT EXISTS idx_cond_req  ON node_conditions(node_id, required);
+-- (node_conditions.created is added by upgrade8to9 for existing DBs; new DBs get it from upgrade8to9 too since SCHEMA_SQL doesn't declare it inline)
+
+-- Runtime state per context (save slot / player / run).
+CREATE TABLE IF NOT EXISTS node_state (
+  tree_id  TEXT NOT NULL REFERENCES trees(id) ON DELETE CASCADE,
+  context  TEXT NOT NULL DEFAULT 'default',
+  node_id  TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  status   TEXT NOT NULL DEFAULT 'locked',  -- locked|available|unlocked
+  level    INTEGER NOT NULL DEFAULT 0,
+  progress REAL NOT NULL DEFAULT 0,
+  updated  TEXT NOT NULL,
+  PRIMARY KEY (tree_id, context, node_id)
+);
+CREATE INDEX IF NOT EXISTS idx_state_ctx    ON node_state(tree_id, context);
+CREATE INDEX IF NOT EXISTS idx_state_status ON node_state(tree_id, context, status);
+
+-- Denormalized index on nodes, refreshed by the 'node index' command.
+-- topo_order lets "can I research this" skip recursive traversal.
+CREATE TABLE IF NOT EXISTS node_index (
+  tree_id     TEXT PRIMARY KEY REFERENCES trees(id) ON DELETE CASCADE,
+  topo_order  TEXT NOT NULL DEFAULT '',   -- JSON array of node ids
+  tiers       TEXT NOT NULL DEFAULT '',   -- JSON: tier -> [node ids]
+  in_degree   TEXT NOT NULL DEFAULT '',   -- JSON: node id -> required parent count
+  built_at    TEXT NOT NULL,
+  dirty       INTEGER NOT NULL DEFAULT 1
+);
+
+-- ---------------------------------------------------------------- generic graph
+CREATE TABLE IF NOT EXISTS relations (
+  id       TEXT PRIMARY KEY,
+  src_type TEXT NOT NULL, src_id TEXT NOT NULL,
+  dst_type TEXT NOT NULL, dst_id TEXT NOT NULL,
+  rel      TEXT NOT NULL DEFAULT 'related',
+  weight   REAL NOT NULL DEFAULT 1,
+  created  TEXT NOT NULL DEFAULT '',
+  UNIQUE(src_type, src_id, dst_type, dst_id, rel)
+);
+
+-- ---------------------------------------------------------------- scheduling
+CREATE TABLE IF NOT EXISTS jobs (
+  id            TEXT PRIMARY KEY,
+  title         TEXT NOT NULL,
+  command       TEXT NOT NULL,
+  every_minutes INTEGER DEFAULT 0,
+  at            TEXT DEFAULT '',     -- one-shot ISO datetime
+  enabled       INTEGER NOT NULL DEFAULT 1,
+  runs          INTEGER NOT NULL DEFAULT 0,
+  last_run      TEXT DEFAULT '',
+  status        TEXT NOT NULL DEFAULT 'pending',
+  created       TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS runs (
+  id       TEXT PRIMARY KEY,
+  job_id   TEXT NOT NULL REFERENCES jobs(id) ON DELETE CASCADE,
+  started  TEXT NOT NULL,
+  finished TEXT DEFAULT '',
+  rc       INTEGER,
+  output   TEXT DEFAULT ''
+);
+
+-- ---------------------------------------------------------------- audit log
+CREATE TABLE IF NOT EXISTS events (
+  id        TEXT PRIMARY KEY,
+  ts        TEXT NOT NULL,
+  actor     TEXT NOT NULL DEFAULT 'cli',
+  kind      TEXT NOT NULL,
+  entity    TEXT DEFAULT '',
+  entity_id TEXT DEFAULT '',
+  payload   TEXT DEFAULT '',
+  level     TEXT NOT NULL DEFAULT 'info'   -- v7 telemetry severity: info|warn|error
+);
+
+CREATE INDEX IF NOT EXISTS idx_sources_project  ON sources(project_id);
+CREATE INDEX IF NOT EXISTS idx_evidence_project ON evidence(project_id);
+CREATE INDEX IF NOT EXISTS idx_claims_project   ON claims(project_id);
+CREATE INDEX IF NOT EXISTS idx_artifacts_proj   ON artifacts(project_id);
+CREATE INDEX IF NOT EXISTS idx_events_ts        ON events(ts);
+CREATE INDEX IF NOT EXISTS idx_jobs_enabled     ON jobs(enabled);
+
+-- idempotent-write uniqueness (schema v3; named indexes serve both fresh
+-- installs and v2 upgrades — keep CREATE TABLEs free of inline UNIQUE)
+CREATE UNIQUE INDEX IF NOT EXISTS uq_queries_content  ON queries(project_id, content_hash);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_evidence_content ON evidence(source_id, content_hash);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_claims_content   ON claims(project_id, content_hash);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_kb_content       ON kb_notes(content_hash);
+
+-- v5: skill refs add upserts ON CONFLICT(skill_id, path) — the unique index
+-- it depends on was missing since v1 (the command errored on first use)
+CREATE UNIQUE INDEX IF NOT EXISTS uq_skill_refs ON skill_refs(skill_id, path);
 `;
 class DB {
     db;
@@ -401,34 +401,65 @@ class DB {
         const useLock = opts?.lock === true; // opt-in: only the CLI entry point locks
         // P0-2 (real-user incident): single-writer mutex. node-sqlite3-wasm has no
         // concurrent-write protection; two CLI processes writing simultaneously
-        // corrupted the DB ("malformed"). The .db.lock dir mechanism already
-        // exists (job tick uses it) — reuse it: if another process holds the lock,
-        // fail fast with a clear message instead of silently corrupting.
-        const lockDir = `${file}.lock`;
+        // corrupted the DB ("malformed"). App-level dir lock with pid file +
+        // stale steal + friendly error.
+        //
+        // NAME COLLISION (0.65.0 P0): node-sqlite3-wasm's Node VFS implements
+        // sqlite's own file-lock protocol with exactly `${file}.lock` (mkdir on
+        // lock, EEXIST → SQLITE_BUSY, rmdir on unlock). An app lock using that
+        // name made every locked open fail BUSY on itself. Ours is `.ygllock` —
+        // the wasm protocol dir stays untouched.
+        const legacyLockDir = `${file}.lock`;
+        if (fs.existsSync(path.join(legacyLockDir, "pid"))) {
+            // orphaned 0.65.0 app-layer lock (wasm protocol dirs are empty — a pid
+            // file marks it as ours) would block wasm forever; remove it.
+            try {
+                fs.rmSync(legacyLockDir, { recursive: true, force: true });
+            }
+            catch { /* */ }
+        }
+        const lockDir = `${file}.ygllock`;
         if (useLock && fs.existsSync(lockDir)) {
             let holder = "unknown";
             try {
                 holder = fs.readFileSync(path.join(lockDir, "pid"), "utf8").trim();
             }
             catch { /* */ }
-            // stale lock (>15 min) — steal it (same policy as job tick)
-            try {
-                const st = fs.statSync(lockDir);
-                if (Date.now() - st.mtimeMs > 15 * 60 * 1000) {
-                    fs.rmSync(lockDir, { recursive: true, force: true });
+            // Same-process re-entry backstop (0.65.0 self-deadlock lesson).
+            const mine = holder === String(process.pid);
+            // PID liveness (P1 cold-user report): the 15-minute mtime window was a
+            // blunt proxy — on Windows the exit-time rmSync can silently fail (EBUSY
+            // from an un-released handle), leaving an orphaned lock whose mtime is
+            // recent. A dead holder means the lock is garbage regardless of mtime;
+            // a live holder means it is real regardless of mtime.
+            //   signal 0 = pure existence check (does NOT kill the process)
+            //   EPERM   = exists but permission-denied (Windows ACL) — still alive
+            //   ESRCH   = no such process — dead, steal the lock
+            let holderAlive;
+            if (mine)
+                holderAlive = false; // our own stale entry — always steal
+            else {
+                try {
+                    process.kill(Number(holder), 0);
+                    holderAlive = true;
                 }
-                else {
-                    throw new Error(`database is locked by another process (pid: ${holder}).\n` +
-                        `  lock: ${lockDir}\n` +
-                        `  if no other ygl-trees is running, remove it:  rmdir "${lockDir}"\n` +
-                        `  (stale locks auto-clear after 15 minutes)`);
+                catch (e) {
+                    holderAlive = e.code === "EPERM"; // EPERM = alive (Windows), ESRCH = dead
                 }
             }
-            catch (e) {
-                if (String(e.message).includes("locked by another"))
-                    throw e;
-                // statSync/readFile failed but lock exists — still fail safe
-                throw new Error(`database is locked: ${lockDir} (holder unreadable)`);
+            if (!holderAlive) {
+                // Orphaned lock (holder crashed / exit cleanup failed) — steal now.
+                try {
+                    fs.rmSync(lockDir, { recursive: true, force: true });
+                }
+                catch { /* */ }
+            }
+            else {
+                throw new Error(`database is locked by another process (pid: ${holder}).\n` +
+                    `  lock: ${lockDir}\n` +
+                    `  if this is a webui serve dashboard, it shares WAL safely — CLI reads work,\n` +
+                    `  write commands need the serve process stopped (or YGL_TEST=1 to bypass)\n` +
+                    `  if no other ygl-trees is running, remove it:  rmdir "${lockDir}"`);
             }
         }
         // acquire the lock (best-effort; crash cleanup via stale detection above)
@@ -436,12 +467,23 @@ class DB {
             try {
                 fs.mkdirSync(lockDir, { recursive: true });
                 fs.writeFileSync(path.join(lockDir, "pid"), String(process.pid));
-                // belt-and-suspenders: release on ANY process exit path (normal, signal, crash)
-                const self = this;
-                process.on("exit", () => { try {
-                    fs.rmSync(lockDir, { recursive: true, force: true });
-                }
-                catch { /* */ } });
+                // P1 cold-user report (Windows): `process.on("exit")` rmSync can silently
+                // fail when the SQLite handle hasn't been released yet (EBUSY on the dir).
+                // Two mitigations:
+                //   1. beforeExit fires earlier (while the event loop is still alive)
+                //   2. PID liveness check (above) makes any residual lock self-healing —
+                //      the NEXT process sees a dead PID and clears it immediately.
+                const cleanup = () => {
+                    for (let i = 0; i < 3; i++) { // retry: Windows may need a tick
+                        try {
+                            fs.rmSync(lockDir, { recursive: true, force: true });
+                            return;
+                        }
+                        catch { /* */ }
+                    }
+                };
+                process.on("beforeExit", cleanup);
+                process.on("exit", cleanup);
             }
             catch { /* lock creation failure is non-fatal (read-only scenarios) */ }
         this.db = new node_sqlite3_wasm_1.Database(file);
@@ -456,7 +498,7 @@ class DB {
     /** Release the write lock (called by close() and process exit). */
     releaseLock() {
         try {
-            const lockDir = `${this.path}.lock`;
+            const lockDir = `${this.path}.ygllock`;
             if (fs.existsSync(lockDir))
                 fs.rmSync(lockDir, { recursive: true, force: true });
         }
@@ -465,7 +507,7 @@ class DB {
     /** Static: force-release a lock (for cleanup hooks). */
     static releaseLockFor(file) {
         try {
-            const lockDir = `${file}.lock`;
+            const lockDir = `${file}.ygllock`;
             if (fs.existsSync(lockDir))
                 fs.rmSync(lockDir, { recursive: true, force: true });
         }
@@ -478,19 +520,19 @@ class DB {
         }
         catch (e) {
             if (String(e.message).includes("malformed") || String(e.message).includes("not a database")) {
-                throw new Error(`database corrupted: ${this.path}
+                throw new Error(`database corrupted: ${this.path}
 ` +
-                    `  ${e.message}
+                    `  ${e.message}
 ` +
-                    `  
+                    `  
 ` +
-                    `  自愈路径（库可随时从源文件重建）：
+                    `  自愈路径（库可随时从源文件重建）：
 ` +
-                    `  1. 备份损坏库：  cp "${this.path}" "${this.path}.corrupt.bak"
+                    `  1. 备份损坏库：  cp "${this.path}" "${this.path}.corrupt.bak"
 ` +
-                    `  2. 重置：        ygl-trees db reset
+                    `  2. 重置：        ygl-trees db reset
 ` +
-                    `  3. 重新导入：    ygl-trees db init && ygl-trees kb import <源目录>
+                    `  3. 重新导入：    ygl-trees db init && ygl-trees kb import <源目录>
 ` +
                     `     （kb 笔记全部有源 .md 文件在盘上，库只是索引）`);
             }