@lingfan-engine/core 0.1.5 → 0.3.0

package/src/runtime/ops/media/shared.ts

@@ -0,0 +1,133 @@
+/**
+ * 媒体域共用：op 负载白名单与音量 / 淡出解析。
+ *
+ * 白名单是 fail-closed 的唯一来源——执行器只查这里，未知字段一律拒绝；
+ * 音量与淡出是音频与视频两族共用的窄化，口径必须一处（否则同一个
+ * `volume` 在两条命令上会有两种边界行为）。
+ */
+import {
+  SYS,
+  type AudioChannel,
+  type AudioChannelState,
+} from "../../../contracts/index.ts";
+import type { OpContext } from "../../internal/index.ts";
+
+/** 音频 op 已知负载字段（未知字段 fail-closed） */
+export const AUDIO_FIELDS: Record<string, ReadonlySet<string>> = {
+  bgm: new Set(["op", "resource", "volume", "loop", "fade", "restart"]),
+  se: new Set(["op", "resource", "volume"]),
+  ambient: new Set(["op", "resource", "volume", "loop", "fade", "restart"]),
+  stop_bgm: new Set(["op", "fade"]),
+  stop_ambient: new Set(["op", "fade"]),
+  stop_se: new Set(["op", "fade"]),
+  voice: new Set(["op", "resource", "volume", "auto_stop", "restart"]),
+  stop_voice: new Set(["op", "fade"]),
+  audio_play: new Set([
+    "op",
+    "inst",
+    "channel",
+    "resource",
+    "volume",
+    "loop",
+    "fade",
+    "restart",
+  ]),
+  audio_stop: new Set(["op", "inst", "fade"]),
+  audio_volume: new Set(["op", "inst", "volume"]),
+  audio_pause: new Set(["op", "channel"]),
+  audio_resume: new Set(["op", "channel"]),
+};
+
+/** 停止类 op → 目标常驻通道系统键 */
+export const AUDIO_STOP_KEY: Record<string, string> = {
+  stop_bgm: SYS.audioBgm,
+  stop_ambient: SYS.audioAmbient,
+  stop_voice: SYS.audioVoice,
+};
+
+/** 音频通道 op → 常驻通道系统键（se 为一次性触发，不在表内） */
+export const AUDIO_CHANNEL_KEY: Record<string, string> = {
+  bgm: SYS.audioBgm,
+  ambient: SYS.audioAmbient,
+  voice: SYS.audioVoice,
+};
+
+/**
+ * volume 三级解析：命令显式值 ?? 工程默认（`shell.audio.volumes[通道]`）?? 1。
+ *
+ * 顺序不能反：显式值是作者在这一条命令上的意图，工程默认是整部作品的口径，
+ * 内建 1 只在前两级都缺席时兜底（与「不指定 = 满音量」的既有语义逐字节一致）。
+ * 玩家偏好不在这里——它是渲染层最外层的乘算，混进来会让「换个工程，玩家设置
+ * 被这个工程的默认值改掉」。
+ *
+ * `channel` 缺省（视频族）表示没有工程默认级：视频音量只认命令与内建 1。
+ * 非有限数字一律 fail-closed（作者写错不能静默当满音量），越界按物理范围钳制。
+ */
+export function audioVolume(
+  ctx: OpContext,
+  raw: unknown,
+  op: string,
+  channel?: AudioChannel,
+): number | null {
+  let explicit: number | undefined;
+  if (raw !== undefined) {
+    if (typeof raw !== "number" || !Number.isFinite(raw)) {
+      ctx.fail(`${op}-invalid-volume`, `${op} 的 volume 必须是有限数字`);
+      return null;
+    }
+    explicit = raw;
+  }
+  const fallback =
+    channel === undefined ? 1 : (ctx.audioConfig.volumes[channel] ?? 1);
+  return Math.min(1, Math.max(0, explicit ?? fallback));
+}
+
+/** fade 窄化：缺省 0；负数/非有限数字 fail-closed */
+export function audioFade(
+  ctx: OpContext,
+  raw: unknown,
+  op: string,
+): number | null {
+  if (raw === undefined) return 0;
+  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
+    ctx.fail(`${op}-invalid-fade`, `${op} 的 fade 必须是非负有限数字（毫秒）`);
+    return null;
+  }
+  return raw;
+}
+
+/**
+ * 播放态判定：暂停记账只记录「有东西可续播」的状态。
+ *
+ * `pause` 态本身不带资源、`stop` 态已经结束，两者都没有可写回的播放态。判据按契约
+ * 形状严格比对——记账表随快照 / 存档随行，读回来的可能是被外部改坏的值，把非 play
+ * 态当成 play 态会让恢复写回一条没有资源的播放态。
+ */
+export function isPlayState(value: unknown): value is AudioChannelState {
+  if (value === null || typeof value !== "object") return false;
+  const state = value as { kind?: unknown; resource?: unknown };
+  return state.kind === "play" && typeof state.resource === "string";
+}
+
+/**
+ * 读 `SYS.audioPaused` 暂停记账表：逐项只留 play 态，形状不合按空表处理。
+ *
+ * 同一张表按两套键空间分区存放：常驻通道项用通道名（`bgm` / `ambient` / `voice`），
+ * 音频实例项用 `inst:<实例id>`。这里原样返回全部键，由调用方按自己的键空间取值——
+ * 在读函数里按前缀过滤会让另一族读不到自己的项。
+ *
+ * 外部改坏的值一律静默过滤：一条脏值不该让整条暂停 / 恢复路径失败。
+ */
+export function readPausedPlayStates(
+  ctx: OpContext,
+): Record<string, AudioChannelState> {
+  const value = ctx.get(SYS.audioPaused);
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const out: Record<string, AudioChannelState> = {};
+  for (const [key, state] of Object.entries(value as Record<string, unknown>)) {
+    if (isPlayState(state)) out[key] = state;
+  }
+  return out;
+}

