@deepseek-ai/dsh-message-feedback 0.0.1-rc.2

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/feedback/message-feedback/README.md
+README.md: 54c6b92fbb68027a4aedb198948785183661a724
+README.zh.md: 29cbee0c1ec2ee810948d895c762d2e6320e9b66

package/README.md

@@ -0,0 +1,84 @@
+# @deepseek-ai/dsh-message-feedback
+
+English | [中文](README.zh.md)
+
+Host-owned editable feedback for one finalized assistant message. The package registers `ctx.messageFeedback`, persists one lifecycle-bound sidecar row per Session in storage-domain, and publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract. It is separate from the immutable Session-level `feedback/record` event and performs no telemetry handoff. The [message-feedback sidecar Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md) owns the design boundary.
+
+Public request, value, version, and failure types are exported from the package root and `@deepseek-ai/dsh-message-feedback/types`; [`src/types.ts`](src/types.ts) is their source.
+
+## Configuration
+
+| key | meaning |
+|---|---|
+| `maxNoteBytes` | Required positive safe integer: maximum UTF-8 byte length of one optional note. |
+
+Notes must contain at least one non-whitespace character, but accepted text is stored verbatim rather than trimmed. Omitting `note` means the desired value has no note, so a version-matched material `put` clears an existing note. Note validation precedes Session lookup and can therefore return `note-blank` or `note-too-large` for a missing Session without touching persistence.
+
+```yaml
+- id: message-feedback
+  name: '@deepseek-ai/dsh-message-feedback'
+  config:
+    maxNoteBytes: 8192
+```
+
+The service injects `storageDomain`, `sessionPersistence`, and `sessions`. Its durable domain is `message_feedback`, with one `sessions` table row per `SessionId`.
+
+## Data, lifecycle, and durability
+
+`MessageFeedbackItem` contains `messageId`, `rating: 'positive' | 'negative'`, optional `note`, an opaque equality-only `version`, and Host-assigned `createdAt`/`updatedAt` Unix-millisecond timestamps. A material update preserves `createdAt`, replaces `version`, and keeps `updatedAt` from moving backward. `list` returns fresh immutable snapshots in first-creation order; updating an item retains its place, while deleting and later recreating it appends a new item.
+
+Each stored row carries the inspected Session header identity `{createdAt, cwd}`. A mismatch is treated as absence: `list` returns an empty `items` array, `delete` returns the absent postcondition, and `put` may replace the stale row with one bound to the current identity. This fences a reused `SessionId` when its header identity differs. Forks use a distinct Session identity and receive no feedback-row copy.
+
+`SessionPersistence.inspect()` supplies a cold-safe observation without publishing or resuming an Agent and without committing cold repair. For a Session without a live owner, `listSnapshots()` first decides definite absence; an `inspect()` failure for a catalogued Session remains an infrastructure failure rather than being guessed into `session-not-found`. `put` accepts only a non-empty, append-origin `assistant/message` with the requested `MessageId`; replacement-origin messages, empty usage-only assistant records, and non-assistant records return `target-not-found`.
+
+After initial validation, `put` establishes a durability barrier before writing the sidecar. A matching live Session commits through the canonical `ctx.sessions.flush` checkpoint, then both live and cold paths are physically read from sequence zero through `SessionPersistence.readFrom`. The resulting observation's header identity and target are validated again. A missing flush participant, changed identity, vanished target, or physical-read failure prevents the sidecar commit, so durable feedback never precedes the durable target message.
+
+Message feedback is not Session-log content or a Session projection. It emits no `feedback/record` event, does not enter model history, and does not trigger `FEEDBACK_ONLY` telemetry release.
+
+## Service and Host Remote contract
+
+The same three `MessageFeedbackService` methods are published by `GatewayService` and `@Remote`; the Host endpoint names are `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete`. Every method returns a discriminated business union: `{ ok: true, value }` or `{ ok: false, error }`. Operational storage, corruption, or missing-durability-listener failures reject instead of being mislabeled as business errors.
+
+| Method | Request | Success `value` | Rejected `error.code` |
+|---|---|---|---|
+| `list` | `MessageFeedbackListRequest { sessionId }` | `MessageFeedbackListValue { items }` | `session-not-found` |
+| `put` | `MessageFeedbackPutRequest { sessionId, messageId, rating, note?, ifVersion }` | committed `MessageFeedbackItem` | `session-not-found`, `target-not-found`, `version-conflict`, `note-blank`, `note-too-large` |
+| `delete` | `MessageFeedbackDeleteRequest { sessionId, messageId, ifVersion }` | `MessageFeedbackDeleteValue { absent: true }` | `session-not-found`, `version-conflict` |
+
+`MessageFeedbackVersionConflict` returns the authoritative `current` item, or `null` when no item exists. This lets a caller reconcile the current rating, note, and version without a second `list` request. `MessageFeedbackNoteTooLarge` returns both `maxBytes` and `actualBytes`. The Client Remote aggregate does not mount the generated client contribution yet; Host callers can use the service/Remote contract without that client assembly.
+
+## Compare-and-set and idempotency
+
+`ifVersion: null` requests creation only; every request for an existing item requires its exact current version, including a no-op whose desired value already matches. The check is per message rather than per Session, so changing one item does not conflict with another. Every material create or update assigns a fresh opaque UUID token, preventing stale writes from crossing an ABA value cycle.
+
+A matching-version no-op returns the already stored item with unchanged version and timestamps. After a lost success response, a retry with the old token receives `version-conflict.current`; the caller can compare that authoritative item with its desired value without an extra read. `delete` ignores `ifVersion` when the item is already absent and always returns the stable `{ absent: true }` postcondition after success.
+
+A per-Session promise queue encloses inspection, durability validation, sidecar read, comparison, and whole-row write. These semantics serialize concurrent mutations through one service instance; storage-domain itself has no cross-process conditional write.
+
+Plugin disposal closes mutation admission, drains every operation already accepted into the per-Session queues, and only then closes the storage domain. A mutation submitted after disposal begins rejects as a lifecycle failure instead of entering a closing domain.
+
+## Model Experience
+
+### Local message-feedback state
+
+#### What the model sees
+
+Nothing. `ctx.messageFeedback` registers no tool, prompt section, model-facing context, or Session event; feedback stays in a Host-owned sidecar unless a separately documented Consumer explicitly exposes it.
+
+#### Token effect
+
+Zero. No request, result, rating, note, timestamp, or failure from this package enters a model request.
+
+#### KV Cache effect
+
+Independent. Listing or mutating message feedback does not touch a model request prefix and cannot invalidate an otherwise reusable provider cache entry.
+
+## Known Limitations and Deferred Work
+
+- **Client aggregate and UI are absent** — the Host Remote contract ships, but the Client Remote aggregate contribution and any UI consumer are separately owned and deferred.
+- **Compare-and-set is single-process** — the per-Session queue serializes one service instance only; multiple Host processes writing one storage root can still lose updates because storage-domain exposes no cross-process conditional write.
+- **No durable Session deletion cascade** — Session persistence has no deletion API, and `session/disposed`/`host/session-removed` mean detach rather than durable deletion. The service therefore retains empty rows and may leave orphan rows after out-of-band log removal instead of deleting valid feedback on detach.
+- **Detach/catalog retirement window** — a request in the narrow interval after live detach but before the persistence catalog materializes the header can receive `session-not-found`; callers retry after retirement materialization.
+- **Header identity is not a content fingerprint** — `{createdAt, cwd}` detects reuse only when those fields differ; a cloned log retaining the same header identity is indistinguishable.
+- **Trusted caller boundary** — `list`/`put`/`delete` carry no authenticated actor or audit identity. A deployment must expose the Host gateway only through its trusted or separately authenticated boundary until authorization and attribution are added.
+- **Catalog and row bounds** — a cold request scans the complete Session snapshot catalog because persistence has no lookup-by-id metadata operation. `maxNoteBytes` bounds one note, but the item count and aggregate retained bytes of one Session row are not capped; an indexed metadata read and deployment-owned row bound remain deferred until a concrete consumer defines their policy.

