opencode-swarm 7.117.0 → 7.118.0

package/dist/hooks/hive-policy.d.ts

@@ -0,0 +1,81 @@
+/**
+ * One promotion policy evaluator used by automatic promotion AND the manual
+ * `/swarm promote` command (issue #1847 §4).
+ *
+ * Previously, automatic promotion went through `isHiveEligible` (3 routes:
+ * hive_eligible+3 phases / hive-fast-track tag / age) while manual promotion
+ * (`promoteToHive` / `promoteFromSwarm`) bypassed policy entirely — an exact
+ * entry id was effectively authorization to skip the gate, with no durable
+ * override record. This module is the single policy function both paths share.
+ *
+ * Manual promotion that fails the policy MUST either be blocked, or proceed
+ * only with an explicit `--force` override that records a durable, audited
+ * override (actor, reason, source revision, failed gates). An exact entry id
+ * alone is NEVER authorization to bypass policy.
+ *
+ * Conservative application evidence (#1847 §2, AC5/AC6): the
+ * `validated_terminal_applications` gate counts ONLY validated terminal receipts
+ * tied to a real retrieval trace + result membership. Legacy records carry no
+ * evidence and receive NO synthetic credit. Until #1849 produces real receipts,
+ * the configured thresholds default to 0, so the gate is satisfied by absence
+ * (it neither credits nor blocks) and current behavior is preserved. Operators
+ * raise the thresholds to activate application-evidence gating.
+ *
+ * This module performs NO I/O and holds NO module-level mutable state
+ * (invariant 8). It is NOT imported on the plugin-init path (invariant 1).
+ */
+import type { KnowledgeConfig, PromotionEvidenceRecord, SwarmKnowledgeEntry } from './knowledge-types.js';
+/** A single named policy gate and whether it passed. */
+export interface PromotionPolicyGate {
+    name: string;
+    passed: boolean;
+    detail: string;
+}
+export interface PromotionPolicyInput {
+    entry: SwarmKnowledgeEntry;
+    config: KnowledgeConfig;
+    /**
+     * Validated terminal-application evidence for this entry's lesson
+     * (near-duplicate-clustered). Empty for legacy/no-evidence records. The
+     * promoter loads this OUTSIDE the hive transaction and passes it in.
+     */
+    evidence: PromotionEvidenceRecord[];
+}
+export interface PromotionPolicyDecision {
+    eligible: boolean;
+    /** Every gate and whether it passed — surfaced in diagnostics + override audit. */
+    gates: PromotionPolicyGate[];
+    /** Human-readable summary of the deciding gate. */
+    reason: string;
+}
+/**
+ * Evaluate the one promotion policy. Used by auto promotion and manual promote.
+ * Returns the full gates list so diagnostics can explain each failed condition
+ * (AC: "Promotion diagnostics explain eligibility failures and lineage").
+ */
+export declare function evaluatePromotionPolicy(input: PromotionPolicyInput): PromotionPolicyDecision;
+/**
+ * The three historical eligibility routes, preserved verbatim from the
+ * pre-#1847 `isHiveEligible`. Exposed so `isHiveEligible` can delegate to it
+ * (M1 fix — keeps the public export + its test consumers working) and so the
+ * policy gate above can report which route satisfied it.
+ */
+export declare function describeEligibilityRoute(entry: SwarmKnowledgeEntry, autoPromoteDays: number): {
+    passed: boolean;
+    detail: string;
+};
+/** Names of override-audit fields the promoter fills when a manual --force fires. */
+export interface OverrideAuditDetail {
+    actor: 'manual-override';
+    reason: string;
+    failedGates: PromotionPolicyGate[];
+    entryId: string;
+    lesson: string;
+}
+/**
+ * Build the failed-gates summary for a manual override, given a decision that
+ * was NOT eligible. Used by the promoter to populate `lineage.override_failed_gates`.
+ */
+export declare function failedGateNames(decision: PromotionPolicyDecision): string[];
+/** Count distinct canonical cohorts among promotion evidence (for diagnostics). */
+export declare function countDistinctEvidenceCohorts(evidence: PromotionEvidenceRecord[]): number;

package/dist/hooks/hive-promoter.d.ts

