opencode-swarm 7.140.3 → 7.140.4

package/dist/hooks/knowledge-receipt-ledger.d.ts

@@ -0,0 +1,305 @@
+import { atomicWriteFsynced, type ReceiptLedgerPaths, type ReceiptStoreErrorCode } from './knowledge-receipt-ledger-storage.js';
+import { type KnowledgeReceiptTransitionObservation } from './knowledge-receipt-observability.js';
+export type ReceiptOutcome = 'applied' | 'ignored' | 'contradicted' | 'violated' | 'n_a';
+export interface ReceiptPredicateCheck {
+    predicate: string;
+    result: 'pass' | 'fail' | 'error';
+    detail: string;
+}
+export interface ReceiptTerminal {
+    outcome: ReceiptOutcome;
+    source: string;
+    reason?: string;
+    predicate_check?: ReceiptPredicateCheck;
+    event_id: string;
+    committed_at: string;
+    authorized_transition?: {
+        actor: 'manual-override' | 'reviewer-remediation' | 'phase-override';
+        reason: string;
+        previous_event_id: string;
+        previous_outcome?: ReceiptOutcome;
+    };
+}
+export interface ReceiptApplicationMarker {
+    outcome: ReceiptOutcome;
+    source: string;
+    reason?: string;
+    event_id: string;
+    committed_at: string;
+}
+export interface ReceiptMembership {
+    trace_id: string;
+    entry_id: string;
+    session_id: string;
+    phase?: string;
+    task_id?: string;
+    agent?: string;
+    critical: boolean;
+    rank?: number;
+    score?: number;
+    committed_at: string;
+    membership_event_id: string;
+    grace_days: number;
+    phase_close_intent_at?: string;
+    phase_closed_at?: string;
+    terminal?: ReceiptTerminal;
+    /** Append-only audited terminal transitions; `terminal` is the current gate state. */
+    terminal_history?: ReceiptTerminal[];
+    application_marker?: ReceiptApplicationMarker;
+    cohort_id?: string;
+    source_link_id?: string;
+    exposure_kind: ReceiptExposureKind;
+    origin: 'v2' | 'legacy';
+}
+export type ReceiptExposureKind = 'architect_directive' | 'delegate_directive' | 'manual_recall' | 'legacy_unknown';
+interface EmptyTrace {
+    trace_id: string;
+    session_id: string;
+    phase?: string;
+    task_id?: string;
+    committed_at: string;
+    empty_event_id: string;
+    grace_days: number;
+    phase_close_intent_at?: string;
+    phase_closed_at?: string;
+    terminal_event_id?: string;
+}
+interface PhaseLifecycle {
+    phase: string;
+    session_id: string;
+    task_id?: string;
+    intent_event_id?: string;
+    intent_at?: string;
+    closed_event_id?: string;
+    closed_at?: string;
+}
+interface ReceiptAuditSummary {
+    original_seq: number;
+    original_hash: string;
+    event_id: string;
+    timestamp: string;
+    kind: ReceiptTransitionKind;
+    trace_id?: string;
+    phase?: string;
+    entry_ids?: string[];
+    reason_codes?: string[];
+}
+export type ReceiptTransitionKind = 'membership_committed' | 'empty_retrieval_committed' | 'terminal_committed' | 'terminal_attempt_rejected' | 'terminal_attempt_idempotent' | 'authorized_transition_committed' | 'application_marker_committed' | 'phase_close_intent' | 'phase_closed' | 'legacy_imported' | 'legacy_unverifiable' | 'cutover_completed' | 'checkpoint';
+interface LedgerState {
+    memberships: Map<string, ReceiptMembership>;
+    traceIds: Set<string>;
+    emptyTraces: Map<string, EmptyTrace>;
+    cutoverCompleted: boolean;
+    legacyUnverifiable: boolean;
+    legacyTraceRegistry: Set<string>;
+    legacyUnverifiableTraceIds: Set<string>;
+    phaseLifecycle: Map<string, PhaseLifecycle>;
+    auditTail: ReceiptAuditSummary[];
+    lastSeq: number;
+    lastHash: string;
+    recordCount: number;
+    observations: KnowledgeReceiptTransitionObservation[];
+}
+export type ReceiptUnavailable = {
+    ok: false;
+    code: ReceiptStoreErrorCode | 'legacy_unverifiable';
+    detail: string;
+    /** Compatibility alias for hook responses that surface typed uncertainty. */
+    uncertainty: string;
+};
+export type ReceiptLedgerResult<T> = ({
+    ok: true;
+} & T) | ReceiptUnavailable;
+declare function writeSnapshot(paths: ReceiptLedgerPaths, state: LedgerState): Promise<void>;
+export interface CommitDisplayedMembershipInput {
+    trace_id: string;
+    session_id: string;
+    phase?: string;
+    task_id?: string;
+    agent?: string;
+    entries: Array<{
+        entry_id: string;
+        critical: boolean;
+        rank?: number;
+        score?: number;
+    }>;
+    grace_days?: number;
+    cohort_id?: string;
+    source_link_id?: string;
+    /** Producer provenance used by application gates; omitted callers fail closed. */
+    exposure_kind?: ReceiptExposureKind;
+}
+export declare function commitDisplayedMembership(directory: string, input: CommitDisplayedMembershipInput): Promise<ReceiptLedgerResult<{
+    event_id: string;
+    memberships: ReceiptMembership[];
+}>>;
+export declare function commitEmptyRetrieval(directory: string, input: Omit<CommitDisplayedMembershipInput, 'entries'>): Promise<ReceiptLedgerResult<{
+    event_id: string;
+    terminal_event_id: string;
+}>>;
+export interface TerminalBatchInput {
+    trace_id: string;
+    session_id: string;
+    phase?: string;
+    task_id?: string;
+    agent?: string;
+    cohort_id?: string;
+    source_link_id?: string;
+    grace_days?: number;
+    items?: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        source?: string;
+        reason?: string;
+        predicate_check?: ReceiptPredicateCheck;
+        event_id?: string;
+    }>;
+    /** Alias used by reviewer/delegate batch producers. */
+    terminals?: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        source?: string;
+        reason?: string;
+        predicate_check?: ReceiptPredicateCheck;
+        event_id?: string;
+    }>;
+    no_relevant_knowledge?: boolean;
+    authorization?: {
+        actor: 'manual-override' | 'reviewer-remediation' | 'phase-override';
+        reason: string;
+        expected_event_id: string;
+        expected_outcome?: ReceiptOutcome;
+    };
+}
+export declare function validateAndCommitTerminalBatch(directory: string, input: TerminalBatchInput): Promise<ReceiptLedgerResult<{
+    accepted: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        event_id: string;
+    }>;
+    committed: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        event_id: string;
+    }>;
+    idempotent: string[];
+    idempotent_events: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        event_id: string;
+    }>;
+    rejected: Array<{
+        entry_id: string;
+        reason: string;
+    }>;
+    closes_no_relevant: boolean;
+    terminal_event_id?: string;
+}>>;
+interface ApplicationMarkerBatchInput {
+    trace_id: string;
+    session_id: string;
+    items?: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        source?: string;
+        reason?: string;
+    }>;
+    markers?: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        source?: string;
+        reason?: string;
+    }>;
+}
+declare function commitApplicationMarkerBatch(directory: string, input: ApplicationMarkerBatchInput): Promise<ReceiptLedgerResult<{
+    committed: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        event_id: string;
+    }>;
+    idempotent: string[];
+    rejected: Array<{
+        entry_id: string;
+        reason: string;
+    }>;
+}>>;
+export interface ApplicationOutcomeBatchInput {
+    trace_id: string;
+    session_id: string;
+    grace_days?: number;
+    items: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        source?: string;
+        reason?: string;
+    }>;
+}
+/**
+ * Atomically commit the architect application marker and its receipt terminal.
+ * Each exact pair is validated before either state projection is staged, so a
+ * terminal conflict can never leave a marker behind. Existing same-outcome
+ * state is preserved and any missing half is repaired in the same journal row.
+ */
+export declare function commitApplicationOutcomeBatch(directory: string, input: ApplicationOutcomeBatchInput): Promise<ReceiptLedgerResult<{
+    committed: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        marker_event_id: string;
+        terminal_event_id: string;
+    }>;
+    idempotent: Array<{
+        entry_id: string;
+        outcome: ReceiptOutcome;
+        marker_event_id: string;
+        terminal_event_id: string;
+    }>;
+    rejected: Array<{
+        entry_id: string;
+        reason: string;
+    }>;
+}>>;
+export declare function queryLiveMemberships(directory: string, filters?: {
+    phase?: string;
+    task_id?: string;
+    session_id?: string;
+    include_terminal?: boolean;
+    include_phase_closed?: boolean;
+    exposure_kind?: ReceiptExposureKind;
+    grace_days?: number;
+}): Promise<ReceiptLedgerResult<{
+    memberships: ReceiptMembership[];
+}>>;
+export declare function queryHistoricalOutcomes(directory: string, entryIds?: string[], graceDays?: number): Promise<ReceiptLedgerResult<{
+    memberships: ReceiptMembership[];
+}>>;
+/**
+ * Compact the authoritative receipt journal under its dedicated lock.
+ * Read-only queries intentionally never rewrite receipt state, so maintenance
+ * callers and focused recovery tests use this explicit mutation boundary.
+ */
+export declare function compactKnowledgeReceiptLedger(directory: string): Promise<ReceiptLedgerResult<{
+    compacted: true;
+}>>;
+export declare const recordPhaseCloseIntent: (directory: string, phase: string, sessionId?: string, taskId?: string) => Promise<ReceiptLedgerResult<{
+    event_id: string;
+}>>;
+export declare const commitPhaseClosed: (directory: string, phase: string, sessionId?: string, taskId?: string) => Promise<ReceiptLedgerResult<{
+    event_id: string;
+}>>;
+export declare function reconcilePhaseClose(directory: string, phase: string, durablePlanClosed: boolean, sessionId?: string, taskId?: string): Promise<ReceiptLedgerResult<{
+    reconciled: boolean;
+}>>;
+export declare function ensureLegacyCutover(directory: string, graceDays?: number): Promise<ReceiptLedgerResult<{
+    completed: true;
+}>>;
+export declare const _internals: {
+    nowMs: () => number;
+    writeSnapshot: typeof writeSnapshot;
+    atomicWriteFsynced: typeof atomicWriteFsynced;
+    /** Test-only migration fixture for pre-atomic marker-only state. */
+    commitApplicationMarkerBatch: typeof commitApplicationMarkerBatch;
+    maxJournalRecords: number;
+    maxArchiveRecords: number;
+    maxArchiveBytes: number;
+};
+export {};

