@jaimevalasek/aioson 1.8.0 → 1.9.0

package/src/learning-loop-migration.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * Active Learning Loop — schema migration runner.
+ *
+ * Idempotent. Safe to call on every openRuntimeDb. Each phase appends steps
+ * to runMigration. All steps use IF NOT EXISTS or guards so legacy v1.x DBs
+ * (AC-ALL-103) acquire new structures without ALTER on existing columns.
+ *
+ * Phase 1: partial index over execution_events for context:load queries.
+ * Phase 2: FTS5 virtual table over project_learnings + 3 sync triggers + backfill.
+ * Phase 3: validity-window columns on evolution_log + 3 indexes.
+ */
+
+// Phase 3 — evolution_log validity-window columns (requirements § M1).
+// ALTER TABLE ... ADD COLUMN is O(1) on SQLite ≥3.25 and preserves legacy rows
+// (existing squad-learning entries keep event_type=NULL, interpreted as
+// 'legacy_squad' by convention). CHECKs are enforced in application code, not in
+// the schema, because SQLite does not support ALTER TABLE ADD CONSTRAINT.
+const PHASE3_COLUMNS = [
+  'event_type TEXT',
+  'target_type TEXT',
+  'target_id TEXT',
+  'start_at TEXT',
+  'end_at TEXT',
+  'reason TEXT',
+  'actor TEXT',
+  'feature_slug TEXT',
+  'payload_json TEXT'
+];
+
+const PHASE3_INDEXES = [
+  `CREATE INDEX IF NOT EXISTS idx_evolution_log_target
+     ON evolution_log(target_type, target_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_evolution_log_active
+     ON evolution_log(target_type, target_id, end_at)
+     WHERE end_at IS NULL`,
+  `CREATE INDEX IF NOT EXISTS idx_evolution_log_feature
+     ON evolution_log(feature_slug, event_type)`
+];
+
+function listColumns(db, table) {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+  return new Set(rows.map((r) => r.name));
+}
+
+const PHASE2_STEPS = [
+  // FTS5 virtual table — external content over project_learnings.
+  // FTS5 columns kept minimal (title, evidence) per requirements § E1; remaining
+  // metadata (target_type, target_id, feature_slug, status) is JOINed at query
+  // time. content_rowid='rowid' binds the FTS5 entries to the source table.
+  `CREATE VIRTUAL TABLE IF NOT EXISTS project_learnings_fts USING fts5(
+     title,
+     evidence,
+     content='project_learnings',
+     content_rowid='rowid',
+     tokenize='unicode61 remove_diacritics 2'
+   )`,
+  // Sync triggers — transactional (BR-ALL-07). 'delete' command on FTS5
+  // contentless/external tables removes the entry without storing content.
+  `CREATE TRIGGER IF NOT EXISTS project_learnings_ai
+   AFTER INSERT ON project_learnings BEGIN
+     INSERT INTO project_learnings_fts(rowid, title, evidence)
+     VALUES (new.rowid, new.title, new.evidence);
+   END`,
+  `CREATE TRIGGER IF NOT EXISTS project_learnings_ad
+   AFTER DELETE ON project_learnings BEGIN
+     INSERT INTO project_learnings_fts(project_learnings_fts, rowid, title, evidence)
+     VALUES ('delete', old.rowid, old.title, old.evidence);
+   END`,
+  `CREATE TRIGGER IF NOT EXISTS project_learnings_au
+   AFTER UPDATE ON project_learnings BEGIN
+     INSERT INTO project_learnings_fts(project_learnings_fts, rowid, title, evidence)
+     VALUES ('delete', old.rowid, old.title, old.evidence);
+     INSERT INTO project_learnings_fts(rowid, title, evidence)
+     VALUES (new.rowid, new.title, new.evidence);
+   END`
+];
+
+// PRAGMA user_version sentinel — set once after the migration completes so
+// that subsequent `openRuntimeDb` calls (which invoke this function on every
+// open) skip the IF NOT EXISTS / PRAGMA table_info probes. Bump this constant
+// when a new Phase adds steps to runMigration; the next call against an older
+// DB will then re-run all idempotent steps and update the sentinel.
+const SCHEMA_VERSION = 3;
+
+function readUserVersion(db) {
+  const row = db.prepare('PRAGMA user_version').get();
+  if (!row) return 0;
+  // sqlite returns { user_version: N }
+  return Number(row.user_version || 0);
+}
+
+function runMigration(db) {
+  if (!db || typeof db.exec !== 'function') {
+    throw new Error('runMigration requires an open better-sqlite3 database handle');
+  }
+
+  // Fast path: if the DB already carries the current schema version, skip the
+  // idempotent probes. Saves ~100ms p99 on tight `openRuntimeDb` loops.
+  const currentVersion = readUserVersion(db);
+  if (currentVersion >= SCHEMA_VERSION) return;
+
+  // Phase 1 — partial index over execution_events for context:load lookups.
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_execution_events_context_load
+    ON execution_events(event_type, agent_name)
+    WHERE event_type IN ('rule_loaded', 'brain_loaded');
+  `);
+
+  // Phase 2 — FTS5 + triggers. Requires the project_learnings source table to
+  // already exist. In the live openRuntimeDb flow that is guaranteed (CREATE TABLE
+  // runs before this migration). Synthetic legacy-DB fixtures may not have it; skip
+  // gracefully in that case so AC-ALL-103 (v1.x compatibility) still holds.
+  const hasProjectLearnings = db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='project_learnings'")
+    .get();
+
+  if (hasProjectLearnings) {
+    for (const stmt of PHASE2_STEPS) {
+      db.exec(stmt);
+    }
+
+    // Backfill guarded by count check — runs once when FTS5 is fresh.
+    const fts = db.prepare('SELECT COUNT(*) AS c FROM project_learnings_fts').get();
+    if (fts && Number(fts.c) === 0) {
+      const src = db.prepare('SELECT COUNT(*) AS c FROM project_learnings').get();
+      if (src && Number(src.c) > 0) {
+        db.exec(`
+          INSERT INTO project_learnings_fts(rowid, title, evidence)
+          SELECT rowid, title, evidence FROM project_learnings
+        `);
+      }
+    }
+  }
+
+  // Phase 3 — evolution_log validity-window columns + 3 indexes.
+  // The squad-learning evolution_log table is created earlier in
+  // runtime-store.js#ensureLegacyColumns, so we can ALTER it directly.
+  // Synthetic legacy fixtures may not have the table — skip in that case so
+  // AC-ALL-103 (v1.x compatibility) still holds.
+  const hasEvolutionLog = db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='evolution_log'")
+    .get();
+
+  if (hasEvolutionLog) {
+    const existing = listColumns(db, 'evolution_log');
+    for (const colSpec of PHASE3_COLUMNS) {
+      const colName = colSpec.split(/\s+/)[0];
+      if (!existing.has(colName)) {
+        db.exec(`ALTER TABLE evolution_log ADD COLUMN ${colSpec}`);
+      }
+    }
+    for (const stmt of PHASE3_INDEXES) {
+      db.exec(stmt);
+    }
+  }
+
+  // Stamp the sentinel so subsequent opens take the fast path.
+  db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+}
+
+module.exports = { runMigration };

package/src/lib/dev-resume.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * dev-resume — build the resume payload @dev consumes when starting a new chat.
+ *
+ * Returns null if no in-progress feature is detected (so @dev knows it is a
+ * cold start). Otherwise returns an envelope with:
+ *   - feature_slug, classification, current_phase
+ *   - artifacts_consumed (from last-handoff.json artifact_uris, v2 form)
+ *   - code_map_paths (from dossier ## Code Map files[].path)
+ *   - sheldon_plan (path if .aioson/plans/{slug}/manifest.md exists)
+ *   - next_step (from dev-state.md or derived from plan manifest)
+ */
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const { parseCodeMapBlock, parseYamlCodeMap } = require('../dossier/codemap-store');
+const {
+  parseFeaturesTable,
+  parseFrontmatterField
+} = require('../commands/dossier-audit');
+
+async function readFileOrNull(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function readJsonOrNull(filePath) {
+  const raw = await readFileOrNull(filePath);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function readClassificationFromFrontmatters(rawList) {
+  for (const raw of rawList) {
+    if (!raw) continue;
+    const cls = parseFrontmatterField(raw, 'classification');
+    if (cls) return cls.toUpperCase();
+  }
+  return null;
+}
+
+function extractDevStateFields(raw) {
+  if (!raw) return { active_phase: null, next_step: null };
+  const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fmMatch) return { active_phase: null, next_step: null };
+  const fm = {};
+  for (const line of fmMatch[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const val = line.slice(idx + 1).trim().replace(/^["']|["']$/g, '');
+    fm[key] = val;
+  }
+  return {
+    active_phase: fm.active_phase || null,
+    next_step: fm.next_step || null
+  };
+}
+
+function extractCodeMapPaths(dossierRaw) {
+  if (!dossierRaw) return [];
+  const block = parseCodeMapBlock(dossierRaw);
+  if (!block) return [];
+  const yamlText = dossierRaw.slice(block.codeStart, block.codeEnd);
+  const map = parseYamlCodeMap(yamlText);
+  if (!Array.isArray(map.files)) return [];
+  const paths = map.files
+    .map((f) => (f && typeof f.path === 'string' ? f.path : null))
+    .filter(Boolean);
+  return Array.from(new Set(paths));
+}
+
+function deriveNextStepFromPlan(planRaw) {
+  if (!planRaw) return null;
+  const lines = planRaw.split('\n');
+  for (const line of lines) {
+    const m = line.match(/^[-*]\s+\[\s*\]\s+(.+)$/);
+    if (m) return m[1].trim();
+  }
+  return null;
+}
+
+async function buildDevResumeData(projectPath) {
+  const targetDir = path.resolve(projectPath || '.');
+  const ctxDir = path.join(targetDir, '.aioson', 'context');
+
+  const lastHandoff = await readJsonOrNull(path.join(ctxDir, 'last-handoff.json'));
+  const featureSlug = lastHandoff && lastHandoff.feature_slug ? lastHandoff.feature_slug : null;
+  if (!featureSlug) return null;
+
+  const featuresRaw = await readFileOrNull(path.join(ctxDir, 'features.md'));
+  const features = featuresRaw ? parseFeaturesTable(featuresRaw) : [];
+  const feature = features.find((f) => f.slug === featureSlug);
+  if (!feature || feature.status !== 'in_progress') return null;
+
+  const dossierPath = path.join(ctxDir, 'features', featureSlug, 'dossier.md');
+  const dossierRaw = await readFileOrNull(dossierPath);
+
+  const prdRaw = await readFileOrNull(path.join(ctxDir, `prd-${featureSlug}.md`));
+  const specRaw = await readFileOrNull(path.join(ctxDir, `spec-${featureSlug}.md`));
+  const classification = readClassificationFromFrontmatters([dossierRaw, prdRaw, specRaw]);
+
+  const devStateRaw = await readFileOrNull(path.join(ctxDir, 'dev-state.md'));
+  const { active_phase, next_step: devStateNext } = extractDevStateFields(devStateRaw);
+
+  const planManifestPath = path.join(targetDir, '.aioson', 'plans', featureSlug, 'manifest.md');
+  const planRaw = await readFileOrNull(planManifestPath);
+  const sheldonPlan = planRaw ? `.aioson/plans/${featureSlug}/manifest.md` : null;
+
+  const artifactsConsumed = Array.isArray(lastHandoff && lastHandoff.artifact_uris)
+    ? lastHandoff.artifact_uris
+    : [];
+
+  return {
+    feature_slug: featureSlug,
+    classification,
+    current_phase: active_phase || 'unknown',
+    artifacts_consumed: artifactsConsumed,
+    code_map_paths: extractCodeMapPaths(dossierRaw),
+    sheldon_plan: sheldonPlan,
+    next_step: devStateNext || deriveNextStepFromPlan(planRaw)
+  };
+}
+
+module.exports = {
+  buildDevResumeData,
+  extractDevStateFields,
+  extractCodeMapPaths,
+  deriveNextStepFromPlan
+};

package/src/lib/dossier-telemetry.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { openRuntimeDb } = require('../runtime-store');
+const { logAgentEvent } = require('../runtime-store');
+
+/**
+ * Emit a single runtime event for dossier auto-init lifecycle.
+ *
+ * Silent: failures are swallowed (telemetry must never break the calling flow).
+ * Used by feature-close.js and workflow-next.js to report:
+ *   - feature_close_dossier_synthesized (mode: from-existing | minimal-fallback)
+ *   - dossier_auto_initialized (trigger: workflow-next | product-prompt)
+ *   - sync_agents_parity_violation
+ */
+async function emitDossierEvent(targetDir, { agent, type, summary, meta }) {
+  try {
+    const { db } = await openRuntimeDb(targetDir);
+    try {
+      await logAgentEvent(db, null, {
+        agentName: agent,
+        message: summary || '',
+        type,
+        summary,
+        meta,
+        finish: false
+      });
+    } finally {
+      db.close();
+    }
+  } catch {
+    // Telemetry failures must not break the calling flow. The dashboard misses
+    // one event; the user-visible operation continues.
+  }
+}
+
+module.exports = { emitDossierEvent };