@@ -1,59 +1,178 @@
-/** Hive promoter hook for opencode-swarm v6.17 two-tier knowledge system. */
+/**
+ * Hive promoter for opencode-swarm v6.17 two-tier knowledge system.
+ *
+ * #1847 (transactional hive promotion): every hive write is routed through ONE
+ * global cross-process transaction (`transactHiveStore` in `./hive-transaction`).
+ * The transaction holds the hive directory lock across read → normalize →
+ * eligibility → canonical-cohort counting → dedup/merge → append/update →
+ * source confirmation → cap → staged audit → atomic persist. No caller reads
+ * the hive, makes a promotion decision, and later calls a separate unlocked
+ * write API.
+ *
+ * Canonical project identity (#1846): cross-project confirmations key on the
+ * canonical `cohort_id` from `resolveCohortId`, not the worktree `project_name`.
+ * Sibling worktrees and remote aliases of one repository count as one project.
+ *
+ * Lineage (#1847 §3): promoted entries retain source entry id, source cohort,
+ * promotion event id, and actor. Manual promotion that fails policy proceeds
+ * only with an explicit `--force` override that records a durable audit entry;
+ * an exact entry id alone is never authorization to bypass policy.
+ *
+ * This module is NOT imported on the plugin-init path (invariant 1): promotion
+ * runs only on the lazy `/swarm promote`, close, curate, and postmortem paths.
+ */
+import { resolveCohortId } from '../knowledge/cohort-identity.js';
 import { appendCuratorRecommendation, readCuratorSummary } from './curator.js';
-import type { KnowledgeConfig, SwarmKnowledgeEntry } from './knowledge-types.js';
-/** Hive promotion summary for curator state */
+import { transactHiveStore } from './hive-transaction.js';
+import type { KnowledgeConfig, ProjectConfirmationRecord, PromotionEvidenceRecord, SwarmKnowledgeEntry } from './knowledge-types.js';
+import { validateLesson } from './knowledge-validator.js';
+/** Hive promotion summary for curator state. */
 export interface HivePromotionSummary {
     timestamp: string;
     new_promotions: number;
     encounters_incremented: number;
     advancements: number;
     total_hive_entries: number;
+    /** #1847: per-entry policy diagnostics for operator visibility. */
+    diagnostics?: string[];
 }
 /**
- * Check whether a swarm knowledge entry is eligible for hive promotion.
- * Three routes to eligibility:
- *   Route 1: hive_eligible flag + 3+ distinct phases
- *   Route 2: 'hive-fast-track' tag
- *   Route 3: age exceeds auto_promote_days threshold
- *
- * @param entry - The swarm knowledge entry to check
- * @param autoPromoteDays - Number of days before age-based promotion kicks in
- * @returns true if the entry is eligible for hive promotion
+ * Check whether a swarm entry is eligible for hive promotion via the historical
+ * 3 routes. Kept as a thin wrapper delegating to the canonical policy route
+ * description (M1 fix, #1847) so existing test consumers
+ * (`hive-promoter-inactive.test.ts`, `close.test.ts` mock) keep working.
+ *
+ * This is ONE of the gates inside {@link evaluatePromotionPolicy}; it is not
+ * the whole policy. New callers should use `evaluatePromotionPolicy`.
  */
 export declare function isHiveEligible(entry: SwarmKnowledgeEntry, autoPromoteDays: number): boolean;
 /**
- * Main promotion logic: checks swarm entries and promotes eligible ones to hive.
- * Also updates existing hive entries with new project confirmations.
- * Returns a summary of the promotion activity for curator state.
+ * Count distinct projects/cohort identities in a hive entry's confirmed_by.
  *
- * @note The 'hive-fast-track' tag is treated as privileged — it bypasses the
- *   3-phase confirmation requirement. It should only be set by authorized tooling
- *   (inferTags() never produces it automatically).
+ * #1847: dedup by canonical `cohort_id` (sibling worktrees + remote aliases of
+ * one repo count as one project). Legacy records written before #1847 lack
+ * `cohort_id`; for those, fall back to `project_name` — but two records sharing
+ * a `cohort_id` are NEVER counted as distinct. This means AC3 ("sibling
+ * worktrees count as one project") is enforced for confirmations written from
+ * this PR forward; legacy confirmations remain `project_name`-keyed and are NOT
+ * retroactively re-counted (consistent with the no-broad-rewrite non-goal).
  */
