@evomap/evolver-core 2.0.0-beta.0

package/dist/events/eventSchema.d.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+export declare const EVENT_SCHEMA_VERSION = "1.0.0";
+export declare const replayability: z.ZodEnum<["deterministic", "stochastic_recorded", "stochastic_unreproducible"]>;
+export type Replayability = z.infer<typeof replayability>;
+/** 每事件自带叙述 (军杰 §9.2). title 必填. */
+export declare const humanNarrative: z.ZodObject<{
+    title: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    why: z.ZodOptional<z.ZodString>;
+    next: z.ZodOptional<z.ZodString>;
+    severity: z.ZodDefault<z.ZodEnum<["info", "notice", "warn", "error"]>>;
+    iconHint: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    severity: "warn" | "info" | "notice" | "error";
+    title: string;
+    detail?: string | undefined;
+    why?: string | undefined;
+    next?: string | undefined;
+    iconHint?: string | undefined;
+}, {
+    title: string;
+    severity?: "warn" | "info" | "notice" | "error" | undefined;
+    detail?: string | undefined;
+    why?: string | undefined;
+    next?: string | undefined;
+    iconHint?: string | undefined;
+}>;
+export type HumanNarrative = z.infer<typeof humanNarrative>;
+/** 人/机操作审计 (军杰 §9.7). */
+export declare const actor: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<["machine", "human"]>>;
+    id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    kind: "machine" | "human";
+    id?: string | undefined;
+}, {
+    kind?: "machine" | "human" | undefined;
+    id?: string | undefined;
+}>;
+export type Actor = z.infer<typeof actor>;
+/** AE 事件信封 (军杰 §3.2). 内部类型 camelCase. */
+export declare const rootEvent: z.ZodObject<{
+    seq: z.ZodNumber;
+    eventId: z.ZodString;
+    ts: z.ZodString;
+    type: z.ZodString;
+    schemaVersion: z.ZodDefault<z.ZodString>;
+    replayability: z.ZodDefault<z.ZodEnum<["deterministic", "stochastic_recorded", "stochastic_unreproducible"]>>;
+    payload: z.ZodDefault<z.ZodUnknown>;
+    human: z.ZodObject<{
+        title: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        why: z.ZodOptional<z.ZodString>;
+        next: z.ZodOptional<z.ZodString>;
+        severity: z.ZodDefault<z.ZodEnum<["info", "notice", "warn", "error"]>>;
+        iconHint: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        severity: "warn" | "info" | "notice" | "error";
+        title: string;
+        detail?: string | undefined;
+        why?: string | undefined;
+        next?: string | undefined;
+        iconHint?: string | undefined;
+    }, {
+        title: string;
+        severity?: "warn" | "info" | "notice" | "error" | undefined;
+        detail?: string | undefined;
+        why?: string | undefined;
+        next?: string | undefined;
+        iconHint?: string | undefined;
+    }>;
+    actor: z.ZodDefault<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodEnum<["machine", "human"]>>;
+        id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "machine" | "human";
+        id?: string | undefined;
+    }, {
+        kind?: "machine" | "human" | undefined;
+        id?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    ts: string;
+    human: {
+        severity: "warn" | "info" | "notice" | "error";
+        title: string;
+        detail?: string | undefined;
+        why?: string | undefined;
+        next?: string | undefined;
+        iconHint?: string | undefined;
+    };
+    seq: number;
+    eventId: string;
+    schemaVersion: string;
+    replayability: "deterministic" | "stochastic_recorded" | "stochastic_unreproducible";
+    actor: {
+        kind: "machine" | "human";
+        id?: string | undefined;
+    };
+    payload?: unknown;
+}, {
+    type: string;
+    ts: string;
+    human: {
+        title: string;
+        severity?: "warn" | "info" | "notice" | "error" | undefined;
+        detail?: string | undefined;
+        why?: string | undefined;
+        next?: string | undefined;
+        iconHint?: string | undefined;
+    };
+    seq: number;
+    eventId: string;
+    payload?: unknown;
+    schemaVersion?: string | undefined;
+    replayability?: "deterministic" | "stochastic_recorded" | "stochastic_unreproducible" | undefined;
+    actor?: {
+        kind?: "machine" | "human" | undefined;
+        id?: string | undefined;
+    } | undefined;
+}>;
+export type RootEvent = z.infer<typeof rootEvent>;
+/** append 入参: seq/eventId/ts 由 store 生成. */
+export type RawEvent = {
+    type: string;
+    payload?: unknown;
+    human: z.input<typeof humanNarrative>;
+    actor?: z.input<typeof actor>;
+    replayability?: Replayability;
+    schemaVersion?: string;
+};

