@lingfan-engine/core 0.2.0 → 0.3.0

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";

package/src/runtime/session/pause.ts

@@ -0,0 +1,114 @@
+/**
+ * 引擎级暂停与恢复：把「停住」与「中断」分成两件事。
+ *
+ * 暂停只做三件事——挂起等待定时器、让正在出声的媒体收声、记下暂停标记；
+ * 外部接管（小游戏 / 玩法系统 / 扩展 op 等待）**保持挂载**，它们只是不再收到推进输入。
+ * 所以这里不调 `abortExternalTakeovers`：那是中断的语义（销毁、导航、读档、回溯），
+ * 调了之后宿主会卸载接管面板，再恢复就不是「接着玩」而是「重进」。
+ *
+ * 恢复按暂停时记下的剩余毫秒续上原来的等待，媒体按**当前状态**逐个恢复——
+ * 暂停期间被命令改成 stop 的通道不复活（留着一条「该出声却永远不出声」的通道更糟）。
+ */
+import { SYS, type VideoCommand } from "../../contracts/index.ts";
+import {
+  armWaitTimer,
+  nowMs,
+  pausedSession,
+  type OpContext,
+} from "../internal/index.ts";
+import {
+  execAudioPause,
+  execAudioResume,
+  pauseAudioInstances,
+  resumeAudioInstances,
+} from "../ops/index.ts";
+
+/** 视频命令流里「正在播」的形态判定（暂停只对正在播的过场有意义） */
+function playingVideo(value: unknown): value is VideoCommand {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as { kind?: unknown }).kind === "play"
+  );
+}
+
+/** 视频命令流里「已暂停」的形态判定（恢复只对暂停过的过场有意义） */
+function pausedVideo(value: unknown): value is VideoCommand {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as { kind?: unknown }).kind === "pause"
+  );
+}
+
+/**
+ * 挂起等待定时器：记下剩余毫秒并取消，等恢复时按剩余量重排。
+ *
+ * 剩余量靠到期时刻与当前时刻相减——`clear` 之后句柄再也问不出「还剩多久」。
+ * 没有到期时刻（非本模块建立的定时器）就退回「不知道剩余量」，
+ * 恢复时宁可丢弃这段等待，也不排一个凭空多出来的完整时长。
+ */
+function suspendWaitTimer(ctx: OpContext): void {
+  const handle = ctx.pendingTimer;
+  if (handle === null) return;
+  const dueAt = ctx.pendingTimerDueAt;
+  ctx.pausedTimerRemainingMs =
+    dueAt === null ? null : Math.max(0, dueAt - nowMs(ctx));
+  ctx.timerPort.clear(handle);
+  ctx.pendingTimer = null;
+  ctx.pendingTimerDueAt = null;
+}
+
+/**
+ * 引擎级暂停：幂等，重复调用不改状态、不重复发事件。
+ *
+ * 常驻音频复用 `audio_pause` 的执行语义（只暂停 play 态、把暂停前的播放态记账），
+ * 引擎级暂停与作者手写 `audio_pause` 因此是同一件事，恢复时走同一条路。
+ * 实例族另走一遍：它们是另一张表（`SYS.audioInstances`），不受通道暂停覆盖，
+ * 漏掉就会留下「引擎已暂停、作者编排的环境音还在放」的状态。
+ */
+export function pauseSession(ctx: OpContext): void {
+  if (pausedSession(ctx)) return;
+  ctx.setSystem(SYS.paused, true);
+  suspendWaitTimer(ctx);
+  execAudioPause(ctx, { op: "audio_pause" });
+  pauseAudioInstances(ctx);
+  const video = ctx.get(SYS.video);
+  if (playingVideo(video)) {
+    ctx.videoSeq += 1;
+    ctx.setSystem(SYS.video, {
+      kind: "pause",
+      seq: ctx.videoSeq,
+    } satisfies VideoCommand);
+  }
+}
+
+/**
+ * 解除引擎级暂停：未暂停时幂等空操作。
+ *
+ * 续起等待前先确认故事仍停在同一个 wait 上——暂停期间可能读过档或导航过，
+ * 那时剩余毫秒属于一段已经不存在的等待，排出来只会提前解除别的等待。
+ */
+export function resumeSession(ctx: OpContext): void {
+  if (!pausedSession(ctx)) return;
+  ctx.setSystem(SYS.paused, false);
+  const remaining = ctx.pausedTimerRemainingMs;
+  ctx.pausedTimerRemainingMs = null;
+  if (
+    remaining !== null &&
+    ctx.pendingTimer === null &&
+    ctx.get(SYS.waiting) === "wait"
+  ) {
+    armWaitTimer(ctx, remaining);
+  }
+  execAudioResume(ctx, { op: "audio_resume" });
+  resumeAudioInstances(ctx);
+  const video = ctx.get(SYS.video);
+  if (pausedVideo(video)) {
+    ctx.videoSeq += 1;
+    ctx.setSystem(SYS.video, {
+      kind: "resume",
+      seq: ctx.videoSeq,
+    } satisfies VideoCommand);
+  }
+}

