@x1a0f3n9/dsh-ptc-runtime 0.1.7-rc.4 → 0.2.1-rc.3

package/README.i18n.yaml

@@ -5,66 +5,66 @@
 /:
   en: 8904d5f5d5251a83
   zh: 69b48f289b0416f0
-/x1a0f3n9-dsh-ptc-runtime:
-  en: 44022b553091816b
-  zh: 43a6935d93af05ff
-/x1a0f3n9-dsh-ptc-runtime/summary:
-  en: d5a1f0be39931018
-  zh: 3584bd577f654a38
-/x1a0f3n9-dsh-ptc-runtime/table-of-contents:
+/deepseek-ai-dsh-ptc-runtime:
+  en: cced8c691b58657a
+  zh: 3da9cdf76a1a07ff
+/deepseek-ai-dsh-ptc-runtime/summary:
+  en: b04917e62d63c7ff
+  zh: 12cb9f38cbf8ee3f
+/deepseek-ai-dsh-ptc-runtime/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
-/x1a0f3n9-dsh-ptc-runtime/use-this-package:
+/deepseek-ai-dsh-ptc-runtime/use-this-package:
   en: 7e5ebf7420c13af4
   zh: 9ad1e056e794ca4a
-/x1a0f3n9-dsh-ptc-runtime/use-this-package/run-a-program:
-  en: 6f97019cebc2f417
-  zh: c56f18a690dbe814
-/x1a0f3n9-dsh-ptc-runtime/use-this-package/choose-a-backend:
-  en: f2dd49b11ef5e888
-  zh: f2be82b0cae2d8e4
-/x1a0f3n9-dsh-ptc-runtime/use-this-package/name-your-bindings-portably:
+/deepseek-ai-dsh-ptc-runtime/use-this-package/run-a-program:
+  en: c856760ebc15d59e
+  zh: dc093083b29794e0
+/deepseek-ai-dsh-ptc-runtime/use-this-package/choose-a-backend:
+  en: fc0d515f0c3664f3
+  zh: 0a1b646b5cf92232
+/deepseek-ai-dsh-ptc-runtime/use-this-package/name-your-bindings-portably:
   en: 4e46c1672701b8df
   zh: 0353c5855c9ff6be
-/x1a0f3n9-dsh-ptc-runtime/use-this-package/what-can-go-wrong:
+/deepseek-ai-dsh-ptc-runtime/use-this-package/what-can-go-wrong:
   en: 44f9fdf2c8e2cacc
   zh: 99dd555a49075f88
-/x1a0f3n9-dsh-ptc-runtime/understand-the-implementation:
+/deepseek-ai-dsh-ptc-runtime/understand-the-implementation:
   en: 686d570f5e669fa4
   zh: 2075cf27c30f251a
-/x1a0f3n9-dsh-ptc-runtime/understand-the-implementation/design-concept:
+/deepseek-ai-dsh-ptc-runtime/understand-the-implementation/design-concept:
   en: 9f0055e22a1595a5
   zh: 0aa3ceb9dd145128
-/x1a0f3n9-dsh-ptc-runtime/understand-the-implementation/service-api:
+/deepseek-ai-dsh-ptc-runtime/understand-the-implementation/service-api:
   en: 1d7a792c9a78a517
   zh: b49bddf18c259edc
-/x1a0f3n9-dsh-ptc-runtime/understand-the-implementation/vocabulary:
+/deepseek-ai-dsh-ptc-runtime/understand-the-implementation/vocabulary:
   en: 855cb8366e3bd293
   zh: da6d7a0ce51f97fc
-/x1a0f3n9-dsh-ptc-runtime/understand-the-implementation/portable-identifiers:
+/deepseek-ai-dsh-ptc-runtime/understand-the-implementation/portable-identifiers:
   en: 01c82c6e73180979
   zh: e29b066f9f82c8b4
-/x1a0f3n9-dsh-ptc-runtime/understand-the-implementation/source-map:
-  en: 73b7deab23f3b00d
-  zh: 780ddf5ff0dd5f65
-/x1a0f3n9-dsh-ptc-runtime/further-exploration:
+/deepseek-ai-dsh-ptc-runtime/understand-the-implementation/source-map:
+  en: 85b65ceb9be0c49f
+  zh: 52df7f06d4e49d6e
+/deepseek-ai-dsh-ptc-runtime/further-exploration:
   en: a77e68bc4f5e66d9
   zh: 101a57bcad581668