package/dist/hooks/knowledge-receipt-observability.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Best-effort observability projection for authoritative receipt transitions.
+ * The V2 journal remains authoritative; telemetry runs best-effort after commit.
+ */
+import { emit } from '../telemetry.js';
+import type { ReceiptOutcome } from './knowledge-receipt-validator.js';
+export type KnowledgeReceiptObservedTransition = 'membership_committed' | 'empty_retrieval_committed' | 'terminal_committed' | 'terminal_attempt_rejected' | 'terminal_attempt_idempotent' | 'authorized_transition_committed' | 'application_marker_committed' | 'phase_close_intent' | 'phase_closed' | 'legacy_imported' | 'legacy_unverifiable' | 'cutover_completed' | 'checkpoint';
+export type KnowledgeReceiptObservationReasonCode = 'committed' | 'idempotent' | 'trace_not_found' | 'id_not_in_trace' | 'wrong_session' | 'wrong_phase' | 'wrong_task' | 'duplicate_conflicting_terminal' | 'event_id_conflict' | 'invalid_outcome' | 'empty_receipt' | 'lock_timeout' | 'store_unavailable' | 'store_corrupt' | 'legacy_unverifiable' | 'unauthorized_transition';
+export interface KnowledgeReceiptTransitionObservation {
+    transition: KnowledgeReceiptObservedTransition;
+    reasonCode: KnowledgeReceiptObservationReasonCode;
+    schemaVersion: number;
+    knowledgeTraceId?: string;
+    knowledgeEntryId?: string;
+    sessionId?: string;
+    taskId?: string;
+    phase?: string;
+    /** Domain value only; never projected to the generic observability outcome. */
+    receiptOutcome?: ReceiptOutcome;
+    /** Bounded domain code only; arbitrary prose is deliberately rejected. */
+    receiptSource?: string;
+}
+/** Emit bounded diagnostics fail-open after an authoritative transition. */
+export declare function emitKnowledgeReceiptTransition(observation: KnowledgeReceiptTransitionObservation): void;
+/** Dependency seam for focused fail-open tests. */
+export declare const _internals: {
+    emit: typeof emit;
+};

