@smartmemory/compose 0.1.1-beta → 0.1.2-beta

package/lib/bug-ledger.js

@@ -0,0 +1,126 @@
+/**
+ * bug-ledger.js — COMP-FIX-HARD hypothesis ledger persistence.
+ *
+ * Persists hypothesis entries to docs/bugs/<bug-code>/hypotheses.jsonl
+ * (append-only JSONL). One JSON object per line.
+ *
+ * Idempotent on (attempt, ts): repeated writes with the same key are skipped
+ * (the first writer wins). Tolerates malformed lines on read (skip + warn).
+ *
+ * Pattern reference: server/gate-log-store.js (gate log JSONL helpers).
+ *
+ * Entry shape:
+ *   Required: attempt (number), ts (ISO string), hypothesis (string),
+ *             verdict ('confirmed' | 'rejected' | 'inconclusive')
+ *   Optional: evidence_for[], evidence_against[], next_to_try, agent,
+ *             tokens_used, findings[]
+ */
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+/**
+ * Resolve the on-disk path for a bug's hypothesis ledger.
+ * @param {string} cwd      — repository root
+ * @param {string} bugCode  — bug identifier (e.g. "BUG-123")
+ * @returns {string} absolute path to hypotheses.jsonl
+ */
+export function getHypothesesPath(cwd, bugCode) {
+  return join(cwd, 'docs', 'bugs', bugCode, 'hypotheses.jsonl');
+}
+
+/**
+ * Append one hypothesis entry to the bug's ledger.
+ * Idempotent: if an entry with the same (attempt, ts) already exists, the
+ * write is skipped. Creates the parent directory if missing.
+ *
+ * @param {string} cwd
+ * @param {string} bugCode
+ * @param {object} entry — must have attempt, ts, hypothesis, verdict
+ */
+export function appendHypothesisEntry(cwd, bugCode, entry) {
+  const filePath = getHypothesesPath(cwd, bugCode);
+  mkdirSync(dirname(filePath), { recursive: true });
+
+  // Idempotency check: scan existing entries for matching (attempt, ts).
+  // Volume per bug is small so a linear scan is fine.
+  if (existsSync(filePath)) {
+    const raw = readFileSync(filePath, 'utf8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const obj = JSON.parse(trimmed);
+        if (obj.attempt === entry.attempt && obj.ts === entry.ts) return; // already written
+      } catch {
+        // malformed line — skip
+      }
+    }
+  }
+
+  appendFileSync(filePath, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+/**
+ * Read all hypothesis entries for a bug.
+ * Returns [] if the file does not exist. Tolerates malformed lines: each
+ * unparseable line is skipped with a stderr warning, valid lines returned.
+ *
+ * @param {string} cwd
+ * @param {string} bugCode
+ * @returns {object[]}
+ */
+export function readHypotheses(cwd, bugCode) {
+  const filePath = getHypothesesPath(cwd, bugCode);
+  if (!existsSync(filePath)) return [];
+
+  const raw = readFileSync(filePath, 'utf8');
+  const entries = [];
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      console.warn('[bug-ledger] malformed line skipped:', trimmed.slice(0, 80));
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Render rejected hypotheses as a markdown block, suitable for splicing into
+ * a bug-fix prompt so the next attempt avoids re-trying dead ends.
+ *
+ * Returns "" if the input has no entries with verdict === 'rejected'.
+ *
+ * @param {object[]} entries
+ * @returns {string}
+ */
+export function formatRejectedHypotheses(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return '';
+  const rejected = entries.filter((e) => e && e.verdict === 'rejected');
+  if (rejected.length === 0) return '';
+
+  const blocks = rejected.map((e) => {
+    const lines = [];
+    lines.push(`### Attempt ${e.attempt} (${e.ts})`);
+    lines.push(`**Hypothesis:** ${e.hypothesis}`);
+    if (Array.isArray(e.evidence_against) && e.evidence_against.length > 0) {
+      lines.push('**Evidence against:**');
+      for (const ev of e.evidence_against) lines.push(`- ${ev}`);
+    }
+    if (Array.isArray(e.evidence_for) && e.evidence_for.length > 0) {
+      lines.push('**Evidence for:**');
+      for (const ev of e.evidence_for) lines.push(`- ${ev}`);
+    }
+    if (e.next_to_try) {
+      lines.push(`**Next to try:** ${e.next_to_try}`);
+    }
+    return lines.join('\n');
+  });
+
+  return ['## Previously Rejected Hypotheses', '', ...blocks].join('\n\n') + '\n';
+}

package/lib/build-stream-schema.js

@@ -0,0 +1,176 @@
+/**
+ * build-stream-schema.js — JSON Schema validator for BuildStreamEvent envelopes.
+ *
+ * STRAT-PAR-STREAM-CONSUMER-VALIDATE: validates incoming progress notifications
+ * in stratum-mcp-client.js#dispatchEvent against the v0.2.6 envelope schema.
+ *
+ * Design decisions:
+ * - Uses AJV (already in compose deps) compiled once at module load.
+ * - On validation failure the caller should warn+drop — never throw.
+ * - KNOWN_VERSIONS: set of accepted schema_version strings. v0.2.5 accepted for
+ *   one-cycle backward compatibility; v0.2.6 is current.
+ * - reply_required (Option A, STRAT-PAR-STREAM-CONSUMER-VALIDATE design):
+ *   optional boolean reserved for future gate/permission/question kinds.
+ */
+
+import Ajv2020 from 'ajv/dist/2020.js';
+
+export const KNOWN_VERSIONS = new Set(['0.2.5', '0.2.6']);
+
+// ---------------------------------------------------------------------------
+// Envelope schema (top-level fields only; metadata shape is kind-specific)
+// ---------------------------------------------------------------------------
+
+const ENVELOPE_SCHEMA = {
+  type: 'object',
+  required: ['schema_version', 'flow_id', 'step_id', 'seq', 'ts', 'kind', 'metadata'],
+  // Closed envelope — matches the producer contract exactly (events.py + build-stream-event.v0.2.6.schema.json).
+  // Unknown top-level fields are rejected so envelope-level producer drift is caught.
+  additionalProperties: false,
+  properties: {
+    schema_version: { type: 'string' },
+    flow_id:        { type: 'string' },
+    step_id:        { type: 'string' },
+    seq:            { type: 'integer', minimum: 0 },
+    ts:             { type: 'string' },
+    kind:           { type: 'string' },
+    // task_id is optional (omitted when null by producer — events.py#to_json drops None).
+    // Type is string only; null task_id should be omitted, not sent.
+    task_id:        { type: 'string' },
+    reply_required: { type: 'boolean' },
+    metadata:       { type: 'object' },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Per-kind closed metadata schemas (v0.2.6 CONTRACT)
+// Source of truth: stratum-mcp/contracts/build-stream-event.v0.2.6.schema.json
+// ---------------------------------------------------------------------------
+
+const KIND_METADATA_SCHEMAS = {
+  capability_profile: {
+    type: 'object',
+    required: ['agent', 'template'],
+    additionalProperties: false,
+    properties: {
+      agent:           { type: 'string' },
+      template:        { type: ['string', 'null'] },
+      allowedTools:    { type: ['array', 'null'], items: { type: 'string' } },
+      disallowedTools: { type: ['array', 'null'], items: { type: 'string' } },
+    },
+  },
+  capability_violation: {
+    type: 'object',
+    required: ['agent', 'template', 'detail', 'severity'],
+    additionalProperties: false,
+    properties: {
+      agent:    { type: 'string' },
+      template: { type: ['string', 'null'] },
+      detail:   { type: 'string' },
+      severity: { type: 'string', enum: ['violation', 'warning'] },
+    },
+  },
+  step_usage: {
+    type: 'object',
+    required: ['stepId', 'input_tokens', 'output_tokens', 'cost_usd'],
+    additionalProperties: false,
+    properties: {
+      stepId:                      { type: 'string' },
+      input_tokens:                { type: 'number', minimum: 0 },
+      output_tokens:               { type: 'number', minimum: 0 },
+      cache_creation_input_tokens: { type: 'number', minimum: 0 },
+      cache_read_input_tokens:     { type: 'number', minimum: 0 },
+      cost_usd:                    { type: 'number', minimum: 0 },
+      model:                       { type: ['string', 'null'] },
+    },
+  },
+  gate_tier_result: {
+    type: 'object',
+    required: ['stepId', 'tierId', 'passed'],
+    additionalProperties: false,
+    properties: {
+      stepId:  { type: 'string' },
+      tierId:  { type: 'string' },
+      passed:  { type: 'boolean' },
+      details: { type: ['string', 'null'] },
+    },
+  },
+  health_score: {
+    type: 'object',
+    required: ['score', 'breakdown'],
+    additionalProperties: false,
+    properties: {
+      score:     { type: 'number', minimum: 0, maximum: 100 },
+      breakdown: { type: 'object', additionalProperties: { type: 'number' } },
+      missing:   { type: 'array', items: { type: 'string' } },
+    },
+  },
+  build_end: {
+    type: 'object',
+    required: ['status', 'featureCode'],
+    additionalProperties: false,
+    properties: {
+      status:              { type: 'string', enum: ['complete', 'killed', 'crashed', 'failed'] },
+      featureCode:         { type: 'string' },
+      total_input_tokens:  { type: 'number', minimum: 0 },
+      total_output_tokens: { type: 'number', minimum: 0 },
+      total_cost_usd:      { type: 'number', minimum: 0 },
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// AJV setup — compile once (Ajv2020 for draft-2020-12 feature support)
+// ---------------------------------------------------------------------------
+
+const ajv = new Ajv2020({ strict: false });
+const validateEnvelope = ajv.compile(ENVELOPE_SCHEMA);
+
+const compiledKindValidators = new Map(
+  Object.entries(KIND_METADATA_SCHEMAS).map(([kind, schema]) => [kind, ajv.compile(schema)])
+);
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a parsed BuildStreamEvent envelope.
+ *
+ * Returns { valid: true } on success.
+ * Returns { valid: false, error: string } on failure.
+ *
+ * Validation rules:
+ * 1. Envelope must pass top-level schema (required fields, correct types).
+ * 2. schema_version must be a known accepted version.
+ * 3. If the kind has a closed metadata schema, metadata must pass it.
+ *
+ * @param {object} envelope  Parsed event object
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateBuildStreamEvent(envelope) {
+  // 1. Top-level envelope shape
+  if (!validateEnvelope(envelope)) {
+    const errMsg = ajv.errorsText(validateEnvelope.errors);
+    return { valid: false, error: `envelope schema: ${errMsg}` };
+  }
+
+  // 2. schema_version check (accepts both 0.2.5 for backward compat and 0.2.6)
+  if (!KNOWN_VERSIONS.has(envelope.schema_version)) {
+    return {
+      valid: false,
+      error: `unknown schema_version "${envelope.schema_version}" (accepted: ${[...KNOWN_VERSIONS].join(', ')})`,
+    };
+  }
+
+  // 3. Kind-specific metadata validation (only for the 6 closed kinds)
+  const kindValidator = compiledKindValidators.get(envelope.kind);
+  if (kindValidator) {
+    if (!kindValidator(envelope.metadata)) {
+      const errMsg = ajv.errorsText(kindValidator.errors);
+      return { valid: false, error: `metadata for kind "${envelope.kind}": ${errMsg}` };
+    }
+  }
+
+  return { valid: true };
+}

package/lib/build-stream-writer.js

@@ -94,14 +94,16 @@ export class BuildStreamWriter {
    * @param {string} agent        Full agent string
    * @param {string} templateName Active template name
    * @param {string} detail       Description of the violation
+   * @param {'violation'|'warning'} [severity='violation']  Severity from checkCapabilityViolation
    */
-  writeViolation(stepId, agent, templateName, detail) {
+  writeViolation(stepId, agent, templateName, detail, severity = 'violation') {
     this.write({
       type: 'capability_violation',
       stepId,
       agent,
       template: templateName,
       detail,
+      severity,
     });
   }