package/src/runtime/ops/media/video.ts

@@ -0,0 +1,118 @@
+/**
+ * 视频族：核心只写命令流（`__video`，seq 单调），渲染器按序执行。
+ */
+import {
+  SYS,
+  type StoryCommand,
+  type VideoCommand,
+} from "../../../contracts/index.ts";
+import type { Frame, OpContext } from "../../internal/index.ts";
+import { audioVolume } from "./shared.ts";
+
+/** 视频族已知负载字段（未知字段 fail-closed） */
+const VIDEO_FIELDS: Record<string, ReadonlySet<string>> = {
+  video: new Set(["op", "resource", "volume", "loop", "z"]),
+  cutscene: new Set(["op", "resource", "volume", "skipable", "z"]),
+  seek_video: new Set(["op", "seconds"]),
+  pause_video: new Set(["op"]),
+  resume_video: new Set(["op"]),
+  stop_video: new Set(["op"]),
+  video_skipable: new Set(["op", "value"]),
+};
+
+/**
+ * 视频族：核心只写命令流（`__video`，seq 单调），渲染器按序执行。
+ * - `video` = 非阻塞播放（故事继续）；`cutscene` = 阻塞过场（等待建立时提交检查点，
+ *   同 menu/wait/input；ended/跳过解除）。
+ * - `seek_video`/`pause_video`/`resume_video`/`stop_video` 为离散命令；
+ *   `video_skipable` 设后续 video/cutscene 的缺省 skipable。
+ */
+export function execVideo(
+  ctx: OpContext,
+  frame: Frame,
+  cmd: StoryCommand,
+  cutscene = false,
+): boolean {
+  const known = VIDEO_FIELDS[cmd.op]!;
+  const unknown = Object.keys(cmd).filter((k) => !known.has(k));
+  if (unknown.length > 0) {
+    ctx.fail(
+      `${cmd.op}-unknown-field`,
+      `${cmd.op} 未知负载字段：${unknown.join(", ")}`,
+    );
+    return false;
+  }
+  ctx.videoSeq += 1;
+  const seq = ctx.videoSeq;
+  if (cmd.op === "video" || cmd.op === "cutscene") {
+    if (ctx.rejectBadInstanceZ(cmd)) return false; // 先拒非法 z（不动状态）
+    ctx.setInstanceZ(SYS.videoZ, cmd.z); // 视频层实例 z（宿主解析后交 VideoPort.setZIndex）
+    if (typeof cmd.resource !== "string" || cmd.resource === "") {
+      ctx.fail(
+        `${cmd.op}-invalid-resource`,
+        `${cmd.op} 需要非空 resource 字符串`,
+      );
+      return false;
+    }
+    const volume = audioVolume(ctx, cmd.volume, cmd.op);
+    if (volume === null) return false;
+    // skipable：cutscene 显式参数 > video_skipable 持久开关（缺省可跳）
+    const skipable =
+      cutscene && cmd.skipable !== undefined
+        ? cmd.skipable === true
+        : ctx.get(SYS.videoSkipable) !== false;
+    ctx.setSystem(SYS.video, {
+      kind: "play",
+      resource: cmd.resource,
+      volume,
+      loop: cmd.loop === true,
+      cutscene,
+      skipable,
+      seq,
+    } satisfies VideoCommand);
+    if (cutscene) {
+      // 过场等待建立时提交检查点（同 menu/wait/input）；重放期同坐标原位替换
+      ctx.setSystem(SYS.waiting, "video");
+      ctx.commitCheckpoint(ctx.takeSnapshot(ctx.checkpointCoord(frame)));
+      ctx.liveCheckpointed = true;
+      ctx.autoSaveAtCheckpoint(); // cutscene 等待画面建立 = auto_save 消费点
+      frame.index += 1;
+    }
+    return true;
+  }
+  if (cmd.op === "seek_video") {
+    const seconds = cmd.seconds;
+    if (
+      typeof seconds !== "number" ||
+      !Number.isFinite(seconds) ||
+      seconds < 0
+    ) {
+      ctx.fail(
+        "seek_video-invalid-seconds",
+        "seek_video 需要非负有限数字（秒）",
+      );
+      return false;
+    }
+    ctx.setSystem(SYS.video, {
+      kind: "seek",
+      seconds,
+      seq,
+    } satisfies VideoCommand);
+    return true;
+  }
+  if (cmd.op === "pause_video") {
+    ctx.setSystem(SYS.video, { kind: "pause", seq } satisfies VideoCommand);
+    return true;
+  }
+  if (cmd.op === "resume_video") {
+    ctx.setSystem(SYS.video, { kind: "resume", seq } satisfies VideoCommand);
+    return true;
+  }
+  if (cmd.op === "stop_video") {
+    ctx.setSystem(SYS.video, { kind: "stop", seq } satisfies VideoCommand);
+    return true;
+  }
+  // video_skipable
+  ctx.setSystem(SYS.videoSkipable, cmd.value !== false);
+  return true;
+}