-export declare function checkHivePromotions(swarmEntries: SwarmKnowledgeEntry[], config: KnowledgeConfig): Promise<HivePromotionSummary>;
+export declare function countDistinctProjects(confirmedBy: ProjectConfirmationRecord[]): number;
+/**
+ * Main promotion logic: checks swarm entries and promotes eligible ones to hive
+ * inside ONE cross-process transaction. Also updates existing hive entries with
+ * new canonical-cohort confirmations. Returns a summary for curator state.
+ *
+ * `directory` is required (#1847) to resolve the canonical cohort identity
+ * (#1846) for cross-project distinctness.
+ *
+ * @note The 'hive-fast-track' tag is privileged — it bypasses the 3-phase
+ *   confirmation requirement inside the eligibility_route gate. It should only
+ *   be set by authorized tooling (inferTags() never produces it automatically).
+ */
+export declare function checkHivePromotions(swarmEntries: SwarmKnowledgeEntry[], config: KnowledgeConfig, directory: string): Promise<HivePromotionSummary>;
 export declare const _internals: {
     readSwarmEntries: (directory: string) => Promise<SwarmKnowledgeEntry[]>;
     checkHivePromotions: typeof checkHivePromotions;
     readCuratorSummary: typeof readCuratorSummary;
     appendCuratorRecommendation: typeof appendCuratorRecommendation;
+    resolveCohortId: typeof resolveCohortId;
+    transactHiveStore: typeof transactHiveStore;
+    validateLesson: typeof validateLesson;
+    /** Loads validated terminal-application evidence per swarm entry id. Empty
+     *  until #1849 produces real receipts (conservative: no synthetic credit). */
+    loadPromotionEvidence: (_swarmEntries: SwarmKnowledgeEntry[]) => Promise<Record<string, PromotionEvidenceRecord[]>>;
+    /** Loads the default KnowledgeConfig (schema defaults) for manual promotion
+     *  paths when the command did not load one. */
+    loadDefaultKnowledgeConfig: () => {
+        enabled: boolean;
+        swarm_max_entries: number;
+        hive_max_entries: number;
+        auto_promote_days: number;
+        max_inject_count: number;
+        delegate_max_inject_count: number;
+        inject_char_budget: number;
+        max_lesson_display_chars: number;
+        dedup_threshold: number;
+        scope_filter: string[];
+        hive_enabled: boolean;
+        rejected_max_entries: number;
+        validation_enabled: boolean;
+        evergreen_confidence: number;
+        evergreen_utility: number;
+        low_utility_threshold: number;
+        min_retrievals_for_utility: number;
+        schema_version: number;
+        directive_min_confidence: number;
+        same_project_weight: number;
+        cross_project_weight: number;
+        min_encounter_score: number;
+        initial_encounter_score: number;
+        encounter_increment: number;
+        max_encounter_score: number;
+        default_max_phases: number;
+        todo_max_phases: number;
+        sweep_enabled: boolean;
+        confidence_floor_action: "none" | "demote" | "quarantine";
+        confidence_floor_min_outcomes: number;
+        confidence_floor_signal_threshold: number;
+        contradiction_threshold_action: "quarantine" | "tag_only";
+        contradiction_quarantine_threshold: number;
+        contradiction_quarantine_window_days: number;
+        promoted_demotion_min_negative_phases: number;
+        promoted_demotion_signal_threshold: number;
+        promotion_min_terminal_applications: number;
+        promotion_min_distinct_cohorts: number;
+        realtime_learning_nudge: {
+            enabled: boolean;
+            first_after_tool_calls: number;
+            repeat_after_tool_calls: number;
+        };
+        enrichment: {
+            max_calls_per_day: number;
+            quota_window: "utc" | "local";
+            batch_size?: number | undefined;
+        };
+        context_budget_threshold?: number | undefined;
+        retrieval?: {
+            mmr_lambda: number;
+            cold_start_bonus: number;
+            cold_start_max_age_phases: number;
+            synonym_min_cooccurrence: number;
+            synonym_map_max_pairs: number;
+        } | undefined;
+    };
 };
 /**
  * Create a hook that promotes swarm entries to the hive.
  * The hook fires unconditionally - the caller decides when to invoke it.
  */
 export declare function createHivePromoterHook(directory: string, config: KnowledgeConfig): (input: unknown, output: unknown) => Promise<void>;