package/dist/hooks/knowledge-receipt-validator.d.ts

@@ -1,29 +1,13 @@
 /**
- * Shared receipt validator (issue #1849).
+ * Shared V2 receipt validator and atomic terminal committer (issue #2031).
  *
- * One validator that enforces the terminal-receipt contract for BOTH the
- * `knowledge_receipt` tool AND the `delegate-ack-collector`. Reads the
- * authoritative event log and rejects forged / expired / conflicting /
- * non-trace receipts while keeping idempotent retries free of double-counting.
- *
- * Authority contract (per issue #1849 §3):
- *  - trace/result delivery proves shown/retrieved only;
- *  - a validated terminal receipt is the durable audit outcome;
- *  - applied counters derive ONLY from validated `applied` receipts;
- *  - ignored/contradicted/no_relevant remain visible but are not application credit.
- *
- * Uniqueness grain: ONE terminal per (trace_id, knowledge_id). A trace surfaces a
- * set of entries; for each entry at most one terminal outcome is accepted.
- * Idempotent retry of the SAME outcome is accepted (not re-emitted, not
- * double-counted); a DIFFERENT outcome for the same (trace_id, knowledge_id)
- * is a conflicting-terminal rejection. The delegate ack path legitimately
- * emits multiple terminals per trace (one per shown directive) — that is fine
- * because each directive has a distinct knowledge_id.
+ * Both the knowledge_receipt tool and delegate/reviewer collectors use this
+ * adapter. Correctness is fail-closed: membership validation, idempotency and
+ * terminal commit occur under the dedicated receipt-ledger lock before any
+ * diagnostic or promotion projection is written.
  */