package/src/runtime/ops/ui.ts

@@ -0,0 +1,95 @@
+/**
+ * UI 挂载的执行：把「哪个组件该不该出现在渲染树上、带什么入参」写成状态。
+ *
+ * 核心只写 `SYS.mounts` 这张表，不碰 DOM、不认识组件内部——挂载与卸载是宿主的活。
+ * `visible: false` 的语义是**从渲染树移除**（卸载），不是 `display: none`：
+ * 隐藏的组件不该继续跑生命周期与计时器。整表随快照 / 存档 / 回溯自动随行。
+ */
+import {
+  SYS,
+  type MountTable,
+  type StoryCommand,
+} from "../../contracts/index.ts";
+import { isMountTable, isUiName, UI_NAME_PATTERN } from "../../shared/index.ts";
+import { findJsonValueError } from "../state/stateContract.ts";
+import type { OpContext } from "../internal/index.ts";
+
+/** `mount` 已知负载字段（未知字段 fail-closed） */
+const MOUNT_OP_FIELDS: ReadonlySet<string> = new Set([
+  "op",
+  "name",
+  "visible",
+  "props",
+]);
+
+/** 读挂载表：形状不合（外部改坏）按空表处理，不让一条脏值卡死整个挂载域 */
+function mountTableOf(ctx: OpContext): MountTable {
+  const value = ctx.get(SYS.mounts);
+  return isMountTable(value) ? value : {};
+}
+
+/**
+ * 挂载 / 卸载一个 UI 组件：`mount(hub, true)`、`mount(hub, false, { scene: "forest" })`。
+ *
+ * - `visible` 必填布尔：没有「切换」语义，显式写显隐才能让回溯读到确定的终值
+ * - `props` 可选：给了就**整份替换**（不是浅合并）——合并语义会让「删掉一个入参」
+ *   无法表达，而组件的入参集合是它的契约，得能完整指定
+ * - 整表新建后写回：**不得原地改** `table[name]`，否则回溯会拿到被污染的值
+ */
+export function execMount(ctx: OpContext, cmd: StoryCommand): boolean {
+  const unknown = Object.keys(cmd).filter((k) => !MOUNT_OP_FIELDS.has(k));
+  if (unknown.length > 0) {
+    ctx.fail(
+      "mount-unknown-field",
+      `mount 未知负载字段：${unknown.join(", ")}`,
+    );
+    return false;
+  }
+  const { name, visible } = cmd;
+  if (!isUiName(name)) {
+    ctx.fail(
+      "mount-invalid-name",
+      `mount 的 name 不合法：${JSON.stringify(name)}（须匹配 ${UI_NAME_PATTERN.source}）`,
+    );
+    return false;
+  }
+  if (typeof visible !== "boolean") {
+    ctx.fail(
+      "mount-invalid-visible",
+      `mount 的 visible 必须是布尔：${JSON.stringify(visible)}`,
+    );
+    return false;
+  }
+  const rawProps = cmd.props;
+  let props: Record<string, unknown> = {};
+  if (rawProps !== undefined) {
+    if (
+      typeof rawProps !== "object" ||
+      rawProps === null ||
+      Array.isArray(rawProps)
+    ) {
+      ctx.fail(
+        "mount-invalid-props",
+        `mount 的 props 必须是对象：${JSON.stringify(rawProps)}`,
+      );
+      return false;
+    }
+    const unsafe = findJsonValueError(rawProps, "mount.props");
+    if (unsafe !== null) {
+      ctx.fail(
+        "mount-unsafe-props",
+        `mount 的 props 不是 JSON 安全的值——${unsafe}`,
+      );
+      return false;
+    }
+    props = rawProps as Record<string, unknown>;
+  }
+  const table = mountTableOf(ctx);
+  const next: Record<
+    string,
+    { visible: boolean; props: Record<string, unknown> }
+  > = { ...table };
+  next[name] = { visible, props };
+  ctx.setSystem(SYS.mounts, next satisfies MountTable);
+  return true;
+}

package/src/runtime/paramDirection.ts

@@ -0,0 +1,35 @@
+/**
+ * 参数方向查表：`PARAM_DIRECTION` 的取值实现。
+ *
+ * **为什么实现在 runtime 而不是 contracts**：契约层只放类型与数据，出现函数关键字即违约
+ * （由 `tests/engine/runtime/scene-type.test.ts` 的「契约层只声明类型」判据锁住）。
+ * 表本身仍是声明（`contracts/param-direction.ts`），本文件只负责查。
+ */
+import {
+  PARAM_DIRECTION,
+  type ParamDirection,
+} from "../contracts/param-direction.ts";
+
+/**
+ * 查某键的方向档位：精确键优先，其次最长前缀匹配，都不命中 = `readonly`。
+ *
+ * 最长前缀而非首个命中：`game.` 与 `game.walk.` 同时存在时后者应赢，
+ * 否则细分命名空间无法覆盖粗粒度默认。
+ *
+ * 缺省 `readonly` 是 fail-closed：新键默认不给写权限，要开放必须显式登记。
+ */
+export function directionOf(key: string): ParamDirection {
+  const exact = PARAM_DIRECTION[key];
+  if (exact !== undefined) return exact;
+  let best: ParamDirection | undefined;
+  let bestLength = 0;
+  for (const [pattern, direction] of Object.entries(PARAM_DIRECTION)) {
+    if (!pattern.endsWith(".")) continue; // 精确键已在上面查过
+    if (!key.startsWith(pattern)) continue;
+    if (pattern.length > bestLength) {
+      best = direction;
+      bestLength = pattern.length;
+    }
+  }
+  return best ?? "readonly";
+}

package/src/runtime/save/export.ts

@@ -2,16 +2,50 @@
  * 存档导出。
  */
 import {
+  SESSION_STATE_KEYS,
   SYS,
   type ColumnCoordinate,
   type SaveDataV1,
 } from "../../contracts/index.ts";
-import { parseMenuReturn, type OpContext } from "../internal/index.ts";
-import { findJsonValueError } from "../stateContract.ts";
+import {
+  parseMenuReturn,
+  type Frame,
+  type OpContext,
+} from "../internal/index.ts";
+import { findJsonValueError } from "../state/stateContract.ts";
+
+/** 存档面的状态条目：会话态键不写进档（读档 = 会话重开，见 `SESSION_STATE_KEYS`） */
+function saveStateEntries(
+  entries: Iterable<[string, unknown]>,
+): [string, unknown][] {
+  return [...entries]
+    .filter(([key]) => !SESSION_STATE_KEYS.has(key))
+    .map(([key, value]) => [key, value]);
+}
+
+/**
+ * 历史检查点对应的列级作用域条目（未用到 = 字段缺席）。
+ *
+ * 检查点的帧栈自带各帧作用域深拷贝，取其中列帧那一层即可；找不到列帧
+ * （坐标属已删列等）⇒ 缺席，读档侧按空层重建。
+ */
+function historyScopeOf(frames: readonly Frame[]): {
+  scope?: [string, unknown][];
+} {
+  for (let i = frames.length - 1; i >= 0; i -= 1) {
+    const frame = frames[i]!;
+    if (frame.columnId === null) continue;
+    const entries = frame.scope.ownEntries();
+    return entries.length > 0 ? { scope: entries } : {};
+  }
+  return {};
+}
 
 /**
  * 导出存档载荷。必须在等待点调用（列尾/未启动 fail-closed 拒绝）。
- * 载荷 = 等待点坐标 + 全局状态 + rngState + 函数表 + 历史；不含块/列级作用域与帧栈。
+ * 载荷 = 等待点坐标 + 全局状态 + 列级作用域 + rngState + 函数表 + 历史；
+ * 块级作用域与帧栈不随档（由坐标重放重建，见 `columnFrameAt`）；
+ * **会话态键也不随档**（暂停标记 / 菜单返回记账 / 重放标记，见 `SESSION_STATE_KEYS`）。
  *
  * **场景类型守卫**：在 `menu`/`ui` 场景按存档，**存的是「菜单前的游戏进度」
  * 而不是菜单状态**（对标 Ren'Py Esc 菜单存档）。
@@ -49,7 +83,10 @@ export function exportSave(ctx: OpContext): SaveDataV1 | null {
   let coord: ColumnCoordinate;
   let historyCursor = ctx.cursor;
   let historyList = ctx.history;
-  if (!ctx.isCurrentColumnReplayable()) {
+  // 存的是不是「当前列的游戏进度」：菜单/界面列存档走 `__menu_return`，
+  // 存的是菜单前的坐标，与当前帧不是同一列（那条路径下作用域拿不到）。
+  const isReplayable = ctx.isCurrentColumnReplayable();
+  if (!isReplayable) {
     if (menuReturn === null) {
       ctx.fail(
         "save-invalid",
@@ -68,20 +105,29 @@ export function exportSave(ctx: OpContext): SaveDataV1 | null {
       index: Math.max(0, columnFrame.index - 1),
     };
   }
+  // 列级作用域随档——但只在「存的就是当前列」时才有意义：菜单里存档存的是
+  // 菜单前的游戏坐标，那一列的帧早已被 `enterColumn` 换掉，拿不到它的作用域。
+  // 此时字段缺席（= 空列级层），与旧档形状一致。
+  const columnScope = isReplayable ? columnFrame.scope.ownEntries() : [];
   return {
     formatVersion: 1,
     storyId: ctx.story.id,
     // 故事版本随档（读档侧按它判定 migrateState 迁移路径；缺省 1）
     storyVersion: ctx.story.version ?? 1,
     coord,
-    state: [...ctx.state.entries()],
+    state: saveStateEntries(ctx.state.entries()),
+    // 列级作用域（未用到 = 字段缺席，读档垫底据此按空层重建）
+    ...(columnScope.length > 0 ? { scope: columnScope } : {}),
     rngState: ctx.rngState,
     functions: [...ctx.functions.entries()],
     cursor: historyCursor,
     history: historyList.map((cp) => ({
       coord: { ...cp.coord },
-      state: cp.snapshot.state,
+      state: saveStateEntries(cp.snapshot.state),
       rngState: cp.snapshot.rngState,
+      // 每个检查点各带一份列级作用域：回溯目标可以是档内任何一步，
+      // 只存一份档尾的层没法回答「那一步当时的列级变量是多少」。
+      ...historyScopeOf(cp.snapshot.frames),
     })),
     // 全局层 undef 墓碑（帧层 undef 不记；未用到 = 字段缺席，读档垫底据此挡默认值复活）
     ...(ctx.deleted.size > 0 ? { deleted: [...ctx.deleted] } : {}),

package/src/runtime/save/import.ts

@@ -2,15 +2,26 @@
  * 存档导入。
  */
 import {
+  SESSION_STATE_KEYS,
   SYS,
   type ColumnCoordinate,
   type SaveDataV1,
 } from "../../contracts/index.ts";
