@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/ai_council/information_gain.ts

@@ -0,0 +1,293 @@
+/**
+ * Expected information gain per cost — step 8.4.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` step 8.4: *"Score
+ * optional next calls by expected information gain per cost, deterministic and
+ * inspectable to start"*, verified by *"the score is reproducible from the
+ * recorded inputs"*.
+ *
+ * ## Every feature is one the tree already computes
+ *
+ * The gain terms are read from {@link DisagreementSignal}
+ * (`disagreement_signal.ts:134`), which 6.1 already established as **zero-cost
+ * and structural** — every input arrives from a verdict the run has already
+ * paid for. No new similarity measure, no new threshold, no model call to
+ * decide whether to make a model call. Forking a second feature set here would
+ * be the same defect 1A.1 forbids for the question hash: two answers to one
+ * question, and the second is the one nobody updates.
+ *
+ * ## "Deterministic and inspectable" is enforced, not promised
+ *
+ * - {@link scoreNextCall} is pure: same record in, same bytes out.
+ * - Terms are summed in a FIXED declared order, so floating-point association
+ *   cannot vary with input ordering.
+ * - The result carries every term's raw value, weight and contribution, so the
+ *   number can be re-derived by hand from what is printed.
+ * - The published figures are rounded to {@link SCORE_PRECISION} decimals, so a
+ *   record round-tripped through JSON reproduces bit-identically.
+ * - {@link reproduceScore} is the verify clause made executable: recompute from
+ *   a record's own inputs and compare.
+ *
+ * ## What an UNAVAILABLE component does, and why it is not zero
+ *
+ * A component the run could not observe is dropped from BOTH the numerator and
+ * the weight denominator. Treating it as 0 would read "not measured" as
+ * "measured, and it showed agreement" — the same NOT-RUN-is-not-a-null failure
+ * this roadmap records elsewhere. `basisComponents` reports how many terms the
+ * gain actually rests on, so a gain over one component is distinguishable from
+ * a gain over five, and {@link scoreNextCall} refuses to produce a gain at all
+ * when nothing is available.
+ *
+ * ## Honest scope
+ *
+ * This scores; it does not decide. 8.5 — stopping when the next call has low
+ * expected value — is explicitly gated on Phase 2 evidence
+ * (`blocker: phase-2-benchmark-cost`), and the weights below are **declared
+ * priors, not fitted values**: nothing has been benchmarked against them.
+ * `revisit-if`: the Phase 2 benchmark shows a term that does not predict a
+ * changed finding, or shows one that does and is absent here.
+ */
+import type { DisagreementSignal, SignalComponent } from './disagreement_signal.js';
+
+/** Decimals every published figure is rounded to. Makes JSON round-trip exact. */
+export const SCORE_PRECISION = 6;
+
+/**
+ * The gain terms, in the FIXED order they are summed.
+ *
+ * `direction` says how the raw component relates to expected gain:
+ *   `'rising'`  — the component rises with DISAGREEMENT, so it is used as-is;
+ *   `'falling'` — it rises with AGREEMENT, so `1 - value` is the gain.
+ *
+ * `weight` is a declared prior. The two divergence terms carry the most because
+ * an unresolved split is the one state where another call can still change the
+ * verdict; `selfSimilarity` is inverted and weighted low because high
+ * self-similarity is exhaustion, which 6.2 already treats as a stop condition
+ * rather than as a gain signal.
+ */
+export const GAIN_TERMS: readonly {
+    readonly key: keyof DisagreementSignal & string;
+    readonly weight: number;
+    readonly direction: 'rising' | 'falling';
+    readonly why: string;
+}[] = [
+    {
+        key: 'stanceDivergence',
+        weight: 0.30,
+        direction: 'rising',
+        why: 'an unresolved split is the one state where another call can still change the verdict',
+    },
+    {
+        key: 'contradictionCount',
+        weight: 0.25,
+        direction: 'rising',
+        why: 'an explicit disagree vote names a specific thing a rebuttal can settle',
+    },
+    {
+        key: 'rankUncertainty',
+        weight: 0.20,
+        direction: 'rising',
+        why: 'tied findings mean the ranking has not resolved and one more input may break it',
+    },
+    {
+        key: 'confidenceSpread',
+        weight: 0.15,
+        direction: 'rising',
+        why: 'a wide confidence range means the members disagree about how sure to be, not only about what',
+    },
+    {
+        key: 'findingOverlap',
+        weight: 0.07,
+        direction: 'falling',
+        why: 'high overlap means the members are already covering the same ground',
+    },
+    {
+        key: 'selfSimilarity',
+        weight: 0.03,
+        direction: 'falling',
+        why: 'high self-similarity is exhaustion, which 6.2 handles as a stop rather than as a gain',
+    },
+];
+
+/** `contradictionCount` is a count, not 0..1; this is its saturation point. */
+export const CONTRADICTION_SATURATION = 5;
+
+/** The cost half. Both figures come from the caller's own estimate. */
+export interface CallCost {
+    /** Provider calls the option would issue. Must be > 0 to be scorable. */
+    readonly calls: number;
+    /** Estimated spend in USD. */
+    readonly costUsd: number;
+}
+
+/** One scorable option, exactly as recorded. */
+export interface NextCallInputs {
+    /** Stable identifier for the option — `cross-exam:c-001`, `round-3`, … */
+    readonly optionId: string;
+    readonly signal: DisagreementSignal;
+    /** Open adversarial triggers. Rising with gain: an open objection is unfinished argument. */
+    readonly unresolvedAdversarialTriggers: number;
+    readonly cost: CallCost;
+}
+
+/** One term's full arithmetic, so the total can be re-derived by hand. */
+export interface TermBreakdown {
+    readonly key: string;
+    readonly available: boolean;
+    /** The component's raw value, or `null` when unavailable. */
+    readonly raw: number | null;
+    /** Why it is unavailable, verbatim from the signal. `null` when available. */
+    readonly reason: string | null;
+    /** Raw mapped into 0..1 gain space (direction applied, count saturated). */
+    readonly normalised: number | null;
+    readonly weight: number;
+    /** `normalised * weight`, or 0 when unavailable. */
+    readonly contribution: number;
+}
+
+export interface NextCallScore {
+    readonly optionId: string;
+    /** 0..1 expected gain, or `null` when NO component was observable. */
+    readonly gain: number | null;
+    /** How many terms the gain rests on. 0..6. */
+    readonly basisComponents: number;
+    /** Sum of the weights of the available terms — the gain's denominator. */
+    readonly weightUsed: number;
+    /** `gain / costUsd`, or `null` when gain is null or cost is not positive. */
+    readonly gainPerCost: number | null;
+    /** `gain / calls`, or `null` on the same conditions. */
+    readonly gainPerCall: number | null;
+    readonly cost: CallCost;
+    readonly terms: readonly TermBreakdown[];
+    /** The trigger bonus applied to the gain, already included in it. */
+    readonly triggerBonus: number;
+}
+
+/** Round to {@link SCORE_PRECISION}. `-0` normalised to `0` so JSON round-trips. */
+export function roundScore(v: number): number {
+    const f = 10 ** SCORE_PRECISION;
+    const r = Math.round(v * f) / f;
+    return Object.is(r, -0) ? 0 : r;
+}
+
+function _normalise(key: string, c: SignalComponent, direction: 'rising' | 'falling'): number {
+    const raw = (c as { value: number }).value;
+    // `contradictionCount` is the one count-valued component; everything else
+    // is already 0..1 by its own contract.
+    const scaled = key === 'contradictionCount' ? Math.min(1, raw / CONTRADICTION_SATURATION) : Math.min(1, Math.max(0, raw));
+    return direction === 'rising' ? scaled : 1 - scaled;
+}
+
+/**
+ * Score one option. Pure — no clock, no randomness, no file, no network.
+ *
+ * The trigger bonus is additive and capped: an unresolved adversarial trigger
+ * raises expected gain because an open objection is unfinished argument (6.2's
+ * own reasoning), but it may not by itself drive the gain to 1 — that would let
+ * one open trigger outvote every measured component.
+ */
+export function scoreNextCall(inputs: NextCallInputs): NextCallScore {
+    const terms: TermBreakdown[] = [];
+    let weighted = 0;
+    let weightUsed = 0;
+    let basisComponents = 0;
+
+    for (const t of GAIN_TERMS) {
+        const c = inputs.signal[t.key] as SignalComponent;
+        if (c !== undefined && c.available) {
+            const normalised = _normalise(t.key, c, t.direction);
+            const contribution = normalised * t.weight;
+            weighted += contribution;
+            weightUsed += t.weight;
+            basisComponents += 1;
+            terms.push({
+                key: t.key,
+                available: true,
+                raw: roundScore(c.value),
+                reason: null,
+                normalised: roundScore(normalised),
+                weight: t.weight,
+                contribution: roundScore(contribution),
+            });
+        } else {
+            terms.push({
+                key: t.key,
+                available: false,
+                raw: null,
+                reason: c === undefined ? 'component-absent' : c.reason,
+                normalised: null,
+                weight: t.weight,
+                contribution: 0,
+            });
+        }
+    }
+
+    const triggerBonus = roundScore(Math.min(0.2, 0.1 * Math.max(0, inputs.unresolvedAdversarialTriggers)));
+    const gain =
+        basisComponents === 0 ? null : roundScore(Math.min(1, weighted / weightUsed + triggerBonus));
+
+    const scorable = gain !== null;
+    return {
+        optionId: inputs.optionId,
+        gain,
+        basisComponents,
+        weightUsed: roundScore(weightUsed),
+        gainPerCost:
+            scorable && inputs.cost.costUsd > 0 ? roundScore((gain as number) / inputs.cost.costUsd) : null,
+        gainPerCall: scorable && inputs.cost.calls > 0 ? roundScore((gain as number) / inputs.cost.calls) : null,
+        cost: inputs.cost,
+        terms,
+        triggerBonus,
+    };
+}
+
+/** Inputs plus the score they produced — the thing 8.4 calls "the recorded inputs". */
+export interface NextCallRecord {
+    readonly inputs: NextCallInputs;
+    readonly score: NextCallScore;
+}
+
+export function recordNextCall(inputs: NextCallInputs): NextCallRecord {
+    return { inputs, score: scoreNextCall(inputs) };
+}
+
+/**
+ * The verify clause, executable: recompute the score from the record's OWN
+ * inputs and report whether it matches byte-for-byte under JSON.
+ */
+export function reproduceScore(record: NextCallRecord): { reproduced: boolean; recomputed: NextCallScore } {
+    const recomputed = scoreNextCall(record.inputs);
+    return { reproduced: JSON.stringify(recomputed) === JSON.stringify(record.score), recomputed };
+}
+
+/** Rank options by gain per USD, then by gain per call, then by id. Deterministic. */
+export function rankByGainPerCost(scores: readonly NextCallScore[]): NextCallScore[] {
+    return [...scores].sort(
+        (a, b) =>
+            (b.gainPerCost ?? -1) - (a.gainPerCost ?? -1) ||
+            (b.gainPerCall ?? -1) - (a.gainPerCall ?? -1) ||
+            (a.optionId < b.optionId ? -1 : a.optionId > b.optionId ? 1 : 0),
+    );
+}
+
+/** Inspectable rendering — every term's arithmetic, so the total is re-derivable by hand. */
+export function renderNextCallScore(s: NextCallScore): string {
+    const lines = [`option ${s.optionId}`];
+    for (const t of s.terms) {
+        lines.push(
+            t.available
+                ? `  ${t.key.padEnd(20)} raw ${String(t.raw).padEnd(10)} × w ${t.weight.toFixed(2)} = ${String(t.contribution)}`
+                : `  ${t.key.padEnd(20)} unavailable (${t.reason ?? '—'}) — excluded from numerator AND denominator`,
+        );
+    }
+    lines.push(
+        `  trigger bonus        ${String(s.triggerBonus)}`,
+        `  weight used          ${String(s.weightUsed)} over ${String(s.basisComponents)} component(s)`,
+        `  gain                 ${s.gain === null ? 'null (nothing observable)' : String(s.gain)}`,
+        `  cost                 ${String(s.cost.calls)} call(s), $${s.cost.costUsd.toFixed(4)}`,
+        `  gain per USD         ${s.gainPerCost === null ? 'null' : String(s.gainPerCost)}`,
+        `  gain per call        ${s.gainPerCall === null ? 'null' : String(s.gainPerCall)}`,
+        '',
+    );
+    return lines.join('\n');
+}

