@balpal4495/quorum 3.0.3 → 3.1.0

package/dist/sentinel/review.js

@@ -0,0 +1,177 @@
+import { promises as fs } from "fs";
+import path from "path";
+import { entryText } from "../shared/types.js";
+import { coverage as runCoverage } from "./coverage.js";
+function extractModule(filePath) {
+    const normalised = filePath.replace(/\\/g, "/").replace(/^\/+/, "");
+    const stripped = normalised.replace(/^modules\//, "");
+    const parts = stripped.split("/");
+    return parts.length === 1 ? "(root)" : parts[0];
+}
+function mermaidSafe(str) {
+    return str.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function riskClass(pct) {
+    if (pct === 0)
+        return "high";
+    if (pct < 50)
+        return "medium";
+    return "good";
+}
+function riskLabel(pct) {
+    if (pct === 0)
+        return "high";
+    if (pct < 50)
+        return "medium";
+    return "low";
+}
+function isoWeekKey(date) {
+    const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+    const day = d.getUTCDay() || 7;
+    d.setUTCDate(d.getUTCDate() + 4 - day);
+    const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+    const week = Math.ceil(((d.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7);
+    return `${d.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+async function readCommittedEntries(chronicleDir) {
+    const committedDir = path.join(chronicleDir, "committed");
+    let files;
+    try {
+        files = await fs.readdir(committedDir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const file of files) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(committedDir, file), "utf8");
+            entries.push(JSON.parse(raw));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return entries;
+}
+/**
+ * Generate a PR-level Chronicle coverage map as a markdown string ready to
+ * post as a PR comment.
+ *
+ * Produces three zones:
+ *   1. Coverage table — all modules with coverage %, entry count, file count,
+ *      PR delta, and risk. Changed modules are bolded.
+ *   2. Heatmap diagram — Chronicle → modules, nodes coloured by risk level,
+ *      labels show coverage % and change count in one visual.
+ *   3. Chronicle context — entries for touched modules only.
+ *
+ * Deterministic — no LLM required. Pass changedFiles from `git diff --name-only`.
+ */
+export async function reviewContext(changedFiles, chronicleDir, codebasePath) {
+    const filtered = changedFiles.filter(f => f.trim().length > 0);
+    if (filtered.length === 0)
+        return "<!-- sentinel: no changed files -->";
+    const [report, allEntries] = await Promise.all([
+        runCoverage(chronicleDir, codebasePath),
+        readCommittedEntries(chronicleDir),
+    ]);
+    // Count changed files per module
+    const changedByModule = new Map();
+    for (const file of filtered) {
+        const mod = extractModule(file);
+        changedByModule.set(mod, (changedByModule.get(mod) ?? 0) + 1);
+    }
+    // Build per-module stats from coverage report
+    const moduleStats = new Map();
+    for (const f of report.coverageByFile) {
+        const mod = extractModule(f.file);
+        const stat = moduleStats.get(mod) ?? {
+            name: mod, totalFiles: 0, coveredFiles: 0,
+            entryIds: [], changedFiles: changedByModule.get(mod) ?? 0, percentage: 0,
+        };
+        stat.totalFiles++;
+        if (f.covered) {
+            stat.coveredFiles++;
+            for (const id of f.entryIds) {
+                if (!stat.entryIds.includes(id))
+                    stat.entryIds.push(id);
+            }
+        }
+        moduleStats.set(mod, stat);
+    }
+    // Include modules only referenced by changedFiles but not in codebase scan
+    for (const [mod, count] of changedByModule) {
+        if (!moduleStats.has(mod)) {
+            moduleStats.set(mod, {
+                name: mod, totalFiles: count, coveredFiles: 0,
+                entryIds: [], changedFiles: count, percentage: 0,
+            });
+        }
+    }
+    for (const stat of moduleStats.values()) {
+        stat.percentage = stat.totalFiles === 0
+            ? 0
+            : Math.round((stat.coveredFiles / stat.totalFiles) * 100);
+    }
+    const allModules = [...moduleStats.values()].sort((a, b) => a.name === "(root)" ? 1 : b.name === "(root)" ? -1 : a.name.localeCompare(b.name));
+    const touchedModules = allModules.filter(m => m.changedFiles > 0);
+    const lines = [];
+    const week = isoWeekKey(new Date());
+    const chronicleIsEmpty = allEntries.length === 0;
+    // ── Header ────────────────────────────────────────────────────────────────
+    lines.push(`## Sentinel — Chronicle Coverage Map — ${week}`);
+    lines.push("");
+    if (chronicleIsEmpty) {
+        lines.push("> **Chronicle has no entries yet.** Every module shows as uncovered because this project has no documented knowledge. " +
+            "The modules touched by this PR are a good starting point — run `oracle.propose()` after this lands to begin building Chronicle.");
+        lines.push("");
+    }
+    // ── Coverage table ────────────────────────────────────────────────────────
+    lines.push("| Module | Coverage | Entries | Files | PR Changes | Risk |");
+    lines.push("|--------|----------|---------|-------|------------|------|");
+    for (const stat of allModules) {
+        const name = stat.changedFiles > 0 ? `**${stat.name}/**` : `${stat.name}/`;
+        const pct = `${stat.percentage}%`;
+        const changed = stat.changedFiles > 0 ? `**${stat.changedFiles} files**` : "—";
+        lines.push(`| ${name} | ${pct} | ${stat.entryIds.length} | ${stat.totalFiles} | ${changed} | ${riskLabel(stat.percentage)} |`);
+    }
+    lines.push("");
+    // ── Heatmap diagram ───────────────────────────────────────────────────────
+    lines.push("```mermaid");
+    lines.push("flowchart TD");
+    lines.push("    classDef high fill:#fca5a5,stroke:#dc2626");
+    lines.push("    classDef medium fill:#fde68a,stroke:#d97706");
+    lines.push("    classDef good fill:#bbf7d0,stroke:#16a34a");
+    lines.push("    Chronicle[(Chronicle)]");
+    for (const stat of allModules) {
+        const nodeId = mermaidSafe(stat.name);
+        const changed = stat.changedFiles > 0 ? ` — ${stat.changedFiles} changed` : "";
+        const label = `${stat.name} — ${stat.percentage}%${changed}`;
+        const cls = riskClass(stat.percentage);
+        lines.push(`    Chronicle --> ${nodeId}["${label}"]:::${cls}`);
+    }
+    lines.push("```");
+    lines.push("");
+    // ── Chronicle context for touched modules ─────────────────────────────────
+    const touchedWithEntries = touchedModules.filter(m => m.entryIds.length > 0);
+    if (touchedWithEntries.length > 0) {
+        lines.push("### Chronicle context for changed modules");
+        lines.push("");
+        for (const stat of touchedWithEntries) {
+            lines.push(`**${stat.name}/**`);
+            const relevant = allEntries.filter(e => stat.entryIds.includes(e.id));
+            for (const entry of relevant) {
+                lines.push(`- \`[${entry.id.slice(0, 8)}]\` ${entryText(entry)}`);
+                lines.push(`  *${entry.status} — confidence ${entry.confidence.toFixed(2)}*`);
+            }
+            lines.push("");
+        }
+    }
+    // ── Footer ────────────────────────────────────────────────────────────────
+    lines.push("---");
+    lines.push("*Risk: high = 0% coverage, medium = 1-49%, low = 50%+*");
+    return lines.join("\n");
+}
+//# sourceMappingURL=review.js.map

package/dist/sentinel/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../../modules/sentinel/review.ts"],"names":[],"mappings":"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"}

package/dist/setup.d.ts

@@ -0,0 +1,103 @@
+import type { LLMProvider, OracleClient } from "./shared/types.js";
+import type { JuryInput, JuryOutput } from "./jury/types.js";
+import type { CouncilInput, CouncilOutput, CouncilModels } from "./council/types.js";
+import type { AdvisorOutput } from "./advisor/types.js";
+import type { Compass } from "./compass/types.js";
+export interface SetupOptions {
+    /**
+     * Injectable LLM provider.
+     * All modules that need an LLM receive this function.
+     * Ignored by Oracle (which has no LLM dependency).
+     */
+    llm: LLMProvider;
+    /**
+     * Root directory for Chronicle data.
+     * Default: ".chronicle" (relative to process.cwd())
+     */
+    chronicleDir?: string;
+    /**
+     * Model overrides for each reasoning step.
+     * If omitted, the LLM provider's default model is used for all steps.
+     */
+    models?: {
+        jury?: string;
+        council?: CouncilModels;
+        compass?: {
+            brief?: string;
+            pathways?: string;
+            bets?: string;
+            score?: string;
+        };
+    };
+    /**
+     * Root directory for scanning source files (used by Compass).
+     * Default: process.cwd()
+     */
+    rootDir?: string;
+    /**
+     * Pre-warm the local ONNX embedder during setup so the first query
+     * is not slow. Set to false to skip (e.g. in test environments).
+     * Default: true
+     */
+    warmEmbedder?: boolean;
+    /**
+     * Swap the default embedder (Xenova all-MiniLM-L6-v2) for your own.
+     * Must return a vector of consistent dimension.
+     */
+    embedder?: (text: string) => Promise<number[]>;
+}
+export interface Modules {
+    /**
+     * Fully wired OracleClient.
+     * Use oracle.query() to retrieve evidence.
+     * Use oracle.propose() + oracle.commit() for the human-gated write path.
+     */
+    oracle: OracleClient;
+    /**
+     * Evaluate a proposed design against Oracle evidence.
+     * Returns a confidence score and the Council brief for the next step.
+     */
+    evaluate: (input: Omit<JuryInput, never>) => Promise<JuryOutput>;
+    /**
+     * Run the full Council deliberation pipeline.
+     * Proposes the verdict to Oracle automatically — a human must call
+     * oracle.commit(proposalId) to index it into Chronicle.
+     */
+    deliberate: (input: Omit<CouncilInput, "jury_output"> & {
+        jury_output: JuryOutput;
+    }) => Promise<CouncilOutput>;
+    /**
+     * Ask the Advisor a plain-language question.
+     * Queries Oracle automatically, synthesises Chronicle evidence into a
+     * human-readable answer, and retries internally until the answer meets
+     * the confidence threshold (≥ 0.7, no blockers) or the retry budget runs out.
+     */
+    ask: (question: string) => Promise<AdvisorOutput>;
+    /**
+     * Product-direction module.
+     * Synthesises Chronicle memory and current codebase behaviour into
+     * pathways, bets, briefs, and opportunities.
+     * All writes go through oracle.propose() — never auto-committed.
+     */
+    compass: Compass;
+}
+/**
+ * Wire up all three modules from a single call.
+ *
+ * @example
+ * import { setup } from "./modules/setup.js"
+ *
+ * const { oracle, evaluate, deliberate } = await setup({
+ *   llm: myLLMProvider,
+ * })
+ *
+ * const evidence  = await oracle.query("authentication patterns")
+ * const jury      = await evaluate({ outcome, design, evidence })
+ * const verdict   = await deliberate({ outcome, design, evidence, jury_output: jury })
+ *
+ * if (verdict.satisfied) {
+ *   // → human gate → Executor
+ * }
+ */
+export declare function setup(options: SetupOptions): Promise<Modules>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../modules/setup.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAY,MAAM,iBAAiB,CAAA;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAe,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACjG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGvD,OAAO,KAAK,EAAE,OAAO,EAAwB,MAAM,oBAAoB,CAAA;AAEvE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,GAAG,EAAE,WAAW,CAAA;IAEhB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,OAAO,CAAC,EAAE,aAAa,CAAA;QACvB,OAAO,CAAC,EAAE;YACR,KAAK,CAAC,EAAE,MAAM,CAAA;YACd,QAAQ,CAAC,EAAE,MAAM,CAAA;YACjB,IAAI,CAAC,EAAE,MAAM,CAAA;YACb,KAAK,CAAC,EAAE,MAAM,CAAA;SACf,CAAA;KACF,CAAA;IAED;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,MAAM,EAAE,YAAY,CAAA;IAEpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAEhE;;;;OAIG;IACH,UAAU,EAAE,CACV,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,GAAG;QAAE,WAAW,EAAE,UAAU,CAAA;KAAE,KACnE,OAAO,CAAC,aAAa,CAAC,CAAA;IAE3B;;;;;OAKG;IACH,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;IAEjD;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CA6EnE"}

package/dist/setup.js

@@ -0,0 +1,87 @@
+import path from "path";
+import { promises as fs } from "fs";
+import { createOracleClient } from "./oracle/index.js";
+import { xenovaEmbed, warmEmbedder } from "./oracle/adapters/xenova-embedder.js";
+import { createLanceDBStore } from "./oracle/adapters/lance-db.js";
+import { evaluate } from "./jury/evaluate.js";
+import { deliberate } from "./council/deliberate.js";
+import { ask as advisorAsk } from "./advisor/ask.js";
+import { entryText } from "./shared/types.js";
+import { createCompass } from "./compass/create.js";
+import { defaultSources } from "./compass/sources/index.js";
+/**
+ * Wire up all three modules from a single call.
+ *
+ * @example
+ * import { setup } from "./modules/setup.js"
+ *
+ * const { oracle, evaluate, deliberate } = await setup({
+ *   llm: myLLMProvider,
+ * })
+ *
+ * const evidence  = await oracle.query("authentication patterns")
+ * const jury      = await evaluate({ outcome, design, evidence })
+ * const verdict   = await deliberate({ outcome, design, evidence, jury_output: jury })
+ *
+ * if (verdict.satisfied) {
+ *   // → human gate → Executor
+ * }
+ */
+export async function setup(options) {
+    const { llm, chronicleDir = ".chronicle", rootDir = process.cwd(), models = {}, warmEmbedder: shouldWarm = true, embedder = xenovaEmbed, } = options;
+    // Ensure Chronicle directories exist before anything tries to write to them
+    await fs.mkdir(path.join(chronicleDir, "proposals"), { recursive: true });
+    await fs.mkdir(path.join(chronicleDir, "committed"), { recursive: true });
+    // Pre-warm the embedder if using the default (downloads model on first use)
+    if (shouldWarm && embedder === xenovaEmbed) {
+        await warmEmbedder();
+    }
+    const vectorStore = await createLanceDBStore(chronicleDir);
+    // Rebuild local index from committed entries if any are missing.
+    // This brings a fresh machine (or a post-git-pull state) up to date
+    // without requiring any manual step.
+    const committedDir = path.join(chronicleDir, "committed");
+    const committedFiles = (await fs.readdir(committedDir)).filter(f => f.endsWith(".json"));
+    if (committedFiles.length > 0) {
+        const existing = await vectorStore.getAll();
+        const existingIds = new Set(existing.map(e => e.id));
+        const missing = committedFiles.filter(f => !existingIds.has(f.replace(".json", "")));
+        if (missing.length > 0) {
+            console.log(`[Chronicle] Rebuilding index from ${missing.length} committed ${missing.length === 1 ? "entry" : "entries"}…`);
+            for (const file of missing) {
+                const raw = await fs.readFile(path.join(committedDir, file), "utf8");
+                const entry = JSON.parse(raw);
+                const embeddingText = [entryText(entry), ...entry.affected_areas, ...(entry.scope ?? [])].join(" ");
+                const vector = await embedder(embeddingText);
+                await vectorStore.upsert(entry.id, vector, entry);
+            }
+        }
+    }
+    const oracle = createOracleClient({
+        embedder,
+        vectorStore,
+        chronicleDir,
+    });
+    return {
+        oracle,
+        evaluate: (input) => evaluate(input, { llm, model: models.jury }),
+        deliberate: (input) => deliberate(input, {
+            llm,
+            oracle,
+            models: models.council,
+        }),
+        ask: async (question) => {
+            const evidence = await oracle.query(question);
+            return advisorAsk({ question, evidence }, { llm });
+        },
+        compass: createCompass({
+            oracle,
+            llm,
+            rootDir,
+            chronicleDir,
+            sources: defaultSources(),
+            models: models.compass,
+        }),
+    };
+}
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../modules/setup.ts"],"names":[],"mappings":"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"}

package/dist/shared/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Shared types used across Oracle, Jury, and Council modules.
+ * These are the only types that cross module boundaries.
+ */
+export type Message = {
+    role: "system" | "user" | "assistant";
+    content: string;
+};
+/**
+ * Injectable LLM provider. Accepts a message array and optional model override.
+ * Returns the assistant response as a string.
+ *
+ * The modules never hardcode a provider — wire this at the application level.
+ */
+export type LLMProvider = (messages: Message[], model?: string) => Promise<string>;
+/**
+ * Links a Chronicle entry to the unit of work that triggered it.
+ * Gives agents the "why now" context that key_insight alone cannot convey.
+ */
+export type WorkRef = {
+    type: "bug" | "story" | "epic" | "pr" | "spike";
+    /** Ticket number, PR reference, or branch name. e.g. "PROJ-123", "PR #4" */
+    ref?: string;
+};
+/**
+ * A durable knowledge record stored in Chronicle.
+ * This is the canonical unit of institutional memory.
+ *
+ * Schema versions:
+ *   v1 (no schema_version field): key_insight is the primary text field.
+ *   v2 (schema_version: 2): decision is the primary text field; key_insight is a copy
+ *       of decision written for backwards compatibility. Always use entryText() to read.
+ */
+export type ChronicleEntry = {
+    id: string;
+    /** The core finding or decision, in one clear sentence. v2: copy of decision. */
+    key_insight: string;
+    /** File paths or system areas this entry applies to. Used by Sentinel for file matching. */
+    affected_areas: string[];
+    status: "validated" | "refuted" | "open";
+    /** 0–1. How strongly this was confirmed at write time. */
+    confidence: number;
+    /** Which module produced this entry (detective, council, executor, etc.). */
+    source_module: string;
+    /** IDs of Chronicle entries this decision was based on. */
+    evidence_cited: string[];
+    /** What actually happened when this was acted on. Added post-execution by Scribe. */
+    outcome?: string;
+    /** The unit of work that triggered this entry. Used to build SUMMARY.md temporal context. */
+    work_ref?: WorkRef;
+    timestamp: string;
+    /** Steps that must pass to confirm this decision was correct. */
+    validation_plan?: string[];
+    /** ISO date after which this entry should be re-evaluated for drift. */
+    review_after?: string;
+    /** What actually happened after the decision was acted on in production. */
+    post_merge_result?: "successful" | "bug" | "partial" | "rolled-back";
+    /** 2 = decision record format. Absent = v1 legacy entry. */
+    schema_version?: 2;
+    /** Short label for this decision. e.g. "auth/session strategy" */
+    topic?: string;
+    /** The decision itself — the primary text field in v2. Use entryText() to read. */
+    decision?: string;
+    /** Domain/category tags. Additive — does NOT replace affected_areas. e.g. ["auth", "sessions"] */
+    scope?: string[];
+    /** Approaches that were considered but not chosen. */
+    alternatives_considered?: string[];
+    /** Why the alternatives were rejected. */
+    rejected_reason?: string[];
+    /** ID of the Chronicle entry this supersedes. */
+    supersedes?: string | null;
+    /** ID of the Chronicle entry that superseded this one. */
+    superseded_by?: string | null;
+};
+/**
+ * Return the primary text for a Chronicle entry regardless of schema version.
+ * v2 entries use decision; v1 entries use key_insight.
+ * All callsites that render or embed entry text must use this function.
+ *
+ * Accepts any object with key_insight and optional decision — works for both
+ * full ChronicleEntry and Omit<ChronicleEntry, "id" | "timestamp"> from propose().
+ */
+export declare function entryText(entry: {
+    key_insight: string;
+    decision?: string;
+}): string;
+/**
+ * A Chronicle entry enriched with its retrieval score and relevance tier.
+ * Returned by Oracle.query().
+ *
+ * Tiers indicate relevance within the result set:
+ *   primary    — top ~30%: directly answers the query, should be foregrounded
+ *   supporting — middle ~40%: contextually relevant, useful but not central
+ *   background — bottom ~30%: loosely related, de-emphasise but do not hide
+ */
+export type OracleResult = ChronicleEntry & {
+    score: number;
+    tier: "primary" | "supporting" | "background";
+};
+/**
+ * Returned by oracle.propose() when a high-similarity entry already exists.
+ * The human gate should surface this before approving the commit.
+ */
+export type SimilarityWarning = {
+    entry: ChronicleEntry;
+    score: number;
+    /** potential-duplicate: near-identical insight. potential-supersession: likely a correction. */
+    warning: "potential-duplicate" | "potential-supersession";
+};
+export type QueryOptions = {
+    statusFilter?: Array<"validated" | "refuted" | "open">;
+    /** Maximum results to return. Default: 10. */
+    limit?: number;
+    /**
+     * Minimum RRF score to include a result.
+     * Results below this threshold are dropped entirely — better to return nothing than noise.
+     * Default: 0.031.
+     */
+    scoreThreshold?: number;
+};
+/** Per-file result from sentinel.coverage(). */
+export type FileCoverage = {
+    file: string;
+    covered: boolean;
+    /** IDs of Chronicle entries that reference this file in affected_areas. */
+    entryIds: string[];
+};
+/** Returned by sentinel.coverage(). */
+export type CoverageReport = {
+    totalFiles: number;
+    coveredFiles: number;
+    uncoveredFiles: string[];
+    coverageByFile: FileCoverage[];
+    /** Integer 0–100. Treat as directional signal, not a precision metric. */
+    percentage: number;
+};
+/**
+ * Advisory result for a single Chronicle entry from sentinel.detectDrift().
+ * Never auto-updates an entry — human reviews the flag and decides.
+ */
+export type DriftFlag = {
+    entryId: string;
+    keyInsight: string;
+    affectedFiles: string[];
+    stillValid: boolean;
+    /** 0–1 confidence in the LLM's verdict. Low confidence = needs closer human review. */
+    confidence: number;
+    reasoning: string;
+};
+/** Returned by sentinel.detectDrift(). */
+export type DriftReport = {
+    checkedAt: string;
+    /** Entries the LLM judged as no longer accurate — review and consider updating status. */
+    flags: DriftFlag[];
+    /** Entries the LLM judged as still current. */
+    confirmed: DriftFlag[];
+    /** Entry IDs skipped because no affected_areas value resolved to a local file. */
+    skipped: string[];
+};
+/**
+ * The public interface any module uses to interact with Chronicle.
+ * Inject this into Jury and Council — do not couple them to Oracle internals.
+ */
+export interface OracleClient {
+    query: (text: string, options?: QueryOptions) => Promise<OracleResult[]>;
+    propose: (entry: Omit<ChronicleEntry, "id" | "timestamp">) => Promise<{
+        proposalId: string;
+        similarity?: SimilarityWarning;
+    }>;
+    /** Called after human approval. Indexes the proposal into Chronicle. */
+    commit: (proposalId: string) => Promise<ChronicleEntry>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../modules/shared/types.ts"],"names":[],"mappings":"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"}

package/dist/shared/types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared types used across Oracle, Jury, and Council modules.
+ * These are the only types that cross module boundaries.
+ */
+/**
+ * Return the primary text for a Chronicle entry regardless of schema version.
+ * v2 entries use decision; v1 entries use key_insight.
+ * All callsites that render or embed entry text must use this function.
+ *
+ * Accepts any object with key_insight and optional decision — works for both
+ * full ChronicleEntry and Omit<ChronicleEntry, "id" | "timestamp"> from propose().
+ */
+export function entryText(entry) {
+    return entry.decision ?? entry.key_insight;
+}
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../modules/shared/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkFH;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,KAAiD;IACzE,OAAO,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAA;AAC5C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balpal4495/quorum",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "Git-backed memory and design review for AI coding agents",
   "type": "module",
   "license": "MIT",
@@ -24,16 +24,21 @@
   "bin": {
     "quorum": "bin/quorum.js"
   },
+  "files": [
+    "dist/**",
+    "bin/**"
+  ],
   "exports": {
-    ".": "./modules/setup.ts",
-    "./oracle": "./modules/oracle/index.ts",
-    "./advisor": "./modules/advisor/index.ts",
-    "./jury": "./modules/jury/index.ts",
-    "./council": "./modules/council/index.ts",
-    "./sentinel": "./modules/sentinel/index.ts",
-    "./compass": "./modules/compass/index.ts"
+    ".": "./dist/setup.js",
+    "./oracle": "./dist/oracle/index.js",
+    "./advisor": "./dist/advisor/index.js",
+    "./jury": "./dist/jury/index.js",
+    "./council": "./dist/council/index.js",
+    "./sentinel": "./dist/sentinel/index.js",
+    "./compass": "./dist/compass/index.js"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run modules/ evals/",
     "test:watch": "vitest modules/",
     "typecheck": "tsc --noEmit"