opencode-swarm 7.130.2 → 7.131.0

package/dist/knowledge/entry-merge.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Field-level merge helpers for near-duplicate knowledge entries (issue #1821
+ * Lane A).
+ *
+ * Extracted verbatim-in-shape from `family-migration.ts` so the SAME merge
+ * semantics back both consumers:
+ *  - the cohort family migration (`/swarm link` / `/swarm unlink`), via
+ *    `mergeStoreEntries`, and
+ *  - the active-store near-duplicate sweep (`hooks/knowledge-dedup-sweep.ts`).
+ *
+ * A near-duplicate merge is PROVENANCE-PRESERVING, not lossless: the losing
+ * entry's id survives in `merged_from`, and every field that represents
+ * independently-earned evidence is unioned rather than overwritten. Both sides
+ * of a merge are genuine near-duplicates, so a predicate present on only one
+ * side was still earned and must survive.
+ *
+ * ## What this module fixes relative to the pre-#1821 implementation
+ *
+ * 1. **Actionability carry.** `required_actions`, `forbidden_actions`,
+ *    `verification_checks`, `applies_to_agents`, `applies_to_tools`,
+ *    `triggers`, and `source_knowledge_ids` were dropped entirely — a merge
+ *    could silently turn an actionable directive into an inert lesson. They are
+ *    now unioned through `dedupeCapped`.
+ * 2. **CAS integrity.** Swapping in the loser's longer lesson without
+ *    recomputing `content_hash` left the CAS token describing the DISCARDED
+ *    text, so every later authorized curation of a merged entry failed the
+ *    `transactKnowledgeWithCas` comparison. The hash is now recomputed and
+ *    `revision` bumped on any lesson swap.
+ * 3. **No shared arrays.** `unionConfirmedBy` returned a source array BY
+ *    REFERENCE when one side was absent, so a surviving winner and an archived
+ *    loser shared one mutable array. It always copies now.
+ * 4. **Symmetric guards.** `source_refs` and `retrieval_outcomes` required BOTH
+ *    sides to be populated before merging, so a sweep over mixed
+ *    legacy/enriched entries silently dropped the loser's refs and counters.
+ *    The one-sided cases are handled.
+ * 5. **Tags are unioned under the SAME bounded rule as their five siblings.**
+ *    See `TAG_UNION_RULE` below.
+ *
+ * ## TAG_UNION_RULE — the one place tags can still be lost, stated explicitly
+ *
+ * `tags` is a bounded field: the store's write boundary
+ * (`normalizeEntryArraysForWrite` in `knowledge-store.ts`) runs `dedupeCapped`
+ * over it at `WRITE_FIELD_CAP` = 20 on every transaction, and `knowledge_add`
+ * caps its producer at 20 as well. A merge therefore CANNOT promise to preserve
+ * every tag from both sides — two entries at the cap carry up to 40 distinct
+ * tags and only 20 can survive. Pretending otherwise is what the pre-fix code
+ * did: it unioned with a bare, uncapped, case-SENSITIVE `new Set(...)`, and the
+ * write boundary then silently truncated the result to the first 20 — which are
+ * the WINNER's, because the winner's tags come first in the union. The loser was
+ * archived in the same transaction, so the discarded tags were unrecoverable.
+ *
+ * The rule this module now implements and pins is:
+ *
+ *   1. Winner tags are retained FIRST, in their existing order.
+ *   2. Loser tags fill the remaining slots, in their existing order.
+ *   3. Dedup is CASE-INSENSITIVE and first-spelling-wins (`dedupeCapped`), the
+ *      same comparison the write boundary uses — so a merge no longer emits a
+ *      list the very next write would rewrite.
+ *   4. Anything past `MERGE_FIELD_CAP` (20) is DROPPED at merge time, visibly,
+ *      instead of being handed to the write boundary to drop invisibly.
+ *
+ * Consequence, stated so nobody has to rediscover it: a winner already holding
+ * 20 tags absorbs ZERO tags from the loser. That is not new data loss — it is
+ * the pre-existing store cap, now applied where it can be reasoned about and
+ * asserted. Order is the whole lever: if tag retention priority ever needs to
+ * change (e.g. prefer a rarer loser tag over a generic winner tag), it changes
+ * HERE, in the argument order of the union, not at the write boundary.
+ *
+ * Pinned by `tests/unit/hooks/knowledge-dedup-sweep-tag-cap.test.ts`.
+ *
+ * ## What this module deliberately does NOT change
+ *
+ * `weightedConfidence` reads POST-merge target state (it runs after
+ * `unionConfirmedBy` and `sumRetrievalOutcomes` have already mutated `target`),
+ * so the source's evidence is counted on both sides of the ratio. That is a
+ * real wart, but the formula defines `/swarm link` cohort-merge semantics and
+ * changing it is out of scope for #1821 Lane A. It is pinned by
+ * `tests/unit/knowledge/entry-merge-characterization-confidence.test.ts`.
+ */
+import type { KnowledgeEntryBase } from '../hooks/knowledge-types.js';
+/** Field-level union of `src` into `target` (mutates target). */
+export declare function mergeEntryFields(target: KnowledgeEntryBase, src: KnowledgeEntryBase): void;
+/**
+ * Union two `confirmed_by` lists, deduping on the identifying triple
+ * `phase_number|project_name|confirmed_at`.
+ *
+ * ALWAYS returns a fresh array. The pre-#1821 short-circuits returned an input
+ * array by reference, so a surviving winner and the archived loser it absorbed
+ * shared one mutable list — a later `push` on either side corrupted the other.
+ */
+export declare function unionConfirmedBy(a: KnowledgeEntryBase['confirmed_by'], b: KnowledgeEntryBase['confirmed_by']): KnowledgeEntryBase['confirmed_by'];
+/**
+ * Sum `src`'s retrieval counters into `target`'s (mutates target).
+ *
+ * One-sided cases are real on mixed legacy/enriched stores and are handled:
+ * a target with no counters ADOPTS a copy of the source's (a copy, so the
+ * winner and the archived loser never share one mutable record), and a source
+ * with no counters simply contributes nothing. The pre-#1821 guard bailed
+ * unless BOTH sides had counters, silently discarding the loser's evidence.
+ */
+export declare function sumRetrievalOutcomes(target: KnowledgeEntryBase, src: KnowledgeEntryBase): void;
+/**
+ * Evidence-weighted average of the two confidences.
+ *
+ * INTENTIONALLY UNCHANGED by #1821 Lane A. It runs AFTER `unionConfirmedBy`
+ * and `sumRetrievalOutcomes` have mutated `target`, so `wT` reflects POST-merge
+ * state and the source's evidence is counted on both sides of the ratio.
+ * Correcting that would change `/swarm link` cohort-merge results, which is out
+ * of scope for this issue; the behavior is pinned by the characterization
+ * suite.
+ */
+export declare function weightedConfidence(target: KnowledgeEntryBase, src: KnowledgeEntryBase): number;

