@deepseek-ai/dsh-chunked-list 0.1.5-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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/util/chunked-list/README.md
+README.md: f0af89e5dd6cfdc6388fe90aaeaf2fb70b149827
+README.zh.md: 9f28884ad7414ceeae1d7e624cb20efca9033b25

package/README.md

@@ -0,0 +1,93 @@
+---
+description: "Immutable append-only lists for projection state, with bounded append copying, insertion-order iteration, and Zod checkpoint validation."
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-chunked-list
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-chunked-list` lets callers append values while retaining earlier list versions without copying the whole collection. Callers can iterate every value in insertion order and validate JSON checkpoints with their own value schema. The subagent catalog uses it for immutable projection state.
+
+## 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)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use this list when an append-only collection needs immutable versions and JSON-compatible storage. An empty list is `undefined`; appending returns a new head without modifying existing nodes. The list shares stored values by reference, so callers must treat them as immutable.
+
+```ts
+import { appendChunkedList, iterateChunkedList } from '@deepseek-ai/dsh-chunked-list'
+
+const first = appendChunkedList(undefined, 'first')
+const second = appendChunkedList(first, 'second')
+console.log([...iterateChunkedList(second)])
+```
+
+The example produces `['first', 'second']`; `first` still contains only its original value. `chunkedListSchema(valueSchema)` validates JSON checkpoints and rejects unknown fields, invalid values, and empty or oversized chunks. Use `.optional()` on the schema when the containing field also permits an empty list. See the [source contracts](src/index.ts) for the operations.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The newest chunk stores up to 64 values. Appends copy at most that chunk and share older nodes, taking bounded O(1) work. The capacity controls storage layout, not total list length. Iteration visits all N values in O(N) time and uses O(N / 64) scratch space to visit chunks from oldest to newest. A single capacity constant governs append rollover and recursive Zod validation.
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Persistent list operations and checkpoint validation |
+| [`tests/chunked-list.spec.ts`](tests/chunked-list.spec.ts) | Version isolation, ordering, structural sharing, and checkpoint acceptance |
+
+No runtime invariant companion is published because this library has no independently changing observations; its operations return caller-owned immutable values.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Utility package map](../README.md) — shared primitives.
+- [Subagent catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) — why projection state uses chunks.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this collection registers nothing model-facing.
+
+#### KV Cache effect
+
+Nothing here enters a model request, so provider cache reuse is unaffected.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Append-only access** — callers needing removal or random access need another collection.
+- **Recursive checkpoints** — JSON serialization and schema validation remain subject to runtime nesting limits. Stored values must themselves support the caller's serialization format.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,93 @@
+---
+description: "用于 projection state 的不可变追加列表，提供有界追加复制、按插入顺序迭代和 Zod 检查点校验。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-chunked-list
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-chunked-list` 让调用方追加值并保留早期列表版本，无需复制整个集合。调用方可以按插入顺序迭代所有值，并使用自己的值 schema 校验 JSON 检查点。subagent 目录用它保存不可变的 projection state。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延后工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+当仅追加集合需要不可变版本和兼容 JSON 的存储时，使用此列表。空列表用 `undefined` 表示；追加返回新的头节点，不修改已有节点。列表按引用共享所存的值，因此调用方必须将这些值视为不可变。
+
+```ts
+import { appendChunkedList, iterateChunkedList } from '@deepseek-ai/dsh-chunked-list'
+
+const first = appendChunkedList(undefined, 'first')
+const second = appendChunkedList(first, 'second')
+console.log([...iterateChunkedList(second)])
+```
+
+示例输出 `['first', 'second']`；`first` 仍只包含原来的值。`chunkedListSchema(valueSchema)` 校验 JSON 检查点并拒绝未知字段、无效值和空块或超大块。当外层字段也允许空列表时，在 schema 上使用 `.optional()`。各操作详见[源码约定](src/index.ts)。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部机制——点击展开</summary>
+
+最新的块最多存储 64 个值。追加最多复制该块并共享较旧的节点，工作量为有界 O(1)。容量控制存储布局，不限制列表总长度。迭代以 O(N) 时间访问全部 N 个值，并使用 O(N / 64) 临时空间按从旧到新的顺序访问各块。追加换块与递归 Zod 校验共用一个容量常量。
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 持久化列表操作与检查点校验 |
+| [`tests/chunked-list.spec.ts`](tests/chunked-list.spec.ts) | 版本隔离、排序、结构共享与检查点接受条件 |
+
+此库没有独立变化的观测值，因此不发布运行时不变式伴随模块；其操作返回调用方拥有的不可变值。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [工具包映射](../README.zh.md)——共享原语。
+- [Subagent 目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md)——projection state 使用分块的原因。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为此集合不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+本包没有内容进入模型请求，因此不影响提供方缓存复用。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅追加访问**——需要删除或随机访问的调用方应使用其他集合。
+- **递归检查点**——JSON 序列化与 schema 校验仍受运行时嵌套深度限制。所存的值本身必须支持调用方的序列化格式。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+//#region lib/types/index.js
+/**
+* Persistent append-only lists with bounded copying and JSON checkpoint validation.
+* @module @deepseek-ai/dsh-chunked-list
+*/
+const CHUNK_CAPACITY = 64;
+/**
+* Append without modifying the input, copying at most one 64-value chunk.
+* @param head - current list, or `undefined` for an empty list.
+* @param value - value to retain by reference.
+* @returns new list sharing the unchanged older chunks.
+*/
+function appendChunkedList(head, value) {
+	if (head === void 0 || head.values.length === CHUNK_CAPACITY) return {
+		values: [value],
+		...head === void 0 ? {} : { previous: head }
+	};
+	return {
+		values: [...head.values, value],
+		...head.previous === void 0 ? {} : { previous: head.previous }
+	};
+}
+/**
+* Visit all values in insertion order, with O(N) time and O(N / 64) scratch space.
+* @param head - current list, or `undefined` for an empty list.
+* @returns iterator yielding the stored values by reference, without truncation.
+*/
+function* iterateChunkedList(head) {
+	const chunks = [];
+	for (let chunk = head; chunk !== void 0; chunk = chunk.previous) chunks.push(chunk);
+	for (const chunk of chunks.reverse()) yield* chunk.values;
+}
+/**
+* Validate nonempty list checkpoints, including every stored value and chunk size.
+* @param valueSchema - caller-owned validation for each stored value.
+* @returns recursive Zod schema rejecting empty or oversized chunks and unknown fields.
+*/
+function chunkedListSchema(valueSchema) {
+	const schema = z.lazy(() => z.object({
+		values: z.array(valueSchema).min(1).max(CHUNK_CAPACITY),
+		previous: schema.optional()
+	}).strict());
+	return schema;
+}
+//#endregion
+export { appendChunkedList, chunkedListSchema, iterateChunkedList };