package/README.zh.md

@@ -0,0 +1,84 @@
+# @deepseek-ai/dsh-message-feedback
+
+[English](README.md) | 中文
+
+本包提供由 Host 拥有、针对单条已完成 assistant 消息的可编辑反馈。它注册 `ctx.messageFeedback`，在 storage-domain 中为每个 Session 持久化一条绑定生命周期的伴随记录（sidecar），并发布 Host `messageFeedback.list`、`messageFeedback.put` 与 `messageFeedback.delete` 一元 Remote 契约。它与不可变的 Session 级 `feedback/record` 事件相互独立，不执行遥测交接。[消息反馈伴随记录 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-message-feedback-sidecar.md)拥有其设计边界。
+
+公开的请求、值、版本与失败类型从包根入口及 `@deepseek-ai/dsh-message-feedback/types` 导出；其源码为 [`src/types.ts`](src/types.ts)。
+
+## 配置
+
+| 键 | 含义 |
+|---|---|
+| `maxNoteBytes` | 必填正 safe integer：一条可选备注的最大 UTF-8 字节长度。 |
+
+备注必须包含至少一个非空白字符，但通过校验的文本按原样存储，不会 trim。省略 `note` 表示目标值不含备注，因此 version 匹配的实质 `put` 会清除已有备注。备注校验早于 Session 查找，因此即使 Session 不存在，也可能在不访问持久化的情况下返回 `note-blank` 或 `note-too-large`。
+
+```yaml
+- id: message-feedback
+  name: '@deepseek-ai/dsh-message-feedback'
+  config:
+    maxNoteBytes: 8192
+```
+
+服务注入 `storageDomain`、`sessionPersistence` 与 `sessions`。其持久存储域为 `message_feedback`，其中 `sessions` 表按 `SessionId` 每个一行。
+
+## 数据、生命周期与持久性
+
+`MessageFeedbackItem` 包含 `messageId`、`rating: 'positive' | 'negative'`、可选 `note`、只能做相等比较的 opaque `version`，以及由 Host 分配、以 Unix 毫秒表示的 `createdAt`/`updatedAt` 时间戳。实质更新保留 `createdAt`、替换 `version`，并保证 `updatedAt` 不倒退。`list` 按首次创建顺序返回新的不可变快照；更新条目时保留其位置，删除后再创建则追加为新条目。
+
+每条存储行都携带检查所得 Session header 身份 `{createdAt, cwd}`。不匹配按不存在处理：`list` 返回空 `items` 数组，`delete` 返回已不存在的后置条件，`put` 可以用绑定当前身份的新行替换陈旧行。这会在复用的 `SessionId` 具有不同 header 身份时形成隔离。fork 使用独立的 Session 身份，不复制反馈伴随记录。
+
+`SessionPersistence.inspect()` 提供 cold-safe 观测，不发布或恢复 Agent，也不提交 cold repair。对于没有 live owner 的 Session，系统先用 `listSnapshots()` 判定明确不存在；已进入目录的 Session 若 `inspect()` 失败，仍属于基础设施故障，不会被猜测成 `session-not-found`。`put` 只接受具有指定 `MessageId` 的非空、append-origin `assistant/message`；replacement-origin 消息、仅承载 usage 的空 assistant 记录与非 assistant 记录都返回 `target-not-found`。
+
+初步校验后，`put` 在写入伴随记录前建立 durability barrier。身份匹配的 live Session 先通过权威 `ctx.sessions.flush` checkpoint 提交，随后 live 与 cold 路径都会通过 `SessionPersistence.readFrom` 从序列零做物理复读。之后再次校验所得观测的 header 身份与目标。缺少 flush 参与方、身份变化、目标消失或物理读取失败都会阻止伴随记录提交，因此持久反馈绝不会先于其持久目标消息。
+
+message feedback 不是 Session 日志内容或 Session 投影。它不发出 `feedback/record` 事件，不进入模型历史，也不触发 `FEEDBACK_ONLY` 遥测释放。
+
+## 服务与 Host Remote 契约
+
+`GatewayService` 与 `@Remote` 将 `MessageFeedbackService` 的同三个方法发布出去；Host endpoint 名称为 `messageFeedback.list`、`messageFeedback.put` 与 `messageFeedback.delete`。每个方法都返回判别式业务 union：`{ ok: true, value }` 或 `{ ok: false, error }`。存储、损坏或缺少 durability listener 等操作故障会产生 reject，不会被误标为业务错误。
+
+| 方法 | 请求 | 成功 `value` | 拒绝的 `error.code` |
+|---|---|---|---|
+| `list` | `MessageFeedbackListRequest { sessionId }` | `MessageFeedbackListValue { items }` | `session-not-found` |
+| `put` | `MessageFeedbackPutRequest { sessionId, messageId, rating, note?, ifVersion }` | 已提交的 `MessageFeedbackItem` | `session-not-found`、`target-not-found`、`version-conflict`、`note-blank`、`note-too-large` |
+| `delete` | `MessageFeedbackDeleteRequest { sessionId, messageId, ifVersion }` | `MessageFeedbackDeleteValue { absent: true }` | `session-not-found`、`version-conflict` |
+
+`MessageFeedbackVersionConflict` 返回权威 `current` 条目；条目不存在时为 `null`。调用方无需额外执行 `list`，即可协调当前 rating、note 与 version。`MessageFeedbackNoteTooLarge` 同时返回 `maxBytes` 与 `actualBytes`。客户端 Remote 聚合尚未挂载生成的客户端 contribution；Host 调用方无需该客户端组装即可使用 service/Remote 契约。
+
+## Compare-and-set 与幂等性
+
+`ifVersion: null` 表示仅当条目不存在时才创建；已有条目的每次请求都必须与其当前 version 完全一致，即使目标值已经相同、不会产生实质更新。检查按消息而非按 Session 进行，因此修改一个条目不会与另一个条目冲突。每次实质创建或更新都会分配新的 opaque UUID token，防止陈旧写入穿过 ABA 值循环。
+
+携带匹配 version 的无变化请求会返回已存条目，version 与时间戳均不变。成功响应丢失后，使用旧 token 重试会得到 `version-conflict.current`；调用方无需额外读取，即可把权威当前值与目标值比较。条目已不存在时，`delete` 忽略 `ifVersion`；成功后始终返回稳定的 `{ absent: true }` 后置条件。
+
+按 Session 划分的 promise 队列覆盖检查、持久性校验、伴随记录读取、比较与整行写入。这些语义会串行化经由同一服务实例的并发变更；storage-domain 自身没有跨进程条件写。
+
+Plugin disposal 会先关闭变更接纳，排空已进入各个 Session 队列的所有操作，然后才关闭 storage domain。disposal 开始后提交的变更会以生命周期故障拒绝，不会进入正在关闭的 domain。
+
+## 模型体验
+
+### 本地消息反馈状态
+
+#### 模型看到的内容
+
+无。`ctx.messageFeedback` 不注册工具、提示词段落、模型可见上下文或 Session 事件；除非另一个具有独立文档的 Consumer 显式公开反馈，否则它只留在 Host 拥有的伴随记录中。
+
+#### Token 影响
+
+为零。本包的请求、结果、评分、备注、时间戳或失败都不会进入模型请求。
+
+#### KV Cache 影响
+
+相互独立。读取或变更消息反馈不会触碰模型请求前缀，也不会使本可复用的提供方缓存条目失效。
+
+## 已知局限与延后工作
+
+- **缺少客户端聚合与 UI**——Host Remote 契约已经发布，但客户端 Remote 聚合 contribution 与任何 UI 消费方由各自边界负责并保持延后。
+- **Compare-and-set 仅限单进程**——按 Session 划分的队列只串行化一个服务实例；storage-domain 不提供跨进程条件写，因此多个 Host 进程写入同一存储根目录时仍可能丢失更新。
+- **没有持久 Session 删除级联**——Session persistence 没有删除接口，且 `session/disposed`/`host/session-removed` 表示 detach 而非持久删除。因此服务会保留空行，并可能在带外移除日志后留下孤儿行，而不会在 detach 时删除仍有效的反馈。
+- **Detach/catalog retirement 窗口**——请求若恰好落在 live detach 之后、persistence catalog 物化 header 之前的极短窗口，可能收到 `session-not-found`；调用方应在 retirement materialization 后重试。
+- **Header 身份不是内容指纹**——只有 `{createdAt, cwd}` 不同时才能识别复用；本契约无法区分保留相同 header 身份的克隆日志。
+- **调用方边界受信任**——`list`/`put`/`delete` 不携带已认证的 actor 或审计身份。在加入授权与归属信息前，部署方必须只通过受信任或另行认证的边界暴露 Host gateway。
+- **目录与行边界**——由于 persistence 没有按 id 读取元数据的操作，cold 请求会扫描完整的 Session snapshot 目录。`maxNoteBytes` 只限制单条备注，单个 Session 行的条目数和聚合保留字节尚无上限；按索引读取元数据和由部署决定的行边界，延后到具体消费方明确策略时处理。

