agentsmesh 0.21.0 → 0.23.0

package/dist/init-YKxF2zpQ.d.ts

@@ -0,0 +1,494 @@
+import { z } from 'zod';
+
+declare const TopicSchema: z.ZodObject<{
+    summary: z.ZodString;
+}, z.core.$strict>;
+declare const TriggerKindSchema: z.ZodEnum<{
+    file_glob: "file_glob";
+    command_pattern: "command_pattern";
+    keyword: "keyword";
+}>;
+declare const TriggerSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        file_glob: "file_glob";
+        command_pattern: "command_pattern";
+        keyword: "keyword";
+    }>;
+    pattern: z.ZodString;
+}, z.core.$strict>;
+declare const LessonStatusSchema: z.ZodEnum<{
+    active: "active";
+    deprecated: "deprecated";
+    superseded: "superseded";
+}>;
+declare const LessonSchema: z.ZodObject<{
+    rule: z.ZodString;
+    rationale: z.ZodOptional<z.ZodString>;
+    topics: z.ZodArray<z.ZodString>;
+    triggers: z.ZodArray<z.ZodString>;
+    evidence: z.ZodArray<z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        deprecated: "deprecated";
+        superseded: "superseded";
+    }>;
+    supersededBy: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+declare const LessonsGraphSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    lessons: z.ZodRecord<z.ZodString, z.ZodObject<{
+        rule: z.ZodString;
+        rationale: z.ZodOptional<z.ZodString>;
+        topics: z.ZodArray<z.ZodString>;
+        triggers: z.ZodArray<z.ZodString>;
+        evidence: z.ZodArray<z.ZodString>;
+        status: z.ZodEnum<{
+            active: "active";
+            deprecated: "deprecated";
+            superseded: "superseded";
+        }>;
+        supersededBy: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+    topics: z.ZodRecord<z.ZodString, z.ZodObject<{
+        summary: z.ZodString;
+    }, z.core.$strict>>;
+    triggers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            file_glob: "file_glob";
+            command_pattern: "command_pattern";
+            keyword: "keyword";
+        }>;
+        pattern: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type LessonsGraph = z.infer<typeof LessonsGraphSchema>;
+type Lesson = z.infer<typeof LessonSchema>;
+type Topic = z.infer<typeof TopicSchema>;
+type Trigger = z.infer<typeof TriggerSchema>;
+type TriggerKind = z.infer<typeof TriggerKindSchema>;
+type LessonStatus = z.infer<typeof LessonStatusSchema>;
+declare function parseGraph(raw: unknown): LessonsGraph;
+
+interface AutoPruneSummary {
+    readonly removedTriggers: number;
+    readonly removedTopics: number;
+    readonly detachedDeadGlobs: number;
+}
+
+/**
+ * Capture guardrails — mostly WARNINGS, steering authors toward a few specific
+ * triggers. Over-triggering (too many triggers per lesson, broad globs,
+ * keyword-only triggers that fire less reliably on the mandatory `--file`/`--cmd`
+ * path, long/stopworded keyword patterns) is the single biggest threat to recall
+ * precision, and a paraphrase silently accumulates a near-duplicate; these are
+ * surfaced without blocking, because an over-broad lesson is better than a lost
+ * one.
+ *
+ * The ONE blocking case lives elsewhere (`addLessonInto` → `UnrecallableLessonError`):
+ * a capture whose EVERY trigger is dead on the mandatory recall path is rejected,
+ * because that lesson is captured then silently never recalled. These guardrails
+ * are the warn-only complement to that single hard block.
+ */
+type GuardrailCode = 'OVERSIZED_LESSON_TRIGGERS' | 'BROAD_GLOB_TRIGGER' | 'KEYWORD_ONLY_LESSON' | 'LOW_SIGNAL_KEYWORD' | 'STOPWORD_KEYWORD' | 'DEAD_GLOB' | 'NEAR_DUPLICATE_LESSON';
+interface GuardrailWarning {
+    readonly code: GuardrailCode;
+    readonly message: string;
+}
+
+/**
+ * Capture rejection errors thrown by {@link addLessonInto}. Kept in their own
+ * module so `add.ts` stays focused on the mutation logic; re-exported from
+ * `add.js` so every existing importer keeps its `from './add.js'` path.
+ */
+declare class UnknownTopicError extends Error {
+    readonly topic: string;
+    readonly code = "UNKNOWN_TOPIC";
+    constructor(topic: string);
+}
+
+interface AddLessonTriggers {
+    readonly files?: readonly string[];
+    readonly commands?: readonly string[];
+    readonly keywords?: readonly string[];
+}
+interface AddLessonInput {
+    readonly rule: string;
+    readonly topic: string;
+    readonly triggers: AddLessonTriggers;
+    readonly evidence?: readonly string[];
+    readonly rationale?: string;
+    readonly createdAt?: string;
+}
+interface AddLessonOptions {
+    readonly allowNewTopic?: boolean;
+    readonly topicSummary?: string;
+    readonly retries?: number;
+    /**
+     * Skip the "a lesson needs at least one trigger" guard. Set only by the
+     * legacy-merge recovery path, which folds historical lessons that may predate
+     * the requirement; interactive capture (CLI/MCP) always enforces it so a fresh
+     * agent cannot create an unreachable lesson.
+     */
+    readonly allowNoTrigger?: boolean;
+    /**
+     * Working-tree file list (project-relative, forward-slash) enabling the
+     * warn-only DEAD_GLOB guardrail. The capture entry point supplies it; the
+     * legacy-merge path omits it, so no tree walk happens off the capture path.
+     */
+    readonly knownPaths?: ReadonlySet<string>;
+}
+interface AddLessonResult {
+    readonly id: string;
+    readonly isNewLesson: boolean;
+    readonly isNewTopic: boolean;
+    readonly newTriggerIds: string[];
+    /** Non-blocking capture guardrail warnings for the resulting (merged) lesson. */
+    readonly warnings: GuardrailWarning[];
+    /**
+     * Counts of structural cruft the opt-in auto-prune cleaned up right after this
+     * capture (config `autoPrune: true`). Present only when something was pruned;
+     * absent when auto-prune is off or there was nothing to clean.
+     */
+    readonly autoPruned?: AutoPruneSummary;
+}
+declare function addLesson(projectRoot: string, input: AddLessonInput, options?: AddLessonOptions): Promise<AddLessonResult>;
+
+interface LessonsQuery {
+    /** Project-relative path of the file about to be edited. */
+    readonly file?: string;
+    /** Shell command about to be executed. */
+    readonly command?: string;
+    /** Free-form text describing the current task. */
+    readonly keyword?: string;
+}
+interface MatchedLesson {
+    readonly id: string;
+    readonly lesson: Lesson;
+}
+/**
+ * Recall primitive — returns every active lesson whose triggers match any of
+ * the supplied query fields. The query fields combine as OR across triggers:
+ * a lesson matches if ANY of its triggers match ANY supplied field.
+ * Deprecated and superseded lessons are excluded.
+ */
+declare function queryLessons(graph: LessonsGraph, query: LessonsQuery): MatchedLesson[];
+
+interface RankReason {
+    readonly matchedTriggers: string[];
+    readonly bm25: number;
+    readonly specificity: number;
+    readonly topicCoherence: number;
+}
+interface RankedLesson {
+    readonly id: string;
+    readonly lesson: Lesson;
+    readonly score: number;
+    readonly reason: RankReason;
+}
+interface RankOptions {
+    /** Keep at most this many results (after ranking). */
+    readonly limit?: number;
+    /**
+     * Best-effort token budget: keep results while their cumulative estimated
+     * rule-token cost fits. The single most-relevant result is ALWAYS returned
+     * even if it alone exceeds the budget — an empty recall for a matched query is
+     * worse for the agent than one slightly-over-budget rule.
+     */
+    readonly maxTokens?: number;
+}
+/** Default recall cap: a broad trigger match returns the most-relevant few, not the whole topic. */
+declare const DEFAULT_RECALL_LIMIT = 10;
+/**
+ * Default recall token budget applied by the application APIs (CLI `query`, MCP
+ * `lessons_query`, {@link recallLessons}) when the caller does not specify one.
+ * Mandatory recall runs before every edit/command, so its payload must stay
+ * lean; without a budget a broad match can return ~450+ rule-tokens. `--all`
+ * (CLI) bypasses both caps. The top result is always kept (see RankOptions).
+ */
+declare const DEFAULT_RECALL_MAX_TOKENS = 400;
+/**
+ * Rank matched lessons by relevance and apply optional caps. Three lightweight
+ * signals are weighted-reciprocal-rank-fused (RRF): trigger specificity (inverse
+ * fanout — a discriminating trigger beats a topic-wide one; highest weight),
+ * per-query topic coherence (a lesson in the topic that dominates this query's
+ * matched set is boosted; middle weight), and BM25 over the rule text (so the
+ * lesson whose wording best fits breaks ties the structural signals cannot;
+ * lowest weight). Ties break by recency (createdAt) then id. No embeddings, no
+ * I/O — pure and sub-millisecond.
+ */
+declare function rankLessons(graph: LessonsGraph, query: LessonsQuery, matches: readonly MatchedLesson[], options?: RankOptions): RankedLesson[];
+
+interface MutateOptions {
+    readonly retries?: number;
+}
+/**
+ * The public transactional write path: migrate a legacy store FIRST (so even a
+ * first raw mutation cannot create an empty `lessons.json` and strand
+ * `index.yaml`), then run the locked transaction. Every mutating operation
+ * (add, merge, deprecate, strip-markers, …) and any third-party consumer routes
+ * through here. `maybeAutoMigrateLessons` is a no-op (one stat) when a graph
+ * already exists or no legacy index is present, and runs before the lock is
+ * taken, so there is no re-entrancy with the migrator's own locked write.
+ */
+declare function mutateLessonsGraph<T>(projectRoot: string, mutator: (graph: LessonsGraph) => T | Promise<T>, options?: MutateOptions): Promise<Awaited<T>>;
+
+declare function graphFilePath(projectRoot: string): string;
+declare function loadLessonsGraph(projectRoot: string): LessonsGraph;
+declare function tryLoadLessonsGraph(projectRoot: string): LessonsGraph | null;
+/**
+ * Deterministic serialization: every object's keys are emitted in alphabetical
+ * order so diffs reflect content changes rather than insertion order. Output
+ * always ends with a single trailing newline to keep CRLF/POSIX diffs clean.
+ */
+declare function serializeGraph(graph: LessonsGraph): string;
+
+interface MergeLessonsResult {
+    readonly loserId: string;
+    readonly keeperId: string;
+}
+interface MergeLessonsOptions {
+    readonly retries?: number;
+}
+/**
+ * Fold a duplicate lesson (`loserId`) into its canonical twin (`keeperId`):
+ * union the loser's triggers, topics, and evidence onto the keeper, then mark
+ * the loser `superseded` with `supersededBy` pointing at the keeper.
+ *
+ * Unioning reachability BEFORE superseding is the whole point — a raw
+ * supersede would silently drop the keeper out of recall for queries that only
+ * matched the loser's (often different-topic) triggers.
+ */
+declare function mergeLessons(projectRoot: string, loserId: string, keeperId: string, options?: MergeLessonsOptions): Promise<MergeLessonsResult>;
+
+interface StripMarkersReport {
+    readonly changedIds: string[];
+    readonly changedCount: number;
+}
+interface StripMarkersOptions {
+    readonly dryRun?: boolean;
+}
+/**
+ * Strip dead legacy provenance markers from a lesson's prose. The migration
+ * from the line-numbered Markdown store left inline `See L\d+`, `(L\d+)`,
+ * `[L\d+]`, and "(also relevant …)" pointers that no longer resolve to
+ * anything. Real provenance lives in the `evidence` array, not the rule text.
+ *
+ * Strictly conservative: ONLY the four marker shapes are touched. Legitimate
+ * parentheticals like `(CWE-78)`, ellipses inside code spans, block-comment
+ * fences, and shell punctuation (`exit 1 ;;`) are left byte-for-byte intact.
+ * Idempotent.
+ */
+declare function stripLegacyMarkers(rule: string): string;
+/**
+ * Apply {@link stripLegacyMarkers} to every lesson. With `dryRun`, computes the
+ * change set without persisting; otherwise writes through the transactional
+ * path (locked + validated + atomic). A legacy-only store is migrated first (the
+ * universal first-access upgrade) so its lessons are stripped rather than
+ * silently ignored. No-op (and no file creation) when neither graph nor legacy
+ * store exists.
+ */
+declare function stripMarkersInGraph(projectRoot: string, options?: StripMarkersOptions): Promise<StripMarkersReport>;
+
+type ValidationLevel = 'error' | 'warning';
+interface ValidationFinding {
+    readonly level: ValidationLevel;
+    readonly code: string;
+    readonly message: string;
+    readonly lessonId?: string;
+    readonly topicId?: string;
+    readonly triggerId?: string;
+}
+interface ValidationReport {
+    /** True when no `error`-level findings exist (warnings do not affect `ok`). */
+    readonly ok: boolean;
+    readonly findings: ValidationFinding[];
+}
+interface ValidateOptions {
+    /**
+     * Working-tree file list (project-relative, forward-slash) for the dead-glob
+     * liveness check. When omitted the check is SKIPPED — the pure write-barrier
+     * call in `mutate.ts` passes nothing, so `add` never walks the tree and a
+     * liveness warning can never block a write. The CLI/lint callers supply it.
+     */
+    readonly knownPaths?: ReadonlySet<string>;
+}
+declare function validateLessonsGraph(graph: LessonsGraph, options?: ValidateOptions): ValidationReport;
+
+interface ImportLegacyOptions {
+    /** ISO date stamped onto every imported lesson's `createdAt`. */
+    readonly migratedAt: string;
+    /**
+     * When `true` (default), delete the legacy `index.yaml`, `journal.md`,
+     * `topics/`, `distill-ledger.yaml`, and `distill-proposal.md` after a
+     * successful migration. Pass `false` to leave them in place (test-only).
+     */
+    readonly deleteLegacy?: boolean;
+    /**
+     * Overwrite an existing non-empty graph. Default `false`: migration refuses
+     * (throws {@link LessonsGraphExistsError}) when, AT WRITE TIME UNDER THE LOCK,
+     * the graph already has lessons — so a concurrent capture is never erased.
+     */
+    readonly force?: boolean;
+    /**
+     * MERGE legacy lessons INTO an existing graph instead of replacing it. This is
+     * the recovery path for a stranded state — legacy `index.yaml` coexisting with
+     * a populated `lessons.json` (an old binary could create this). Each legacy
+     * lesson is folded in via the normal capture path: rules dedup by text,
+     * triggers content-address and dedup, topics union. Never overwrites graph
+     * data; `force` is irrelevant in this mode.
+     */
+    readonly merge?: boolean;
+}
+/** Thrown when migration would overwrite an already-populated graph without `force`. */
+declare class LessonsGraphExistsError extends Error {
+    readonly code = "LESSONS_GRAPH_EXISTS";
+    constructor();
+}
+interface ImportLegacyReport {
+    readonly wroteGraphPath: string;
+    readonly deletedPaths: string[];
+    readonly topicCount: number;
+    readonly lessonCount: number;
+    readonly triggerCount: number;
+}
+/**
+ * One-shot upgrade migrator: reads the legacy YAML index + per-topic
+ * Markdown files, emits the new JSON graph, and (by default) removes every
+ * legacy artifact so the project lands in a clean state on the new system.
+ *
+ * Deterministic over (input, options): the graph output and deletion list are
+ * fixed. Requires the legacy `index.yaml` to exist — it is read unconditionally
+ * and a missing index throws (ENOENT). Callers MUST guard with
+ * `existsSync(lessonsPaths(root).index)` before invoking (see
+ * `maybeAutoMigrateLessons` and the `import-md` handler); re-running on a
+ * post-migration tree, where the legacy files are already gone, throws.
+ */
+declare function importLegacyLessons(projectRoot: string, options: ImportLegacyOptions): Promise<ImportLegacyReport>;
+
+/**
+ * Cross-platform process lock backed by an atomic mkdir.
+ *
+ * Acquire semantics: mkdir with no `recursive` option is atomic per POSIX and
+ * returns EEXIST if the directory already exists. That makes it a reliable
+ * cross-process mutex without any third-party dependency.
+ *
+ * Stale recovery: the holder writes its PID and start timestamp into the lock
+ * dir. On contention we peek at the PID; if the process is gone or the lock is
+ * older than `staleMs`, we evict it and retry.
+ */
+interface LockOptions {
+    /** Maximum retry attempts before throwing LockAcquisitionError. */
+    retries?: number;
+    /** Delay between retries in ms. */
+    retryDelayMs?: number;
+    /** Lock age beyond which an existing lock is treated as stale and evicted. */
+    staleMs?: number;
+    /** Human-readable lock name surfaced in LockAcquisitionError, e.g. "lessons lock". */
+    label?: string;
+}
+type LockRelease = () => Promise<void>;
+
+/**
+ * Process lock for lessons-graph writes.
+ *
+ * Multiple harnesses can call `agentsmesh lessons add` concurrently — capture
+ * the rule once per failure, even when a hooked CI step and the user's editor
+ * race for the same `lessons.json`. The lock lives at
+ * `.agentsmesh/lessons/.lessons.lock` and reuses the same `acquireProcessLock`
+ * primitive as `.install.lock` / `.generate.lock`, so stale-eviction, signal
+ * cleanup, and PID metadata all behave identically.
+ */
+
+declare const LESSONS_LOCK_FILENAME = ".lessons.lock";
+declare function lessonsLockPath(projectRoot: string): string;
+declare function acquireLessonsLock(projectRoot: string, opts?: LockOptions): Promise<LockRelease>;
+
+/**
+ * Default on-disk locations for the lessons subsystem.
+ *
+ * Canonical store: `<projectRoot>/.agentsmesh/lessons/lessons.json` (the JSON
+ * graph). The legacy paths (`journal`, `index`, `topicsDir`) are retained for
+ * the one-shot upgrade migrator only; fresh projects never create them.
+ */
+interface LessonsPaths {
+    /** Directory containing every lessons artifact. */
+    readonly base: string;
+    /** Canonical JSON graph — the single source of truth. */
+    readonly graph: string;
+    /** Optional per-project recall tuning (recallLimit / recallMaxTokens). */
+    readonly config: string;
+    /** Legacy append-only journal. Used by the migrator only. */
+    readonly journal: string;
+    /** Legacy YAML trigger index. Used by the migrator only. */
+    readonly index: string;
+    /** Legacy per-topic Markdown directory. Used by the migrator only. */
+    readonly topicsDir: string;
+}
+declare function lessonsPaths(projectRoot: string): LessonsPaths;
+/**
+ * Project-relative path for a given absolute path, normalized to forward
+ * slashes for cross-platform consistency in markdown rule files.
+ */
+declare function toRelPath(projectRoot: string, absolute: string): string;
+/**
+ * Tier 1 of the lessons contract: the always-on trigger.
+ *
+ * Lives in the project's root rule (`.agentsmesh/rules/_root.md`) as a managed
+ * block, so it reaches every target through canonical rule generation. Universal:
+ * only requires the ability to shell-exec the `agentsmesh` CLI. No `Skill` tool,
+ * no description-match, no per-target projection.
+ *
+ * Deliberately minimal — it carries only the BINDING essentials (both commands,
+ * the BLOCKING framing, the recall scope, the broad capture scope, the graph
+ * path, the MCP fallback). The expansive how-to (full command set, topic
+ * workflow, trigger-flag mechanics, the complete rejected-excuse enumeration, and
+ * the rebuttal pedagogy) lives in the `lessons` skill (`LESSONS_SKILL_BODY`) so
+ * the manual can grow without bloating every target's always-on context.
+ *
+ * Recall is scoped to MUTATING actions — file edits and state-changing commands —
+ * with pure-read commands and the recall query itself explicitly exempt. This
+ * removes the infinite regress (recall before the recall command) and the
+ * most-flouted "read-only included" clause, cutting guarded actions roughly in
+ * half (exploration is read-heavy) while keeping recall where it changes outcomes.
+ *
+ * Structural shape (heading + intro + Recall block + Capture block + closing)
+ * survives generate → import → generate round-trip; only the wording inside each
+ * block is tightened for maximum agent compliance.
+ */
+declare const LESSONS_PROCEDURAL_RULE = "## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)\n\nGraph `.agentsmesh/lessons/lessons.json` is canonical \u2014 never hand-edit. Manual: the `lessons` skill.\n\n**Recall \u2014 MUST run before every file edit and every state-changing command** (build/test/install/migrate/git-write): `agentsmesh lessons query --file <path> --cmd <command>`, then apply every rule. Pure-read commands (cat/ls/grep/git-log) and the recall query itself are exempt.\n\n**Capture \u2014 MUST run immediately after any failure** (a failing test/CI/lint/typecheck, a code review, a user correction, a regression, or a wrong assumption \u2014 yours or anyone's): `agentsmesh lessons add \"<rule>\" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>`.\n\nNo shell? Use the `lessons_query` / `lessons_add` MCP tools. Skip either and the system does not exist.";
+
+interface ScaffoldLessonsResult {
+    readonly created: string[];
+    /** Managed artifacts rewritten to the current wording (e.g. a stale skill). */
+    readonly updated: string[];
+    readonly skipped: string[];
+    readonly rootRuleUpdated: boolean;
+    /** True when the recall-log gitignore entry was added to `.gitignore`. */
+    readonly gitignoreUpdated: boolean;
+    /** True when the PostToolUse recall hook was injected into `hooks.yaml`. */
+    readonly recallHookInjected: boolean;
+}
+/**
+ * Idempotent scaffolder for the lessons subsystem. Backs `agentsmesh init
+ * --lessons`, the lessons-only retrofit, and the import safety net.
+ *
+ * - Creates `.agentsmesh/lessons/lessons.json` (an empty graph) if missing.
+ * - Injects the lessons ritual (Tier 1 — the always-on trigger) into
+ *   `.agentsmesh/rules/_root.md` as a managed block
+ *   (`<!-- agentsmesh:lessons-contract:start -->` … `:end -->`). The block is
+ *   canonical content so it reaches every target — including rules-directory
+ *   targets the generation-contract decorator skips — while the sentinels keep
+ *   the block an identifiable unit for clean round-trip and let re-running
+ *   scaffold refresh the wording from one constant.
+ * - Writes `.agentsmesh/skills/lessons/SKILL.md` (Tier 2 — the on-demand manual).
+ *   Like the Tier-1 paragraph, this is a MANAGED artifact: every run rewrites it
+ *   to the current manual so an upgraded agentsmesh propagates the new wording
+ *   (reported as `updated` when it changed, `skipped` when already current).
+ *   The graph, by contrast, is user data and stays create-if-missing. Targets
+ *   without skills still get Tier 1.
+ */
+declare function scaffoldLessons(projectRoot: string): Promise<ScaffoldLessonsResult>;
+
+export { type AddLessonInput as A, loadLessonsGraph as B, mergeLessons as C, DEFAULT_RECALL_LIMIT as D, mutateLessonsGraph as E, parseGraph as F, queryLessons as G, rankLessons as H, type ImportLegacyOptions as I, scaffoldLessons as J, serializeGraph as K, LESSONS_PROCEDURAL_RULE as L, type MatchedLesson as M, stripLegacyMarkers as N, stripMarkersInGraph as O, toRelPath as P, tryLoadLessonsGraph as Q, type RankOptions as R, type ScaffoldLessonsResult as S, type Topic as T, UnknownTopicError as U, type ValidationFinding as V, validateLessonsGraph as W, DEFAULT_RECALL_MAX_TOKENS as X, LESSONS_LOCK_FILENAME as Y, LessonsGraphExistsError as Z, lessonsLockPath as _, type AddLessonOptions as a, type AddLessonResult as b, type AddLessonTriggers as c, type ImportLegacyReport as d, type Lesson as e, type LessonStatus as f, type LessonsGraph as g, LessonsGraphSchema as h, type LessonsPaths as i, type LessonsQuery as j, type MergeLessonsOptions as k, type MergeLessonsResult as l, type MutateOptions as m, type RankReason as n, type RankedLesson as o, type StripMarkersOptions as p, type StripMarkersReport as q, type Trigger as r, type TriggerKind as s, type ValidationLevel as t, type ValidationReport as u, acquireLessonsLock as v, addLesson as w, graphFilePath as x, importLegacyLessons as y, lessonsPaths as z };

