@smartmemory/compose 0.1.1-beta → 0.1.2-beta

package/server/open-loops-store.js

@@ -0,0 +1,102 @@
+/**
+ * open-loops-store.js — COMP-OBS-LOOPS persistence layer.
+ *
+ * Reads/writes item.lifecycle.lifecycle_ext.open_loops[] via the existing
+ * updateLifecycleExt path (same as BRANCH for branch_lineage).
+ *
+ * Design decisions:
+ *   - Server fills id (UUID v4), created_at, parent_feature from item.lifecycle.featureCode.
+ *   - parent_feature is REQUIRED by schema — route returns 400 if item lacks featureCode.
+ *   - Append-only: resolution is set in-place; entries are never deleted.
+ *   - isStaleLoop is exported here and imported by status-snapshot.js so the
+ *     panel and STATUS agree on the stale predicate (Decision 3).
+ */
+
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Returns true if a loop is unresolved and past its TTL.
+ * @param {object} loop — OpenLoop object
+ * @param {number} nowMs — epoch ms (Date.parse result or Date.now())
+ */
+export function isStaleLoop(loop, nowMs) {
+  if (loop.resolution) return false; // resolved — never stale
+  const ttl = loop.ttl_days ?? 90;
+  const ageMs = nowMs - Date.parse(loop.created_at);
+  return ageMs > ttl * 24 * 60 * 60 * 1000;
+}
+
+/**
+ * Add an OpenLoop to an item.
+ * The caller must persist the result via store.updateLifecycleExt(item.id, 'open_loops', next).
+ *
+ * @param {object} item — vision store item (must have lifecycle.featureCode)
+ * @param {{ kind, summary, parent_branch?, ttl_days? }} fields
+ * @returns {{ loop: OpenLoop, nextLoops: OpenLoop[] }}
+ * @throws {Error} if item has no featureCode (400 guard)
+ */
+export function addOpenLoop(item, { kind, summary, parent_branch, ttl_days }) {
+  const featureCode = item.lifecycle?.featureCode;
+  if (!featureCode) {
+    throw Object.assign(new Error('item has no lifecycle.featureCode — cannot create feature-scoped open loop'), { status: 400 });
+  }
+
+  const loop = {
+    id: randomUUID(),
+    kind,
+    summary,
+    created_at: new Date().toISOString(),
+    parent_feature: featureCode,
+    parent_branch: parent_branch ?? null,
+    resolution: null,
+    ttl_days: ttl_days ?? 90,
+  };
+
+  const existing = item.lifecycle?.lifecycle_ext?.open_loops ?? [];
+  const nextLoops = [...existing, loop];
+  return { loop, nextLoops };
+}
+
+/**
+ * Resolve an open loop in place.
+ * @param {object} item — vision store item
+ * @param {string} loopId
+ * @param {{ note: string, resolved_by: string }} resolution
+ * @returns {{ loop: OpenLoop, nextLoops: OpenLoop[] }}
+ * @throws {Error} if loopId not found (404) or already resolved (400)
+ */
+export function resolveOpenLoop(item, loopId, { note, resolved_by }) {
+  const existing = item.lifecycle?.lifecycle_ext?.open_loops ?? [];
+  const idx = existing.findIndex(l => l.id === loopId);
+  if (idx === -1) {
+    throw Object.assign(new Error(`loop not found: ${loopId}`), { status: 404 });
+  }
+  const loop = existing[idx];
+  if (loop.resolution !== null && loop.resolution !== undefined) {
+    throw Object.assign(new Error(`loop already resolved: ${loopId}`), { status: 400 });
+  }
+
+  const resolved = {
+    ...loop,
+    resolution: {
+      resolved_at: new Date().toISOString(),
+      resolved_by: resolved_by || 'unknown',
+      note: note || '',
+    },
+  };
+
+  const nextLoops = existing.map((l, i) => (i === idx ? resolved : l));
+  return { loop: resolved, nextLoops };
+}
+
+/**
+ * List open loops for an item.
+ * @param {object} item
+ * @param {{ includeResolved?: boolean }} opts
+ * @returns {OpenLoop[]}
+ */
+export function listOpenLoops(item, { includeResolved = false } = {}) {
+  const loops = item.lifecycle?.lifecycle_ext?.open_loops ?? [];
+  if (includeResolved) return [...loops];
+  return loops.filter(l => l.resolution == null);
+}

