@sparkelf/dsh-patch-session-envelope-ignorable 0.2.0-rc.44

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 patches/npm/session-envelope-ignorable/README.md
+README.md: 6eb808d895e9acdd2b2cd06a21add3518412ad7a
+README.zh.md: abf5983079e08aff14e0c636b6cbc547af3f5b4a

package/README.md

@@ -0,0 +1,11 @@
+# @sparkelf/dsh-patch-session-envelope-ignorable
+
+English | [中文](README.zh.md)
+
+This data-only package lets a log-only event declare the session envelope's `ignorable` marker at `Session.append`.
+
+The envelope has carried `ignorable` since the released session format, and the persistence read path enforces it: an event whose type the reader does not know is refused unless the event is marked ignorable, because skipping an unrecognized required event could reconstruct a wrong session. The marker had no writer. `Session.append` builds the envelope from `type`, `seq`, `time`, `data`, and the surface metadata, so an out-of-repo plugin appending its own event type could only produce records that every reader without that plugin refuses — including the reader that wrote them, once the plugin is unmounted.
+
+The patch adds an `EnvelopeIntent` to `packages/core/session/src/types.ts` and widens `append`'s rest parameter to accept it for non-surface events. The event construction copies `ignorable: true` onto the envelope only when the caller passes exactly `true`, matching the field's own contract: absence means required, and an explicit falsy value would be indistinguishable from a producer that meant the opposite.
+
+The deployment carries three sessions written by `@sparkelf/dsh-image-hoist` before this patch: `session-08bf0cc7-b831-4834-a30f-9153854503fe`, `session-160644ce-0546-4a75-8482-3848a0f2ebc7`, and `session-7dad49d6-1745-4158-b578-8fddf54cb45f`. Their `image/hoist` records are repaired in place by moving the marker to the envelope. This package is the writer-side change, moved from a mirror stash into a reviewed patch so a rebuild cannot drop it.

package/README.zh.md

@@ -0,0 +1,11 @@
+# @sparkelf/dsh-patch-session-envelope-ignorable
+
+[English](README.md) | 中文
+
+这个 data-only 包让「只写日志」的事件可以在 `Session.append` 时声明会话信封的 `ignorable` 标记。
+
+信封从已发布的会话格式起就带 `ignorable`，持久化读取路径也强制它：读取器不认识的类型会被拒绝，除非该事件标了 ignorable —— 因为静默跳过一条不可忽略的事件会重建出错误的会话。**但没有任何写入者能设置它。** `Session.append` 用 `type`、`seq`、`time`、`data` 和 surface 元数据构造信封，所以外部插件追加自己的事件类型时，只能产出「所有没挂载该插件的读取器都拒绝」的记录 —— 包括卸载插件后它自己。
+
+补丁在 `packages/core/session/src/types.ts` 增加 `EnvelopeIntent`，并把 `append` 的剩余参数放宽为非 surface 事件可接受它。事件构造只在调用方传入恰好 `true` 时把 `ignorable: true` 复制到信封上，与该字段自身的契约一致：缺省即必需，显式的假值与「本意相反的生产者」无法区分。
+
+部署里有三个由 `@sparkelf/dsh-image-hoist` 在本补丁之前写入的会话：`session-08bf0cc7-b831-4834-a30f-9153854503fe`、`session-160644ce-0546-4a75-8482-3848a0f2ebc7`、`session-7dad49d6-1745-4158-b578-8fddf54cb45f`。它们的 `image/hoist` 记录已就地修复，把标记移到信封上。本包是写入侧改动：从镜像暂存区搬进受审查的补丁，重建不会再丢掉它。

package/package.json

