@aiwayds/dsh-topics-memory 0.22.0 → 0.23.0

package/lib/embedding.js

@@ -0,0 +1,208 @@
+/**
+ * Local embedding client (ollama) — the semantic layer behind the nearFloor
+ * reranker (A4 决议 2, spec §3.1).
+ *
+ * Semantics (mirror of jev/client's outcome mode):
+ *  - every failure returns as a structured {ok:false, outcome} result, NEVER
+ *    a throw — the caller degrades explicitly to the pure-lexical path;
+ *  - one AbortSignal.timeout per request, NO retry (query 2s / batch 30s);
+ *  - localhost only in v1 (ADR 0017 local exception). Remote providers do
+ *    not exist here by design: a remote embedding may only ever enter a
+ *    slow-lane/offline path, never the fast lane (red line ①).
+ *
+ * @module embedding
+ */
+import { execFileSync } from 'node:child_process';
+/** Default ollama bind (the plugin's own default; OLLAMA_HOST overrides). */
+export const DEFAULT_EMBED_HOST = 'http://127.0.0.1:11434';
+/** Provider default model when embeddingModel is the '' sentinel
+ *  (spec §7: ollama → nomic-embed-text, 768 dims, A1 §5 measured). */
+export const DEFAULT_EMBED_MODEL = 'nomic-embed-text';
+/** Query-side timeout — the reranker sits in the spliced hot path; a slow
+ *  ollama must lose the race, not the injection. */
+export const EMBED_QUERY_TIMEOUT_MS = 2000;
+/** Batch-side timeout (index rebuild: A1 measured ~9.5s for 137 topics). */
+export const EMBED_BATCH_TIMEOUT_MS = 30_000;
+/** Per-text byte cap before anything leaves the process (query端 p50=153 tok
+ *  ~ well under this; the cap only bites on paste pollution). */
+export const MAX_TEXT_BYTES = 2048;
+/** The only provider v1 speaks. Anything else is an explicit
+ *  unsupported_provider outcome, not a silent attempt. */
+export const SUPPORTED_PROVIDER = 'ollama';
+/** Resolve the ollama base URL: explicit arg wins, then OLLAMA_HOST, then
+ *  the localhost default. Bare `host:port` values get the http:// prefix
+ *  (ollama's own OLLAMA_HOST convention); trailing slashes are trimmed. */
+export function resolveEmbedHost(explicit) {
+    const raw = (explicit ?? process.env.OLLAMA_HOST ?? '').trim();
+    const withScheme = raw === '' ? DEFAULT_EMBED_HOST : /^https?:\/\//.test(raw) ? raw : `http://${raw.replace(/^tcp:\/\//, '')}`;
+    return withScheme.replace(/\/+$/, '');
+}
+/** '' sentinel → provider default model. */
+export function resolveEmbedModel(model) {
+    const m = (model ?? '').trim();
+    return m === '' ? DEFAULT_EMBED_MODEL : m;
+}
+/** Truncate a string to ≤ maxBytes UTF-8 bytes WITHOUT splitting a multibyte
+ *  character: cut at the byte cap, then back off over any continuation bytes
+ *  (0b10xxxxxx) so the decoded tail is never a replacement char. */
+export function truncateUtf8(text, maxBytes = MAX_TEXT_BYTES) {
+    if (maxBytes <= 0)
+        return '';
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.length <= maxBytes)
+        return text;
+    let end = maxBytes;
+    while (end > 0 && (buf[end] & 0xc0) === 0x80)
+        end -= 1;
+    return buf.subarray(0, end).toString('utf8');
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Shared request path: POST {host}/api/embed, outcome-mode failures only. */
+async function embedRequest(texts, config, timeoutMs) {
+    const provider = (config.provider ?? '').trim();
+    if (provider === '') {
+        return { ok: false, outcome: 'provider_off', message: "embeddingProvider is '' — the semantic layer is off (pure lexical).", host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 };
+    }
+    if (provider !== SUPPORTED_PROVIDER) {
+        return { ok: false, outcome: 'unsupported_provider', message: `embeddingProvider '${provider}' is not supported in v1 (only '${SUPPORTED_PROVIDER}'); remote providers may not enter the fast lane.`, host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 };
+    }
+    if (texts.length === 0) {
+        return { ok: false, outcome: 'empty_input', message: 'no texts to embed.', host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 };
+    }
+    const host = resolveEmbedHost(config.host);
+    const model = resolveEmbedModel(config.model);
+    const started = Date.now();
+    let res;
+    try {
+        res = await fetch(`${host}/api/embed`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ model, input: texts.map((t) => truncateUtf8(t)) }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const outcome = err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError') ? 'timeout' : 'network';
+        return { ok: false, outcome, message: `${outcome}: ${err instanceof Error ? err.message : String(err)}`, host, model, latencyMs: Date.now() - started };
+    }
+    if (!res.ok) {
+        const text = (await res.text().catch(() => '')).slice(0, 300);
+        // ollama answers 404 {"error":"model \"…\" not found, try pulling it first"}
+        const outcome = res.status === 404 ? 'model_missing' : res.status >= 500 ? 'http_5xx' : 'http_4xx';
+        return { ok: false, outcome, message: `ollama responded ${res.status}: ${text}`, host, model, latencyMs: Date.now() - started };
+    }
+    let json;
+    try {
+        json = await res.json();
+    }
+    catch (err) {
+        return { ok: false, outcome: 'bad_json', message: `non-JSON body: ${err instanceof Error ? err.message : String(err)}`, host, model, latencyMs: Date.now() - started };
+    }
+    const vectors = isPlainObject(json) ? json.embeddings : undefined;
+    if (!Array.isArray(vectors) ||
+        vectors.length !== texts.length ||
+        !vectors.every((v) => Array.isArray(v) && v.length > 0 && v.every((n) => typeof n === 'number' && Number.isFinite(n))) ||
+        new Set(vectors.map((v) => v.length)).size !== 1) {
+        return { ok: false, outcome: 'bad_shape', message: 'embeddings must be a rectangular [texts.length][dim] array of finite numbers.', host, model, latencyMs: Date.now() - started };
+    }
+    return { ok: true, vectors: vectors, model, dim: vectors[0].length, latencyMs: Date.now() - started };
+}
+/** Batch-embed texts (index build/rebuild path). Vectors align 1:1 with the
+ *  input order; each text is truncated to MAX_TEXT_BYTES first. */
+export async function embedTexts(texts, config = {}, opts = {}) {
+    const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : EMBED_BATCH_TIMEOUT_MS;
+    return embedRequest(texts, config, timeoutMs);
+}
+/** Embed one query (reranker hot path, 2s budget). Empty/whitespace queries
+ *  fail locally with 'empty_input' — nothing leaves the process. */
+export async function embedQuery(query, config = {}, opts = {}) {
+    if ((query ?? '').trim() === '') {
+        return { ok: false, outcome: 'empty_input', message: 'empty query.', host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 };
+    }
+    const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : EMBED_QUERY_TIMEOUT_MS;
+    const r = await embedRequest([query], config, timeoutMs);
+    if (!r.ok)
+        return r;
+    return { ok: true, vector: r.vectors[0], model: r.model, dim: r.dim, latencyMs: r.latencyMs };
+}
+/**
+ * Probe: is the server there, is the model pulled? One micro embed call —
+ * unlike a /api/tags listing it validates the FULL path (server + model +
+ * response shape) and yields the vector dim for index validation, at the
+ * same 15-30ms cost (A1 §5). Structured result; never throws.
+ */
+export async function probeEmbedding(config = {}, opts = {}) {
+    const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : EMBED_QUERY_TIMEOUT_MS;
+    const r = await embedRequest(['dsh-topics-memory semantic layer probe'], config, timeoutMs);
+    if (!r.ok)
+        return r;
+    return { ok: true, host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), dim: r.dim, latencyMs: r.latencyMs };
+}
+/**
+ * Build an embedder handle for retrieval's `ensureIndexFresh` — a callable
+ * embedTexts bound to this config, carrying the RESOLVED model identity the
+ * index must match. ensureIndexFresh reads `.model` only; the actual
+ * rebuild stays with the caller.
+ */
+export function embedderWith(config) {
+    const fn = (texts) => embedTexts(texts, config);
+    return Object.assign(fn, { model: resolveEmbedModel(config.model) });
+}
+// --- Sync query embed (Phase-2 wiring) --------------------------------------
+// The spliced hot path is synchronous (the chancelu lesson): retrieveSync
+// cannot await. A local ollama query is 15-30ms steady state (A1 §5), so a
+// bounded SYNC subprocess call keeps the reranker on the hot lane inside the
+// ADR 0017 local exception — hard-capped so a wedged ollama loses the race,
+// never the injection. curl ships with the host OS; node has no sync HTTP.
+/** Hard sync budget for the hot-lane query embed. Generous over the measured
+ *  15-30ms, merciless for a wedged server. */
+export const EMBED_QUERY_SYNC_TIMEOUT_MS = 250;
+export function embedQuerySync(query, config = {}) {
+    const provider = (config.provider ?? '').trim();
+    if (provider === '') {
+        return { ok: false, outcome: 'provider_off', message: "embeddingProvider is '' — the semantic layer is off.", host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 };
+    }
+    if (provider !== SUPPORTED_PROVIDER) {
+        return { ok: false, outcome: 'unsupported_provider', message: `embeddingProvider '${provider}' is not supported in v1.`, host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 };
+    }
+    if ((query ?? '').trim() === '') {
+        return { ok: false, outcome: 'empty_input', message: 'empty query.', host: resolveEmbedHost(config.host), model: resolveEmbedModel(config.model), latencyMs: 0 };
+    }
+    const host = resolveEmbedHost(config.host);
+    const model = resolveEmbedModel(config.model);
+    const started = Date.now();
+    let raw;
+    try {
+        raw = execFileSync('curl', [
+            '-sS',
+            '--max-time', String(Math.ceil(EMBED_QUERY_SYNC_TIMEOUT_MS / 1000)),
+            '-X', 'POST', `${host}/api/embed`,
+            '-H', 'content-type: application/json',
+            '-d', JSON.stringify({ model, input: [truncateUtf8(query)] }),
+        ], { timeout: EMBED_QUERY_SYNC_TIMEOUT_MS, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const outcome = /timed out|ETIMEDOUT|maxTime/i.test(message) ? 'timeout' : 'network';
+        return { ok: false, outcome, message: `${outcome}: ${message}`, host, model, latencyMs: Date.now() - started };
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, outcome: 'bad_json', message: 'ollama returned non-JSON (sync path).', host, model, latencyMs: Date.now() - started };
+    }
+    const embeddings = isPlainObject(json) ? json.embeddings : undefined;
+    const first = Array.isArray(embeddings) && embeddings.length > 0 ? embeddings[0] : undefined;
+    if (!Array.isArray(first)) {
+        return { ok: false, outcome: 'bad_shape', message: 'ollama response has no embeddings[0] array (sync path).', host, model, latencyMs: Date.now() - started };
+    }
+    const vector = first.filter((n) => typeof n === 'number');
+    if (vector.length === 0 || vector.length !== first.length) {
+        return { ok: false, outcome: 'bad_shape', message: 'embeddings[0] malformed (sync path).', host, model, latencyMs: Date.now() - started };
+    }
+    return { ok: true, vector, model, dim: vector.length, latencyMs: Date.now() - started };
+}

package/lib/ilog.d.ts

@@ -23,6 +23,13 @@ export interface SlowItem {
     slug: string;
     why: string;
 }
+/**
+ * Slow-lane full-lifecycle outcome (A4 决议 3, spec §3.2): where a slow-lane
+ * run (or round with a slow-lane stake) ended. Precedent = decisions.jsonl's
+ * outcome enum — a closed vocabulary so 「没跑」(no-run/no-claim) and 「跑了
+ * 全败」(llm-error/timeout) are finally distinguishable in the log.
+ */
+export type SlowOutcome = 'no-run' | 'no-claim' | 'no-candidates' | 'llm-error' | 'timeout' | 'delivered' | 'expired';
 export interface InjectionRecord {
     at: string;
     sessionId?: string;
@@ -69,6 +76,15 @@ export interface InjectionRecord {
     slowMs?: number;
     /** Slow-lane pointers this round, in delivery order. */
     slow?: SlowItem[];
+    /**
+     * Slow-lane disposition for this round (A4 决议 3, spec §8.2): `delivered`
+     * when a pending was consumed and packed, `expired` at its hard bounds, and
+     * the producing run's failure point (no-run/no-claim/no-candidates/
+     * llm-error/timeout) when a spliced arrived with no pending. Optional —
+     * older lines predate the field and pure fast-lane rounds may omit it.
+     * Written once with the record, never backfilled (ilog append-only).
+     */
+    slowOutcome?: SlowOutcome;
 }
 /**
  * One topic_open event (pointer-open log, v4 §4.3). Everything beyond

package/lib/index.d.ts

@@ -121,6 +121,9 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     jevSecretFile: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
     jevLayaFallback: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
     jevLayaUrl: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    embeddingProvider: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    embeddingModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    packageMode: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     repo: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
     autoInject: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
@@ -156,6 +159,9 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     jevSecretFile: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
     jevLayaFallback: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
     jevLayaUrl: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    embeddingProvider: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    embeddingModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    packageMode: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
 }>>, "plain">;
 /** Live config reference as a 0.1.7 host passes it (cron / mcp-adapter
  * spelling): `.get()` snapshots the current value — the host swaps the

package/lib/index.js

@@ -359,8 +359,9 @@ export async function apply(ctx, config = {}) {
             if (cfg.autoInject) {
                 const consumed = slowLane.consume(sessionId, observer.turnCountOf(sessionId));
                 if (consumed !== undefined) {
-                    if ('pending' in consumed)
-                        slow = consumed.pending;
+                    if ('pending' in consumed) {
+                        slow = { ...consumed.pending, outcome: consumed.pending.outcome };
+                    }
                     else
                         slowExpired = consumed.expired;
                 }
@@ -578,7 +579,10 @@ export async function apply(ctx, config = {}) {
         // and its own settle hook does the release.
         const run = distiller.request(sessionId, reason);
         if (run !== undefined) {
-            void run.finally(() => releaseSessionLlm(sessionId)).catch(() => undefined);
+            void run
+                .finally(() => releaseSessionLlm(sessionId))
+                .then(() => service.refreshEmbeddingIndex())
+                .catch(() => undefined);
         }
     });
     // ---- Session events: injection + observation ----
@@ -786,8 +790,11 @@ export async function apply(ctx, config = {}) {
                         // no-adapter detail instead
                     }
                     const run = distiller.request(sessionId, 'boot-replay');
-                    if (run !== undefined)
-                        void run.catch(() => undefined);
+                    if (run !== undefined) {
+                        void run
+                            .then(() => service.refreshEmbeddingIndex())
+                            .catch(() => undefined);
+                    }
                 })
                     .catch(() => undefined);
                 // Consolidation cadence check — after the pull (freshest pool),
@@ -823,6 +830,9 @@ export async function apply(ctx, config = {}) {
                     })
                         .catch(() => undefined);
                 }
+                // Embedding index maintenance (A4/A6, spec §3): boot-time freshness
+                // check + incremental rebuild — provider '' / packageMode off = no-op.
+                void service.refreshEmbeddingIndex().catch(() => undefined);
             })
                 .catch((error) => {
                 warn(`dsh-topics-memory 启动链失败（不影响会话启动）：${error instanceof Error ? error.message : String(error)}`);
@@ -948,7 +958,11 @@ export async function apply(ctx, config = {}) {
                     ? { ok: false, reason: 'in-flight', created: [], updated: [], marked: 0 }
                     : { ok: false, reason: 'no-model', created: [], updated: [], marked: 0 };
             }
-            return run.finally(() => releaseSessionLlm(sessionId));
+            void run
+                .finally(() => releaseSessionLlm(sessionId))
+                .then(() => service.refreshEmbeddingIndex())
+                .catch(() => undefined);
+            return run;
         };
         // Manual /topics consolidate trigger: same lane as the cadence path, same
         // trigger-time llm capture and in-flight guard (the command runs inside a
@@ -1018,6 +1032,9 @@ const DEFAULTS = {
     distillMaxModelCalls: 8,
     consolidateCadence: 'daily',
     deprecatedTtlDays: 15,
+    embeddingProvider: '',
+    embeddingModel: '',
+    packageMode: 'off',
     usageBoost: 0.15,
     pushDebounceSeconds: 45,
 };

package/lib/pipeline-events.d.ts

@@ -0,0 +1,36 @@
+/**
+ * meta/pipeline-events.jsonl — the pipeline-level anomaly ledger (spec §8.1,
+ * A2/A6 BL-1 revised: the "记 wtf 账" mechanism never existed, this IS the
+ * explicit ledger). One line JSON per event; always on, no config key
+ * (恒开无键 — observability is not a gray-release feature).
+ *
+ * Discipline = decisions.jsonl (src/jev/log.ts) verbatim: field-whitelist
+ * copy on write (extra caller fields cannot leak in, detail values must be
+ * scalar), 512KB auto-compaction keeping the most recent quarter, and write
+ * failures swallowed silently — a broken sink must never break the pipeline.
+ * Unlike jev/log this writer takes the bundle root explicitly (callers like
+ * the slow lane already hold it; tests point it at a tmp dir).
+ *
+ * @module pipeline-events
+ */
+/** Closed vocabulary, spec §8.1 + W-C wave start set. `slow-lane-outcome` is
+ *  the slow lane's per-run disposition row (quality.ts); the distill/link
+ *  kinds are the A2/A6 producers' contract — they import this module. */
+export type PipelineEventKind = 'slow-lane-outcome' | 'distill-op-invalid' | 'distill-op-retry-exhausted' | 'link-ref-rejected';
+/** File NAME inside the bundle's meta dir (path via pipelineEventsFile). */
+export declare const PIPELINE_EVENTS_FILE = "pipeline-events.jsonl";
+export interface PipelineEvent {
+    at: string;
+    kind: PipelineEventKind;
+    /** Bounded scalar metadata only — never conversation or conclusion text. */
+    detail?: Record<string, string | number | boolean>;
+}
+export declare function pipelineEventsFile(bundleDir: string): string;
+/**
+ * Copy one event through the field whitelist onto the ledger. Only `at`,
+ * `kind` and a scalar-valued `detail` map can pass; non-scalar detail values
+ * (objects/arrays/null/NaN), surplus entries and over-long keys/values are
+ * dropped here so no unbounded content can ride in. Write failures are
+ * swallowed downstream — this never rejects and never throws.
+ */
+export declare function recordPipelineEvent(bundleDir: string, event: PipelineEvent): Promise<void>;

package/lib/pipeline-events.js

@@ -0,0 +1,121 @@
+/**
+ * meta/pipeline-events.jsonl — the pipeline-level anomaly ledger (spec §8.1,
+ * A2/A6 BL-1 revised: the "记 wtf 账" mechanism never existed, this IS the
+ * explicit ledger). One line JSON per event; always on, no config key
+ * (恒开无键 — observability is not a gray-release feature).
+ *
+ * Discipline = decisions.jsonl (src/jev/log.ts) verbatim: field-whitelist
+ * copy on write (extra caller fields cannot leak in, detail values must be
+ * scalar), 512KB auto-compaction keeping the most recent quarter, and write
+ * failures swallowed silently — a broken sink must never break the pipeline.
+ * Unlike jev/log this writer takes the bundle root explicitly (callers like
+ * the slow lane already hold it; tests point it at a tmp dir).
+ *
+ * @module pipeline-events
+ */
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { metaDir } from "./paths.js";
+/** File NAME inside the bundle's meta dir (path via pipelineEventsFile). */
+export const PIPELINE_EVENTS_FILE = 'pipeline-events.jsonl';
+const COMPACT_LIMIT = 512 * 1024; // ~512KB cap, same as the decisions/ilog sidecars
+/** Whitelist copy bounds: detail entries and their values stay metadata-sized. */
+const DETAIL_MAX_ENTRIES = 16;
+const DETAIL_KEY_MAX_CHARS = 64;
+const DETAIL_VALUE_MAX_CHARS = 256;
+/** Runtime mirror of PipelineEventKind — the closed vocabulary is enforced
+ *  at the write gate too (a JS caller cannot smuggle an unknown kind in). */
+const KNOWN_KINDS = new Set([
+    'slow-lane-outcome',
+    'distill-op-invalid',
+    'distill-op-retry-exhausted',
+    'link-ref-rejected',
+]);
+export function pipelineEventsFile(bundleDir) {
+    return join(metaDir(bundleDir), PIPELINE_EVENTS_FILE);
+}
+// Serialized like jev/log: single-record appends are line-atomic anyway, but
+// the compaction rewrite must not interleave with an append.
+let queue = Promise.resolve();
+function enqueue(op) {
+    const run = queue.then(op, op);
+    queue = run.catch(() => undefined);
+    return run;
+}
+/** All write failures die HERE — never upstream. */
+async function appendJsonl(file, lines) {
+    await enqueue(async () => {
+        try {
+            await mkdir(dirname(file), { recursive: true });
+            await appendFile(file, lines.map((l) => `${l}\n`).join(''), 'utf8');
+            await compactIfNeeded(file);
+        }
+        catch {
+            // fail-open: a broken ledger must never break the pipeline (§8.1)
+        }
+    });
+}
+// jev/log compactIfNeeded pattern: ~512KB cap; keep the most recent quarter
+// when exceeded (headroom for the next window).
+async function compactIfNeeded(file) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    if (raw.length <= COMPACT_LIMIT)
+        return;
+    const lines = raw.split('\n').filter((l) => l.trim() !== '');
+    const keep = lines.slice(-Math.max(1, Math.floor(lines.length / 4)));
+    const tmp = `${file}.tmp-${randomUUID()}`;
+    try {
+        await writeFile(tmp, keep.map((l) => `${l}\n`).join(''), 'utf8');
+        await rename(tmp, file);
+    }
+    catch {
+        // swallow — the next append retries the compaction
+    }
+}
+/**
+ * Copy one event through the field whitelist onto the ledger. Only `at`,
+ * `kind` and a scalar-valued `detail` map can pass; non-scalar detail values
+ * (objects/arrays/null/NaN), surplus entries and over-long keys/values are
+ * dropped here so no unbounded content can ride in. Write failures are
+ * swallowed downstream — this never rejects and never throws.
+ */
+export async function recordPipelineEvent(bundleDir, event) {
+    if (bundleDir === '' || typeof bundleDir !== 'string')
+        return;
+    if (event === null || typeof event !== 'object')
+        return;
+    if (typeof event.kind !== 'string' || !KNOWN_KINDS.has(event.kind))
+        return;
+    const detail = {};
+    if (event.detail !== undefined && typeof event.detail === 'object') {
+        for (const [key, value] of Object.entries(event.detail)) {
+            if (Object.keys(detail).length >= DETAIL_MAX_ENTRIES)
+                break;
+            const t = typeof value;
+            if (t === 'string') {
+                if (value !== '')
+                    detail[key.slice(0, DETAIL_KEY_MAX_CHARS)] = value.slice(0, DETAIL_VALUE_MAX_CHARS);
+            }
+            else if (t === 'number') {
+                if (Number.isFinite(value))
+                    detail[key.slice(0, DETAIL_KEY_MAX_CHARS)] = value;
+            }
+            else if (t === 'boolean') {
+                detail[key.slice(0, DETAIL_KEY_MAX_CHARS)] = value;
+            }
+            // objects/arrays/null/undefined never pass the whitelist
+        }
+    }
+    const at = typeof event.at === 'string' && event.at !== '' ? event.at : new Date().toISOString();
+    const row = Object.keys(detail).length === 0
+        ? { at, kind: event.kind }
+        : { at, kind: event.kind, detail };
+    await appendJsonl(pipelineEventsFile(bundleDir), [JSON.stringify(row)]);
+}

package/lib/quality.d.ts

@@ -15,8 +15,11 @@
  * Picks rest in a per-session pending slot and inject at the NEXT spliced
  * (steer message), then the slot is gone (消费即清). Hard bounds: per-call
  * 20s, pipeline 45s, pending TTL 10min, turn-lag ≤2. Every failure is
- * contained and silent — I3 (可丢弃性): async products may be missing, never
- * blocking. The lexical re-gate at consumption is SHADOW-ONLY (v4 B3): it
+ * contained — async products may be missing, never blocking (I3 可丢弃性) —
+ * but no longer SILENT (A4 决议 3): each run lands a `slow-lane-outcome`
+ * disposition (SlowOutcome) on the session and in the pipeline-events
+ * ledger, so 「没跑」and 「跑了全败」are distinguishable in the log. The
+ * lexical re-gate at consumption is SHADOW-ONLY (v4 B3): it
  * records verdicts into ilog and never blocks a pick.
  *
  * @module quality
@@ -24,7 +27,10 @@
 import type { TopicsService } from './service.ts';
 import type { ModelCaller } from './distill.ts';
 import type { RingEntry } from './observer.ts';
-import type { QueryBuildShape } from './ilog.ts';
+import type { QueryBuildShape, SlowOutcome } from './ilog.ts';
+/** Re-exported for the ilog writers (spec §8.2): the service layer takes a
+ *  pending's `outcome` (or lastOutcomeOf) as the record's `slowOutcome`. */
+export type { SlowOutcome };
 export declare const PENDING_TTL_MS: number;
 /** Hard drift bound: a pending older than this many turn-ends expires. */
 export declare const TURN_LAG_LIMIT = 2;
@@ -69,6 +75,13 @@ export interface PendingInjection {
     queryBuild: QueryBuildShape;
     model: string;
     ms: number;
+    /**
+     * The producing run's disposition (A4 决议 3, spec §8.2) — always
+     * 'delivered' here (a pending only exists after a settled run). The
+     * service layer copies it into the ilog record's `slowOutcome` at
+     * consumption; expiry surfaces as `expired` via ConsumeResult instead.
+     */
+    outcome: SlowOutcome;
 }
 export type ConsumeResult = {
     pending: PendingInjection;
@@ -94,6 +107,13 @@ export declare class SlowLane {
     private inFlight;
     /** Same-session shadow serialization — a second trigger never overlaps. */
     private shadowInFlight;
+    /**
+     * The session's most recent slow-lane disposition (A4 决议 3): what a
+     * spliced with NO pending reports as its `slowOutcome` — without it a
+     * consumed-undefined round cannot say whether the lane never ran or ran
+     * and failed. One slot per session, overwritten by every trigger.
+     */
+    private outcomeBySession;
     private readonly service;
     private readonly caller;
     /**
@@ -109,6 +129,20 @@ export declare class SlowLane {
     hasPending(sessionId: string): boolean;
     /** True while the session's produce pipeline is still running (llm-capture guard). */
     hasInFlight(sessionId: string): boolean;
+    /**
+     * The session's most recent slow-lane disposition (A4 §3.2): a round whose
+     * consume() came up empty writes THIS as its ilog `slowOutcome` (spec §8.2
+     * — 「spliced 收到但未 produce 也留痕」). Undefined when the lane never
+     * triggered for the session.
+     */
+    lastOutcomeOf(sessionId: string): SlowOutcome | undefined;
+    /**
+     * One disposition, two sinks (A4 决议 3): the per-session slot above and a
+     * `slow-lane-outcome` row in the pipeline-events ledger. Metadata only
+     * (outcome/reason/session/turn/timing — never ring or query text). Never
+     * throws, never rejects: traceability must not become a failure source.
+     */
+    private traceOutcome;
     /** Drop the pending slot (session teardown, restore boundary). */
     clear(sessionId: string): void;
     /**
@@ -126,13 +160,19 @@ export declare class SlowLane {
     private fastGateShadow;
     /**
      * Produce a pending slot for the session's next steer message. Fire-and-
-     * forget; every guard failure is silent. Policy gates live here (config,
-     * sampling, in-flight); host gates (delegation, distill yield) live with
-     * the caller, which owns those services.
+     * forget; every guard failure is contained (never breaks the event
+     * handler) and QUALIFIED (A4 决议 3): a skipped trigger lands a `no-run`
+     * outcome naming the guard, so a later spliced can report why there was
+     * nothing to consume. Policy gates live here (config, sampling, in-flight);
+     * host gates (delegation, distill yield) live with the caller, which owns
+     * those services.
      */
     dispatch(sessionId: string, input: DispatchInput): void;
     private produce;
-    /** One pending slot per settled pipeline (the 0-2 picks + lane metadata). */
+    /** One pending slot per settled pipeline (the 0-2 picks + lane metadata).
+     *  The pending carries its producing run's disposition (A4 §3.2) so the
+     *  ilog writer can copy it verbatim — a pending only exists when the run
+     *  delivered, hence the constant. */
     private settlePending;
     /**
      * The jev rerank (design §2 row 1): one batched noul request over the whole