-import { type KnowledgeEvent, type RetrievedEvent } from './knowledge-events.js';
-/** Terminal outcomes the validator accepts. */
+import type { KnowledgeEvent, RetrievedEvent } from './knowledge-events.js';
 export type ReceiptOutcome = 'applied' | 'ignored' | 'contradicted' | 'violated' | 'n_a' | 'no_relevant';
-/** A single item being filed in a receipt. */
 export interface ReceiptItem {
     id: string;
     outcome: Exclude<ReceiptOutcome, 'no_relevant'>;
@@ -31,31 +15,26 @@ export interface ReceiptItem {
 }
 export interface ReceiptValidationContext {
     directory: string;
-    /** The retrieval trace this receipt accounts for, or `'none'`. */
     trace_id: string;
     session_id: string;
     task_id?: string;
     phase?: string;
     agent: string;
+    cohort_id?: string;
+    source_link_id?: string;
+    grace_days?: number;
     items: ReceiptItem[];
-    /** True when the receipt asserts nothing relevant was surfaced. */
     no_relevant_knowledge: boolean;
 }
-export type ReceiptRejectReason = 'trace_not_found' | 'id_not_in_trace' | 'wrong_session' | 'expired' | 'duplicate_conflicting_terminal' | 'invalid_outcome' | 'empty_receipt';
+export type ReceiptRejectReason = 'trace_not_found' | 'id_not_in_trace' | 'wrong_session' | 'wrong_phase' | 'wrong_task' | 'expired' | 'duplicate_conflicting_terminal' | 'invalid_outcome' | 'empty_receipt' | 'lock_timeout' | 'store_unavailable' | 'store_corrupt' | 'legacy_unverifiable';
 export type ReceiptValidationResult = {
     ok: true;
-    /** Items that should be freshly emitted (excludes idempotent skips). */
     accepted: ReceiptItem[];
-    /** Items already recorded with the same outcome — skip emitting. */
     idempotent_skips: ReceiptItem[];
-    /** The matched retrieval trace, or null for the real-empty (`'none'`) path. */
     trace: RetrievedEvent | null;
-    /** True when this receipt closes the loop with a `no_relevant` terminal. */
     closes_no_relevant: boolean;
-    /**
-     * Per-item rejections when SOME items were accepted but others were not
-     * (id_not_in_trace / conflicting). Present only when non-empty.
-     */
+    authoritative_event_ids: Record<string, string>;
+    no_relevant_event_id?: string;
     rejected_items?: Array<{
         item: ReceiptItem;
         reason: ReceiptRejectReason;
@@ -65,31 +44,15 @@ export type ReceiptValidationResult = {
     rejected: true;
     reason: ReceiptRejectReason;
     detail: string;
-    /** Items rejected by per-item checks (id_not_in_trace / conflicting). */
     rejected_items?: Array<{
         item: ReceiptItem;
         reason: ReceiptRejectReason;
     }>;
 };
-/**
- * Receipt validity window. A receipt must be filed within this many
- * milliseconds of the retrieval trace's timestamp. Generous constant (30 min)
- * covers slow agents. NOTE: this is a compile-time constant, NOT configurable
- * via the config schema — raise an issue if runtime configurability is needed.
- */
-export declare const RECEIPT_VALIDITY_MS: number;
-/** The `trace_id` sentinel meaning "no retrieval occurred". */
 export declare const NO_TRACE_SENTINEL = "none";
-/**
- * Validate a receipt against the authoritative event log. Never throws — any
- * internal error fails open by accepting the items (the agent's work must not
- * be blocked by a validator crash). Rejections are AUDITED by the caller via
- * the returned reason; the validator itself does not write audit events to
- * keep it side-effect-free and testable.
- */
 export declare function validateReceipt(ctx: ReceiptValidationContext): Promise<ReceiptValidationResult>;
 declare function findTrace(events: KnowledgeEvent[], traceId: string): RetrievedEvent | null;
-declare function isTerminalReceipt(e: KnowledgeEvent): boolean;
+declare function isTerminalReceipt(event: KnowledgeEvent): boolean;
 export declare const _internals: {
     findTrace: typeof findTrace;
     isTerminalReceipt: typeof isTerminalReceipt;

package/dist/hooks/knowledge-store.d.ts

@@ -173,7 +173,12 @@ export declare function inferTags(lesson: string): string[];
 export declare function bumpKnowledgeConfidenceBatch(directory: string, deltas: Array<{
     id: string;
     delta: number;
-}>, options?: ConfidenceFloorOptions): Promise<void>;
+    receipt_events?: Array<{
+        event_id: string;
+        timestamp: string;
+        outcome: 'applied' | 'violated' | 'ignored';
+    }>;
+}>, options?: ConfidenceFloorOptions): Promise<number>;
 /** Options for the G2 confidence-floor action in bumpKnowledgeConfidenceBatch. */
 export interface ConfidenceFloorOptions {
     /** Action when a just-bumped entry sits at the confidence floor with a

package/dist/hooks/knowledge-types.d.ts

@@ -262,6 +262,16 @@ export interface KnowledgeEntryBase extends ActionableDirectiveFields {
      * (rewrite/demote/confidence-delta). Prevents compounding under concurrent
      * cohort postmortems that claim the same batch. */
     last_curated_generation?: number;
+    /**
+     * Exact-once checkpoint for receipt-driven confidence feedback. Stored in the
+     * same atomic knowledge-entry rewrite as the confidence delta so a crash
+     * before the external projection cursor is written cannot apply the same V2
+     * terminal twice.
+     */
+    receipt_feedback_cursors?: Record<string, {
+        timestamp: string;
+        event_id: string;
+    }>;
 }
 /**
  * Current knowledge schema marker. v1 entries are still parseable and
@@ -454,6 +464,8 @@ export interface KnowledgeConfig {
     max_encounter_score: number;
     /** Default N-phase TTL for knowledge entries. Default: 10 */
     default_max_phases: number;
+    /** Days to retain closed authoritative receipt state before archival. Default: 7 */
+    receipt_close_grace_days: number;
     /** N-phase TTL for 'todo' category entries. Default: 3 */
     todo_max_phases: number;
     /** Enable age-based sweep of knowledge entries. Default: true */

package/dist/hooks/phase-complete-directive-gate.d.ts

@@ -21,6 +21,7 @@ export interface DirectiveGateResult {
     blocked: boolean;
     unresolved: Array<{
         id: string;
+        trace_id?: string;
         reason: DirectiveBlockReason;
     }>;
     overridden: string[];
@@ -32,6 +33,7 @@ export interface DirectiveGateResult {
  */
 export declare function evaluatePhaseCriticalDirectives(params: {
     directory: string;
+    sessionId?: string;
     phaseLabel?: string;
     acceptViolations?: string[];
 }): Promise<DirectiveGateResult>;
@@ -39,6 +41,6 @@ export declare function evaluatePhaseCriticalDirectives(params: {
  * Record an architect override for accepted critical violations. Each accepted
  * id is logged as an `override` event with the written justification.
  */
-export declare function recordDirectiveOverrides(directory: string, ids: string[], justification: string, sessionId: string | undefined): Promise<void>;
+export declare function recordDirectiveOverrides(directory: string, ids: string[], justification: string, sessionId: string | undefined, phaseLabel?: string): Promise<void>;
 /** Build a structured, human-readable block message for unresolved criticals. */
 export declare function formatDirectiveBlockMessage(unresolved: DirectiveGateResult['unresolved']): string;

package/dist/hooks/phase-directives.d.ts

@@ -6,15 +6,15 @@
  * reviewer must verify) and the phase-complete gate (Task 2.4 — which CRITICAL
  * IDs must reach a terminal outcome before the phase advances).
  *
- * The window is defined by the retrieval event's `phase` label: every
- * `retrieved` event (auto_injection AND delegate_inject) carries the plan phase
- * label, so a single equality filter gives a consistent set across consumers.
+ * The window is defined by each authoritative receipt membership's `phase`
+ * label. Legacy retrieval events are imported by the V2 ledger at cutover, so a
+ * single equality filter gives a consistent set across consumers.
  * Passing an empty/undefined phase collects directives across all phases (used
  * only as a permissive fallback).
  */
 import type { DirectiveToVerify } from '../agents/reviewer-directive-compliance.js';
 import type { KnowledgeEntryBase } from './knowledge-types.js';
-/** Collect the directive IDs surfaced by `retrieved` events in the phase window. */
+/** Collect unique entry IDs from authoritative memberships in the phase window. */
 export declare function collectPhaseDirectiveIds(directory: string, phaseLabel?: string): Promise<string[]>;
 /** Load all knowledge entries (swarm + hive) indexed by id. */
 export declare function readEntriesById(directory: string): Promise<Map<string, KnowledgeEntryBase>>;

package/dist/hooks/pr-workflow-gate.d.ts

@@ -165,6 +165,8 @@ export interface PrFeedbackStageACheckReceipt {
         feedbackItemId: string;
         target: string;
         expectedBehavior: string;
+        /** Typed proof kind (issue #2131 criterion C4); optional for records persisted before it existed. */
+        proofKind?: string;
     }>;
     durationMs: number;
 }
@@ -201,7 +203,7 @@ interface PrFeedbackReadyToPublishRecord {
     remoteRef: string;
     validatedAt: string;
 }
-export type PrWorkflowCompletionStatus = 'completed' | 'ready-to-publish';
+export type PrWorkflowCompletionStatus = 'completed' | 'ready-to-publish' | 'verified-no-change';
 export type PrReviewValidationPhase = 'council' | 'reviewer' | 'critic';
 export type PrReviewArtifactBoundary = 'post_explorer' | 'post_reviewer' | 'post_critic';
 type PrReviewArtifactRecord = {
@@ -340,6 +342,14 @@ export interface PrWorkflowGateState {
     prFeedbackStageA?: PrFeedbackStageARecord;
     prFeedbackGateBatches?: PrFeedbackGateBatchRecord[];
     prFeedbackReadyToPublish?: PrFeedbackReadyToPublishRecord;
+    /**
+     * Issue #2131 criterion C2: count of controlled base-sync/rebind transitions.
+     * Each rebind moves the immutable intake head to a new verified remote PR
+     * head after merge/rebase/conflict repair and invalidates every
+     * ancestry-bound receipt (Stage A, verification, gate batches) so the full
+     * mechanical ladder re-runs on the new ancestry.
+     */
+    prFeedbackRebindCount?: number;
     prFeedbackScopes?: PrFeedbackScopeDeclarationRecord[];
 }
 export declare function activatePrWorkflow(directory: string, sessionID: string, mode: PrWorkflowMode, options?: {
@@ -407,6 +417,29 @@ export declare function abortPrWorkflow(directory: string, sessionID: string, op
 }>;
 /** Bind an active PR workflow to one immutable PR head. */
 export declare function bindPrWorkflowHead(directory: string, sessionID: string, prHeadSha: string): Promise<PrWorkflowGateState>;
+/**
+ * Controlled base-sync/rebind transition for PR_FEEDBACK (issue #2131
+ * criterion C2). After a merge/rebase used to resolve base drift or conflicts,
+ * the local history is no longer a direct child of the original intake head and
+ * the ordinary publication path can never be satisfied. Instead of an ad-hoc
+ * abort, this transition moves the immutable intake head to a NEW verified
+ * remote PR head and invalidates every ancestry-bound receipt (Stage A,
+ * verification batches, ordered gates), forcing the full mechanical ladder to
+ * re-run against the new ancestry.
+ *
+ * Fail-closed semantics:
+ *   1. Only an active PR_FEEDBACK gate bound to a head may rebind.
+ *   2. Refuses while publication is armed — an armed gate must complete (the
+ *      immutable-commit binding must not be dropped silently).
+ *   3. Refuses while PR workflow lanes are in flight.
+ *   4. The new head must differ from the current intake head (a no-op rebind
+ *      would silently launder receipts).
+ *   5. The current checkout must equal the new head, and the PR-feedback
+ *      tracking-checkout discipline is re-asserted for it.
+ *   6. The immutable feedback inventory is preserved (item ownership
+ *      continuity); only ancestry-bound receipts are invalidated.
+ */
+export declare function rebindPrFeedbackHead(directory: string, sessionID: string, prHeadSha: string): Promise<PrWorkflowGateState>;
 /** Bind an active PR_REVIEW workflow to one immutable merge-base scope. */
 export declare function bindPrReviewBase(directory: string, sessionID: string, options: {
     prHeadSha: string;

package/dist/hooks/promotion-evidence-store.d.ts

@@ -1,9 +1,10 @@
 /**
  * Promotion-evidence store (issue #1849 §B2).
  *
- * Append-only, FIFO-bounded JSONL store for {@link PromotionEvidenceRecord}s
- * produced when a validated terminal receipt (applied/violated/contradicted) is
- * filed. This is the wiring that finally feeds #1847's
+ * Append-only, FIFO-bounded, rebuildable projection of
+ * {@link PromotionEvidenceRecord}s produced when an authoritative V2 terminal
+ * receipt (applied/violated/contradicted) is filed. V2 receipt history remains
+ * the authority if this projection write fails. This is the wiring that feeds #1847's
  * {@link evaluatePromotionPolicy} consumer (previously inert "until #1849
  * produces real receipts").
  *
@@ -14,6 +15,7 @@
  * `.swarm/` (via {@link validateSwarmPath}), NOT the link-aware shared store
  * dir, so it stays per-worktree.
  */
+import { queryHistoricalOutcomes } from './knowledge-receipt-ledger.js';
 import type { PromotionEvidenceRecord } from './knowledge-types.js';
 /** Resolve the promotion-evidence log path under the project-root `.swarm/`. */
 export declare function resolvePromotionEvidencePath(directory: string): string;
@@ -25,9 +27,13 @@ export declare function resolvePromotionEvidencePath(directory: string): string;
  */
 export declare function appendPromotionEvidence(directory: string, records: PromotionEvidenceRecord[]): Promise<void>;
 /**
- * Load all promotion-evidence records, grouped by entry_id. This is the loader
- * that replaces the inert stub at `hive-promoter.ts:loadPromotionEvidence`.
- * Returns an empty object when the file is absent (no evidence yet — the
- * conservative default). Never throws.
+ * Load authoritative receipt terminals as promotion evidence, grouped by
+ * entry_id. The FIFO file above remains a derived projection and is never read.
+ * Ledger uncertainty or missing truthful cohort lineage conservatively returns
+ * no evidence. Never throws.
  */
-export declare function loadPromotionEvidenceByEntry(directory: string): Promise<Record<string, PromotionEvidenceRecord[]>>;
+export declare function loadPromotionEvidenceByEntry(directory: string, canonicalCohortId?: string): Promise<Record<string, PromotionEvidenceRecord[]>>;
+/** Dependency seam for authoritative-reader failure and mapping tests. */
+export declare const _internals: {
+    queryHistoricalOutcomes: typeof queryHistoricalOutcomes;
+};