akm-cli 0.9.0-beta.2 → 0.9.0-beta.27

package/dist/commands/improve/extract.js

@@ -36,12 +36,33 @@ import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { preFilterSession } from "../../integrations/session-logs/pre-filter.js";
 import { chatCompletion } from "../../llm/client.js";
+import { embed } from "../../llm/embedder.js";
 import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
+import { sha256Hex } from "../../runtime.js";
 import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
 import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload } from "./extract-prompt.js";
+import { applySchemaSimilarityPenalty, buildHotProbationFrontmatter, loadDerivedLayerEmbeddings, } from "./homeostatic.js";
+import { resolveProcessEnabled } from "./improve-profiles.js";
 import { buildSessionSummaryPrompt, parseSessionSummary, SESSION_SUMMARY_JSON_SCHEMA, sessionMeetsDurationGate, writeSessionAsset, } from "./session-asset.js";
+import { resolveTriageConfig, scoreSessionTriage } from "./triage.js";
 /** Default minimum session duration (minutes) for session indexing (#561). */
 const DEFAULT_MIN_SESSION_DURATION_MINUTES = 5;
+/**
+ * Default minimum raw session size (chars) below which the extract LLM call is
+ * skipped (#595/#596). Deliberately tiny: analysis of 218 candidate-producing
+ * sessions showed sessions of 22–368 raw chars regularly yield 1–5 candidates,
+ * so size is not a reliable proxy for value — only truly empty sessions
+ * (0 chars, journal files) are safe to skip.
+ */
+const DEFAULT_MIN_CONTENT_CHARS = 10;
+/**
+ * Default cap on NEW sessions the extract pass will LLM-process in a single run
+ * (`processes.extract.maxSessionsPerRun` overrides; `0` disables). Bounds per-run
+ * wall time + token spend so a backlog of accumulated sessions can't run a single
+ * pass past its scheduled-task timeout. Overflow sessions stay unseen and are
+ * processed by subsequent runs, so coverage is preserved — just spread out.
+ */
+const DEFAULT_MAX_SESSIONS_PER_RUN = 25;
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
  * Parse a since-string into an absolute ms-epoch cutoff. Accepts:
@@ -104,9 +125,43 @@ function buildCandidateProposal(candidate, sourceRef) {
     if (candidate.type === "lesson" && candidate.when_to_use) {
         fm.when_to_use = candidate.when_to_use;
     }
+    // #615 WS-0: preserve ordered-action + outcome data in frontmatter so the data
+    // survives even if source transcripts are not re-extractable later. The
+    // procedural-compilation feature (detection/compilation) is deferred to 0.10+.
+    if (candidate.orderedActions && candidate.orderedActions.length > 0) {
+        fm.orderedActions = candidate.orderedActions;
+        if (candidate.outcomeData) {
+            fm.outcomeData = candidate.outcomeData;
+        }
+    }
     const content = assembleAsset(fm, candidate.body);
     return { ref, content, description };
 }
+/**
+ * Canonicalize a session's content into a single deterministic string for
+ * hashing (#602). Each event is rendered `<role>\n<text>` and events are joined
+ * with a NUL-delimited separator (`\n\0\n`) so event boundaries cannot be forged
+ * by text that itself contains newlines.
+ *
+ * The input is the RAW `data.events` stream — NOT the pre-filtered / truncated
+ * set — so the hash is stable across `maxTotalChars` (and any other pre-filter)
+ * config changes: changing config must NEVER change the hash (idempotency AC).
+ * `inlineRefs` and ref metadata (title, startedAt/endedAt timestamps) are
+ * deliberately EXCLUDED so clock/title churn (and an agent adding an inline
+ * `akm remember` mid-session) does not change the hash.
+ */
+function canonicalizeSessionContent(data) {
+    return data.events.map((e) => `${e.role ?? "unknown"}\n${e.text}`).join("\n\0\n");
+}
+/**
+ * sha256 (hex) of the normalized session content (#602). This is the byte-exact,
+ * clock-independent skip authority that replaced the old `session_ended_at`
+ * timestamp comparison. See {@link canonicalizeSessionContent} for exactly what
+ * is (and is not) hashed.
+ */
+export function hashSessionContent(data) {
+    return sha256Hex(canonicalizeSessionContent(data));
+}
 /**
  * Process one session through the full pipeline: read → pre-filter → LLM →
  * parse → createProposal-per-candidate. Returns the per-session result.
@@ -115,7 +170,16 @@ function buildCandidateProposal(candidate, sourceRef) {
  * proposal validation failure) the session result records a warning and
  * keeps going — one session's bad luck never aborts a multi-session run.
  */
