@balpal4495/quorum 3.0.3 → 3.1.0

package/modules/jury/types.ts

@@ -1,50 +0,0 @@
-import type { OracleResult, LLMProvider } from "../shared/types"
-
-export interface JuryInput {
-  /** What needs to be achieved. */
-  outcome: string
-  /** Proposed approach from the Designer. */
-  design: string
-  /** Evidence retrieved from Oracle. */
-  evidence: OracleResult[]
-}
-
-/** Per-dimension breakdown of the 0–1 confidence score. */
-export interface ConfidenceBreakdown {
-  /** Do validated Oracle entries confirm this approach works here? */
-  evidence_support: number
-  /** Do Oracle entries suggest this is achievable in this codebase? */
-  feasibility: number
-  /** How well does the design address known failure modes? (1 = fully addressed) */
-  risk: number
-  /** Does the design cover the full outcome, or only part of it? */
-  completeness: number
-}
-
-export interface JuryOutput {
-  /** 0–1 confidence score. Average of the four breakdown dimensions. */
-  confidence: number
-  /** Per-dimension breakdown of the confidence score. */
-  confidence_breakdown: ConfidenceBreakdown
-  /** What the evidence supports or contradicts. */
-  assessment: string
-  /** Evidence missing from Oracle that would improve confidence. */
-  gaps: string[]
-  /**
-   * Gaps that are hard blockers — must be resolved before Council should proceed.
-   * Subset of gaps where the missing information is critical (auth, rollback, data safety).
-   */
-  blocking_gaps: string[]
-  /**
-   * Council brief derived from confidence:
-   *   < 0.6  → "challenge"      (find what is wrong — broader scope)
-   *   ≥ 0.6  → "pressure-test"  (assume correct, try to break it)
-   */
-  council_brief: "challenge" | "pressure-test"
-  recommendation: "proceed" | "investigate-more" | "redesign"
-}
-
-export interface JuryDeps {
-  llm: LLMProvider
-  model?: string
-}

package/modules/oracle/adapters/lance-db.ts

