@maintainabilityai/research-runner 0.1.1

package/dist/runner/audit-emitter.js

@@ -0,0 +1,210 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditEmitter = void 0;
+exports.readAuditLog = readAuditLog;
+exports.verifyChain = verifyChain;
+/**
+ * AuditEmitter — append-only JSONL writer with SHA-256 hash chain.
+ *
+ * Every node in both pipelines emits one event through this emitter; the
+ * emitter:
+ *   1. Assigns `event_id` (1, 2, 3, …) and `prev_event_hash` (sha256 of the
+ *      previous event's full serialization).
+ *   2. Computes `event_hash` (sha256 of this event with `event_hash` set to
+ *      the canonical placeholder `''`).
+ *   3. Appends the serialized event as one JSON line to
+ *      `<audit-dir>/<run_id>.jsonl`.
+ *
+ * The chain is tamper-evident: changing any past event breaks every
+ * subsequent `prev_event_hash`. The `run_complete` event pins the chain
+ * root hash (= the final event's event_hash) so auditors only need to
+ * verify one number to trust the whole run.
+ *
+ * Hash computation is deterministic regardless of object key order: we
+ * canonicalize via a recursive key-sorted JSON stringify before hashing.
+ */
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const schemas_1 = require("../schemas");
+const PLACEHOLDER_HASH = '0'.repeat(64);
+/** Recursively sort object keys so JSON.stringify produces a canonical form. */
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = canonicalize(obj[key]);
+    }
+    return sorted;
+}
+function sha256(text) {
+    return (0, node_crypto_1.createHash)('sha256').update(text, 'utf8').digest('hex');
+}
+/** Hash an event with `event_hash` zeroed out so the hash itself is part of the JSON body. */
+function hashEventBody(event) {
+    const placeholderEvent = { ...event, event_hash: PLACEHOLDER_HASH };
+    return sha256(JSON.stringify(canonicalize(placeholderEvent)));
+}
+class AuditEmitter {
+    runId;
+    filePath;
+    nextEventId = 1;
+    prevEventHash = null;
+    rootHash = null;
+    closed = false;
+    /**
+     * @param auditDir   target directory (created on demand)
+     * @param runId      the run id; becomes `<runId>.jsonl`
+     */
+    constructor(auditDir, runId) {
+        this.runId = runId;
+        fs.mkdirSync(auditDir, { recursive: true });
+        this.filePath = path.join(auditDir, `${runId}.jsonl`);
+        // Refuse to clobber an existing run's audit file — log immutability is load-bearing.
+        if (fs.existsSync(this.filePath)) {
+            throw new Error(`Audit log already exists at ${this.filePath}; refusing to overwrite.`);
+        }
+        // Touch the file so concurrent readers see it.
+        fs.writeFileSync(this.filePath, '', { flag: 'wx' });
+    }
+    /**
+     * Emit one event. Returns the canonical serialized form (useful for tests).
+     * Validates against the AuditEvent schema before writing.
+     */
+    emit(input) {
+        if (this.closed) {
+            throw new Error('AuditEmitter is closed; cannot emit further events.');
+        }
+        const ts = input.ts ?? new Date().toISOString();
+        // Build with a placeholder hash, hash, then overwrite event_hash with the real hash.
+        const draft = {
+            ...input,
+            run_id: this.runId,
+            event_id: this.nextEventId,
+            ts,
+            prev_event_hash: this.prevEventHash,
+            event_hash: PLACEHOLDER_HASH,
+        };
+        const parsed = schemas_1.AuditEvent.parse(draft);
+        const eventHash = hashEventBody(parsed);
+        const finalEvent = { ...parsed, event_hash: eventHash };
+        fs.appendFileSync(this.filePath, JSON.stringify(finalEvent) + '\n', 'utf8');
+        this.nextEventId += 1;
+        this.prevEventHash = eventHash;
+        this.rootHash = eventHash;
+        if (finalEvent.node_kind === 'run_complete') {
+            this.closed = true;
+        }
+        return finalEvent;
+    }
+    /**
+     * Emit a `run_complete` event. The emitter computes `chain_root_hash` itself
+     * (the hash of the run_complete event), so callers leave that field blank
+     * (or omit it) — it's filled in here.
+     */
+    emitRunComplete(input) {
+        const enriched = {
+            ...input,
+            outcome: { ...input.outcome, chain_root_hash: PLACEHOLDER_HASH },
+        };
+        const event = this.emit(enriched);
+        // The emitted event_hash IS the chain root by definition — rewrite the
+        // outcome.chain_root_hash to that value on the in-memory record we return.
+        // (The serialized line on disk uses the placeholder for chain_root_hash;
+        // we keep it that way so the event_hash matches the line. Auditors
+        // verify the chain root by hashing the line as written.)
+        return { ...event, outcome: { ...event.outcome, chain_root_hash: event.event_hash } };
+    }
+    /** SHA-256 of the most recent event — equal to `chain_root_hash` after run_complete. */
+    get currentRootHash() {
+        return this.rootHash;
+    }
+    /** Absolute path to the JSONL file this emitter writes to. */
+    get path() {
+        return this.filePath;
+    }
+}
+exports.AuditEmitter = AuditEmitter;
+/**
+ * Parse a JSONL audit file back into typed events. Re-validates every event
+ * against the schema; returns null on malformed input.
+ */
+function readAuditLog(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        const lines = raw.split('\n').filter(l => l.trim().length > 0);
+        const events = [];
+        for (const line of lines) {
+            const parsed = schemas_1.AuditEvent.parse(JSON.parse(line));
+            events.push(parsed);
+        }
+        return events;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify the hash chain of a sequence of events.
+ *   - Each event's prev_event_hash must match the previous event's event_hash.
+ *   - Each event's event_hash must match a recomputation against the line.
+ *   - The first event must have prev_event_hash === null.
+ * Returns the chain root hash (= final event_hash) on success, null on any failure.
+ */
+function verifyChain(events) {
+    let prev = null;
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (e.prev_event_hash !== prev) {
+            return null;
+        }
+        const recomputed = hashEventBody(e);
+        if (e.event_hash !== recomputed) {
+            return null;
+        }
+        if (e.event_id !== i + 1) {
+            return null;
+        }
+        prev = e.event_hash;
+    }
+    return prev;
+}