-async function processSession(harness, sessionRef, stashDir, config, llmConfig, chat, ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, sessionIndexing) {
+async function processSession(harness, sessionRef, stashDir, config, llmConfig, chat, ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, 
+// #626 — pre-LLM heuristic triage gate. Default-off (enabled:false) takes the
+// exact pre-change path (no scorer call, no new skipReason).
+triage, sessionIndexing, schemaSimilarityCtx, 
+// #602 — already-extracted skip moved INSIDE processSession: the content hash
+// can only be computed after readSession, so the skip decision lives here. The
+// prior row + bypass flags are threaded in from the caller. Skipping here still
+// costs ZERO LLM calls (the expensive resource #602 protects); only the cheap
+// file read is incurred.
+prior, force, singleSession) {
     const warnings = [];
     let data;
     try {
@@ -133,9 +197,79 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             skipReason: "read_failed",
         };
     }
+    // #602 — content-hash skip. Computed on the RAW event stream immediately after
+    // a successful read, BEFORE the pre-filter / minContentChars / triage gates, so
+    // an unchanged session never reaches the LLM. Hash-based ⇒ clock-independent
+    // (immune to the Jun 11-12 timestamp double-extract/over-throttle bug). --force
+    // and single-session (explicit sessionId) modes bypass the skip entirely.
+    const contentHash = hashSessionContent(data);
+    if (!force && !singleSession && shouldSkipAlreadyExtractedSession(prior, contentHash)) {
+        return {
+            sessionId: sessionRef.sessionId,
+            harness: harness.name,
+            candidateCount: 0,
+            proposalIds: [],
+            preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
+            warnings: [`already extracted (content unchanged) at ${prior?.processed_at}; pass --force to re-process`],
+            skipped: true,
+            skipReason: "already_extracted",
+            contentHash,
+        };
+    }
     const filtered = preFilterSession(data, {
         ...(typeof maxTotalChars === "number" ? { maxTotalChars } : {}),
     });
+    // #595/#596 — minContentChars gate: skip the LLM call for sessions whose RAW
+    // size is below threshold. Measured on the raw event text BEFORE the noise
+    // pre-filter, NOT on post-filter output — the pre-filter strips boilerplate
+    // so aggressively that even signal-bearing sessions can have tiny output
+    // (#596: gating post-filter filtered out 100% of sessions). Note: the 0.8.x
+    // fix gated on `filtered.stats.inputCount`, which is an EVENT count, not a
+    // char count — this port measures actual raw chars so the threshold matches
+    // the config key's documented unit.
+    const rawContentChars = data.events.reduce((sum, event) => sum + event.text.length, 0);
+    if (minContentChars > 0 && rawContentChars < minContentChars) {
+        return {
+            sessionId: sessionRef.sessionId,
+            harness: harness.name,
+            candidateCount: 0,
+            proposalIds: [],
+            preFilter: {
+                inputCount: filtered.stats.inputCount,
+                outputCount: filtered.stats.outputCount,
+                truncatedCount: filtered.stats.truncatedCount,
+            },
+            warnings: [],
+            skipped: true,
+            skipReason: "too_short",
+            contentHash,
+        };
+    }
+    // #626 — pre-LLM heuristic triage gate. Runs AFTER minContentChars + the
+    // already-extracted skip check (both in the caller / above), BEFORE the
+    // extraction prompt and the session-asset write. When the session scores below
+    // the configured threshold we triage it out: no chat() call, no session asset,
+    // no proposals. Pure-heuristic — zero added LLM cost. Default-off → skipped.
+    if (triage.enabled) {
+        const t = scoreSessionTriage(data, triage.minScore);
+        if (!t.pass) {
+            return {
+                sessionId: sessionRef.sessionId,
+                harness: harness.name,
+                candidateCount: 0,
+                proposalIds: [],
+                preFilter: {
+                    inputCount: filtered.stats.inputCount,
+                    outputCount: filtered.stats.outputCount,
+                    truncatedCount: filtered.stats.truncatedCount,
+                },
+                warnings: [],
+                skipped: true,
+                skipReason: "triaged_out",
+                contentHash,
+            };
+        }
+    }
     const prompt = buildExtractPrompt({ data, events: filtered.events, inlineRefs: data.inlineRefs });
     // #561 — ADDITIVE session indexing. Generate + write the session asset
     // (`sessions/<harness>/<id>.md`). FAIL-OPEN: any failure only records a
@@ -184,6 +318,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             warnings: ["session_extraction feature returned empty (disabled / timeout / error)"],
             skipped: true,
             skipReason: "llm_unavailable",
+            contentHash,
         };
     }
     const payload = parseExtractPayload(llmRaw);