+/** Options for manual promotion (override semantics, #1847 §4). */
+export interface ManualPromotionOptions {
+    force?: boolean;
+    reason?: string;
+}
 /**
  * Promote a lesson directly to the hive (manual promotion).
- * @param directory - Project directory
- * @param lesson - The lesson text to promote
- * @param category - Optional category (defaults to 'process')
- * @returns Confirmation message
+ *
+ * Runs the one policy evaluator. On a policy FAIL:
+ *   - without `force` → returns a diagnostic string listing the failed gates
+ *     (does NOT promote);
+ *   - with `force` + `reason` → promotes and writes a durable override audit
+ *     record (actor='manual-override', failed gates recorded) inside the
+ *     transaction.
+ * On a policy PASS → promotes with actor='manual'.
+ *
+ * An exact entry id / direct text alone is NEVER authorization to bypass policy.
  */
-export declare function promoteToHive(directory: string, lesson: string, category?: string): Promise<string>;
+export declare function promoteToHive(directory: string, lesson: string, category?: string, options?: ManualPromotionOptions, config?: KnowledgeConfig): Promise<string>;
 /**
  * Promote a lesson from swarm knowledge to hive.
- * @param directory - Project directory
- * @param lessonId - The ID of the lesson to promote from swarm
- * @returns Confirmation message
+ *
+ * Snapshots the swarm read OUTSIDE the hive transaction (the swarm store is
+ * read-only here — no two-phase locking needed). Then runs the one policy
+ * evaluator + override semantics inside the hive transaction.
  */
-export declare function promoteFromSwarm(directory: string, lessonId: string): Promise<string>;
+export declare function promoteFromSwarm(directory: string, lessonId: string, options?: ManualPromotionOptions, config?: KnowledgeConfig): Promise<string>;
+export { resolveHiveKnowledgePath } from './knowledge-store.js';

package/dist/hooks/hive-transaction.d.ts