-/x1a0f3n9-dsh-ptc-runtime/model-experience:
+/deepseek-ai-dsh-ptc-runtime/model-experience:
   en: 5506904c50c1ee20
   zh: f0ffa9f4f08b20cf
-/x1a0f3n9-dsh-ptc-runtime/model-experience/kv-cache-effect:
+/deepseek-ai-dsh-ptc-runtime/model-experience/kv-cache-effect:
   en: 40294c1c31b74824
   zh: 081cebc2e2650f03
-/x1a0f3n9-dsh-ptc-runtime/known-limitations-and-deferred-work:
-  en: 7f30f78c5d427667
-  zh: 99d21160016deea2
-/x1a0f3n9-dsh-ptc-runtime/known-limitations-and-deferred-work/dev-note:
+/deepseek-ai-dsh-ptc-runtime/known-limitations-and-deferred-work:
+  en: e20364d073f78c60
+  zh: 6cac5c46ff91b3ca
+/deepseek-ai-dsh-ptc-runtime/known-limitations-and-deferred-work/dev-note:
   en: d56846da29ad869c
   zh: 0397151a7e29b8ba
-/x1a0f3n9-dsh-ptc-runtime/known-limitations-and-deferred-work/dev-note/future-persistent-kernel-backend:
-  en: cfefaae6ed9705d5
-  zh: 3cca5b1bd92445b0
-/x1a0f3n9-dsh-ptc-runtime/known-limitations-and-deferred-work/dev-note/future-container-backend:
+/deepseek-ai-dsh-ptc-runtime/known-limitations-and-deferred-work/dev-note/retained-state:
+  en: cd86d95f288b86dc
+  zh: 2157b7a97eb62667
+/deepseek-ai-dsh-ptc-runtime/known-limitations-and-deferred-work/dev-note/future-container-backend:
   en: 2b94202842f0556c
   zh: 5aa0311fa621a018

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use `dsh-ptc-runtime` to run one model-written program against host-provided asynchronous functions through a configured backend. A request returns a lossless-JSON value, ordered per-channel logs, or a structured error; program failures resolve in the result, while rejected promises indicate caller misuse. Each run is isolated from prior runs, and the runtime has no knowledge of tools or sessions. Choose an execution backend separately; its language and isolation descriptors identify the required source language and execution substrate but do not themselves promise a security boundary.
+Use `dsh-ptc-runtime` to execute model programs against host-provided asynchronous functions. Requests return lossless JSON, captured logs, or structured failures; rejected promises indicate caller misuse. Providers isolate distinct state owners and declare whether source is an async function body or REPL statements. A provider may retain memory for an explicit owner until release; it never restores that memory from a Session. Language and isolation descriptors identify syntax and execution substrate, not security guarantees.
 
 ## Table of Contents
 
@@ -29,7 +29,7 @@ Choose this package when you compose a deployment that executes model-written pr
 
 ### Run a program
 