@@ -0,0 +1,35 @@
+{
+  "description": "Data-only exact official-source patch letting a log-only event declare the session envelope's ignorable marker at append",
+  "dshPatch": {
+    "formatVersion": 1,
+    "variants": [
+      {
+        "dsh": ">=0.2.0-rc.2",
+        "file": "./patches/session-envelope-ignorable.patch",
+        "id": "session-envelope-ignorable-at-append",
+        "target": {
+          "baseRevision": "639ed015397290b3745d163aafe02ffee4aa3f84",
+          "kind": "dsh-source",
+          "paths": [
+            "packages/core/session/src/"
+          ]
+        }
+      }
+    ]
+  },
+  "files": [
+    "patches/*.patch"
+  ],
+  "license": "MIT",
+  "name": "@sparkelf/dsh-patch-session-envelope-ignorable",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "patches/npm/session-envelope-ignorable",
+    "type": "git",
+    "url": "git+https://github.com/SparkElf/deepseek-harness-plus.git"
+  },
+  "type": "module",
+  "version": "0.2.0-rc.44"
+}

package/patches/session-envelope-ignorable.patch

@@ -0,0 +1,59 @@
+--- a/packages/core/session/src/types.ts
++++ b/packages/core/session/src/types.ts
+@@ -478,6 +478,18 @@
+ })
+ 
+ /**
++ * Envelope markers a log-only event may declare at {@link Session.append}.
++ *
++ * `ignorable` lets a reader that does not know the event type skip it instead of refusing the
++ * whole log. Only a producer whose record cannot affect reconstruction may set it, so it is
++ * opt-in per append rather than a property of the event type.
++ */
++export type EnvelopeIntent = {
++  /** Marks an event a reader may skip when it does not recognize the type. */
++  ignorable?: true
++}
++
++/**
+  * One immutable entry in the session log.
+  *
+  * A proper discriminated union over `type` (not independent `type`/`data`
+--- a/packages/core/session/src/index.ts
++++ b/packages/core/session/src/index.ts
+@@ -15,7 +15,8 @@
+ import type { Message } from '@deepseek-ai/dsh-llm'
+ import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from './types.ts'
+ import type { TypertLookup } from '@deepseek-ai/dsh-typert-protocol'
+-import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SessionSeedEventState, SurfaceIntent, SurfaceEventType } from './types.ts'
++import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SessionSeedEventState, EnvelopeIntent,
++  SurfaceIntent, SurfaceEventType } from './types.ts'
+ import { SurfaceManager, validateSessionEventData, validateSurfaceMetadata } from './surface.ts'
+ import type { SessionSurface, SessionMessageProjection } from './surface.ts'
+ import { foldRequestHeader } from './request-header.ts'
+@@ -722,9 +723,12 @@
+   append<T extends SessionEventType>(
+     type: T,
+     data: SessionEventMap[T],
+-    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : []
++    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : [opts?: EnvelopeIntent]
+   ): SessionEvent<T> {
+-    const surfaceOpts: SurfaceIntent | undefined = opts[0]
++    // A surface event's single option object is a `SurfaceIntent`; a log-only event's is an
++    // `EnvelopeIntent`. The two never share a field, so one object serves both.
++    const intent: SurfaceIntent & EnvelopeIntent = (opts[0] ?? {}) as SurfaceIntent & EnvelopeIntent
++    const surfaceOpts: SurfaceIntent | undefined = opts[0] as SurfaceIntent | undefined
+     const surfaceMetadata = {
+       ...surfaceOpts?.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: surfaceOpts.sourceEventSeqs },
+       ...surfaceOpts?.surfaceOp === undefined ? {} : { surfaceOp: surfaceOpts.surfaceOp },
+@@ -747,6 +751,10 @@
+       time: Date.now(),
+       data: dataSnapshot,
+       ...(surfaceMetadataSnapshot as { surfaceOp?: unknown; sourceEventSeqs?: unknown }),
++      // A log-only producer declares that a reader without its event type may skip the record.
++      // Only `true` is admitted: the field's absence means required, and an explicit falsy value
++      // would be indistinguishable from a producer that meant the opposite.
++      ...(intent.ignorable === true ? { ignorable: true } : {}),
+     } as unknown as SessionEvent<T>)
+     validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`)
+     this.surfaceManager.validateNext(event as SessionEvent)