@@ -0,0 +1,113 @@
+/**
+ * One global, cross-process transaction primitive for hive storage (issue #1847 §1).
+ *
+ * Problem: hive promotion previously performed read → N× append → batch rewrite
+ * → cap enforcement as FOUR separate directory-lock acquisitions, with unlocked
+ * read/validate/dedup windows between them. Because the hive store
+ * (`shared-learnings.jsonl`) is a shared, cross-project, cross-process file,
+ * two opencode-swarm sessions could each read the same snapshot and one's
+ * rewrite silently dropped the other's entries (TOCTOU lost update — #1604).
+ *
+ * This module routes every hive writer through ONE critical section that spans,
+ * under a single directory lock:
+ *   1. read + mixed-schema normalize;
+ *   2. the caller's mutate (eligibility, canonical project counting, dedup,
+ *      merge decision, append/update, source confirmation);
+ *   3. validate-before-commit;
+ *   4. priority-aware cap enforcement (in the same closure, not a separate call);
+ *   5. staged audit/reject appends (raw, under the held lock — never via
+ *      `appendHiveKnowledgeEvent`, which would re-enter the directory lock and
+ *      deadlock — see the curator precedent at `curator.ts:1966-1969`);
+ *   6. atomic persistence (temp + rename).
+ *
+ * Lock contract (AGENTS.md invariants 3, 8): `stale: 5000` to MATCH every other
+ * hive writer (`appendKnowledge`, `rewriteKnowledge`, `transactKnowledge`,
+ * `knowledge-application.ts`, `knowledge-escalator.ts`). proper-lockfile's stale
+ * mechanism is preemptive — a process that cannot acquire the lock and sees its
+ * mtime older than its OWN stale threshold force-breaks it. Using a longer stale
+ * here would let a concurrent 5s writer break this transaction mid-flight and
+ * tear the file, which is exactly the bug this PR fixes. The held closure is
+ * kept fast (in-memory mutate + one atomic write + raw appends) so 5s is never
+ * exceeded; all heavy work (git cohort resolution, evidence rollup, near-
+ * duplicate precompute) runs OUTSIDE the lock and is passed in via HiveTxContext.
+ *
+ * This module holds NO module-level mutable state (invariant 8) and is NOT
+ * imported on the plugin-init path (invariant 1).
+ */
+import * as path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { atomicWriteFile } from '../evidence/task-file.js';
+import { resolveHiveDataDir, resolveHiveEventsPath, resolveHiveKnowledgePath, resolveHiveRejectedPath } from '../knowledge/hive-paths.js';
+import { readKnowledge, selectKnowledgeCapSurvivors } from './knowledge-store.js';
+import type { HiveKnowledgeEntry, RejectedLesson } from './knowledge-types.js';
+/**
+ * Context handed to a hive mutation closure. All expensive pre-work (cohort
+ * resolution, evidence loading, near-duplicate indexing) is performed by the
+ * caller OUTSIDE the lock and injected here so the held closure stays fast.
+ */
+export interface HiveTxContext {
+    /** Current hive entries (read + normalized under the lock). */
+    entries: HiveKnowledgeEntry[];
+}
+/** A pre-serialized knowledge-event line to append to the hive audit log. */
+export interface HiveAuditEntry {
+    line: string;
+}
+/** The result a mutation closure returns. */
+export type HiveMutationOutcome<T> = {
+    kind: 'commit';
+    entries: HiveKnowledgeEntry[];
+    /** Hive cap to enforce inside the same closure (omit for no cap). */
+    maxEntries?: number;
+    /** Rejected lessons to append to the hive rejected log under the lock. */
+    rejects?: RejectedLesson[];
+    /** Audit lines to append to the hive events log under the lock. */
+    audit?: HiveAuditEntry[];
+    /** Caller return value surfaced back through HiveTransactionResult. */
+    return: T;
+} | {
+    kind: 'noop';
+    return: T;
+};
+export interface HiveTransactionResult<T> {
+    /** True iff the hive file was rewritten within the transaction. */
+    committed: boolean;
+    /**
+     * The caller's return value. Present when `committed` is true OR the mutate
+     * closure returned a `noop` outcome. Undefined on lock-acquire / mkdir /
+     * validation-before-commit failure (F-004/PRR-1): callers MUST check
+     * `committed` (or `return !== undefined`) before dereferencing it.
+     */
+    return: T | undefined;
+    /** Human-readable diagnostics (lock timeout, validation failure, etc.). */
+    diagnostics: string[];
+}
+/**
+ * Run `mutate` against the hive store inside one cross-process transaction.
+ *
+ * On lock-acquire failure or validation failure the prior hive file is left
+ * intact (the atomic write is not performed) and `committed` is false; the
+ * function never hangs. `mutate` receives the current (normalized) entries and
+ * returns either a `commit` (new entries + optional cap/rejects/audit) or a
+ * `noop`.
+ */
+export declare function transactHiveStore<T>(mutate: (ctx: HiveTxContext) => Promise<HiveMutationOutcome<T>> | HiveMutationOutcome<T>): Promise<HiveTransactionResult<T>>;
+/** Path to the hive events log (re-exported for callers building audit lines). */
+export { resolveHiveEventsPath };
+export declare const HIVE_TXN_LOCK_STALE_MS = 5000;
+/**
+ * Test-only DI seam (AGENTS.md invariant 7). Tests inject a fake lockfile /
+ * readers / writers rather than `mock.module`-ing the consumers, which leaks
+ * across test files in Bun's shared runner.
+ */
+export declare const _internals: {
+    lockfile: typeof lockfile;
+    readKnowledge: typeof readKnowledge;
+    atomicWriteFile: typeof atomicWriteFile;
+    selectKnowledgeCapSurvivors: typeof selectKnowledgeCapSurvivors;
+    resolveHiveDataDir: typeof resolveHiveDataDir;
+    resolveHiveKnowledgePath: typeof resolveHiveKnowledgePath;
+    resolveHiveRejectedPath: typeof resolveHiveRejectedPath;
+    resolveHiveEventsPath: typeof resolveHiveEventsPath;
+    path: typeof path;
+};

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

@@ -19,6 +19,7 @@
  *   `directory` argument injected by `createSwarmTool` / hook constructors — never
  *   from the process working directory.
  */
+import { resolveHiveEventsPath as resolveHiveEventsPathImpl } from '../knowledge/hive-paths.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. */
@@ -182,7 +183,7 @@ export declare const RECEIPT_EVENT_TYPES: ReadonlySet<string>;
 export declare function resolveKnowledgeEventsPath(directory: string): string;
 /** Returns the knowledge-counter-baseline.json path (link-aware). */
 export declare function resolveKnowledgeCounterBaselinePath(directory: string): string;