-Give the runtime a program and binding namespaces, then call `resolve(request)` followed by `run(spec)`. Resolution validates optional cwd, timeout and sandbox policy against the provider's capabilities and fills deployment defaults. The program runs as an async function body, so top-level `await` and `return` work; a lossless-JSON completion becomes `result.value`, captured text becomes `result.logs`, and program failures become `result.error`. Each output channel preserves its own order, while cross-channel interleaving is backend-dependent.
+Call `resolve(request)` followed by `run(spec)` with a program and binding namespaces. Resolution validates cwd, timeout and sandbox choices and applies provider defaults. `programFormat` selects an async function body with top-level `await` and `return`, or REPL statements with top-level declarations, `await`, and a final expression. Lossless-JSON completion becomes `result.value`, text becomes `result.logs`, and failures become `result.error`.
 
 ```text
 const spec = ctx.ptcRuntime.resolve({
@@ -44,6 +44,8 @@ const result = await ctx.ptcRuntime.run(spec)
 
 Backends expose `language` and `isolation` as diagnostic descriptors; neither grants authority or proves confinement. [`dsh-ptc-runtime-node`](../ptc-runtime-node/README.md) executes erasable TypeScript in a fresh managed Node process under the resolved sandbox policy. The private [`dsh-experimental-ptc-runtime-python`](../../experimental/ptc-runtime-python/README.md) provider executes Python in a fresh CPython subprocess without file confinement. `sandboxMode` advertises a provider's deployment file-policy mode, or is absent when that capability is unsupported.
 
+For the optional [Node in-memory mode](../ptc-runtime-node/README.md#persistent-repl), pass the same `stateOwner` object across runs and await `release(owner)` at the owner's end. Different object identities never share an environment; omitted owners use a temporary environment. Stateless providers ignore ownership. Calls for one retained owner must not overlap.
+
 ### Name your bindings portably
 
 Binding-global and error-class names are language-portable: they must match `[A-Za-z_][A-Za-z0-9_]*`, avoid every portable target language's reserved words, and avoid backend-owned slots, so one namespace list is valid against every backend. A name like `$tools`, `lambda`, or `console` fails the run before it starts; the exact exclusion sets are part of the seam contract.
@@ -90,7 +92,6 @@ Binding-global and error-class names are language-portable: they must match the
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: abstract `PtcRuntime` service and the portable-identifier exclusion sets |
 | [`src/types.ts`](src/types.ts) | Vocabulary: `PtcRunRequest`, `PtcRunSpec`, bindings, results, failures and sandbox facts |
-| — | No runtime invariant companion is published; this package exposes no independent event sequence or mutable data relation beyond contracts enforced at its owning seam. |
 
 </details>
 
@@ -126,7 +127,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 These limits define what the seam cannot do; they are current package constraints, not a task backlog.
 
 - **`run()` is one-shot** — `logs` arrive only on the resolved `PtcRunResult`; the seam exposes no streaming-log or progress API for a live program's output.
-- **No state survives between runs** — every request runs against a fresh world; a persistent REPL-style kernel is deferred until a backend brings its own logging story.
+- **Retained memory is disposable**: providers may keep state for an explicit owner; restart, release, and provider-specific failures discard it. Programs, binding calls and results remain logged by consumers; live objects are neither serialized nor replayed.
 - **Providers have different confinement capabilities** — the shipped Node provider enforces a resolved file policy, while the private experimental Python provider rejects an explicit policy. No container provider is supplied.
 - **No uniform binding byte cap applies across providers** — each provider owns its transport limits; a binding can still allocate memory before its result reaches those limits.
 
@@ -138,9 +139,9 @@ These limits define what the seam cannot do; they are current package constraint
 
 This Dev Note is working context for maintainers: undecided directions and open questions. It is explicitly non-authoritative — shipped behavior and limits live in the sections above and the package code.
 
-#### Future: persistent kernel backend
+#### Retained state
 
-A REPL-style kernel that keeps state across `run_code` calls remains undecided; it would need its own logging story, because the no-state-between-runs contract is what keeps every request reconstructable from the session log alone.
+Retained state has no disk checkpoint or restoration protocol. Consumers must tolerate its loss and retain only model-visible programs and outcomes in the Session log.
 
 #### Future: container backend
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用 `dsh-ptc-runtime`，可通过已配置的后端，针对宿主提供的异步函数运行一段模型编写的程序。请求返回无损 JSON 值、通道内有序的日志或结构化错误；程序失败在结果中 resolve，而 Promise reject 表示调用方误用。每次运行都与先前运行隔离，且运行时不了解工具或会话。执行后端需另行选择；其语言与隔离描述符标明所需的源语言和执行基底，但这些描述符本身不承诺安全边界。
+使用 `dsh-ptc-runtime` 执行调用宿主异步函数的模型程序。请求返回无损 JSON、捕获日志或结构化失败；Promise 拒绝表示调用方误用。提供方隔离不同状态所有者，并声明源码是异步函数体还是 REPL 语句。提供方可以为显式所有者保留内存，直到释放，但不会从 Session 恢复这些内存。语言与隔离描述符标识语法和执行基底，不提供安全保证。
 
 ## 目录
 
@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 运行一个程序
 
-向运行时提供程序与绑定命名空间，然后依次调用 `resolve(request)` 和 `run(spec)`。解析根据提供方能力验证可选 cwd、timeout 与沙箱策略，并填入部署默认值。程序作为异步函数体运行，支持顶层 `await` 与 `return`；无损 JSON 完成值成为 `result.value`，捕获文本成为 `result.logs`，程序失败成为 `result.error`。每个输出通道保持自身顺序，跨通道交错由后端决定。
+传入程序和绑定命名空间，依次调用 `resolve(request)` 和 `run(spec)`。解析阶段验证 cwd、超时与沙盒选项，并应用提供方默认值。`programFormat` 选择支持顶层 `await`、`return` 的异步函数体，或支持顶层声明、`await` 和末尾表达式的 REPL 语句。无损 JSON 完成值进入 `result.value`，文本进入 `result.logs`，失败进入 `result.error`。
 
 ```text
 const spec = ctx.ptcRuntime.resolve({
@@ -44,6 +44,8 @@ const result = await ctx.ptcRuntime.run(spec)
 
 后端以 `language` 与 `isolation` 提供诊断描述符；两者都不授予权限或证明约束。[`dsh-ptc-runtime-node`](../ptc-runtime-node/README.zh.md) 在全新的受管 Node 进程中按已解析沙箱策略执行可擦除 TypeScript。私有的 [`dsh-experimental-ptc-runtime-python`](../../experimental/ptc-runtime-python/README.zh.md) 提供方在全新 CPython 子进程中执行 Python，不提供文件约束。`sandboxMode` 声明提供方的部署文件策略模式；不支持该能力时则缺省。
 
+使用可选的[Node 内存保留模式](../ptc-runtime-node/README.zh.md#persistent-repl)时，跨调用传入同一个 `stateOwner` 对象，并在所有者结束时等待 `release(owner)`。不同对象不会共享环境；省略所有者时使用临时环境。无状态提供方忽略所有权。同一保留环境的调用不能重叠。
+
 ### 可移植地命名绑定
 
 binding-global 与 error-class 名称是语言可移植的：必须匹配 `[A-Za-z_][A-Za-z0-9_]*`，避开每个可移植目标语言的保留字，并避开后端拥有的槽位，因此同一份命名空间列表对每个后端都有效。`$tools`、`lambda` 或 `console` 之类的名称会在运行开始前失败；确切的排除集是 seam 约定的一部分。
@@ -90,7 +92,6 @@ binding-global 与 error-class 名称是语言可移植的：必须匹配标识
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：抽象 `PtcRuntime` 服务与可移植标识符排除集 |
 | [`src/types.ts`](src/types.ts) | 词汇：`PtcRunRequest`、`PtcRunSpec`、绑定、结果、失败与沙箱事实 |
-| — | 不发布运行时不变式伴生入口；本包不公开任何独立的事件序列或可变数据关系，相关约束仅由其所属 seam 的约定实施。 |
 
 </details>
 
@@ -126,7 +127,7 @@ binding-global 与 error-class 名称是语言可移植的：必须匹配标识
 这些限制说明 seam 不能做什么；它们是当前包约束，不是任务积压。
 
 - **`run()` 是一次性的**——`logs` 只有在 `PtcRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。
-- **运行之间不保留状态**——每次请求都在全新环境中运行；持久 REPL 风格内核在某个后端带来自己的日志方案之前保持延期。
+- **保留内存可以丢失**：提供方可以为显式所有者保留状态；重启、释放以及提供方指定的失败会清除状态。程序、绑定调用和结果仍由消费者记录；运行中的对象不会被序列化或回放。
 - **提供方的约束能力不同**——已发布 Node 提供方强制执行已解析文件策略，私有实验性 Python 提供方拒绝显式策略。不提供容器提供方。
 - **提供方之间没有统一的绑定字节上限**——各提供方负责自己的传输限制；绑定仍可能在结果到达这些限制前分配内存。
 
@@ -138,9 +139,9 @@ binding-global 与 error-class 名称是语言可移植的：必须匹配标识
 
 本开发备注是维护者的工作上下文：尚未决定的方向与开放问题。它明确不具权威性——已交付的行为与限制以上文和包代码为准。
 
-#### 未来：持久内核后端
+#### 保留状态
 
-跨 `run_code` 调用保留状态的 REPL 风格内核仍未决定；它需要自己的日志方案，因为「运行之间不保留状态」的约定正是让每次请求仅凭会话日志即可重建的原因。
+保留状态没有磁盘检查点或恢复协议。消费者必须容忍状态丢失，并在 Session 日志中记录模型可见的程序与结果。
 
 #### 未来：容器后端
 

package/lib/index.js

@@ -141,10 +141,24 @@ const PORTABLE_RESERVED_WORDS = new Set([
 * Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate
 * failures resolve in {@link PtcRunResult}; only Service Definition contract misuse rejects. Implementations bridge
 * structured-cloneable bindings, materialize each declared namespace rejection
-* class, treat programs as hostile peers, isolate runs from one another, and
+* class, treat programs as hostile peers, isolate distinct state owners, and
 * terminate and await in-flight runs during disposal.
 */
 var PtcRuntime = class extends Service {
+	/** Source evaluation form, independent of whether the provider retains state for an owner. */
+	get programFormat() {
+		return "function-body";
+	}
+	/**
+	* Release an owner's retained environment and await its execution resources.
+	* Stateless providers have no retained resources to release.
+	* @param owner - The exact object supplied as the request's state owner.
+	* @returns Completion after all owned execution resources have been released.
+	* @throws When managed resource cleanup fails.
+	*/
+	release(owner) {
+		return Promise.resolve();
+	}
 	/** Provider-owned program usage guidance for consumers to present alongside the source language. */
 	get executionInstructions() {
 		return "";

package/lib/types/index.d.ts

@@ -63,7 +63,7 @@ declare module '@deepseek-ai/cordis' {
  * Registers one `ctx.ptcRuntime` implementation. Program, budget, abort, and substrate
  * failures resolve in {@link PtcRunResult}; only Service Definition contract misuse rejects. Implementations bridge
  * structured-cloneable bindings, materialize each declared namespace rejection
- * class, treat programs as hostile peers, isolate runs from one another, and
+ * class, treat programs as hostile peers, isolate distinct state owners, and
  * terminate and await in-flight runs during disposal.
  */
 export declare abstract class PtcRuntime extends Service {
@@ -84,6 +84,16 @@ export declare abstract class PtcRuntime extends Service {
      * `'process'`, `'container'`.
      */
     abstract readonly isolation: string;
+    /** Source evaluation form, independent of whether the provider retains state for an owner. */
+    get programFormat(): 'function-body' | 'repl';
+    /**
+     * Release an owner's retained environment and await its execution resources.
+     * Stateless providers have no retained resources to release.
+     * @param owner - The exact object supplied as the request's state owner.
+     * @returns Completion after all owned execution resources have been released.
+     * @throws When managed resource cleanup fails.
+     */
+    release(owner: object): Promise<void>;
     /** Provider-owned program usage guidance for consumers to present alongside the source language. */
     get executionInstructions(): string;
     /** Deployment file-policy mode, or undefined for a provider without confinement support. */

package/lib/types/types.d.ts

@@ -69,11 +69,18 @@ export interface PtcBindingNamespace {
 export interface PtcRunRequest {
     /**
      * The program source, in the runtime's {@link ../index.ts | language}. It
-     * runs as the body of an async function: top-level `await` and `return`
-     * are available, and the completion value becomes
+     * follows the provider's programFormat: an async function body supports
+     * top-level `await` and `return`; a REPL supports top-level declarations,
+     * `await`, and a final expression. The completion value becomes
      * {@link PtcRunResult.value}.
      */
     program: string;
+    /**
+     * Object-identity owner for optional in-memory state. Omission requests a fresh
+     * environment. Consumers must await runtime.release(owner) when the owner ends.
+     * Stateless providers ignore this field; retained state is never durable.
+     */
+    stateOwner?: object;
     /** Host functions exposed to the program, one global object per namespace. */
     bindings: PtcBindingNamespace[];
     /** Working directory in the mounted filesystem and subprocess execution world. */
@@ -110,7 +117,7 @@ export interface PtcRunSandbox {
 }
 /**
  * Why a run failed. The kinds are orthogonal outcomes reported independently
- * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
+ * (per docs/defensive-patterns/general.md): a budget expiry is not an exception, an
  * abort is not a timeout, and a substrate death is neither.
  *
  * - `'exception'` — the program threw or failed to parse/transform.
@@ -137,7 +144,7 @@ export interface PtcRunResult {
     /** Applied file policy and observed denial, when the provider enforces file policy. */
     sandbox?: PtcRunSandbox;
     /**
-     * The program's completion value (its top-level `return`), when it ran to
+     * The program's completion value (a return or final REPL expression), when it ran to
      * completion and the value crossed the runtime's lossless-JSON boundary.
      * Invalid or over-limit completions fail the run instead of substituting a
      * rendered string; a failed or value-less run leaves this absent.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x1a0f3n9/dsh-ptc-runtime",
   "description": "Abstract PTC execution seam (ctx.ptcRuntime) for the DeepSeek Harness",
-  "version": "0.1.7-rc.4",
+  "version": "0.2.1-rc.3",
   "publishConfig": {
     "access": "public"
   },
@@ -27,11 +27,11 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@x1a0f3n9/dsh-sandbox": "0.1.7-rc.4"
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@x1a0f3n9/dsh-sandbox": "0.2.1-rc.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4",
-    "@x1a0f3n9/dsh-sandbox": "0.1.7-rc.4"
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@x1a0f3n9/dsh-sandbox": "0.2.1-rc.3"
   }
 }