@@ -1,81 +0,0 @@
-/**
- * LanceDB vector store adapter.
- *
- * Required package: npm install vectordb
- *
- * Chronicle entries are stored in .chronicle/entries/ (LanceDB table directory).
- * Vectors are indexed with cosine metric — no need to pre-normalise embeddings.
- *
- * Note: this adapter targets the `vectordb` package (LanceDB v0.x).
- * If your project uses `@lancedb/lancedb` (v0.4+), the connect/createTable API
- * is nearly identical but table.query() replaces table.search() for non-vector queries.
- */
-
-import type { VectorStore } from "../types"
-import type { ChronicleEntry } from "../../shared/types"
-import path from "path"
-
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const lancedb = require("vectordb")
-
-interface LanceRow {
-  id: string
-  vector: number[]
-  /** ChronicleEntry serialised as JSON string. */
-  payload: string
-  _distance?: number
-}
-
-export async function createLanceDBStore(chronicleDir: string): Promise<VectorStore> {
-  const tableDir = path.join(chronicleDir, "entries")
-  const db = await lancedb.connect(tableDir)
-  let table: any = null
-
-  async function getOrCreateTable(firstRow?: LanceRow): Promise<any> {
-    if (table) return table
-    const names: string[] = await db.tableNames()
-    if (names.includes("entries")) {
-      table = await db.openTable("entries")
-    } else if (firstRow) {
-      table = await db.createTable("entries", [firstRow], { metric: "cosine" })
-    }
-    return table
-  }
-
-  return {
-    async upsert(id, vector, metadata) {
-      const row: LanceRow = { id, vector, payload: JSON.stringify(metadata) }
-      const t = await getOrCreateTable(row)
-      if (t !== table) {
-        // table was just created with this row — already inserted
-        return
-      }
-      // LanceDB does not have native upsert — delete existing then insert
-      await t.delete(`id = '${sanitiseId(id)}'`)
-      await t.add([row])
-    },
-
-    async search(vector, limit) {
-      const t = await getOrCreateTable()
-      if (!t) return []
-      const rows: LanceRow[] = await t.search(vector).limit(limit).execute()
-      return rows.map(row => ({
-        entry: JSON.parse(row.payload) as ChronicleEntry,
-        // Convert L2 distance (cosine metric stores 1 - cosine_sim as distance)
-        score: row._distance !== undefined ? 1 - row._distance : 0,
-      }))
-    },
-
-    async getAll() {
-      const t = await getOrCreateTable()
-      if (!t) return []
-      const rows: LanceRow[] = await t.query().execute()
-      return rows.map(row => JSON.parse(row.payload) as ChronicleEntry)
-    },
-  }
-}
-
-/** Prevent SQL injection in the delete filter. LanceDB uses SQL-like WHERE clauses. */
-function sanitiseId(id: string): string {
-  return id.replace(/'/g, "''")
-}

package/modules/oracle/adapters/xenova-embedder.ts

@@ -1,43 +0,0 @@
-/**
- * Local ONNX embedder using @xenova/transformers (all-MiniLM-L6-v2).
- *
- * Required package: npm install @xenova/transformers
- *
- * Runs entirely locally — no API key, no network dependency after first use.
- * First call downloads and caches the model (~25 MB).
- * Produces 384-dimensional unit vectors (mean pooling + L2 normalisation).
- *
- * For production use, pre-warm the embedder on startup:
- *   import { warmEmbedder } from "./adapters/xenova-embedder"
- *   await warmEmbedder()
- */
-
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { pipeline } = require("@xenova/transformers")
-
-let embedderPipeline: any = null
-
-async function getPipeline(): Promise<any> {
-  if (!embedderPipeline) {
-    embedderPipeline = await pipeline(
-      "feature-extraction",
-      "Xenova/all-MiniLM-L6-v2",
-    )
-  }
-  return embedderPipeline
-}
-
-/**
- * Embed text using all-MiniLM-L6-v2.
- * Returns a 384-dimensional unit vector.
- */
-export async function xenovaEmbed(text: string): Promise<number[]> {
-  const embedder = await getPipeline()
-  const output = await embedder(text, { pooling: "mean", normalize: true })
-  return Array.from(output.data) as number[]
-}
-
-/** Pre-warm the model so the first real query is not slow. */
-export async function warmEmbedder(): Promise<void> {
-  await getPipeline()
-}

package/modules/oracle/bm25.ts

@@ -1,92 +0,0 @@
-/**
- * Lightweight BM25 implementation for Pass 2 re-ranking.
- *
- * k1 = 1.5  (term frequency saturation)
- * b  = 0.75 (length normalization)
- *
- * Formula: score(q, d) = Σ IDF(qi) * f(qi, d) * (k1 + 1) / (f(qi, d) + k1 * (1 − b + b * |d| / avgdl))
- */
-
-const K1 = 1.5
-const B = 0.75
-
-function tokenize(text: string): string[] {
-  return text.toLowerCase().match(/\b\w+\b/g) ?? []
-}
-
-/** Robertson–Sparck Jones IDF with smoothing. */
-function computeIdf(N: number, df: number): number {
-  return Math.log(1 + (N - df + 0.5) / (df + 0.5))
-}
-
-/**
- * Score each document string against the query using BM25.
- * Returns a score array parallel to `documents`.
- */
-export function bm25Score(query: string, documents: string[]): number[] {
-  if (documents.length === 0) return []
-
-  const queryTokens = tokenize(query)
-  const docTokenLists = documents.map(tokenize)
-  const totalLength = docTokenLists.reduce((sum, d) => sum + d.length, 0)
-  const avgdl = totalLength / docTokenLists.length
-  const N = documents.length
-
-  // Precompute document frequency for each unique query token
-  const df = new Map<string, number>()
-  for (const token of queryTokens) {
-    if (!df.has(token)) {
-      df.set(token, docTokenLists.filter(doc => doc.includes(token)).length)
-    }
-  }
-
-  return docTokenLists.map(docTokenList => {
-    const docLength = docTokenList.length
-
-    const tf = new Map<string, number>()
-    for (const token of docTokenList) {
-      tf.set(token, (tf.get(token) ?? 0) + 1)
-    }
-
-    let score = 0
-    for (const token of queryTokens) {
-      const termFreq = tf.get(token) ?? 0
-      if (termFreq === 0) continue
-      const idfScore = computeIdf(N, df.get(token) ?? 0)
-      const normTf =
-        (termFreq * (K1 + 1)) /
-        (termFreq + K1 * (1 - B + B * (docLength / avgdl)))
-      score += idfScore * normTf
-    }
-
-    return score
-  })
-}
-
-const BM25_STOP_WORDS = new Set([
-  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
-  "have", "has", "had", "do", "does", "did", "will", "would", "should",
-  "could", "may", "might", "shall", "can", "to", "of", "in", "for", "on",
-  "with", "at", "by", "from", "as", "into", "through", "and", "or", "but",
-  "if", "then", "this", "that", "these", "those", "it", "its", "we", "they",
-  "their", "there", "when", "where", "what", "which", "who", "how", "not", "no",
-])
-
-/**
- * Extract domain terms from Chronicle key insights for Pass 2 query enrichment.
- * Bridges the vocabulary gap between natural language queries and technical identifiers.
- * Strips stop words, returns the most frequent distinctive tokens.
- */
-export function extractDomainTerms(insights: string[]): string[] {
-  const allTokens = insights.flatMap(s => tokenize(s))
-  const freq = new Map<string, number>()
-  for (const token of allTokens) {
-    if (!BM25_STOP_WORDS.has(token) && token.length > 2) {
-      freq.set(token, (freq.get(token) ?? 0) + 1)
-    }
-  }
-  return [...freq.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 10)
-    .map(([token]) => token)
-}

package/modules/oracle/index.ts

@@ -1,36 +0,0 @@
-export { query } from "./query"
-export { propose, commit } from "./propose"
-export type { OracleDeps, VectorStore } from "./types"
-export type {
-  OracleResult,
-  QueryOptions,
-  ChronicleEntry,
-  OracleClient,
-} from "../shared/types"
-
-export { createLanceDBStore } from "./adapters/lance-db"
-export { xenovaEmbed, warmEmbedder } from "./adapters/xenova-embedder"
-
-import type { OracleClient } from "../shared/types"
-import type { OracleDeps } from "./types"
-import { query } from "./query"
-import { propose, commit } from "./propose"
-
-/**
- * Create a bound OracleClient from injected deps.
- * Pass this to Jury and Council — they only need the OracleClient interface,
- * not the raw Oracle functions.
- *
- * @example
- * const oracle = createOracleClient({
- *   embedder: xenovaEmbed,
- *   vectorStore: await createLanceDBStore(".chronicle"),
- * })
- */
-export function createOracleClient(deps: OracleDeps): OracleClient {
-  return {
-    query: (text, options) => query(text, options ?? {}, deps),
-    propose: entry => propose(entry, deps),
-    commit: proposalId => commit(proposalId, deps),
-  }
-}

package/modules/oracle/log.ts

@@ -1,15 +0,0 @@
-import { promises as fs } from "fs"
-import path from "path"
-
-/**
- * Append a query log entry to .chronicle/query-log.jsonl.
- * Best-effort — callers should swallow errors from this.
- */
-export async function appendQueryLog(
-  entry: Record<string, unknown>,
-  chronicleDir: string,
-): Promise<void> {
-  await fs.mkdir(chronicleDir, { recursive: true })
-  const logPath = path.join(chronicleDir, "query-log.jsonl")
-  await fs.appendFile(logPath, JSON.stringify(entry) + "\n", "utf8")
-}

package/modules/oracle/propose.ts

@@ -1,164 +0,0 @@
-import { promises as fs } from "fs"
-import path from "path"
-import { randomUUID } from "crypto"
-import { exec } from "child_process"
-import { promisify } from "util"
-import type { ChronicleEntry, SimilarityWarning } from "../shared/types"
-import { entryText } from "../shared/types"
-import type { OracleDeps } from "./types"
-import { updateSummary } from "./summary"
-
-const execAsync = promisify(exec)
-
-const INSIGHT_MIN_LENGTH = 20
-const INSIGHT_MAX_LENGTH = 200
-const SIMILARITY_WARNING_THRESHOLD = 0.85
-
-function validateEntry(entry: Omit<ChronicleEntry, "id" | "timestamp">): void {
-  const insight = entry.key_insight?.trim() ?? ""
-  if (insight.length < INSIGHT_MIN_LENGTH) {
-    throw new Error(
-      `key_insight too short (${insight.length} chars, min ${INSIGHT_MIN_LENGTH}). ` +
-      `Write a specific, complete sentence naming the module or area affected.`,
-    )
-  }
-  if (insight.length > INSIGHT_MAX_LENGTH) {
-    throw new Error(
-      `key_insight too long (${insight.length} chars, max ${INSIGHT_MAX_LENGTH}). ` +
-      `Distil to a single clear sentence.`,
-    )
-  }
-  if (entry.decision !== undefined) {
-    const d = entry.decision.trim()
-    if (d.length < INSIGHT_MIN_LENGTH) {
-      throw new Error(
-        `decision too short (${d.length} chars, min ${INSIGHT_MIN_LENGTH}). ` +
-        `Write a specific, complete sentence describing the decision.`,
-      )
-    }
-    if (d.length > INSIGHT_MAX_LENGTH) {
-      throw new Error(
-        `decision too long (${d.length} chars, max ${INSIGHT_MAX_LENGTH}). ` +
-        `Distil to a single clear sentence.`,
-      )
-    }
-  }
-  if (!entry.affected_areas || entry.affected_areas.filter(a => a.trim()).length === 0) {
-    throw new Error(`affected_areas must contain at least one non-empty entry.`)
-  }
-  if (entry.confidence < 0 || entry.confidence > 1) {
-    throw new Error(`confidence must be between 0 and 1, got ${entry.confidence}.`)
-  }
-}
-
-async function checkSimilarity(
-  entry: Omit<ChronicleEntry, "id" | "timestamp">,
-  deps: OracleDeps,
-): Promise<SimilarityWarning | undefined> {
-  try {
-    const text = [entryText(entry), ...entry.affected_areas, ...(entry.scope ?? [])].join(" ")
-    const vector = await deps.embedder(text)
-    const results = await deps.vectorStore.search(vector, 3)
-    if (results.length === 0) return undefined
-    const top = results[0]
-    if (top.score < SIMILARITY_WARNING_THRESHOLD) return undefined
-    return {
-      entry: top.entry,
-      score: top.score,
-      // If the existing entry is validated, a near-duplicate is likely a correction
-      warning: top.entry.status === "validated" ? "potential-supersession" : "potential-duplicate",
-    }
-  } catch {
-    // Similarity check is best-effort — never block a proposal because of it
-    return undefined
-  }
-}
-
-/**
- * Propose a new Chronicle entry for human review.
- * Validates entry quality and checks for similar existing entries before writing.
- * Writes the entry to .chronicle/proposals/<id>.json — NOT yet indexed.
- * The proposal sits pending until a human calls commit() to approve it.
- *
- * Throws if key_insight is too short/long or affected_areas is empty.
- * Returns a SimilarityWarning if a near-identical entry already exists —
- * the human gate should surface this before approving the commit.
- */
-export async function propose(
-  entry: Omit<ChronicleEntry, "id" | "timestamp">,
-  deps: OracleDeps,
-): Promise<{ proposalId: string; similarity?: SimilarityWarning }> {
-  validateEntry(entry)
-
-  const similarity = await checkSimilarity(entry, deps)
-
-  const chronicleDir = deps.chronicleDir ?? ".chronicle"
-  const proposalsDir = path.join(chronicleDir, "proposals")
-  await fs.mkdir(proposalsDir, { recursive: true })
-
-  const proposalId = randomUUID()
-  const proposalPath = path.join(proposalsDir, `${proposalId}.json`)
-  await fs.writeFile(proposalPath, JSON.stringify(entry, null, 2), "utf8")
-
-  return { proposalId, ...(similarity ? { similarity } : {}) }
-}
-
-/**
- * Commit a pending proposal after human approval.
- * Reads the proposal file, assigns an ID and timestamp, embeds the entry,
- * upserts it into the vector store, and deletes the proposal file.
- *
- * Throws if the proposal does not exist.
- */
-export async function commit(
-  proposalId: string,
-  deps: OracleDeps,
-): Promise<ChronicleEntry> {
-  const chronicleDir = deps.chronicleDir ?? ".chronicle"
-  const proposalPath = path.join(chronicleDir, "proposals", `${proposalId}.json`)
-
-  let raw: string
-  try {
-    raw = await fs.readFile(proposalPath, "utf8")
-  } catch {
-    throw new Error(`Proposal not found: ${proposalId}`)
-  }
-
-  const partial = JSON.parse(raw) as Omit<ChronicleEntry, "id" | "timestamp">
-
-  const entry: ChronicleEntry = {
-    ...partial,
-    id: randomUUID(),
-    timestamp: new Date().toISOString(),
-  }
-
-  // Embed the primary text + areas + scope tags for richer retrieval
-  const embeddingText = [entryText(entry), ...entry.affected_areas, ...(entry.scope ?? [])].join(" ")
-  const vector = await deps.embedder(embeddingText)
-  await deps.vectorStore.upsert(entry.id, vector, entry)
-
-  // Write to committed/ — the git-tracked source of truth shared across the team
-  const committedDir = path.join(chronicleDir, "committed")
-  await fs.mkdir(committedDir, { recursive: true })
-  const committedPath = path.join(committedDir, `${entry.id}.json`)
-  await fs.writeFile(committedPath, JSON.stringify(entry, null, 2), "utf8")
-
-  // Stage the committed entry for the next git commit — best-effort
-  try {
-    await execAsync(`git add "${committedPath}"`)
-  } catch {
-    // Not in a git repo, or git is unavailable — silently continue
-  }
-
-  // Rebuild SUMMARY.md — best-effort, never fail a commit
-  try {
-    await updateSummary(chronicleDir)
-  } catch {
-    // Summary generation failure must not fail a commit
-  }
-
-  // Remove the proposal — it has been committed
-  await fs.unlink(proposalPath)
-
-  return entry
-}

package/modules/oracle/query.ts

@@ -1,146 +0,0 @@
-import type { ChronicleEntry, OracleResult, QueryOptions } from "../shared/types"
-import { entryText } from "../shared/types"
-import type { OracleDeps } from "./types"
-import { bm25Score, extractDomainTerms } from "./bm25"
-import { appendQueryLog } from "./log"
-
-const DEFAULT_LIMIT = 10
-const DEFAULT_SCORE_THRESHOLD = 0.031
-const RRF_K = 60
-/** Retrieve this many vector candidates before BM25 re-ranking. */
-const CANDIDATE_MULTIPLIER = 3
-
-/**
- * Reciprocal Rank Fusion score.
- * score = Σ 1 / (k + rank_i) summed across all rank lists.
- * k = 60 (standard constant).
- */
-function rrfScore(ranks: number[]): number {
-  return ranks.reduce((sum, rank) => sum + 1 / (RRF_K + rank), 0)
-}
-
-/**
- * Two-pass retrieval with Reciprocal Rank Fusion.
- *
- * Pass 1 — vector similarity:
- *   Embed the query, retrieve top (limit × CANDIDATE_MULTIPLIER) candidates.
- *
- * Pass 2 — BM25 re-ranking with query enrichment:
- *   Extract domain terms from Pass 1 key insights, enrich the query,
- *   score candidates with BM25, fuse ranks via RRF.
- *
- * Results below scoreThreshold are dropped entirely.
- * All queries are appended to .chronicle/query-log.jsonl.
- */
-export async function query(
-  text: string,
-  options: QueryOptions = {},
-  deps: OracleDeps,
-): Promise<OracleResult[]> {
-  const {
-    statusFilter,
-    limit = DEFAULT_LIMIT,
-    scoreThreshold = DEFAULT_SCORE_THRESHOLD,
-  } = options
-
-  const startTime = Date.now()
-
-  // ── Pass 1: vector similarity ──────────────────────────────────────────────
-  const queryVector = await deps.embedder(text)
-  const candidateLimit = limit * CANDIDATE_MULTIPLIER
-  let candidates = await deps.vectorStore.search(queryVector, candidateLimit)
-
-  // Status filter applied before BM25 to avoid scoring irrelevant entries
-  if (statusFilter && statusFilter.length > 0) {
-    candidates = candidates.filter(c => statusFilter.includes(c.entry.status))
-  }
-
-  if (candidates.length === 0) {
-    await tryLogQuery(text, [], startTime, deps)
-    return []
-  }
-
-  // ── Pass 2: BM25 re-ranking with query enrichment ─────────────────────────
-  const topInsights = candidates
-    .slice(0, Math.min(5, candidates.length))
-    .map(c => entryText(c.entry))
-  const domainTerms = extractDomainTerms(topInsights)
-  const enrichedQuery =
-    domainTerms.length > 0 ? `${text} ${domainTerms.join(" ")}` : text
-
-  const documents = candidates.map(c =>
-    [entryText(c.entry), ...c.entry.affected_areas, ...(c.entry.scope ?? [])].join(" "),
-  )
-  const bm25Scores = bm25Score(enrichedQuery, documents)
-
-  // Build BM25 rank lookup (index → rank)
-  const bm25RankOf: number[] = new Array(candidates.length)
-  bm25Scores
-    .map((score, i) => ({ i, score }))
-    .sort((a, b) => b.score - a.score)
-    .forEach(({ i }, rank) => {
-      bm25RankOf[i] = rank
-    })
-
-  // ── RRF fusion ─────────────────────────────────────────────────────────────
-  const fused: Array<ChronicleEntry & { score: number }> = candidates.map(
-    (candidate, vectorRank) => ({
-      ...candidate.entry,
-      score: rrfScore([vectorRank, bm25RankOf[vectorRank]]),
-    }),
-  )
-
-  fused.sort((a, b) => b.score - a.score)
-
-  const filtered = fused
-    .filter(r => r.score >= scoreThreshold)
-    .slice(0, limit)
-
-  const results = assignTiers(filtered)
-
-  await tryLogQuery(text, results, startTime, deps)
-  return results
-}
-
-/**
- * Assign relevance tiers within the result set using relative rank.
- * Top ~30% → primary, next ~40% → supporting, remainder → background.
- * Thresholds are relative so they self-calibrate as Chronicle grows.
- */
-function assignTiers(
-  results: Array<ChronicleEntry & { score: number }>,
-): OracleResult[] {
-  const n = results.length
-  if (n === 0) return []
-  const primaryCount = Math.max(1, Math.ceil(n * 0.3))
-  const supportingCount = Math.max(1, Math.ceil(n * 0.4))
-  return results.map((r, i) => ({
-    ...r,
-    tier:
-      i < primaryCount ? "primary"
-      : i < primaryCount + supportingCount ? "supporting"
-      : "background",
-  }))
-}
-
-async function tryLogQuery(
-  text: string,
-  results: OracleResult[],
-  startTime: number,
-  deps: OracleDeps,
-): Promise<void> {
-  try {
-    await appendQueryLog(
-      {
-        query: text,
-        results: results.map(r => ({ id: r.id, score: r.score, status: r.status })),
-        resultCount: results.length,
-        durationMs: Date.now() - startTime,
-        timestamp: new Date().toISOString(),
-      },
-      deps.chronicleDir ?? ".chronicle",
-    )
-  } catch {
-    // Query logging is best-effort — never fail a query because of a log write failure
-  }
-}