package/dist/knowledge/family-migration.d.ts

@@ -27,6 +27,7 @@
  */
 import type { CounterRollup } from '../hooks/knowledge-events.js';
 import type { KnowledgeEntryBase } from '../hooks/knowledge-types.js';
+import { mergeEntryFields } from './entry-merge.js';
 import { type KnowledgeFamilyMember } from './family-manifest.js';
 /**
  * Lock config for the migration critical section. Re-exported from
@@ -58,14 +59,17 @@ declare function keySelectorFor(member: KnowledgeFamilyMember): (obj: unknown) =
  * confidence becomes an evidence-weighted average; the losing entry's `id` is
  * preserved in `merged_from` for retraction traceability. A `merge` is NOT
  * silent. (Critic C8: this is "provenance-preserving", not "lossless".)
+ *
+ * The field-level merge itself lives in `./entry-merge.ts` (issue #1821 Lane A)
+ * so the active-store near-duplicate sweep in `hooks/knowledge-dedup-sweep.ts`
+ * shares EXACTLY these semantics. `DEDUP_THRESHOLD` and this function stay here
+ * because they are migration policy, not merge mechanics.
  */
 declare function mergeStoreEntries(destination: KnowledgeEntryBase[], source: KnowledgeEntryBase[]): {
     merged: KnowledgeEntryBase[];
     added: number;
     skipped: number;
 };
