@maintainabilityai/research-runner 0.1.1

package/dist/schemas/audit-event.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditEvent = void 0;
+/**
+ * AuditEvent — the hash-chained JSONL events written to
+ * `.research-audit/<run_id>.jsonl` by every node in both pipelines.
+ *
+ * Discriminated by `node_kind`. The common envelope at the top of every
+ * variant carries the chain: `prev_event_hash` + `event_hash`, both
+ * SHA-256. The first event in a run has `prev_event_hash: null`. The
+ * `run_complete` event closes the run with a chain root hash.
+ *
+ * See docs/design/research-and-prd-agents.md §"Audit schema — per-node
+ * JSONL events" for the canonical definitions.
+ */
+const zod_1 = require("zod");
+const primitives_1 = require("./primitives");
+/** Common envelope present on every event (NOT a partial — shared base). */
+const Envelope = zod_1.z.object({
+    run_id: primitives_1.RunId,
+    /** Monotonically incrementing within a run, starting at 1. */
+    event_id: zod_1.z.number().int().positive(),
+    ts: primitives_1.IsoTimestamp,
+    node_name: zod_1.z.string().min(1),
+    duration_ms: zod_1.z.number().int().nonnegative(),
+    /** SHA-256 of the previous serialized event (without its own event_hash). Null on event 1. */
+    prev_event_hash: primitives_1.Sha256.nullable(),
+    /** SHA-256 of THIS event with `event_hash` set to the empty string. */
+    event_hash: primitives_1.Sha256,
+});
+/** `pure_api` — deterministic external HTTP call (Tavily, arXiv, USPTO, HN, GitHub REST). */
+const PureApiEvent = Envelope.extend({
+    node_kind: zod_1.z.literal('pure_api'),
+    api: zod_1.z.object({
+        provider: zod_1.z.string(),
+        endpoint: zod_1.z.string(),
+        /** Redacted query / body — secrets must NOT appear here. */
+        request_summary: zod_1.z.string(),
+        http_status: zod_1.z.number().int(),
+        response_byte_count: zod_1.z.number().int().nonnegative(),
+    }),
+});
+/** `llm` — non-deterministic LLM call (plan_queries, synthesize, expert reviews). */
+const LlmEvent = Envelope.extend({
+    node_kind: zod_1.z.literal('llm'),
+    llm: zod_1.z.object({
+        provider: primitives_1.LlmProvider,
+        model: zod_1.z.string(),
+        prompt_pack: zod_1.z.object({
+            /** Path relative to mesh root, e.g. `.caterpillar/prompts/research/synthesis.md@v1.0.0`. */
+            path: zod_1.z.string(),
+            sha256: primitives_1.Sha256,
+        }),
+        input_tokens: zod_1.z.number().int().nonnegative(),
+        output_tokens: zod_1.z.number().int().nonnegative(),
+        /** USD cost estimate. */
+        cost_usd: zod_1.z.number().nonnegative(),
+        /** Guardrail decisions for this hop. */
+        guardrails: zod_1.z.object({
+            mode: primitives_1.GuardrailMode,
+            pre: zod_1.z.enum(['PASS', 'WARN', 'BLOCK']),
+            post: zod_1.z.enum(['PASS', 'WARN', 'BLOCK']),
+        }),
+    }),
+});
+/** `pure` — local-only deterministic computation (validate, dedupe, structural check). */
+const PureEvent = Envelope.extend({
+    node_kind: zod_1.z.literal('pure'),
+    pure: zod_1.z.object({
+        inputs_summary: zod_1.z.string(),
+        outputs_summary: zod_1.z.string(),
+    }),
+});
+/** `node_error` — any node failure, before any retry. */
+const NodeErrorEvent = Envelope.extend({
+    node_kind: zod_1.z.literal('node_error'),
+    error: zod_1.z.object({
+        message: zod_1.z.string(),
+        /** Optional stack — redacted of secrets. */
+        stack: zod_1.z.string().optional(),
+        retryable: zod_1.z.boolean(),
+    }),
+});
+/**
+ * `iteration_summary` — emitted once per PRD refinement loop iteration after
+ * `verify_grounding` resolves. Carries the 4 reviewer signals + composite +
+ * verdict in one place so the published PRD can render a score-progression
+ * table without re-parsing earlier events.
+ */
+const IterationSummaryEvent = Envelope.extend({
+    node_kind: zod_1.z.literal('iteration_summary'),
+    iteration: zod_1.z.number().int().min(1).max(5),
+    summary: zod_1.z.object({
+        det_arch: zod_1.z.object({
+            severity: zod_1.z.enum(['PASS', 'MINOR', 'MAJOR']),
+            invalid_citations: zod_1.z.number().int().nonnegative(),
+            coverage_discrepancies: zod_1.z.number().int().nonnegative(),
+        }),
+        det_sec: zod_1.z.object({
+            severity: zod_1.z.enum(['PASS', 'MINOR', 'MAJOR']),
+            invalid_citations: zod_1.z.number().int().nonnegative(),
+            coverage_discrepancies: zod_1.z.number().int().nonnegative(),
+        }),
+        llm_arch: zod_1.z.object({
+            score: zod_1.z.number().min(0).max(1),
+            severity: zod_1.z.enum(['PASS', 'MINOR', 'MAJOR', 'BLOCKING']),
+        }),
+        llm_sec: zod_1.z.object({
+            score: zod_1.z.number().min(0).max(1),
+            severity: zod_1.z.enum(['PASS', 'MINOR', 'MAJOR', 'BLOCKING']),
+        }),
+        composite_score: zod_1.z.number().min(0).max(1),
+        /** |llm_arch.score - llm_sec.score| — used by verify_grounding for the disagreement rule. */
+        disagreement_delta: zod_1.z.number().min(0).max(1),
+        verdict: zod_1.z.enum(['PASS', 'ITERATE', 'EXHAUSTED']),
+        reason: zod_1.z.string(),
+    }),
+});
+/** `run_complete` — final event emitted by verify_and_trigger. Closes the chain. */
+const RunCompleteEvent = Envelope.extend({
+    node_kind: zod_1.z.literal('run_complete'),
+    outcome: zod_1.z.object({
+        status: zod_1.z.enum(['ok', 'failed', 'partial']),
+        mesh_sha: primitives_1.GitSha,
+        total_input_tokens: zod_1.z.number().int().nonnegative(),
+        total_output_tokens: zod_1.z.number().int().nonnegative(),
+        total_cost_usd: zod_1.z.number().nonnegative(),
+        artifact_paths: zod_1.z.array(zod_1.z.string()),
+        pr_url: zod_1.z.string().url().optional(),
+        /** SHA-256 of the entire chain (the last event's event_hash). */
+        chain_root_hash: primitives_1.Sha256,
+    }),
+});
+exports.AuditEvent = zod_1.z.discriminatedUnion('node_kind', [
+    PureApiEvent,
+    LlmEvent,
+    PureEvent,
+    NodeErrorEvent,
+    IterationSummaryEvent,
+    RunCompleteEvent,
+]);

