@aitne/daemon 0.1.9 → 0.1.10

package/dist/core/feedback/consolidation-prep.js

@@ -0,0 +1,242 @@
+/**
+ * Feedback Learning Loop — consolidation pre-step (FEEDBACK_LEARNING_LOOP_DESIGN.md §4).
+ *
+ * The daemon-side, deterministic half of Stage 2. On the evening-review tick it
+ * reads unconsumed `feedback_signals`, groups them by `(scope_type, scope_ref)`,
+ * pre-computes each candidate's weighted evidence + promotion verdict and each
+ * lessons file's eviction ranking + headroom, and emits a `<feedback_worksheet>`
+ * block — exactly as `<journal_skeleton>` / `harvestForGate` blocks are
+ * daemon-prepared today. The LLM step then does only the *semantic* work
+ * (intent-match merge, contradiction detection, phrasing) and writes via
+ * `PATCH /api/context/policies/agent-lessons`, then consumes the worksheet's ids.
+ *
+ * Two layers, mirroring `journal-skeleton-builder.ts`:
+ *   - `gatherFeedbackWorksheetScopes(db, …)` — the single DB read (side-effect
+ *     free); groups pending signals by scope. Cost scales with feedback volume,
+ *     not agent count (the `idx_feedback_unconsumed` partial index).
+ *   - `buildFeedbackWorksheet(scopes, …)` — pure markdown/XML composer. Every
+ *     output byte is a deterministic function of its inputs; the caller supplies
+ *     each lessons file's current contents so this stays I/O-free and 100%
+ *     coverable.
+ *
+ * Phase 2 stored `user` + `agent`; Phase 4 added `agent:<slug>` (the evening-review
+ * pre-step now requests it). This module already rendered any lessons scope
+ * generically, so Phase 4 was wiring (`scopeTypes` + task-flow), not new logic here.
+ */
+import { getPendingFeedbackSignals, } from "../../db/feedback-signals-store.js";
+import { extractMarkdownSection, LESSON_KINDS, parseLessonsSection, } from "./lesson-format.js";
+import { evaluatePromotion } from "./promotion-gate.js";
+import { enforceCaps, scoreLesson, isLessonStale, DEFAULT_RECENCY_HALFLIFE_DAYS, } from "./eviction-scorer.js";
+import { groupSignalsBySummary } from "./lesson-merge.js";
+import { formatScope, parseScope, scopeKey, scopeSectionSlug, scopeStoreFile, } from "./scope-parser.js";
+/** Fixed entry caps (§6 table) — config carries only the byte caps. */
+export const GLOBAL_LESSON_ENTRY_CAP = 40;
+export const PER_AGENT_LESSON_ENTRY_CAP = 20;
+/** Default ceiling on signals pulled per pass (store caps the query at 500). */
+const DEFAULT_SIGNAL_LIMIT = 400;
+/**
+ * Read unconsumed signals for the requested scope types and group them by
+ * canonical scope. Each scope type is queried independently (oldest-first
+ * within the type) so the per-pass row budget applies *per type*. A single
+ * global `LIMIT` over `created_at ASC` would let a backlog of unconsumed
+ * `agent_slug` rows occupy the oldest-N window and silently starve the
+ * `user`/`agent` scopes — the per-type fetch caps each scope type
+ * independently so a busy agent can't crowd out the others. Groups come back in
+ * `scopeTypes` order; rows whose `(scope_type, scope_ref)` can't be parsed
+ * (defensive — the route + behavioral sink only write valid pairs) are skipped
+ * so a bad row never breaks the pass.
+ */
+export function gatherFeedbackWorksheetScopes(db, opts) {
+    const limit = opts.limit ?? DEFAULT_SIGNAL_LIMIT;
+    const order = [];
+    const byKey = new Map();
+    for (const scopeType of opts.scopeTypes) {
+        const rows = getPendingFeedbackSignals(db, { scopeType, limit });
+        for (const row of rows) {
+            const scope = parseScope(row.scope_type, row.scope_ref);
+            if (!scope)
+                continue;
+            const key = scopeKey(scope);
+            let group = byKey.get(key);
+            if (!group) {
+                group = { scope, signals: [] };
+                byKey.set(key, group);
+                order.push(key);
+            }
+            group.signals.push(row);
+        }
+    }
+    return order.map((key) => byKey.get(key));
+}
+/** Resolve per-scope byte/entry caps; `null` for raw (user) + unstored scopes. */
+export function lessonCapsForScope(scope, byteCaps) {
+    if (scope.kind === "agent") {
+        return { capBytes: byteCaps.global, maxEntries: GLOBAL_LESSON_ENTRY_CAP };
+    }
+    if (scope.kind === "agent_slug") {
+        return {
+            capBytes: byteCaps.perAgent,
+            maxEntries: PER_AGENT_LESSON_ENTRY_CAP,
+        };
+    }
+    return null;
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function round2(value) {
+    return (Math.round(value * 100) / 100).toFixed(2);
+}
+/**
+ * `store=` attribute for a scope. Stored scopes (user/agent/agent_slug) resolve
+ * to a path; v2 scopes surfaced raw (channel/task/integration, not yet stored)
+ * render an empty string so the LLM treats them as advisory-only.
+ */
+function storeFileAttr(scope) {
+    return scopeStoreFile(scope) ?? "";
+}
+/** Collapse a one-line excerpt of a signal/lesson for an XML text node. */
+function inline(text, max = 300) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const clipped = flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+    return xmlEscape(clipped);
+}
+/** Authority ranking for picking a candidate's representative `src=` trailer. */
+const SOURCE_AUTHORITY = {
+    explicit: 3,
+    self_critique: 2,
+    behavioral: 1,
+};
+/** The strongest source across a candidate's contributing signals. */
+function dominantSource(rows) {
+    return rows.reduce((best, row) => SOURCE_AUTHORITY[row.source] > SOURCE_AUTHORITY[best] ? row.source : best, "behavioral");
+}
+/** Read a stated lesson `kind` out of a signal's `evidence_json` (the route
+ * stores an explicit/self_critique POST's `kind` there), tolerating malformed
+ * JSON. */
+function evidenceKind(json) {
+    if (!json)
+        return null;
+    try {
+        const parsed = JSON.parse(json);
+        return typeof parsed?.kind === "string" && LESSON_KINDS.has(parsed.kind)
+            ? parsed.kind
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort lesson `kind` for a candidate so the LLM doesn't have to guess
+ * the trailer it's told to copy "from the candidate" (task-flow Step 4a): an
+ * explicit/self_critique POST's stated `kind` wins, else a `correction`
+ * valence maps to `correction`, else `null` (the LLM infers from the prose).
+ */
+function candidateKind(rows) {
+    for (const row of rows) {
+        const kind = evidenceKind(row.evidence_json);
+        if (kind)
+            return kind;
+    }
+    return rows.some((row) => row.valence === "correction") ? "correction" : null;
+}
+function renderLessonsScope(input, opts, out) {
+    const label = formatScope(input.scope);
+    const storeFile = storeFileAttr(input.scope);
+    const section = scopeSectionSlug(input.scope);
+    const halfLife = opts.recencyHalfLifeDays ?? DEFAULT_RECENCY_HALFLIFE_DAYS;
+    const sectionBody = input.existingFileMd
+        ? extractMarkdownSection(input.existingFileMd, "Lessons")
+        : null;
+    const existing = sectionBody ? parseLessonsSection(sectionBody) : [];
+    const currentBytes = input.existingFileMd
+        ? Buffer.byteLength(input.existingFileMd, "utf-8")
+        : 0;
+    // Eviction ranking: ascending score → rank 1 = evict-first. The plan
+    // (post-dedupe) tells the LLM whether the store is already over cap.
+    const plan = enforceCaps(existing, { maxBytes: input.caps.capBytes, maxEntries: input.caps.maxEntries }, opts.nowIso, { scopeLabel: label });
+    const ranked = [...existing].sort((a, b) => scoreLesson(a, opts.nowIso, undefined, halfLife) -
+        scoreLesson(b, opts.nowIso, undefined, halfLife));
+    out.push(`  <scope label="${xmlEscape(label)}" store="${xmlEscape(storeFile)}" ` +
+        `section="${xmlEscape(section)}" mode="lessons" ` +
+        `cap_bytes="${input.caps.capBytes}" max_entries="${input.caps.maxEntries}" ` +
+        `current_bytes="${currentBytes}" current_entries="${existing.length}" ` +
+        `over_cap="${plan.evicted.length > 0}">`);
+    if (ranked.length > 0) {
+        out.push(`    <existing_lessons note="ranked by eviction score; drop any lesson marked stale=&quot;true&quot; unless a fresh candidate re-reinforces it; if the section still exceeds the cap after your edits, remove from rank 1 upward then append: ${xmlEscape("- [...N lower-signal lessons omitted — full history in feedback_signals]")}">`);
+        ranked.forEach((lesson, idx) => {
+            out.push(`      <lesson rank="${idx + 1}" score="${round2(scoreLesson(lesson, opts.nowIso, undefined, halfLife))}" ev="${lesson.ev}" kind="${lesson.kind}" last="${lesson.last}" ` +
+                `provisional="${lesson.provisional}" ` +
+                `stale="${isLessonStale(lesson, opts.nowIso, opts.staleDays)}">` +
+                `${inline(lesson.text)}</lesson>`);
+        });
+        out.push("    </existing_lessons>");
+    }
+    renderCandidates(input.signals, opts, out, true);
+    out.push("  </scope>");
+}
+function renderRawScope(input, opts, out) {
+    const label = formatScope(input.scope);
+    const storeFile = storeFileAttr(input.scope);
+    const section = scopeSectionSlug(input.scope);
+    out.push(`  <scope label="${xmlEscape(label)}" store="${xmlEscape(storeFile)}" ` +
+        `section="${xmlEscape(section)}" mode="raw">`);
+    renderCandidates(input.signals, opts, out, false);
+    out.push("  </scope>");
+}
+function renderCandidates(signals, opts, out, withVerdict) {
+    const groups = groupSignalsBySummary(signals.map((row) => ({ id: row.id, summary: row.summary, row })));
+    out.push("    <candidates>");
+    for (const group of groups) {
+        const ids = group.members.map((member) => member.id).join(",");
+        if (withVerdict) {
+            const memberRows = group.members.map((member) => member.row);
+            const verdict = evaluatePromotion(memberRows.map((row) => ({
+                source: row.source,
+                valence: row.valence,
+            })), opts.promotionThreshold);
+            const src = dominantSource(memberRows);
+            const kind = candidateKind(memberRows);
+            out.push(`      <candidate signals="${group.members.length}" ` +
+                `weighted_ev="${round2(verdict.weightedEv)}" ` +
+                `decision="${verdict.promotable ? "promote" : "hold-provisional"}" ` +
+                `conf="${verdict.conf}" src="${src}"` +
+                (kind ? ` kind="${kind}"` : "") +
+                ` reason="${verdict.reason}" ids="${ids}">` +
+                `${inline(group.summary)}</candidate>`);
+        }
+        else {
+            out.push(`      <candidate signals="${group.members.length}" ids="${ids}">` +
+                `${inline(group.summary)}</candidate>`);
+        }
+    }
+    out.push("    </candidates>");
+}
+/**
+ * Compose the `<feedback_worksheet>` block. Returns `null` when there are no
+ * signals at all (the caller then stamps nothing — no empty block in the prompt).
+ */
+export function buildFeedbackWorksheet(scopes, opts) {
+    const signalIds = scopes.flatMap((scope) => scope.signals.map((signal) => signal.id));
+    if (signalIds.length === 0)
+        return null;
+    const out = [];
+    out.push(`<feedback_worksheet generated_at="${xmlEscape(opts.nowIso)}" ` +
+        `promotion_threshold="${opts.promotionThreshold}" scopes="${scopes.length}">`);
+    for (const scope of scopes) {
+        if (scope.caps) {
+            renderLessonsScope({ ...scope, caps: scope.caps }, opts, out);
+        }
+        else {
+            renderRawScope(scope, opts, out);
+        }
+    }
+    out.push(`  <consume ids="${signalIds.join(",")}" />`);
+    out.push("</feedback_worksheet>");
+    return { block: out.join("\n"), signalIds, scopeCount: scopes.length };
+}

package/dist/core/feedback/eviction-scorer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Feedback Learning Loop — eviction scorer + cap enforcer (FEEDBACK_LEARNING_LOOP_DESIGN.md §6).
+ *
+ * A **new** pure-logic module (not `trimBulletEntries`, which is recency
+ * top-N with no notion of `ev`/`kind`; not `clearEntriesBefore`, which keys on
+ * the *leading* `[date]` not the trailer `last=`). It scores lessons and, when
+ * a file is over its per-scope byte/entry cap, evicts the lowest-scored first
+ * — provisional + stale go first — emitting an `[...N omitted]` marker.
+ *
+ *   score = w_ev·log(ev+1) + w_recency·decay(last) + w_kind·importance(kind)
+ *
+ * where importance is `constraint > correction > do-more/do-less > preference`.
+ * Provisional lessons carry a fixed penalty so they sort below active peers of
+ * equal evidence. Near-duplicates are merged (their `ev` summed) *before*
+ * eviction is considered, so a merged lesson is harder to evict, never easier.
+ */
+import { type Lesson, type LessonKind } from "./lesson-format.js";
+export interface EvictionWeights {
+    ev: number;
+    recency: number;
+    kind: number;
+    /** Subtracted from a provisional lesson's score so it evicts first. */
+    provisionalPenalty: number;
+}
+export declare const DEFAULT_EVICTION_WEIGHTS: EvictionWeights;
+/** Half-life (days) of the recency decay term. */
+export declare const DEFAULT_RECENCY_HALFLIFE_DAYS = 45;
+/** `constraint` > `correction` > `do-more`/`do-less` > `preference`. */
+export declare function kindImportance(kind: LessonKind): number;
+/**
+ * Exponential recency decay in `[0, 1]`: `1` for a lesson reinforced today,
+ * `0.5` at one half-life, approaching `0` for ancient lessons. A future or
+ * unparseable `last` clamps to `1` (treated as fresh — never penalised for a
+ * clock/format quirk).
+ */
+export declare function recencyDecay(last: string, nowIso: string, halfLifeDays?: number): number;
+/** Composite eviction score — higher means keep, lower means evict first. */
+export declare function scoreLesson(lesson: Lesson, nowIso: string, weights?: EvictionWeights, halfLifeDays?: number): number;
+/**
+ * §4 step 7 staleness test — a lesson is prunable for staleness when its `last`
+ * reinforcement predates `now − staleDays` and it is not a durable
+ * `constraint`. Shared single source of truth for both worksheet builders
+ * (the nightly `consolidation-prep` and the monthly `regeneralization-prep`)
+ * so the `stale="…"` flag they stamp can never drift apart.
+ *
+ * Semantics (kept byte-stable across the two prior local copies):
+ *   - no horizon configured (`staleDays === undefined`) ⇒ never stale;
+ *   - `kind=constraint` ⇒ never stale (durable);
+ *   - an unparseable `last` (or `nowIso`) yields a `NaN` comparison, which is
+ *     `false` — i.e. never prune on a clock/format quirk. Reuses {@link dateToMs}
+ *     for the same `YYYY-MM-DD → epoch ms` parse the recency decay uses.
+ */
+export declare function isLessonStale(lesson: Lesson, nowIso: string, staleDays: number | undefined): boolean;
+export interface CapConfig {
+    maxBytes: number;
+    maxEntries: number;
+}
+export interface EvictionPlan {
+    /** Lessons that survive, in eviction-score order (highest first). */
+    keep: Lesson[];
+    /** Lessons removed to satisfy the cap, lowest-scored first. */
+    evicted: Lesson[];
+    /** `[...N … omitted]` marker when anything was evicted, else `null`. */
+    omittedMarker: string | null;
+    /** Serialized byte length of the kept section incl. header + marker. */
+    bytes: number;
+}
+export declare function omittedMarker(count: number): string;
+/**
+ * Dedupe, score, sort (highest first), then evict the lowest-scored lessons
+ * until the section fits both `maxEntries` and `maxBytes`. The byte cap is
+ * checked against the *serialized* section (header + bullets + marker) so the
+ * measured size matches what lands on disk.
+ *
+ * Always makes progress when over the byte cap with ≥1 lesson — even a single
+ * lesson longer than the cap is reduced to an empty kept set with the marker —
+ * so the loop terminates.
+ */
+export declare function enforceCaps(lessons: ReadonlyArray<Lesson>, cap: CapConfig, nowIso: string, opts: {
+    scopeLabel: string;
+}, weights?: EvictionWeights, halfLifeDays?: number): EvictionPlan;

package/dist/core/feedback/eviction-scorer.js

@@ -0,0 +1,132 @@
+/**
+ * Feedback Learning Loop — eviction scorer + cap enforcer (FEEDBACK_LEARNING_LOOP_DESIGN.md §6).
+ *
+ * A **new** pure-logic module (not `trimBulletEntries`, which is recency
+ * top-N with no notion of `ev`/`kind`; not `clearEntriesBefore`, which keys on
+ * the *leading* `[date]` not the trailer `last=`). It scores lessons and, when
+ * a file is over its per-scope byte/entry cap, evicts the lowest-scored first
+ * — provisional + stale go first — emitting an `[...N omitted]` marker.
+ *
+ *   score = w_ev·log(ev+1) + w_recency·decay(last) + w_kind·importance(kind)
+ *
+ * where importance is `constraint > correction > do-more/do-less > preference`.
+ * Provisional lessons carry a fixed penalty so they sort below active peers of
+ * equal evidence. Near-duplicates are merged (their `ev` summed) *before*
+ * eviction is considered, so a merged lesson is harder to evict, never easier.
+ */
+import { formatLessonsSection, } from "./lesson-format.js";
+import { dedupeLessons } from "./lesson-merge.js";
+export const DEFAULT_EVICTION_WEIGHTS = {
+    ev: 1.0,
+    recency: 1.0,
+    kind: 0.75,
+    provisionalPenalty: 1.0,
+};
+/** Half-life (days) of the recency decay term. */
+export const DEFAULT_RECENCY_HALFLIFE_DAYS = 45;
+const KIND_IMPORTANCE = {
+    constraint: 4,
+    correction: 3,
+    "do-more": 2,
+    "do-less": 2,
+    preference: 1,
+};
+/** `constraint` > `correction` > `do-more`/`do-less` > `preference`. */
+export function kindImportance(kind) {
+    return KIND_IMPORTANCE[kind];
+}
+function dateToMs(date) {
+    const ms = Date.parse(`${date.slice(0, 10)}T00:00:00Z`);
+    return Number.isFinite(ms) ? ms : NaN;
+}
+/**
+ * Exponential recency decay in `[0, 1]`: `1` for a lesson reinforced today,
+ * `0.5` at one half-life, approaching `0` for ancient lessons. A future or
+ * unparseable `last` clamps to `1` (treated as fresh — never penalised for a
+ * clock/format quirk).
+ */
+export function recencyDecay(last, nowIso, halfLifeDays = DEFAULT_RECENCY_HALFLIFE_DAYS) {
+    const lastMs = dateToMs(last);
+    const nowMs = Date.parse(nowIso);
+    if (!Number.isFinite(lastMs) || !Number.isFinite(nowMs))
+        return 1;
+    const ageDays = (nowMs - lastMs) / 86_400_000;
+    if (ageDays <= 0)
+        return 1;
+    return Math.pow(0.5, ageDays / halfLifeDays);
+}
+/** Composite eviction score — higher means keep, lower means evict first. */
+export function scoreLesson(lesson, nowIso, weights = DEFAULT_EVICTION_WEIGHTS, halfLifeDays = DEFAULT_RECENCY_HALFLIFE_DAYS) {
+    const evTerm = weights.ev * Math.log(Math.max(lesson.ev, 0) + 1);
+    const recencyTerm = weights.recency * recencyDecay(lesson.last, nowIso, halfLifeDays);
+    const kindTerm = weights.kind * kindImportance(lesson.kind);
+    const penalty = lesson.provisional ? weights.provisionalPenalty : 0;
+    return evTerm + recencyTerm + kindTerm - penalty;
+}
+/**
+ * §4 step 7 staleness test — a lesson is prunable for staleness when its `last`
+ * reinforcement predates `now − staleDays` and it is not a durable
+ * `constraint`. Shared single source of truth for both worksheet builders
+ * (the nightly `consolidation-prep` and the monthly `regeneralization-prep`)
+ * so the `stale="…"` flag they stamp can never drift apart.
+ *
+ * Semantics (kept byte-stable across the two prior local copies):
+ *   - no horizon configured (`staleDays === undefined`) ⇒ never stale;
+ *   - `kind=constraint` ⇒ never stale (durable);
+ *   - an unparseable `last` (or `nowIso`) yields a `NaN` comparison, which is
+ *     `false` — i.e. never prune on a clock/format quirk. Reuses {@link dateToMs}
+ *     for the same `YYYY-MM-DD → epoch ms` parse the recency decay uses.
+ */
+export function isLessonStale(lesson, nowIso, staleDays) {
+    if (staleDays === undefined || lesson.kind === "constraint")
+        return false;
+    const lastMs = dateToMs(lesson.last);
+    const nowMs = Date.parse(nowIso);
+    return (nowMs - lastMs) / 86_400_000 > staleDays;
+}
+export function omittedMarker(count) {
+    return `- [...${count} lower-signal lessons omitted — full history in feedback_signals]`;
+}
+/**
+ * Dedupe, score, sort (highest first), then evict the lowest-scored lessons
+ * until the section fits both `maxEntries` and `maxBytes`. The byte cap is
+ * checked against the *serialized* section (header + bullets + marker) so the
+ * measured size matches what lands on disk.
+ *
+ * Always makes progress when over the byte cap with ≥1 lesson — even a single
+ * lesson longer than the cap is reduced to an empty kept set with the marker —
+ * so the loop terminates.
+ */
+export function enforceCaps(lessons, cap, nowIso, opts, weights = DEFAULT_EVICTION_WEIGHTS, halfLifeDays = DEFAULT_RECENCY_HALFLIFE_DAYS) {
+    const deduped = dedupeLessons(lessons);
+    const sorted = [...deduped].sort((a, b) => scoreLesson(b, nowIso, weights, halfLifeDays) -
+        scoreLesson(a, nowIso, weights, halfLifeDays));
+    const evicted = [];
+    let keep = sorted;
+    // Entry cap first — cheap, and shrinks the byte-cap work.
+    if (keep.length > cap.maxEntries) {
+        evicted.push(...keep.slice(cap.maxEntries));
+        keep = keep.slice(0, cap.maxEntries);
+    }
+    const sectionOpts = {
+        scopeLabel: opts.scopeLabel,
+        capBytes: cap.maxBytes,
+        maxEntries: cap.maxEntries,
+    };
+    const measure = (lessonsToMeasure) => Buffer.byteLength(formatLessonsSection(lessonsToMeasure, {
+        ...sectionOpts,
+        omittedMarker: evicted.length > 0 ? omittedMarker(evicted.length) : null,
+    }), "utf-8");
+    // Byte cap — drop lowest-scored (tail of the sorted array) until it fits.
+    while (keep.length > 0 && measure(keep) > cap.maxBytes) {
+        evicted.push(keep[keep.length - 1]);
+        keep = keep.slice(0, -1);
+    }
+    const marker = evicted.length > 0 ? omittedMarker(evicted.length) : null;
+    return {
+        keep,
+        evicted,
+        omittedMarker: marker,
+        bytes: Buffer.byteLength(formatLessonsSection(keep, { ...sectionOpts, omittedMarker: marker }), "utf-8"),
+    };
+}

package/dist/core/feedback/lesson-format.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Feedback Learning Loop — lesson MD format (FEEDBACK_LEARNING_LOOP_DESIGN.md §3.4).
+ *
+ * A *lesson* is a generalized, injectable directive rendered as a markdown
+ * bullet that extends the existing Learned-Context convention with a
+ * machine-readable trailer:
+ *
+ *   - [2026-06-07] Keep the weekly report's budget section even when spend is
+ *     flat — owner flagged it missing twice.
+ *     <!-- ev=2 kind=correction src=explicit conf=high last=2026-06-07 -->
+ *
+ * Optional `<!-- provisional -->` marks a lesson stored but excluded from
+ * injection until it promotes (§4 step 4).
+ *
+ * This module is pure (no I/O): parse a `## Lessons` section body into typed
+ * {@link Lesson}s and serialize them back byte-stably. It is the shared
+ * vocabulary for the promotion gate, eviction scorer, merge/dedup, and the
+ * consolidation worksheet — the §4 division-of-labour mechanical layer. The
+ * LLM authors *prose*; this code owns the *structure*.
+ */
+export type LessonKind = "preference" | "correction" | "do-more" | "do-less" | "constraint";
+export type LessonSource = "explicit" | "behavioral" | "self_critique";
+export type LessonConfidence = "high" | "medium" | "low";
+export interface Lesson {
+    /** Leading `[YYYY-MM-DD]` — creation date, drives age-based pruning. */
+    date: string;
+    /** Human-readable directive prose, newlines collapsed to single spaces. */
+    text: string;
+    /** Evidence count (weighted sum, §4 step 4) — drives promotion + eviction. */
+    ev: number;
+    kind: LessonKind;
+    src: LessonSource;
+    conf: LessonConfidence;
+    /** Last reinforced `YYYY-MM-DD` — staleness pruning keys on this, NOT date. */
+    last: string;
+    /** Stored but excluded from injection until promoted. */
+    provisional: boolean;
+}
+export declare const LESSON_KINDS: ReadonlySet<string>;
+export declare const LESSON_SOURCES: ReadonlySet<string>;
+export declare const LESSON_CONFIDENCES: ReadonlySet<string>;
+/**
+ * Extract a single markdown `## <header>` section body from a file, returning
+ * the lines between the header and the next `## `/`# ` heading (exclusive),
+ * or `null` when the header is absent. CRLF-tolerant.
+ */
+export declare function extractMarkdownSection(md: string, header: string): string | null;
+/**
+ * Parse a `## Lessons` section body into typed lessons. Non-lesson lines
+ * (blank lines, the `<!-- scope: … -->` header comment, the `[...N omitted]`
+ * eviction marker, stray prose) are ignored. Continuation lines (indented)
+ * fold into the preceding lesson's prose. Malformed entries degrade to
+ * defaults rather than throwing, so a hand-edited file never crashes the
+ * nightly pass.
+ */
+export declare function parseLessonsSection(sectionBody: string): Lesson[];
+/**
+ * Render one lesson as a markdown bullet with its trailer. Prose stays on the
+ * first line; the trailer follows on a 2-space-indented continuation line so
+ * it survives `trimBulletEntries` / `clearEntriesBefore` continuation rules.
+ */
+export declare function formatLesson(lesson: Lesson): string;
+/**
+ * Render a full `## Lessons` section: the `<!-- scope: … -->` header comment
+ * (carrying the cap for at-a-glance review), the lesson bullets, and an
+ * optional eviction marker. `scopeLabel` is the {@link formatScope} string.
+ */
+export declare function formatLessonsSection(lessons: ReadonlyArray<Lesson>, opts: {
+    scopeLabel: string;
+    capBytes: number;
+    maxEntries: number;
+    omittedMarker?: string | null;
+}): string;
+/** UTF-8 byte length of a serialized lessons section — the cap unit (§6). */
+export declare function lessonsSectionByteLength(lessons: ReadonlyArray<Lesson>, opts: {
+    scopeLabel: string;
+    capBytes: number;
+    maxEntries: number;
+}): number;