opencode-swarm 7.130.2 → 7.131.0

package/dist/learning/provenance.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Learning provenance records (issue #1821, Lane 0a).
+ *
+ * Every durable learning write — a curator sweep decision, a micro-reflection,
+ * a PRM pattern, a consensus-mined lesson, a skill-improver edit — must be able
+ * to say *where it came from*. `LearningProvenanceV1` is the shared envelope:
+ * which mechanism produced it, which knowledge/task/evidence/run/model ids fed
+ * it, and which session/agent physically wrote it.
+ *
+ * Every reference class is deduplicated, sorted, and hard-capped at
+ * `MAX_REFS_PER_CLASS` so a long-running session cannot grow a provenance record
+ * without bound (AGENTS.md invariant 8 — global/persisted state must be
+ * bounded).
+ *
+ * This module is pure: no filesystem, no network, no module-level mutable state.
+ * The only ambient input is the wall clock, and only when the caller does not
+ * supply `producedAt` — callers that need determinism pass it explicitly.
+ */
+import { z } from 'zod';
+/**
+ * Hard cap on entries retained per reference class. Sorting happens before the
+ * cap so truncation is deterministic rather than insertion-order dependent.
+ */
+export declare const MAX_REFS_PER_CLASS = 50;
+/** The learning mechanism that produced a record. */
+export type LearningMechanism = 'curator_sweep' | 'micro_reflection' | 'prm_pattern' | 'consensus_mine' | 'skill_improver';
+export declare const LearningProvenanceV1Schema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    mechanism: z.ZodEnum<{
+        skill_improver: "skill_improver";
+        consensus_mine: "consensus_mine";
+        curator_sweep: "curator_sweep";
+        micro_reflection: "micro_reflection";
+        prm_pattern: "prm_pattern";
+    }>;
+    sourceKnowledgeIds: z.ZodArray<z.ZodString>;
+    sourceTaskIds: z.ZodArray<z.ZodString>;
+    sourceEvidenceRefs: z.ZodArray<z.ZodString>;
+    sourceRunIds: z.ZodArray<z.ZodString>;
+    sourceModelIds: z.ZodArray<z.ZodString>;
+    writeOrigin: z.ZodObject<{
+        sessionId: z.ZodOptional<z.ZodString>;
+        agentRole: z.ZodOptional<z.ZodString>;
+        producedAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export interface LearningProvenanceV1 {
+    v: 1;
+    mechanism: LearningMechanism;
+    sourceKnowledgeIds: string[];
+    sourceTaskIds: string[];
+    sourceEvidenceRefs: string[];
+    sourceRunIds: string[];
+    sourceModelIds: string[];
+    /** See `LearningWriteOriginSchema` for why there is no `agentId` here. */
+    writeOrigin: {
+        sessionId?: string;
+        agentRole?: string;
+        producedAt: string;
+    };
+}
+/** Caller-supplied provenance body. Every reference class is optional. */
+export interface LearningProvenanceInput {
+    mechanism: LearningMechanism;
+    sourceKnowledgeIds?: string[];
+    sourceTaskIds?: string[];
+    sourceEvidenceRefs?: string[];
+    sourceRunIds?: string[];
+    sourceModelIds?: string[];
+}
+/** Caller-supplied write origin. `producedAt` defaults to now when omitted. */
+export interface LearningWriteOriginInput {
+    sessionId?: string;
+    agentRole?: string;
+    producedAt?: string;
+}
+/**
+ * Build a validated `LearningProvenanceV1` from a partial body and a write
+ * origin. Fills `v`, missing reference classes, and `producedAt`; deduplicates,
+ * sorts, and caps every reference class; then parses through
+ * `LearningProvenanceV1Schema` so the returned value is guaranteed valid.
+ *
+ * Throws (via Zod) on an unknown mechanism or an unparseable `producedAt` —
+ * a malformed provenance record must never be persisted silently.
+ */
+export declare function stampLearningProvenance(partial: LearningProvenanceInput, origin?: LearningWriteOriginInput): LearningProvenanceV1;

package/dist/prm/index.d.ts

@@ -16,6 +16,10 @@ export { formatCourseCorrectionForInjection, generateCourseCorrection, } from '.
 export { createDefaultEscalationState, EscalationTracker } from './escalation';
 export { detectContextThrash, detectExpansionDrift, detectPatterns, detectPingPong, detectRepetitionLoop, detectStuckOnTest, } from './pattern-detector';
 export type { CourseCorrection, EscalationState, PatternDetectionResult, PatternMatch, PatternSeverity, PatternType, PrmConfig, TaxonomyCategory, TrajectoryEntry, } from './types';
+import type { LearningConfig } from '../config/schema.js';
+import { appendInsightCandidates } from '../hooks/micro-reflector.js';
+import { enqueueCandidate } from '../learning/candidate-queue.js';
+import { recordPatternObservation } from '../learning/prm-pattern-support.js';
 import { getAgentSession } from '../state';
 import { telemetry } from '../telemetry';
 import { formatCourseCorrectionForInjection, generateCourseCorrection } from './course-correction';
@@ -44,6 +48,9 @@ export declare const _internals: {
     recordReplayEntry: typeof recordReplayEntry;
     startReplayRecording: typeof startReplayRecording;
     telemetry: typeof telemetry;
+    recordPatternObservation: typeof recordPatternObservation;
+    enqueueCandidate: typeof enqueueCandidate;
+    appendInsightCandidates: typeof appendInsightCandidates;
 };
 /**
  * Context passed to toolAfter handler
@@ -94,4 +101,42 @@ export declare function resetPrmSessionState(session: ResettablePrmSessionState,
  * // Wire prmHook.toolAfter into your tool.execute.after hook
  * ```
  */
-export declare function createPrmHook(config: PrmConfig, directory: string): PrmHook;
+/**
+ * Knobs the PRM hook needs to hand supported patterns to the real-time
+ * admission queue (issue #1821, AC10). Optional so existing callers and tests
+ * keep working unchanged; when absent, pattern persistence is simply off.
+ */
+export interface PrmPatternPersistenceOptions {
+    /**
+     * `learning.prm_persistence.enabled`. Governs the WHOLE producer, durable
+     * append included.
+     */
+    enabled: boolean;
+    min_support: number;
+    cooldown_ms: number;
+    /**
+     * `learning.realtime_admission.enabled`. Governs ONLY the in-memory enqueue.
+     *
+     * It must never gate the durable append (issue #1821 F3): AC8 says disabled
+     * or crashed real-time work loses nothing, and the phase-boundary backstop
+     * can only see candidates that reached `.swarm/insight-candidates.jsonl`.
+     * ANDing the two flags at the call site made `realtime_admission.enabled=false`
+     * silently discard every PRM candidate. Mirrors `micro-reflector.ts`, which
+     * appends unconditionally and gates only its enqueue.
+     */
+    admission_enabled: boolean;
+    /** `learning.realtime_admission.max_queue_size` — bounds the shared queue. */
+    max_queue_size: number;
+}
+/**
+ * Map a parsed `learning` config onto the PRM producer's knobs (issue #1821 F3).
+ *
+ * The mapping lives here, beside the interface that documents which flag governs
+ * what, and `src/index.ts` is its only production caller — so the AC8 coupling
+ * ("durable persistence is gated by `prm_persistence.enabled` ALONE") is
+ * expressed once and can be asserted directly by a test instead of being
+ * re-derived from an object literal at the plugin's wiring site, where the two
+ * flags were previously ANDed together.
+ */
+export declare function resolvePrmPatternPersistenceOptions(learning: LearningConfig): PrmPatternPersistenceOptions;
+export declare function createPrmHook(config: PrmConfig, directory: string, patternPersistence?: PrmPatternPersistenceOptions): PrmHook;

package/dist/services/recommendation-ledger.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Cross-producer recommendation dedup ledger (issue #1821, AC21).
+ *
+ * Three mechanisms propose learning recommendations: the curator sweep
+ * (`src/hooks/curator.ts`), the skill improver's macro-reflector
+ * (`src/services/trajectory-cluster.ts`), and the consensus miner
+ * (`src/consensus/miner.ts`). `src/learning/fingerprint.ts` gave them a shared
+ * identity function, but a fingerprint alone dedups nothing: somebody has to
+ * remember what was already emitted. This module is that memory.
+ *
+ * ## Why a second key
+ *
+ * `computeRecommendationFingerprint` deliberately folds `kind` into the digest —
+ * its own doc says "dedup across mechanisms is a policy decision made by the
+ * caller, not baked into the identity". This module *is* that caller, and the
+ * policy it implements is: **two recommendations are the same recommendation
+ * when they say the same thing about the same scope, regardless of which
+ * mechanism noticed it first.** So every ledger entry carries two ids:
+ *
+ * - `fingerprint` — the producer-scoped `lrec_…` id, kept verbatim for audit.
+ * - `crossKey` — an `lxk_…` id over `{ normalizedStatement, sortedScopeKeys }`.
+ *
+ * `crossKey` drops both `kind` and `target`. Dropping `kind` is the whole point.
+ * Dropping `target` is a redundancy call, not a necessity: each producer already
+ * interpolates its target into the statement it emits (the miner's `intent`
+ * names its `proposedTarget`; the improver's statement names the tool and
+ * failure kind its slug is built from; the curator's `entry_id` travels in
+ * `scopeKeys`), so keeping `target` would add no discriminating power while
+ * splitting identity on producer-local vocabulary.
+ *
+ * Disambiguation that genuinely must survive therefore travels in `scopeKeys`,
+ * which is order- and duplicate-insensitive (`normalizeScopeKeys`). The curator
+ * uses that to keep `archive entry-X` and `rewrite entry-X` distinct even when
+ * both carry the same lesson text; recommendations that mint *new* knowledge
+ * carry no scope keys, because content alone is their identity.
+ *
+ * ## What this does and does not achieve today
+ *
+ * The key is an EXACT hash of normalized text. Two producers dedup against each
+ * other only when they emit the same sentence. In the current codebase the
+ * improver and the miner build their statements from fixed templates
+ * (`Avoid the recurring … failure in …`, `Investigate the smallest … change …`)
+ * while the curator's statement is a free-form LLM lesson, so a cross-producer
+ * collision is possible but uncommon. The concrete, everyday win is therefore:
+ * (a) WITHIN-producer dedup, which the curator and the improver had none of, and
+ * (b) one shared, provenance-stamped record of every emitted recommendation that
+ * any producer can consult. Making cross-producer suppression routine would need
+ * near-duplicate matching (see `findNearDuplicate` / the knowledge dedup sweep)
+ * rather than an exact fingerprint, which is a different mechanism than the one
+ * `src/learning/fingerprint.ts` defines.
+ *
+ * ## Check, emit, then record — never "reserve"
+ *
+ * The two phases are deliberately separate:
+ *
+ * - `checkRecommendations` is read-only. It answers "has this been emitted
+ *   before?" and writes nothing.
+ * - `recordEmittedRecommendations` is the locked write, and callers run it only
+ *   for recommendations that **actually took effect**.
+ *
+ * An earlier design claimed the key up-front, before the caller emitted. That is
+ * wrong here: the curator legitimately *defers* recommendations (cohort-safe
+ * authorization not yet granted, target entry temporarily inactive, CAS revision
+ * drift, fair-scan generation already curated, actionability quarantine pending
+ * the hardening loop). Every one of those paths expects a later sweep to retry,
+ * and a key claimed before the emit would suppress that retry permanently.
+ * Recording after the fact costs a small race — two producers can both pass
+ * `check` and both emit — whose worst case is one duplicate, exactly the
+ * pre-#1821 behaviour. A burned key, by contrast, loses a lesson forever. The
+ * record step re-checks under the lock, so the ledger itself never grows a
+ * duplicate.
+ *
+ * ## Boundedness and containment
+ *
+ * The ledger is a JSONL file at `.swarm/learning/recommendation-ledger.jsonl`,
+ * hard-capped at `MAX_RECOMMENDATION_LEDGER_ENTRIES` entries with oldest-first
+ * FIFO eviction, and every entry is capped at `MAX_ENTRY_BYTES` (provenance is
+ * dropped rather than allowed to blow the bound), so the file has a hard ceiling
+ * of roughly 2 MB (AGENTS.md invariant 8). It never touches `process.cwd()`
+ * (invariant 4). Its own subdirectory is deliberate: `transactFile` locks the
+ * *containing directory*, so living under `learning/` keeps this lock disjoint
+ * from the `.swarm/` root lock that `transactKnowledge` takes.
+ *
+ * The root is `resolveKnowledgeStoreDir`, NOT a hardcoded `<directory>/.swarm`.
+ * That is the same link-aware resolution `resolveSwarmKnowledgePath` uses, so in
+ * a linked cohort the ledger lives beside the knowledge store it guards instead
+ * of being stranded per-worktree — a lane worktree would otherwise discard its
+ * ledger while the lessons it recorded persisted in the shared store.
+ *
+ * Eviction means a recommendation older than the last 500 emissions can surface
+ * again. That is the intended trade: bounded state beats perfect recall. Note
+ * this cap is independent of `knowledge.swarm_max_entries` (default 100): a
+ * lesson the knowledge store has already FIFO-evicted can still be suppressed
+ * here until its own entry ages out.
+ *
+ * ## Fail-open
+ *
+ * Every failure mode — unreadable ledger, lock timeout, corrupt lines, a
+ * provenance record the schema rejects — resolves to "emit everything", i.e.
+ * exactly the behaviour that existed before this module. A broken dedup ledger
+ * must never silence the learning loops.
+ */
+import { transactFile } from '../hooks/knowledge-store.js';
+import { type RecommendationKind } from '../learning/fingerprint.js';
+import { type LearningProvenanceInput, type LearningProvenanceV1, type LearningWriteOriginInput } from '../learning/provenance.js';
+/**
+ * Hard cap on retained ledger entries (AGENTS.md invariant 8). Sized to match
+ * `INSIGHT_CANDIDATES_MAX_ENTRIES` in `src/hooks/micro-reflector.ts`, the
+ * closest sibling queue: the same order of magnitude of learning artifacts flows
+ * through both, and one shared number is easier to reason about than two.
+ */
+export declare const MAX_RECOMMENDATION_LEDGER_ENTRIES = 500;
+/**
+ * Hard cap on one serialized entry. Provenance reference lists are individually
+ * bounded by `stampLearningProvenance`, but 5 classes x 50 refs x 512 chars is
+ * still ~128 KB, which would put the file's ceiling in the tens of megabytes.
+ * An entry over this budget keeps its identity fields and drops provenance —
+ * dedup is the contract, provenance is the bonus.
+ */
+export declare const MAX_ENTRY_BYTES = 4096;
+/** A recommendation a producer is about to emit, or has just emitted. */
+export interface RecommendationCandidate {
+    /** Producing mechanism. Recorded on the entry; excluded from `crossKey`. */
+    kind: RecommendationKind;
+    /** Producer-local target (knowledge id, proposal slug, subsystem name). */
+    target: string;
+    /** The recommendation body. Normalized before hashing. */
+    statement: string;
+    /** Scope disambiguators. Order- and duplicate-insensitive. */
+    scopeKeys?: string[];
+    /** Learning provenance stamped onto the ledger entry when recorded. */
+    provenance?: LearningProvenanceInput;
+    /** Write origin for the provenance stamp. */
+    origin?: LearningWriteOriginInput;
+}
+/** The two ids a candidate resolves to. */
+export interface RecommendationIdentity {
+    /** Producer-scoped `lrec_…` id from `src/learning/fingerprint.ts`. */
+    fingerprint: string;
+    /** Kind- and target-independent `lxk_…` id used for dedup. */
+    crossKey: string;
+}
+/** One durable record of an emitted recommendation. */
+export interface RecommendationLedgerEntry extends RecommendationIdentity {
+    v: 1;
+    kind: RecommendationKind;
+    target: string;
+    /** ISO-8601 timestamp of the record call that appended this entry. */
+    emittedAt: string;
+    provenance?: LearningProvenanceV1;
+}
+/**
+ * Why a candidate was not accepted for emission.
+ *
+ * Module-private: consumers reach this set through
+ * `RecommendationDecision['suppressedBy']`, which is exported and narrows to the
+ * same two literals. Exporting the alias as well gave it a name no importer ever
+ * used.
+ */
+type RecommendationSuppressionSource = 'ledger' | 'batch';
+/** Per-candidate outcome, in input order. */
+export interface RecommendationDecision extends RecommendationIdentity {
+    /** Index into the candidate array this decision belongs to. */
+    index: number;
+    /** True when the caller should emit this recommendation. */
+    emit: boolean;
+    /**
+     * `'ledger'` — a previous emission (possibly by another producer) already
+     * claimed this `crossKey`. `'batch'` — an earlier candidate in this same call
+     * claimed it. Absent when `emit` is true.
+     */
+    suppressedBy?: RecommendationSuppressionSource;
+}
+export interface CheckRecommendationsResult {
+    decisions: RecommendationDecision[];
+    /** Count of `emit === true` decisions. */
+    accepted: number;
+    /** Count of `emit === false` decisions. */
+    suppressed: number;
+    /**
+     * True when the ledger could not be read and every candidate was accepted by
+     * fail-open default rather than by an actual dedup check.
+     */
+    degraded: boolean;
+}
+export interface RecordRecommendationsResult {
+    /** Entries actually appended. */
+    recorded: number;
+    /** Candidates skipped because the ledger already carried their cross key. */
+    suppressed: number;
+    /** Entries dropped by the FIFO cap during this record. */
+    evicted: number;
+    /** True when the ledger could not be written. */
+    degraded: boolean;
+}
+/**
+ * Absolute path of the ledger, link-aware.
+ *
+ * Byte-identical to `<directory>/.swarm/learning/recommendation-ledger.jsonl`
+ * for an unlinked worktree; redirects to the shared cohort store when
+ * `.swarm/link.json` is active, exactly as `resolveSwarmKnowledgePath` does for
+ * the knowledge file this ledger shadows.
+ */
+export declare function resolveRecommendationLedgerPath(directory: string): string;
+/** Shape check for a value that claims to be a cross-producer key. */
+export declare function isRecommendationCrossKey(value: string): boolean;
+/**
+ * Compute the kind- and target-independent dedup key.
+ *
+ * Built from the same normalizers the `lrec_` fingerprint uses, so whitespace
+ * runs, surrounding space, letter case, trailing sentence punctuation, scope-key
+ * order, and scope-key duplicates all collapse to one identity.
+ */
+export declare function computeCrossProducerKey(input: {
+    statement: string;
+    scopeKeys?: string[];
+}): string;
+/** Compute both ids for a candidate. Pure. */
+export declare function computeRecommendationIdentity(candidate: RecommendationCandidate): RecommendationIdentity;
+/**
+ * Read every retained ledger entry, propagating a real read failure.
+ *
+ * A missing ledger is the first-run case and yields `[]`; anything else throws
+ * so `checkRecommendations` can report `degraded` truthfully instead of treating
+ * an unreadable ledger as an empty one and silently claiming it deduped.
+ */
+declare function readLedgerStrict(directory: string): Promise<RecommendationLedgerEntry[]>;
+/**
+ * Read every retained ledger entry. Fail-open: returns `[]` when the ledger is
+ * absent or unreadable. This is the inspection entry point — the dedup decision
+ * itself goes through `readLedgerStrict` so a failure is visible rather than
+ * disguised as an empty ledger.
+ */
+export declare function readRecommendationLedger(directory: string): Promise<RecommendationLedgerEntry[]>;
+/**
+ * Answer "has this been emitted before?" without writing anything.
+ *
+ * Suppression is decided against the ledger's existing cross keys plus the keys
+ * claimed by earlier candidates in this same batch. Fail-open: an unreadable
+ * ledger yields `degraded: true` and accepts everything.
+ */
+export declare function checkRecommendations(directory: string, candidates: readonly RecommendationCandidate[]): Promise<CheckRecommendationsResult>;
+/**
+ * Append the recommendations a producer actually emitted.
+ *
+ * Runs one locked read-modify-write and re-checks every cross key under that
+ * lock, so a candidate another producer recorded between `checkRecommendations`
+ * and here is counted as `suppressed` rather than duplicated into the ledger.
+ * Candidates whose statement normalizes to nothing are never recorded.
+ */
+export declare function recordEmittedRecommendations(directory: string, candidates: readonly RecommendationCandidate[], options?: {
+    producedAt?: string;
+}): Promise<RecordRecommendationsResult>;
+/**
+ * DI seam (AGENTS.md invariant 7). `now` lets tests pin `emittedAt`;
+ * `transactFile`, `readRecommendationLedger`, and
+ * `resolveRecommendationLedgerPath` let them exercise the fail-open paths
+ * without `mock.module`. Restore each entry in `afterEach`.
+ */
+export declare const _internals: {
+    now: () => Date;
+    transactFile: typeof transactFile;
+    readLedgerStrict: typeof readLedgerStrict;
+    resolveRecommendationLedgerPath: typeof resolveRecommendationLedgerPath;
+};
+export {};

package/dist/services/skill-improver.d.ts

@@ -83,11 +83,15 @@ export interface SkillImproveResult {
     macroMotifs?: {
         motifs: number;
         proposalsWritten: number;
+        /** #1821 AC21: motifs suppressed by the cross-producer dedup ledger. */
+        duplicatesSuppressed?: number;
     };
     /** #1234 Part 4: success workflow-motif proposals written this run. */
     successMotifs?: {
         motifs: number;
         proposalsWritten: number;
+        /** #1821 AC21: motifs suppressed by the cross-producer dedup ledger. */
+        duplicatesSuppressed?: number;
     };
     /** Issue #1477: self-healing reconciliation of stale active generated skills
      *  (regenerate-or-retire). In proposal-only runs this is a dry run (the

package/dist/services/status-service.d.ts

@@ -78,6 +78,19 @@ export interface StatusData {
     unactionableQueueDepth?: number;
     /** #1234 Part 3: pending insight candidates awaiting phase boundary consumption */
     insightCandidatesPending?: number;
+    /**
+     * #1821 AC22: consensus report FILES stored under
+     * `.swarm/evolution/consensus/`.
+     *
+     * The reader half of the consensus store. Without it the miner's reports were
+     * a write-only directory — nothing in the product enumerated them, so a user
+     * had no way to learn they existed. A file count, deliberately: it is one
+     * `readdir` with no JSON parse and no integrity recomputation, so it costs the
+     * same whether the store holds one report or fifty. It therefore includes any
+     * corrupt report, because what it counts is files whose name is a well-formed
+     * report id.
+     */
+    consensusReports?: number;
     /**
      * Cohort/link status (issue #1846). Makes the linked knowledge store and its
      * health obvious in `/swarm status`. `undefined` when link state is absent.

package/dist/services/trajectory-cluster.d.ts

@@ -16,6 +16,7 @@
  * Read-only over the knowledge store; writes only proposal markdown (never
  * active skills). Fail-open.
  */
+import { checkRecommendations, recordEmittedRecommendations } from './recommendation-ledger.js';
 /** Trajectories scanned per macro pass (the plan's N=200 window). */
 export declare const MACRO_TRAJECTORY_WINDOW = 200;
 /** A motif must recur across at least this many distinct tasks to propose. */
@@ -36,11 +37,31 @@ export declare function gatherFailureMotifs(directory: string, opts?: {
     window?: number;
     minTasks?: number;
 }): Promise<FailureMotif[]>;
+/**
+ * The recommendation a failure motif asserts, in cross-producer form
+ * (issue #1821 AC21).
+ *
+ * The agent role is folded into the *statement* rather than carried as a scope
+ * key so this statement can collide with an equivalent lesson proposed by the
+ * curator or the consensus miner — the whole point of a shared identity. The
+ * motif signature's constituents (tool, failure kind) are what actually vary
+ * between motifs, so two distinct motifs never produce the same statement.
+ */
+declare function motifStatement(motif: FailureMotif): string;
 /** Render a draft SKILL.md proposal body for a motif (with full provenance). */
-export declare function buildMotifProposal(motif: FailureMotif): string;
+export declare function buildMotifProposal(motif: FailureMotif, options?: {
+    fingerprint?: string;
+    producedAt?: string;
+}): string;
 export interface MotifProposalResult {
     motifs: number;
     proposalsWritten: string[];
+    /**
+     * #1821 AC21: motifs whose recommendation was already emitted — by an earlier
+     * improver run, the curator sweep, or the consensus miner — and were therefore
+     * not re-proposed.
+     */
+    duplicatesSuppressed: number;
 }
 /**
  * Run the macro motif pass and write one proposal per recurring motif. Returns
@@ -50,6 +71,8 @@ export declare function writeMotifProposals(directory: string, opts?: {
     window?: number;
     minTasks?: number;
     maxProposals?: number;
+    /** Recorded in the ledger entry's provenance write origin. */
+    sessionId?: string;
 }): Promise<MotifProposalResult>;
 /** Minimum number of steps in a trajectory for it to qualify as a workflow. */
 export declare const SUCCESS_SEQUENCE_MIN_STEPS = 3;
@@ -66,16 +89,56 @@ export interface SuccessMotif {
 export interface SuccessMotifProposalResult {
     motifs: number;
     proposalsWritten: string[];
+    /** #1821 AC21: see `MotifProposalResult.duplicatesSuppressed`. */
+    duplicatesSuppressed: number;
 }
 export declare function gatherSuccessMotifs(directory: string, opts?: {
     window?: number;
     minTasks?: number;
     minSteps?: number;
 }): Promise<SuccessMotif[]>;
-export declare function buildWorkflowProposal(motif: SuccessMotif): string;
+/**
+ * The recommendation a success motif asserts, in cross-producer form
+ * (issue #1821 AC21). Same agent-in-statement rationale as `motifStatement`.
+ *
+ * The rendered sequence MUST mirror `sequenceSignature` (`tool:action` per
+ * step), not just the tool names: two motifs that share a tool chain but differ
+ * in actions have different signatures, different slugs, and different proposal
+ * files, so a tool-only statement would collapse two genuinely different
+ * workflows onto one cross key and suppress the second.
+ */
+declare function workflowStatement(motif: SuccessMotif): string;
+export declare function buildWorkflowProposal(motif: SuccessMotif, options?: {
+    fingerprint?: string;
+    producedAt?: string;
+}): string;
 export declare function writeSuccessMotifProposals(directory: string, opts?: {
     window?: number;
     minTasks?: number;
     minSteps?: number;
     maxProposals?: number;
+    /** Recorded in the ledger entry's provenance write origin. */
+    sessionId?: string;
 }): Promise<SuccessMotifProposalResult>;
+/**
+ * DI seam (AGENTS.md invariant 7). `now` pins the shared `producedAt` that the
+ * ledger entry and the proposal frontmatter both carry; the two ledger functions
+ * let a test exercise the suppressed / degraded branches without touching the
+ * real ledger. Restore each entry in `afterEach`.
+ */
+export declare const _internals: {
+    now: () => Date;
+    checkRecommendations: typeof checkRecommendations;
+    recordEmittedRecommendations: typeof recordEmittedRecommendations;
+};
+/**
+ * Pure-function seam for tests (writing-tests SKILL.md, Tier 0). The two
+ * statement builders define the cross-producer identity of a motif, so a test
+ * asserting cross-producer suppression must derive the competing statement from
+ * them rather than hardcode a copy that can silently drift.
+ */
+export declare const _test_exports: {
+    motifStatement: typeof motifStatement;
+    workflowStatement: typeof workflowStatement;
+};
+export {};