opencode-swarm 7.140.3 → 7.140.5

package/dist/hooks/issue-trace-state.d.ts

@@ -17,6 +17,8 @@ import type { IssueReference, TraceState } from './issue-trace-reducer';
 declare function _defaultLoadPlanFromLedger(directory: string): Promise<Plan | null>;
 declare function _defaultReproductionReceiptExists(directory: string, issueNumber: number): Promise<boolean>;
 declare function _defaultPublicationReceiptExists(directory: string, issueNumber: number): Promise<boolean>;
+declare function _defaultRecurrenceSweepReceiptExists(directory: string, issueNumber: number): Promise<boolean>;
+declare function _defaultImplementationReviewReceiptExists(directory: string, issueNumber: number): Promise<boolean>;
 export declare const _internals: {
     readFileSync: typeof readFileSync;
     writeFileSync: typeof writeFileSync;
@@ -27,6 +29,8 @@ export declare const _internals: {
     loadPlanFromLedger: typeof _defaultLoadPlanFromLedger;
     reproductionReceiptExists: typeof _defaultReproductionReceiptExists;
     publicationReceiptExists: typeof _defaultPublicationReceiptExists;
+    recurrenceSweepReceiptExists: typeof _defaultRecurrenceSweepReceiptExists;
+    implementationReviewReceiptExists: typeof _defaultImplementationReviewReceiptExists;
 };
 /**
  * Reads `.swarm/issue-reference.json` and returns the parsed object,
@@ -90,4 +94,18 @@ export declare function reproductionReceiptExists(directory: string, issueNumber
  * a new trace.
  */
 export declare function publicationReceiptExists(directory: string, issueNumber: number): Promise<boolean>;
+/**
+ * Returns whether a valid recurrence-sweep receipt exists for the given issue
+ * (issue #2131 residual criterion B). Modeled on issue-tracer Phase 4.2: for a
+ * real defect class it must record search predicates, a typed disposition for
+ * every hit, and a guardrail with proof it catches the original defect; the
+ * "no defect class" fast path requires a one-line justification.
+ */
+export declare function recurrenceSweepReceiptExists(directory: string, issueNumber: number): Promise<boolean>;
+/**
+ * Returns whether a valid independent implementation-review receipt exists for
+ * the given issue (issue #2131 residual criterion B): fresh reviewer AND critic
+ * contexts both recorded APPROVE verdicts for the implementation diff.
+ */
+export declare function implementationReviewReceiptExists(directory: string, issueNumber: number): Promise<boolean>;
 export {};

package/dist/hooks/issue-trace.d.ts

@@ -17,7 +17,7 @@
  */
 import { error as _logErrorImpl } from '../utils/logger.js';
 import { isPlanCriticApproved } from './delegation-gate';
-import { publicationReceiptExists, readIssueReference, readPlanPhaseStatus, readSpecIssueNumber, readTraceState, reproductionReceiptExists, specExists, writeTraceState } from './issue-trace-state';
+import { implementationReviewReceiptExists, publicationReceiptExists, readIssueReference, readPlanPhaseStatus, readSpecIssueNumber, readTraceState, recurrenceSweepReceiptExists, reproductionReceiptExists, specExists, writeTraceState } from './issue-trace-state';
 export declare const _internals: {
     readIssueReference: typeof readIssueReference;
     readTraceState: typeof readTraceState;
@@ -27,6 +27,8 @@ export declare const _internals: {
     specExists: typeof specExists;
     reproductionReceiptExists: typeof reproductionReceiptExists;
     publicationReceiptExists: typeof publicationReceiptExists;
+    recurrenceSweepReceiptExists: typeof recurrenceSweepReceiptExists;
+    implementationReviewReceiptExists: typeof implementationReviewReceiptExists;
     isPlanCriticApproved: typeof isPlanCriticApproved;
     logError: typeof _logErrorImpl;
 };

package/dist/hooks/knowledge-application-gate.d.ts

@@ -12,13 +12,13 @@
  *
  *   2. `tool.execute.before` (FAIL-CLOSED chain at src/index.ts) — when a
  *      high-risk tool fires and the calling agent is the architect,
- *      consults `swarmState.currentCriticalShownIds` and the audit log to
- *      assemble the set of critical directives that have been shown but
+ *      consults the authoritative receipt ledger for critical architect
+ *      directives in the current active phase/task that have been shown but
  *      not acknowledged. In `mode: 'enforce'` it THROWS to block the
  *      action (per the FAIL-CLOSED contract — `output.error` is NOT a
  *      write API at toolBefore time) — UNLESS one of two bounded escape
  *      hatches has fired first (a per-directive denial-count limit, or a
- *      staleness TTL since the directive was shown; see
+ *      per-exact-pair staleness TTL since the directive was shown; see
  *      `incrementGateDenialCount`/`buildGateDenialDirectiveKey` in
  *      `../state.js`), in which case the pending directives are
  *      auto-acknowledged and an audit event is durably written before the
@@ -34,6 +34,7 @@
  * Non-architect agents are never gated.
  */
 import { type KnowledgeApplicationConfig } from './knowledge-application.js';
+import { type ReceiptMembership } from './knowledge-receipt-ledger.js';
 import type { MessageWithParts } from './knowledge-types.js';
 /** Tools that require knowledge-directive acknowledgment before execution. */
 export declare const HIGH_RISK_TOOLS: Set<string>;
@@ -42,6 +43,8 @@ export interface GateInput {
     agent?: unknown;
     sessionID?: unknown;
 }
+declare function selectCurrentArchitectDirectiveMemberships(memberships: ReceiptMembership[]): ReceiptMembership[];
+declare function selectStaleUnmarkedMemberships(memberships: ReceiptMembership[], now: number, stalenessMs: number): ReceiptMembership[];
 /**
  * Pre-tool gate. Throws when the architect attempts a high-risk action with
  * an unacknowledged critical directive in `enforce` mode. Always returns in
@@ -64,5 +67,7 @@ export declare const _internals: {
     knowledgeApplicationTransformScan: typeof knowledgeApplicationTransformScan;
     HIGH_RISK_TOOLS: Set<string>;
     writeWarnEvent: typeof writeWarnEvent;
+    selectCurrentArchitectDirectiveMemberships: typeof selectCurrentArchitectDirectiveMemberships;
+    selectStaleUnmarkedMemberships: typeof selectStaleUnmarkedMemberships;
 };
 export {};

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

@@ -11,14 +11,17 @@ export declare const MAX_LEGACY_APPLICATION_LOG_ENTRIES = 5000;
 /**
  * Parse explicit knowledge-acknowledgment markers from architect/delegate text.
  * Recognised forms (case-insensitive, line-anchored or inline):
- *   KNOWLEDGE_APPLIED: <id>
- *   KNOWLEDGE_IGNORED: <id> reason=<reason>
- *   KNOWLEDGE_CONTRADICTED: <id> reason=<observable conflict>
- *   KNOWLEDGE_VIOLATED: <id> reason=<reason>
- *   KNOWLEDGE_N_A: <id> reason=<reason>   (delegate contract, Change 1)
+ *   KNOWLEDGE_APPLIED: <trace_id>:<entry_id>
+ *   KNOWLEDGE_IGNORED: <trace_id>:<entry_id> reason=<reason>
+ *   KNOWLEDGE_CONTRADICTED: <trace_id>:<entry_id> reason=<observable conflict>
+ *   KNOWLEDGE_VIOLATED: <trace_id>:<entry_id> reason=<reason>
+ *   KNOWLEDGE_N_A: <trace_id>:<entry_id> reason=<reason>
+ * Legacy one-token delegate markers remain parseable, but architect application
+ * reconciliation requires the exact trace token.
  */
 export interface ParsedAcknowledgment {
     id: string;
+    trace_id?: string;
     result: 'applied' | 'ignored' | 'contradicted' | 'violated' | 'n_a';
     reason?: string;
 }

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

@@ -11,6 +11,7 @@
  * Persistence goes through `rewriteKnowledge` (never a raw JSONL write). Fail-open:
  * any error leaves the entry untouched and returns `escalated:false`.
  */
+import { queryHistoricalOutcomes } from './knowledge-receipt-ledger.js';
 import type { DirectivePriority } from './knowledge-types.js';
 export declare const ESCALATION_WINDOW_DAYS = 30;
 export declare const ESCALATION_THRESHOLD = 2;
@@ -25,7 +26,7 @@ export interface EscalationResult {
 }
 /**
  * Evaluate and (if warranted) apply a repeat-violation escalation to a single
- * entry. Call AFTER the triggering `violated` event has been persisted.
+ * entry. Call AFTER the triggering authoritative `violated` terminal commits.
  */
 export declare function maybeEscalateOnViolation(directory: string, entryId: string, now?: Date): Promise<EscalationResult>;
 export interface RecentEscalation {
@@ -58,9 +59,12 @@ export interface ContradictionQuarantineResult {
 /**
  * G3 (#1715): if an entry's `contradicted` count within `windowDays` crosses
  * `threshold`, auto-quarantine it. Mirrors {@link maybeEscalateOnViolation}
- * (counts from the RAW event log via {@link countEntryContradictionsInWindow}
- * — NOT the rollup cache, which is mtime-keyed and can be stale immediately
- * after an append). Idempotent: already-quarantined/archived entries are
- * skipped. Never throws.
+ * Counts exact authoritative receipt terminals, never the diagnostic FIFO or
+ * rollup cache. Idempotent: already-quarantined/archived entries are skipped.
+ * Receipt-ledger uncertainty is conservative and never quarantines.
  */
 export declare function maybeQuarantineOnContradiction(directory: string, entryId: string, threshold: number, windowDays: number, now?: Date): Promise<ContradictionQuarantineResult>;
+/** Dependency seam for authoritative-history tests; restore after each test. */
+export declare const _internals: {
+    queryHistoricalOutcomes: typeof queryHistoricalOutcomes;
+};

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

@@ -1,11 +1,13 @@
 /**
- * Event-sourced knowledge lifecycle for opencode-swarm.
+ * Bounded diagnostic knowledge lifecycle stream for opencode-swarm.
  *
  * `.swarm/knowledge-events.jsonl` records meaningful knowledge interactions
  * (retrieval, receipt, outcome, archival). Recent lines stay in the event log;
  * old lines are folded into `.swarm/knowledge-counter-baseline.json` when the
- * log exceeds the cap. The event log plus baseline are the authoritative
- * history for derived per-entry counters (`retrieval_outcomes.*`).
+ * log exceeds the cap. The event log plus baseline remain the source for
+ * best-effort aggregate metrics (`retrieval_outcomes.*`), but are not receipt,
+ * membership, gate, promotion, escalation, or destructive-action authority.
+ * Correctness state lives in the canonical project-local V2 receipt ledger.
  *
  * Design contracts:
  * - Append-first, bounded retention. New events use OS-level atomic append; trim
@@ -20,6 +22,7 @@
  *   from the process working directory.
  */
 import { resolveHiveEventsPath as resolveHiveEventsPathImpl } from '../knowledge/hive-paths.js';
+import { queryHistoricalOutcomes } from './knowledge-receipt-ledger.js';
 import type { ConfidenceFloorOptions } from './knowledge-store.js';
 import type { KnowledgeApplicationRecord, RetrievalOutcome } from './knowledge-types.js';
 /** Current event-log record schema version. Bump when the on-disk shape changes. */
@@ -372,16 +375,24 @@ export declare function countEntryViolationsInWindow(directory: string, entryId:
  */
 export declare function countEntryContradictionsInWindow(directory: string, entryId: string, windowDays: number, now?: Date): Promise<number>;
 /**
- * Fail-open rollup reader for hot paths. Search and promotion use this instead
- * of stale persisted counters so `knowledge_receipt` feedback affects ranking
- * and safety gates immediately.
+ * Fail-open diagnostic rollup reader. This preserves legacy metrics and
+ * postmortem views, but correctness-affecting consumers must use
+ * {@link readAuthoritativeKnowledgeCounterRollups} instead.
  */
 export declare function readKnowledgeCounterRollups(directory: string): Promise<Map<string, CounterRollup>>;
+/**
+ * Build correctness-affecting retrieval/outcome counters exclusively from the
+ * project-local receipt authority. The bounded knowledge-events FIFO remains a
+ * diagnostics/metrics source and must never influence ranking, curation,
+ * confidence floors, promotion, or generated-skill eligibility.
+ */
+export declare function readAuthoritativeKnowledgeCounterRollups(directory: string): Promise<Map<string, CounterRollup>>;
 /** Merge event-derived rollups over stored outcome counters for scoring only. */
 export declare function effectiveRetrievalOutcomes(stored: RetrievalOutcome | undefined, rollup: CounterRollup | undefined): RetrievalOutcome;
 /**
- * Read receipt events (applied/violated/ignored), aggregate per knowledge entry,
- * and apply bounded confidence deltas via `bumpKnowledgeConfidenceBatch`.
+ * Read authoritative receipt terminals (applied/violated/ignored), aggregate
+ * per knowledge entry, and apply bounded confidence deltas via
+ * `bumpKnowledgeConfidenceBatch`.
  *
  * Complements `applySkillUsageFeedback` (skill-usage-log.ts) which bridges
  * skill compliance → confidence. This function bridges raw knowledge verdict
@@ -407,9 +418,11 @@ export declare const _internals: {
     appendKnowledgeEvent: typeof appendKnowledgeEvent;
     recordKnowledgeEvent: typeof recordKnowledgeEvent;
     readKnowledgeEvents: typeof readKnowledgeEvents;
+    queryHistoricalOutcomes: typeof queryHistoricalOutcomes;
     readCounterBaseline: typeof readCounterBaseline;
     readLegacyApplicationRecords: typeof readLegacyApplicationRecords;
     readKnowledgeCounterRollups: typeof readKnowledgeCounterRollups;
+    readAuthoritativeKnowledgeCounterRollups: typeof readAuthoritativeKnowledgeCounterRollups;
     effectiveRetrievalOutcomes: typeof effectiveRetrievalOutcomes;
     recomputeCounters: typeof recomputeCounters;
     applyKnowledgeVerdictFeedback: typeof applyKnowledgeVerdictFeedback;

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

@@ -5,11 +5,14 @@
  * compaction. Skips for non-architect agents. Appends rejected-pattern warnings
  * to prevent re-learning loops.
  */
+import { ensureCohortIdCached } from './cohort-cache.js';
 import { recordKnowledgeShown } from './knowledge-application.js';
 import { buildEscalationBriefing, readRecentEscalations } from './knowledge-escalator.js';
 import { recordKnowledgeEvent } from './knowledge-events.js';
+import { readLinkPointer } from './knowledge-link.js';
 import type { RankedEntry } from './knowledge-reader.js';
 import { recordLessonsShown } from './knowledge-reader.js';
+import { commitDisplayedMembership, commitEmptyRetrieval, queryLiveMemberships } from './knowledge-receipt-ledger.js';
 import { confirmEntriesPhase } from './knowledge-store.js';
 import type { DirectivePriority, KnowledgeConfig, MessageWithParts } from './knowledge-types.js';
 import { searchKnowledge } from './search-knowledge.js';
@@ -48,6 +51,7 @@ export interface InjectForDelegateParams {
     agent: string;
     expectedTools?: string[];
     taskTitle?: string;
+    taskId?: string;
     sessionId?: string;
     config: KnowledgeConfig;
     /**
@@ -117,6 +121,11 @@ export declare const _internals: {
     buildEscalationBriefing: typeof buildEscalationBriefing;
     recordLessonsShown: typeof recordLessonsShown;
     confirmEntriesPhase: typeof confirmEntriesPhase;
+    commitDisplayedMembership: typeof commitDisplayedMembership;
+    commitEmptyRetrieval: typeof commitEmptyRetrieval;
+    queryLiveMemberships: typeof queryLiveMemberships;
+    ensureCohortIdCached: typeof ensureCohortIdCached;
+    readLinkPointer: typeof readLinkPointer;
 };
 /**
  * Tier-0 test seam (see `.opencode/skills/writing-tests/SKILL.md`). Exposes the

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

@@ -0,0 +1,49 @@
+import * as fs from 'node:fs';
+import { lstat, realpath } from 'node:fs/promises';
+export declare const RECEIPT_SCHEMA_VERSION = 2;
+export declare const RECEIPT_CUTOVER_VERSION = 1;
+export interface ReceiptLedgerPaths {
+    root: string;
+    swarmDir: string;
+    journal: string;
+    snapshot: string;
+    archive: string;
+    quarantine: string;
+    lockTarget: string;
+    legacyEvents: string;
+    legacyBaseline: string;
+    linkPointer: string;
+}
+export type ReceiptStoreErrorCode = 'lock_timeout' | 'store_unavailable' | 'store_corrupt';
+export declare class ReceiptStoreError extends Error {
+    readonly code: ReceiptStoreErrorCode;
+    constructor(code: ReceiptStoreErrorCode, message: string);
+}
+export declare function resolveReceiptLedgerPaths(directory: string): ReceiptLedgerPaths;
+interface MutationParentDependencies {
+    lstat: typeof lstat;
+    realpath: typeof realpath;
+}
+declare function validateMutationParent(filePath: string, dependencies?: MutationParentDependencies): Promise<string>;
+declare function readLinuxProcStat(pid: number, signal: AbortSignal): Promise<string>;
+declare function isProcessAlive(pid: number): Promise<boolean>;
+declare function recoverLockIfSafe(paths: ReceiptLedgerPaths): Promise<void>;
+export declare function withReceiptLedgerLock<T>(directory: string, action: (paths: ReceiptLedgerPaths) => Promise<T>): Promise<T>;
+export declare function receiptRecordHash(value: unknown): string;
+export declare function readUtf8IfPresent(filePath: string, maxBytes?: number): Promise<string | null>;
+export declare function appendFsynced(filePath: string, line: string): Promise<void>;
+export declare function atomicWriteFsynced(targetPath: string, content: string): Promise<void>;
+export declare function fileMtimeMs(filePath: string): Promise<number | null>;
+export declare const _internals: {
+    platform: () => NodeJS.Platform;
+    killProcess: (pid: number) => void;
+    readLinuxProcStat: typeof readLinuxProcStat;
+    procStateReadTimeoutMs: number;
+    isProcessAlive: typeof isProcessAlive;
+    rename: typeof fs.promises.rename;
+    rm: typeof fs.promises.rm;
+    afterRecoveryRename: (_paths: ReceiptLedgerPaths, _claimedPath: string) => Promise<void>;
+    recoverLockIfSafe: typeof recoverLockIfSafe;
+    validateMutationParent: typeof validateMutationParent;
+};
+export {};

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;
+};