@aitne/daemon 0.1.9 → 0.1.11

package/dist/core/dm-freshness-metrics.d.ts

@@ -51,7 +51,7 @@ export interface DmFreshnessAggregate {
      * `agent_log_lag_minutes=0` by construction (the snapshot is built at
      * dispatch time), so including them would drag the percentile toward 0
      * and hide the cohort the plan §6 acceptance threshold targets
-     * ("p95 ≤ 60 — i.e. resumed turns are typically within an hourly_check
+     * ("p95 ≤ 60 — i.e. resumed turns are typically within an activity_scan
      * cadence of session start"). When `resumedTurns === 0`, both
      * percentiles are 0 — there is no lag to report.
      */

package/dist/core/drift-effects.js

@@ -224,7 +224,7 @@ function recordCoalescedObservation(db, params) {
         // novelty_score populated. Without this, coalesced inserts only get
         // summarized via the daemon-startup reclaim sweep — a row that lands
         // mid-run sits at `summary_status='pending'` forever and the
-        // hourly_check skill is forced into the legacy fetch-on-doubt path.
+        // activity_scan skill is forced into the legacy fetch-on-doubt path.
         if (inserted)
             notifyObservationSummarizer(inserted.id);
         return 1;
@@ -257,7 +257,7 @@ function recordCoalescedObservation(db, params) {
     // summary describes obsolete content. Reset the summarizer-owned columns
     // to mirror `recordObservation`'s UPSERT on payload change — without
     // this, `summary_text` / `novelty_score` linger from the prior payload
-    // and the hourly_check skill consumes a stale summary as if it were
+    // and the activity_scan skill consumes a stale summary as if it were
     // current (`summary_status='done'` with `summaryStale=false`).
     db.prepare(`UPDATE observations
      SET change_type = ?,

package/dist/core/feedback/consolidation-prep.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 type Database from "better-sqlite3";
+import { type FeedbackScopeType, type FeedbackSignalRow } from "../../db/feedback-signals-store.js";
+import { type CanonicalScope } from "./scope-parser.js";
+/** Fixed entry caps (§6 table) — config carries only the byte caps. */
+export declare const GLOBAL_LESSON_ENTRY_CAP = 40;
+export declare const PER_AGENT_LESSON_ENTRY_CAP = 20;
+export interface WorksheetScopeGroup {
+    scope: CanonicalScope;
+    signals: FeedbackSignalRow[];
+}
+/**
+ * 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 declare function gatherFeedbackWorksheetScopes(db: Database.Database, opts: {
+    scopeTypes: ReadonlyArray<FeedbackScopeType>;
+    limit?: number;
+}): WorksheetScopeGroup[];
+/** Resolve per-scope byte/entry caps; `null` for raw (user) + unstored scopes. */
+export declare function lessonCapsForScope(scope: CanonicalScope, byteCaps: {
+    global: number;
+    perAgent: number;
+}): {
+    capBytes: number;
+    maxEntries: number;
+} | null;
+export interface WorksheetScopeInput {
+    scope: CanonicalScope;
+    signals: FeedbackSignalRow[];
+    /** Current lessons-store file contents (lessons scopes), else null. */
+    existingFileMd: string | null;
+    /** Byte/entry caps for lessons scopes; null for raw (user) scopes. */
+    caps: {
+        capBytes: number;
+        maxEntries: number;
+    } | null;
+}
+export interface BuildWorksheetOptions {
+    promotionThreshold: number;
+    nowIso: string;
+    recencyHalfLifeDays?: number;
+    /**
+     * Staleness horizon in days (`feedbackLessonStaleDays`, §4 step 7). An
+     * existing lesson whose `last=` predates `now − staleDays` and is not a
+     * `constraint` is flagged `stale="true"` so the LLM prunes it in the rebuild.
+     * Omitted ⇒ nothing is flagged stale (no time-based prune this pass).
+     */
+    staleDays?: number;
+}
+export interface WorksheetResult {
+    /** `<feedback_worksheet>…</feedback_worksheet>` block for verbatim injection. */
+    block: string;
+    /** Every surfaced signal id — the exact consume set (§4 step 6). */
+    signalIds: number[];
+    scopeCount: number;
+}
+/**
+ * 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 declare function buildFeedbackWorksheet(scopes: ReadonlyArray<WorksheetScopeInput>, opts: BuildWorksheetOptions): WorksheetResult | null;

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

@@ -0,0 +1,254 @@
+/**
+ * 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.
+ *  The clip strips a trailing lone high surrogate so cutting through an
+ *  astral char (emoji) can't leave a U+FFFD in the worksheet. */
+function inline(text, max = 300) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const clipped = flat.length > max
+        ? `${flat.slice(0, max - 1).replace(/[\uD800-\uDBFF]$/, "")}…`
+        : 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) : [];
+    // `current_bytes` measures the on-disk `## Lessons` SECTION body — the
+    // §6 cap unit (`lessonsSectionByteLength` in lesson-format.ts), the same
+    // unit `enforceCaps` below derives `over_cap` from. Measuring the whole
+    // file here while `over_cap` measured the section produced a
+    // self-contradictory tag (and disagreed with the §6 unit the eviction
+    // engine actually controls).
+    const currentBytes = sectionBody
+        ? Buffer.byteLength(sectionBody, "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.
+    // Pass the same half-life the displayed `ranked` scores use so the plan
+    // and the ranking can never derive from two different scorings.
+    const plan = enforceCaps(existing, { maxBytes: input.caps.capBytes, maxEntries: input.caps.maxEntries }, opts.nowIso, { scopeLabel: label }, undefined, halfLife);
+    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,136 @@
+/**
+ * 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. Reverse the
+    // overflow slice (it comes off the descending-sorted array) so `evicted`
+    // honours its documented lowest-scored-first order; the byte-cap loop
+    // below already pushes lowest-first, so the combined array stays
+    // ascending by score.
+    if (keep.length > cap.maxEntries) {
+        evicted.push(...keep.slice(cap.maxEntries).reverse());
+        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"),
+    };
+}