@@ -215,15 +350,34 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
                 truncatedCount: filtered.stats.truncatedCount,
             },
             warnings,
+            contentHash,
             ...sessionAsset,
         };
     }
+    // WS-3b step 0c: hot-probation intake buffer (#604).
+    // When enabled, system-generated extractions enter captureMode: hot-probation
+    // so they spend ONE consolidation cycle in probation before the deterministic
+    // dedup+quality pass promotes them. Default OFF.
+    const hotProbationEnabled = config.profiles?.improve?.default?.processes?.extract?.hotProbation
+        ?.enabled === true;
     for (const candidate of payload.candidates) {
         if (dryRun) {
             proposalIds.push(`dry-run:${candidate.type}:${candidate.name}`);
             continue;
         }
         try {
+            // WS-3b Step-0b: schema-similarity intake gate. When enabled and the
+            // candidate is a lesson/knowledge whose body embedding is within ε of an
+            // existing derived-layer node, down-prioritize by multiplying confidence by
+            // the penalty. PARITY: schemaSimilarityCtx is null when the flag is off →
+            // applySchemaSimilarityPenalty returns the original confidence untouched and
+            // never embeds. (Logic lives in homeostatic.ts so it is unit-testable.)
+            const gateResult = await applySchemaSimilarityPenalty(candidate, schemaSimilarityCtx, (text) => schemaSimilarityCtx?.embedFn
+                ? schemaSimilarityCtx.embedFn(text)
+                : embed(text, schemaSimilarityCtx?.embeddingConfig));
+            const effectiveConfidence = gateResult.effectiveConfidence;
+            if (gateResult.warning)
+                warn(gateResult.warning);
             const { ref, content, description } = buildCandidateProposal(candidate, sessionRef);
             const result = createProposal(stashDir, {
                 ref,
@@ -234,9 +388,22 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
                     frontmatter: {
                         description,
                         ...(candidate.when_to_use ? { when_to_use: candidate.when_to_use } : {}),
-                        ...(typeof candidate.confidence === "number" ? { confidence: candidate.confidence } : {}),
+                        ...(effectiveConfidence !== undefined ? { confidence: effectiveConfidence } : {}),
                         sources: [`session:${sessionRef.harness}:${sessionRef.sessionId}`],
                         evidence: candidate.evidence,
+                        // #615 WS-0: mirror ordered-action + outcome data in the proposal
+                        // frontmatter record so downstream tooling can read it without
+                        // re-parsing the content body. Omitted when not present.
+                        ...(candidate.orderedActions && candidate.orderedActions.length > 0
+                            ? { orderedActions: candidate.orderedActions }
+                            : {}),
+                        ...(candidate.outcomeData ? { outcomeData: candidate.outcomeData } : {}),
+                        // WS-3b step 0c: tag system-generated extractions as hot-probation
+                        // when the feature is enabled. The consolidation pass will exclude
+                        // them from the LLM merge pool until the intake dedup+quality pass
+                        // runs against them. User-explicit `akm remember` (captureMode: hot)
+                        // is unaffected — this only applies to extract-generated proposals.
+                        ...(hotProbationEnabled ? buildHotProbationFrontmatter() : {}),
                     },
                 },
             }, ctx);
@@ -277,6 +444,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             truncatedCount: filtered.stats.truncatedCount,
         },
         warnings,
+        contentHash,
         ...sessionAsset,
     };
 }
