@x1a0f3n9/dsh-storage 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/storage/storage/README.md
+README.md: edb833ad29d38df3225edad6296096ddbd69107f
+README.zh.md: 1b39857099687a208f4644408ff9a9a3936a5847

package/README.md

@@ -0,0 +1,142 @@
+---
+description: "Storage hub (ctx.storage) for compositions and maintainers choosing, mounting, or debugging named storage backends and data-form facilities."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-storage
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `dsh-storage` to keep typed application data durable without adding it to session history. Mount it with a supported storage medium and domain configuration, then callers can access records through the public `ctx.storageDomain` API. Choose it for workspace records, session sidecars, or other application state that must survive restarts without becoming session events. It is available only to host code and has no model-visible effect; compositions that do not need such data can omit it.
+
+## 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 package to give a composition durable, non-session storage: mount it together with backend and domain-form packages, and host-side packages read and write validated records through `ctx.storageDomain`. The hub itself adds nothing observable — it is the meeting point that makes the family work, and everything below is what a composition gets from it.
+
+### When to use it
+
+Mount the hub whenever any package in the composition persists data that is not a session event log — workspace records, session sidecars. It is required by the domain form and both shipped backends, so the storage rows of a composition are `storage` plus a backend plus `storage-domain`. Skip the whole group when nothing stores such data; the agent loop never needs it.
+
+### A minimal composition
+
+```yaml
+- name: '@x1a0f3n9/dsh-storage'
+- name: '@x1a0f3n9/dsh-storage-json'
+  config:
+    root: /var/lib/dsh/data
+- name: '@x1a0f3n9/dsh-storage-domain'
+  config:
+    backend: json
+```
+
+With these rows, the `json` backend registers itself and the `domain` data form mounts; a consumer such as `dsh-workspace` then opens its domain over the routed backend and reads and writes records through `ctx.storageDomain`. Several backends can stay mounted side by side; which backend serves which domain is the domain form's configuration, never a hub-wide choice.
+
+### What you get
+
+- A mounted backend resolves by name, so a composition with both shipped backends can route each domain to either medium by configuration.
+- A mounted data form resolves as `ctx.storage.<form>`; the domain form is additionally served directly as `ctx.storageDomain`.
+- Misconfiguration fails loud with a stable `StorageError` code instead of silently deferring: an unknown backend name, a form read before its owner mounts, or a duplicate registration all throw.
+
+### Failures and recovery
+
+- `backend-not-found` — the domain form routes to a backend that is not mounted; add the backend package. The form waits for every configured backend to register, so row order is not a failure mode.
+- `form-not-mounted` — a consumer reads `ctx.storage.domain` before `dsh-storage-domain` loads; mount the domain row before the consumer.
+- `duplicate-backend` / `duplicate-mount` — the same name or form registers twice; that is a composition bug and fails loud.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The hub is a pure registration table with two faces, designed so backends and data forms stay replaceable without the hub knowing their internals.
+
+### Design concept
+
+- **Backends own media, data forms own semantics.** The hub never performs IO; it only holds the name → backend table and the form-name → facility map. Backend packages register their medium owner, data-form packages mount their facility, and neither needs the other's details.
+- **Multiple backends stay side by side.** Which backend serves which consumer is the consumer's configuration (the domain form's route table), never a hub-global either-or.
+- **Registration and mounting are effects.** `register()` and `mount()` return disposers; disposal removes only that registration's contribution, and does not close the backend — the owning plugin closes it after unregistering.
+- **Activation cannot race registration.** Each backend plugin also publishes a lifecycle-only service key (`storage.backend.<name>`); form providers inject those keys, so the domain form activates only after every configured backend registers, while callers still resolve backends by name through the hub.
+
+### The backend contract
+
+[`src/backend.ts`](src/backend.ts) is the normative contract for backend implementers, checked clause by clause by the shared conformance suite in `tests/contract.ts`. A backend owns exactly one medium and exposes optional data-shape facets; `kv` is the only facet, and opening a unit yields a versioned, globally-singleton schema handle whose single calls are atomic and durable once resolved. Unit and table names must match `UNIT_NAME_RE`; record keys are arbitrary strings that never reach file paths. The unit does not serialize concurrent writes — ordering belongs to the caller — and a stored version differing from the descriptor rejects `version-mismatch` (no migration).
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Storage` service, form mounting, `StorageForms` map |
+| [`src/registry.ts`](src/registry.ts) | `BackendRegistry`: name → backend table, registration disposers |
+| [`src/backend.ts`](src/backend.ts) | The backend contract: facets, units, `UNIT_NAME_RE` |
+| [`src/error.ts`](src/error.ts) | `StorageError` codes shared by the hub and every backend |
+| — | No runtime invariant companion is published; the hub is a pure registration table (names → backends, forms → facilities) whose consistency is fully enforced at the call sites (duplicate/missing entries fail loud synchronously); it owns no event stream or mutable medium to cross-check. |
+| [`tests/contract.ts`](tests/contract.ts) | The shared conformance suite run against each backend |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the hub's view is not enough: the subsystem reference is the authoritative contract, and the Agent Note records the family design and its deferred work.
+
+- [Storage subsystem](../../../docs/subsystems/storage.md) — the backend contract, domain semantics, change events, and generated API.
+- [Storage package map](../README.md) — the family's packages and their repository position.
+- [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) — the design behind the hub, the domain form, and the session-backend migration.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Backend and form registrations
+
+#### What the model sees
+
+Nothing. `ctx.storage` is a host-side registration table: the hub registers no tools, injects no prompts, and writes no session events, so no request field ever carries this package's data.
+
+#### Token effect
+
+Zero direct tokens on every request.
+
+#### KV Cache effect
+
+Independent of live requests: the hub never touches a request prefix, so it cannot invalidate provider cache reuse.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the hub cannot do. They are current package constraints, not a task backlog.
+
+- **`kv` is the only data shape** — a backend implements one facet; the `log` facet for session event logs is deferred to the session-backend migration ([Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)).
+- **Forms resolve lazily** — reading `ctx.storage.domain` before the domain plugin mounts throws `form-not-mounted`; assemblies order plugins accordingly rather than silently deferring.
+
+<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,142 @@
+---
+description: "存储枢纽（ctx.storage）：面向选择、挂载或排查具名存储后端与数据形式设施的组合方与维护者。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-storage
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `dsh-storage` 持久保存类型化应用数据，而不将其加入会话历史。将它与受支持的存储介质和领域配置一同挂载后，调用方即可通过公共 `ctx.storageDomain` API 访问记录。工作区记录、会话伴随数据或其他必须在重启后保留且不应成为会话事件的应用状态适合使用它。它仅供宿主代码使用，对模型没有可见影响；无需此类数据的组合可以省略它。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+使用本包为组合提供持久的非会话存储：把它与后端和数据形式包一起挂载，宿主包即可通过 `ctx.storageDomain` 读写经过校验的记录。枢纽自身不增加任何可观察行为——它是让整个家族运转起来的交汇点——以下内容就是组合从它得到的一切。
+
+### 何时使用
+
+当组合中任何包需要持久化会话事件日志以外的数据——工作区记录、会话伴随数据——时就挂载枢纽。领域数据形式与两个内置后端都依赖它，因此组合的存储行是 `storage` 加一个后端加 `storage-domain`。没有任何此类数据的组合可以省略整个组；agent loop 永远不需要它。
+
+### 最小组合
+
+```yaml
+- name: '@x1a0f3n9/dsh-storage'
+- name: '@x1a0f3n9/dsh-storage-json'
+  config:
+    root: /var/lib/dsh/data
+- name: '@x1a0f3n9/dsh-storage-domain'
+  config:
+    backend: json
+```
+
+这些行加载后，`json` 后端注册自身、`domain` 数据形式挂载；诸如 `dsh-workspace` 之类的消费方随后在已路由后端上打开自己的领域，并通过 `ctx.storageDomain` 读写记录。多个后端可以并排保持挂载；哪个后端服务哪个领域由领域数据形式的配置决定，绝非枢纽的全局选择。
+
+### 你能得到什么
+
+- 已挂载的后端按名称解析，因此同时挂载两个内置后端的组合可以把每个领域按配置路由到任一种介质。
+- 已挂载的数据形式解析为 `ctx.storage.<form>`；领域数据形式还直接以 `ctx.storageDomain` 对外服务。
+- 错误配置会以稳定的 `StorageError` 代码明确报错，而不是静默推迟：未知的后端名称、在其所有者挂载前读取数据形式、或重复注册都会抛出异常。
+
+### 失败与恢复
+
+- `backend-not-found`——领域数据形式路由到未挂载的后端；请添加后端包。数据形式会等待所有已配置后端注册，因此行序不会造成失败。
+- `form-not-mounted`——消费方在 `dsh-storage-domain` 加载前读取 `ctx.storage.domain`；请把领域行放在消费方之前。
+- `duplicate-backend`／`duplicate-mount`——同一名称或形式注册了两次；这是组合错误，会明确报错。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+枢纽是一张纯注册表，拥有两个面，设计目标是后端与数据形式可以独立替换，而枢纽无需了解它们的内部实现。
+
+### 设计理念
+
+- **后端拥有介质，数据形式拥有语义。** 枢纽从不执行 IO；它只持有名称 → 后端表和形式名 → 设施表。后端包注册其介质所有者，数据形式包挂载其设施，双方都不需要对方的细节。
+- **多个后端并排共存。** 哪个后端服务哪个消费方由消费方自身的配置决定（领域数据形式的路由表），绝非枢纽全局的二选一。
+- **注册与挂载都是 effect。** `register()` 与 `mount()` 返回资源释放函数；释放只移除该次注册的贡献，且不会关闭后端——由所属插件在注销后关闭。
+- **激活不会与注册竞争。** 每个后端插件还会发布一个仅用于生命周期的服务键（`storage.backend.<name>`）；数据形式提供方注入这些键，因此领域数据形式只在所有已配置后端注册后激活，而调用方仍通过枢纽按名称解析后端。
+
+### 后端约定
+
+[`src/backend.ts`](src/backend.ts) 是后端实现者的规范性约定，由 `tests/contract.ts` 中的共享一致性套件逐条款检查。一个后端只拥有一种介质，并暴露可选的数据形状分面；`kv` 是唯一的分面，打开单元即可获得一个带版本、全局单例的 schema 句柄，其每次单独调用都是原子的，且 resolve 后即已持久。单元名与表名必须匹配 `UNIT_NAME_RE`；记录键是任意字符串，绝不进入文件路径。单元不对并发写入做串行化——顺序由调用方负责——介质上记录的版本与描述符不同时拒绝 `version-mismatch`（不做迁移）。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`Storage` 服务、数据形式挂载、`StorageForms` 表 |
+| [`src/registry.ts`](src/registry.ts) | `BackendRegistry`：名称 → 后端表、注册资源释放函数 |
+| [`src/backend.ts`](src/backend.ts) | 后端约定：分面、单元、`UNIT_NAME_RE` |
+| [`src/error.ts`](src/error.ts) | 枢纽与每个后端共享的 `StorageError` 代码 |
+| — | 不发布运行时不变式伴生入口；纯注册表。 |
+| [`tests/contract.ts`](tests/contract.ts) | 针对每个后端运行的共享一致性套件 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当枢纽视角不够用时阅读以下页面：子系统参考是权威约定，Agent Note 记录了家族设计与延期工作。
+
+- [存储子系统](../../../docs/subsystems/storage.zh.md)——后端约定、领域语义、变更事件与生成的 API。
+- [存储包映射](../README.zh.md)——家族的各包及其在仓库中的位置。
+- [领域 KV 存储 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)——枢纽、领域数据形式与会话后端迁移背后的设计。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 后端与形式注册
+
+#### 模型看到什么
+
+无。`ctx.storage` 是宿主侧注册表：枢纽不注册工具、不注入提示词，也不写入会话事件，因此任何请求字段都不会携带本包的数据。
+
+#### Token 影响
+
+每次请求都不会直接增加 token。
+
+#### KV Cache 影响
+
+与实时请求相互独立：枢纽绝不触碰请求前缀，因此无法使提供方缓存复用失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制定义了枢纽不能做什么。它们是当前包约束，不是任务积压。
+
+- **`kv` 是唯一的数据形状**——后端只实现一个分面；面向会话事件日志的 `log` 分面被推迟到会话后端迁移（[Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)）。
+- **数据形式按需解析**——在领域插件挂载前读取 `ctx.storage.domain` 会抛出 `form-not-mounted`；组装会按相应顺序排列插件，而不是静默推迟。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,140 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/error.js
+/**
+* Error vocabulary for the storage hub and its backends.
+* @module @x1a0f3n9/dsh-storage/src/error
+*/
+/**
+* Error thrown by the hub and by backend implementations. The `code` is the
+* stable contract consumers may switch on; `message` is diagnostic prose.
+*/
+var StorageError = class extends Error {
+	code;
+	name = "StorageError";
+	/**
+	* @param code - Stable discriminant for the failure class.
+	* @param message - Human-readable diagnostic detail.
+	* @param options - Standard error options (`cause`).
+	*/
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+	}
+};
+//#endregion
+//#region lib/types/registry.js
+/**
+* Named backend registry of the storage hub.
+* @module @x1a0f3n9/dsh-storage/src/registry
+*/
+/**
+* Mutable name → backend table. Multiple backends stay mounted side by side;
+* which backend serves which consumer is the consumer's configuration
+* (e.g. the domain layer's route table), never a hub-global choice.
+*/
+var BackendRegistry = class {
+	backends = /* @__PURE__ */ new Map();
+	/**
+	* Register a named backend. Registration is an effect: the returned
+	* disposer removes the name. Disposal does NOT close the backend — the
+	* owning plugin closes it after unregistering.
+	* @param name - Backend name, e.g. `json` or `sqlite`.
+	* @param backend - The backend instance.
+	* @returns the disposer that unregisters the name.
+	*/
+	register(name, backend) {
+		if (this.backends.has(name)) throw new StorageError("duplicate-backend", `storage backend '${name}' is already registered`);
+		this.backends.set(name, backend);
+		return () => {
+			if (this.backends.get(name) === backend) this.backends.delete(name);
+		};
+	}
+	/**
+	* Resolve a backend by name.
+	* @param name - Registered backend name.
+	* @returns the backend.
+	*/
+	get(name) {
+		const backend = this.backends.get(name);
+		if (!backend) throw new StorageError("backend-not-found", `storage backend '${name}' is not registered (registered: ${[...this.backends.keys()].join(", ") || "none"})`);
+		return backend;
+	}
+	/**
+	* Registered backend names, for diagnostics.
+	* @returns a snapshot array of names.
+	*/
+	names() {
+		return [...this.backends.keys()];
+	}
+};
+//#endregion
+//#region lib/types/backend.js
+/**
+* Backend-facing vocabulary of the storage hub: a backend owns one medium
+* (a file-tree root, a database file) and exposes operation groups over it.
+* This module defines the normative contract text for backend implementers; the shared
+* conformance suite in `tests/contract.ts` checks every rule.
+* @module @x1a0f3n9/dsh-storage/src/backend
+*/
+/** Allowed format for unit and table names: safe as a file name and as a SQL identifier segment without escaping. */
+const UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/;
+//#endregion
+//#region lib/types/index.js
+/**
+* Storage hub (`ctx.storage`): a named backend registry plus mounted
+* data-form facilities. The hub itself performs no IO — backends own media,
+* data forms (the domain layer first) own semantics.
+* @module @x1a0f3n9/dsh-storage
+*/
+/**
+* Derive the Cordis lifecycle service that one named backend plugin provides.
+* Domain-form providers inject these keys so activation cannot race backend
+* registration even though callers continue resolving backends through the
+* storage registry.
+* @param name - Backend registry name.
+* @returns the corresponding lifecycle-only service key.
+*/
+function storageBackendServiceKey(name) {
+	return `storage.backend.${name}`;
+}
+/**
+* The storage hub service. Backends register under `backend`; data forms
+* mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
+*/
+var Storage = class extends Service {
+	/** Named backend table; multiple backends stay mounted side by side. */
+	backend = new BackendRegistry();
+	forms = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		super(ctx, "storage");
+	}
+	/**
+	* Mount a data-form facility on the hub. Mounting is an effect: the
+	* returned disposer unmounts the form.
+	* @param form - Form key declared in {@link StorageForms}.
+	* @param facility - The facility instance to expose.
+	* @returns the disposer that unmounts the form.
+	*/
+	mount(form, facility) {
+		if (this.forms.has(form)) throw new StorageError("duplicate-mount", `storage form '${String(form)}' is already mounted`);
+		this.forms.set(form, facility);
+		return () => {
+			if (this.forms.get(form) === facility) this.forms.delete(form);
+		};
+	}
+	/**
+	* Resolve a mounted data form.
+	* @param form - Form key declared in {@link StorageForms}.
+	* @returns the mounted facility.
+	*/
+	form(form) {
+		if (!this.forms.has(form)) throw new StorageError("form-not-mounted", `storage form '${String(form)}' is not mounted`);
+		return this.forms.get(form);
+	}
+	/** Domain data form; present once the domain layer plugin is loaded. */
+	get domain() {
+		return this.form("domain");
+	}
+};
+//#endregion
+export { BackendRegistry, Storage, Storage as default, StorageError, UNIT_NAME_RE, storageBackendServiceKey };

package/lib/types/backend.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Backend-facing vocabulary of the storage hub: a backend owns one medium
+ * (a file-tree root, a database file) and exposes operation groups over it.
+ * This module defines the normative contract text for backend implementers; the shared
+ * conformance suite in `tests/contract.ts` checks every rule.
+ * @module @x1a0f3n9/dsh-storage/src/backend
+ */
+/** Allowed format for unit and table names: safe as a file name and as a SQL identifier segment without escaping. */
+export declare const UNIT_NAME_RE: RegExp;
+/**
+ * One registered backend. A backend owns exactly one medium and shares its
+ * lifecycle across all facets; facets are optional members — a backend that
+ * cannot serve a data kind simply omits it, and resolution fails loud instead.
+ */
+export interface StorageBackend {
+    /** Key-value operations; absent when this backend cannot serve them. */
+    readonly kv?: KvFacet;
+    /**
+     * Drain in-flight writes across all open units and release the medium.
+     * Idempotent; concurrent and repeated calls resolve once teardown finishes.
+     * @returns resolution after the medium is released.
+     */
+    close(): Promise<void>;
+}
+/** The key-value data shape: whole-unit snapshots plus per-record durable writes. */
+export interface KvFacet {
+    /**
+     * Open one unit, creating it when the medium holds no trace of it yet
+     * (materialization may defer to the first write, but {@link KvUnit.loadAll}
+     * must immediately serve the empty shape). A version already stamped on the
+     * medium that differs from `descriptor.version` rejects with
+     * `version-mismatch`; a medium that cannot be parsed as this unit rejects
+     * with `malformed-medium`. Opening the same unit name twice without closing
+     * is a caller bug and rejects.
+     * @param descriptor - Static identity and shape of the unit to open.
+     * @returns the opened unit.
+     */
+    open(descriptor: KvUnitDescriptor): Promise<KvUnit>;
+}
+/** Static identity and shape of one KV unit, projected from its owner's spec. */
+export interface KvUnitDescriptor {
+    /** Unit name; must match {@link UNIT_NAME_RE}. Also the file-name / SQL-identifier segment. */
+    readonly name: string;
+    /** Unit format version; a non-negative integer stamped on the medium at first materialization. */
+    readonly version: number;
+    /** Table names; each must match {@link UNIT_NAME_RE}. */
+    readonly tables: readonly string[];
+    /** Whether this unit carries the global singleton slot. */
+    readonly hasGlobal: boolean;
+    /**
+     * Medium layout. `single` (the default) keeps the whole unit in one
+     * document; `per-record` keeps each record in its own document, so a unit
+     * whose records are large or sparse never rewrites the rest on one write,
+     * and an unaccepted version stamp discards only that record instead of
+     * rejecting the whole unit. Backends that only serve one layout accept the
+     * other's units as foreign documents.
+     */
+    readonly layout?: 'single' | 'per-record';
+    /**
+     * Older unit versions whose stored records are also readable under the
+     * declaring owner's current record schemas (the owner vouches for that —
+     * typically by declaring the fields old records lack as optional). Reads of
+     * a `per-record` unit accept documents stamped with any listed version, and
+     * the legacy whole-unit bootstrap accepts a legacy file stamped with one;
+     * writes always stamp {@link version}. `single`-layout reads stay
+     * exact-version.
+     */
+    readonly compatibleVersions?: readonly number[];
+}
+/**
+ * One opened unit. Values are opaque JSON to this layer: no schema, no
+ * events, no domain meaning. The unit does NOT serialize concurrent writes —
+ * write ordering is the caller's responsibility (the domain layer runs one
+ * write chain per unit); the unit only guarantees that each single call is
+ * atomic on the medium and durable once resolved (a crash after resolution
+ * followed by a re-open observes the write). Any call after {@link close}
+ * rejects with `closed`.
+ */
+export interface KvUnit {
+    /**
+     * Read the full current snapshot.
+     * @returns every table's records keyed by table name, plus the global
+     * singleton (`null` when never written or not declared).
+     */
+    loadAll(): Promise<{
+        tables: Record<string, Record<string, unknown>>;
+        global: unknown;
+    }>;
+    /**
+     * Upsert one record durably. Overwrite semantics: an existing key is replaced.
+     * @param table - Declared table name.
+     * @param key - Record key. In the `per-record` layout a key becomes a path
+     * segment and must match `[a-zA-Z0-9_-]+` (an unsafe key rejects); in the
+     * `single` layout keys stay opaque.
+     * @param value - Opaque JSON-serializable record.
+     * @returns resolution after durability.
+     */
+    putRecord(table: string, key: string, value: unknown): Promise<void>;
+    /**
+     * Delete one record durably. Idempotent: a missing key is a no-op.
+     * @param table - Declared table name.
+     * @param key - Record key.
+     * @returns resolution after durability.
+     */
+    deleteRecord(table: string, key: string): Promise<void>;
+    /**
+     * Move one record's stored document out of the unit's readable set,
+     * preserving its bytes for inspection instead of deleting them. Backends
+     * whose medium has no per-record document to move (the `single` layout, a
+     * row store) omit this member, and the caller falls back to its
+     * reject-loud path. Absent after the move: a later {@link loadAll} reads
+     * the key as missing and a later {@link putRecord} recreates it fresh.
+     * @param table - Declared table name.
+     * @param key - Record key.
+     * @returns the medium location the document was moved to (diagnostics).
+     */
+    backupRecord?(table: string, key: string): Promise<string>;
+    /**
+     * Write the global singleton durably. Only valid when the descriptor
+     * declared `hasGlobal`.
+     * @param value - Opaque JSON-serializable value.
+     * @returns resolution after durability.
+     */
+    setGlobal(value: unknown): Promise<void>;
+    /**
+     * Drain this unit's in-flight writes and release it. Idempotent.
+     * @returns resolution after the unit is released.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=backend.d.ts.map

package/lib/types/error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Error vocabulary for the storage hub and its backends.
+ * @module @x1a0f3n9/dsh-storage/src/error
+ */
+/** Discriminant codes carried by every {@link StorageError}. */
+export type StorageErrorCode = 'backend-not-found' | 'form-not-mounted' | 'duplicate-backend' | 'duplicate-mount' | 'version-mismatch' | 'malformed-medium' | 'closed';
+/**
+ * Error thrown by the hub and by backend implementations. The `code` is the
+ * stable contract consumers may switch on; `message` is diagnostic prose.
+ */
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    readonly name = "StorageError";
+    /**
+     * @param code - Stable discriminant for the failure class.
+     * @param message - Human-readable diagnostic detail.
+     * @param options - Standard error options (`cause`).
+     */
+    constructor(code: StorageErrorCode, message: string, options?: ErrorOptions);
+}
+//# sourceMappingURL=error.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Storage hub (`ctx.storage`): a named backend registry plus mounted
+ * data-form facilities. The hub itself performs no IO — backends own media,
+ * data forms (the domain layer first) own semantics.
+ * @module @x1a0f3n9/dsh-storage
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { BackendRegistry } from './registry.ts';
+export { BackendRegistry } from './registry.ts';
+export { StorageError } from './error.ts';
+export type { StorageErrorCode } from './error.ts';
+export { UNIT_NAME_RE } from './backend.ts';
+export type { StorageBackend, KvFacet, KvUnit, KvUnitDescriptor } from './backend.ts';
+/**
+ * Derive the Cordis lifecycle service that one named backend plugin provides.
+ * Domain-form providers inject these keys so activation cannot race backend
+ * registration even though callers continue resolving backends through the
+ * storage registry.
+ * @param name - Backend registry name.
+ * @returns the corresponding lifecycle-only service key.
+ */
+export declare function storageBackendServiceKey(name: string): string;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        storage: Storage;
+    }
+}
+/**
+ * Data forms mountable on the hub, keyed by form name. Form owners extend
+ * this map via declaration merging (the domain layer merges
+ * `domain: DomainFacility`) and mount the facility in their `apply`.
+ */
+export interface StorageForms {
+}
+/**
+ * The storage hub service. Backends register under `backend`; data forms
+ * mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.
+ */
+export declare class Storage extends Service {
+    /** Named backend table; multiple backends stay mounted side by side. */
+    readonly backend: BackendRegistry;
+    private readonly forms;
+    constructor(ctx: Context);
+    /**
+     * Mount a data-form facility on the hub. Mounting is an effect: the
+     * returned disposer unmounts the form.
+     * @param form - Form key declared in {@link StorageForms}.
+     * @param facility - The facility instance to expose.
+     * @returns the disposer that unmounts the form.
+     */
+    mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void;
+    /**
+     * Resolve a mounted data form.
+     * @param form - Form key declared in {@link StorageForms}.
+     * @returns the mounted facility.
+     */
+    form<K extends keyof StorageForms>(form: K): StorageForms[K];
+    /** Domain data form; present once the domain layer plugin is loaded. */
+    get domain(): StorageForms extends {
+        domain: infer D;
+    } ? D : never;
+}
+export default Storage;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Named backend registry of the storage hub.
+ * @module @x1a0f3n9/dsh-storage/src/registry
+ */
+import type { StorageBackend } from './backend.ts';
+/**
+ * Mutable name → backend table. Multiple backends stay mounted side by side;
+ * which backend serves which consumer is the consumer's configuration
+ * (e.g. the domain layer's route table), never a hub-global choice.
+ */
+export declare class BackendRegistry {
+    private readonly backends;
+    /**
+     * Register a named backend. Registration is an effect: the returned
+     * disposer removes the name. Disposal does NOT close the backend — the
+     * owning plugin closes it after unregistering.
+     * @param name - Backend name, e.g. `json` or `sqlite`.
+     * @param backend - The backend instance.
+     * @returns the disposer that unregisters the name.
+     */
+    register(name: string, backend: StorageBackend): () => void;
+    /**
+     * Resolve a backend by name.
+     * @param name - Registered backend name.
+     * @returns the backend.
+     */
+    get(name: string): StorageBackend;
+    /**
+     * Registered backend names, for diagnostics.
+     * @returns a snapshot array of names.
+     */
+    names(): string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@x1a0f3n9/dsh-storage",
+  "description": "Storage hub (ctx.storage): named backend registry plus mounted data-form facilities for the DeepSeek Harness",
+  "version": "0.1.5-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/storage/storage"
+  },
+  "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"
+  }
+}