package/lib/types/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Persistent append-only lists with bounded copying and JSON checkpoint validation.
+ * @module @deepseek-ai/dsh-chunked-list
+ */
+import { z } from 'zod';
+/**
+ * Newest chunk of an immutable list; `undefined` represents the empty list.
+ * Values within each chunk follow insertion order. Callers treat nodes, arrays,
+ * and stored values as immutable; operations share values and older chunks.
+ */
+export interface ChunkedList<T> {
+    readonly values: readonly T[];
+    readonly previous?: ChunkedList<T> | undefined;
+}
+/**
+ * Append without modifying the input, copying at most one 64-value chunk.
+ * @param head - current list, or `undefined` for an empty list.
+ * @param value - value to retain by reference.
+ * @returns new list sharing the unchanged older chunks.
+ */
+export declare function appendChunkedList<T>(head: ChunkedList<T> | undefined, value: T): ChunkedList<T>;
+/**
+ * Visit all values in insertion order, with O(N) time and O(N / 64) scratch space.
+ * @param head - current list, or `undefined` for an empty list.
+ * @returns iterator yielding the stored values by reference, without truncation.
+ */
+export declare function iterateChunkedList<T>(head: ChunkedList<T> | undefined): Generator<T>;
+/**
+ * Validate nonempty list checkpoints, including every stored value and chunk size.
+ * @param valueSchema - caller-owned validation for each stored value.
+ * @returns recursive Zod schema rejecting empty or oversized chunks and unknown fields.
+ */
+export declare function chunkedListSchema<T>(valueSchema: z.ZodType<T>): z.ZodType<ChunkedList<T>>;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@deepseek-ai/dsh-chunked-list",
+  "description": "Persistent append-only chunked lists with bounded copying and JSON checkpoint validation",
+  "version": "0.1.5-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/chunked-list"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}