package/dist/schemas/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public schema surface for @maintainabilityai/research-runner.
+ *
+ * Importers should reference schemas through this barrel so internal file
+ * reorganisation doesn't break downstream code.
+ */
+export * from './primitives';
+export * from './research-brief';
+export * from './mesh-context';
+export * from './query-plan';
+export * from './ranked-source';
+export * from './research-doc';
+export * from './prd-brief';
+export * from './prd-doc';
+export * from './prd-manifest';
+export * from './audit-event';
+export * from './observed-architecture';

package/dist/schemas/index.js

@@ -0,0 +1,33 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Public schema surface for @maintainabilityai/research-runner.
+ *
+ * Importers should reference schemas through this barrel so internal file
+ * reorganisation doesn't break downstream code.
+ */
+__exportStar(require("./primitives"), exports);
+__exportStar(require("./research-brief"), exports);
+__exportStar(require("./mesh-context"), exports);
+__exportStar(require("./query-plan"), exports);
+__exportStar(require("./ranked-source"), exports);
+__exportStar(require("./research-doc"), exports);
+__exportStar(require("./prd-brief"), exports);
+__exportStar(require("./prd-doc"), exports);
+__exportStar(require("./prd-manifest"), exports);
+__exportStar(require("./audit-event"), exports);
+__exportStar(require("./observed-architecture"), exports);

package/dist/schemas/mesh-context.d.ts

@@ -0,0 +1,415 @@
+/**
+ * MeshContext — what `gather_mesh_context` produces for every LLM node.
+ *
+ * Mirrors the shape defined in the design doc (§"gather_mesh_context — the
+ * mesh IS the expert"). Every LLM call in both the Archeologist and PRD
+ * pipelines receives this as its grounding payload.
+ */
+import { z } from 'zod';
+/** Structural gap kinds the GovernanceScorer detects per BAR. */
+export declare const MeshGapKind: z.ZodEnum<["no_threat_model", "no_controls_mapping", "no_adrs", "stale_research", "missing_prd_for_planned_feature", "low_architecture_pillar", "low_security_pillar"]>;
+export type MeshGapKind = z.infer<typeof MeshGapKind>;
+export declare const MeshContext: z.ZodObject<{
+    scope: z.ZodObject<{
+        level: z.ZodEnum<["platform", "bar"]>;
+        bar_id: z.ZodOptional<z.ZodString>;
+        platform_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        level: "platform" | "bar";
+        bar_id?: string | undefined;
+        platform_id?: string | undefined;
+    }, {
+        level: "platform" | "bar";
+        bar_id?: string | undefined;
+        platform_id?: string | undefined;
+    }>;
+    /** Git SHA of the mesh repo at the moment context was read. */
+    mesh_sha: z.ZodString;
+    /** Always populated. */
+    portfolio: z.ZodObject<{
+        name: z.ZodString;
+        governance_policy: z.ZodUnknown;
+        capability_models: z.ZodArray<z.ZodUnknown, "many">;
+        related_research_summaries: z.ZodArray<z.ZodObject<{
+            research_id: z.ZodString;
+            topic: z.ZodString;
+            published_at: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        capability_models: unknown[];
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        governance_policy?: unknown;
+    }, {
+        name: string;
+        capability_models: unknown[];
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        governance_policy?: unknown;
+    }>;
+    /** Populated when level is platform OR bar. */
+    platform: z.ZodNullable<z.ZodObject<{
+        platform_id: z.ZodString;
+        architecture: z.ZodUnknown;
+        sibling_bars: z.ZodArray<z.ZodObject<{
+            bar_id: z.ZodString;
+            name: z.ZodString;
+            composite_score: z.ZodNumber;
+            /** owner/repo entries parsed from each sibling BAR's app.yaml. */
+            linked_repos: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            /** CALM node ids the BAR owns. Used by generate-prd-manifest's
+             *  impact classification to decide whether a sibling is HIGH
+             *  confidence (one of these nodes is referenced by an endpoint)
+             *  or LOW (no citation overlap). */
+            calm_node_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            /** Threat ids declared in the BAR's threat-model.yaml. Used by the
+             *  same impact classification to flag siblings whose threats are
+             *  cited by the PRD's security requirements. */
+            threat_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            bar_id: string;
+            name: string;
+            composite_score: number;
+            linked_repos: string[];
+            calm_node_ids: string[];
+            threat_ids: string[];
+        }, {
+            bar_id: string;
+            name: string;
+            composite_score: number;
+            linked_repos?: string[] | undefined;
+            calm_node_ids?: string[] | undefined;
+            threat_ids?: string[] | undefined;
+        }>, "many">;
+        related_research_summaries: z.ZodArray<z.ZodObject<{
+            research_id: z.ZodString;
+            topic: z.ZodString;
+            published_at: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        platform_id: string;
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        sibling_bars: {
+            bar_id: string;
+            name: string;
+            composite_score: number;
+            linked_repos: string[];
+            calm_node_ids: string[];
+            threat_ids: string[];
+        }[];
+        architecture?: unknown;
+    }, {
+        platform_id: string;
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        sibling_bars: {
+            bar_id: string;
+            name: string;
+            composite_score: number;
+            linked_repos?: string[] | undefined;
+            calm_node_ids?: string[] | undefined;
+            threat_ids?: string[] | undefined;
+        }[];
+        architecture?: unknown;
+    }>>;
+    /** Populated only when level is bar. */
+    bar: z.ZodNullable<z.ZodObject<{
+        bar_id: z.ZodString;
+        name: z.ZodString;
+        composite_score: z.ZodNumber;
+        tier: z.ZodEnum<["restricted", "supervised", "autonomous"]>;
+        calm_model: z.ZodUnknown;
+        threats: z.ZodNullable<z.ZodUnknown>;
+        controls: z.ZodNullable<z.ZodUnknown>;
+        adrs: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            status: z.ZodString;
+            decision: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            status: string;
+            id: string;
+            title: string;
+            decision: string;
+        }, {
+            status: string;
+            id: string;
+            title: string;
+            decision: string;
+        }>, "many">;
+        pillar_scores: z.ZodObject<{
+            architecture: z.ZodNumber;
+            security: z.ZodNumber;
+            info_risk: z.ZodNumber;
+            operations: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            architecture: number;
+            security: number;
+            info_risk: number;
+            operations: number;
+        }, {
+            architecture: number;
+            security: number;
+            info_risk: number;
+            operations: number;
+        }>;
+        related_research: z.ZodArray<z.ZodObject<{
+            research_id: z.ZodString;
+            topic: z.ZodString;
+            published_at: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }>, "many">;
+        related_prds: z.ZodArray<z.ZodObject<{
+            research_id: z.ZodString;
+            topic: z.ZodString;
+            published_at: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }, {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }>, "many">;
+        mesh_gaps: z.ZodArray<z.ZodEnum<["no_threat_model", "no_controls_mapping", "no_adrs", "stale_research", "missing_prd_for_planned_feature", "low_architecture_pillar", "low_security_pillar"]>, "many">;
+        /** owner/repo entries parsed from app.yaml application.repos — drives PrdManifest.target_repos. */
+        linked_repos: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        bar_id: string;
+        name: string;
+        composite_score: number;
+        linked_repos: string[];
+        tier: "restricted" | "supervised" | "autonomous";
+        adrs: {
+            status: string;
+            id: string;
+            title: string;
+            decision: string;
+        }[];
+        pillar_scores: {
+            architecture: number;
+            security: number;
+            info_risk: number;
+            operations: number;
+        };
+        related_research: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        related_prds: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        mesh_gaps: ("no_threat_model" | "no_controls_mapping" | "no_adrs" | "stale_research" | "missing_prd_for_planned_feature" | "low_architecture_pillar" | "low_security_pillar")[];
+        calm_model?: unknown;
+        threats?: unknown;
+        controls?: unknown;
+    }, {
+        bar_id: string;
+        name: string;
+        composite_score: number;
+        tier: "restricted" | "supervised" | "autonomous";
+        adrs: {
+            status: string;
+            id: string;
+            title: string;
+            decision: string;
+        }[];
+        pillar_scores: {
+            architecture: number;
+            security: number;
+            info_risk: number;
+            operations: number;
+        };
+        related_research: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        related_prds: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        mesh_gaps: ("no_threat_model" | "no_controls_mapping" | "no_adrs" | "stale_research" | "missing_prd_for_planned_feature" | "low_architecture_pillar" | "low_security_pillar")[];
+        linked_repos?: string[] | undefined;
+        calm_model?: unknown;
+        threats?: unknown;
+        controls?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    platform: {
+        platform_id: string;
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        sibling_bars: {
+            bar_id: string;
+            name: string;
+            composite_score: number;
+            linked_repos: string[];
+            calm_node_ids: string[];
+            threat_ids: string[];
+        }[];
+        architecture?: unknown;
+    } | null;
+    bar: {
+        bar_id: string;
+        name: string;
+        composite_score: number;
+        linked_repos: string[];
+        tier: "restricted" | "supervised" | "autonomous";
+        adrs: {
+            status: string;
+            id: string;
+            title: string;
+            decision: string;
+        }[];
+        pillar_scores: {
+            architecture: number;
+            security: number;
+            info_risk: number;
+            operations: number;
+        };
+        related_research: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        related_prds: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        mesh_gaps: ("no_threat_model" | "no_controls_mapping" | "no_adrs" | "stale_research" | "missing_prd_for_planned_feature" | "low_architecture_pillar" | "low_security_pillar")[];
+        calm_model?: unknown;
+        threats?: unknown;
+        controls?: unknown;
+    } | null;
+    scope: {
+        level: "platform" | "bar";
+        bar_id?: string | undefined;
+        platform_id?: string | undefined;
+    };
+    mesh_sha: string;
+    portfolio: {
+        name: string;
+        capability_models: unknown[];
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        governance_policy?: unknown;
+    };
+}, {
+    platform: {
+        platform_id: string;
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        sibling_bars: {
+            bar_id: string;
+            name: string;
+            composite_score: number;
+            linked_repos?: string[] | undefined;
+            calm_node_ids?: string[] | undefined;
+            threat_ids?: string[] | undefined;
+        }[];
+        architecture?: unknown;
+    } | null;
+    bar: {
+        bar_id: string;
+        name: string;
+        composite_score: number;
+        tier: "restricted" | "supervised" | "autonomous";
+        adrs: {
+            status: string;
+            id: string;
+            title: string;
+            decision: string;
+        }[];
+        pillar_scores: {
+            architecture: number;
+            security: number;
+            info_risk: number;
+            operations: number;
+        };
+        related_research: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        related_prds: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        mesh_gaps: ("no_threat_model" | "no_controls_mapping" | "no_adrs" | "stale_research" | "missing_prd_for_planned_feature" | "low_architecture_pillar" | "low_security_pillar")[];
+        linked_repos?: string[] | undefined;
+        calm_model?: unknown;
+        threats?: unknown;
+        controls?: unknown;
+    } | null;
+    scope: {
+        level: "platform" | "bar";
+        bar_id?: string | undefined;
+        platform_id?: string | undefined;
+    };
+    mesh_sha: string;
+    portfolio: {
+        name: string;
+        capability_models: unknown[];
+        related_research_summaries: {
+            topic: string;
+            research_id: string;
+            published_at: string;
+        }[];
+        governance_policy?: unknown;
+    };
+}>;
+export type MeshContext = z.infer<typeof MeshContext>;