@@ -290,13 +458,20 @@ export async function akmExtract(options) {
     const stashDir = options.stashDir ?? resolveStashDir();
     const dryRun = options.dryRun ?? false;
     const sourceRun = options.sourceRun ?? `extract-${timestampForFilename()}`;
-    // Read the per-process extract config from the active improve profile. Matches
-    // the pattern reflect/distill/consolidate use: `profiles.improve.<active>.processes.extract`.
-    // Only the `default` improve profile is consulted here — extract isn't invoked
-    // with a profile flag yet (parity item for a future change).
-    const extractProcess = config.profiles?.improve?.default?.processes?.extract;
+    // Read the per-process extract config + enabled-state from the ACTIVE improve
+    // profile when `akmImprove` threaded it; otherwise fall back to the `default`
+    // profile (the explicit `akm extract` path, which has no active profile). This
+    // is what stops a non-default profile's `extract.enabled` from being silently
+    // overridden by the default profile and vice-versa.
+    const activeProfile = options.improveProfile;
+    const extractProcess = activeProfile
+        ? activeProfile.processes?.extract
+        : config.profiles?.improve?.default?.processes?.extract;
+    const extractEnabled = activeProfile
+        ? resolveProcessEnabled("extract", activeProfile)
+        : isLlmFeatureEnabled(config, "session_extraction");
     // Feature-gate early so we get a clean "skipped because disabled" envelope.
-    if (!isLlmFeatureEnabled(config, "session_extraction")) {
+    if (!extractEnabled) {
         return {
             schemaVersion: 1,
             ok: true,
@@ -339,8 +514,20 @@ export async function akmExtract(options) {
         60_000;
     // Pre-filter budget — process config can raise it for large-context models.
     const maxTotalChars = typeof extractProcess?.maxTotalChars === "number" ? extractProcess.maxTotalChars : undefined;
+    // #595/#596 — minimum raw session size; sessions below it skip the LLM call
+    // entirely. Set `processes.extract.minContentChars: 0` to disable the gate.
+    const minContentChars = typeof extractProcess?.minContentChars === "number" ? extractProcess.minContentChars : DEFAULT_MIN_CONTENT_CHARS;
+    // Cap on NEW sessions LLM-processed per run; 0 disables. Absent = default.
+    // Bounds per-run wall time / LLM cost so a backlog can't push a run past its
+    // task timeout — the overflow stays unseen and is picked up by later runs.
+    const maxSessionsPerRun = typeof extractProcess?.maxSessionsPerRun === "number"
+        ? extractProcess.maxSessionsPerRun
+        : DEFAULT_MAX_SESSIONS_PER_RUN;
     // Default discovery window — process config can override the built-in 24h.
     const effectiveSince = options.since ?? extractProcess?.defaultSince;
+    // #626 — resolve the triage gate config once per run. Default-off → the
+    // per-session path never calls the scorer and emits no telemetry.
+    const triage = resolveTriageConfig(extractProcess);
     // #561 — resolve session-indexing config. Default ON: we only reach this code
     // when `session_extraction` is enabled AND an LLM is configured (both checked
     // above), so defaulting on costs nothing offline (the summary call fails open)
@@ -438,6 +625,10 @@ export async function akmExtract(options) {
     const sessions = [];
     let processedCount = 0;
     let skippedCount = 0;
+    // #626 — per-run triage aggregation counters (counts-only telemetry, AC4).
+    let triageEvaluated = 0;
+    let triagePassed = 0;
+    let triagedOut = 0;
     const allProposalIds = [];
     const topLevelWarnings = [];
     const chat = options.chat ?? chatCompletion;
@@ -461,39 +652,66 @@ export async function akmExtract(options) {
             stateDb = undefined;
         }
     }
+    // WS-3b Step-0b: schema-similarity intake gate.
+    // Load derived-layer (lesson/knowledge) embeddings once per run, but ONLY
+    // when the gate is enabled in config. When disabled (the default) this block
+    // is fully skipped and schemaSimilarityCtx stays null → byte-identical to
+    // prior behaviour.
+    const schemaSimilarityCfg = extractProcess?.schemaSimilarity;
+    let schemaSimilarityCtx = null;
+    if (schemaSimilarityCfg?.enabled === true) {
+        const derivedEmbeddings = options.schemaSimilarityEmbeddings ?? loadDerivedLayerEmbeddings();
+        schemaSimilarityCtx = {
+            config: schemaSimilarityCfg,
+            derivedEmbeddings,
+            embeddingConfig: config.embedding,
+            embedFn: options.schemaSimilarityEmbedFn,
+        };
+    }
     for (const summary of candidates) {
-        // Skip-tracking: if this session was already processed AND no new events
-        // have arrived since (live endedAt <= recorded endedAt), don't burn an LLM
-        // call. --force or single-session mode (explicit sessionId) bypasses.
+        // #602 — the already-extracted skip moved INTO processSession (the content
+        // hash needs the session body, only available after readSession). The prior
+        // row + bypass flags are threaded through; an unchanged session returns
+        // skipReason 'already_extracted' WITHOUT any LLM call.
         const prior = seenMap.get(summary.sessionId);
-        if (!options.force && !options.sessionId && shouldSkipAlreadyExtractedSession(prior, summary.endedAt)) {
-            sessions.push({
-                sessionId: summary.sessionId,
-                harness: harness.name,
-                candidateCount: 0,
-                proposalIds: [],
-                preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
-                warnings: [
-                    `already extracted at ${prior?.processed_at}; pass --force to re-process or wait until the session has new content`,
-                ],
-                skipped: true,
-                skipReason: "already_extracted",
-            });
-            skippedCount += 1;
-            continue;
+        // Per-run cap on LLM-processed sessions (skip-tracked seen sessions above
+        // don't count). Single-session / --force modes bypass the cap (explicit
+        // intent). Overflow sessions are left unseen for the next run.
+        if (!options.sessionId && !options.force && maxSessionsPerRun > 0 && processedCount >= maxSessionsPerRun) {
+            topLevelWarnings.push(`Reached maxSessionsPerRun=${maxSessionsPerRun}; ${candidates.length - processedCount - skippedCount} session(s) deferred to a later run.`);
+            break;
         }
         try {
-            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, sessionIndexing);
+            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, schemaSimilarityCtx, prior, options.force === true, typeof options.sessionId === "string" && options.sessionId.length > 0);
             sessions.push(result);
+            // #626 — triage aggregation. A session reached the triage gate only when it
+            // was NOT already preempted by an earlier skip (read_failed / too_short /
+            // already_extracted handled above the processSession call). When triage is
+            // enabled, processSession either triages-out (skipReason 'triaged_out') or
+            // proceeds past the gate — both count as "evaluated".
+            if (triage.enabled) {
+                const preemptedBeforeTriage = result.skipReason === "read_failed" ||
+                    result.skipReason === "too_short" ||
+                    result.skipReason === "already_extracted";
+                if (!preemptedBeforeTriage) {
+                    triageEvaluated += 1;
+                    if (result.skipReason === "triaged_out")
+                        triagedOut += 1;
+                    else
+                        triagePassed += 1;
+                }
+            }
             if (result.skipped)
                 skippedCount += 1;
             else
                 processedCount += 1;
             allProposalIds.push(...result.proposalIds);
-            // Persist outcome so the next run skips this session unless new events
-            // arrive. We only track non-dry-run paths — dry-run is for inspection
-            // and should never poison the seen-table.
-            if (trackingEnabled && stateDb && !dryRun) {
+            // Persist outcome so the next run skips this session unless its content
+            // changes. We only track non-dry-run paths — dry-run is for inspection
+            // and should never poison the seen-table. #602: an `already_extracted`
+            // skip is a no-op (the row already carries the matching hash), so don't
+            // re-write it — that keeps `processed_at` stable across unchanged runs.
+            if (trackingEnabled && stateDb && !dryRun && result.skipReason !== "already_extracted") {
                 try {
                     const outcome = result.skipped
                         ? result.skipReason === "read_failed" || result.skipReason === "exception"
@@ -512,6 +730,10 @@ export async function akmExtract(options) {
                         proposalCount: result.proposalIds.length,
                         rationale: result.rationaleIfEmpty ?? null,
                         sourceRun,
+                        // #602 — persist the freshly computed content hash so the NEXT run
+                        // can compare byte-for-byte. read_failed (before hash) → null, which
+                        // keeps the row eligible for retry (matches failed-row semantics).
+                        contentHash: result.contentHash ?? null,
                         metadata: {
                             preFilterInputCount: result.preFilter.inputCount,
                             preFilterOutputCount: result.preFilter.outputCount,
@@ -559,6 +781,20 @@ export async function akmExtract(options) {
             // best-effort close
         }
     }
+    // #626 — counts-only triage telemetry (AC4). Exactly ONE aggregated event per
+    // run, emitted only when the gate was enabled and actually evaluated at least
+    // one session. No per-session events (avoids the log-spam the issue warns of).
+    if (triage.enabled && triageEvaluated > 0) {
+        appendEvent({
+            eventType: "extract_triaged",
+            metadata: {
+                evaluated: triageEvaluated,
+                passed: triagePassed,
+                triagedOut,
+                sourceRun,
+            },
+        }, options.ctx);
+    }
     return {
         schemaVersion: 1,
         ok: true,
@@ -580,9 +816,15 @@ export async function akmExtract(options) {
  * logic in {@link akmExtract} so the `#554 minNewSessions` gate in `improve`
  * can decide whether the extract pass is worth running before any work begins.
  *
- * A session is a "new candidate" when it is in the `since` window AND it would
- * not be skipped by {@link shouldSkipAlreadyExtractedSession} (i.e. it has never
- * been extracted, or new events have arrived since it was last extracted).
+ * #602 — this gate is intentionally CHEAP: it does NOT read session bodies, so
+ * it cannot compute the content hash that {@link shouldSkipAlreadyExtractedSession}
+ * now uses. It therefore uses a CONSERVATIVE row-presence approximation: a
+ * session counts as "new" when there is NO prior row OR the prior row's
+ * `content_hash` is null (never-seen or backfill-eligible). A prior row WITH a
+ * non-null content_hash counts as NOT new — it MIGHT have changed, but the
+ * precise per-session hash check happens downstream in processSession, so an
+ * over-/under-count here only affects whether the pass RUNS, never whether a
+ * changed session is actually re-processed.
  */
 export function countNewExtractCandidates(config, options = {}) {
     const extractProcess = config.profiles?.improve?.default?.processes?.extract;
@@ -616,7 +858,10 @@ export function countNewExtractCandidates(config, options = {}) {
             }
             for (const summary of candidates) {
                 const prior = seenMap.get(summary.sessionId);
-                if (shouldSkipAlreadyExtractedSession(prior, summary.endedAt))
+                // #602 row-presence approximation (see fn doc): a prior row WITH a
+                // non-null content_hash is treated as not-new here; everything else
+                // (never-seen, or null-hash backfill-eligible) counts as new.
+                if (prior && prior.content_hash != null)
                     continue;
                 total += 1;
             }

package/dist/commands/improve/feedback-valence.js

@@ -0,0 +1,54 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Symmetric valence weighting for the improve eligibility sort (#614).
+ *
+ * BACKGROUND. The improve attention/eligibility ranking historically combined
+ * utility with a NEGATIVE-ONLY feedback term: `negative / (positive + negative)`.
+ * Under that formula a strong-positive asset contributes a feedback ratio of
+ * `0` — i.e. positive feedback never drives attention. Only complaints could
+ * lift an asset up the ranking, so a heavily-praised, heavily-used asset that
+ * deserves REINFORCEMENT (distill / promote the win) is treated identically to
+ * a never-rated one.
+ *
+ * FIX (gated, default-off). When symmetric valence is enabled we replace the
+ * negative-only ratio with a |valence| MAGNITUDE term so that BOTH strong
+ * positive and strong negative feedback drive attention. Utility remains the
+ * dominant ordering factor — valence is a secondary attention nudge with a
+ * small fixed weight, never a utility override.
+ *
+ * This module is intentionally pure and storage-free: it takes pre-aggregated
+ * positive/negative counts plus a utility lookup and returns a deterministic
+ * score and lane. All DB access stays in the caller.
+ */
+/** Weight on utility in the combined eligibility score. Utility is dominant. */
+export const UTILITY_WEIGHT = 0.7;
+/** Weight on the feedback attention term in the combined eligibility score. */
+export const FEEDBACK_WEIGHT = 0.3;
+/**
+ * Minimum |valence| magnitude for an item to be ROUTED to the fix / reinforce
+ * lane. Below this the feedback is too weak/mixed to be a confident signal and
+ * the item carries no attention lane (`null`). Pure magnitude in [0, 1].
+ */
+export const STRONG_VALENCE_THRESHOLD = 0.5;
+/**
+ * Compute the symmetric-valence attention score for one asset's feedback.
+ *
+ * Deterministic: depends only on the integer counts. No clock, no randomness.
+ */
+export function computeValenceScore(counts) {
+    const positive = Math.max(0, counts.positive);
+    const negative = Math.max(0, counts.negative);
+    const total = positive + negative;
+    if (total === 0) {
+        return { valence: 0, magnitude: 0, attention: 0, lane: null };
+    }
+    const valence = (positive - negative) / total;
+    const magnitude = Math.abs(valence);
+    let lane = null;
+    if (magnitude >= STRONG_VALENCE_THRESHOLD) {
+        lane = valence < 0 ? "fix" : "reinforce";
+    }
+    return { valence, magnitude, attention: magnitude, lane };
+}