-/** Field-level union of `src` into `target` (mutates target). */
-declare function mergeEntryFields(target: KnowledgeEntryBase, src: KnowledgeEntryBase): void;
 /**
  * Append-union / append-concat: append source lines whose key is not already
  * present on the destination. The key is extracted by `keyOf` — the member's id

package/dist/learning/admission.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Real-time knowledge admission (issue #1821, Workstream B).
+ *
+ * `admitCandidate` takes ONE insight candidate all the way into the swarm
+ * knowledge store; `drainSessionQueue` runs a bounded batch of them for a live
+ * session. Together they close the loop that previously required a phase
+ * boundary: a lesson learned at step 3 becomes retrievable at step 40 of the
+ * same session.
+ *
+ * ## The bounding rule (read before touching the await graph)
+ *
+ * `withTimeout` (`src/utils/timeout.ts`) is a `Promise.race`. A race does NOT
+ * cancel the loser. Racing the knowledge-store transaction would therefore be
+ * actively harmful: the "timed out" admission keeps running, keeps holding the
+ * `.swarm/` directory lock, and the next drain blocks on that lock while the
+ * caller has already been told the work finished. So:
+ *
+ * - the `transactKnowledge` call is NEVER raced or timed out;
+ * - only genuinely cancellable work (the optional LLM screening call) is
+ *   bounded, via a manual `AbortController` + `setTimeout` (see
+ *   `timeoutSignal` below) + `isAbortError`. This deliberately does NOT use
+ *   `AbortSignal.timeout(...)` (unlike `micro-reflector.ts`): Bun on Windows
+ *   has a native bug where that signal's `abort` event never fires when
+ *   awaited by a plain JS Promise (oven-sh/bun#29546) — exactly the shape
+ *   `screenCandidate`'s caller uses — which hung this file's own tests for
+ *   the full CI wall-clock kill on Windows;
+ * - `max_drain_wall_time_ms` is enforced BETWEEN candidates — it stops the
+ *   drain from STARTING new work, and never interrupts work in flight.
+ *
+ * Concurrency uses `p-limit` (an existing dependency, see
+ * `src/evaluation/runner.ts`) rather than a hand-rolled limiter.
+ */
+import type { KnowledgeConfig } from '../config/schema.js';
+import type { CuratorLLMDelegate } from '../hooks/curator.js';
+import type { InsightCandidate } from '../hooks/micro-reflector.js';
+import type { LearningProvenanceV1 } from './provenance.js';
+/** Outcome of a single admission attempt. */
+export type AdmissionOutcome = 'admitted' | 'reinforced' | 'rejected';
+export interface AdmissionResult {
+    outcome: AdmissionOutcome;
+    /** Present only for `rejected`, and on the two non-rejected paths for tracing. */
+    reason?: string;
+    /** Id of the entry created or reinforced. */
+    entryId?: string;
+    /** The `insight:<id>` marker this candidate is identified by. */
+    marker: string;
+    /** Validated provenance record for the write. */
+    provenance?: LearningProvenanceV1;
+}
+/** Everything `admitCandidate` needs that is not the candidate itself. */
+export interface AdmissionDeps {
+    knowledgeConfig: KnowledgeConfig;
+    projectName: string;
+    /**
+     * Phase recorded in the entry's `confirmed_by`. NOTE: this value is NOT used
+     * for idempotency — the fold-in resolves phase numbers differently across its
+     * five callers, which is exactly why D1 keys on candidate identity instead.
+     */
+    phaseNumber: number;
+    sessionID?: string;
+    /** Optional screening delegate. Absent → admission runs with no LLM call. */
+    llmDelegate?: CuratorLLMDelegate;
+    /** Per-candidate LLM deadline. 0 or absent disables the bound (and the call). */
+    llmTimeoutMs?: number;
+    /** Per-session LLM ceilings. Absent → no screening call is made. */
+    llmBudget?: {
+        maxLlmCallsPerSession: number;
+        maxTokensPerSession: number;
+    };
+    /**
+     * Milliseconds left in the enclosing drain's wall-clock budget. Supplied by
+     * `drainSessionQueue` so a screening call can never outlive the budget that
+     * is supposed to bound the whole drain. Absent → unbounded by the drain.
+     */
+    remainingBudgetMs?: () => number;
+    /** Called after a write actually changed the store — bumps injector caches. */
+    onKnowledgeChanged?: () => void;
+    /** Injectable clock/path seams for tests. */
+    now?: () => number;
+    resolveKnowledgePath?: (directory: string) => string;
+}
+/**
+ * Admit one candidate into the swarm knowledge store.
+ *
+ * Order: shape gate → actionability gate → near-duplicate lookup → reinforce or
+ * append, all inside ONE `transactKnowledge` so the dedup decision and the
+ * write cannot be separated by a concurrent writer.
+ */
+export declare function admitCandidate(directory: string, candidate: InsightCandidate, deps: AdmissionDeps): Promise<AdmissionResult>;
+/** The subset of a `tool.execute.after` input the drain adapter reads. */
+export interface RealtimeAdmissionInput {
+    tool: unknown;
+    sessionID?: unknown;
+}
+/**
+ * `tool.execute.after` adapter for real-time admission.
+ *
+ * Called UNCONDITIONALLY from the plugin hook chain and SELF-GATES here, in
+ * this order:
+ *
+ *   1. non-`Task` tool  → return immediately (mirrors `micro-reflector.ts`);
+ *   2. feature disabled → return;
+ *   3. no session id    → return;
+ *   4. empty queue      → return (an O(1) `Map.get(...).length` probe).
+ *
+ * Only past gate 4 does anything touch the filesystem. This ordering is the
+ * contract that keeps the hook off the hot path: it is awaited on EVERY tool
+ * call, so the non-`Task` path must cost a single string comparison and
+ * perform NO knowledge-store read, write, or lock acquisition.
+ *
+ * `resolveDeps` is a FACTORY, not a value, so resolving the plan (project name
+ * and phase number) happens only after all four gates pass.
+ */
+export declare function realtimeAdmissionAfter(directory: string, input: RealtimeAdmissionInput, config: RealtimeAdmissionConfig | undefined, resolveDeps: () => AdmissionDeps | Promise<AdmissionDeps>): Promise<DrainSummary | undefined>;
+/** Per-drain tallies. */
+export interface DrainSummary {
+    attempted: number;
+    admitted: number;
+    reinforced: number;
+    rejected: number;
+    /** Candidates put back because the wall-clock budget ran out first. */
+    deferred: number;
+    /** Candidates abandoned after exhausting their retry budget. */
+    failed: number;
+    retries: number;
+}
+/** `learning.realtime_admission`, as consumed by the drain. */
+export type RealtimeAdmissionConfig = {
+    enabled: boolean;
+    max_queue_size: number;
+    min_drain: number;
+    max_drain: number;
+    drain_depth_factor: number;
+    drain_velocity_factor: number;
+    max_llm_calls_per_session: number;
+    max_tokens_per_session: number;
+    max_concurrent_admissions: number;
+    max_retries_per_candidate: number;
+    per_candidate_llm_timeout_ms: number;
+    max_drain_wall_time_ms: number;
+    supersede_nudge: boolean;
+};
+/**
+ * Drain a bounded, adaptively-sized batch of a session's pending candidates.
+ *
+ * Bounds, in the order they apply:
+ *   1. `computeDrainSize` caps how many candidates are claimed at all;
+ *   2. `p-limit` caps how many run concurrently;
+ *   3. `max_retries_per_candidate` caps rework per candidate;
+ *   4. `max_drain_wall_time_ms` stops NEW candidates from starting.
+ *
+ * Never throws: a drain is best-effort background work behind a live tool call.
+ */
+export declare function drainSessionQueue(directory: string, sessionID: string, config: RealtimeAdmissionConfig, deps: AdmissionDeps): Promise<DrainSummary>;