package/server/schema-validator.js

@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = resolve(__dirname, '../contracts/comp-obs-contract.schema.json');
+
+let cached = null;
+
+function load() {
+  if (cached) return cached;
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+  const ajv = new Ajv({ strict: false, allErrors: true });
+  addFormats(ajv);
+  ajv.addSchema(schema);
+  cached = { schema, ajv };
+  return cached;
+}
+
+export class SchemaValidator {
+  constructor() {
+    const { schema, ajv } = load();
+    this.schema = schema;
+    this.ajv = ajv;
+    this._validators = new Map();
+  }
+
+  _getValidator(defName) {
+    if (this._validators.has(defName)) return this._validators.get(defName);
+    if (!this.schema.definitions || !(defName in this.schema.definitions)) {
+      throw new Error(`unknown schema definition: ${defName}`);
+    }
+    const ref = `${this.schema.$id}#/definitions/${defName}`;
+    let v = this.ajv.getSchema(ref);
+    if (!v) v = this.ajv.compile({ $ref: ref });
+    this._validators.set(defName, v);
+    return v;
+  }
+
+  validate(defName, obj) {
+    const v = this._getValidator(defName);
+    const valid = v(obj);
+    return { valid: !!valid, errors: valid ? [] : (v.errors || []) };
+  }
+}
+
+export const SCHEMA_VERSION = load().schema.version;

package/server/status-emit.js

@@ -0,0 +1,27 @@
+/**
+ * status-emit.js — COMP-OBS-STATUS broadcast dispatcher (A2).
+ *
+ * Single choke point: emitStatusSnapshot(broadcastMessage, state, featureCode, now)
+ * Recomputes the StatusSnapshot from current store state and broadcasts:
+ *   { type: 'statusSnapshot', featureCode, snapshot }
+ *
+ * Returns the snapshot for caller convenience (mirrors decision-event-emit.js pattern).
+ * No caching — recomputed on every call. The snapshot is cheap (~200 bytes, single scan).
+ */
+
+import { computeStatusSnapshot } from './status-snapshot.js';
+
+/**
+ * Emit a StatusSnapshot broadcast.
+ *
+ * @param {function} broadcastMessage — fn(msg) to dispatch to all WS clients
+ * @param {object}   state            — VisionStore (getItemByFeatureCode, getPendingGates)
+ * @param {string|null} featureCode   — the feature whose snapshot to recompute
+ * @param {string}   [now]            — ISO timestamp (defaults to Date.now())
+ * @returns {StatusSnapshot}
+ */
+export function emitStatusSnapshot(broadcastMessage, state, featureCode, now) {
+  const snapshot = computeStatusSnapshot(state, featureCode, now || new Date().toISOString());
+  broadcastMessage({ type: 'statusSnapshot', featureCode, snapshot });
+  return snapshot;
+}

package/server/status-snapshot.js