-import type { OpContext } from "../internal/index.ts";
+import { parseScopeEntries, type OpContext } from "../internal/index.ts";
+
+/** 读档面的状态条目：会话态键一律丢弃（旧档里可能还留着，见 `SESSION_STATE_KEYS`） */
+function loadStateEntries(
+  entries: readonly (readonly [string, unknown])[],
+): [string, unknown][] {
+  return entries
+    .filter(([key]) => !SESSION_STATE_KEYS.has(key))
+    .map(([key, value]) => [key, value]);
+}
 
 /**
  * 读档——恢复全局态与历史，从存档坐标重放重建等待点。
- * 帧栈按坐标重建列帧；故事版本不匹配 fail-closed。
+ * 帧栈按坐标重建列帧；**列级作用域来自档内的 `scope`**（旧档无该字段 =
+ * 空列级层，行为与修复前一致）；块级作用域由坐标重放重建。故事版本不匹配 fail-closed。
  * 返回 false = 已拒绝（engine.error 事件已出站），调用方不得当作成功处理。
  */
 export function importSave(ctx: OpContext, data: SaveDataV1): boolean {
@@ -160,18 +171,20 @@ export function importSave(ctx: OpContext, data: SaveDataV1): boolean {
     pendingSay: ctx.pendingSay,
     liveCheckpointed: ctx.liveCheckpointed,
   };
-  ctx.state = new Map(data.state); // 垫底后的全量状态（扩展恢复 + 玩法系统 + defines 补齐）
+  ctx.state = new Map(loadStateEntries(data.state)); // 垫底后的全量状态（扩展恢复 + 玩法系统 + defines 补齐）
   ctx.rngState = data.rngState;
   ctx.functions = new Map(data.functions);
   // 角色表重置为构造期初值（模块层声明「进场即有」）：档不携带角色表，
   // 读档 = 会话重开，列内运行期覆盖不随档继承（与快照回溯面不同，档格式 v1 无此字段）
   ctx.characters = new Map();
+  // 档内检查点各自带一份列级作用域：回溯到档内任意一步时要能恢复那一步的
+  // 列级变量（旧档无 `scope` 字段 ⇒ 按空层重建，与修复前一致）。
   ctx.history = data.history.map((h) => ({
     coord: { ...h.coord },
     snapshot: {
-      state: h.state,
+      state: loadStateEntries(h.state),
       rngState: h.rngState,
-      frames: [ctx.columnFrameAt(h.coord)],
+      frames: [ctx.columnFrameAt(h.coord, parseScopeEntries(h.scope) ?? [])],
       coord: { ...h.coord },
       functions: data.functions,
       // 墓碑随检查点回溯：回滚到 undef 之前的检查点时删除记录同步回退
@@ -188,7 +201,9 @@ export function importSave(ctx: OpContext, data: SaveDataV1): boolean {
       : Math.min(Math.max(data.cursor, 0), ctx.history.length - 1);
   ctx.started = true;
   ctx.pendingSay = null;
-  ctx.frames = [ctx.columnFrameAt(data.coord)];
+  ctx.frames = [
+    ctx.columnFrameAt(data.coord, parseScopeEntries(data.scope) ?? []),
+  ];
   ctx.coord = { ...data.coord };
   ctx.liveCheckpointed = true;
   if (!ctx.restoreSaveExtensions(data.extensions)) {

package/src/runtime/scope.ts

@@ -59,6 +59,23 @@ export class Scope {
     return this.vars.has(name);
   }
 
+  /**
+   * 本层变量导出（存档用）：只取这一层，不沿父链。
+   *
+   * 存档只携带**列级**层——那一层在存档坐标之前就声明完了，重放不会回到那些命令，
+   * 只能靠这条通道带过去；块级层由重放重建（见 `columnFrameAt`）。
+   */
+  ownEntries(): [string, unknown][] {
+    return [...this.vars.entries()];
+  }
+
+  /** 用导出的本层变量重建单层作用域（`ownEntries` 的逆操作） */
+  static fromEntries(entries: readonly (readonly [string, unknown])[]): Scope {
+    const scope = new Scope(null);
+    for (const [k, v] of entries) scope.vars.set(k, v);
+    return scope;
+  }
+
   /** 深拷贝作用域链（03 历史检查点：帧栈快照需独立副本，回溯恢复后互不串扰） */
   static cloneDeep(source: Scope | null): Scope {
     if (source === null) return Scope.root();

package/src/runtime/session/index.ts

@@ -0,0 +1,21 @@
+/**
+ * 会话挂起与等待的出口：引擎级暂停的执行面（`pause.ts`）与等待声明表（`waitingOps.ts`）。
+ *
+ * **名字消歧（重要）**：本目录的「会话」指**一次执行的挂起与恢复**——暂停时挂起等待定时器、
+ * 让出声的媒体收声、记下暂停标记，恢复时按剩余毫秒续上。它与
+ * `runtime/internal/session.ts` **不是同一件事**：后者是 op 上下文生命周期
+ * （启动、推进、选择、导航、存读档、语言切换与热重载），属运行层内部、不进包出口。
+ * 两者不同层，不要合并理解。
+ *
+ * **暂停标记的读口不在本目录**：`SYS.paused` 的唯一读口是
+ * `runtime/internal/waiting.ts` 的 `pausedSession`（该函数注释已写明别的模块不要自己
+ * `get` 一次再判）。本目录只是调用方，不再另开一次 `get(SYS.paused)`。
+ */
+export { pauseSession, resumeSession } from "./pause.ts";
+export {
+  collectWaitSpecs,
+  waitSpecOfOp,
+  WAITING_OPS,
+  waitingStateOfOp,
+  type WaitSpec,
+} from "./waitingOps.ts";