@evomap/evolver-core 2.0.0-beta.0

package/dist/material/factory.js

@@ -0,0 +1,25 @@
+import { ulid as makeUlid } from 'ulid';
+import { material } from '../schema/material.js';
+/** Fresh ULID for a Material record. Kept in core so the ULID constraint lives next to the schema. */
+export function newMaterialId() {
+    return makeUlid();
+}
+/**
+ * Build a schema-valid Material from a recording event. The composition layer (CLI) owns the source content;
+ * core owns the record shape + id/clock generation. Re-record idempotency is the caller's concern (see the
+ * file watermark cursor): identical content yields a fresh materialId here, so dedup must gate the call, not
+ * the build (a Material's identity is its ULID, not its content — that is the M1 substrate's design).
+ */
+export function buildMaterial(input) {
+    return material.parse({
+        materialId: input.materialId ?? newMaterialId(),
+        ...(input.sourceAgent ? { sourceAgent: input.sourceAgent } : {}),
+        sourceKind: input.sourceKind ?? 'runtime_session',
+        sourcePath: input.sourcePath,
+        kind: input.kind,
+        watermark: input.watermark,
+        capturedAt: input.capturedAt ?? new Date().toISOString(),
+        consumerGroup: input.consumerGroup,
+        ...(input.payload !== undefined ? { payload: input.payload } : {}),
+    });
+}

package/dist/material/index.d.ts

@@ -0,0 +1,8 @@
+export * from './materialStore.js';
+export * from './watermark.js';
+export * from './sources.js';
+export * from './consumer.js';
+export * from './sampling.js';
+export * from './boundary.js';
+export * from './emit.js';
+export * from './factory.js';

package/dist/material/index.js

@@ -0,0 +1,8 @@
+export * from './materialStore.js';
+export * from './watermark.js';
+export * from './sources.js';
+export * from './consumer.js';
+export * from './sampling.js';
+export * from './boundary.js';
+export * from './emit.js';
+export * from './factory.js';

package/dist/material/materialStore.d.ts

@@ -0,0 +1,24 @@
+import { type Material } from '../schema/material.js';
+export interface MaterialStoreOptions {
+    path: string;
+}
+/** 原材料库 (append-only jsonl + single-writer + materialId 去重). */
+export declare class MaterialStore {
+    readonly path: string;
+    private readonly lockPath;
+    private readonly seen;
+    private chain;
+    constructor(opts: MaterialStoreOptions);
+    /** 幂等 put: 已存在 materialId 跳过. */
+    put(input: Material): Promise<{
+        material: Material;
+        stored: boolean;
+    }>;
+    private putLocked;
+    get(materialId: string): Material | undefined;
+    readAll(): Material[];
+    iterate(opts?: {
+        consumerGroup?: string;
+        since?: string;
+    }): Generator<Material>;
+}

package/dist/material/materialStore.js

