opencode-swarm 7.121.3 → 7.122.0

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

@@ -0,0 +1,98 @@
+/**
+ * Shared receipt validator (issue #1849).
+ *
+ * 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.
+ */
+import { type KnowledgeEvent, type RetrievedEvent } from './knowledge-events.js';
+/** Terminal outcomes the validator accepts. */
+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'>;
+    reason?: string;
+}
+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;
+    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 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.
+     */
+    rejected_items?: Array<{
+        item: ReceiptItem;
+        reason: ReceiptRejectReason;
+    }>;
+} | {
+    ok: false;
+    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;
+export declare const _internals: {
+    findTrace: typeof findTrace;
+    isTerminalReceipt: typeof isTerminalReceipt;
+    VALID_OUTCOMES: ReadonlySet<string>;
+};
+export {};

package/dist/hooks/micro-reflector.d.ts

@@ -80,6 +80,9 @@ export interface MicroReflectorInput {
     tool: unknown;
     args?: unknown;
     sessionID?: unknown;
+    /** (#1849) callID from the SDK tool.execute.after input — used to recover the
+     * snapshot args (the SDK toolAfter input has NO args field). */
+    callID?: unknown;
 }
 export interface MicroReflectorOutput {
     output?: unknown;

package/dist/hooks/pr-auto-subscribe.d.ts

@@ -23,6 +23,9 @@ export interface PrAutoSubscribeHook {
         tool: string;
         sessionID?: string;
         args?: unknown;
+        /** (#1849) SDK tool.execute.after input carries callID (not args); used
+         * to recover the snapshot args via resolveToolAfterContext. */
+        callID?: string;
     }, output: {
         output?: unknown;
         args?: unknown;

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

@@ -0,0 +1,33 @@
+/**
+ * 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
+ * {@link evaluatePromotionPolicy} consumer (previously inert "until #1849
+ * produces real receipts").
+ *
+ * Per-worktree by design: promotion evidence records THIS worktree's observed
+ * applications. It is intentionally NOT a member of `KNOWLEDGE_FAMILY` (the
+ * linked-cohort shared-artifact manifest), matching the precedent set by
+ * `src/turbo/epic/promotion-evidence.ts`. It lives under the project-root
+ * `.swarm/` (via {@link validateSwarmPath}), NOT the link-aware shared store
+ * dir, so it stays per-worktree.
+ */
+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;
+/**
+ * Append validated promotion-evidence records. Fail-open + bounded: a write
+ * error logs and continues (the receipt event itself is the authoritative
+ * record; promotion evidence is a derived consumer). FIFO-trims the log when it
+ * exceeds {@link MAX_PROMOTION_EVIDENCE_ENTRIES}.
+ */
+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.
+ */
+export declare function loadPromotionEvidenceByEntry(directory: string): Promise<Record<string, PromotionEvidenceRecord[]>>;