package/src/runtime/{waitingOps.ts → session/waitingOps.ts}

@@ -16,7 +16,7 @@
  * 块体（if/while/switch/func 体）内的等待点：其检查点坐标按 `checkpointCoord` 的块帧回退语义
  * 落在**块进入命令**上——故静态切分时「块体内含等待 ⇒ 该块命令本身即边界」，无需逐 op 特判。
  */
-import type { OpExtension, WaitingState } from "../contracts/index.ts";
+import type { OpExtension, WaitingState } from "../../contracts/index.ts";
 
 /** 单个 op 的等待规格：等待态 + 是否硬等待（`pause` = 不可跳过） */
 export interface WaitSpec {

package/src/runtime/shell.ts

@@ -10,12 +10,16 @@
  */
 
 import {
+  AUDIO_CHANNELS,
+  DEFAULT_AUDIO_CONFIG,
   DEFAULT_LAYER_Z,
   DEFAULT_SAVES_CONFIG,
   DEFAULT_STAGE_CONFIG,
   isOrientationMode,
   LAYER_IDS,
   SYS,
+  type AudioChannel,
+  type AudioConfig,
   type LayerId,
   type LayerZTable,
   type OrientationMode,
@@ -32,12 +36,14 @@ import {
  * 后续并入包出口时统一改走包出口。
  */
 export {
+  DEFAULT_AUDIO_CONFIG,
   DEFAULT_LAYER_Z,
   DEFAULT_SAVES_CONFIG,
   DEFAULT_STAGE_CONFIG,
   LAYER_IDS,
 } from "../contracts/index.ts";
 export type {
+  AudioConfig,
   LayerId,
   LayerZOverrides,
   LayerZTable,
@@ -145,6 +151,26 @@ export function slotIds(count: number): string[] {
   return Array.from({ length: count }, (_, i) => `slot_${i + 1}`);
 }
 
+/** 取清单里一个非空字符串字段；不是字符串或是空串一律返回 null，由调用方决定回落 */
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * 解析工程展示名：`name` → `id` → 空串。
+ *
+ * 展示名是**给玩家看的**那一行字，与工程 id 是两个用途：id 是存储与引用目标（不可随意改），
+ * name 才是可随时换的招牌。缺 name 时退回 id 是为了让工程至少有个名字可显示；
+ * 两者都没有才算没名字（空串），由调用方决定怎么兜。
+ *
+ * 入参与其他壳配置解析同口径：`unknown`、不猜不抛——清单是外部文件，畸形是常态不是异常。
+ */
+export function resolveProjectName(manifest: unknown): string {
+  if (manifest === null || typeof manifest !== "object") return "";
+  const record = manifest as Record<string, unknown>;
+  return nonEmptyText(record.name) ?? nonEmptyText(record.id) ?? "";
+}
+
 /** 解析存档壳配置：内建默认 × 工程覆盖（`shell.saves`，逐键合并；非法值/越界忽略） */
 export function resolveSavesConfig(manifest: unknown): SavesConfig {
   const resolved: SavesConfig = {
@@ -173,6 +199,48 @@ export function resolveSavesConfig(manifest: unknown): SavesConfig {
   return resolved;
 }
 
+/* ============================ 音频壳配置 ============================ */
+
+/** 通道音量：有限数按物理范围钳制；其余（含缺键）回 null，由调用方保持默认 */
+function channelVolume(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return Math.min(1, Math.max(0, value));
+}
+
+/**
+ * 解析音频壳配置：内建默认（四通道皆 1）× 工程覆盖（`shell.audio.volumes`）。
+ *
+ * 与 `resolveSavesConfig` 同一口径（清单入参 `unknown`、不猜不抛），差别在越界处理：
+ * 越界值**钳制后采纳**（`1.5` ⇒ `1`）而不是丢弃——与命令面 `volume=` 的行为一致，
+ * 作者手滑写个越界数不该让音量悄悄回满。非有限数（`NaN`/`Infinity`/字符串）仍忽略，
+ * 它们不是「差一点」而是「不是数」。
+ *
+ * 真正的畸形在组装期就 fail-closed 了（`project.json: shell.audio.volumes.<通道>
+ * 必须为 0..1 的有限数字`），这里的宽松只是不让解析函数自己抛。
+ */
+export function resolveAudioConfig(
+  manifest: unknown,
+  defaults: AudioConfig = DEFAULT_AUDIO_CONFIG,
+): AudioConfig {
+  const resolved: Record<AudioChannel, number> = { ...defaults.volumes };
+  if (manifest === null || typeof manifest !== "object") {
+    return { volumes: resolved };
+  }
+  const shell = (manifest as { shell?: unknown }).shell;
+  if (shell === null || typeof shell !== "object") return { volumes: resolved };
+  const audio = (shell as { audio?: unknown }).audio;
+  if (audio === null || typeof audio !== "object") return { volumes: resolved };
+  const volumes = (audio as { volumes?: unknown }).volumes;
+  if (volumes === null || typeof volumes !== "object") {
+    return { volumes: resolved };
+  }
+  for (const channel of AUDIO_CHANNELS) {
+    const value = channelVolume((volumes as Record<string, unknown>)[channel]);
+    if (value !== null) resolved[channel] = value;
+  }
+  return { volumes: resolved };
+}
+
 /* ============================ 舞台适配配置 ============================ */
 
 /** 取 [min,max] 闭区间内的有限数（尺寸/倍率允许小数）；越界或非有限一律 null */

package/src/runtime/state/index.ts

@@ -1,5 +1,5 @@
 /**
- * 状态子层出口：写入通道、实例 z、表达式求值、出站面与状态读口。
+ * 状态子层出口：写入通道、写入契约守卫、实例 z、表达式求值、出站面与状态读口。
  *
  * 执行器与运行层内部模块从这里取状态相关成员；子层各文件之间仍按需直接引用。
  * 这里只做转发，不放任何实现。
@@ -9,3 +9,4 @@ export { rejectBadInstanceZ, setInstanceZ } from "./instance-z.ts";
 export { evalValue, readVariable, resolveName } from "./evaluate.ts";
 export { emitChange, emitErrorEvent, publishEvent } from "./notify.ts";
 export { createStateReader } from "./reader.ts";
+export { findJsonValueError, jsonUnsafeReason } from "./stateContract.ts";

package/src/runtime/state/reader.ts

@@ -11,6 +11,7 @@
  */
 import {
   SYS,
+  sceneTypeOf,
   type AudioChannel,
   type AudioChannelState,
   type ElementInstance,
@@ -18,6 +19,7 @@ import {
   type LayerId,
   type LayerZOverrides,
   type MenuChoice,
+  type SceneType,
   type StateReader,
   type StateSource,
   type VideoCommand,
@@ -44,7 +46,7 @@ function inUnitRange(value: unknown, fallback: number): number {
 }
 
 /**
- * 音频通道状态收窄：`stop` 只认淡出参数，`play` 缺资源或资源为空串即视为「无媒体」。
+ * 音频通道状态收窄：`stop` 只认淡出参数，`pause` 只认序号，`play` 缺资源或资源为空串即视为「无媒体」。
  *
  * `fadeMs` 非正数按 0（无淡出）算；`volume` 非有限数按 1 并钳到 0..1；
  * `autoStop` / `restart` 只在显式为 `true` 时保留（缺字段与 `false` 同义）；
@@ -65,6 +67,10 @@ function channelStateOf(value: unknown): AudioChannelState | null {
   const fade = finiteNumber(state.fadeMs);
   const fadeMs = fade !== null && fade > 0 ? fade : 0;
   if (state.kind === "stop") return { kind: "stop", fadeMs };
+  if (state.kind === "pause") {
+    const pauseSeq = finiteNumber(state.seq);
+    return { kind: "pause", ...(pauseSeq === null ? {} : { seq: pauseSeq }) };
+  }
   if (state.kind !== "play") return null;
   if (typeof state.resource !== "string" || state.resource === "") return null;
   const seq = finiteNumber(state.seq);
@@ -133,6 +139,27 @@ function textOf(value: unknown): string {
 /** 见契约 `StateReader`：各方法的降级口径写在契约的字段注释里。 */
 export function createStateReader(source: StateSource): StateReader {
   const get = (key: string): unknown => source.get(key);
+
+  /**
+   * 当前列 id：非字符串一律当空串（与 `textOf` 同口径）。
+   *
+   * 空串同时表达「还没进列」与「值被改坏」——两者对界面是同一件事：没有当前位置。
+   */
+  const currentColumnId = (): string => textOf(get(SYS.currentSceneColumn));
+
+  /**
+   * 当前列类型：从列清单里查 id 对应的类型，查不到即缺省。
+   *
+   * 「查不到」有三种来源，对界面是同一件事（没有可用的当前列）：启动期尚未进列、
+   * 读口拿不到列清单、id 已失效（热重载后坐标过期）。三种都交给 `sceneTypeOf` 归一，
+   * 缺省口径因此只有一处——与列清单、与可回溯判定同源，这里不另判一遍。
+   */
+  const currentColumnType = (): SceneType => {
+    const id = currentColumnId();
+    const columns = source.columns?.() ?? [];
+    return sceneTypeOf(columns.find((column) => column.id === id) ?? {});
+  };
+
   return {
     audioChannel(channel: AudioChannel): AudioChannelState | null {
       return channelStateOf(get(AUDIO_CHANNEL_KEY[channel]));
@@ -234,5 +261,9 @@ export function createStateReader(source: StateSource): StateReader {
       }
       return overrides;
     },
+
+    currentColumnId,
+
+    currentColumnType,
   };
 }

package/src/runtime/state/writer.ts

@@ -6,7 +6,7 @@ import {
   RESERVED_STATE_KEYS,
 } from "../../contracts/index.ts";
 import type { OpContext } from "../internal/index.ts";
-import { findJsonValueError } from "../stateContract.ts";
+import { findJsonValueError } from "./stateContract.ts";
 
 /**
  * 全局层写入（作者 `set`/`define` / 小游戏奖励 / 数组族 op 的唯一汇聚点）。

package/src/shared/audio.ts

@@ -0,0 +1,106 @@
+/**
+ * 音频实例表的读入判据：把运行期到手的 `unknown` 收窄成契约里的实例表。
+ *
+ * 契约层只声明形态，实例表却可能来自存档、来自扩展、来自被改坏的工程文件，
+ * 所以每次读入都得先判后用（与 `guards.ts` 同一套纪律：判不过就由调用方
+ * fail-closed，这里不抛错也不猜默认值）。
+ *
+ * 三条规则一次判清，缺一条都会让坏数据漏进状态：
+ * - 表是普通对象（数组与 `null` 不算——数组会把下标当实例 id）
+ * - 实例 id 合 `AUDIO_INSTANCE_ID_PATTERN`（作者要按名字点名，形态必须统一）
+ * - 实例数不超 `MAX_AUDIO_INSTANCES`（整表进快照与存档，无上限存档会写到写不动）
+ */
+import {
+  AUDIO_INSTANCE_ID_PATTERN,
+  MAX_AUDIO_INSTANCES,
+  type AudioChannel,
+  type AudioChannelState,
+  type AudioInstanceState,
+  type AudioInstanceTable,
+} from "../contracts/media/index.ts";
+import { isPlainObject } from "./guards.ts";
+
+const AUDIO_CHANNELS: readonly string[] = ["bgm", "se", "ambient", "voice"];
+
+/** 是否是已知的音频通道（`bgm` / `se` / `ambient` / `voice`） */
+export function isAudioChannel(value: unknown): value is AudioChannel {
+  return typeof value === "string" && AUDIO_CHANNELS.includes(value);
+}
+
+/** 是否是合形态的实例 id（与扩展 / 玩法系统同一份短 id 规则） */
+export function isAudioInstanceId(value: unknown): value is string {
+  return typeof value === "string" && AUDIO_INSTANCE_ID_PATTERN.test(value);
+}
+
+/**
+ * 通道状态判据：按 `kind` 分支判各自字段。
+ *
+ * 不能先统一要求 `fadeMs` 存在——`pause` 态不带淡出参数，那样会把合法的暂停
+ * 判成坏数据（读入 fail-closed 后暂停就丢了）。淡出只在 `play` / `stop` 分支里判。
+ */
+function isChannelState(value: unknown): value is AudioChannelState {
+  if (!isPlainObject(value)) return false;
+  if (value.kind === "pause") {
+    return value.seq === undefined || isOptionalSeq(value.seq);
+  }
+  if (typeof value.fadeMs !== "number" || !Number.isFinite(value.fadeMs)) {
+    return false;
+  }
+  const fadeMs = value.fadeMs;
+  if (value.kind === "stop") {
+    return value.seq === undefined || isOptionalSeq(value.seq);
+  }
+  if (value.kind !== "play") return false;
+  return (
+    typeof value.resource === "string" &&
+    value.resource !== "" &&
+    typeof value.volume === "number" &&
+    Number.isFinite(value.volume) &&
+    typeof value.loop === "boolean" &&
+    fadeMs >= 0 &&
+    (value.autoStop === undefined || typeof value.autoStop === "boolean") &&
+    (value.restart === undefined || typeof value.restart === "boolean") &&
+    (value.seq === undefined || isOptionalSeq(value.seq))
+  );
+}
+
+function isOptionalSeq(value: unknown): boolean {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** 是否是合形态的单个实例状态：通道已知 + 播放状态合形态 */
+export function isAudioInstanceState(
+  value: unknown,
+): value is AudioInstanceState {
+  if (!isPlainObject(value)) return false;
+  return isAudioChannel(value.channel) && isChannelState(value.state);
+}
+
+/**
+ * 是否是合形态的实例表：普通对象 + 键合 id + 值合形态 + 条数不超上限。
+ *
+ * **上限在这里判**而不是在写入 op 里判：读入与写入都走同一个判据，
+ * 存档里被人改成 100 个实例时也能在装载阶段挡下来。
+ */
+export function isAudioInstanceTable(
+  value: unknown,
+): value is AudioInstanceTable {
+  if (!isPlainObject(value)) return false;
+  const ids = Object.keys(value);
+  if (ids.length > MAX_AUDIO_INSTANCES) return false;
+  for (const id of ids) {
+    if (!isAudioInstanceId(id)) return false;
+    if (!isAudioInstanceState(value[id])) return false;
+  }
+  return true;
+}
+
+/**
+ * 取实例表的 id 清单（字典序）：不合形态的表按空表处理。
+ *
+ * 渲染层按 id 排序后下发才能保证「同一份状态 → 同一串播放动作」，
+ * 否则对象键序会让同一存档在两台机器上叠出不同顺序的音轨。
+ */
+export function audioInstanceIds(value: unknown): readonly string[] {
+  return isAudioInstanceTable(value) ? Object.keys(value).sort() : [];
+}