opencode-swarm 7.130.2 → 7.131.0

package/dist/consensus/corpus.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Read-only corpus assembly for the consensus miner (issue #1821, Workstream C).
+ *
+ * This module owns exactly one job: turn every already-existing evidence store
+ * in `.swarm/` into a single flat stream of `CorpusObservation` records. It
+ * introduces **no new store**. Every reader below is an existing exported
+ * function; the two enumerators added here are `listTrajectorySessions` (a
+ * `readdir` over `.swarm/trajectories`) and `listEvaluationRunIds` (a `readdir`
+ * over `.swarm/evolution/runs`), because both underlying stores read one
+ * artifact at a time and never needed a listing of their own. An enumerator is
+ * not a store: it writes nothing, caches nothing, and owns no schema. One
+ * source composes rather than enumerates: `.swarm/skills/rejected-edits.jsonl`
+ * has no bulk reader, so `defaultReaders` pairs that module's already-exported
+ * `rejectedEditsPath` with the shared JSONL `readKnowledge`.
+ *
+ * Hard rules this module upholds (AGENTS.md invariants 4 and 8):
+ * - Every reader receives an injected `directory`. There is no `process.cwd()`
+ *   fallback anywhere in this file, and none may be added: a consensus report
+ *   mined against the wrong root would silently attribute one project's
+ *   evidence to another.
+ * - Nothing here writes to disk: no artifact, no lock, no cache file, no marker.
+ *   That is not a property of *reading* — it has to be chosen. `loadEvidence`
+ *   performs a lazy in-place upgrade of a legacy flat retrospective by default
+ *   (rewriting the bundle under an `evidence-loader` lock and creating a lock
+ *   sentinel under `.swarm/locks/`), so `defaultReaders` binds it with
+ *   `{ migrate: false }`. A mining run must never mutate the evidence it is
+ *   merely counting. Note that `migrate: false` skips only the PERSISTENCE: the
+ *   returned bundle is still the wrapped, normalized view — including the
+ *   `task_complexity` remap, which happens in `wrapFlatRetrospective` before the
+ *   write branch — so the corpus reads normalized values while the file on disk
+ *   keeps its legacy ones.
+ *   Three upstream readers do populate PROCESS-LOCAL caches, which is worth
+ *   stating rather than hiding behind the word "read-only": `readTrajectory`
+ *   fills the PRM in-memory trajectory cache (`src/prm/trajectory-store.ts`),
+ *   while `readKnowledge` and `loadEvidence` fill the two SEPARATE maps in
+ *   `src/utils/swarm-artifact-cache.ts` — the parsed-artifact cache and the text
+ *   cache, each independently bounded at `MAX_CACHE_ENTRIES` = 128 entries. All
+ *   are bounded and FIFO-evicting, so mining a large `.swarm/` tree CAN evict
+ *   another subsystem's cached entries and change what that subsystem sees next.
+ *   The PRM one goes further: it is a plain `Map` with no revalidation, and
+ *   `readTrajectory` REPLACES the entry for the session it read, re-bounded by
+ *   its own `maxLines` default rather than by whatever bound the live writer was
+ *   using — a session whose list exceeds 1000 entries is cut to the newest
+ *   `floor(maxLines / 2)` = 500 ENTRIES. That 500 is unrelated to
+ *   `MAX_TRACKED_TRAJECTORY_SESSIONS` = 500, which bounds how many SESSIONS the
+ *   cache holds at once; the two constants merely happen to share a value.
+ *   None of these caches is on disk: nothing about them writes a file, and none
+ *   survives the process. (The readers themselves obviously do read files — the
+ *   claim above is that nothing here WRITES, not that nothing here touches the
+ *   filesystem. The artifact cache in particular `stat`s the file on every
+ *   lookup to check freshness, and on a miss invokes the caller's own read
+ *   function and `stat`s again before storing.)
+ * - Every free-text fragment that survives into a signal, a statement, or an
+ *   evidence reference passes through `redactSecrets` and a hard length bound
+ *   before it is retained. Prompts and reasoning traces are never read into an
+ *   observation at all — only outcomes, verdicts, categories, and the bounded
+ *   excerpts below.
+ * - The whole corpus is capped at `maxEvidenceItems` observations. The cap is
+ *   applied against a deterministic source order and a deterministic per-source
+ *   sort, so the same `.swarm/` tree always yields the same truncated corpus.
+ *   Within a source the cut is *balanced between failing and succeeding
+ *   observations* rather than lexicographic, because a lexicographic cut
+ *   systematically drops whichever class sorts late and would let truncation
+ *   erase counterexamples while confidence rose. That removes the systematic
+ *   bias; it does not make truncation lossless. The balance is struck PER
+ *   SOURCE, so one signal can still lose every counterexample it had, and once
+ *   the budget is spent every later source is dropped WHOLE. `report.truncation`
+ *   exists so a reader can tell a partial view from a complete one — see
+ *   `docs/consensus-mining.md`.
+ */
+import type { EvaluationRunV1 } from '../evaluation/contracts.js';
+import { readGateGroundTruth } from '../evaluation/gate-ground-truth.js';
+import { type GateAuditReadSummary } from '../evaluation/store.js';
+import { type LoadEvidenceResult } from '../evidence/manager.js';
+import type { RetrievalOutcome } from '../hooks/knowledge-types.js';
+import { readSkillUsageEntries } from '../hooks/skill-usage-log.js';
+import type { TrajectoryEntry } from '../prm/types.js';
+import type { ConsensusCorpusHash, ConsensusSourceKind } from './contracts.js';
+/**
+ * One normalized evidence record.
+ *
+ * `runId` is the *support unit*: the miner counts distinct `runId` values, so
+ * whatever a source uses as its independent-trial identity belongs here. For
+ * evaluation and gate-audit evidence that is the literal run id; for per-task
+ * evidence it is the task's own identity, and for session trajectories the
+ * session id. Each is namespaced so two sources can never collide.
+ */
+export interface CorpusObservation {
+    runId: string;
+    taskId?: string;
+    taskCategory?: string;
+    agentRole?: string;
+    modelId?: string;
+    seed?: string;
+    success: boolean;
+    signals: string[];
+    evidenceRef: string;
+}
+export interface ConsensusCorpus {
+    observations: CorpusObservation[];
+    hashes: ConsensusCorpusHash[];
+    /** True when `maxEvidenceItems` truncated the stream. */
+    truncated: boolean;
+    /** Sources that threw while being read. Never fatal — the corpus degrades. */
+    unreadableSources: ConsensusSourceKind[];
+}
+/**
+ * Injectable readers. Dependency injection rather than `mock.module` (AGENTS.md
+ * invariant 7): the corpus pulls from eight subsystems, and mocking those module
+ * paths would leak across Bun's shared test-runner process.
+ */
+export interface CorpusReaders {
+    listEvaluationRunIds: (directory: string) => Promise<string[]>;
+    readEvaluationRun: (directory: string, runId: string) => Promise<EvaluationRunV1 | undefined>;
+    listGateAuditResults: (directory: string) => Promise<GateAuditReadSummary>;
+    readGateGroundTruth: typeof readGateGroundTruth;
+    listEvidenceTaskIds: (directory: string) => Promise<string[]>;
+    readTaskTrajectory: (directory: string, taskId: string) => Promise<TrajectoryEntry[]>;
+    listTrajectorySessions: (directory: string) => Promise<string[]>;
+    readTrajectory: (sessionId: string, directory: string) => Promise<TrajectoryEntry[]>;
+    readSkillUsageEntries: typeof readSkillUsageEntries;
+    readKnowledgeEntries: (directory: string) => Promise<KnowledgeLike[]>;
+    loadEvidence: (directory: string, taskId: string) => Promise<LoadEvidenceResult>;
+    readRejectedLessons: (directory: string) => Promise<RejectedLessonLike[]>;
+    readRejectedSkillEdits: (directory: string) => Promise<RejectedSkillEditLike[]>;
+}
+/**
+ * Structural view of a knowledge entry. Deliberately minimal: the consensus
+ * miner reads four fields, and depending on the full `KnowledgeEntry` union
+ * would couple this module to a schema another lane actively edits.
+ */
+export interface KnowledgeLike {
+    id?: unknown;
+    lesson?: unknown;
+    category?: unknown;
+    retrieval_outcomes?: RetrievalOutcome;
+}
+/**
+ * Structural view of a `RejectedLesson` (`src/hooks/knowledge-types.ts`). Same
+ * reason as `KnowledgeLike`: the corpus reads four fields and must not couple
+ * itself to a schema another lane edits.
+ */
+export interface RejectedLessonLike {
+    id?: unknown;
+    lesson?: unknown;
+    rejection_reason?: unknown;
+    rejection_layer?: unknown;
+}
+/**
+ * Structural view of a `RejectedSkillEditRecord`
+ * (`src/services/skill-evaluator.ts`). `candidatePreview` is deliberately NOT
+ * read: it is up to 800 bytes of the rejected skill BODY, which is closer to a
+ * prompt than to an outcome, and the corpus reads outcomes only.
+ */
+export interface RejectedSkillEditLike {
+    slug?: unknown;
+    operation?: unknown;
+    reason?: unknown;
+    candidateHash?: unknown;
+}
+export interface LoadCorpusOptions {
+    /** Hard cap on retained observations. Required — there is no default. */
+    maxEvidenceItems: number;
+    /** Hard cap on any single retained free-text fragment. */
+    maxExcerptChars: number;
+    /**
+     * Caller-supplied retention predicate, applied per source AFTER that source's
+     * hash and observation count are recorded and BEFORE the `maxEvidenceItems`
+     * budget is spent.
+     *
+     * That position is the whole point. The consensus miner's request filters used
+     * to run only on the already-truncated stream, so narrowing a request to the
+     * one task category that mattered removed observations from a corpus the cap
+     * had already shaped — 50 observations in, 0 out. Applying the predicate here
+     * spends the budget on observations that can survive the request instead, so
+     * narrowing genuinely widens what is available to it.
+     *
+     * Applied after the per-source hash so `corpusHashes` keeps meaning "what this
+     * source contained", independent of any one request; `truncation.observations`
+     * on the report is what declares how many were actually tallied.
+     *
+     * Omitted \u21D2 every observation is retained, which is the pre-existing behaviour.
+     */
+    filter?: (observation: CorpusObservation) => boolean;
+    /** Reader overrides for tests. Unspecified readers use the real store. */
+    readers?: Partial<CorpusReaders>;
+}
+/**
+ * Total, locale-INDEPENDENT string order.
+ *
+ * `String.prototype.localeCompare` without an explicit locale is ICU- and
+ * environment-sensitive: it orders `a-b, a:b, ab, aB` differently from code-unit
+ * order, and the collation can differ between hosts. That is fine for display
+ * and fatal here — this ordering decides which observations survive truncation
+ * and the order of the attribute array, both of which are hashed into
+ * `integrityHash`. A report whose id depends on the host's collation is not
+ * reproducible. Code-unit comparison is the same everywhere.
+ */
+export declare function compareRefs(left: string, right: string): number;
+/**
+ * Redact, collapse, and bound a free-text fragment before it is retained.
+ *
+ * Order matters: redaction runs BEFORE truncation, so a secret that straddles
+ * the length bound is still replaced rather than half-copied into the report.
+ * Newlines and control characters collapse to single spaces because signals are
+ * compared for equality — a fragment that differs only by line wrapping must
+ * not split one consensus attribute into two.
+ *
+ * Format characters (`\p{Cf}`) are collapsed alongside control characters — to a
+ * SPACE, like everything else here, not deleted — and that is a correctness rule
+ * rather than tidiness. U+202E (RIGHT-TO-LEFT OVERRIDE), U+2066–U+2069 (the
+ * isolates) and U+200E/U+200F reorder how the text RENDERS without changing the
+ * bytes stored, so a persisted signal, statement, evidence ref, or `llmSummary`
+ * could read as something other than the bytes the report actually holds.
+ * U+200B–U+200D and U+FEFF are the same class of invisible, and they also hide
+ * INSIDE a token: `[REDACTED\u200B:x]` is not the placeholder it renders as, and
+ * `sk\u200B-…` is not the secret shape `redactSecrets` matches.
+ *
+ * Replacing rather than deleting is a real choice, in both directions. What it
+ * BUYS: deletion would let `[REDACTED\u200B:x]` close up into a well-formed
+ * `[REDACTED:x]` after the forged-marker check in `extractRestatement` has
+ * already run on the raw text — manufacturing exactly the forged redaction
+ * marker that check exists to reject. A space breaks the token instead, and
+ * `MARKUP_RE` then rejects it on the bare `[`. What it does NOT buy: `a\u200Db`
+ * becomes `a b`, not `ab`, so a fragment differing from another only by a
+ * zero-width joiner still differs afterwards. Equality is canonicalized (every
+ * such fragment collapses the same way), not made to agree with the joiner-free
+ * spelling.
+ */
+export declare function sanitizeExcerpt(value: string, maxChars: number): string;
+/**
+ * READ-ONLY enumerator over `.swarm/trajectories`.
+ *
+ * `src/prm/trajectory-store.ts` reads exactly one session at a time and has no
+ * bulk enumerator, so the consensus corpus needs this to discover which sessions
+ * exist. It lives here rather than in the PRM store because it is the consensus
+ * miner's need, not the PRM subsystem's, and because adding it there would put a
+ * second writer-adjacent surface in a module another lane owns. It performs a
+ * single `readdir`, filters to `<sessionId>.jsonl` names that match the shared
+ * identifier shape, sorts, bounds, and returns. Missing directory \u21D2 `[]`.
+ */
+export declare function listTrajectorySessions(directory: string): Promise<string[]>;
+/**
+ * READ-ONLY enumerator over `.swarm/evolution/runs`.
+ *
+ * `src/evaluation/store.ts` exposes `readEvaluationRun(directory, runId)` but no
+ * listing (its own callers always know the run id). Mirrors the directory
+ * discipline of `listGateAuditResults`: validated names only, sorted, bounded.
+ */
+export declare function listEvaluationRunIds(directory: string): Promise<string[]>;
+/**
+ * Load and normalize every corpus source.
+ *
+ * Failure of any single source is non-fatal and recorded in `unreadableSources`:
+ * a corrupt trajectory file must not make the whole mining run unavailable, and
+ * a silently-empty corpus would be worse than a declared partial one. The
+ * returned observations are stable-sorted, reduced by the optional
+ * `options.filter`, and then truncated to `maxEvidenceItems` — filter first, so
+ * the budget is spent on observations the caller can actually use.
+ */
+export declare function loadConsensusCorpus(directory: string, options: LoadCorpusOptions): Promise<ConsensusCorpus>;

package/dist/consensus/miner.d.ts

@@ -0,0 +1,200 @@
+/**
+ * The consensus miner (issue #1821, Workstream C).
+ *
+ * Reads the read-only corpus, counts agreement deterministically, gates the
+ * result, and emits a report. It is a **proposals-only** boundary: it activates
+ * no skill, writes no knowledge, and mutates none of the evidence it reads.
+ * `mineConsensus` itself writes nothing at all; the subsystem's only disk
+ * mutations live in `./store.ts`, which persists a report and — under
+ * `pruneConsensusReports` — deletes the subsystem's own older ones.
+ *
+ * Ordering is a correctness property, not a style choice. The pipeline is:
+ *
+ *   1. deterministic filtering
+ *   2. deterministic co-occurrence + distinct-run support counting
+ *   3. deterministic gates (support, successful runs, task diversity)
+ *   4. deterministic retention of negative evidence
+ *   5. deterministic proposal + fingerprint construction
+ *   6. ONLY THEN, optional LLM restatement, into a SEPARATE field
+ *
+ * Step 6 last is what keeps a model from influencing whether something
+ * qualifies. A model may only rephrase a conclusion the arithmetic already
+ * reached. If no dispatcher is available, or the call times out, or
+ * summarization is disabled, or the response fails the restatement guard, the
+ * attribute simply has no `llmSummary` — graceful degradation, never a hard
+ * dependency.
+ *
+ * Two properties are easy to lose here and are enforced explicitly:
+ *
+ * - **Reproducibility.** Ordering alone does NOT make the report reproducible.
+ *   Two fields had to be moved out of hashed content, and both were reachable in
+ *   ordinary use. `llm_summarization_enabled` defaults to `true`, so a model's
+ *   wording in `statement` gave a different `integrityHash` — and a different
+ *   `reportId` — on every run over an identical corpus; the restatement now goes
+ *   into `ConsensusAttributeV1.llmSummary`, which the hash excludes. And
+ *   `provenance.writeOrigin.sessionId` comes from `ctx.sessionID`, so two
+ *   sessions mining the same corpus forked the artifact too; the hash now
+ *   excludes the whole `writeOrigin`. `statement` is always the deterministic
+ *   rendering, and who ran the mine cannot change what the mine found.
+ * - **Model prose reaches disk only through a bounded whitelist.**
+ *   `SUMMARIZATION_SYSTEM` is a request, not a filter, and `sanitizeExcerpt`
+ *   only redacts secrets, collapses control and format characters, and
+ *   truncates. `extractRestatement` is the actual guard, and what it enforces is
+ *   precisely this: one `FINDING:` line per dispatch survives (the first),
+ *   everything else in the response is discarded, and the captured text is
+ *   admitted only if it carries no forged `[REDACTED:…]` marker, no bracket or
+ *   angle-bracket markup, no listed reasoning marker, and — once decimal points
+ *   and at most one lower-case-continued `e.g.`/`i.e.`/`etc.` are MASKED — no
+ *   sentence terminator other than a single trailing run, and fits
+ *   `MAX_CONSENSUS_STATEMENT_CHARS` without truncation (issue #1821 AC18). Note
+ *   the masking clause: the persisted text can hold several literal `.`
+ *   characters (`… on 0.8 of the runs, e.g. the refactor pair.` is admitted and
+ *   contains four: the decimal, the two in `e.g.`, and the trailing one. Three
+ *   of them are masked, leaving the single trailing run the rule allows). The
+ *   bound is on UNMASKED terminators, not on periods.
+ *
+ *   The limitation belongs in the same breath, because the absolute version was
+ *   claimed here twice and is false: **a single grammatical sentence chained
+ *   with semicolons, colons, dashes, tabs, or the one permitted abbreviation can
+ *   still read as a multi-step narration, and this guard does not stop that.**
+ *   It bounds how much model text, in what shape, can reach an attribute — one
+ *   sentence-shaped fragment of at most `MAX_CONSENSUS_STATEMENT_CHARS`, in a
+ *   field excluded from the integrity hash that never displaces `statement`. It
+ *   does not classify meaning.
+ */
+import type { ConsensusConfig } from '../config/schema.js';
+import type { EvaluationModelDispatcher } from '../evaluation/model-dispatcher.js';
+import type { ConsensusMineRequest, ConsensusReportV1 } from './contracts.js';
+import type { ConsensusCorpus, CorpusObservation } from './corpus.js';
+/**
+ * Minimum distinct task identities before an attribute may become a proposal.
+ *
+ * Two is not a tuning knob. One anecdote — one task, however many times it was
+ * observed — cannot distinguish "this is how the system behaves" from "this is
+ * how that one task behaves". Below this an attribute is still emitted, as an
+ * investigation note with `proposedTarget: 'none'`, because suppressing it
+ * entirely would hide the very evidence a human needs to decide whether to go
+ * looking for a second task.
+ */
+export declare const MIN_TASK_DIVERSITY_FOR_PROPOSAL = 2;
+/**
+ * Minimum distinct RUNS before an attribute may become a proposal.
+ *
+ * A second, independent gate from `MIN_TASK_DIVERSITY_FOR_PROPOSAL`, and it is
+ * NOT implied by the request's `minSupport`: `min_support: 1` is an accepted
+ * argument, so without this an attribute supported by a single run could clear
+ * every threshold the caller asked for and still be a one-run recommendation.
+ * Exported so `consensus_mine` can print the gate it actually applies rather
+ * than restating it — the printed `thresholds` block used to omit this one, and
+ * an attribute that cleared every printed number could still be forced to
+ * `proposedTarget: 'none'` with nothing in the output explaining why.
+ */
+export declare const MIN_SUPPORT_FOR_PROPOSAL = 2;
+/**
+ * Hard cap on LLM restatement dispatches per report.
+ *
+ * Exported so `consensus_mine` can state the real ceiling in the description the
+ * model reads. Each unit is one `session.create` + one `session.prompt`
+ * (`src/evaluation/model-dispatcher.ts`), so this is 20 sessions and 20 prompts
+ * in the worst case, not 20 cheap local calls.
+ */
+export declare const MAX_LLM_SUMMARIES = 20;
+export interface MineConsensusDeps {
+    /** Effective consensus configuration. Required — the miner reads no config. */
+    config: ConsensusConfig;
+    /** Corpus loader override. Defaults to the real read-only loader. */
+    loadCorpus?: (directory: string, options: {
+        maxEvidenceItems: number;
+        maxExcerptChars: number;
+        filter?: (observation: CorpusObservation) => boolean;
+    }) => Promise<ConsensusCorpus>;
+    /**
+     * Optional LLM dispatcher. Absent ⇒ deterministic statements are kept.
+     * Injected rather than constructed so the miner never reaches for a runtime
+     * client and stays unit-testable without one.
+     */
+    dispatcher?: EvaluationModelDispatcher;
+    /** Model id for summarization dispatches. */
+    summarizationModelId?: string;
+    /** Prefixed-swarm selector forwarded to the dispatcher. */
+    preferredSwarm?: string;
+    /** Parent session for dispatched child sessions. */
+    sessionId?: string;
+    /** Agent role recorded in proposal provenance. */
+    agentRole?: string;
+    /**
+     * Fingerprints already proposed by earlier reports. A proposal whose
+     * fingerprint appears here is suppressed so a standing recommendation is not
+     * re-proposed on every mining run.
+     */
+    priorFingerprints?: Iterable<string>;
+    /** Clock seam. Defaults to `Date.now`-backed ISO output. */
+    now?: () => Date;
+}
+export interface MineConsensusResult {
+    report: ConsensusReportV1;
+    /** True when `maxEvidenceItems` truncated the corpus. */
+    truncated: boolean;
+    /** Corpus sources that could not be read. */
+    unreadableSources: string[];
+    /** Attributes emitted as investigation notes rather than proposals. */
+    investigationNoteCount: number;
+    /** Proposals suppressed because a prior report already carries them. */
+    dedupedProposalCount: number;
+    /** How many statements the LLM actually restated. */
+    summarizedCount: number;
+    /** Why summarization did not run, when it did not. */
+    summarizationSkippedReason?: 'disabled_by_config' | 'no_dispatcher' | 'no_attributes';
+}
+/**
+ * A report body, with the three hash-excluded fields optional so both the
+ * pre-id construction path and the post-read verification path can call the
+ * same function.
+ */
+export type ConsensusReportIntegrityInput = Omit<ConsensusReportV1, 'integrityHash' | 'reportId' | 'generatedAt'> & Partial<Pick<ConsensusReportV1, 'integrityHash' | 'reportId' | 'generatedAt'>>;
+/**
+ * Recompute a report's integrity hash from its own content.
+ *
+ * Deliberately subtractive rather than additive: it hashes everything except
+ * the named exclusions, so a field added to `ConsensusReportV1` later is covered
+ * automatically. An additive allow-list would silently leave new fields
+ * unhashed — the failure mode where a report's content changes but its
+ * integrity hash does not.
+ *
+ * Exclusions fall into two classes, both failing the same test — "would an
+ * identical corpus produce an identical value?":
+ *
+ * 1. **Who and when, as opposed to what.** The report's own `generatedAt` (plus
+ *    `reportId`, which is *derived* from this hash and would otherwise be
+ *    circular), and every proposal's ENTIRE `provenance.writeOrigin` — the
+ *    `producedAt` clock and the `sessionId` / `agentRole` that identify whoever
+ *    physically ran the mine — which, since `ProposedSkillChangeProvenance`
+ *    dropped the unreachable `agentId`, is the whole of that object. All are
+ *    real provenance and stay in the artifact; none of them is content.
+ *
+ *    Excluding the identity fields is not cosmetic. `sessionId` comes from
+ *    `ctx.sessionID`, so with only `producedAt` excluded, two sessions mining a
+ *    byte-identical corpus produced different `integrityHash` values and
+ *    therefore different `reportId`s — the same user-visible symptom as hashing
+ *    the model's wording, just from a different field. Who ran the mine cannot
+ *    be allowed to change what the mine found.
+ * 2. **Non-reproducible model prose** — every attribute's `llmSummary`. This one
+ *    is not a nicety: `llm_summarization_enabled` defaults to `true`, so hashing
+ *    a model's wording made "same inputs ⇒ identical hash" FALSE in the default
+ *    configuration. Two mining runs over a byte-identical corpus produced
+ *    different `integrityHash` values and therefore different `reportId`s,
+ *    which defeats content addressing, defeats `isEquivalent` in the store, and
+ *    turns every re-mine into a new artifact. The deterministic `statement` that
+ *    the summary paraphrases IS hashed, so nothing about the finding escapes
+ *    coverage — only the paraphrase does.
+ */
+export declare function computeConsensusIntegrityHash(report: ConsensusReportIntegrityInput): string;
+/** Deterministic report id, derived from the integrity hash. */
+export declare function deriveReportId(integrityHash: string): string;
+/**
+ * Mine consensus attributes and proposals from `directory`'s `.swarm/` evidence.
+ *
+ * MUTATES NOTHING. The returned report is a value; persisting it is the
+ * caller's separate, explicit `writeConsensusReport` call.
+ */
+export declare function mineConsensus(directory: string, request: ConsensusMineRequest, deps: MineConsensusDeps): Promise<MineConsensusResult>;

package/dist/consensus/public-api.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Stable package-level boundary for the consensus miner (issue #1821).
+ *
+ * This module exports exactly one thing — `mineAndStoreConsensusV1` — because
+ * exactly one caller exists: `src/tools/consensus-mine.ts`. It previously also
+ * exported a frozen callable `consensusV1` namespace mirroring
+ * `src/evaluation/public-api.ts`, together with a `src/consensus/index.ts`
+ * barrel. Both were dead RUNTIME VALUES — a public API surface with no importer
+ * anywhere in `src/`, `tests/`, or `scripts/` — and the evaluation precedent did
+ * not apply: that barrel IS consumed (`src/index.ts` re-exports `evaluationV1`),
+ * whereas nothing ever wired consensus into the plugin entry. Both were removed
+ * rather than left standing (see the "never ship unwired code" directive in
+ * `CLAUDE.md`). If a future consumer needs a versioned namespace, reintroduce it
+ * together with that consumer.
+ *
+ * The two type aliases below have no by-name importer either, and are kept for a
+ * different and declared reason: they are the parameter and return shapes of
+ * `mineAndStoreConsensusV1` itself, so they are already handed out by its
+ * signature. See the export carve-out note at the bottom of `./contracts.ts`.
+ */
+import type { ConsensusMineRequest, ConsensusReportV1 } from './contracts.js';
+import { type MineConsensusDeps } from './miner.js';
+export type MineAndStoreConsensusOptions = {
+    directory: string;
+    request: ConsensusMineRequest;
+    deps: MineConsensusDeps;
+};
+export type MineAndStoreConsensusResult = {
+    report: ConsensusReportV1;
+    truncated: boolean;
+    unreadableSources: string[];
+    investigationNoteCount: number;
+    dedupedProposalCount: number;
+    summarizedCount: number;
+    summarizationSkippedReason?: string;
+};
+/**
+ * Mine, then persist. The two phases stay separable on purpose — `mineConsensus`
+ * mutates nothing and is safe to call speculatively; only this boundary writes,
+ * and it writes exactly one artifact: the report itself.
+ */
+export declare function mineAndStoreConsensusV1(options: MineAndStoreConsensusOptions): Promise<MineAndStoreConsensusResult>;

package/dist/consensus/store.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Immutable persistence for consensus reports (issue #1821, Workstream C).
+ *
+ * Reports live under `.swarm/evolution/consensus/<reportId>.json`, alongside the
+ * evaluation substrate's runs and decisions. The write goes through the shared
+ * `writeImmutableArtifact` pipeline in `src/evidence/immutable-store.ts` — the
+ * same one the evaluation store binds — so the lock/read/compare/atomic-rename
+ * sequence exists exactly once in the codebase. This module supplies only the
+ * three parameters that pipeline deliberately leaves to its callers: the lock
+ * actor, the canonical serializer, and the conflict-error factory.
+ *
+ * Idempotence has three wrinkles a report has and a run does not, all reachable
+ * under the DEFAULT configuration. Two mining runs over an identical corpus
+ * produce reports that differ in `generatedAt` (a wall clock), in each
+ * proposal's `provenance.writeOrigin` (the `producedAt` clock plus the
+ * `sessionId` / `agentRole` of whoever ran the mine), and — because
+ * `llm_summarization_enabled` defaults to `true` — in each attribute's
+ * `llmSummary`, which is model prose and is not reproducible. All three are
+ * excluded from `integrityHash`, so an `isEquivalent` escape hatch comparing
+ * recomputed hashes treats such reports as the same artifact, exactly how
+ * `savePromotionDecision` handles `decidedAt`. A report that differs in any
+ * *content* field still conflicts.
+ */
+import type { ConsensusReportV1 } from './contracts.js';
+export declare class ConsensusConflictError extends Error {
+    constructor(message: string);
+}
+export declare class ConsensusIntegrityError extends Error {
+    constructor(message: string);
+}
+/**
+ * Persist a report exactly once.
+ *
+ * The integrity hash is **verified before persist**, not merely recorded: a
+ * report whose declared hash does not match its own content is rejected rather
+ * than written, so a corrupted or hand-edited report can never enter the store
+ * and later be trusted on read.
+ */
+export declare function writeConsensusReport(directory: string, input: ConsensusReportV1): Promise<ConsensusReportV1>;
+/**
+ * Read one report. Returns `undefined` when absent.
+ *
+ * Re-verifies the integrity hash on the way out: a report that was tampered with
+ * on disk after being written must not be handed to a caller as authoritative.
+ */
+export declare function readConsensusReport(directory: string, reportId: string): Promise<ConsensusReportV1 | undefined>;
+export type ConsensusListSummary = {
+    reports: ConsensusReportV1[];
+    /** Report ids present on disk that failed to parse or verify. */
+    corruptReportIds: string[];
+};
+/**
+ * Enumerate every stored report, newest first.
+ *
+ * Corrupt entries are reported rather than thrown so one bad file cannot make
+ * the whole history unreadable — the same posture `listGateAuditResults` takes.
+ * Sorted by `generatedAt` descending, ties broken by id, so the ordering is
+ * total and reproducible.
+ */
+export declare function listConsensusReports(directory: string): Promise<ConsensusListSummary>;
+export type ConsensusPruneResult = {
+    /** Report ids deleted, oldest-first. */
+    deleted: string[];
+    /** Report ids retained. */
+    retained: string[];
+    /** Ids that failed to delete, with the reason. Never fatal. */
+    failed: Array<{
+        reportId: string;
+        error: string;
+    }>;
+    /**
+     * Report ids on disk that failed to parse or verify.
+     *
+     * These are neither deleted nor counted in `retained`, so without this field
+     * `deleted + retained` silently under-counts what is actually stored and a
+     * caller printing those two numbers describes a store it cannot see all of.
+     * Empty when pruning is disabled, because that mode enumerates nothing.
+     */
+    corrupt: string[];
+};
+/**
+ * Count the report files present, without parsing or verifying any of them.
+ *
+ * This is the cheap listing primitive `/swarm status` needs: `readdir` plus a
+ * name filter, no JSON parse and no hash recomputation, so surfacing the store
+ * in an interactive command costs one syscall rather than a full re-verification
+ * of every stored report. It therefore counts CORRUPT reports too — it counts
+ * files whose name is a well-formed report id, which is exactly the claim the
+ * status line makes. Use `listConsensusReports` when you need content.
+ */
+export declare function countConsensusReportFiles(directory: string): Promise<number>;
+/**
+ * Enforce `consensus.report_retention`.
+ *
+ * Deliberate posture, mirroring the evaluation substrate's retention rules:
+ * - `retain === 0` **disables** pruning rather than deleting everything. The
+ *   schema's `min(0)` bound reads as "the constraint is off", the same way
+ *   `default_min_successful_runs: 0` turns that gate off. Interpreting it as
+ *   "keep zero reports" would delete the report the caller just wrote.
+ * - Corrupt reports are **never** deleted. An unparseable artifact is data-
+ *   quality evidence; silently discarding it destroys the only trace of the bug
+ *   that produced it. They are reported as `corrupt` rather than dropped
+ *   silently: they are excluded from `retained` as well as from `deleted`, so a
+ *   caller that printed only those two numbers would describe a store smaller
+ *   than the one on disk.
+ * - Newest-first by `generatedAt`, ties broken by id, so pruning is a total
+ *   order and two runs over the same store delete the same files.
+ * - Only files directly under `.swarm/evolution/consensus/` with a validated
+ *   `<id>.json` name are candidates; nothing recurses (AGENTS.md invariant 4).
+ */
+export declare function pruneConsensusReports(directory: string, retain: number): Promise<ConsensusPruneResult>;
+/**
+ * Every proposal fingerprint already present in the store.
+ *
+ * This is what the miner dedupes against so a standing recommendation is not
+ * re-proposed on every run. Corrupt reports are skipped: an unreadable prior
+ * report is a reason to re-propose, not to crash.
+ */
+export declare function listConsensusProposalFingerprints(directory: string): Promise<Set<string>>;