package/dist/events/eventSchema.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { ulid } from '../schema/common.js';
+export const EVENT_SCHEMA_VERSION = '1.0.0';
+export const replayability = z.enum(['deterministic', 'stochastic_recorded', 'stochastic_unreproducible']);
+/** 每事件自带叙述 (军杰 §9.2). title 必填. */
+export const humanNarrative = z.object({
+    title: z.string().min(1).max(80),
+    detail: z.string().optional(),
+    why: z.string().optional(),
+    next: z.string().optional(),
+    severity: z.enum(['info', 'notice', 'warn', 'error']).default('info'),
+    iconHint: z.string().optional(),
+});
+/** 人/机操作审计 (军杰 §9.7). */
+export const actor = z.object({
+    kind: z.enum(['machine', 'human']).default('machine'),
+    id: z.string().optional(),
+});
+/** AE 事件信封 (军杰 §3.2). 内部类型 camelCase. */
+export const rootEvent = z.object({
+    seq: z.number().int().nonnegative(),
+    eventId: ulid,
+    ts: z.string().datetime(),
+    type: z.string().min(1),
+    schemaVersion: z.string().default(EVENT_SCHEMA_VERSION),
+    replayability: replayability.default('deterministic'),
+    payload: z.unknown().default({}),
+    human: humanNarrative,
+    actor: actor.default({ kind: 'machine' }),
+});

package/dist/events/eventStore.d.ts

@@ -0,0 +1,32 @@
+import { type RootEvent, type RawEvent } from './eventSchema.js';
+/** 单行字节上限, 保 O_APPEND+write 在 ext4 的原子性 (军杰 §3.2). */
+export declare const MAX_LINE_BYTES = 4096;
+export declare class LineTooLargeError extends Error {
+    readonly bytes: number;
+    constructor(bytes: number);
+}
+export interface EventStoreOptions {
+    path: string;
+    /** Injectable clock for the event `ts` (ms epoch). Defaults to the real clock; inject for deterministic tests. */
+    now?: () => number;
+}
+/** 唯一权威事件流 (AE). single-writer / append-only / seq 递增 / fsync. */
+export declare class EventStore {
+    readonly path: string;
+    private readonly lockPath;
+    private readonly now;
+    private chain;
+    constructor(opts: EventStoreOptions);
+    /** 唯一写路径: 生成 seq/eventId/ts, 校验, 原子 append + fsync. */
+    append(raw: RawEvent): Promise<RootEvent>;
+    private appendLocked;
+    /** 读全部事件 (跳过尾部半行/损坏行). */
+    readAll(): RootEvent[];
+    iterate(fromSeq?: number): Generator<RootEvent>;
+    tail(n?: number): RootEvent[];
+    /** 截断尾部半行 (崩溃恢复). */
+    recover(): {
+        truncated: boolean;
+    };
+    private lastSeqFromFile;
+}

package/dist/events/eventStore.js