-export declare function resolveHiveEventsPath(): string;
+export declare const resolveHiveEventsPath: typeof resolveHiveEventsPathImpl;
 /** Returns the knowledge-application.jsonl path for legacy v2 audit records (link-aware). */
 export declare function resolveLegacyApplicationLogPath(directory: string): string;
 /** Generate a fresh trace id. One per retrieval; receipts reference it. */

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

@@ -1,12 +1,14 @@
 /** Core storage layer for the opencode-swarm v6.17 two-tier knowledge system. */
+import { resolveHiveDataDir, resolveHiveEventsPath as resolveHiveEventsPathImpl, resolveHiveKnowledgePath as resolveHiveKnowledgePathImpl, resolveHiveRejectedPath as resolveHiveRejectedPathImpl } from '../knowledge/hive-paths.js';
 import type { KnowledgeEntryBase, RejectedLesson, RetrievalOutcome } from './knowledge-types.js';
 export declare function getPlatformConfigDir(): string;
 export declare function resolveSwarmKnowledgePath(directory: string): string;
 export declare function resolveSwarmRejectedPath(directory: string): string;
 export declare function resolveSwarmRetractionsPath(directory: string): string;
-export declare function resolveHiveKnowledgePath(): string;
-export declare function resolveHiveRejectedPath(): string;
-export declare function resolveHiveEventsPath(): string;
+export declare const resolveHiveKnowledgePath: typeof resolveHiveKnowledgePathImpl;
+export declare const resolveHiveRejectedPath: typeof resolveHiveRejectedPathImpl;
+export declare const resolveHiveEventsPath: typeof resolveHiveEventsPathImpl;
+export { resolveHiveDataDir };
 declare function parseKnowledgeContent<T>(content: string, max: number): T[];
 export declare function readKnowledge<T>(filePath: string, maxEntries?: number): Promise<T[]>;
 export declare function normalizeEntry<T>(raw: T): T;