package/dist/lessons.d.ts

@@ -0,0 +1,106 @@
+import { o as RankedLesson, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult, j as LessonsQuery } from './init-YKxF2zpQ.js';
+export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-YKxF2zpQ.js';
+import 'zod';
+
+/**
+ * Migration-aware application APIs for the lessons subsystem.
+ *
+ * The WRITE path migrates automatically: `mutateLessonsGraph` (and everything
+ * built on it — `addLesson`, `mergeLessons`, deprecate, strip-markers) runs the
+ * legacy→JSON migration before mutating, so even a first raw write can never
+ * create an empty `lessons.json` over an unmigrated `index.yaml`. (The migrator
+ * and scaffolding use the internal `mutateLessonsGraphLocked` to avoid
+ * recursing.)
+ *
+ * The low-level READ primitives (`tryLoadLessonsGraph`, `loadLessonsGraph`,
+ * `queryLessons`) do NOT migrate — a first read through them on a legacy project
+ * would see no graph. `recallLessons` closes that: it migrates first, then
+ * loads + ranks. `captureLesson` is the symmetric capture entry point. Prefer
+ * these application APIs; reach for the read primitives only post-migration.
+ */
+interface RecallOptions {
+    /** Max ranked lessons to return. Defaults to {@link DEFAULT_RECALL_LIMIT}. */
+    readonly limit?: number;
+    /**
+     * Cumulative rule-token budget. Defaults to {@link DEFAULT_RECALL_MAX_TOKENS};
+     * pass `null` to disable the budget (return up to `limit` results).
+     */
+    readonly maxTokens?: number | null;
+    /**
+     * Session correlator for recall dedup. Defaults to `AGENTSMESH_SESSION_ID`;
+     * when set, lessons already delivered this session are suppressed.
+     */
+    readonly sessionId?: string;
+    /** Force dedup off even when a session correlator is present. */
+    readonly noDedup?: boolean;
+}
+interface RecallResult {
+    /** Relevance-ranked, capped lessons (compact metadata lives on each entry). */
+    readonly lessons: RankedLesson[];
+    /** How many active lessons matched the query before the caps were applied. */
+    readonly totalMatches: number;
+    /**
+     * True when the canonical graph existed but could not be read (corrupt JSON /
+     * schema drift). Recall degrades to empty instead of throwing; callers surface
+     * this so a corrupt graph is a visible warning, not silent zero recall.
+     */
+    readonly corrupt?: boolean;
+    /**
+     * Set to the on-disk schema version when the graph is newer than this build
+     * understands. Recall degrades to empty (like `corrupt`) but callers surface
+     * an upgrade hint rather than a "corrupt" warning.
+     */
+    readonly newerVersion?: number;
+    /**
+     * Count of matched lessons suppressed because they were already delivered
+     * earlier in this session (dedup). 0 when dedup is off or nothing repeated.
+     */
+    readonly suppressed: number;
+}
+/**
+ * Recall primitive for applications: migrate if needed, then return the active
+ * lessons matching `query`, relevance-ranked and capped by limit + token budget.
+ */
+declare function recallLessons(projectRoot: string, query: LessonsQuery, options?: RecallOptions): Promise<RecallResult>;
+/**
+ * Capture primitive for applications: migrate if needed, then add the lesson
+ * through the transactional write path. Idempotent on repeat (same rule+topic).
+ *
+ * Both CLI `lessons add` and MCP `lessons_add` route through here, so capture
+ * telemetry is recorded once at this single entry point (mirroring how every
+ * recall records through `recallLessons`). Every rejection — a dead trigger, an
+ * unknown topic, a write-barrier failure — is recorded as a BLOCKED capture
+ * before being rethrown, so `stats` never undercounts blocks.
+ */
+declare function captureLesson(projectRoot: string, input: AddLessonInput, options?: AddLessonOptions): Promise<AddLessonResult>;
+
+/**
+ * One-shot legacy→JSON migration on first access. Shared by the CLI dispatcher
+ * AND the MCP handlers so that an MCP-only agent (query/add) does not strand a
+ * legacy store: if it added first it would create `lessons.json`, which then
+ * permanently blocks the absent-graph auto-migration. Returns true if it
+ * migrated. No-op when a graph already exists or no legacy index is present.
+ */
+declare function maybeAutoMigrateLessons(projectRoot: string): Promise<boolean>;
+
+/**
+ * Safety gate for `command_pattern` triggers.
+ *
+ * Recall is mandatory (it runs before every edit/command) and matches
+ * author-supplied patterns against the command string. A backtracking `RegExp`
+ * can be driven super-linear by a crafted pattern — `(a+)+`, `(a|aa)+`, `a+a+`,
+ * or even `a+b` (quadratic on a long non-matching input) — so one lesson could
+ * hang recall. Local inspection of quantifier shape CANNOT prove a backtracking
+ * regex linear, so we do not try: command patterns are matched by an in-repo
+ * non-backtracking engine ({@link compileLinearMatcher}), which is provably
+ * linear in the input length for any pattern it can compile.
+ *
+ * A pattern is "safe" iff the linear engine can compile it. Patterns it cannot
+ * evaluate (invalid syntax, backreferences, lookarounds) are rejected at capture
+ * (UNSAFE_TRIGGER_PATTERN) and skipped at read time — fail closed.
+ */
+
+/** True when `pattern` can be matched by the linear engine (no ReDoS risk). */
+declare function isSafeRegexPattern(pattern: string): boolean;
+
+export { AddLessonInput, AddLessonOptions, AddLessonResult, LessonsQuery, RankedLesson, type RecallOptions, type RecallResult, captureLesson, isSafeRegexPattern, maybeAutoMigrateLessons, recallLessons };