package/dist/learning/candidate-queue.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Session-keyed bounded candidate queue (issue #1821, Workstream B).
+ *
+ * The micro-reflector emits insight candidates while a session is live. Before
+ * this module they were only readable at a phase boundary, so a lesson learned
+ * in step 3 could not help step 40 of the same session. This queue is the
+ * in-memory hand-off that makes same-session admission possible: the reflector
+ * enqueues, and the `Task`-tool drain adapter admits.
+ *
+ * Everything here is bounded on purpose (AGENTS.md invariant 8):
+ *
+ * - the KEY count is capped at `MAX_TRACKED_SESSIONS` with FIFO eviction,
+ *   mirroring `recentToolCallsBySession` in `src/hooks/adversarial-detector.ts`;
+ * - each session's item list is capped at `max_queue_size` with drop-oldest
+ *   plus a `dropped` counter, so a flood is observable rather than silent;
+ * - the LLM-call, token, and retry budgets are per-session ceilings that only
+ *   ever count up within a session and are released wholesale on reset.
+ *
+ * This module performs NO I/O and holds no clock dependency beyond `Date.now`
+ * (injectable through `_internals` for deterministic tests). The admission side
+ * effects live in `./admission.ts`; keeping them apart lets the queue be tested
+ * without touching the knowledge store.
+ */
+import type { InsightCandidate } from '../hooks/micro-reflector.js';
+/**
+ * Hard ceiling on how many drain cycles a single candidate may be claimed by.
+ *
+ * A candidate deferred by the wall-clock budget is requeued for the next drain.
+ * Without this bound a session whose budget always expires would bounce the same
+ * candidate forever, so the per-candidate retry cap would be satisfied while the
+ * queue still never made progress (AGENTS.md invariant 8).
+ */
+export declare const MAX_CANDIDATE_DRAIN_ATTEMPTS = 5;
+/** Per-session ceilings applied when a candidate is enqueued or budget is spent. */
+export interface CandidateQueueLimits {
+    /** Hard cap on pending candidates; the OLDEST is dropped past this. */
+    maxQueueSize: number;
+    /** Per-session ceiling on admission LLM calls. 0 disables LLM admission. */
+    maxLlmCallsPerSession: number;
+    /** Per-session ceiling on admission tokens. */
+    maxTokensPerSession: number;
+}
+/** Inputs to the adaptive drain sizer. Mirrors `learning.realtime_admission`. */
+export interface DrainSizeLimits {
+    /** Minimum candidates drained per cycle. */
+    minDrain: number;
+    /** Maximum candidates drained per cycle. */
+    maxDrain: number;
+    /** Weight of queue depth when sizing a drain (0 = ignore depth). */
+    drainDepthFactor: number;
+    /** Weight of arrival velocity when sizing a drain (0 = ignore rate). */
+    drainVelocityFactor: number;
+}
+/** One queued candidate plus the bookkeeping the drain needs. */
+export interface QueuedCandidate {
+    candidate: InsightCandidate;
+    /** Epoch millis the candidate entered the queue. */
+    enqueuedAt: number;
+    /** How many drain attempts this candidate has already survived. */
+    attempts: number;
+}
+/** Read-only projection of a session's queue state. Test/observability seam. */
+export interface QueueStats {
+    depth: number;
+    dropped: number;
+    llmCallsUsed: number;
+    tokensUsed: number;
+    retriesUsed: number;
+    lastDrainAt: number;
+    enqueuedSinceLastDrain: number;
+}
+export interface EnqueueResult {
+    /** False only when the candidate was rejected outright (invalid session id). */
+    enqueued: boolean;
+    /**
+     * Cumulative drop count for the session.
+     *
+     * There is deliberately no `depth` here. It was returned and read by nobody —
+     * not by `micro-reflector.ts`, not by `prm/index.ts` (both discard this whole
+     * value), and not by a test. The drain path that genuinely needs a depth
+     * already asks for it at the moment it drains, via `getQueueStats(...).depth`;
+     * a depth captured at enqueue time is stale by then. Reporting a number
+     * nothing consumes is unwired code (issue #1821).
+     */
+    dropped: number;
+    /** True when this enqueue evicted the oldest pending candidate. */
+    evictedOldest: boolean;
+}
+/** Injectable clock — tests pin time instead of sleeping. */
+export declare const _internals: {
+    now: () => number;
+};
+/**
+ * Enqueue one candidate for same-session admission.
+ *
+ * Drop-oldest (not drop-newest) on overflow: a flood of candidates is far more
+ * likely to be a repeating failure mode, and the NEWEST observation is the one
+ * most likely to reflect the agent's current state. The `dropped` counter makes
+ * the loss observable to `getQueueStats` rather than silent.
+ */
+export declare function enqueueCandidate(sessionID: string, candidate: InsightCandidate, limits: Pick<CandidateQueueLimits, 'maxQueueSize'>): EnqueueResult;
+/**
+ * Adaptive drain size (AC9). Pure: no module state is read, so it is unit
+ * testable in isolation.
+ *
+ *   size = ceil(minDrain + depthFactor * depth + velocityFactor * velocity)
+ *
+ * then clamped into `[minDrain, maxDrain]` and finally capped by the actual
+ * depth — a drain never claims more than exists. `ceil` (rather than `round`)
+ * biases marginally toward draining, because a candidate left in the queue is
+ * a lesson the current session cannot use yet.
+ *
+ * @param depth     Pending candidates in the queue.
+ * @param velocity  Arrivals per second since the last drain.
+ */
+export declare function computeDrainSize(depth: number, velocity: number, limits: DrainSizeLimits): number;
+declare function clampUnit(value: unknown): number;
+/**
+ * Arrivals per second since the session's last drain. Returns 0 for a session
+ * that has never been drained within the same millisecond as its first
+ * enqueue, so velocity can never be infinite.
+ */
+export declare function computeArrivalVelocity(stats: QueueStats, now: number): number;
+/**
+ * Remove and return up to `size` oldest candidates, marking the drain point.
+ * Resets the velocity numerator so the next cycle measures a fresh interval.
+ */
+export declare function takeDrainBatch(sessionID: string, size: number): QueuedCandidate[];
+/**
+ * Return an unfinished candidate to the FRONT of the queue so the next drain
+ * retries it before newer arrivals. Respects `maxQueueSize` by dropping the
+ * newest tail entry rather than the requeued item — the item already consumed
+ * budget, so discarding it would waste that spend.
+ */
+export declare function requeueCandidate(sessionID: string, item: QueuedCandidate, limits: Pick<CandidateQueueLimits, 'maxQueueSize'>): void;
+/** O(1) pending-work probe used by the hot-path drain adapter. */
+export declare function getQueueDepth(sessionID?: string): number;
+/**
+ * Reserve LLM budget for one admission call. Returns false when either the
+ * call ceiling or the token ceiling would be exceeded; the caller then admits
+ * without LLM assistance rather than failing the candidate.
+ */
+export declare function reserveLlmBudget(sessionID: string, estimatedTokens: number, limits: Pick<CandidateQueueLimits, 'maxLlmCallsPerSession' | 'maxTokensPerSession'>): boolean;
+/**
+ * Record that a retry was spent, returning the session's running total.
+ *
+ * The BOUND lives on the admission side, per candidate
+ * (`max_retries_per_candidate`); this counter is the session-wide observability
+ * view. Total retries per drain is therefore bounded by
+ * `max_retries_per_candidate * batchSize`, and `batchSize` is itself bounded by
+ * `max_drain`, so the product is bounded without a second cap here.
+ */
+export declare function recordRetry(sessionID: string): number;
+/** Read-only stats for a session. Returns a zeroed record for unknown ids. */
+export declare function getQueueStats(sessionID?: string): QueueStats;
+/** Drop one session's queue, or every session when `sessionID` is omitted. */
+export declare function resetSessionQueue(sessionID?: string): void;
+/** Number of distinct sessions currently tracked. Bound-eviction test seam. */
+declare function getTrackedSessionCount(): number;
+/**
+ * Tier-0 pure-function seam (see the writing-tests skill).
+ *
+ * `clampUnit` is defensive: `computeDrainSize` caps its result by the actual
+ * depth, so an un-clamped factor is not observable through the public function
+ * and could be deleted with the whole suite green. Exporting it here lets the
+ * clamp be asserted directly instead of being untestable dead defence.
+ *
+ * `MAX_TRACKED_SESSIONS` and `getTrackedSessionCount` live here for the same
+ * reason and were moved behind the seam by the issue #1821 dead-export pass: the
+ * eviction bound has no production reader and the count probe has no production
+ * caller, so as bare exports they were indistinguishable from public API.
+ */
+export declare const _test_exports: {
+    clampUnit: typeof clampUnit;
+    getTrackedSessionCount: typeof getTrackedSessionCount;
+    MAX_TRACKED_SESSIONS: number;
+};
+export {};

package/dist/learning/fingerprint.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Stable recommendation fingerprints (issue #1821, Lane 0a).
+ *
+ * The curator sweep, the skill improver, and the consensus miner all emit
+ * learning recommendations. Without a shared identity function the three
+ * producers happily re-propose the same lesson under three different ids and
+ * the knowledge store accumulates triplicates. `computeRecommendationFingerprint`
+ * gives every producer one canonical id so downstream dedup/supersede logic can
+ * compare recommendations across mechanisms.
+ *
+ * This module is intentionally pure: no filesystem, no network, no clock, no
+ * `process.cwd()`, no module-level mutable state (AGENTS.md invariants 1 and 8).
+ * The only dependency is the canonical JSON hasher shared with the evaluation
+ * subsystem, so a fingerprint computed in a hook matches one computed in a tool.
+ */
+/** Which learning mechanism produced a recommendation. */
+export type RecommendationKind = 'curator' | 'improver' | 'miner';
+export interface RecommendationFingerprintInput {
+    /** Producing mechanism. Two mechanisms proposing the same statement about the
+     * same target intentionally fingerprint differently — dedup across mechanisms
+     * is a policy decision made by the caller, not baked into the identity. */
+    kind: RecommendationKind;
+    /** What the recommendation is about (skill slug, knowledge id, file path, …). */
+    target: string;
+    /** The human-readable recommendation body. Normalized before hashing. */
+    statement: string;
+    /** Optional scope keys (e.g. `stableScopeKey` outputs). Order-insensitive. */
+    scopeKeys?: string[];
+}
+/**
+ * Normalize a recommendation statement for identity purposes.
+ *
+ * Mirrors `normalizeMemoryText` in `src/memory/schema.ts` (whitespace-run
+ * collapse + trim) and the `.toLowerCase()` that `computeMemoryContentHash`
+ * applies on top of it, then additionally strips trailing sentence punctuation
+ * so "Prefer DI over mock.module." and "prefer DI over mock.module" collapse to
+ * one identity.
+ */
+export declare function normalizeRecommendationStatement(statement: string): string;
+/**
+ * Deduplicate and sort scope keys so caller-side ordering can never change the
+ * fingerprint. Empty/whitespace-only keys are dropped: they carry no scope
+ * information and would otherwise split identity for two equivalent inputs.
+ */
+export declare function normalizeScopeKeys(scopeKeys?: string[]): string[];
+/**
+ * Compute the stable fingerprint for a learning recommendation.
+ *
+ * Returns `lrec_` followed by the first 16 hex characters of the canonical
+ * sha256 of `{ kind, target, normalizedStatement, sortedScopeKeys }`. Because
+ * `canonicalHash` sorts object keys, the shape of the input literal cannot
+ * change the result.
+ */
+export declare function computeRecommendationFingerprint(input: RecommendationFingerprintInput): string;
+/** Shape check for a value that claims to be a recommendation fingerprint. */
+export declare function isRecommendationFingerprint(value: string): boolean;

package/dist/learning/prm-pattern-support.d.ts

@@ -0,0 +1,124 @@
+/**
+ * PRM pattern persistence support tracking (issue #1821, AC10).
+ *
+ * PRM already detects recurring failure patterns (repetition loops, ping-pong,
+ * context thrash, …) and injects a course correction. Those detections were
+ * purely ephemeral: the same crew rediscovered the same pattern next session.
+ * This module decides WHEN a detected pattern has earned a durable knowledge
+ * entry, and turns it into an insight candidate for the normal bounded
+ * admission path.
+ *
+ * Three properties matter, and each one is a defence against a specific way
+ * this could go wrong:
+ *
+ * 1. **Identity** is `pattern|sortedAgents|sortedTargets`. Two different
+ *    repetition loops in different files are different lessons.
+ * 2. **Support counts DISTINCT OCCURRENCE STARTS.** PRM re-reports a live
+ *    pattern on every subsequent tool call, and `pattern-detector.ts` emits
+ *    `stepRange: [startStep, endStep]` with an ADVANCING `endStep` — so
+ *    [1,2], [1,3], [1,4] are all the SAME incident. Counting whole ranges would
+ *    let one continuous loop self-confirm to the threshold in seconds, so
+ *    support is keyed on `stepRange[0]` instead.
+ * 3. **Evidence is POINTERS ONLY** — `prm:<sid>:<pattern>:<start>-<end>`.
+ *    Transcript text and model reasoning are NEVER copied into a durable
+ *    record; a knowledge entry is shared across sessions and must not carry
+ *    another session's content.
+ *
+ * Module state follows the same bounded shape as `./candidate-queue.ts`: FIFO
+ * key eviction at `MAX_TRACKED_SESSIONS` plus a per-session identity cap
+ * (AGENTS.md invariant 8). No I/O happens here — this runs on the PRM
+ * `toolAfter` hot path.
+ */
+import type { InsightCandidate } from '../hooks/micro-reflector.js';
+import type { PatternMatch } from '../prm/types.js';
+/** Tuning knobs, mirroring `learning.prm_persistence`. */
+export interface PrmSupportLimits {
+    /** Distinct observations required before a pattern is persistable. */
+    minSupport: number;
+    /** Cooldown between persists for one identity, in milliseconds. */
+    cooldownMs: number;
+}
+export interface PrmObservationResult {
+    identity: string;
+    /** Number of DISTINCT occurrence starts observed for this identity. */
+    support: number;
+    /** True when support met the threshold AND the cooldown has elapsed. */
+    persistable: boolean;
+    /** Why `persistable` is false. Absent when it is true. */
+    reason?: 'below_support' | 'cooling_down' | 'unactionable';
+    /** Bounded evidence pointers. Never contains transcript or reasoning text. */
+    evidenceRefs: string[];
+    /** Present only when `persistable` — ready for `enqueueCandidate`. */
+    candidate?: InsightCandidate;
+}
+/** Injectable clock — tests pin time instead of sleeping. */
+export declare const _internals: {
+    now: () => number;
+};
+/**
+ * Stable identity for a detected pattern.
+ *
+ * Agents and targets are sorted so detection order cannot mint a second
+ * identity for the same underlying situation.
+ */
+declare function computePatternIdentity(match: Pick<PatternMatch, 'pattern' | 'affectedAgents' | 'affectedTargets'>): string;
+/**
+ * Build ONE evidence pointer. Deliberately carries only the session id, the
+ * pattern name, and the step window — enough to re-derive the evidence from
+ * that session's own trajectory, and nothing that leaks its content.
+ */
+declare function buildPrmEvidenceRef(sessionID: string, pattern: string, stepRange: [number, number]): string;
+/**
+ * Build the durable lesson for a supported pattern.
+ *
+ * Returns undefined when the pattern yields no usable scope — an entry with no
+ * `applies_to_agents` / `applies_to_tools` fails the Layer-5 actionability gate
+ * and would only be quarantined, so it is better not to emit it at all.
+ */
+declare function buildPrmPatternCandidate(match: PatternMatch, evidenceRefs: string[], createdAt: string): InsightCandidate | undefined;
+/**
+ * Record one PRM pattern detection and report whether it now warrants a durable
+ * knowledge entry.
+ *
+ * MUST be called only after PRM's `matches.length === 0` early return, so the
+ * overwhelmingly common no-match path costs nothing.
+ */
+export declare function recordPatternObservation(sessionID: string, match: PatternMatch, limits: PrmSupportLimits): PrmObservationResult;
+/** Read-only support view for one identity. Test/observability seam. */
+declare function getPatternSupport(sessionID: string, identity: string): {
+    support: number;
+    lastPersistedAt: number;
+    occurrenceStarts: number[];
+};
+/** Drop one session's support state, or every session when omitted. */
+export declare function resetPrmPatternSupport(sessionID?: string): void;
+/** Number of distinct sessions tracked. Bound-eviction test seam. */
+declare function getTrackedPrmSessionCount(): number;
+/** Number of distinct identities tracked for a session. */
+declare function getTrackedPrmIdentityCount(sessionID: string): number;
+/**
+ * Tier-0 pure-function and observability seam (see the writing-tests skill, and
+ * the sibling seam in `candidate-queue.ts`).
+ *
+ * Everything here was a bare `export` with no importer outside the tests — the
+ * three caps, the three pure builders, and the three read-only probes. The issue
+ * #1821 dead-export pass moved them behind this seam rather than deleting them:
+ * each is genuinely needed to assert a bound or a pure mapping that the public
+ * `recordPatternObservation` path only exercises indirectly, but as bare exports
+ * they were indistinguishable from public API and read as unwired code.
+ *
+ * `_internals` stays separate and stays small: it is the DI seam tests
+ * SUBSTITUTE (the clock). Nothing below is substitutable.
+ */
+export declare const _test_exports: {
+    buildPrmEvidenceRef: typeof buildPrmEvidenceRef;
+    buildPrmPatternCandidate: typeof buildPrmPatternCandidate;
+    computePatternIdentity: typeof computePatternIdentity;
+    getPatternSupport: typeof getPatternSupport;
+    getTrackedPrmIdentityCount: typeof getTrackedPrmIdentityCount;
+    getTrackedPrmSessionCount: typeof getTrackedPrmSessionCount;
+    MAX_IDENTITIES_PER_SESSION: number;
+    MAX_OCCURRENCES_PER_IDENTITY: number;
+    MAX_TRACKED_SESSIONS: number;
+};
+export {};