opencode-swarm 7.146.2 → 7.146.4

package/dist/context-map/telemetry.d.ts

@@ -2,8 +2,32 @@
  * Telemetry recording and persistence for the Context Capsule feature.
  *
  * Records capsule telemetry data (token estimates, cache hit/miss counts,
- * stale summary counts) per delegation. Aggregates telemetry written to
- * `.swarm/context-telemetry.jsonl` for user inspection.
+ * stale summary counts) per delegation.
+ *
+ * ISSUE #2037 (Observability PR 09/23): this store was previously an unbounded
+ * append-only JSONL (`.swarm/context-telemetry.jsonl`) full-read on every
+ * summary. It is now a BOUNDED single-file store:
+ *
+ *   Line 1:  `ctx-telemetry-manifest` header carrying a size-bounded FOLDED
+ *            aggregate (records compacted away) + health counters.
+ *   Line 2+: raw `TelemetryEntry` JSONL — the RECENT retained window, bounded
+ *            to CONTEXT_TELEMETRY_LIMITS.activeMaxBytes / activeMaxEntries.
+ *
+ * Lifetime totals = folded aggregate (header) + retained window (file). Because
+ * every structural mutation (first write, compaction, cutover migration,
+ * finalize) is a synchronous, atomic single-file rewrite (write tmp + atomic
+ * rename), a reader sees either the old complete file or the new complete file
+ * — there is no partial-apply state, so double-count and loss cannot arise from
+ * a crash mid-mutation.
+ *
+ * Concurrency: in production the ONLY writer is the plugin's
+ * `context-capsule-inject` hook, and every mutating function here is
+ * synchronous, so within a single plugin process there is no interleaving at
+ * all. A second plugin instance on the same project root is guarded by an
+ * exclusive `.swarm/context-telemetry.lock` (`wx` create, stale-broken)
+ * acquired for the compaction/cutover read→rewrite window. Cross-process
+ * CONCURRENT WRITERS to this store are documented as unsupported (it is a
+ * single-writer store). All disk failures are fail-open.
  *
  * All functions are synchronous for simplicity and reliability. The module
  * uses the `_internals` DI seam pattern so tests can override filesystem
@@ -15,9 +39,32 @@
  *
  * No `bun:` imports — this module is Node-ESM-loadable (Invariant 2).
  *
- * See issue #1104, FR-007.
+ * See issue #1104, FR-007, and issue #2037.
  */
 import * as fs from 'node:fs';
+export interface ContextTelemetryLimits {
+    /** Hard ceiling on the retained raw window (bytes). */
+    activeMaxBytes: number;
+    /** Hard ceiling on the retained raw window (entries). */
+    activeMaxEntries: number;
+    /** Raw retention age: records older than this are pruned from the raw
+     *  window (the folded aggregate is lifetime and unaffected by pruning). */
+    ageMaxMs: number;
+    /** Bounded work per legacy-migration / compaction pass (bytes folded). */
+    compactMaxBytes: number;
+    /** Hard documented read bound: getTelemetrySummary never reads more than
+     *  this, even when legacy history is arbitrarily large. Must satisfy
+     *  readMaxBytes >= activeMaxBytes + headerMaxBytes + 1 KiB slack. */
+    readMaxBytes: number;
+    /** Writes between throttled maintenance checks (mirrors core telemetry's
+     *  ROTATION_CHECK_INTERVAL). */
+    checkInterval: number;
+    /** Disk-pressure/failure warning cooldown. */
+    warnCooldownMs: number;
+    /** Upper bound for a serialized manifest header (single line). */
+    headerMaxBytes: number;
+}
+export declare const CONTEXT_TELEMETRY_LIMITS: ContextTelemetryLimits;
 /**
  * A single telemetry record for one capsule delegation.
  * Written as one JSON line to `.swarm/context-telemetry.jsonl`.
@@ -46,12 +93,23 @@ export interface TelemetryEntry {
     /** Whether capsule generation succeeded */
     success: boolean;
 }