@@ -0,0 +1,76 @@
+import { openSync, writeSync, fsyncSync, closeSync, existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { material } from '../schema/material.js';
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+import { assertMaterialSource } from './boundary.js';
+/** 原材料库 (append-only jsonl + single-writer + materialId 去重). */
+export class MaterialStore {
+    path;
+    lockPath;
+    seen = new Set();
+    chain = Promise.resolve();
+    constructor(opts) {
+        this.path = opts.path;
+        this.lockPath = `${opts.path}.lock`;
+        mkdirSync(dirname(this.path), { recursive: true });
+        for (const m of this.readAll())
+            this.seen.add(m.materialId);
+    }
+    /** 幂等 put: 已存在 materialId 跳过. */
+    async put(input) {
+        const run = this.chain.then(() => this.putLocked(input));
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    putLocked(input) {
+        const m = material.parse(input);
+        assertMaterialSource(m);
+        if (this.seen.has(m.materialId))
+            return { material: m, stored: false };
+        acquireLock(this.lockPath);
+        try {
+            const fd = openSync(this.path, 'a');
+            try {
+                writeSync(fd, `${JSON.stringify(m)}\n`);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            this.seen.add(m.materialId);
+            return { material: m, stored: true };
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+    }
+    get(materialId) {
+        for (const m of this.readAll())
+            if (m.materialId === materialId)
+                return m;
+        return undefined;
+    }
+    readAll() {
+        if (!existsSync(this.path))
+            return [];
+        const out = [];
+        for (const l of readFileSync(this.path, 'utf8').split('\n')) {
+            if (!l)
+                continue;
+            try {
+                out.push(material.parse(JSON.parse(l)));
+            }
+            catch { /* skip */ }
+        }
+        return out;
+    }
+    *iterate(opts = {}) {
+        for (const m of this.readAll()) {
+            if (opts.consumerGroup !== undefined && m.consumerGroup !== opts.consumerGroup)
+                continue;
+            if (opts.since !== undefined && m.capturedAt < opts.since)
+                continue;
+            yield m;
+        }
+    }
+}

package/dist/material/sampling.d.ts

@@ -0,0 +1,21 @@
+export interface ToolEvent {
+    toolName?: string;
+    toolResult?: string;
+    errorMessage?: string;
+}
+export interface SamplingConfig {
+    defaultRate: number;
+    toolRates?: Record<string, number>;
+    collapseConsecutive: boolean;
+    maxPerBatch?: number;
+}
+export declare const CONSERVATIVE_SAMPLING: SamplingConfig;
+/** tool_event 采样/过滤 (批注#12): 强信号(error)全留, 低价值降采样, 连续折叠, 突发限速. */
+export declare class ToolEventSampler {
+    private readonly cfg;
+    private readonly counts;
+    private lastTool;
+    constructor(cfg: SamplingConfig);
+    shouldKeep(e: ToolEvent): boolean;
+    filter(events: readonly ToolEvent[]): ToolEvent[];
+}

package/dist/material/sampling.js

@@ -0,0 +1,39 @@
+export const CONSERVATIVE_SAMPLING = {
+    defaultRate: 1, toolRates: { read: 100, ls: 100, glob: 50, grep: 20 }, collapseConsecutive: true, maxPerBatch: 500,
+};
+/** tool_event 采样/过滤 (批注#12): 强信号(error)全留, 低价值降采样, 连续折叠, 突发限速. */
+export class ToolEventSampler {
+    cfg;
+    counts = new Map();
+    lastTool;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    shouldKeep(e) {
+        if (e.errorMessage) {
+            this.lastTool = e.toolName;
+            return true;
+        } // 错误 100% 保留
+        const name = e.toolName ?? '';
+        if (this.cfg.collapseConsecutive && name === this.lastTool) {
+            return false;
+        } // 折叠连续相同
+        this.lastTool = name;
+        const rate = this.cfg.toolRates?.[name] ?? this.cfg.defaultRate;
+        if (rate <= 1)
+            return true;
+        const n = (this.counts.get(name) ?? 0) + 1;
+        this.counts.set(name, n);
+        return n % rate === 1; // 每 N 留第 1 个
+    }
+    filter(events) {
+        const out = [];
+        for (const e of events) {
+            if (this.cfg.maxPerBatch !== undefined && out.length >= this.cfg.maxPerBatch)
+                break;
+            if (this.shouldKeep(e))
+                out.push(e);
+        }
+        return out;
+    }
+}

package/dist/material/sources.d.ts

@@ -0,0 +1,25 @@
+import type { SourceAgent } from '../schema/common.js';
+export interface RegisteredSource {
+    agent: SourceAgent;
+    kind: 'session_log' | 'tool_event';
+    globs: string[];
+}
+export declare const DEFAULT_DISCOVERY_WHITELIST: readonly string[];
+export interface SourceRegistryOptions {
+    path?: string;
+    autoDiscover?: boolean;
+    whitelist?: readonly string[];
+}
+/** 源注册/发现 (批注#33): 默认只扫显式 register; 自动发现 opt-in + 白名单. */
+export declare class SourceRegistry {
+    private readonly sources;
+    private readonly autoDiscover;
+    private readonly whitelist;
+    private readonly path;
+    constructor(opts?: SourceRegistryOptions);
+    register(s: RegisteredSource): void;
+    list(): readonly RegisteredSource[];
+    /** 自动发现根: 默认 off→空; opt-in→白名单(实际 glob 扫描在集成层). */
+    discoveryRoots(): string[];
+    private persist;
+}

package/dist/material/sources.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export const DEFAULT_DISCOVERY_WHITELIST = [
+    join(homedir(), '.claude', 'projects'),
+    join(homedir(), '.codex', 'sessions'),
+    join(homedir(), '.cursor'),
+];
+/** 源注册/发现 (批注#33): 默认只扫显式 register; 自动发现 opt-in + 白名单. */
+export class SourceRegistry {
+    sources = [];
+    autoDiscover;
+    whitelist;
+    path;
+    constructor(opts = {}) {
+        this.autoDiscover = opts.autoDiscover ?? false;
+        this.whitelist = opts.whitelist ?? DEFAULT_DISCOVERY_WHITELIST;
+        this.path = opts.path;
+        if (this.path && existsSync(this.path)) {
+            this.sources.push(...JSON.parse(readFileSync(this.path, 'utf8')));
+        }
+    }
+    register(s) { this.sources.push(s); this.persist(); }
+    list() { return this.sources; }
+    /** 自动发现根: 默认 off→空; opt-in→白名单(实际 glob 扫描在集成层). */
+    discoveryRoots() { return this.autoDiscover ? [...this.whitelist] : []; }
+    persist() {
+        if (!this.path)
+            return;
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(this.sources, null, 2));
+    }
+}

package/dist/material/watermark.d.ts

@@ -0,0 +1,21 @@
+import type { Watermark } from '../schema/material.js';
+export declare function fileWatermark(path: string, hashBytes?: number): Watermark;
+export interface ScanResult {
+    changed: boolean;
+    newBytes: {
+        start: number;
+        end: number;
+    } | null;
+    watermark: Watermark;
+}
+/** 增量去重 (批注#15/#16): 快路径 (mtime,size,hash); 前缀完好+size 增→append 增量; 否则全量(rewrite/rename/truncate). */
+export declare function scanFile(path: string, prev: Watermark | undefined, hashBytes?: number): ScanResult;
+export declare function readRange(path: string, start: number, end: number): string;
+/** watermark 游标持久化. */
+export declare class WatermarkStore {
+    private readonly path;
+    private readonly map;
+    constructor(path: string);
+    get(filePath: string): Watermark | undefined;
+    set(filePath: string, wm: Watermark): void;
+}

package/dist/material/watermark.js

@@ -0,0 +1,76 @@
+import { statSync, openSync, readSync, closeSync, existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+/** hash 文件前 length 字节. */
+function prefixHash(path, length) {
+    const fd = openSync(path, 'r');
+    try {
+        const n = Math.max(0, length);
+        const buf = Buffer.alloc(n);
+        if (n > 0)
+            readSync(fd, buf, 0, n, 0);
+        return `sha256:${createHash('sha256').update(buf).digest('hex')}`;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function fileWatermark(path, hashBytes = 4096) {
+    const st = statSync(path);
+    return { path, mtime: st.mtimeMs, size: st.size, contentHash: prefixHash(path, Math.min(hashBytes, st.size)) };
+}
+/** 增量去重 (批注#15/#16): 快路径 (mtime,size,hash); 前缀完好+size 增→append 增量; 否则全量(rewrite/rename/truncate). */
+export function scanFile(path, prev, hashBytes = 4096) {
+    const wm = fileWatermark(path, hashBytes);
+    if (!prev)
+        return { changed: true, newBytes: { start: 0, end: wm.size }, watermark: wm };
+    if (prev.mtime === wm.mtime && prev.size === wm.size && prev.contentHash === wm.contentHash)
+        return { changed: false, newBytes: null, watermark: wm };
+    if (wm.size >= prev.size) {
+        const cover = Math.min(hashBytes, prev.size);
+        if (prev.contentHash === prefixHash(path, cover)) { // prev 前缀完好 → append
+            const newBytes = wm.size > prev.size ? { start: prev.size, end: wm.size } : null;
+            return { changed: newBytes !== null, newBytes, watermark: wm };
+        }
+    }
+    return { changed: true, newBytes: { start: 0, end: wm.size }, watermark: wm };
+}
+export function readRange(path, start, end) {
+    const fd = openSync(path, 'r');
+    try {
+        const buf = Buffer.alloc(end - start);
+        if (buf.length > 0)
+            readSync(fd, buf, 0, buf.length, start);
+        return buf.toString('utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** watermark 游标持久化. */
+export class WatermarkStore {
+    path;
+    map = new Map();
+    constructor(path) {
+        this.path = path;
+        // A corrupt watermark file (crash mid-write) must NOT crash the daemon at startup: degrade to empty → re-scan
+        // every source file. materialStore dedups by content/watermark, so a full re-scan is idempotent, not harmful.
+        if (existsSync(path)) {
+            try {
+                const o = JSON.parse(readFileSync(path, 'utf8'));
+                for (const [k, v] of Object.entries(o))
+                    this.map.set(k, v);
+            }
+            catch { /* corrupt watermark → start empty (idempotent re-scan) */ }
+        }
+    }
+    get(filePath) { return this.map.get(filePath); }
+    set(filePath, wm) {
+        this.map.set(filePath, wm);
+        mkdirSync(dirname(this.path), { recursive: true });
+        // Atomic write: a crash mid-write keeps the previous watermark, never a truncated/corrupt file.
+        const tmp = `${this.path}.tmp`;
+        writeFileSync(tmp, JSON.stringify(Object.fromEntries(this.map)));
+        renameSync(tmp, this.path);
+    }
+}

package/dist/observers/cursorRewriteObserver.d.ts

@@ -0,0 +1,46 @@
+import type { Observer } from './observerBus.js';
+/**
+ * Event types that mean "the APPROVED gene set the agent should see may have changed":
+ *  - cycle.solidified / capsule.produced : a cycle solidified a gene — its learning history (and therefore the
+ *    top-genes ordering) just moved. Emitted by the CycleEngine through the daemon's Ingestor → genuinely live.
+ *  - actor.human.teach                   : a human taught a gene directly (`evolver distill`); it enters the pool
+ *    UN-quarantined, so it is immediately part of the rendered set.
+ *  - actor.human.review.approve          : a human approved a quarantined draft (`evolver review --approve`) — it
+ *    now passes the read-side review gate (A2a), so the rendered set genuinely changed (A2b).
+ * NOT subscribed: `gene.distilled`. An auto-distilled draft enters QUARANTINED, and the read side (A2a) withholds
+ * it until approved — so re-rendering on distill would only ever be a no-op. The meaningful change is the APPROVE
+ * above. Subscribing to this exact set (not all events) keeps the observer quiet on unrelated traffic.
+ */
+export declare const GENE_SET_CHANGE_EVENT_TYPES: readonly string[];
+/** Default debounce window — a cycle emits several gene-set-change events in quick succession; coalesce them
+ *  into a single rewrite rather than re-rendering the file once per event. */
+export declare const DEFAULT_CURSOR_REWRITE_DEBOUNCE_MS = 2000;
+export interface CursorRewriteObserverDeps {
+    /**
+     * Re-render `.cursor/rules/evolver.mdc` from the CURRENT top genes. Injected by the composition layer (it reads
+     * the gene pool + writes the file). May return whether the file actually changed (for the optional change
+     * callback); a void return is treated as "rewritten". Async is awaited so the bus's timeout/DLQ apply.
+     */
+    rewrite(): boolean | void | Promise<boolean | void>;
+    /** Debounce window in ms (a burst of gene events ⇒ one rewrite). Default 2s. */
+    debounceMs?: number;
+    /** Injected clock (epoch ms). Default Date.now. */
+    now?: () => number;
+    /** Observer handle timeout — the bus quarantines on timeout. Default 5s (plenty for a local file render). */
+    timeoutMs?: number;
+    /** Optional: called after a rewrite that actually changed the file (the composition layer can emit value.inject
+     *  here so the inject rail stays consistent across runtimes; deduped to "on real change" only). */
+    onChange?: () => void | Promise<void>;
+}
+/**
+ * Build the cursor rewrite observer. Subscribes to the gene-set-change event types only. On each such event it
+ * (re)arms a debounce timer; when the timer fires it calls `rewrite()` once for the whole burst. Because the bus
+ * dispatches asynchronously and the debounce is timer-based, the observer's own `handle` returns immediately
+ * (just arming the timer) — the actual rewrite runs on the timer and reports its own errors to `onError`.
+ *
+ * idempotent=false: a rewrite has an external side effect (a file write), so the bus must not assume free re-run.
+ */
+export declare function cursorRewriteObserver(deps: CursorRewriteObserverDeps): Observer & {
+    flush(): Promise<void>;
+    pending(): boolean;
+};

package/dist/observers/cursorRewriteObserver.js

@@ -0,0 +1,103 @@
+// Cursor rewrite observer (#124) — the observer-bus member that keeps cursor's injected gene memory FRESH.
+//
+// Cursor has no SessionStart hook (the CC/codex freshness mechanism): a cursor `alwaysApply:true` rule file is
+// read as-is on every request, so there is no pull-at-start moment to re-render it. Freshness therefore comes
+// from REWRITE-ON-CHANGE: when the gene set changes, we re-render .cursor/rules/evolver.mdc. This observer is
+// the live trigger for that — it is hung off the SAME ObserverBus that fans out from the daemon's Ingestor, so a
+// real cycle solidifying a gene (or a distill landing one) ticks it. It is the cursor analogue of the value
+// digest observer: a side-effect hung off the bus, fully fault-isolated by the bus (a throwing rewrite
+// quarantines the observer without ever touching the main write path).
+//
+// Boundaries: the observer owns ONLY the trigger policy (which events count as a gene-set change + debounce). It
+// does NOT render or write the file itself — a `rewrite` callback is injected (the CLI composition layer wires
+// it to the cursorRulesInstaller). So core stays free of fs/cursor knowledge and the observer is testable with a
+// spy. Debounced so a burst of gene events (a cycle emits several) coalesces into ONE rewrite.
+/**
+ * Event types that mean "the APPROVED gene set the agent should see may have changed":
+ *  - cycle.solidified / capsule.produced : a cycle solidified a gene — its learning history (and therefore the
+ *    top-genes ordering) just moved. Emitted by the CycleEngine through the daemon's Ingestor → genuinely live.
+ *  - actor.human.teach                   : a human taught a gene directly (`evolver distill`); it enters the pool
+ *    UN-quarantined, so it is immediately part of the rendered set.
+ *  - actor.human.review.approve          : a human approved a quarantined draft (`evolver review --approve`) — it
+ *    now passes the read-side review gate (A2a), so the rendered set genuinely changed (A2b).
+ * NOT subscribed: `gene.distilled`. An auto-distilled draft enters QUARANTINED, and the read side (A2a) withholds
+ * it until approved — so re-rendering on distill would only ever be a no-op. The meaningful change is the APPROVE
+ * above. Subscribing to this exact set (not all events) keeps the observer quiet on unrelated traffic.
+ */
+export const GENE_SET_CHANGE_EVENT_TYPES = [
+    'cycle.solidified',
+    'capsule.produced',
+    'actor.human.teach',
+    'actor.human.review.approve',
+];
+/** Default debounce window — a cycle emits several gene-set-change events in quick succession; coalesce them
+ *  into a single rewrite rather than re-rendering the file once per event. */
+export const DEFAULT_CURSOR_REWRITE_DEBOUNCE_MS = 2_000;
+/**
+ * Build the cursor rewrite observer. Subscribes to the gene-set-change event types only. On each such event it
+ * (re)arms a debounce timer; when the timer fires it calls `rewrite()` once for the whole burst. Because the bus
+ * dispatches asynchronously and the debounce is timer-based, the observer's own `handle` returns immediately
+ * (just arming the timer) — the actual rewrite runs on the timer and reports its own errors to `onError`.
+ *
+ * idempotent=false: a rewrite has an external side effect (a file write), so the bus must not assume free re-run.
+ */
+export function cursorRewriteObserver(deps) {
+    const debounceMs = deps.debounceMs ?? DEFAULT_CURSOR_REWRITE_DEBOUNCE_MS;
+    const now = deps.now ?? (() => Date.now());
+    let timer;
+    let armedAt;
+    let lastError;
+    const meta = {
+        name: 'cursor-rewrite',
+        eventTypes: GENE_SET_CHANGE_EVENT_TYPES,
+        idempotent: false,
+        timeoutMs: deps.timeoutMs ?? 5_000,
+    };
+    // The actual rewrite, run once per coalesced burst. Swallows nothing on its own — but since it runs on a timer
+    // (out of the bus's handle path) it cannot use the bus DLQ, so it records lastError for flush() to surface.
+    async function fire() {
+        timer = undefined;
+        armedAt = undefined;
+        try {
+            const changed = await deps.rewrite();
+            if (changed !== false && deps.onChange)
+                await deps.onChange();
+            lastError = undefined;
+        }
+        catch (e) {
+            lastError = e;
+        }
+    }
+    function arm() {
+        armedAt = now();
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => { void fire(); }, debounceMs);
+        // Do not keep the process alive solely for a pending rewrite (the daemon is resident anyway; tests exit).
+        timer.unref?.();
+    }
+    return {
+        meta,
+        handle(_event) {
+            // Just (re)arm the debounce — fast + non-blocking so the bus never stalls on a gene event.
+            arm();
+        },
+        /** Force any pending debounced rewrite to run now and await it (graceful shutdown / tests). Re-throws the
+         *  last rewrite error so a broken rewrite is not silently swallowed when explicitly flushed. */
+        async flush() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+                armedAt = undefined;
+                await fire();
+            }
+            if (lastError) {
+                const e = lastError;
+                lastError = undefined;
+                throw e instanceof Error ? e : new Error(String(e));
+            }
+        },
+        /** Whether a rewrite is currently armed (debounce in flight). */
+        pending() { return armedAt !== undefined; },
+    };
+}

package/dist/observers/distillObserver.d.ts

@@ -0,0 +1,31 @@
+import type { Observer } from './observerBus.js';
+/** The root_event ingestion emits when a batch of material lands (see CLI ingest). The only trigger this observer
+ *  subscribes to — it claims from the consumer group, so the event is a tick, not a payload it reads. */
+export declare const MATERIAL_READY_EVENT_TYPE = "material.batch_ready";
+export interface DistillObserverDeps {
+    /**
+     * Drain newly-ready material into UNPROVEN quarantined gene drafts. Injected by the CLI composition (it owns the
+     * consumer-group claim, session re-parse, intake, quarantine, and the gene.distilled emit). Returns TRUE when the
+     * drain STALLED — it stopped on a stuck head (un-acked material it could not advance past, e.g. a transient
+     * persist/audit failure) with a backlog still behind it. A stalled drain needs another attempt that does NOT
+     * depend on a future material.batch_ready, so the observer self-schedules a backoff retry. Falsy = fully drained.
+     */
+    distill(): boolean | void | Promise<boolean | void>;
+    /** Backoff before retrying a STALLED drain (no new material.batch_ready needed). Default 30s. */
+    retryDelayMs?: number;
+    /** Observer handle timeout the bus enforces. Default 30s (a drain re-reads + parses several session files). */
+    timeoutMs?: number;
+}
+/**
+ * Build the distill observer. Subscribes to `material.batch_ready` only. On each such event it runs `distill()`
+ * once, SINGLE-FLIGHT: an event arriving while a drain is in flight is coalesced into ONE trailing drain (never
+ * dropped). If a drain STALLS on a stuck head, the observer self-schedules a backoff retry so a transient write
+ * failure cannot stall the queue forever waiting on an external event. idempotent=false: distill writes a gene +
+ * a root_event, so the bus must not assume a free re-run.
+ */
+export declare function distillObserver(deps: DistillObserverDeps): Observer & {
+    flush(): Promise<void>;
+    running(): boolean;
+    retryScheduled(): boolean;
+    kick(): void;
+};

package/dist/observers/distillObserver.js

@@ -0,0 +1,93 @@
+/** The root_event ingestion emits when a batch of material lands (see CLI ingest). The only trigger this observer
+ *  subscribes to — it claims from the consumer group, so the event is a tick, not a payload it reads. */
+export const MATERIAL_READY_EVENT_TYPE = 'material.batch_ready';
+/**
+ * Build the distill observer. Subscribes to `material.batch_ready` only. On each such event it runs `distill()`
+ * once, SINGLE-FLIGHT: an event arriving while a drain is in flight is coalesced into ONE trailing drain (never
+ * dropped). If a drain STALLS on a stuck head, the observer self-schedules a backoff retry so a transient write
+ * failure cannot stall the queue forever waiting on an external event. idempotent=false: distill writes a gene +
+ * a root_event, so the bus must not assume a free re-run.
+ */
+export function distillObserver(deps) {
+    const retryDelayMs = deps.retryDelayMs ?? 30_000;
+    let inFlight;
+    let pending = false; // a wakeup arrived while a drain was running — coalesce it into ONE trailing drain
+    let retryTimer;
+    let lastError;
+    function trigger() {
+        // Single-flight with coalesce: if a drain is running, REMEMBER the wakeup (pending); otherwise start one.
+        if (inFlight) {
+            pending = true;
+            return;
+        }
+        // Wrap in an IIFE that AWAITS run(): even when run() settles synchronously (e.g. deps.distill() throws before
+        // any real await), the `await` suspends, so `inFlight = …` is ASSIGNED before we clear it. Clearing inside
+        // run()'s own finally would otherwise race the assignment, leave inFlight pointing at an already-settled
+        // promise, and make flush()'s `while (inFlight) await inFlight` spin forever. Clear + retry live HERE (after
+        // the await) so inFlight is undefined before scheduleRetry checks it.
+        inFlight = (async () => {
+            const stalled = await run();
+            inFlight = undefined;
+            if (stalled)
+                scheduleRetry();
+        })();
+    }
+    function scheduleRetry() {
+        if (retryTimer || inFlight)
+            return; // a retry/run is already coming
+        retryTimer = setTimeout(() => { retryTimer = undefined; trigger(); }, retryDelayMs);
+        retryTimer.unref?.(); // never keep the process alive solely for a pending retry
+    }
+    /** One drain cycle. Returns true if it STALLED on a stuck head (un-acked backlog), false if fully drained.
+     *  Trailing edge: loops while wakeups arrive mid-drain so a coalesced wakeup is never dropped. Does NOT touch
+     *  inFlight (the caller owns it — see trigger). */
+    async function run() {
+        let stalled = false;
+        try {
+            do {
+                pending = false;
+                stalled = Boolean(await deps.distill());
+            } while (pending);
+            lastError = undefined;
+        }
+        catch (e) {
+            // A THROWN drain (e.g. store.list / readAll failed) is a transient failure that left the backlog un-drained
+            // — treat it as stalled so a backoff retry is scheduled, same as an explicit stuck head. Without this a
+            // throw would silently stop all draining until an unrelated future event.
+            lastError = e;
+            stalled = true;
+        }
+        return stalled;
+    }
+    const meta = {
+        name: 'distill',
+        eventTypes: [MATERIAL_READY_EVENT_TYPE],
+        idempotent: false,
+        timeoutMs: deps.timeoutMs ?? 30_000,
+    };
+    return {
+        meta,
+        handle(_event) {
+            trigger(); // returns immediately (the drain runs in the background) so the bus never stalls on a slow drain
+        },
+        /** Await the drain chain to settle (a pending trailing drain may chain another) and re-throw its last error
+         *  (graceful shutdown / tests) — so a broken drain is not silently swallowed when explicitly flushed. */
+        async flush() {
+            while (inFlight)
+                await inFlight;
+            if (lastError) {
+                const e = lastError;
+                lastError = undefined;
+                throw e instanceof Error ? e : new Error(String(e));
+            }
+        },
+        /** Whether a drain is currently in flight. */
+        running() { return inFlight !== undefined; },
+        /** Whether a backoff retry of a stalled drain is armed (introspection for tests / shutdown). */
+        retryScheduled() { return retryTimer !== undefined; },
+        /** Trigger an initial drain WITHOUT a material.batch_ready event — the daemon calls this once after
+         *  registration so a process restart recovers any un-acked backlog (the in-memory backoff retry does not
+         *  survive a restart). Same single-flight/coalesce/retry path as an event-driven wakeup. */
+        kick() { trigger(); },
+    };
+}

package/dist/observers/index.d.ts

@@ -0,0 +1,5 @@
+export * from './observerBus.js';
+export * from './valueDigestObserver.js';
+export * from './cursorRewriteObserver.js';
+export * from './distillObserver.js';
+export * from './reflectionObserver.js';

package/dist/observers/index.js

@@ -0,0 +1,5 @@
+export * from './observerBus.js';
+export * from './valueDigestObserver.js';
+export * from './cursorRewriteObserver.js';
+export * from './distillObserver.js';
+export * from './reflectionObserver.js';