package/src/scripts/ai_council/inline_findings.ts

@@ -0,0 +1,340 @@
+// Phase 1B — inline findings, the whole concern in one module.
+//
+// The consensus round's pass 1 asks every member a SECOND time, in a separate
+// paid call, to restate its own analysis as a JSON findings array. Phase 1B of
+// `road-to-inbox-harvest-2026-08-e-council-topology-evidence` asks for that
+// array in the FIRST reply instead, and keeps the extraction call as the
+// repair path.
+//
+// It lives here rather than spread across `orchestrator.ts`, `consensus.ts` and
+// `council_cli.ts` for a reason the source-size budget made concrete: all three
+// are far past the 1500-line ceiling, so a new concern added to them is new
+// budget excess with nowhere to go. Concentrating it also puts the four pieces
+// that have to agree — the contract text's promise, the locator, the harvest
+// and the config predicate — where a reader meets them together.
+import type { ExternalAIClient, CouncilResponse } from './clients.js';
+import type { Finding, FindingsExtraction } from './consensus.js';
+import { _BARE_ARRAY_SRC, _JSON_BLOCK_SRC, parse_findings_outcome } from './consensus.js';
+import { INLINE_FINDINGS_CONTRACT, STANCE_LINE_CONTRACT } from './prompts.js';
+
+/** Python `str.strip()` parity, as everywhere else in this package. */
+const _strip = (s: string): string => s.replace(/^\s+|\s+$/g, '');
+
+/**
+ * Phase 1B — the deliberation reply split into argument and findings block.
+ *
+ * `deliberation_text` is what every downstream consumer should see: peer
+ * review, chairman synthesis, and the rendered artifact evaluate the member's
+ * REASONING, and a schema block restating selected conclusions is scaffolding,
+ * not argument. Leaving it in amplifies a concise finding simply because it
+ * appears twice — the AI council's stated reason (2026-08-30, 2 of 2 seats) for
+ * choosing to strip.
+ *
+ * `block` is the exact consumed span. One locator produces both halves, so the
+ * text that is parsed and the text that is removed cannot disagree — the
+ * council's other requirement, and the reason there is no separate
+ * "find and remove a JSON fence" function anywhere in this change.
+ */
+export interface InlineFindingsSplit {
+    /** The reply with the consumed block removed. Equals the input when `found` is false. */
+    readonly deliberation_text: string;
+    /** The consumed span, ready for `parse_findings_outcome`. `''` when `found` is false. */
+    readonly block: string;
+    readonly found: boolean;
+}
+
+/**
+ * Split a full analysis reply at its TRAILING findings block.
+ *
+ * A locator, deliberately not a second parser: `parse_findings_outcome` stays
+ * the only thing that decides whether a candidate IS a findings block, and this
+ * narrows where it looks.
+ *
+ * The narrowing is not cosmetic. `_extract_json_array` returns the FIRST match,
+ * which is correct for an extraction reply (the reply IS the array) and wrong
+ * for an analysis reply, where the prose above may legitimately quote a JSON
+ * array — the analysis lens exists to critique analyser OUTPUT, so a quoted
+ * array is an ordinary thing to find there. First-match would read the quoted
+ * array as the member's findings and never reach the real block.
+ *
+ * `INLINE_FINDINGS_CONTRACT` asks for the block LAST, so LAST is what this
+ * reads. `found: false` when nothing array-shaped is present, which the caller
+ * treats as "no inline block" and repairs with the extraction call — the same
+ * outcome as today, never worse.
+ *
+ * **Precisely: "last FENCED, else last bare" — not "last in the text."** The
+ * two patterns are tried in `_extract_json_array`'s precedence order and the
+ * first pattern that matches at all wins, so a reply carrying a quoted FENCED
+ * array above its own trailing BARE array selects the quoted one. Stated
+ * because the docstring used to claim the simpler rule, which a completion
+ * review of 2026-08-30 found untrue against that ordering; the precedence test
+ * puts the bare array first and so never exercises the collision.
+ *
+ * The consequence is bounded rather than eliminated. `_isOwnFindingsBlock`
+ * below now rejects any array whose items are not all well-formed findings, so
+ * the common shape of a quoted array — evidence rows, log lines, a schema
+ * fragment — no longer wins. What survives is a quoted array of well-formed
+ * findings sitting fenced above the member's own bare one, and that is recorded
+ * as a known residual of 1B.4's gate rather than claimed away.
+ */
+export function split_inline_findings(text: string): InlineFindingsSplit {
+    const none: InlineFindingsSplit = { deliberation_text: text, block: '', found: false };
+    if (!text) {
+        return none;
+    }
+    // Deliberately the same two patterns `_extract_json_array` uses, in the same
+    // precedence order — fenced beats bare — so a block this locator returns is
+    // one that function can also read. Only the match SELECTION differs: last,
+    // not first.
+    for (const src of [_JSON_BLOCK_SRC, _BARE_ARRAY_SRC]) {
+        const re = new RegExp(src, 'gs');
+        let last: RegExpExecArray | null = null;
+        let m: RegExpExecArray | null;
+        while ((m = re.exec(text)) !== null) {
+            last = m;
+            // A zero-length match would spin forever; the patterns cannot produce
+            // one (both require at least `[]`), but the guard costs nothing and a
+            // future pattern edit is exactly when it would matter.
+            if (m.index === re.lastIndex) {
+                re.lastIndex += 1;
+            }
+        }
+        if (last) {
+            const start = last.index;
+            const end = start + last[0].length;
+            return {
+                deliberation_text: `${text.slice(0, start)}${text.slice(end)}`,
+                block: text.slice(start, end),
+                found: true,
+            };
+        }
+    }
+    return none;
+}
+
+/**
+ * How a member's findings were obtained — the RECORDED provenance, wider than
+ * `FindingsParseOutcome`, which describes one parse of one piece of text.
+ *
+ * Typed rather than a bare string because Phase 1B's promotion gate is computed
+ * off exactly these values: an untyped `Map<string, string>` makes the number
+ * that decides the experiment vulnerable to a misspelling no compiler would
+ * catch. The AI council (2026-08-30, 2 of 2 seats) called the pre-existing bare
+ * `'parsed-after-reask'` technical debt rather than a precedent to extend.
+ *
+ * `'parsed'` keeps its shipped meaning — read from the separate extraction
+ * call — and is unambiguous now that `'parsed-inline'` names the other source.
+ * One seat asked for a rename to `'parsed-extraction'`; renaming a value that
+ * is already recorded and compared against is a separate change with its own
+ * migration, and is recorded here as declined-with-a-reason, not overlooked.
+ */
+export type RecordedExtractionOutcome =
+    | 'parsed'
+    | 'empty'
+    | 'parse_failed'
+    | 'parsed-after-reask'
+    | 'parsed-inline';
+
+/**
+ * Phase 1B — harvest the inline findings block out of each deliberation reply.
+ *
+ * Runs BETWEEN the deliberation and every consumer of its text. That placement
+ * is the load-bearing part and it was a defect the AI council caught
+ * (2026-08-30, 2 of 2 seats): peer review and chairman synthesis read the
+ * responses BEFORE the consensus round does, so parsing inside
+ * `run_consensus_scoring` would have left the schema block in the text those
+ * two evaluate — which is precisely the amplification the strip exists to
+ * prevent.
+ *
+ * MUTATES `text` on each response whose block parsed, replacing the consumed
+ * span with a one-line marker. Mutation rather than a parallel clean copy
+ * because two representations of one response means every downstream consumer
+ * has to know which one it holds, and the one that forgets is a silent bug.
+ * `CouncilResponse.text` is already mutated on the stance-repair path, so this
+ * is the established seam rather than a new one.
+ *
+ * The marker is deliberately visible. Stripping without an observable trace is
+ * a silent mutation of the artifact a reader takes for a transcript, and one
+ * seat made an observable marker a condition of its verdict; the other reached
+ * the same concern from the auditability side. ~90 characters replaces ~300 of
+ * JSON, so the scaffolding is gone and the fact of its removal is not.
+ *
+ * Returns the per-member extraction keyed by `provider:model` — the same key
+ * `run_consensus_scoring` records outcomes under. A member whose block did not
+ * parse gets NO entry and its `text` is left exactly as the model wrote it, so
+ * the repair extraction call downstream still sees the raw reply.
+ */
+/**
+ * Is this extraction the member's OWN findings block, or just some JSON it quoted?
+ *
+ * `outcome === 'parsed'` was the whole test until a completion review of
+ * 2026-08-30 showed it decides nothing: `parse_findings_outcome` returns
+ * `'parsed'` for ANY syntactically valid JSON array, and `_collect_findings`
+ * silently skips items missing `id` or `text` while the outcome stays `'parsed'`.
+ * So a reply carrying no findings block at all, but quoting
+ * `[{"file":"src/a.ts","line":42}]` as evidence, was recorded as a successful
+ * inline extraction with zero findings — and its quoted evidence was DELETED
+ * from the text the peer review, the chairman and the artifact read. Worse, the
+ * failure was recorded as a success in the rate the 1B.4 promotion gate reads,
+ * so the gate could not see it.
+ *
+ * Two conjuncts, and both are needed:
+ *
+ * - **it parsed** — unchanged;
+ * - **every item it saw became a finding** — `findings.length === item_count`.
+ *   A findings block from a member following the contract has well-formed items
+ *   throughout. An array where some or all items lack `id`/`text` is something
+ *   else, whatever it parsed to.
+ *
+ * The bare-`[]` answer keeps working: `item_count` is 0 and `findings.length`
+ * is 0, so the conjunction holds and "I found nothing" is still an answer
+ * rather than a re-ask.
+ *
+ * **What this does NOT decide, stated rather than implied away.** A member that
+ * quotes ANOTHER member's well-formed `[{"id":…,"text":…}]` array, as the last
+ * block in its reply, is indistinguishable from its own by shape — and would
+ * still be attributed to the quoting member. Shape cannot separate those; only
+ * provenance could, and the reply carries none. It is narrower than the case
+ * fixed here (the quote must be well-formed AND last AND the member must have
+ * emitted no block of its own), it is visible in the emitted marker, and it is
+ * carried into 1B.4's gate as a known residual rather than counted as a success.
+ */
+function _isOwnFindingsBlock(ex: {
+    outcome: string;
+    findings: readonly unknown[];
+    item_count: number;
+}): boolean {
+    return ex.outcome === 'parsed' && ex.findings.length === ex.item_count;
+}
+
+export function harvest_inline_findings(
+    members: readonly ExternalAIClient[],
+    responses: readonly CouncilResponse[],
+): Map<string, FindingsExtraction> {
+    const out = new Map<string, FindingsExtraction>();
+    const model_by_name = new Map<string, string>();
+    for (const m of members) {
+        model_by_name.set(m.name, m.model);
+    }
+    for (const resp of responses) {
+        const model = model_by_name.get(resp.provider);
+        if (model === undefined || resp.error || !_strip(resp.text)) {
+            continue;
+        }
+        const split = split_inline_findings(resp.text);
+        if (!split.found) {
+            continue;
+        }
+        const source = `${resp.provider}:${model}`;
+        const ex = parse_findings_outcome(split.block, { source });
+        if (!_isOwnFindingsBlock(ex)) {
+            // Not a findings block after all — most likely a JSON array the member
+            // quoted from the artifact. Leave the reply untouched: stripping text
+            // we could not read would remove evidence and buy nothing.
+            continue;
+        }
+        out.set(source, ex);
+        // Retain the reply BEFORE rewriting it — this is the single write of
+        // `CouncilResponse.raw_text`, and the reason that field exists.
+        //
+        // The marker appended below promises "the raw reply is retained in the
+        // session record". Until 2026-08-30 that promise was false, and a
+        // completion review is what caught it: the persisted record is
+        // serialized from these same objects AFTER this harvest runs
+        // (`council_cli._serialise_responses`), so the stripped text was the
+        // only text that survived anywhere, and the auditability condition the
+        // council attached to this feature was unmet.
+        //
+        // `null` stays the honest value for a reply nothing rewrote — it means
+        // "`text` IS the raw reply", never "the raw reply was lost" — which is
+        // also why the serializer omits the key entirely in that case rather
+        // than writing a duplicate of the reply into every session record.
+        resp.raw_text = resp.text;
+        const marker = `_[inline findings block extracted: ${String(ex.findings.length)} item(s); the raw reply is retained in the session record.]_`;
+        resp.text = `${_strip(split.deliberation_text)}\n\n${marker}`;
+    }
+    return out;
+}
+
+
+/**
+ * The FINAL deliberation round's volatile suffix.
+ *
+ * Two opt-in contracts ride it and their ORDER is load-bearing:
+ * `STANCE_LINE_CONTRACT` requires the stance to be the last line of the reply,
+ * so it is appended last and the findings block sits above it. A findings block
+ * appended after the stance line would contradict the instruction the member is
+ * reading, which is the one composition bug this function exists to make
+ * impossible to reintroduce.
+ *
+ * Both off → the caller's suffix is returned unchanged, so the composed default
+ * is byte-identical to a run without either feature.
+ */
+export function composeFinalRoundSuffix(
+    suffix: string,
+    opts: { is_final: boolean; inline_findings: boolean; stance_tally: boolean },
+): string {
+    if (!opts.is_final) {
+        return suffix;
+    }
+    let out = suffix;
+    if (opts.inline_findings) {
+        out = `${out}\n\n---\n\n${INLINE_FINDINGS_CONTRACT}`;
+    }
+    if (opts.stance_tally) {
+        out = `${out}\n\n---\n\n${STANCE_LINE_CONTRACT}`;
+    }
+    return out;
+}
+
+/**
+ * Consume a member's harvested findings, or report that it has none.
+ *
+ * Returns `true` when the caller should SKIP its extraction call. An entry in
+ * the map is always a short-circuit and never a partial one, because
+ * `harvest_inline_findings` records only a member whose block PARSED — a member
+ * with no entry had its reply left raw and takes the shipped extraction path
+ * over the full text.
+ */
+export function takeInlineFindings(
+    inline_extractions: ReadonlyMap<string, FindingsExtraction> | null,
+    source: string,
+    parse_outcomes: Map<string, RecordedExtractionOutcome>,
+    all_findings: Finding[],
+): boolean {
+    const inline = inline_extractions?.get(source);
+    if (inline === undefined) {
+        return false;
+    }
+    parse_outcomes.set(source, 'parsed-inline');
+    all_findings.push(...inline.findings);
+    return true;
+}
+
+/**
+ * Is the inline-findings contract active for this run?
+ *
+ * Read BEFORE the deliberation, because the contract is a prompt change and the
+ * prompt is built first; the harvest reads the same predicate so the two cannot
+ * disagree about whether a member was asked for the block. Three conjuncts, all
+ * required: consensus scoring on, this lens in its lens list, and
+ * `inline_findings` explicitly on. Any missing → `false`, and `false` is a
+ * byte-identical prompt.
+ *
+ * Reads the SYNTHESISED settings dict, not the typed config. That distinction
+ * is not academic: `_lib/council_settings_block.ts` projects the typed config
+ * into this dict, and when it did not carry the key a `true` in the YAML
+ * resolved to `undefined` and the feature was silently off with every unit test
+ * green — found by a live analysis run on 2026-08-30, not by review.
+ */
+export function inlineFindingsActive(
+    ai_cfg: Record<string, unknown>,
+    mode: string,
+): boolean {
+    const cs = (ai_cfg['consensus_scoring'] as Record<string, unknown> | undefined) ?? {};
+    if (cs['enabled'] !== true || cs['inline_findings'] !== true) {
+        return false;
+    }
+    const lenses = (cs['lenses'] as string[] | undefined) ?? ['analysis'];
+    return lenses.includes(mode);
+}