+/**
+ * Coverage disclosure for a computed summary (issue #2037). `'partial-unmigrated'`
+ * is produced whenever the on-disk store exceeds the read bound (a pre-cutover
+ * header-less file, or a header'd store mid-migration with an unmigrated legacy
+ * tail) — in both cases the totals are INCOMPLETE. `'truncated'` is reserved for
+ * the physical "read exceeded the bound" state but is never surfaced to callers:
+ * a truncated header'd read is re-labeled `'partial-unmigrated'`.
+ */
+export type TelemetryCoverage = 'complete' | 'partial-unmigrated' | 'truncated' | 'empty';
 /**
  * Aggregate statistics computed from all telemetry entries.
- * Returned by {@link getTelemetrySummary}.
+ * Returned by {@link getTelemetrySummary}. The eight leading fields preserve the
+ * pre-issue-#2037 public surface (semantically compatible); the trailing fields
+ * are additive issue-#2037 disclosure (partial coverage / drops / retention).
  */
 export interface TelemetrySummary {
-    /** Total number of capsule delegations recorded */
+    /** Total number of capsule delegations recorded (lifetime) */
     total_delegations: number;
     /** Sum of all cache hits across entries */
     total_cache_hits: number;
@@ -67,53 +125,137 @@ export interface TelemetrySummary {
     total_skipped_reads: number;
     /** Percentage of successful capsule generations (0–100) */
     success_rate: number;
+    /** Coverage disclosure (issue #2037). 'complete' = full lifetime history
+     *  accounted; 'partial-unmigrated' = the on-disk store exceeds the read bound
+     *  (legacy history not yet fully migrated) so only the accounted part is
+     *  reflected — never presented as a complete-looking number. */
+    coverage: TelemetryCoverage;
+    /** Newest - oldest timestamp across all accounted records (ms, or null when
+     *  there is no accounted history). */
+    tracked_period_ms: number | null;
+    /** Records currently retained in the on-disk raw window. */
+    retained_entries: number;
+    /** Records folded into the durable aggregate. */
+    folded_entries: number;
+    /** Corrupt/partial lines encountered (maintenance + current window). */
+    corrupt_entries: number;
+    /** Records folded into the aggregate due to age retention — included in
+     *  lifetime totals (not an additive counter on top of them), just not
+     *  retained in the raw window. */
+    dropped_entries: number;
+    /** Approximate on-disk bytes of the store. */
+    on_disk_bytes: number;
 }
 /**
  * Test-only dependency-injection seam. Production code calls through this
  * object so tests can replace the underlying implementations without
  * `mock.module` (which leaks across files in Bun's shared test-runner process).
  * Mutating this local object is file-scoped and trivially restorable
- * via `afterEach`.
+ * via `afterEach`. `limits` is also overridable so tests can exercise small
+ * budgets.
  */
 export declare const _internals: {
     readonly appendFileSync: typeof fs.appendFileSync;
     readonly readFileSync: typeof fs.readFileSync;
     readonly existsSync: typeof fs.existsSync;
     readonly mkdirSync: typeof fs.mkdirSync;
+    readonly statSync: fs.StatSyncFn;
+    readonly renameSync: typeof fs.renameSync;
+    readonly writeFileSync: typeof fs.writeFileSync;
+    readonly unlinkSync: typeof fs.unlinkSync;
+    readonly openSync: typeof fs.openSync;
+    readonly closeSync: typeof fs.closeSync;
+    readonly readSync: typeof fs.readSync;
+    readonly limits: ContextTelemetryLimits;
+    readonly emitHealth: typeof emitContextTelemetryHealth;
+    readonly withStoreLock: typeof withStoreLock;
 };
+/** Size-bounded folded aggregate persisted in the manifest header. FOLDED-ONLY:
+ *  records compacted/cut away from the raw window. Retained records are NOT in
+ *  here. Lifetime total = folded + retained. */
+export interface FoldedAggregate {
+    delegations: number;
+    successCount: number;
+    cacheHits: number;
+    cacheMisses: number;
+    staleEntries: number;
+    tokenSum: number;
+    recommendedReads: number;
+    skippedReads: number;
+    corrupt: number;
+    dropped: number;
+    oldestTimestamp: string | null;
+    newestTimestamp: string | null;
+}
+/** The manifest header — line 1 of `.swarm/context-telemetry.jsonl`. */
+export interface TelemetryManifest {
+    v: 2;
+    type: 'ctx-telemetry-manifest';
+    schemaVersion: number;
+    folded: FoldedAggregate;
+    updatedAt: string;
+}
+declare function withStoreLock<T>(directory: string, fn: () => T): T | null;
 /**
- * Append a telemetry entry to `.swarm/context-telemetry.jsonl`.
- *
- * Creates the `.swarm/` directory if it does not exist. The entry is
- * serialized as a single JSON line and appended to the file.
- *
- * Returns `true` on success, `false` on any error. Never throws.
- *
- * @param entry - The telemetry record to append
- * @param directory - Project root directory (must contain `.swarm/`)
+ * Test seam (AGENTS.md invariant 7): resets the module-scoped maintenance
+ * counters so an unswept run in Bun's shared test-runner process cannot shift
+ * a later test's first maintenance pass. Restore is one call, always in
+ * `afterEach`.
  */
+export declare function _resetMaintenanceCounters(): void;
 export declare function recordTelemetry(entry: TelemetryEntry, directory: string): boolean;
 /**
- * Read all telemetry entries from `.swarm/context-telemetry.jsonl`.
+ * Read the telemetry entries currently retained in `.swarm/context-telemetry.jsonl`.
  *
- * Parses each line as JSON and returns the array of valid entries.
- * Malformed lines are silently skipped. Returns an empty array if the
- * file does not exist. Never throws.
+ * ISSUE #2037: this now returns ONLY the bounded recent window (the retained
+ * records after the manifest header) — NOT the entire lifetime history. Full
+ * lifetime history is represented by {@link getTelemetrySummary}, which folds
+ * the durable aggregate + retained window. This bounded read is the intended
+ * contract change: no whole-history file read on any command/runtime path.
+ *
+ * Malformed/partial lines are skipped. Returns an empty array if the file does
+ * not exist or cannot be parsed. Never throws.
  *
  * @param directory - Project root directory
- * @returns Array of parsed telemetry entries (empty if none or on error)
+ * @returns Array of parsed telemetry entries in the retained window
  */
 export declare function readTelemetry(directory: string): TelemetryEntry[];
 /**
- * Compute aggregate statistics from all telemetry entries.
- *
- * Reads all entries via {@link readTelemetry}, then computes totals
- * and averages across the dataset.
+ * Compute aggregate statistics from all telemetry entries (lifetime).
  *
- * Returns a summary with zeroed fields if no entries exist or on error.
- * Never throws.
+ * Lifetime totals = folded aggregate (durable header) + current retained
+ * window. This is a PURE READ: it never writes. Reads are always bounded to
+ * {@link ContextTelemetryLimits.readMaxBytes}; if a legacy (pre-issue-#2037)
+ * header-less file is larger than the read bound, only part of it is folded
+ * in-memory and {@link TelemetrySummary.coverage} is disclosed as
+ * 'partial-unmigrated' rather than silently presenting a complete-looking
+ * number. Returns a zeroed summary if no entries exist or on error. Never
+ * throws.
  *
  * @param directory - Project root directory
  * @returns Aggregate telemetry summary
  */
 export declare function getTelemetrySummary(directory: string): TelemetrySummary;
+/**
+ * Fold the entire remaining retained window into the aggregate and atomically
+ * publish a defined, validated cut. Called by `/swarm close` before archiving
+ * (issue #2037: "close archives a defined, validated cut and leaves active
+ * state usable"). Also migrates any header-less legacy file. Fail-open: never
+ * throws to the close pipeline.
+ *
+ * @param directory - Project root directory
+ */
+export declare function finalizeContextTelemetry(directory: string): void;
+declare function emitContextTelemetryHealth(_directory: string, payload: {
+    trigger: 'compaction' | 'close';
+    accepted: number;
+    compacted: number;
+    retained: number;
+    dropped: number;
+    corrupt: number;
+    oldest: string | null;
+    newest: string | null;
+    bytes: number;
+    limitBytes: number;
+}): void;
+export {};

package/dist/council/council-evidence-writer.d.ts

@@ -15,6 +15,7 @@
  * any filesystem op.
  */
 import { withTaskEvidenceLock } from '../evidence/task-file.js';
+import type { CouncilReviewIdentity } from './council-review-identity';
 import type { CouncilSynthesis } from './types';
 /**
  * Dependency-injection seam for testing. Tests can temporarily replace
@@ -24,5 +25,5 @@ import type { CouncilSynthesis } from './types';
 export declare const _internals: {
     withTaskEvidenceLock: typeof withTaskEvidenceLock;
 };
-export declare function writeCouncilEvidence(workingDir: string, synthesis: CouncilSynthesis, attemptId?: string, expectedGeneration?: number): Promise<void>;
+export declare function writeCouncilEvidence(workingDir: string, synthesis: CouncilSynthesis, attemptId?: string, expectedGeneration?: number, identity?: CouncilReviewIdentity): Promise<void>;
 export declare function hasCouncilEvidenceAttempt(workingDir: string, taskId: string, attemptId: string, roundNumber: number): boolean;

package/dist/council/council-freshness.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Centralized council evidence freshness evaluation (issue #2102 contract D).
+ *
+ * ONE evaluator + ONE bounded config field (`council.freshnessMaxAgeHours`,
+ * default 24 hours to preserve prior behavior) govern the phase council,
+ * architecture supervisor, and final council gates. Callers pass a single
+ * captured `nowMs` (one clock per aggregate phase preflight) so gates cannot
+ * disagree across an age boundary mid-run.
+ *
+ * Wall-clock age is never the sole identity check: generation binding is the
+ * identity-digest comparison in the gates. Freshness only decides whether
+ * otherwise-correctly-bound evidence is recent enough, not in the future,
+ * and not older than a later required input (e.g. the phase retrospective).
+ */
+import type { CouncilConfig } from './types';
+export declare const DEFAULT_FRESHNESS_MAX_AGE_MS: number;
+export type CouncilFreshnessFailureReason = 'invalid_timestamp' | 'future_timestamp' | 'stale_evidence' | 'predates_required_input' | 'invalid_required_input';
+export interface CouncilFreshnessOutcome {
+    ok: boolean;
+    reason?: CouncilFreshnessFailureReason;
+    /** Human-facing explanation (gate message body). */
+    message: string;
+    /** Concrete recovery action. */
+    recovery: string;
+}
+export declare function resolveCouncilFreshnessMaxAgeMs(config?: CouncilConfig): number;
+/**
+ * Evaluate one evidence timestamp against the shared policy.
+ *
+ * - `timestampMs: null` → invalid_timestamp (missing/unparseable).
+ * - `timestampMs > nowMs` → future_timestamp (fail closed).
+ * - age > maxAgeMs → stale_evidence.
+ * - `mustPostdateMs` set (e.g. latest retrospective timestamp) and
+ *   `timestampMs < mustPostdateMs` → predates_required_input.
+ */
+export declare function evaluateCouncilFreshness(input: {
+    nowMs: number;
+    timestampMs: number | null;
+    maxAgeMs: number;
+    mustPostdateMs?: number | null;
+}): CouncilFreshnessOutcome;
+export declare function parseTimestampMs(value: unknown): number | null;
+/**
+ * Latest retrospective-relevant timestamp from an already-loaded retro bundle
+ * (created_at/updated_at + this phase's retrospective entries). Shared by the
+ * phase-council and final-council gates so both prefer the bundle captured by
+ * the aggregate preflight over re-reading the disk (PRR-021(g)).
+ */
+export declare function latestRetroTimestampMsFromBundle(bundle: unknown, phase: number): number | null;

package/dist/council/council-review-identity.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Canonical council review identity (issue #2102 contract A).
+ *
+ * ONE shared implementation used by the task/phase/final council producers,
+ * the #2085 authoritative round store (as the scope/generation key), the
+ * evidence writers, and the completion gates. Writers and gates compute the
+ * identity from the same plan + config through this module, so the digests
+ * match byte-for-byte by construction.
+ *
+ * Identity components:
+ * - `planId` / `planIdentityHash` — collision-resistant raw plan identity
+ *   (swarm/title), delegated to `plan/utils`.
+ * - `reviewHash` — a purpose-built, status-stable hash of every
+ *   review-relevant plan field. Pure execution progress (statuses, the
+ *   current-phase pointer, transient blocked reasons, timestamps) is
+ *   excluded, so normal progress never invalidates a completed review.
+ * - `policyDigest` — canonical digest of the council policy that shaped the
+ *   review (quorum/veto/concerns/maxRounds/freshness). Any policy change
+ *   opens a new generation and invalidates prior evidence.
+ * - `identityDigest` — sha256 over the canonical identity object; this is
+ *   the round-store scope/generation key and the evidence binding.
+ *
+ * `computePlanHash` (ledger integrity) and `computePlanStructureHash`
+ * (plan-critic execution gate) are intentionally NOT reused or modified:
+ * the first is status-sensitive by design, and the second still hashes
+ * progress-like fields (`blocked_reason`, `current_phase`) while dropping
+ * the review-relevant `fr_refs`. See `src/plan/ledger.ts` doc comments.
+ */
+import type { RuntimePlan } from '../config/plan-schema';
+import type { CouncilAgent, CouncilConfig } from './types';
+/** Schema/cutover version of the council review identity itself. */
+export declare const COUNCIL_REVIEW_IDENTITY_VERSION: 2;
+export type CouncilLevel = 'task' | 'phase' | 'final';
+export type CouncilReviewScope = {
+    kind: 'task';
+    taskId: string;
+} | {
+    kind: 'phase';
+    phaseNumber: number;
+} | {
+    kind: 'final';
+    final: true;
+};
+/** Normalized final-council completion policy (issue #2102 contract C). */
+export type FinalCompletionPolicy = {
+    mode: 'all_required';
+} | {
+    mode: 'quorum';
+    minimumMembers: number;
+};
+export interface CouncilReviewIdentity {
+    version: number;
+    level: CouncilLevel;
+    scope: CouncilReviewScope;
+    planId: string | null;
+    planIdentityHash: string | null;
+    reviewHash: string | null;
+    policyDigest: string;
+    identityDigest: string;
+}
+export declare function isIdentityDigest(value: unknown): value is string;
+/**
+ * Resolve a submitted council member name to its canonical role (issue
+ * #2102 contract C). Accepts the exact canonical role (`critic`) and
+ * multi-swarm prefixed names (`local_critic`) via suffix resolution.
+ * Returns null for unknown names — they never count toward quorum.
+ *
+ * Swarm-membership itself cannot be verified for architect-submitted JSON
+ * verdicts (there is no per-agent authentication at the tool boundary), so
+ * the enforceable cross-swarm defense is canonical-role deduplication: two
+ * prefixed names that resolve to the same canonical role (`local_critic` +
+ * `mega_critic`) count as ONE member. Writers, gates, and tests must all
+ * use this shared resolver so the role policy never drifts.
+ */
+export declare function resolveCouncilMemberRole(agentName: string): CouncilAgent | null;
+/**
+ * Status-stable hash of every review-relevant plan field.
+ *
+ * INCLUDED (the council judges these): schema_version, title, swarm,
+ * execution_profile (execution requirements), migration_status (durable plan
+ * property), phase id/name/type/required_agents, task id/phase/size/
+ * description/depends/acceptance/files_touched/evidence_path/fr_refs
+ * (FR/spec references, #1687).
+ *
+ * EXCLUDED (pure execution progress — the issue's explicit list):
+ * phase.status, task.status, current_phase (progress pointer), blocked_reason
+ * (transient), specMtime/specHash (timestamps + spec content, tracked
+ * separately by the ledger's spec_updated path per ledger.ts's established
+ * rationale).
+ */
+export declare function computeCouncilReviewHash(plan: RuntimePlan): string;
+/**
+ * Canonical per-level council policy digest.
+ *
+ * Every field that shapes what the council required at this level is hashed,
+ * so changing the mode, a minimum, the role/quorum knobs, veto/concerns
+ * behavior, max rounds, or the freshness window opens a new generation.
+ * Inert fields (`parallelTimeoutMs`, `escalateOnMaxRounds`) deliberately do
+ * NOT contribute — changing them must not invalidate evidence.
+ */
+export declare function computeCouncilPolicyDigest(level: CouncilLevel, config?: CouncilConfig): string;
+/**
+ * Resolve the final-council completion policy from config.
+ *
+ * Missing/absent config, a missing `finalCompletionPolicy`, or an invalid
+ * quorum declaration all fail closed to the strict legacy `all_required`
+ * requirement (all five canonical roles, zero absentees). Explicit
+ * `quorum` requires a bounded `minimumMembers` of 3..5; only distinct
+ * members of the canonical five-role set ever count toward it.
+ */
+export declare function resolveFinalCompletionPolicy(config?: CouncilConfig): FinalCompletionPolicy;
+/**
+ * Compute the canonical council review identity. `plan` may be null (no plan
+ * on disk): the identity then carries null plan fields, and any consumer
+ * holding a plan will fail closed against it — evidence without plan binding
+ * can never satisfy a gate that has a plan.
+ */
+export declare function computeCouncilReviewIdentity(input: {
+    level: CouncilLevel;
+    scope: CouncilReviewScope;
+    plan: RuntimePlan | null;
+    config?: CouncilConfig;
+}): CouncilReviewIdentity;
+/**
+ * The evidence-entry projection of an identity. Writers embed these fields in
+ * council evidence; gates recompute the identity and compare byte-for-byte.
+ */
+export declare function councilIdentityEvidenceFields(identity: CouncilReviewIdentity): {
+    identity_version: number;
+    review_hash: string | null;
+    policy_digest: string;
+    identity_digest: string;
+};

package/dist/council/council-round-state.d.ts

@@ -1,29 +1,45 @@
 import { randomUUID } from 'node:crypto';
 import { withEvidenceLock } from '../evidence/lock.js';
 import { atomicWriteFile } from '../evidence/task-file.js';
+/**
+ * Council round scope, keyed by the canonical council review identity
+ * (issue #2102 contract B). `identityDigest` binds every round to the exact
+ * review-relevant plan content and council policy it was convened under:
+ * a status-only progress change keeps the identity (and therefore the
+ * accepted round), while any review-relevant plan or policy change opens a
+ * fresh authoritative generation under a new token. Legacy v1 files (whose
+ * tokens predate identity binding) are never read — they remain on disk,
+ * auditable, and are never rewritten as if they carried identity proof.
+ */
 export type CouncilRoundScope = {
     kind: 'task';
     taskId: string;
+    identityDigest: string;
 } | {
     kind: 'phase';
     phaseNumber: number;
+    identityDigest: string;
 } | {
     kind: 'final';
-    generation: string;
+    identityDigest: string;
 };
 export type CouncilRoundTransition = 'stay' | 'advance' | 'close';
 type AuditScope = {
     kind: 'task';
     scopeHash: string;
+    identityDigest: string;
 } | {
     kind: 'phase';
     phaseNumber: number;
+    identityDigest: string;
 } | {
     kind: 'final';
     scopeHash: string;
+    identityDigest: string;
 };
 interface StateSnapshot {
-    version: 1;
+    version: 2;
+    identityDigest: string;
     currentRound: number;
     status: 'open' | 'closed';
     maxRoundsExhausted: boolean;
@@ -31,7 +47,7 @@ interface StateSnapshot {
     lastDigest?: string;
 }
 interface AttemptRecord {
-    version: 1;
+    version: 2;
     event: 'received' | 'finalized' | 'recovered';
     attemptId: string;
     timestamp: string;
@@ -76,6 +92,14 @@ export interface CouncilAttemptInput {
     request: unknown;
     verdictCount: number;
     members: string[];
+    /**
+     * True when the user explicitly configured `council.escalateOnMaxRounds`.
+     * Only this boolean reaches the durable max-rounds exhaustion event —
+     * the configured handler/webhook string itself is never persisted or
+     * logged (URL/query redaction, issue #2102 contract F). No outbound
+     * execution ever happens.
+     */
+    escalationConfigured?: boolean;
     probePendingEvidence?: (attemptId: string, round: number, evidenceRef?: string) => Promise<boolean>;
     evaluate: (authoritativeRound: number) => Promise<CouncilAttemptEvaluation>;
 }

package/dist/council/disagreement-detector.d.ts

@@ -5,9 +5,19 @@
  * responses, returns the set of factual disagreements that should be routed
  * back to disputing members for Round 2 reconciliation.
  *
- * Two-pass detection:
+ * Three-pass detection:
  *   Pass 1 — Explicit linguistic markers ("I disagree with", "unlike", etc.)
- *   Pass 2 — Claim divergence heuristic (mutually exclusive recommendations)
+ *   Pass 2 — Structured claims (issue #2102 contract G): contrary typed
+ *            stances on the same subject, detectable without any marker
+ *            phrase. Claims are optional and bounded; when absent, invalid,
+ *            or malformed this pass contributes nothing and the fallback
+ *            passes below still run.
+ *   Pass 3 — Claim divergence heuristic (mutually exclusive recommendations)
+ *
+ * Marker-based disagreements are always kept: the combined list orders the
+ * explicit-marker pass FIRST, so structured data can never push a marker
+ * detection out of the MAX_DISAGREEMENTS cap, and dedupe merges positions
+ * instead of removing them.
  *
  * NSED design note (arXiv:2601.16863): only the disagreement delta is fed
  * forward to Round 2, not full Round 1 context — mirrors the "semantic forget

package/dist/council/general-council-types.d.ts

@@ -18,6 +18,31 @@ export interface WebSearchResult {
     snippet: string;
     query: string;
 }
+/**
+ * Bounded structured claim on a council question (issue #2102 contract G).
+ * Claims are OPTIONAL: smaller models may omit them entirely and the
+ * disagreement detector falls back to its phrase/heuristic passes. A claim
+ * by itself is never proof of consensus or correctness — claims only make
+ * positions comparable so a phrase-free contrary stance is detectable.
+ */
+export interface GeneralCouncilClaim {
+    /** Bounded subject/topic the claim is about (≤120 chars). */
+    subject: string;
+    /** Bounded statement of the member's position (≤600 chars). */
+    statement: string;
+    /** Typed stance; 'oppose'/'alternative' mark contrary positions. */
+    stance: 'support' | 'oppose' | 'neutral' | 'concern' | 'alternative';
+    /** Self-reported confidence, same validated range as the response. */
+    confidence: number;
+    /**
+     * Optional bounded evidence/source references (≤4 items, each ≤240 chars).
+     * The bound is enforced at the Zod tool boundary (`MemberClaimsSchema` in
+     * src/tools/convene-general-council.ts) and independently re-checked by
+     * `isWellFormedClaim` in the disagreement detector — the TypeScript type
+     * alone cannot express it.
+     */
+    evidence?: string[];
+}
 export interface GeneralCouncilMemberConfig {
     memberId: string;
     model: string;
@@ -35,6 +60,13 @@ export interface GeneralCouncilMemberResponse {
     confidence: number;
     areasOfUncertainty: string[];
     durationMs: number;
+    /**
+     * Optional bounded structured claims (issue #2102 contract G). Absent,
+     * malformed, or oversized claims degrade to the phrase/Jaccard fallback —
+     * they never reject the submission and never suppress explicit
+     * disagreement evidence.
+     */
+    claims?: GeneralCouncilClaim[];
 }
 export interface GeneralCouncilDisagreementPosition {
     memberId: string;