@hasna-internal/kai-storage 0.1.1-rc.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: bf827220afe0d8b1cbc53b3a12e6d0034004e1d2
+README.zh.md: fb52c96e38c17b76ef0e6b70a79177911a088fb7

package/README.md

@@ -0,0 +1,32 @@
+# @hasna-internal/kai-storage
+
+English | [中文](README.zh.md)
+
+Storage hub (`ctx.storage`) for non-session data: a named backend registry plus mounted data-form facilities. The hub performs no IO itself — backends own media, and data forms own semantics. The [storage family overview](../README.md) maps those packages; the [domain KV storage Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) records the design rationale.
+
+## Shape
+
+- `ctx.storage.backend` — name → backend table. Multiple backends stay mounted side by side (`json`, `sqlite`); which backend serves a consumer is that consumer's configuration (the domain layer's route table), never a hub-global choice. `register()` returns the disposer; duplicate names and unknown lookups fail loud.
+- `ctx.storage.mount(form, facility)` / `ctx.storage.form(form)` — data-form mounting. `StorageForms` is merge-extensible; the domain layer merges `domain` and is reached as `ctx.storage.domain`.
+- A backend owns one medium and exposes the data-shape facets it supports. `kv` is the current facet; `src/backend.ts` owns its exact contract.
+
+## 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.
+
+#### 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
+
+- **`kv` is the only data shape** — backends currently have one facet to implement.
+- **Forms resolve lazily** — reading `ctx.storage.domain` before the domain plugin mounts throws `form-not-mounted`; assemblies order plugins accordingly (misconfiguration fails loud rather than silently deferring).

package/README.zh.md

@@ -0,0 +1,32 @@
+# @hasna-internal/kai-storage
+
+[English](README.md) | 中文
+
+非会话数据的存储中心（`ctx.storage`）：具名后端注册表加已挂载的数据形式设施。中心自身不执行 IO：后端拥有介质，数据形式拥有语义。[存储家族概述](../README.zh.md)列出了这些包；[领域 KV 存储 Agent Note](../../../.agents/notes/proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.zh.md)记录了设计理由。
+
+## 结构
+
+- `ctx.storage.backend`：名称 → 后端表。多个后端并排保持挂载（`json`、`sqlite`）；为消费方提供服务的后端由该消费方自身的配置决定（领域层的路由表），绝非中心的全局选择。`register()` 返回资源释放函数；注册重复名称或查找未知名称时都会明确报错。
+- `ctx.storage.mount(form, facility)`／`ctx.storage.form(form)`：数据形式挂载。`StorageForms` 可通过合并扩展；领域层合并 `domain`，并通过 `ctx.storage.domain` 访问。
+- 后端拥有一种介质，并公开其支持的数据形状**分面**。当前分面为 `kv`；`src/backend.ts` 负责定义其确切约定。
+
+## 模型体验
+
+### 后端与形式注册
+
+#### 模型看到的内容
+
+无。`ctx.storage` 是主机侧注册表；中心不注册工具、不注入提示词，也不写入会话事件。
+
+#### Token 影响
+
+每次请求都不会直接增加 token。
+
+#### KV Cache 影响
+
+与实时请求相互独立：中心绝不触碰请求前缀，因此无法使提供方缓存复用失效。
+
+## 已知限制与暂缓事项
+
+- **`kv` 是唯一的数据形状**：后端目前只有一个分面需要实现。
+- **数据形式按需解析**：在领域插件挂载前读取 `ctx.storage.domain` 会抛出 `form-not-mounted`；组装会按相应顺序排列插件（错误配置会明确报错，而不是静默推迟处理）。

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 @hasna-internal/kai-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 @hasna-internal/kai-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 @hasna-internal/kai-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 @hasna-internal/kai-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/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-storage`.
+* @module @hasna-internal/kai-storage/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-storage";
+/** Cordis companion plugin name. */
+const name = "storage-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: 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.
+*/
+const install = () => {};
+/**
+* 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/types/backend.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 @hasna-internal/kai-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;
+}
+/**
+ * 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; any string is safe (keys never reach file paths).
+     * @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>;
+    /**
+     * 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 @hasna-internal/kai-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 @hasna-internal/kai-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/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-storage`.
+ * @module @hasna-internal/kai-storage/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "storage-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/registry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Named backend registry of the storage hub.
+ * @module @hasna-internal/kai-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,42 @@
+{
+  "name": "@hasna-internal/kai-storage",
+  "description": "Storage hub (ctx.storage): named backend registry plus mounted data-form facilities for the DeepSeek Harness",
+  "version": "0.1.1-rc.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"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}