package/lib/index.js

@@ -0,0 +1,420 @@
+import { Buffer } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { Service } from "@deepseek-ai/cordis";
+import s from "@deepseek-ai/schemastery";
+import { deriveEventMessage, isAppendSurfaceEvent } from "@deepseek-ai/dsh-session/surface";
+import { GatewayService, Remote } from "@deepseek-ai/dsh-type-meta";
+import { z } from "zod";
+import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
+//#region lib/types/spec.js
+/**
+* Durable storage-domain declaration for lifecycle-bound message feedback.
+* @module @deepseek-ai/dsh-message-feedback/src/spec
+*/
+const nonNegativeSafeInteger = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+/** Runtime schema for the closed rating vocabulary. */
+const messageFeedbackRatingSchema = z.union([z.literal("positive"), z.literal("negative")]);
+/** Runtime schema for one opaque item version stored on disk. */
+const messageFeedbackVersionSchema = z.uuid().transform((value) => value);
+/** Runtime schema for one current feedback item. */
+const messageFeedbackItemSchema = z.object({
+	messageId: z.string().min(1).transform((value) => value),
+	rating: messageFeedbackRatingSchema,
+	note: z.string().refine((note) => note.trim().length > 0, { message: "message feedback note must contain a non-whitespace character" }).optional(),
+	version: messageFeedbackVersionSchema,
+	createdAt: nonNegativeSafeInteger,
+	updatedAt: nonNegativeSafeInteger
+}).refine((item) => item.updatedAt >= item.createdAt, {
+	path: ["updatedAt"],
+	message: "message feedback updatedAt must not precede createdAt"
+});
+/** Persisted Session fields that fence a sidecar row to one log lifecycle. */
+const messageFeedbackSessionIdentitySchema = z.object({
+	createdAt: nonNegativeSafeInteger,
+	cwd: z.string().optional()
+});
+/**
+* One whole-Session sidecar. Duplicate message ids would make item lookup
+* ambiguous; duplicate versions would break their independent identity.
+*/
+const messageFeedbackRowSchema = z.object({
+	session: messageFeedbackSessionIdentitySchema,
+	items: z.array(messageFeedbackItemSchema)
+}).superRefine((row, ctx) => {
+	const messageIds = /* @__PURE__ */ new Set();
+	const versions = /* @__PURE__ */ new Set();
+	row.items.forEach((item, index) => {
+		if (messageIds.has(item.messageId)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"items",
+				index,
+				"messageId"
+			],
+			message: `duplicate message feedback id '${item.messageId}'`
+		});
+		messageIds.add(item.messageId);
+		if (versions.has(item.version)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"items",
+				index,
+				"version"
+			],
+			message: `duplicate message feedback version '${item.version}'`
+		});
+		versions.add(item.version);
+	});
+});
+/** One lifecycle-bound sidecar record per Session id. */
+const messageFeedbackDomainSpec = defineDomain({
+	name: "message_feedback",
+	version: 0,
+	tables: { sessions: domainTable(messageFeedbackRowSchema) }
+});
+//#endregion
+//#region lib/types/index.js
+/**
+* Durable, lifecycle-bound feedback for finalized assistant messages.
+* @module @deepseek-ai/dsh-message-feedback
+*/
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+/** Immutable empty list reused only as an input to caller-owned copying. */
+const EMPTY_ITEMS = Object.freeze([]);
+/** Validate the one deployment-varying limit at the configuration boundary. */
+function resolveMaxNoteBytes(value) {
+	if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`message-feedback: maxNoteBytes must be a positive safe integer, got ${String(value)}`);
+	return value;
+}
+/** Copy and freeze one item before it crosses the service boundary. */
+function snapshotItem(item) {
+	return Object.freeze({
+		messageId: item.messageId,
+		rating: item.rating,
+		...item.note === void 0 ? {} : { note: item.note },
+		version: item.version,
+		createdAt: item.createdAt,
+		updatedAt: item.updatedAt
+	});
+}
+/** Copy and freeze a list response. */
+function snapshotList(items) {
+	return Object.freeze({ items: Object.freeze(items.map(snapshotItem)) });
+}
+/** Build a frozen success branch. */
+function success(value) {
+	return Object.freeze({
+		ok: true,
+		value
+	});
+}
+/** Build a frozen business-failure branch. */
+function rejected(error) {
+	return Object.freeze({
+		ok: false,
+		error: Object.freeze(error)
+	});
+}
+/** Project the Session fields that distinguish one persisted log lifecycle. */
+function identityOf(header) {
+	return Object.freeze({
+		createdAt: header.createdAt,
+		...header.cwd === void 0 ? {} : { cwd: header.cwd }
+	});
+}
+/** Whether a stored row belongs to the inspected Session lifecycle. */
+function sameIdentity(row, header) {
+	return row.session.createdAt === header.createdAt && row.session.cwd === header.cwd;
+}
+/** Whether two observations name the same persisted Session lifecycle. */
+function sameHeaderIdentity(left, right) {
+	return left.id === right.id && left.createdAt === right.createdAt && left.cwd === right.cwd;
+}
+/** Freeze the replacement row so storage-domain never exposes mutable aliases. */
+function rowSnapshot(session, items) {
+	const copiedItems = items.map(snapshotItem);
+	Object.freeze(copiedItems);
+	return Object.freeze({
+		session,
+		items: copiedItems
+	});
+}
+/** Generate an opaque equality token for one material mutation. */
+function nextVersion() {
+	return randomUUID();
+}
+/**
+* Storage-domain sidecar service. It inspects persisted Session history and
+* never creates or resumes an Agent or Session.
+*/
+let MessageFeedbackService = (() => {
+	let _classSuper = GatewayService;
+	let _instanceExtraInitializers = [];
+	let _list_decorators;
+	let _put_decorators;
+	let _delete_decorators;
+	return class MessageFeedbackService extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_list_decorators = [Remote("list")];
+			_put_decorators = [Remote("put")];
+			_delete_decorators = [Remote("delete")];
+			__esDecorate(this, null, _list_decorators, {
+				kind: "method",
+				name: "list",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "list" in obj,
+					get: (obj) => obj.list
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _put_decorators, {
+				kind: "method",
+				name: "put",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "put" in obj,
+					get: (obj) => obj.put
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _delete_decorators, {
+				kind: "method",
+				name: "delete",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "delete" in obj,
+					get: (obj) => obj.delete
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		static inject = [
+			"storageDomain",
+			"sessionPersistence",
+			"sessions"
+		];
+		/** Loader validation for the required note-size policy. */
+		static Config = s.object({ maxNoteBytes: s.number().step(1).min(1).required() });
+		maxNoteBytes = __runInitializers(this, _instanceExtraInitializers);
+		table;
+		operationTails = /* @__PURE__ */ new Map();
+		mutationAdmissionOpen = true;
+		/**
+		* @param ctx - Host context carrying persistence and the storage-domain form.
+		* @param config - Required note-size policy.
+		*/
+		constructor(ctx, config) {
+			super(ctx, "messageFeedback");
+			this.maxNoteBytes = resolveMaxNoteBytes(config.maxNoteBytes);
+		}
+		/** Open and own the one message-feedback sidecar domain. */
+		async [Service.init]() {
+			const domain = await this.ctx.storageDomain.open(messageFeedbackDomainSpec);
+			this.ctx.effect(() => async () => {
+				this.mutationAdmissionOpen = false;
+				await Promise.all(this.operationTails.values());
+				await domain.close();
+			}, "message-feedback.domainClose");
+			this.table = domain.table("sessions");
+		}
+		/**
+		* Read feedback belonging to the current persisted Session lifecycle.
+		* A stale row from a reused Session id is invisible.
+		* @param request - Session identity to inspect and list.
+		* @returns current immutable items or `session-not-found`.
+		*/
+		async list(request) {
+			const known = await this.inspectSession(request.sessionId);
+			if (!known.ok) return known;
+			const row = this.requireTable().get(request.sessionId);
+			return success(snapshotList(row !== void 0 && sameIdentity(row, known.value.meta) ? row.items : EMPTY_ITEMS));
+		}
+		/**
+		* Create or replace feedback for one derived append-origin assistant
+		* message. Every request must match the addressed item's current version;
+		* a matching no-op returns the stored item without changing its revision.
+		* @param request - target, desired value, and observed item version.
+		* @returns the committed item or an explicit business failure.
+		*/
+		put(request) {
+			const note = this.resolveNote(request.note);
+			if (!note.ok) return Promise.resolve(note);
+			return this.enqueue(request.sessionId, async () => {
+				const known = await this.inspectSession(request.sessionId);
+				if (!known.ok) return known;
+				if (!this.hasFeedbackTarget(known.value, request.messageId)) return rejected({
+					code: "target-not-found",
+					sessionId: request.sessionId,
+					messageId: request.messageId
+				});
+				const durable = await this.ensureTargetDurable(known.value);
+				if (!sameHeaderIdentity(durable.meta, known.value.meta) || !this.hasFeedbackTarget(durable, request.messageId)) return rejected({
+					code: "target-not-found",
+					sessionId: request.sessionId,
+					messageId: request.messageId
+				});
+				const table = this.requireTable();
+				const stored = table.get(request.sessionId);
+				const items = (stored !== void 0 && sameIdentity(stored, durable.meta) ? stored : void 0)?.items ?? EMPTY_ITEMS;
+				const index = items.findIndex((item) => item.messageId === request.messageId);
+				const existing = items[index];
+				if (request.ifVersion !== (existing?.version ?? null)) return rejected(this.versionConflict(existing ?? null));
+				if (existing !== void 0 && existing.rating === request.rating && existing.note === note.value) return success(snapshotItem(existing));
+				const now = Date.now();
+				const item = snapshotItem({
+					messageId: request.messageId,
+					rating: request.rating,
+					...note.value === void 0 ? {} : { note: note.value },
+					version: nextVersion(),
+					createdAt: existing?.createdAt ?? now,
+					updatedAt: existing === void 0 ? now : Math.max(now, existing.updatedAt)
+				});
+				const nextItems = [...items];
+				if (index === -1) nextItems.push(item);
+				else nextItems[index] = item;
+				await table.put(request.sessionId, rowSnapshot(identityOf(durable.meta), nextItems));
+				return success(snapshotItem(item));
+			});
+		}
+		/**
+		* Delete one feedback item. Absence is successful regardless of the
+		* supplied version; an existing item requires an exact version match.
+		* @param request - Session, message, and observed item version.
+		* @returns the stable absent postcondition, or an explicit failure.
+		*/
+		delete(request) {
+			return this.enqueue(request.sessionId, async () => {
+				const known = await this.inspectSession(request.sessionId);
+				if (!known.ok) return known;
+				const table = this.requireTable();
+				const stored = table.get(request.sessionId);
+				const items = (stored !== void 0 && sameIdentity(stored, known.value.meta) ? stored : void 0)?.items ?? EMPTY_ITEMS;
+				const existing = items.find((item) => item.messageId === request.messageId);
+				if (existing === void 0) return success(Object.freeze({ absent: true }));
+				if (request.ifVersion !== existing.version) return rejected(this.versionConflict(existing));
+				await table.put(request.sessionId, rowSnapshot(identityOf(known.value.meta), items.filter((item) => item !== existing)));
+				return success(Object.freeze({ absent: true }));
+			});
+		}
+		/**
+		* Resolve a live owner directly; otherwise use the storage catalog as the
+		* existence authority before inspecting the log. Inspection failures for a
+		* catalogued Session remain infrastructure failures rather than being
+		* guessed into the business `session-not-found` branch.
+		*/
+		async inspectSession(sessionId) {
+			if (this.ctx.sessions.get(sessionId) === void 0) {
+				if (!(await this.ctx.sessionPersistence.listSnapshots()).some((snapshot) => snapshot.header.id === sessionId) && this.ctx.sessions.get(sessionId) === void 0) return rejected({
+					code: "session-not-found",
+					sessionId
+				});
+			}
+			return success(await this.ctx.sessionPersistence.inspect(sessionId));
+		}
+		/** Require the exact finalized append-origin assistant message projection. */
+		hasFeedbackTarget(inspection, messageId) {
+			return inspection.events.some((event) => {
+				if (event.type !== "assistant/message" || !isAppendSurfaceEvent(event)) return false;
+				const message = deriveEventMessage(event);
+				return message?.role === "assistant" && message.id === messageId;
+			});
+		}
+		/**
+		* Put the target log prefix behind a durability barrier before its sidecar.
+		* A live owner flushes through the SessionStore's canonical checkpoint; a
+		* cold owner is re-read from the physical durable prefix.
+		*/
+		async ensureTargetDurable(inspection) {
+			const live = this.ctx.sessions.get(inspection.meta.id);
+			if (live !== void 0 && sameHeaderIdentity(live.header, inspection.meta)) {
+				if (!await this.ctx.sessions.flush(live)) throw new Error(`message-feedback: no durability listener participated for live session '${inspection.meta.id}'`);
+				return await this.ctx.sessionPersistence.readFrom(inspection.meta.id, 0);
+			}
+			return await this.ctx.sessionPersistence.readFrom(inspection.meta.id, 0);
+		}
+		/** Validate optional-note semantics and the configured complete UTF-8 byte bound. */
+		resolveNote(note) {
+			if (note === void 0) return success(void 0);
+			if (note.trim().length === 0) return rejected({ code: "note-blank" });
+			const actualBytes = Buffer.byteLength(note, "utf8");
+			if (actualBytes > this.maxNoteBytes) return rejected({
+				code: "note-too-large",
+				maxBytes: this.maxNoteBytes,
+				actualBytes
+			});
+			return success(note);
+		}
+		/** Return the authoritative item needed to reconcile one failed comparison. */
+		versionConflict(current) {
+			return {
+				code: "version-conflict",
+				current: current === null ? null : snapshotItem(current)
+			};
+		}
+		/** Queue a complete read/compare/write mutation behind this Session's prior mutation. */
+		enqueue(sessionId, operation) {
+			if (!this.mutationAdmissionOpen) return Promise.reject(/* @__PURE__ */ new Error("message-feedback: service is disposing"));
+			const result = (this.operationTails.get(sessionId) ?? Promise.resolve()).then(operation);
+			const tail = result.then(() => void 0, () => void 0);
+			this.operationTails.set(sessionId, tail);
+			return result.finally(() => {
+				if (this.operationTails.get(sessionId) === tail) this.operationTails.delete(sessionId);
+			});
+		}
+		/** Resolve the initialized durable table or fail a broken service lifecycle. */
+		requireTable() {
+			if (this.table === void 0) throw new Error("message-feedback: durable domain is not initialized");
+			return this.table;
+		}
+	};
+})();
+//#endregion
+export { MessageFeedbackService, MessageFeedbackService as default, messageFeedbackDomainSpec, messageFeedbackItemSchema, messageFeedbackRatingSchema, messageFeedbackRowSchema, messageFeedbackSessionIdentitySchema, messageFeedbackVersionSchema };

package/lib/invariant.js

@@ -0,0 +1,20 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion. @module @deepseek-ai/dsh-message-feedback/invariant */
+const PACKAGE_NAME = "@deepseek-ai/dsh-message-feedback";
+/** Cordis companion plugin name. */
+const name = "message-feedback-invariant";
+/** Services required before the companion can reserve and check package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the private typed writer owns current row mutations,
+* the domain schema validates rows on reopen, and no second authority exists.
+*/
+const install = Object.assign(() => {}, { inject: ["messageFeedback"] });
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown