opencode-swarm 7.130.2 → 7.132.0

package/dist/evidence/immutable-store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared write pipeline for content-addressed, write-once artifacts under
+ * `.swarm/` (issue #1821).
+ *
+ * Several subsystems persist artifacts that must never be silently rewritten:
+ * the evaluation store (`.swarm/evolution/{task-sets,runs,decisions,...}`) and
+ * the consensus report store (`.swarm/evolution/consensus/`). They all need the
+ * identical sequence — create the parent directory, take the evidence lock,
+ * re-read whatever is already on disk, treat a byte-identical (or
+ * caller-defined equivalent) payload as idempotent, reject a divergent payload,
+ * and otherwise commit through the atomic temp-file+rename write.
+ *
+ * That sequence lives here exactly once. Duplicating it per store is how the
+ * two copies drift: one gains a conflict check the other lacks, or one takes
+ * the lock under the wrong actor and corrupts lock attribution.
+ *
+ * Deliberate design points:
+ * - `agent` is a **parameter**, not a constant. The lock actor identifies the
+ *   subsystem doing the write; hard-coding one store's actor would mislabel
+ *   every other store's lock acquisitions in telemetry and diagnostics.
+ * - `serialize` is a **parameter**. The canonical-JSON encoder that the
+ *   evaluation store uses lives in `src/evaluation/`, and importing it here
+ *   would tie this module to a sibling subsystem it has no business knowing
+ *   about. Callers supply their own canonical form.
+ * - `conflictError` is a **factory parameter** rather than a hard-coded error
+ *   class, so each store throws its own conflict type (and keeps `instanceof`
+ *   identity with its own tests) without this module importing any of them.
+ */
+/**
+ * Read a UTF-8 file, returning `undefined` when it does not exist.
+ *
+ * A missing immutable artifact is the normal first-write case, not an error, so
+ * this collapses `ENOENT` into `undefined` while letting every other filesystem
+ * error (EACCES, EISDIR, EIO, ...) propagate. Exported because the same
+ * "absent means not-yet-written" semantics apply to the stores' own reads.
+ */
+export declare function readOptionalFile(filePath: string): Promise<string | undefined>;
+/**
+ * Why a write to an already-populated path could not proceed.
+ *
+ * - `corrupt`   — a file exists but does not parse/validate as the artifact
+ *                 type, so it cannot be compared against the desired payload.
+ * - `divergent` — a valid artifact exists and differs from the desired payload.
+ */
+export type ImmutableArtifactConflict = {
+    kind: 'corrupt';
+    filePath: string;
+    cause: unknown;
+} | {
+    kind: 'divergent';
+    filePath: string;
+};
+export type WriteImmutableArtifactOptions<T> = {
+    /** Project root; the evidence lock is scoped to it. */
+    directory: string;
+    /** Lock key — the artifact path relative to `<directory>/.swarm/`. */
+    relativeLockPath: string;
+    /** Absolute path of the artifact file to write. */
+    filePath: string;
+    /** Lock actor, e.g. the owning store's name. */
+    agent: string;
+    /** Lock task identifier, for diagnostics. */
+    taskId: string;
+    /** The artifact to persist. */
+    value: T;
+    /** Canonical encoder; its output is what lands on disk verbatim. */
+    serialize: (value: unknown) => string;
+    /** Schema parse/validate for the artifact already on disk. */
+    parse: (value: unknown) => T;
+    /**
+     * Optional equivalence escape hatch for artifacts whose canonical form may
+     * legitimately differ (e.g. a decision that carries a decision timestamp).
+     */
+    isEquivalent?: (existing: T, desired: T) => boolean;
+    /** Builds the store-specific error thrown on a conflict. */
+    conflictError: (conflict: ImmutableArtifactConflict) => Error;
+};
+/**
+ * Write `value` to `filePath` exactly once.
+ *
+ * Idempotent: re-writing an equivalent payload returns the artifact already on
+ * disk without touching the file. Writing a different payload to the same path
+ * throws the caller-supplied conflict error. The whole read-compare-write runs
+ * under the evidence lock so concurrent writers cannot interleave.
+ */
+export declare function writeImmutableArtifact<T>(options: WriteImmutableArtifactOptions<T>): Promise<T>;

package/dist/evidence/manager.d.ts

@@ -16,6 +16,32 @@ export type LoadEvidenceResult = {
     status: 'invalid_schema';
     errors: string[];
 };
+/**
+ * Options for {@link loadEvidence}.
+ *
+ * Additive and backward-compatible: omitting the argument entirely — which every
+ * pre-existing caller does — keeps the historical behaviour exactly, including
+ * the lazy in-place upgrade of a legacy flat retrospective.
+ */
+export interface LoadEvidenceOptions {
+    /**
+     * Whether a legacy flat retrospective may be upgraded **in place** on read.
+     *
+     * `true` (the default, and the historical behaviour) persists the wrapped
+     * bundle back to `.swarm/evidence/<taskId>/evidence.json` under the evidence
+     * lock, so the repair happens once instead of on every read.
+     *
+     * `false` makes the call a pure read: the caller still receives the wrapped,
+     * validated bundle, but nothing is written, no lock is taken, and no
+     * `evidence-loader` actor appears in lock telemetry. Callers that advertise a
+     * read-only contract — the consensus corpus (`src/consensus/corpus.ts`) is the
+     * first — MUST pass `false`. A mining run that silently rewrote the evidence
+     * it was merely reading would falsify that contract and, because
+     * `LEGACY_TASK_COMPLEXITY_MAP` remaps values on the way through, would also
+     * change the stored data.
+     */
+    migrate?: boolean;
+}
 /**
  * All valid evidence types (13 total)
  */
@@ -67,8 +93,12 @@ declare function wrapFlatRetrospective(flatEntry: Record<string, unknown>, taskI
 /**
  * Load evidence bundle for a task.
  * Returns a LoadEvidenceResult discriminated union.
+ *
+ * By default this may perform a one-time in-place upgrade of a legacy flat
+ * retrospective (see {@link LoadEvidenceOptions.migrate}). Pass
+ * `{ migrate: false }` for a guaranteed pure read.
  */
-export declare function loadEvidence(directory: string, taskId: string): Promise<LoadEvidenceResult>;
+export declare function loadEvidence(directory: string, taskId: string, options?: LoadEvidenceOptions): Promise<LoadEvidenceResult>;
 /**
  * List all task IDs that have evidence bundles.
  * Returns sorted array of valid task IDs.

package/dist/hooks/actionability-predicate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The pure actionability predicate (knowledge Layer 5), extracted as a LEAF
+ * module (issue #1821 Workstream A3).
+ *
+ * Why this file exists separately from `knowledge-validator.ts`: the predicate
+ * itself has always been pure, but its host module imports `node:fs/promises`
+ * and `proper-lockfile` at the top level. `hive-policy.ts` documents that it
+ * "performs NO I/O and holds NO module-level mutable state" (invariant 8), so
+ * importing the predicate from the validator would have quietly made that
+ * comment false. Extracting the predicate keeps the documented purity TRUE
+ * rather than weakening the comment.
+ *
+ * CONTRACT FOR THIS MODULE: no I/O imports, no module-level mutable state, no
+ * plugin-init-path import. It may only import types. `knowledge-validator.ts`
+ * re-exports everything here, so every existing consumer is unaffected.
+ */
+import type { KnowledgeEntryBase } from './knowledge-types.js';
+export interface ActionabilityResult {
+    actionable: boolean;
+    /** Present only when not actionable. */
+    reason?: 'missing_predicate' | 'missing_scope' | 'missing_predicate_and_scope';
+}
+/** The exact field subset the predicate reads. */
+export type ActionabilityInput = Pick<KnowledgeEntryBase, 'forbidden_actions' | 'required_actions' | 'verification_checks' | 'verification_predicate' | 'applies_to_tools' | 'applies_to_agents'>;
+/**
+ * Layer 5: an entry is actionable only when it carries at least one
+ * machine-checkable predicate AND at least one scope tag.
+ *
+ *   predicate := forbidden_actions | required_actions | verification_checks
+ *                | verification_predicate
+ *   scope     := applies_to_tools | applies_to_agents
+ *
+ * Plain-prose lessons (no predicate, no scope) are NOT actionable and must be
+ * quarantined rather than activated.
+ */
+export declare function validateActionability(entry: ActionabilityInput): ActionabilityResult;

package/dist/hooks/curator.d.ts

@@ -24,6 +24,7 @@
  * This dual dispatch means agent lists are incomplete — they capture factory-dispatched
  * curators but omit hook-dispatched ones. This is by design for hook-internal operations.
  */
+import { checkRecommendations, recordEmittedRecommendations } from '../services/recommendation-ledger.js';
 import { listSkills, parseDraftFrontmatter, retireOrMarkStale, retireSkill } from '../services/skill-generator.js';
 import { getSkillVersion, reviseSkill } from '../services/skill-reviser.js';
 import type { ComplianceObservation, CuratorConfig, CuratorInitResult, CuratorPhaseResult, CuratorSummary, KnowledgeRecommendation, PhaseDigestEntry } from './curator-types.js';
@@ -61,6 +62,8 @@ export declare const _internals: {
     reviseSkill: typeof reviseSkill;
     getSkillVersion: typeof getSkillVersion;
     readLatestPostMortemDigest: (directory: string) => string | null;
+    checkRecommendations: typeof checkRecommendations;
+    recordEmittedRecommendations: typeof recordEmittedRecommendations;
 };
 export interface RecommendationParseDiagnostic {
     section: 'OBSERVATIONS' | 'RECOMMENDATION_ID';

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

@@ -21,8 +21,19 @@
  * (it neither credits nor blocks) and current behavior is preserved. Operators
  * raise the thresholds to activate application-evidence gating.
  *
+ * Actionability floor (#1821 A3): the `actionability_floor` gate refuses to
+ * promote a plain-prose lesson — a promotion candidate must carry at least one
+ * machine-checkable predicate AND at least one scope tag. It is ON by default
+ * (`knowledge.promotion_require_actionable`, schema default `true`); the
+ * hand-written `KnowledgeConfig` interface declares the field OPTIONAL, so this
+ * module reads it as `?? true`.
+ *
  * 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).
+ * `validateActionability` is imported from the LEAF module
+ * `./actionability-predicate.js` rather than from `./knowledge-validator.js`,
+ * which imports `node:fs/promises` + `proper-lockfile` — importing the
+ * validator here would have made the no-I/O statement above false.
  */
 import type { KnowledgeConfig, PromotionEvidenceRecord, SwarmKnowledgeEntry } from './knowledge-types.js';
 /** A single named policy gate and whether it passed. */

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

@@ -126,6 +126,7 @@ export declare const _internals: {
         promoted_demotion_signal_threshold: number;
         promotion_min_terminal_applications: number;
         promotion_min_distinct_cohorts: number;
+        promotion_require_actionable: boolean;
         realtime_learning_nudge: {
             enabled: boolean;
             first_after_tool_calls: number;
@@ -156,6 +157,26 @@ export interface ManualPromotionOptions {
     force?: boolean;
     reason?: string;
 }
+/**
+ * Actionability fields supplied on the DIRECT-TEXT promote path (#1821 A3).
+ *
+ * `/swarm promote "<text>"` has no swarm entry to inherit predicates/scope
+ * from, so the command passes them explicitly. Without this parameter the
+ * default-on `actionability_floor` gate would be permanently unsatisfiable on
+ * that path: every direct-text promotion would return "Promotion blocked by
+ * policy" and operators would be pushed into `--force`, poisoning the
+ * override-audit signal that #1847 exists to keep honest.
+ *
+ * `promoteFromSwarm` does NOT take these — it inherits the source swarm entry's
+ * own actionable-directive fields via `carryActionableFields`.
+ */
+export interface ManualActionabilityFields {
+    applies_to_tools?: string[];
+    applies_to_agents?: string[];
+    required_actions?: string[];
+    forbidden_actions?: string[];
+    verification_checks?: string[];
+}
 /**
  * Promote a lesson directly to the hive (manual promotion).
  *
@@ -168,8 +189,13 @@ export interface ManualPromotionOptions {
  * On a policy PASS → promotes with actor='manual'.
  *
  * An exact entry id / direct text alone is NEVER authorization to bypass policy.
+ *
+ * `actionable` (#1821 A3) carries the predicate/scope fields the direct-text
+ * path has no swarm entry to inherit from. They land on the synthetic stand-in
+ * (so the `actionability_floor` gate can see them) AND on the written hive
+ * entry (so a correctly-supplied field is not dropped on write).
  */
-export declare function promoteToHive(directory: string, lesson: string, category?: string, options?: ManualPromotionOptions, config?: KnowledgeConfig): Promise<string>;
+export declare function promoteToHive(directory: string, lesson: string, category?: string, options?: ManualPromotionOptions, config?: KnowledgeConfig, actionable?: ManualActionabilityFields): Promise<string>;
 /**
  * Promote a lesson from swarm knowledge to hive.
  *

package/dist/hooks/knowledge-dedup-sweep.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Active-store near-duplicate dedup sweep (issue #1821 Lane A).
+ *
+ * The swarm knowledge store accretes near-duplicate lessons: the same insight
+ * arrives from a curator pass, a retrospective, and a micro-reflection, each
+ * with its own id. The `/swarm link` family migration already merges
+ * near-duplicates when two cohort stores are unified, but nothing ever did it
+ * for the ACTIVE store of a single worktree. This sweep closes that gap using
+ * the SAME merge helpers (`knowledge/entry-merge.ts`), so a lesson merged by a
+ * sweep and a lesson merged by a link end up in the same shape.
+ *
+ * ## Contract
+ *
+ * - ACTIVE entries only (`candidate` / `established` / `promoted`). Archived and
+ *   quarantined entries are neither merge targets nor merge sources.
+ * - Bucketed by `category` so the pairwise comparison count is bounded by the
+ *   sum of per-category squares rather than the whole store squared, and hard
+ *   capped by `learning.dedup_sweep.max_comparisons`.
+ * - Deterministic: entries are compared in `id` order and clusters are resolved
+ *   in `id` order, so two concurrent sweeps converge on the same winner rather
+ *   than racing to different survivors.
+ * - All merges plus all loser archivals commit inside ONE `transactKnowledge`
+ *   transaction, so a crash cannot leave a loser archived with its evidence
+ *   never carried to the winner.
+ * - IDEMPOTENT. Losers are archived and only active entries are considered, so
+ *   a second sweep over an unchanged store is a no-op. See the CLUSTERING note
+ *   below for why that holds transitively, and
+ *   `tests/unit/hooks/knowledge-dedup-sweep.test.ts` for the assertion — the
+ *   underlying `mergeStoreEntries` is NOT idempotent (it re-merges and doubles
+ *   counters on a repeat), so this property is earned here, not inherited.
+ *
+ * ## CLUSTERING (why a second sweep is a no-op)
+ *
+ * Near-duplication is not transitive: A~B and B~C does not imply A~C. A greedy
+ * "compare against the surviving representative" pass would therefore leave C
+ * active next to a winner it is a near-duplicate of, and the NEXT sweep would
+ * merge them — the sweep would never reach a fixed point.
+ *
+ * Instead every in-bucket pair is compared and near-duplicate pairs are unioned
+ * into connected components (union-find). Each component elects ONE winner that
+ * absorbs every other member. Because the winner's surviving lesson is always
+ * one of its own component's member lessons, and no member of one component is
+ * a near-duplicate of any member of another (that is exactly what the
+ * transitive closure guarantees), the surviving winners are pairwise non-
+ * duplicate. The next sweep finds nothing.
+ *
+ * The only ways a follow-up sweep does more work are the explicit budgets
+ * (`max_comparisons`, `max_merges_per_sweep`) — that is bounded progress, not
+ * non-convergence.
+ *
+ * ## Configuration
+ *
+ * The sweep reads its OWN config via `loadPluginConfigWithMeta(directory)`.
+ * `runCuratorPhase`'s 5th parameter is `knowledgeConfig: { directory?: string }`
+ * and cannot carry thresholds, and widening that signature would ripple through
+ * all three curator entry points. The dynamic `import('../config/index.js')`
+ * matches the established hook pattern (`knowledge-curator.ts`,
+ * `knowledge-escalator.ts`, `phase-monitor.ts`) and keeps `hooks → config` off
+ * the static import graph.
+ */
+import type { KnowledgeEntryBase } from './knowledge-types.js';
+export interface DedupSweepOptions {
+    /**
+     * Knowledge-store directory override — the curator's
+     * `knowledgeConfig.directory`. Defaults to `directory`. Audit surfaces
+     * (tombstone events, rewrite history) always use `directory`, matching the
+     * curator's own archive-invalidation call.
+     */
+    knowledgeDirectory?: string;
+}
+/** One applied merge: `loserId` was absorbed into `winnerId` and archived. */
+export interface DedupSweepMerge {
+    winnerId: string;
+    loserId: string;
+    category: string;
+}
+export interface DedupSweepResult {
+    /** False when `learning.dedup_sweep.enabled` is off (nothing was read). */
+    enabled: boolean;
+    /** Number of ACTIVE entries considered. */
+    scanned: number;
+    /** Pairwise near-duplicate comparisons actually performed. */
+    comparisons: number;
+    /** True when `max_comparisons` cut the scan short. */
+    comparisonBudgetExhausted: boolean;
+    /** True when `max_merges_per_sweep` cut the merge set short. */
+    mergeBudgetExhausted: boolean;
+    /** Merges that actually committed. */
+    merges: DedupSweepMerge[];
+}
+declare function isActive(entry: KnowledgeEntryBase): boolean;
+/**
+ * Evidence mass used as the third winner-selection tiebreak. Counts the
+ * outcome signals that represent a real interaction with the entry plus the
+ * confirmation records.
+ */
+declare function evidenceWeight(entry: KnowledgeEntryBase): number;
+/**
+ * Winner-selection order (negative result ⇒ `a` wins):
+ *   1. actionable beats non-actionable — an actionable directive is enforceable
+ *      and a non-actionable near-duplicate is not; losing the actionable one
+ *      would silently downgrade the store even though `mergeEntryFields` now
+ *      carries the predicates across.
+ *   2. higher confidence
+ *   3. more evidence
+ *   4. older `created_at` (the original, not the restatement)
+ *   5. lexicographic `id` — a total order, so concurrent sweeps converge.
+ */
+declare function compareCandidates(a: KnowledgeEntryBase, b: KnowledgeEntryBase): number;
+interface PlannedMerge {
+    winner: KnowledgeEntryBase;
+    loser: KnowledgeEntryBase;
+    category: string;
+}
+/**
+ * Build the merge plan from a read-only snapshot. Pure (no I/O), so it is
+ * cheap to reason about and the transaction below only has to re-validate.
+ */
+declare function planMerges(active: KnowledgeEntryBase[], threshold: number, maxComparisons: number, maxMerges: number): {
+    plan: PlannedMerge[];
+    comparisons: number;
+    comparisonBudgetExhausted: boolean;
+    mergeBudgetExhausted: boolean;
+};
+/**
+ * Merge active near-duplicate knowledge entries in `directory`'s swarm store.
+ *
+ * Never throws: every failure path is logged and returns a result describing
+ * what did happen. The caller (`runCuratorPhase`) must never be blocked by a
+ * background learning loop.
+ */
+export declare function sweepActiveNearDuplicates(directory: string, options?: DedupSweepOptions): Promise<DedupSweepResult>;
+/**
+ * Tier-0 pure-function test seam (see `.opencode/skills/writing-tests`). These
+ * are deterministic and dependency-free at the I/O boundary, so their tests need
+ * no mocks at all — planning, winner selection, and evidence weighting are
+ * exercised directly instead of through a temp-directory round trip.
+ */
+export declare const _test_exports: {
+    compareCandidates: typeof compareCandidates;
+    evidenceWeight: typeof evidenceWeight;
+    isActive: typeof isActive;
+    planMerges: typeof planMerges;
+};
+export {};

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

@@ -63,6 +63,10 @@ export interface InjectForDelegateResult {
     entries: RankedEntry[];
     trace_id: string;
 }
+/** Invalidate memoized injections. Called by the admission path after a write. */
+export declare function bumpKnowledgeGeneration(): number;
+/** Current corpus generation. Part of the architect injection cache key. */
+export declare function getKnowledgeGeneration(): number;
 /**
  * Retrieve the subset of active knowledge directives scoped to a delegated
  * subagent's role + expected tools (Change 1, Task 1.2). Emits a single

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

@@ -42,6 +42,32 @@ export declare function appendRewriteHistory(directory: string, record: RewriteH
  * Read rewrite/merge history records (issue #1848 §3). Used for audit/recovery.
  */
 export declare function readRewriteHistory(directory: string): Promise<RewriteHistoryRecord[]>;
+/**
+ * Normalize a loosely-typed knowledge array field: keep only strings,
+ * optionally truncate each item, deduplicate case-insensitively, then cap.
+ *
+ * The steps run in EXACTLY this order and the order is observable:
+ *
+ *  1. non-array input      → `[]`
+ *  2. drop non-string items
+ *  3. truncate each item to `itemMaxChars` (when provided)
+ *  4. deduplicate on a case-insensitive key, PRESERVING the first
+ *     occurrence's original casing
+ *  5. cap to `opts.cap`, keeping the first N survivors
+ *
+ * Truncation happens BEFORE deduplication, so two items that differ only past
+ * `itemMaxChars` collapse into one. Deduplication happens BEFORE the cap, so a
+ * run of duplicates can no longer evict distinct values off the end — that
+ * eviction was the defect this helper eradicates (a bare positional cap of 20
+ * with no dedup, repeated at six call sites — issue #1821 Lane 0b).
+ *
+ * `values` is typed `unknown` because every call site receives untrusted or
+ * loosely-typed input (LLM output, tool arguments, on-disk records).
+ */
+export declare function dedupeCapped(values: unknown, opts: {
+    cap: number;
+    itemMaxChars?: number;
+}): string[];
 export declare function appendKnowledge<T>(filePath: string, entry: T): Promise<void>;
 export declare function rewriteKnowledge<T>(filePath: string, entries: T[]): Promise<void>;
 export declare function transactFile<T>(filePath: string, read: (filePath: string) => Promise<T>, write: (filePath: string, data: T) => Promise<void>, mutate: (data: T) => T | null): Promise<boolean>;

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

@@ -490,6 +490,12 @@ export interface KnowledgeConfig {
      * `validated_terminal_applications` gate. Default 0 (conservative; see
      * `promotion_min_terminal_applications`). */
     promotion_min_distinct_cohorts: number;
+    /** #1821: require a promotion candidate to carry an actionable directive
+     * before it may be promoted. Default true (see `KnowledgeConfigSchema`).
+     * Declared OPTIONAL here on purpose: this hand-written interface is what the
+     * hooks layer imports, and hundreds of full config literals in tests would
+     * otherwise need updating. The Zod inference keeps it required. */
+    promotion_require_actionable?: boolean;
     /** Change 5: retrieval-upgrade tuning (MMR / cold-start / synonyms). */
     retrieval?: {
         mmr_lambda?: number;

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

@@ -79,23 +79,19 @@ export declare function validateSkillCandidatePath(p: unknown): boolean;
 /** Validate the optional ActionableDirectiveFields block on a knowledge entry. */
 export declare function validateActionableFields(fields: ActionableDirectiveFields | undefined): ActionableValidationResult;
 export type { ActionableDirectiveFields, DirectivePriority };
-export interface ActionabilityResult {
-    actionable: boolean;
-    /** Present only when not actionable. */
-    reason?: 'missing_predicate' | 'missing_scope' | 'missing_predicate_and_scope';
-}
 /**
- * Layer 5: an entry is actionable only when it carries at least one
- * machine-checkable predicate AND at least one scope tag.
- *
- *   predicate := forbidden_actions | required_actions | verification_checks
- *                | verification_predicate
- *   scope     := applies_to_tools | applies_to_agents
+ * The predicate itself now lives in the leaf module
+ * `./actionability-predicate.js` (issue #1821 Workstream A3). It is re-exported
+ * here so every historical consumer of `knowledge-validator` is unaffected.
  *
- * Plain-prose lessons (no predicate, no scope) are NOT actionable and must be
- * quarantined rather than activated.
+ * Why it moved: this module imports `node:fs/promises` and `proper-lockfile` at
+ * the top level, while `hive-policy.ts` documents that it performs NO I/O
+ * (invariant 8). The promotion `actionability_floor` gate needs the predicate,
+ * so the predicate moved to a leaf with no I/O imports instead of the purity
+ * comment being weakened.
  */
-export declare function validateActionability(entry: Pick<KnowledgeEntryBase, 'forbidden_actions' | 'required_actions' | 'verification_checks' | 'verification_predicate' | 'applies_to_tools' | 'applies_to_agents'>): ActionabilityResult;
+export type { ActionabilityInput, ActionabilityResult, } from './actionability-predicate.js';
+export { validateActionability } from './actionability-predicate.js';
 /** Returns the knowledge-unactionable.jsonl path for the given directory (link-aware). */
 export declare function resolveUnactionablePath(directory: string): string;
 /** One quarantined-unactionable record. */

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

@@ -24,11 +24,18 @@ export type MicroOutcome = 'success' | 'failure_test' | 'failure_lint' | 'failur
 export declare const MICRO_PROMPT_INPUT_CAP = 1800;
 /** One v3-schema candidate insight written to the queue. */
 export interface InsightCandidate extends ActionableDirectiveFields {
+    /**
+     * Deterministic candidate identity (`ic_<16hex>`), issue #1821 Workstream B
+     * D1. OPTIONAL on purpose: legacy id-less lines already on disk recompute
+     * the identical value through `resolveInsightCandidateId`, so no migration
+     * of `.swarm/insight-candidates.jsonl` is required.
+     */
+    id?: string;
     lesson: string;
     category: string;
     tags: string[];
     source: {
-        kind: 'micro_reflection';
+        kind: 'micro_reflection' | 'prm_pattern';
         task_id?: string;
         agent: string;
         outcome: MicroOutcome;
@@ -36,6 +43,75 @@ export interface InsightCandidate extends ActionableDirectiveFields {
     };
     created_at: string;
 }
+/**
+ * Compute the deterministic identity of an insight candidate.
+ *
+ * Hashes exactly `{lesson, taskId, createdAt}`. `canonicalJson` DROPS
+ * `undefined` keys, so a candidate with no `source.task_id` hashes
+ * consistently whether the key is absent or explicitly undefined — which is
+ * what makes the value reproducible from a legacy durable line that never
+ * carried an `id`.
+ */
+export declare function computeInsightCandidateId(cand: {
+    lesson: string;
+    source?: {
+        task_id?: string;
+    };
+    created_at: string;
+}): string;
+/**
+ * Resolve a candidate's identity by ALWAYS deriving it from content.
+ *
+ * The stamped `id` is deliberately NOT trusted. `.swarm/insight-candidates.jsonl`
+ * is read back through a bare `JSON.parse(...) as InsightCandidate`, and the
+ * curator explicitly treats that file as tamper-suspect (it re-applies both
+ * write-time gates on read). A trusted `id` would be an unvalidated field on
+ * that same untrusted line: setting it to an already-admitted candidate's id
+ * would make the fold-in silently DROP a distinct new lesson, and rotating it
+ * every run would let the same lesson be re-confirmed every phase, inflating
+ * confidence toward hive auto-promotion.
+ *
+ * Recomputation is a single sha256 over a three-field object, bounded by the
+ * meso batch limit — far cheaper than the failure it prevents. The stamped `id`
+ * survives as a diagnostic and round-trip aid only.
+ */
+export declare function resolveInsightCandidateId(cand: InsightCandidate): string;
+/**
+ * The marker recorded in an admitted entry's EXISTING `source_knowledge_ids`
+ * field so the phase-boundary fold-in can recognise a candidate real-time
+ * admission already handled. 27 chars, matching the 64-char per-id ceiling
+ * `validateActionableFields` applies wherever that field IS validated (the
+ * admission/fold-in paths pass an explicit field subset that omits it, so the
+ * length is a construction guarantee here rather than a checked one).
+ */
+export declare function insightAdmissionMarker(candidateId: string): string;
+/**
+ * Cap on `source_knowledge_ids` for an entry stamped by real-time admission.
+ *
+ * The knowledge store deliberately EXCLUDES `source_knowledge_ids` from its
+ * 20-item write normalization (see `WRITE_NORMALIZED_ARRAY_FIELDS` in
+ * `knowledge-store.ts`) because `skill-invalidator.ts` walks the full list.
+ * That exclusion means nothing else bounds the array, so an entry reinforced by
+ * many distinct candidates would grow it forever (AGENTS.md invariant 8). 50
+ * matches the cap the curator's own producer already applies.
+ */
+export declare const MAX_SOURCE_KNOWLEDGE_IDS = 50;
+/**
+ * Union an insight marker into an entry's `source_knowledge_ids`, bounded.
+ *
+ * Eviction drops the OLDEST `insight:` markers only. Non-insight ids (`task:`
+ * ids and real knowledge ids) are NEVER dropped: `skill-invalidator.ts` walks
+ * them to retire skills whose source entry was archived, so silently losing one
+ * would leave a stale skill live. If the array is over cap purely because of
+ * non-insight ids it is left over cap — correctness beats the bound here, and
+ * that case is already bounded by the producers of those ids.
+ *
+ * Losing a very old insight marker can at worst allow ONE extra confirmation
+ * for a long-superseded candidate; unbounded growth has no such ceiling.
+ */
+export declare function unionInsightMarker(existing: string[] | undefined, marker: string): string[];
+/** Extract the insight marker carried by an entry, if any. */
+export declare function findInsightAdmissionMarker(sourceKnowledgeIds: string[] | undefined): string | undefined;
 /** Returns `.swarm/insight-candidates.jsonl` for a project directory. */
 export declare function resolveInsightCandidatesPath(directory: string): string;
 /**
@@ -47,6 +123,15 @@ export declare function classifyOutcome(transcript: string, trajectory: Trajecto
 /** Read a task's trajectory slice. Fail-open: [] when absent/corrupt. */
 export declare function readTaskTrajectory(directory: string, taskId: string): Promise<TrajectoryEntry[]>;
 export declare const INSIGHT_CANDIDATES_MAX_ENTRIES = 500;
+/** Append validated candidates to the insight queue (best-effort, fail-open).
+ *  Uses transactFile for consistency with consumeInsightCandidates and enforces
+ *  a FIFO cap to prevent unbounded growth between phase completions.
+ *
+ *  EXPORTED (#1821) so the PRM pattern producer can write the SAME durable
+ *  crash backstop the micro-reflector writes. Any producer that only enqueues
+ *  in memory loses its candidate on process death, on queue overflow, and on a
+ *  drain failure — with no phase-boundary fold-in to recover it. */
+export declare function appendInsightCandidates(directory: string, candidates: InsightCandidate[]): Promise<void>;
 /** Build the bounded micro-reflection prompt (≤ MICRO_PROMPT_INPUT_CAP chars). */
 export declare function buildMicroPrompt(params: {
     agent: string;
@@ -75,6 +160,13 @@ export declare function runMicroReflection(params: {
     trajectory: TrajectoryEntry[];
     llmDelegate?: CuratorLLMDelegate;
     quota?: EnrichmentQuotaOptions;
+    /** Session that produced the reflection — required for real-time admission. */
+    sessionID?: string;
+    /** `learning.realtime_admission` knobs the enqueue side needs. */
+    admission?: {
+        enabled?: boolean;
+        maxQueueSize?: number;
+    };
 }): Promise<MicroReflectionResult>;
 export interface MicroReflectorInput {
     tool: unknown;
@@ -87,10 +179,22 @@ export interface MicroReflectorInput {
 export interface MicroReflectorOutput {
     output?: unknown;
 }
+/**
+ * True for the delegation tool under either casing.
+ *
+ * EXPORTED (issue #1821 Workstream B) so the real-time admission drain adapter
+ * can self-gate on exactly the same predicate this hook uses. Six private
+ * copies of this two-line check already exist across the hook layer; the drain
+ * reuses this one rather than adding a seventh.
+ */
+export declare function isTaskTool(tool: unknown): boolean;
 /**
  * `tool.execute.after` adapter for the `Task` tool. Resolves the delegate, the
  * transcript, the task id, and the trajectory slice, then runs micro-reflection.
  * The LLM delegate is provided by the caller (so tests can inject one); when
  * absent, classification still runs but no LLM call is made.
  */
-export declare function microReflectorAfter(directory: string, input: MicroReflectorInput, output: MicroReflectorOutput, llmDelegate?: CuratorLLMDelegate, quota?: EnrichmentQuotaOptions): Promise<void>;
+export declare function microReflectorAfter(directory: string, input: MicroReflectorInput, output: MicroReflectorOutput, llmDelegate?: CuratorLLMDelegate, quota?: EnrichmentQuotaOptions, admission?: {
+    enabled?: boolean;
+    maxQueueSize?: number;
+}): Promise<void>;