@@ -0,0 +1,137 @@
+import { openSync, writeSync, fsyncSync, closeSync, statSync, readSync, mkdirSync, existsSync, truncateSync, readFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { monotonicFactory } from 'ulid';
+import { acquireLock, releaseLock } from '../util/fileLock.js';
+// Monotonic ULIDs: plain ulid() randomizes the low 80 bits, so two ids minted in the SAME millisecond can sort
+// out of order — the event log wants time-sortable eventIds (and a flaky CI test proved it). The monotonic
+// factory increments within a millisecond, guaranteeing each successive eventId is strictly greater.
+const makeUlid = monotonicFactory();
+import { rootEvent, EVENT_SCHEMA_VERSION } from './eventSchema.js';
+/** 单行字节上限, 保 O_APPEND+write 在 ext4 的原子性 (军杰 §3.2). */
+export const MAX_LINE_BYTES = 4096;
+export class LineTooLargeError extends Error {
+    bytes;
+    constructor(bytes) {
+        super(`root_event line ${bytes}B exceeds ${MAX_LINE_BYTES}B; 大 payload 须走 artifact 引用`);
+        this.bytes = bytes;
+        this.name = 'LineTooLargeError';
+    }
+}
+/** 唯一权威事件流 (AE). single-writer / append-only / seq 递增 / fsync. */
+export class EventStore {
+    path;
+    lockPath;
+    now;
+    chain = Promise.resolve();
+    constructor(opts) {
+        this.path = opts.path;
+        this.lockPath = `${opts.path}.lock`;
+        this.now = opts.now ?? Date.now;
+        mkdirSync(dirname(this.path), { recursive: true });
+    }
+    /** 唯一写路径: 生成 seq/eventId/ts, 校验, 原子 append + fsync. */
+    async append(raw) {
+        const run = this.chain.then(() => this.appendLocked(raw));
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    appendLocked(raw) {
+        // Crash-recoverable, pid-aware O_EXCL lock shared with every other persistence path (localJsonl /
+        // materialStore / mailbox / pendingSignals): it reclaims a stale lock left by a crashed writer instead of
+        // deadlocking every future append until the .lock is deleted by hand.
+        acquireLock(this.lockPath);
+        try {
+            const seq = this.lastSeqFromFile() + 1;
+            const evt = rootEvent.parse({
+                seq,
+                eventId: makeUlid(),
+                ts: new Date(this.now()).toISOString(),
+                type: raw.type,
+                schemaVersion: raw.schemaVersion ?? EVENT_SCHEMA_VERSION,
+                replayability: raw.replayability ?? 'deterministic',
+                payload: raw.payload ?? {},
+                human: raw.human,
+                actor: raw.actor ?? { kind: 'machine' },
+            });
+            const line = `${JSON.stringify(evt)}\n`;
+            const bytes = Buffer.byteLength(line, 'utf8');
+            if (bytes > MAX_LINE_BYTES)
+                throw new LineTooLargeError(bytes);
+            const fd = openSync(this.path, 'a');
+            try {
+                writeSync(fd, line);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return evt;
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+    }
+    /** 读全部事件 (跳过尾部半行/损坏行). */
+    readAll() {
+        if (!existsSync(this.path))
+            return [];
+        const out = [];
+        for (const l of readFileSync(this.path, 'utf8').split('\n')) {
+            if (!l)
+                continue;
+            try {
+                out.push(rootEvent.parse(JSON.parse(l)));
+            }
+            catch { /* 崩溃半行: 跳过 */ }
+        }
+        return out;
+    }
+    *iterate(fromSeq = 0) {
+        for (const e of this.readAll())
+            if (e.seq >= fromSeq)
+                yield e;
+    }
+    tail(n = 1) {
+        const all = this.readAll();
+        return all.slice(Math.max(0, all.length - n));
+    }
+    /** 截断尾部半行 (崩溃恢复). */
+    recover() {
+        if (!existsSync(this.path))
+            return { truncated: false };
+        const buf = readFileSync(this.path);
+        if (buf.length === 0)
+            return { truncated: false };
+        const lastNl = buf.lastIndexOf(0x0a);
+        if (lastNl === buf.length - 1)
+            return { truncated: false };
+        truncateSync(this.path, lastNl + 1);
+        return { truncated: true };
+    }
+    lastSeqFromFile() {
+        if (!existsSync(this.path))
+            return 0;
+        const size = statSync(this.path).size;
+        if (size === 0)
+            return 0;
+        const readBytes = Math.min(8192, size);
+        const fd = openSync(this.path, 'r');
+        try {
+            const buf = Buffer.alloc(readBytes);
+            readSync(fd, buf, 0, readBytes, size - readBytes);
+            const lines = buf.toString('utf8').split('\n').filter((l) => l.length > 0);
+            for (let i = lines.length - 1; i >= 0; i--) {
+                try {
+                    const o = JSON.parse(lines[i]);
+                    if (typeof o.seq === 'number')
+                        return o.seq;
+                }
+                catch { /* skip */ }
+            }
+            return 0;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}

package/dist/events/ingest.d.ts

@@ -0,0 +1,34 @@
+import { EventStore, type EventStoreOptions } from './eventStore.js';
+import type { RawEvent, RootEvent } from './eventSchema.js';
+import type { EventSink } from './sink.js';
+/** 已知事件类型 (军杰 §9; 可 registerEventType 扩展). */
+export declare const EVENT_TYPES: readonly ["cycle.started", "cycle.signals_collected", "cycle.solidified", "cycle.failed", "cycle.aborted", "cycle.heartbeat", "cycle.consumed", "decision.gene_selected", "decision.triggered", "decision.suppressed", "personality.selected", "personality.risk_gated", "personality.mutated", "personality.stats_updated", "personality.pivoted", "signals.extracted", "mutation.built", "capsule.produced", "evolution_event.projected", "observer.quarantined", "observer.dead_letter", "actor.human.nudge", "actor.human.intervene", "actor.human.teach", "actor.human.observe", "actor.human.review.approve", "actor.human.review.reject", "gene.distilled", "gene.distill_shadowed", "anti_gene.distilled", "anti_gene.distill_shadowed", "anti_gene.benchmark_result", "anti_gene.rollout_result", "reflection.recorded", "material.batch_ready", "value.reuse_hit", "value.inject", "value.reuse_outcome", "value.recall"];
+export type EventType = (typeof EVENT_TYPES)[number];
+export declare function registerEventType(t: string): void;
+export declare function isKnownEventType(t: string): boolean;
+export declare class IngestValidationError extends Error {
+    constructor(message: string);
+}
+export declare class UnknownEventTypeError extends Error {
+    readonly type: string;
+    constructor(type: string);
+}
+export type IngestorOptions = (EventStoreOptions | {
+    store: EventStore;
+}) & {
+    sink?: EventSink;
+};
+/** root_events 的全仓唯一写入口 (军杰 §9.2). EventStore 不对外暴露 (见 public.ts). */
+export declare class Ingestor {
+    private readonly store;
+    private readonly sink;
+    constructor(opts: IngestorOptions);
+    ingest(raw: RawEvent): Promise<RootEvent>;
+    readAll(): RootEvent[];
+    iterate(fromSeq?: number): Generator<RootEvent>;
+    tail(n?: number): RootEvent[];
+    recover(): {
+        truncated: boolean;
+    };
+    get path(): string;
+}

package/dist/events/ingest.js

@@ -0,0 +1,61 @@
+import { EventStore } from './eventStore.js';
+/** 已知事件类型 (军杰 §9; 可 registerEventType 扩展). */
+export const EVENT_TYPES = [
+    'cycle.started', 'cycle.signals_collected', 'cycle.solidified', 'cycle.failed',
+    'cycle.aborted', 'cycle.heartbeat', 'cycle.consumed',
+    'decision.gene_selected', 'decision.triggered', 'decision.suppressed',
+    'personality.selected', 'personality.risk_gated',
+    'personality.mutated', 'personality.stats_updated', 'personality.pivoted',
+    'signals.extracted', 'mutation.built', 'capsule.produced', 'evolution_event.projected',
+    'observer.quarantined', 'observer.dead_letter',
+    'actor.human.nudge', 'actor.human.intervene', 'actor.human.teach', 'actor.human.observe',
+    'actor.human.review.approve', 'actor.human.review.reject',
+    'gene.distilled', 'gene.distill_shadowed',
+    'anti_gene.distilled', 'anti_gene.distill_shadowed',
+    'anti_gene.benchmark_result', 'anti_gene.rollout_result',
+    'reflection.recorded',
+    'material.batch_ready',
+    'value.reuse_hit', 'value.inject', 'value.reuse_outcome', 'value.recall',
+];
+const knownTypes = new Set(EVENT_TYPES);
+export function registerEventType(t) { knownTypes.add(t); }
+export function isKnownEventType(t) { return knownTypes.has(t); }
+export class IngestValidationError extends Error {
+    constructor(message) { super(message); this.name = 'IngestValidationError'; }
+}
+export class UnknownEventTypeError extends Error {
+    type;
+    constructor(type) {
+        super(`未知事件类型: ${type}`);
+        this.type = type;
+        this.name = 'UnknownEventTypeError';
+    }
+}
+/** root_events 的全仓唯一写入口 (军杰 §9.2). EventStore 不对外暴露 (见 public.ts). */
+export class Ingestor {
+    store;
+    sink;
+    constructor(opts) {
+        this.store = 'store' in opts ? opts.store : new EventStore(opts);
+        this.sink = opts.sink;
+    }
+    async ingest(raw) {
+        if (!isKnownEventType(raw.type))
+            throw new UnknownEventTypeError(raw.type);
+        if (!raw.human || typeof raw.human.title !== 'string' || raw.human.title.length === 0)
+            throw new IngestValidationError('human.title 必填 (军杰 §9.2)');
+        if (raw.type.startsWith('decision.') && !raw.human.why)
+            throw new IngestValidationError(`${raw.type}: decision.* 必填 human.why (Why 面板)`);
+        if (raw.actor?.kind === 'human' && !raw.actor.id)
+            throw new IngestValidationError('actor.kind=human 必带 actor.id (审计, 军杰 §9.7)');
+        const evt = await this.store.append(raw);
+        this.sink?.dispatch(evt);
+        return evt;
+    }
+    // 读 passthrough (写只能经 ingest)
+    readAll() { return this.store.readAll(); }
+    iterate(fromSeq = 0) { return this.store.iterate(fromSeq); }
+    tail(n = 1) { return this.store.tail(n); }
+    recover() { return this.store.recover(); }
+    get path() { return this.store.path; }
+}

package/dist/events/paths.d.ts

@@ -0,0 +1,22 @@
+/** ~/.evomap, 可 EVOLVER_HOME/EVOMAP_HOME 覆盖. */
+export declare function evomapHome(): string;
+export declare function rootEventsPath(): string;
+export declare function mvDir(): string;
+/** 可进化人格模型持久化文件 (五维向量 + 各键统计 + 变更历史). v1 personality_state.json 的 v2 落点. */
+export declare function personalityStatePath(): string;
+export declare function assetsDir(): string;
+/** M1 raw-material substrate (append-only jsonl consumed by the cycle). */
+export declare function materialDir(): string;
+/** MaterialStore backing file. */
+export declare function materialStorePath(): string;
+/** Per-source watermark cursor used to make re-ingest idempotent (file-level dedup). */
+export declare function materialWatermarkPath(): string;
+/** Proxy LLM-trace day-files dir (`llm-trace-YYYYMMDD.jsonl`), the route-savings source for the value ledger.
+ *  Mirrors the proxy's EVOLVER_LLM_TRACE_DIR default so the outreach layer reads what the proxy wrote. */
+export declare function tracesDir(): string;
+/** Hub-asset audit trail (`asset_call_log.jsonl`): one JSONL line per hub-asset interaction (search hit/miss,
+ *  reuse/reference, publish, review). Written best-effort by AssetCallLog; the desktop's RecallHistory / 召回历程
+ *  reads it. Defaults to the evomap home root, beside assets/ + evolution/.
+ *  NOTE(reuse/#234): confirm this matches where the proxy/RecallHistory reads — best-effort append, so a path
+ *  mismatch degrades the audit line, never the reuse write itself. */
+export declare function assetCallLogPath(): string;

package/dist/events/paths.js

@@ -0,0 +1,44 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** ~/.evomap, 可 EVOLVER_HOME/EVOMAP_HOME 覆盖. */
+export function evomapHome() {
+    return process.env['EVOLVER_HOME'] ?? process.env['EVOMAP_HOME'] ?? join(homedir(), '.evomap');
+}
+export function rootEventsPath() {
+    return join(evomapHome(), 'evolution', 'root_events.jsonl');
+}
+export function mvDir() {
+    return join(evomapHome(), 'evolution', 'mv');
+}
+/** 可进化人格模型持久化文件 (五维向量 + 各键统计 + 变更历史). v1 personality_state.json 的 v2 落点. */
+export function personalityStatePath() {
+    return join(evomapHome(), 'evolution', 'personality_state.json');
+}
+export function assetsDir() {
+    return join(evomapHome(), 'assets');
+}
+/** M1 raw-material substrate (append-only jsonl consumed by the cycle). */
+export function materialDir() {
+    return join(evomapHome(), 'evolution', 'material');
+}
+/** MaterialStore backing file. */
+export function materialStorePath() {
+    return join(materialDir(), 'material.jsonl');
+}
+/** Per-source watermark cursor used to make re-ingest idempotent (file-level dedup). */
+export function materialWatermarkPath() {
+    return join(materialDir(), 'watermark.json');
+}
+/** Proxy LLM-trace day-files dir (`llm-trace-YYYYMMDD.jsonl`), the route-savings source for the value ledger.
+ *  Mirrors the proxy's EVOLVER_LLM_TRACE_DIR default so the outreach layer reads what the proxy wrote. */
+export function tracesDir() {
+    return process.env['EVOLVER_LLM_TRACE_DIR'] ?? join(evomapHome(), 'proxy', 'traces');
+}
+/** Hub-asset audit trail (`asset_call_log.jsonl`): one JSONL line per hub-asset interaction (search hit/miss,
+ *  reuse/reference, publish, review). Written best-effort by AssetCallLog; the desktop's RecallHistory / 召回历程
+ *  reads it. Defaults to the evomap home root, beside assets/ + evolution/.
+ *  NOTE(reuse/#234): confirm this matches where the proxy/RecallHistory reads — best-effort append, so a path
+ *  mismatch degrades the audit line, never the reuse write itself. */
+export function assetCallLogPath() {
+    return join(evomapHome(), 'asset_call_log.jsonl');
+}

package/dist/events/projectors.d.ts

@@ -0,0 +1,9 @@
+import type { Projector } from './replayer.js';
+/** demo MV: 按 type 计数 + lastSeq (真 cycle timeline 见 M0-9). */
+export interface EventCountsMV {
+    total: number;
+    byType: Record<string, number>;
+    lastSeq: number;
+}
+export declare const eventCountsProjector: Projector<EventCountsMV>;
+export declare const DEFAULT_PROJECTORS: readonly Projector[];

package/dist/events/projectors.js

@@ -0,0 +1,11 @@
+import { cycleTimelineProjector } from '../cycle/cycleTimeline.js';
+export const eventCountsProjector = {
+    name: 'event_counts',
+    initial: () => ({ total: 0, byType: {}, lastSeq: 0 }),
+    reduce: (s, e) => ({
+        total: s.total + 1,
+        byType: { ...s.byType, [e.type]: (s.byType[e.type] ?? 0) + 1 },
+        lastSeq: Math.max(s.lastSeq, e.seq),
+    }),
+};
+export const DEFAULT_PROJECTORS = [eventCountsProjector, cycleTimelineProjector];

package/dist/events/public.d.ts

@@ -0,0 +1,14 @@
+export { Ingestor, EVENT_TYPES, registerEventType, isKnownEventType, IngestValidationError, UnknownEventTypeError } from './ingest.js';
+export type { EventType, IngestorOptions } from './ingest.js';
+export { Replayer } from './replayer.js';
+export type { Projector } from './replayer.js';
+export { eventCountsProjector, DEFAULT_PROJECTORS } from './projectors.js';
+export type { EventCountsMV } from './projectors.js';
+export { LineTooLargeError, MAX_LINE_BYTES } from './eventStore.js';
+export { rootEventsPath, evomapHome, mvDir, personalityStatePath, assetsDir, materialDir, materialStorePath, materialWatermarkPath, tracesDir, assetCallLogPath } from './paths.js';
+export { EVENT_SCHEMA_VERSION } from './eventSchema.js';
+export type { RootEvent, RawEvent, HumanNarrative, Actor, Replayability } from './eventSchema.js';
+export { readEvents, statusReport, listCycles, showCycle, listTriggers, dailySummary, buildNarrativeSnapshot, NARRATIVE_DEFAULT_LIMIT, NARRATIVE_MAX_LIMIT, } from './reports.js';
+export { buildRetentionReport, defaultMaterialCursorPath, RETENTION_DEFAULT_MAX_MATERIAL_BYTES, RETENTION_DEFAULT_MAX_MATERIAL_RECORDS, RETENTION_DEFAULT_MAX_ROOT_BYTES, RETENTION_DEFAULT_MAX_ROOT_EVENTS, RETENTION_DEFAULT_ROOT_TAIL_EVENTS, RETENTION_DEFAULT_WATCH_RATIO, } from './retention.js';
+export type { ReportEvent, StatusReport, CycleSummary, CycleTimeline, TriggerRow, DailySummary, NarrativeEntry, NarrativeOutcome, NarrativeSnapshot, NarrativeSnapshotOptions, } from './reports.js';
+export type { MaterialRetentionSnapshot, RetentionReport, RetentionReportOptions, RetentionState, RetentionThresholds, RootRetentionSnapshot, } from './retention.js';

package/dist/events/public.js

@@ -0,0 +1,8 @@
+export { Ingestor, EVENT_TYPES, registerEventType, isKnownEventType, IngestValidationError, UnknownEventTypeError } from './ingest.js';
+export { Replayer } from './replayer.js';
+export { eventCountsProjector, DEFAULT_PROJECTORS } from './projectors.js';
+export { LineTooLargeError, MAX_LINE_BYTES } from './eventStore.js';
+export { rootEventsPath, evomapHome, mvDir, personalityStatePath, assetsDir, materialDir, materialStorePath, materialWatermarkPath, tracesDir, assetCallLogPath } from './paths.js';
+export { EVENT_SCHEMA_VERSION } from './eventSchema.js';
+export { readEvents, statusReport, listCycles, showCycle, listTriggers, dailySummary, buildNarrativeSnapshot, NARRATIVE_DEFAULT_LIMIT, NARRATIVE_MAX_LIMIT, } from './reports.js';
+export { buildRetentionReport, defaultMaterialCursorPath, RETENTION_DEFAULT_MAX_MATERIAL_BYTES, RETENTION_DEFAULT_MAX_MATERIAL_RECORDS, RETENTION_DEFAULT_MAX_ROOT_BYTES, RETENTION_DEFAULT_MAX_ROOT_EVENTS, RETENTION_DEFAULT_ROOT_TAIL_EVENTS, RETENTION_DEFAULT_WATCH_RATIO, } from './retention.js';

package/dist/events/replayer.d.ts

@@ -0,0 +1,26 @@
+import type { RootEvent } from './eventSchema.js';
+/** 纯函数视图投影器: 由 root_events 折叠出 MV. */
+export interface Projector<S = unknown> {
+    readonly name: string;
+    initial(): S;
+    reduce(state: S, event: RootEvent): S;
+}
+/** AE→MV 分层 (军杰 §3.6). MV 由 root_events 确定性重建, 写保护(#write 私有 + 读深冻结). */
+export declare class Replayer {
+    #private;
+    readonly dir: string;
+    private readonly projectors;
+    constructor(opts: {
+        dir: string;
+        projectors: readonly Projector[];
+    });
+    private mvPath;
+    /** 全量重放重建全部 MV (rebuild-views). */
+    rebuild(events: readonly RootEvent[]): void;
+    /** 增量: 单事件更新全部 MV. */
+    apply(event: RootEvent): void;
+    /** 读 MV (深冻结 → 业务代码 mutate 即抛). */
+    read<S>(name: string): Readonly<S>;
+    /** 删除全部 MV (rebuild-views 前). */
+    clear(): void;
+}

package/dist/events/replayer.js

@@ -0,0 +1,67 @@
+import { mkdirSync, existsSync, readFileSync, writeFileSync, rmSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+function deepFreeze(o) {
+    if (o && typeof o === 'object') {
+        for (const v of Object.values(o))
+            deepFreeze(v);
+        Object.freeze(o);
+    }
+    return o;
+}
+/** AE→MV 分层 (军杰 §3.6). MV 由 root_events 确定性重建, 写保护(#write 私有 + 读深冻结). */
+export class Replayer {
+    dir;
+    projectors;
+    constructor(opts) {
+        this.dir = opts.dir;
+        this.projectors = new Map(opts.projectors.map((p) => [p.name, p]));
+        mkdirSync(this.dir, { recursive: true });
+    }
+    mvPath(name) { return join(this.dir, `${name}.json`); }
+    /** 唯一写 MV 路径 (ES 私有, 业务代码无法调用). */
+    #write(name, state) {
+        writeFileSync(this.mvPath(name), `${JSON.stringify({ _mv: true, _projector: name, state }, null, 2)}\n`);
+    }
+    /** 全量重放重建全部 MV (rebuild-views). */
+    rebuild(events) {
+        for (const p of this.projectors.values()) {
+            let s = p.initial();
+            for (const e of events)
+                s = p.reduce(s, e);
+            this.#write(p.name, s);
+        }
+    }
+    /** 增量: 单事件更新全部 MV. */
+    apply(event) {
+        for (const p of this.projectors.values()) {
+            const cur = this.#readRaw(p.name);
+            this.#write(p.name, p.reduce((cur === undefined ? p.initial() : cur), event));
+        }
+    }
+    #readRaw(name) {
+        const path = this.mvPath(name);
+        if (!existsSync(path))
+            return undefined;
+        const o = JSON.parse(readFileSync(path, 'utf8'));
+        return o.state;
+    }
+    /** 读 MV (深冻结 → 业务代码 mutate 即抛). */
+    read(name) {
+        const raw = this.#readRaw(name);
+        if (raw === undefined) {
+            const p = this.projectors.get(name);
+            if (!p)
+                throw new Error(`未注册 projector: ${name}`);
+            return deepFreeze(p.initial());
+        }
+        return deepFreeze(raw);
+    }
+    /** 删除全部 MV (rebuild-views 前). */
+    clear() {
+        if (!existsSync(this.dir))
+            return;
+        for (const f of readdirSync(this.dir))
+            if (f.endsWith('.json'))
+                rmSync(join(this.dir, f));
+    }
+}