@@ -29,7 +31,7 @@ export declare function transactKnowledge<T>(filePath: string, mutate: (entries:
 export declare function getArchivedKnowledgeIds(directory: string): Promise<Set<string>>;
 export declare function appendKnowledgeWithCapEnforcement<T>(filePath: string, entry: T, maxEntries: number): Promise<boolean>;
 export declare function enforceKnowledgeCap<T>(filePath: string, maxEntries: number): Promise<void>;
-declare function selectKnowledgeCapSurvivors<T>(entries: T[], maxEntries: number): T[];
+export declare function selectKnowledgeCapSurvivors<T>(entries: T[], maxEntries: number): T[];
 export interface SweepResult {
     scanned: number;
     aged: number;
@@ -136,4 +138,3 @@ export declare const _internals: {
     bumpKnowledgeConfidenceBatch: typeof bumpKnowledgeConfidenceBatch;
     getArchivedKnowledgeIds: typeof getArchivedKnowledgeIds;
 };
-export {};

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

@@ -7,6 +7,15 @@ export interface PhaseConfirmationRecord {
 }
 export interface ProjectConfirmationRecord {
     project_name: string;
+    /**
+     * Canonical cohort id (issue #1847) — the identity used for cross-project
+     * distinctness, from `resolveCohortId` (#1846). Sibling worktrees and remote
+     * aliases of one repository share one `cohort_id`, so they count as a single
+     * project. Absent on legacy records written before #1847; such records are
+     * counted by `project_name` as a degraded fallback and are NEVER synthetically
+     * credited with a cohort id.
+     */
+    cohort_id?: string;
     confirmed_at: string;
     phase_number?: number;
 }
@@ -205,6 +214,69 @@ export interface SwarmKnowledgeEntry extends KnowledgeEntryBase {
     confirmed_by: PhaseConfirmationRecord[];
     project_name: string;
 }
+/**
+ * A single validated terminal application of a knowledge entry, usable as
+ * promotion evidence (issue #1847). Only receipts tied to a real retrieval
+ * trace AND a terminal outcome (`applied` / `violated` / `contradicted`) that
+ * is a member of that trace's result set qualify. Shown / retrieved / injected
+ * / acknowledged-only states do NOT qualify — they are display/attention
+ * signals, not application evidence.
+ *
+ * Production of real host traces is owned by #1849; this PR (#1847) owns the
+ * schema and the conservative promotion-side consumer. Legacy records carry no
+ * `PromotionEvidenceRecord`s and receive NO synthetic credit.
+ */
+export interface PromotionEvidenceRecord {
+    /** Canonical repository/cohort identity (from `resolveCohortId`, #1846). */
+    cohort_id: string;
+    /** Source cohort / link id when known (from the v2 LinkPointer). */
+    source_link_id?: string;
+    /** The hive/swarm entry id this evidence contributes to. */
+    entry_id: string;
+    /** Retrieval trace id that surfaced the entry (ties to a RetrievedEvent). */
+    retrieval_trace_id: string;
+    /** Terminal receipt outcome. */
+    receipt_outcome: 'applied' | 'violated' | 'contradicted';
+    /** Id of the ReceiptEvent this evidence was derived from. */
+    receipt_event_id: string;
+    phase?: string;
+    timestamp: string;
+}
+/** How a hive entry was promoted (issue #1847 §3 lineage). */
+export type PromotionActor = 'auto' | 'manual' | 'manual-override';
+/**
+ * Lineage + validated-evidence block attached to a promoted hive entry (issue
+ * #1847 §3). A promoted hive record must retain enough provenance to audit
+ * redaction/ownership and to trace back to its source without storing
+ * unnecessary sensitive content.
+ *
+ * All fields optional except `actor` so legacy on-disk records (which predate
+ * this block) load unchanged. Legacy records are NOT retroactively given a
+ * synthetic lineage block (no broad rewrite); consumers treat an absent
+ * `lineage` as "origin unknown, pre-#1847".
+ */
+export interface PromotionLineage {
+    /** UUID of the source swarm entry this hive record was promoted from. */
+    source_entry_id?: string;
+    /** Canonical cohort id of the source repository (#1846). */
+    source_cohort_id?: string;
+    /** Source entry content hash/revision (for drift detection). */
+    source_revision?: string;
+    /** Prior phase/confidence snapshot captured at promotion time. */
+    prior_confidence?: number;
+    prior_phases_alive?: number;
+    /** Ids of {@link PromotionEvidenceRecord}s that contributed to this promotion. */
+    contributing_evidence_ids?: string[];
+    /** For merged near-duplicates: losing entry ids preserved for audit. */
+    merged_from?: string[];
+    /** The promotion transaction/event id (ties to the hive audit-event log). */
+    promotion_event_id?: string;
+    /** Who/what initiated the promotion. */
+    actor: PromotionActor;
+    reason?: string;
+    /** When an override was used: the policy gates that failed. */
+    override_failed_gates?: string[];
+}
 export interface HiveKnowledgeEntry extends KnowledgeEntryBase {
     tier: 'hive';
     confirmed_by: ProjectConfirmationRecord[];
@@ -213,6 +285,9 @@ export interface HiveKnowledgeEntry extends KnowledgeEntryBase {
     encounter_score: number;
     /** @deprecated Legacy field for backward compatibility. Use encounter_score for weighting. */
     encounter_count?: number;
+    /** #1847: promotion lineage + validated-evidence references. Optional so
+     * legacy on-disk records load unchanged; normalized in-memory on read. */
+    lineage?: PromotionLineage;
 }
 export interface RejectedLesson {
     id: string;
@@ -298,6 +373,18 @@ export interface KnowledgeConfig {
      * demotion counter increments for the current phase. Default: -0.3 (matches
      * `OUTCOME_BLOCK_THRESHOLD`). */
     promoted_demotion_signal_threshold: number;
+    /** #1847: minimum number of validated terminal-application receipts
+     * (PromotionEvidenceRecord) required for the `validated_terminal_applications`
+     * promotion gate. Default 0 — conservative: until #1849 produces real
+     * receipts, absence of evidence neither credits nor blocks. Raising this
+     * activates application-evidence gating. Legacy records get NO synthetic
+     * credit; they simply do not add to the count. */
+    promotion_min_terminal_applications: number;
+    /** #1847: minimum number of DISTINCT canonical cohort ids that must appear
+     * among the validated terminal-application receipts for the
+     * `validated_terminal_applications` gate. Default 0 (conservative; see
+     * `promotion_min_terminal_applications`). */
+    promotion_min_distinct_cohorts: number;
     /** Change 5: retrieval-upgrade tuning (MMR / cold-start / synonyms). */
     retrieval?: {
         mmr_lambda?: number;