@@ -0,0 +1,218 @@
+/**
+ * status-snapshot.js — COMP-OBS-STATUS producer (A1).
+ *
+ * Pure function: computeStatusSnapshot(state, featureCode, now) → StatusSnapshot
+ *
+ * Decision 2 (design.md): 8 rule branches, first-match wins.
+ *   1. No feature selected  → "Select a feature to see status."
+ *   2. Killed               → "{fc} killed. No further action."
+ *   3. Complete             → "{fc} complete."
+ *   4. Pending gate         → "Holding {phase}. Next: approve {gateId}."
+ *   5. Drift breach         → "{phase} — N drift alert(s)."
+ *   6. Stale open loops     → "{phase}. N loop(s) past TTL."
+ *   7. Iteration in flight  → "Iterating {loopType} (attempt {count})."
+ *   8. Idle baseline        → "Building {phase}. Open loops: {count}."
+ *
+ * Null/unknown phase fallbacks (Decision 2 note):
+ *   - null phase + feature selected → "{fc}: phase pending."
+ *   - unknown phase string          → "{fc}: {phase} (unrecognized phase)."
+ *   Both short-circuit branches 4–7.
+ */
+
+import { readGateLog } from './gate-log-store.js';
+import { isStaleLoop } from './open-loops-store.js';
+
+// Known lifecycle phases — must match LIFECYCLE_PHASE_LABELS in constants.js
+const KNOWN_PHASES = new Set([
+  'explore_design', 'prd', 'architecture', 'blueprint',
+  'verification', 'plan', 'execute', 'report', 'docs', 'ship',
+  'complete', 'killed',
+]);
+
+const TERMINAL_PHASES = new Set(['complete', 'killed']);
+const MAX_SENTENCE = 280;
+
+/**
+ * Truncate a string to fit within `headroom` chars, appending '…' if cut.
+ * If the string already fits, it is returned unchanged.
+ */
+export function truncateForSentence(s, headroom) {
+  if (s.length <= headroom) return s;
+  if (headroom <= 1) return '…';
+  return s.slice(0, headroom - 1) + '…';
+}
+
+/**
+ * Build the sentence string from Decision 2 branches.
+ *
+ * @param {object} params
+ * @param {string|null} featureCode
+ * @param {string|null} activePhase
+ * @param {Array}  pendingGates  — gate objects with .id
+ * @param {Array}  driftAlerts   — breached DriftAxis objects
+ * @param {number} staleLoopCount
+ * @param {object|null} iterationState — lifecycle.iterationState
+ * @param {boolean} featureExists — whether the feature was found in the store
+ */
+function buildStatusSentence({
+  featureCode,
+  activePhase,
+  pendingGates,
+  driftAlerts,
+  staleLoopCount,
+  iterationState,
+  openLoopsCount,
+  featureExists,
+}) {
+  // Branch 1: no feature selected
+  if (!featureCode || !featureExists) {
+    return 'Select a feature to see status.';
+  }
+
+  // Null phase guard (Decision 2 note) — short-circuits 4–7
+  if (activePhase === null || activePhase === undefined) {
+    return `${featureCode}: phase pending.`;
+  }
+
+  // Unknown phase guard — short-circuits 4–7
+  if (!KNOWN_PHASES.has(activePhase)) {
+    return truncateForSentence(`${featureCode}: ${activePhase} (unrecognized phase).`, MAX_SENTENCE);
+  }
+
+  // Branch 2: killed (terminal, checked BEFORE non-terminal branches)
+  if (activePhase === 'killed') {
+    return `${featureCode} killed. No further action.`;
+  }
+
+  // Branch 3: complete (terminal)
+  if (activePhase === 'complete') {
+    return `${featureCode} complete.`;
+  }
+
+  // Branch 4: pending gate
+  if (pendingGates.length > 0) {
+    const gateId = pendingGates[0].id;
+    const prefix = `Holding ${activePhase}. Next: approve `;
+    const suffix = '.';
+    const headroom = MAX_SENTENCE - prefix.length - suffix.length;
+    const gateIdShort = truncateForSentence(gateId, headroom);
+    return `${prefix}${gateIdShort}${suffix}`;
+  }
+
+  // Branch 5: drift breach
+  if (driftAlerts.length > 0) {
+    const n = driftAlerts.length;
+    const s = n === 1 ? '' : 's';
+    return truncateForSentence(`${activePhase} — ${n} drift alert${s}.`, MAX_SENTENCE);
+  }
+
+  // Branch 6: stale open loops
+  if (staleLoopCount > 0) {
+    const n = staleLoopCount;
+    const s = n === 1 ? '' : 's';
+    return truncateForSentence(`${activePhase}. ${n} loop${s} past TTL.`, MAX_SENTENCE);
+  }
+
+  // Branch 7: iteration in flight
+  if (iterationState?.status === 'running') {
+    const { loopType, count } = iterationState;
+    return truncateForSentence(`Iterating ${loopType} (attempt ${count}).`, MAX_SENTENCE);
+  }
+
+  // Branch 8: idle baseline
+  return truncateForSentence(`Building ${activePhase}. Open loops: ${openLoopsCount}.`, MAX_SENTENCE);
+}
+
+/**
+ * Compute a full StatusSnapshot for the given featureCode from current store state.
+ *
+ * @param {object} state — VisionStore (must expose getItemByFeatureCode, getPendingGates)
+ * @param {string|null} featureCode
+ * @param {string} now — ISO timestamp (injected for testability)
+ * @returns {StatusSnapshot}
+ */
+export function computeStatusSnapshot(state, featureCode, now) {
+  const nowStr = now || new Date().toISOString();
+
+  // No feature selected → branch 1 baseline
+  if (!featureCode) {
+    return {
+      sentence: 'Select a feature to see status.',
+      active_goal: null,
+      active_phase: null,
+      pending_gates: [],
+      drift_alerts: [],
+      open_loops_count: 0,
+      gate_load_24h: 0, // TODO: real value when COMP-OBS-GATELOG ships
+      cta: null,
+      computed_at: nowStr,
+    };
+  }
+
+  const item = state.getItemByFeatureCode(featureCode);
+
+  // Feature not found in store — return no-feature snapshot
+  if (!item) {
+    return {
+      sentence: 'Select a feature to see status.',
+      active_goal: null,
+      active_phase: null,
+      pending_gates: [],
+      drift_alerts: [],
+      open_loops_count: 0,
+      gate_load_24h: 0,
+      cta: null,
+      computed_at: nowStr,
+    };
+  }
+
+  const lc = item.lifecycle;
+  const activePhase = lc?.currentPhase ?? null;
+  const ext = lc?.lifecycle_ext ?? {};
+
+  // Pending gates for this item
+  const pendingGates = state.getPendingGates(item.id);
+  const pendingGateIds = pendingGates.map(g => g.id);
+
+  // Drift alerts: only axes with breached:true
+  const driftAxes = ext.drift_axes ?? [];
+  const driftAlerts = driftAxes.filter(a => a.breached === true);
+
+  // Open loops — only unresolved entries count (COMP-OBS-LOOPS semantic fix)
+  const openLoops = ext.open_loops ?? [];
+  const openLoopsCount = openLoops.filter(l => l.resolution == null).length;
+
+  // Stale open loops: unresolved and past TTL — use shared isStaleLoop helper
+  const nowMs = Date.parse(nowStr);
+  const staleLoops = openLoops.filter(loop => isStaleLoop(loop, nowMs));
+  const staleLoopCount = staleLoops.length;
+
+  const iterationState = lc?.iterationState ?? null;
+
+  // Is active phase known? (for null/unknown guard)
+  const phaseKnown = activePhase === null || KNOWN_PHASES.has(activePhase);
+
+  // Build sentence — pass iterationState only when phase is non-terminal+known
+  const sentence = buildStatusSentence({
+    featureCode,
+    activePhase,
+    pendingGates,
+    driftAlerts,
+    staleLoopCount,
+    iterationState: phaseKnown && !TERMINAL_PHASES.has(activePhase) ? iterationState : null,
+    openLoopsCount,
+    featureExists: true,
+  });
+
+  return {
+    sentence,
+    active_goal: item.title || null,
+    active_phase: activePhase,
+    pending_gates: pendingGateIds,
+    drift_alerts: driftAlerts,
+    open_loops_count: openLoopsCount,
+    gate_load_24h: readGateLog({ since: nowMs - 86400000 }).length,
+    cta: null,
+    computed_at: nowStr,
+  };
+}