package/dist/runner/hatters-tag-builder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Hatter's Tag — versioned, signed-style YAML block appended to every
+ * research / PRD artifact. Auditors use it to verify the artifact against
+ * the recorded mesh sha + prompt-library version + audit chain root.
+ *
+ * Format choice: hand-rolled YAML emitter (no js-yaml dependency) because
+ * the shape is fixed and the values are scalar — strings, numbers, dates,
+ * and one nested object for guardrails. Keeps the package zero-runtime-dep
+ * beyond zod.
+ *
+ * Output is always wrapped in a ```yaml fenced code block so it renders
+ * cleanly in GitHub PR bodies + the rendered docs site.
+ */
+import type { GuardrailMode, LlmProvider } from '../schemas';
+export interface HattersTagInput {
+    run_id: string;
+    /** Git SHA of the mesh repo at run start. */
+    mesh_sha: string;
+    /** Semver of the .caterpillar/prompts library. */
+    prompt_library_version: string;
+    /** Semver of @maintainabilityai/research-runner. */
+    agent_version: string;
+    llm: {
+        provider: LlmProvider;
+        model: string;
+        input_tokens: number;
+        output_tokens: number;
+        cost_usd: number;
+    };
+    guardrails: {
+        mode: GuardrailMode;
+        blocks: number;
+        warns: number;
+    };
+    /** Present on PRDs; omitted on research docs. */
+    grounding?: {
+        final_score: number;
+        threshold: number;
+        iterations: number;
+        passed: boolean;
+    };
+    audit: {
+        event_count: number;
+        chain_root_hash: string;
+        /** Path to the JSONL audit file relative to mesh root. */
+        audit_log_path: string;
+    };
+    /** ISO timestamp the artifact was published (PR created). */
+    published_at: string;
+}
+/** Build the full Hatter's Tag block, including heading + fenced YAML. */
+export declare function buildHattersTag(input: HattersTagInput): string;

package/dist/runner/hatters-tag-builder.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHattersTag = buildHattersTag;
+/** Build the full Hatter's Tag block, including heading + fenced YAML. */
+function buildHattersTag(input) {
+    const lines = [];
+    lines.push('## Hatter’s Tag');
+    lines.push('');
+    lines.push('```yaml');
+    lines.push(`run_id: ${input.run_id}`);
+    lines.push(`mesh_sha: ${input.mesh_sha}`);
+    lines.push(`prompt_library_version: ${input.prompt_library_version}`);
+    lines.push(`agent_version: ${input.agent_version}`);
+    lines.push(`published_at: ${input.published_at}`);
+    lines.push('llm:');
+    lines.push(`  provider: ${input.llm.provider}`);
+    lines.push(`  model: ${input.llm.model}`);
+    lines.push(`  input_tokens: ${input.llm.input_tokens}`);
+    lines.push(`  output_tokens: ${input.llm.output_tokens}`);
+    lines.push(`  cost_usd: ${input.llm.cost_usd.toFixed(4)}`);
+    lines.push('guardrails:');
+    lines.push(`  mode: ${input.guardrails.mode}`);
+    lines.push(`  blocks: ${input.guardrails.blocks}`);
+    lines.push(`  warns: ${input.guardrails.warns}`);
+    if (input.grounding) {
+        lines.push('grounding:');
+        lines.push(`  final_score: ${input.grounding.final_score.toFixed(4)}`);
+        lines.push(`  threshold: ${input.grounding.threshold.toFixed(2)}`);
+        lines.push(`  iterations: ${input.grounding.iterations}`);
+        lines.push(`  passed: ${input.grounding.passed}`);
+    }
+    lines.push('audit:');
+    lines.push(`  event_count: ${input.audit.event_count}`);
+    lines.push(`  chain_root_hash: ${input.audit.chain_root_hash}`);
+    lines.push(`  audit_log_path: ${input.audit.audit_log_path}`);
+    lines.push('```');
+    lines.push('');
+    lines.push('> **How to verify this artifact yourself:** check out the mesh at the recorded `mesh_sha`, replay the audit log at `audit_log_path`, and confirm the final event’s `event_hash` matches `chain_root_hash`.');
+    return lines.join('\n');
+}

package/dist/runner/nodes/analyze-architecture.d.ts

@@ -0,0 +1,10 @@
+import type { ObservedArchitecture } from '../../schemas';
+import type { FileInventory } from './clone-and-index';
+export interface AnalyzeArchitectureOpts {
+    cloneDir: string;
+    targetRepo: string;
+    cloneSha: string;
+    inventory: FileInventory;
+}
+export declare const ANALYZER_VERSION = "file-based-v1";
+export declare function analyzeArchitecture(opts: AnalyzeArchitectureOpts): ObservedArchitecture;