@hy-sde-org/dsh-memory-extraction 0.1.2-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hy-sde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/memory/memory-extraction/README.md
+README.md: 25234ba6ae648ede9e26988d72271e257596e5eb
+README.zh.md: c7b48d15b06fe6381c66ad5bfd3824ba6e54a258

package/README.md

@@ -0,0 +1,148 @@
+---
+description: "Automatic long-term-memory extraction at compaction checkpoints: evidence projection, proposal/canonicalization pipeline, gated ctx.memory commit, and durable cursors/receipts/failure ledger (Maka port, slice No. 2)."
+kind: "package-reference"
+---
+
+# @hy-sde-org/dsh-memory-extraction
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-memory-extraction` is the DSH port of Maka's automatic memory-extraction
+trigger: after every `compaction/summary` event (a checkpoint boundary), a
+bounded, fail-open pipeline projects the **user-authored** text of the
+checkpointed range, proposes and canonicalizes durable facts with auxiliary
+model calls, and commits admitted facts into the same project memory bank
+`retain`/`learn` write. It is strictly **additive** to DSH's explicit memory
+surface: the `retain`/`learn`/`memory_edit` tools stay the model-facing path
+and the port intentionally reserves (does not port) Maka's
+`memory_remember`/`memory_extract` verbs.
+
+The package is a **host-plane** Cordis plugin (`inject: ['memory', 'llm']`,
+publishes nothing): one process opens the `memory_extraction` control unit once
+and observes every session's events through an unscoped `ctx.on('session/event')`
+listener (the scope filter admits unscoped listeners globally). Runs are
+per-session serialized and never block the compaction listener.
+
+### Load-bearing rules (ported from Maka)
+
+1. **Evidence is user-authored text only** — project `user/message` events whose
+   `source.kind === 'user'`; assistant text is interpretation-only; tool
+   calls/results, reasoning, and plugin checkpoints are opaque. Evidence is
+   bounded (12 000 chars JSON / 4 000 chars per record / 64 records) and
+   **fail-closed** on overflow.
+2. **Admission is verified** — proposal → admission (verbatim quote check
+   against the bounded evidence + secret rejection) → canonicalization →
+   re-admission, at most **3 auxiliary model calls** per range with a 60 s
+   timeout; failures are contained (fail-open at the runtime boundary).
+3. **The cursor only moves to a committed boundary** — empty ranges still
+   advance (a no-op receipt, no model call); a failed range becomes one pending
+   record retried by the next trigger and then discarded. Write order is
+   items → cursor → receipt, so a crash between cursor and receipt can never
+   double-process.
+4. **Idempotency is deterministic** — operation id = `memory_` + sha256 of
+   `{sessionId, trigger, boundarySeq}`; receipts make replays no-ops and the
+   commit-side dedupe probe heals a crash between items and receipt.
+5. **Subagents are excluded** — the gate re-checks after every model call and
+   rejects child sessions by default (`excludeSubagents: true`).
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+
+## Use this package
+
+The row belongs in the **host composition** — it injects host services
+(`memory`, `llm`), opens the control unit once per process, and must observe
+every session's events. There is no agent-preset contribution and no tool.
+
+```yaml
+# host composition (loaded before any session)
+- id: memory-extraction
+  name: '@hy-sde-org/dsh-memory-extraction'
+  config:
+    backend: sqlite           # storage backend hosting the control unit (default sqlite)
+    enabled: true             # master switch (default true)
+    excludeSubagents: true    # child-agent compactions never extract (default true)
+    # provider: <cheap provider id>  # optional; unset uses the session's routed model config
+    # model: <cheap model id>        # optional; unset uses the session's routed model config
+    importance: 0.5           # bank importance for auto-extracted facts (default 0.5)
+    dedupe: true              # probe the bank before committing duplicates (default true)
+    timeoutMs: 60000          # auxiliary call timeout (default 60000)
+```
+
+Its storage backend must expose a `kv` facet (the shipped `sqlite` backend
+does; `storage-json` does not) — see the
+[example patch](../../../apps/cli/config/examples/memory-extraction/cordis.yml).
+The engine itself is pure and testable without cordis:
+
+```ts
+import { MemoryExtractionEngine } from '@hy-sde-org/dsh-memory-extraction'
+
+const engine = new MemoryExtractionEngine(ports) // readGate/readEvents/read+write cursor+receipt+failure/commitItems/generate
+const result = await engine.execute(snapshot)   // never throws; idempotent by operation id
+```
+
+### Wiring
+
+The plugin boots asynchronously: an effect opens the control unit via
+`storage.backend.<backend>.kv.open(MemoryExtractionControlStore.descriptor)`
+(`memory_extraction`, version 1, tables `cursors`/`receipts`/`failures`) and
+registers the `session/event` listener. A missing backend logs and leaves the
+plugin inert instead of failing composition.
+
+## Understand the implementation
+
+- `src/evidence.ts` — bounded evidence projection, coverage planning
+  (binary-search shrink, fail-closed overflow), the same-session localization
+  search, and quote verification.
+- `src/proposal.ts` — strict hand-rolled JSON parsers (complete /
+  `search_required` / `cannot_resolve` / canonicalization), prompt builders that
+  frame evidence as **untrusted data**, admission (verbatim quotes, min 4 chars,
+  secret rejection, NFC + injection neutralization, 2 000-char content cap).
+- `src/control.ts` — the durable cursor/receipt/failure store over one
+  `KvUnit` (single write chain; heal-on-open; write ordering documented).
+- `src/engine.ts` — the state machine: idempotency receipt, gate, empty-range
+  advance, one-retry-then-discard, 3-call budget, commit ordering.
+- `src/events.ts` — the lossy DSH event projection (user/assistant text only,
+  turn tracking for localization grouping).
+- `src/memory-adapter.ts` — the commit surface over `ctx.memory`: a dedupe probe,
+  then `save` with `source: 'memory_extract'`, plus the gate factory.
+- `src/runtime.ts` — host wiring: per-session sequential queue, generate adapter
+  (`BlockAssembler`, `AbortSignal.timeout`, routed provider/model override),
+  sync/async port implementations over live services.
+
+## Further Exploration
+
+- The Maka source this was ported from: `packages/runtime/src/memory-extraction.ts`
+  in the Maka repository.
+- The compaction lifecycle that emits the boundary events:
+  `@deepseek-ai/dsh-compaction`.
+
+## Model Experience
+
+The pipeline adds up to 3 auxiliary model calls per checkpointed range with
+user-authored text (proposal, optional localization, canonicalization), each
+bounded by `timeoutMs`. Configuring `provider`/`model` to a cheap auxiliary
+model is recommended for large deployments; when unset the session's routed
+request header is used. The model never sees raw logs or tool results — only
+the bounded, user-authored evidence plus a short localization context.
+
+## Known Limitations and Deferred Work
+
+- **One pending failure per session** (retry once, then discard) — Maka keeps
+  richer failure states (e.g. evidence-growth retry), ported as a single later
+  retry.
+- **No persistent re-extraction** on evidence growth: a checkpoint that failed
+  is retried once and then dropped.
+- **Maka facets are not ported** (kind/temporal/scope/tags); every extracted
+  fact lands with `source: 'memory_extract'` and the configured importance.
+- **No per-verb tools**: `memory_remember`/`memory_extract` are reserved names;
+  the explicit DSH memory tools remain the model-facing path.
+- The dedupe probe relies on the local memory bank's `search` seeing previously
+  committed rows (same-process semantics).

package/README.zh.md

@@ -0,0 +1,134 @@
+---
+description: "在压缩检查点自动提取长期记忆：证据投影、提案/规范化流水线、受门控的 ctx.memory 提交，以及持久化的游标/回执/失败账本（Maka 移植，切片 No. 2）。"
+kind: "package-reference"
+---
+
+# @hy-sde-org/dsh-memory-extraction
+
+[English](README.md) | 中文
+
+## 摘要
+
+`dsh-memory-extraction` 是 Maka 自动记忆提取触发器的 DSH 移植：每次
+`compaction/summary` 事件（检查点边界）之后，一个有界、失败开放的流水线投影
+检查点范围内**用户撰写**的文本，用辅助模型调用提出并规范化持久事实，并把通过
+的事实提交到 `retain`/`learn` 使用的同一项目记忆库。它严格**叠加**在 DSH 显式
+记忆能力之上：`retain`/`learn`/`memory_edit` 工具仍是面向模型的路径，移植
+有意保留（不移植）Maka 的 `memory_remember`/`memory_extract` 动词。
+
+本包是**主机平面**的 Cordis 插件（`inject: ['memory', 'llm']`，不发布服务）：
+每进程只打开一次 `memory_extraction` 控制单元，通过无作用域的
+`ctx.on('session/event')` 监听器观察所有会话的事件（作用域过滤器全局接纳无
+作用域监听器）。运行按会话串行，绝不阻塞压缩监听器。
+
+### 承重规则（移植自 Maka）
+
+1. **证据仅限用户撰写文本** —— 投影 `source.kind === 'user'` 的
+   `user/message` 事件；助手文本仅作解读上下文；工具调用/结果、推理块和插件
+   检查点保持不透明。证据有界（12 000 字符 JSON / 单条 4 000 字符 / 64 条）且
+   **失败关闭**（溢出则跳过）。
+2. **准入经核验** —— 提案 → 准入（对有界证据逐字核验引文 + 密钥拒绝）→
+   规范化 → 再准入，每个范围最多 **3 次辅助模型调用**、60 秒超时；失败被包含
+   （在运行时边界失败开放）。
+3. **游标只推进到已提交边界** —— 空范围仍然推进（记无操作回执，不调用模型）；
+   失败范围成为一条待处理记录，由下一次触发重试一次后丢弃。写入顺序为
+   条目 → 游标 → 回执，因此游标与回执之间崩溃永远不会重复处理。
+4. **幂等是确定性的** —— 操作 id = `memory_` + sha256(`{sessionId, trigger,
+   boundarySeq}`)；回执使重放成为空操作，提交侧去重探测修复条目与回执之间的
+   崩溃。
+5. **排除子代理** —— 门控在每次模型调用后重新检查，默认拒绝子会话
+   （`excludeSubagents: true`）。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知局限与延后工作](#known-limitations-and-deferred-work)
+
+<a id="use-this-package"></a>
+## 使用本包
+
+该行属于**主机组合** —— 它注入主机服务（`memory`、`llm`），每进程打开一次
+控制单元，且必须观察所有会话的事件。没有代理预设贡献，也没有工具。
+
+```yaml
+# host composition (loaded before any session)
+- id: memory-extraction
+  name: '@hy-sde-org/dsh-memory-extraction'
+  config:
+    backend: sqlite           # storage backend hosting the control unit (default sqlite)
+    enabled: true             # master switch (default true)
+    excludeSubagents: true    # child-agent compactions never extract (default true)
+    # provider: <cheap provider id>  # optional; unset uses the session's routed model config
+    # model: <cheap model id>        # optional; unset uses the session's routed model config
+    importance: 0.5           # bank importance for auto-extracted facts (default 0.5)
+    dedupe: true              # probe the bank before committing duplicates (default true)
+    timeoutMs: 60000          # auxiliary call timeout (default 60000)
+```
+
+其存储后端必须暴露 `kv` 面（shipped 的 `sqlite` 后端可以；`storage-json`
+不可以）—— 参见
+[示例补丁](../../../apps/cli/config/examples/memory-extraction/cordis.yml)。
+引擎本身是纯的，可在无 cordis 下测试：
+
+```ts
+import { MemoryExtractionEngine } from '@hy-sde-org/dsh-memory-extraction'
+
+const engine = new MemoryExtractionEngine(ports) // readGate/readEvents/read+write cursor+receipt+failure/commitItems/generate
+const result = await engine.execute(snapshot)   // never throws; idempotent by operation id
+```
+
+### 接线
+
+插件异步启动：一个 effect 通过
+`storage.backend.<backend>.kv.open(MemoryExtractionControlStore.descriptor)`
+打开控制单元（`memory_extraction`，版本 1，表 `cursors`/`receipts`/`failures`）
+并注册 `session/event` 监听器。后端缺失时记录日志并保持惰性，而不是让组合失败。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+- `src/evidence.ts` —— 有界证据投影、覆盖规划（二分收缩、溢出失败关闭）、
+  同会话本地化搜索、引文核验。
+- `src/proposal.ts` —— 严格手写 JSON 解析（complete/`search_required`/
+  `cannot_resolve`/规范化）、把证据标示为**不可信数据**的提示词构建、准入
+  （逐字引文、最少 4 字符、密钥拒绝、NFC + 注入中和、内容上限 2 000 字符）。
+- `src/control.ts` —— 单个 `KvUnit` 上的持久化游标/回执/失败存储（单一写入
+  链；打开时自愈；写入顺序有文档说明）。
+- `src/engine.ts` —— 状态机：幂等回执、门控、空范围推进、一次重试后丢弃、
+  3 次调用预算、提交顺序。
+- `src/events.ts` —— 有损的 DSH 事件投影（仅用户/助手文本，为本地化分组跟踪
+  轮次）。
+- `src/memory-adapter.ts` —— 基于 `ctx.memory` 的提交面（去重探测 +
+  `save`，来源 `'memory_extract'`）与门控工厂。
+- `src/runtime.ts` —— 主机接线：按会话的顺序队列、generate 适配器
+  （`BlockAssembler`、`AbortSignal.timeout`、路由 provider/model 覆盖）、
+  基于真实服务的同步/异步端口实现。
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- 移植来源：Maka 仓库 `packages/runtime/src/memory-extraction.ts`。
+- 产生边界事件的压缩生命周期：`@deepseek-ai/dsh-compaction`。
+
+<a id="model-experience"></a>
+## 模型体验
+
+流水线对每个含用户文本的检查点范围最多增加 3 次辅助模型调用（提案、可选
+本地化、规范化），每次受 `timeoutMs` 约束。大型部署建议把 `provider`/`model`
+配置为廉价辅助模型；未配置时使用会话路由的请求头。模型从不接触原始日志或
+工具结果 —— 只有有界的用户证据和一小段本地化上下文。
+
+<a id="known-limitations-and-deferred-work"></a>
+## 已知局限与延后工作
+
+- **每会话仅一条待处理失败**（重试一次后丢弃）—— Maka 保有更丰富的失败
+  状态（如证据增长重试），此处移植为单次延后重试。
+- **证据增长不重提取**：失败的检查点只重试一次即丢弃。
+- **Maka 侧面未移植**（kind/temporal/scope/tags）；每条提取事实以
+  `source: 'memory_extract'` 与配置的重要性落库。
+- **无逐动词工具**：`memory_remember`/`memory_extract` 为保留名；显式 DSH
+  记忆工具仍是面向模型的路径。
+- 去重探测依赖本地记忆库的 `search` 能看到先前提交的行（同进程语义）。

package/dist/control.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The memory-extraction control store: durable per-session cursor, idempotency
+ * receipts, and the single pending-failure record, over one {@link KvUnit}
+ * (`memory_extraction`). Same pattern as `dsh-graph-control`: single write
+ * chain, heal-on-open, no SQL transactions (the storage contract already
+ * forbids concurrent writers on one unit).
+ *
+ * Write ordering is load-bearing: the CURSOR is written before the receipt so
+ * a crash between the two can never double-process a range (the next trigger's
+ * range starts at the new cursor), and a pending failure is written before any
+ * retry settles so a crash mid-retry keeps the pending row.
+ * @module @hy-sde-org/dsh-memory-extraction/control
+ */
+import type { KvUnit } from '@deepseek-ai/dsh-storage';
+import type { MemoryExtractionCursor, MemoryExtractionReceipt, PendingMemoryExtractionFailure } from './types.ts';
+export declare const MEMORY_EXTRACTION_CONTROL_UNIT_NAME = "memory_extraction";
+export declare const MEMORY_EXTRACTION_CONTROL_UNIT_VERSION = 1;
+export declare class MemoryExtractionControlStore {
+    private readonly kv;
+    /** The unit descriptor callers open with `storage.backend.<name>.kv.open(descriptor)`. */
+    static readonly descriptor: {
+        name: string;
+        version: number;
+        tables: ("cursors" | "receipts" | "failures")[];
+        hasGlobal: boolean;
+    };
+    private constructor();
+    /** Open the store over an already-opened unit. */
+    static open(kv: KvUnit): MemoryExtractionControlStore;
+    /** Serialize one read-modify-write over the unit (the single write chain). */
+    private withChain;
+    private tail;
+    readCursor(sessionId: string): Promise<MemoryExtractionCursor | undefined>;
+    /** Advance the watermark. Written before the receipt on every commit path. */
+    writeCursor(cursor: MemoryExtractionCursor): Promise<void>;
+    readReceipt(operationId: string): Promise<MemoryExtractionReceipt | undefined>;
+    writeReceipt(receipt: MemoryExtractionReceipt): Promise<void>;
+    readFailure(sessionId: string): Promise<PendingMemoryExtractionFailure | undefined>;
+    writeFailure(failure: PendingMemoryExtractionFailure): Promise<void>;
+    deleteFailure(sessionId: string): Promise<void>;
+}
+//# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,YAAY,CAAA;AAEnB,eAAO,MAAM,mCAAmC,sBAAsB,CAAA;AACtE,eAAO,MAAM,sCAAsC,IAAI,CAAA;AAQvD,qBAAa,4BAA4B;IASnB,OAAO,CAAC,QAAQ,CAAC,EAAE;IARvC,0FAA0F;IAC1F,MAAM,CAAC,QAAQ,CAAC,UAAU;;;;;MAKzB;IAED,OAAO;IAEP,kDAAkD;IAClD,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,4BAA4B;IAIrD,8EAA8E;IAC9E,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,IAAI,CAAsC;IAI5C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC;IAUhF,8EAA8E;IAC9E,WAAW,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC;IAqBpF,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,8BAA8B,GAAG,SAAS,CAAC;IA8BzF,YAAY,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD"}

package/dist/control.js

@@ -0,0 +1,125 @@
+/**
+ * The memory-extraction control store: durable per-session cursor, idempotency
+ * receipts, and the single pending-failure record, over one {@link KvUnit}
+ * (`memory_extraction`). Same pattern as `dsh-graph-control`: single write
+ * chain, heal-on-open, no SQL transactions (the storage contract already
+ * forbids concurrent writers on one unit).
+ *
+ * Write ordering is load-bearing: the CURSOR is written before the receipt so
+ * a crash between the two can never double-process a range (the next trigger's
+ * range starts at the new cursor), and a pending failure is written before any
+ * retry settles so a crash mid-retry keeps the pending row.
+ * @module @hy-sde-org/dsh-memory-extraction/control
+ */
+export const MEMORY_EXTRACTION_CONTROL_UNIT_NAME = 'memory_extraction';
+export const MEMORY_EXTRACTION_CONTROL_UNIT_VERSION = 1;
+const UNIT_TABLES = ['cursors', 'receipts', 'failures'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export class MemoryExtractionControlStore {
+    kv;
+    /** The unit descriptor callers open with `storage.backend.<name>.kv.open(descriptor)`. */
+    static descriptor = {
+        name: MEMORY_EXTRACTION_CONTROL_UNIT_NAME,
+        version: MEMORY_EXTRACTION_CONTROL_UNIT_VERSION,
+        tables: [...UNIT_TABLES],
+        hasGlobal: false,
+    };
+    constructor(kv) {
+        this.kv = kv;
+    }
+    /** Open the store over an already-opened unit. */
+    static open(kv) {
+        return new MemoryExtractionControlStore(kv);
+    }
+    /** Serialize one read-modify-write over the unit (the single write chain). */
+    withChain(run) {
+        const tail = this.tail;
+        const next = tail.then(run, run);
+        const guarded = next.then(() => { if (this.tail === guarded)
+            this.tail = Promise.resolve(); }, () => { if (this.tail === guarded)
+            this.tail = Promise.resolve(); });
+        this.tail = guarded;
+        return next;
+    }
+    tail = Promise.resolve();
+    /* ── cursor ──────────────────────────────────────────────────────────── */
+    async readCursor(sessionId) {
+        const { tables } = await this.kv.loadAll();
+        const row = tables['cursors']?.[sessionId];
+        if (!isRecord(row))
+            return undefined;
+        const processedSeq = row['processedSeq'];
+        const updatedAt = row['updatedAt'];
+        if (typeof processedSeq !== 'number' || typeof updatedAt !== 'number')
+            return undefined;
+        return { sessionId, processedSeq, updatedAt };
+    }
+    /** Advance the watermark. Written before the receipt on every commit path. */
+    writeCursor(cursor) {
+        return this.withChain(() => this.kv.putRecord('cursors', cursor.sessionId, { ...cursor }));
+    }
+    /* ── receipts (idempotency) ──────────────────────────────────────────── */
+    async readReceipt(operationId) {
+        const { tables } = await this.kv.loadAll();
+        const row = tables['receipts']?.[operationId];
+        if (!isRecord(row))
+            return undefined;
+        const sessionId = row['sessionId'];
+        const status = row['status'];
+        const items = row['items'];
+        const committedAt = row['committedAt'];
+        if (typeof sessionId !== 'string' || typeof status !== 'string' || typeof committedAt !== 'number') {
+            return undefined;
+        }
+        if (!Array.isArray(items) || items.some(item => typeof item !== 'string'))
+            return undefined;
+        return {
+            operationId,
+            sessionId,
+            status: status,
+            items: items,
+            committedAt,
+        };
+    }
+    writeReceipt(receipt) {
+        return this.withChain(() => this.kv.putRecord('receipts', receipt.operationId, { ...receipt }));
+    }
+    /* ── pending failure ─────────────────────────────────────────────────── */
+    async readFailure(sessionId) {
+        const { tables } = await this.kv.loadAll();
+        const row = tables['failures']?.[sessionId];
+        if (!isRecord(row))
+            return undefined;
+        const throughSeq = row['throughSeq'];
+        const coverageHash = row['coverageHash'];
+        const operationId = row['operationId'];
+        const attempts = row['attempts'];
+        const failureClass = row['failureClass'];
+        const failedAt = row['failedAt'];
+        if (typeof throughSeq !== 'number' || typeof coverageHash !== 'string'
+            || typeof operationId !== 'string' || typeof attempts !== 'number'
+            || typeof failureClass !== 'string' || typeof failedAt !== 'number') {
+            return undefined;
+        }
+        const fromSeq = row['fromSeq'];
+        return {
+            sessionId,
+            fromSeq: typeof fromSeq === 'number' ? fromSeq : throughSeq,
+            throughSeq,
+            coverageHash,
+            operationId,
+            attempts,
+            failureClass: failureClass,
+            failedAt,
+        };
+    }
+    writeFailure(failure) {
+        return this.withChain(() => this.kv.putRecord('failures', failure.sessionId, { ...failure }));
+    }
+    deleteFailure(sessionId) {
+        return this.withChain(() => this.kv.deleteRecord('failures', sessionId));
+    }
+}
+//# sourceMappingURL=control.js.map

package/dist/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The memory-extraction engine: a bounded, fail-open pipeline over frozen
+ * evidence. Ported from Maka `memory-extraction.ts` with the compaction-only
+ * surface (no `remember`/`extract` tools, no per-checkpoint policy denials,
+ * no range-splitting) and the same load-bearing rules:
+ *
+ * - evidence is user-authored text only, bounded and fail-closed on overflow;
+ * - proposal → admission → canonicalization → re-admission, with verbatim
+ *   quote verification and deterministic secret rejection;
+ * - the per-session cursor only moves to a committed boundary; empty ranges
+ *   still advance; a failed range becomes one pending record retried by the
+ *   next trigger and then discarded;
+ * - every run is idempotent by deterministic operation id.
+ *
+ * The engine is pure (ports only, no cordis, no live session) so the whole
+ * state machine is unit-testable with fakes.
+ * @module @hy-sde-org/dsh-memory-extraction/engine
+ */
+import type { AdmittedMemoryItem, MemoryExtractionCursor, MemoryExtractionEventEntry, MemoryExtractionGate, MemoryExtractionReceipt, MemoryExtractionRunResult, MemoryExtractionSourceSnapshot, PendingMemoryExtractionFailure } from './types.ts';
+export type MemoryExtractionStage = 'proposal' | 'localized' | 'canonicalize';
+export type MemoryGenerateResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly errorClass: 'aborted' | 'timeout' | 'configuration' | 'provider' | 'persistence' | 'unknown';
+};
+/** The ports the engine drives. One implementation: the host runtime over real services. */
+export interface MemoryExtractionPorts {
+    readGate(snapshot: MemoryExtractionSourceSnapshot): MemoryExtractionGate | Promise<MemoryExtractionGate>;
+    /** Read the session log window `(fromSeq, throughSeq]` as portable text events. */
+    readEvents(sessionId: string, fromSeq: number, throughSeq: number): readonly MemoryExtractionEventEntry[] | Promise<readonly MemoryExtractionEventEntry[]>;
+    readCursor(sessionId: string): MemoryExtractionCursor | undefined | Promise<MemoryExtractionCursor | undefined>;
+    readReceipt(operationId: string): MemoryExtractionReceipt | undefined | Promise<MemoryExtractionReceipt | undefined>;
+    readFailure(sessionId: string): PendingMemoryExtractionFailure | undefined | Promise<PendingMemoryExtractionFailure | undefined>;
+    writeCursor(cursor: MemoryExtractionCursor): void | Promise<void>;
+    writeReceipt(receipt: MemoryExtractionReceipt): void | Promise<void>;
+    writeFailure(failure: PendingMemoryExtractionFailure): void | Promise<void>;
+    deleteFailure(sessionId: string): void | Promise<void>;
+    /** Commit admitted items into the project memory store; returns what was actually stored. */
+    commitItems(input: {
+        readonly sessionId: string;
+        readonly workspaceKey?: string;
+        readonly trigger: MemoryExtractionSourceSnapshot['trigger'];
+        readonly boundarySeq: number;
+        readonly items: readonly AdmittedMemoryItem[];
+    }): {
+        readonly committed: readonly string[];
+    } | Promise<{
+        readonly committed: readonly string[];
+    }>;
+    /** One bounded auxiliary model call. Implementations own the timeout signal. */
+    generate(input: {
+        readonly snapshot: MemoryExtractionSourceSnapshot;
+        readonly prompt: string;
+        readonly stage: MemoryExtractionStage;
+    }): MemoryGenerateResult | Promise<MemoryGenerateResult>;
+    now?(): number;
+}
+/** Max auxiliary model calls per range (Maka: 3). */
+export declare const MAX_MEMORY_EXTRACTION_MODEL_CALLS = 3;
+/** One later retry after a settled failure, then discard (Maka keeps more states). */
+export declare const MAX_FAILURE_ATTEMPTS = 2;
+export declare class MemoryExtractionEngine {
+    private readonly ports;
+    constructor(ports: MemoryExtractionPorts);
+    execute(snapshot: MemoryExtractionSourceSnapshot): Promise<MemoryExtractionRunResult>;
+    private processRange;
+    private processCoverage;
+    private commitEmpty;
+    private settleCountedFailure;
+    private callModel;
+    private allowed;
+    private now;
+}
+export declare function memoryExtractionOperationId(snapshot: MemoryExtractionSourceSnapshot): string;
+export declare function memoryCoverageHash(entries: readonly MemoryExtractionEventEntry[], fromSeq: number, throughSeq: number): string;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}