@deepseek-ai/dsh-session-format-v3-to-v4 0.1.7-alpha.1

package/lib/types/codec.d.ts

@@ -0,0 +1,48 @@
+/** V4 framing with native tool-role admission and released physical rows. */
+import type { SessionFormatHeader, SessionFormatEvent } from '@deepseek-ai/dsh-session-format';
+/**
+ * V4 physical encoder and decoder retain the released row framing while
+ * validating the native tool-role message directly.
+ */
+export declare const releasedV4SessionFormatCodec: Readonly<{
+    version: number;
+    decodeHeader(value: unknown): {
+        version: number;
+        id: string;
+        createdAt: number;
+        cwd?: string;
+        parentSession?: string;
+        isSeeded: boolean;
+        origin?: "subagent";
+        delegationDepth: number;
+        agentPreset?: string;
+    };
+    createDecoder(value: unknown, recovery: import("@deepseek-ai/dsh-session-format").SessionFormatRecovery): {
+        header: {
+            version: number;
+            id: string;
+            createdAt: number;
+            cwd?: string;
+            parentSession?: string;
+            isSeeded: boolean;
+            origin?: "subagent";
+            delegationDepth: number;
+            agentPreset?: string;
+        };
+        decodeRow(row: unknown, context: import("@deepseek-ai/dsh-session-format").SessionFormatMigrationContext): void;
+        headerInheritedEventCount?: number;
+        finish(context: import("@deepseek-ai/dsh-session-format").SessionFormatMigrationContext): number;
+    };
+    encodeHeader(header: SessionFormatHeader, inheritedEventCount: number): {
+        version: number;
+    };
+    encodeEvent(event: SessionFormatEvent): import("@deepseek-ai/dsh-session-format").SessionFormatJsonObject;
+}>;
+/**
+ * Apply native V4 admission before a scanner discards a recoverable suffix.
+ * Ignorable developer payloads require reader vocabulary; physical decoding defers them.
+ * @param row - parsed physical row before framing and source-event range decoding.
+ * @param knownEventTypes - installed event types, supplied by native readers before tail recovery.
+ */
+export declare function assertV4RowAdmission(row: unknown, knownEventTypes?: ReadonlySet<string>): void;
+//# sourceMappingURL=codec.d.ts.map

package/lib/types/content.d.ts

@@ -0,0 +1,17 @@
+/** V3 content tags and request-tool fields admitted before V4 interpretation. */
+import type { SessionFormatEvent, SessionFormatJsonValue } from '@deepseek-ai/dsh-session-format';
+/**
+ * Convert declared content tags while keeping arguments and extension data opaque.
+ * @param value - released content array.
+ * @param subject - owning event and content location for diagnostics.
+ * @returns content in the same order, sharing unchanged blocks and image references.
+ */
+export declare function migrateV3Content(value: SessionFormatJsonValue | undefined, subject: string): SessionFormatJsonValue[];
+/**
+ * Convert declared V3 extension content and stream tags after canonical result lifting.
+ * @param event - source event after producer attribution conversion.
+ * @returns the event with namespaced content tags, retaining all coordinates and other fields.
+ * @throws {SessionFormatUnsupportedMigrationError} A V3 tool definition contains the V4-only deferLoading field.
+ */
+export declare function migrateV3EventContent(event: SessionFormatEvent): SessionFormatEvent;
+//# sourceMappingURL=content.d.ts.map

package/lib/types/developer.d.ts

@@ -0,0 +1,10 @@
+/** Native V4 developer-message and deferred-tool-schema validation. */
+import type { SessionFormatEvent } from '@deepseek-ai/dsh-session-format';
+/**
+ * Validate native V4 developer messages, tool-change blocks, and deferred tool schemas.
+ * Additional developer JSON fields are preserved. Malformed legacy message
+ * slots remain available to recoverable decoding.
+ * @param event - logical event or physical row before source-event range decoding.
+ */
+export declare function assertV4DeveloperData(event: SessionFormatEvent): void;
+//# sourceMappingURL=developer.d.ts.map

package/lib/types/extension-identities.d.ts

@@ -0,0 +1,11 @@
+/** Fixed V3 event vocabulary and namespaced historical opaque events. */
+import type { SessionFormatEvent } from '@deepseek-ai/dsh-session-format';
+/** First-party event names understood by the released V3 reader, independent of the installed writer. */
+export declare const RELEASED_V3_EVENT_TYPES: ReadonlySet<string>;
+/**
+ * Keep unknown ignorable events opaque after header promotion.
+ * @param event - original V3 event; this incoming identity conversion is applied once.
+ * @returns the same event or an ignorable namespaced event retaining its payload and coordinates.
+ */
+export declare function namespaceV3OpaqueEvent(event: SessionFormatEvent): SessionFormatEvent;
+//# sourceMappingURL=extension-identities.d.ts.map

package/lib/types/facts.d.ts

@@ -0,0 +1,35 @@
+/** Historical child identity reduced to the fields required by a parent's catalog. */
+import type { SessionFormatArtifact, SessionFormatJsonObject, SessionFormatJsonValue } from '@deepseek-ai/dsh-session-format';
+/**
+ * Collect a child's own descriptor without requiring one before its parent catalog is read.
+ * @param artifact - validated historical child artifact with its exact inherited cut.
+ * @returns compact child identity and descriptor evidence with validated discovery fields for catalog completion.
+ * @throws SessionFormatError when a supported own descriptor has invalid discovery fields.
+ */
+export declare function historicalChildCatalogSource(artifact: SessionFormatArtifact): SessionFormatJsonObject;
+/**
+ * Validate supplemental child evidence supplied across the migration JSON interface.
+ * @param value - collected child identity and optional descriptor.
+ * @returns validated evidence; descriptor interpretation is deferred until parent membership is known.
+ */
+export declare function childCatalogSource(value: SessionFormatJsonValue): SessionFormatJsonObject;
+/**
+ * Interpret only the discovery fields of known historical descriptors.
+ * @param source - validated child evidence.
+ * @returns a catalog fact, or undefined without exactly one supported own descriptor.
+ */
+export declare function childCatalogFact(source: SessionFormatJsonObject): SessionFormatJsonObject | undefined;
+/**
+ * Validate the historical fields used for catalog membership without interpreting extensions.
+ * @param value - catalog payload or prepared historical discovery fact.
+ * @param subject - event type or child identity used in rejection diagnostics.
+ * @returns validated catalog payload.
+ */
+export declare function catalogFact(value: SessionFormatJsonValue, subject?: string): SessionFormatJsonObject;
+/**
+ * Name the child and its optional storage-owned location in a migration diagnostic.
+ * @param source - validated supplemental child evidence.
+ * @returns a child identity with its source path when persistence supplied one.
+ */
+export declare function childCatalogSubject(source: SessionFormatJsonObject): string;
+//# sourceMappingURL=facts.d.ts.map

package/lib/types/fork-result.d.ts

@@ -0,0 +1,8 @@
+/** Native V4 fork-result identity and not-started error validation. */
+/**
+ * Validate fork-generated not-started results without changing their identity or text.
+ * Append results carry their own sequence; replacement results retain an earlier identity.
+ * @param row - logical event or physical event row.
+ */
+export declare function assertV4ForkResult(row: unknown): void;
+//# sourceMappingURL=fork-result.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+/** Tool-role V3-to-V4 migration with native V4 framing and delivery validation. */
+export { releasedV3SessionFormatCodec } from '@deepseek-ai/dsh-session-format-v2-to-v3';
+export * from './codec.ts';
+export * from './migration.ts';
+export { assertReleasedV4Header, assertReleasedV4Relationships, restoreReleasedV4Artifact } from './validation.ts';
+export { historicalChildCatalogSource } from './facts.ts';
+export { RELEASED_V3_EVENT_TYPES } from './extension-identities.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/message-sources.d.ts

@@ -0,0 +1,13 @@
+/** Native source admission preserves unknown attribution and refuses retired plugin wrappers. */
+import type { SessionFormatEvent } from '@deepseek-ai/dsh-session-format';
+/**
+ * Validate producer attribution in every declared durable message slot.
+ * @param event - complete native V4 event before Session adoption.
+ */
+export declare function assertV4MessageSources(event: SessionFormatEvent): void;
+/**
+ * Refuse retired source syntax even after a malformed recoverable row; leave incomplete messages to decoding.
+ * @param row - parsed row whose incomplete values have not been classified by the scanner.
+ */
+export declare function assertV4SourceRowAdmission(row: unknown): void;
+//# sourceMappingURL=message-sources.d.ts.map

package/lib/types/migration.d.ts

@@ -0,0 +1,11 @@
+/** Append historical child facts after converting V3 source events to V4. */
+import type { SessionFormatJsonValue, SessionFormatMigration } from '@deepseek-ai/dsh-session-format';
+/** Header-only migration declaration; body restoration requires explicit child evidence. */
+export declare const sessionFormatV3ToV4: SessionFormatMigration;
+/**
+ * Bind one parent's historical child evidence to its V3→V4 migration.
+ * @param children - complete child evidence retained unchanged for the lifetime of this declaration; an empty array declares no children.
+ * @returns an adjacent migration that creates independent stages with the supplied evidence.
+ */
+export declare function createSessionFormatV3ToV4(children: readonly SessionFormatJsonValue[]): SessionFormatMigration;
+//# sourceMappingURL=migration.d.ts.map

package/lib/types/references.d.ts

@@ -0,0 +1,11 @@
+/** Remap released V3 local event references after interrupted-turn insertion. */
+import type { SessionFormatEvent } from '@deepseek-ai/dsh-session-format';
+/**
+ * Remap first-party local references, retaining generation-qualified captures and numeric payloads.
+ * @param event - first-party source event before envelope renumbering.
+ * @param seq - target event position.
+ * @param mapping - target positions of all earlier source events.
+ * @returns the event with target coordinates; unchanged events retain their identity.
+ */
+export declare function remapV3References(event: SessionFormatEvent, seq: number, mapping: readonly number[]): SessionFormatEvent;
+//# sourceMappingURL=references.d.ts.map

package/lib/types/relationships.d.ts

@@ -0,0 +1,9 @@
+/** Mandatory native V4 relationships; incomplete tails retain their open transactions. */
+import type { SessionFormatArtifact } from '@deepseek-ai/dsh-session-format';
+/**
+ * Validate native V4 lifecycle and ownership facts without rewriting any event.
+ * @param artifact - artifact whose V4 envelopes and messages have been admitted.
+ * @param knownEventTypes - installed event types whose payloads this reader interprets.
+ */
+export declare function assertV4LifecycleRelationships(artifact: SessionFormatArtifact, knownEventTypes: ReadonlySet<string>): void;
+//# sourceMappingURL=relationships.d.ts.map

package/lib/types/retired-syntax.d.ts

@@ -0,0 +1,8 @@
+/** Retired native syntax remains a hard refusal even after a recoverable physical-row failure. */
+/**
+ * Refuse retired headers, PTC tags, and tool-result blocks in interpreted content slots.
+ * Tool arguments, replay state, schema parameters, and nested extension values remain opaque.
+ * @param row - parsed physical row or complete native logical event.
+ */
+export declare function assertV4RetiredSyntax(row: unknown): void;
+//# sourceMappingURL=retired-syntax.d.ts.map

package/lib/types/sources.d.ts

@@ -0,0 +1,26 @@
+/** Released V3 plugin-source conversion and declared message traversal. */
+import type { SessionFormatEvent, SessionFormatJsonObject, SessionFormatJsonValue } from '@deepseek-ai/dsh-session-format';
+/**
+ * Visit only messages carried by first-party event payloads.
+ * @param event - source or target logical event.
+ * @param transform - message transform preserving unchanged identity.
+ * @returns the event sharing all untouched payloads.
+ */
+export declare function mapEventMessages(event: SessionFormatEvent, transform: (message: SessionFormatJsonObject) => SessionFormatJsonObject): SessionFormatEvent;
+/**
+ * Lift one released V3 plugin source into the current producer-owned shape.
+ * @param source - source record whose `kind` is `'plugin'`.
+ * @param seq - event seq for diagnostics.
+ * @param role - carried message role for role-sensitive renames.
+ * @returns a copy whose kind is the producer's own kind and whose `plugin` field is dropped.
+ */
+export declare function rewritePluginSource(source: SessionFormatJsonObject, seq: number, role: SessionFormatJsonValue | undefined): SessionFormatJsonObject;
+/**
+ * Convert released plugin wrappers while retaining every direct source kind and its metadata.
+ * @param source - decoded V3 message source.
+ * @param seq - event sequence for diagnostics.
+ * @param role - enclosing message role for role-sensitive producer mappings.
+ * @returns the converted source with every non-identity field preserved.
+ */
+export declare function rewriteV3MessageSource(source: SessionFormatJsonObject, seq: number, role: SessionFormatJsonValue | undefined): SessionFormatJsonObject;
+//# sourceMappingURL=sources.d.ts.map

package/lib/types/system-message.d.ts

@@ -0,0 +1,7 @@
+/** Native system-message fields checked before physical recovery can discard a row. */
+/**
+ * Validate system fields independently of historical message representations; preserve additional JSON fields.
+ * @param row - complete logical event or parsed physical row before corruption recovery.
+ */
+export declare function assertV4SystemMessageFields(row: unknown): void;
+//# sourceMappingURL=system-message.d.ts.map

package/lib/types/testing/validation.d.ts

@@ -0,0 +1,7 @@
+import type { SessionFormatArtifact } from '@deepseek-ai/dsh-session-format';
+/**
+ * Validate an artifact through the native codec without vocabulary-aware restoration.
+ * @param artifact - current-generation artifact to encode and decode.
+ */
+export declare function assertReleasedV4Artifact(artifact: SessionFormatArtifact): void;
+//# sourceMappingURL=validation.d.ts.map

package/lib/types/tool-role.d.ts

@@ -0,0 +1,19 @@
+/** First-class tool-role messages in the V4 representation. */
+import type { SessionFormatEvent } from '@deepseek-ai/dsh-session-format';
+/**
+ * Lift one released-V3 wrapper tool/result row into the first-class V4 message.
+ * Validate the wrapper before dropping it so malformed historical content is
+ * rejected instead of being silently truncated.
+ * @param event - released wrapper tool/result event.
+ * @returns the same event with a first-class tool-role message.
+ * @throws {SessionFormatError} when the wrapper, tool source, content, or error flag is malformed.
+ * @throws {SessionFormatUnsupportedMigrationError} when the result contains another result.
+ */
+export declare function liftToolResult(event: SessionFormatEvent): SessionFormatEvent;
+/**
+ * Validate the native V4 first-class tool-role message of one tool/result row.
+ * @param event - canonical V4 event.
+ * @throws {SessionFormatError} when the row is not an exact first-class tool result.
+ */
+export declare function assertV4ToolResultMessage(event: SessionFormatEvent): void;
+//# sourceMappingURL=tool-role.d.ts.map

package/lib/types/validation.d.ts

@@ -0,0 +1,33 @@
+/** Native V4 metadata and generation-owned relationship validation. */
+import type { SessionFormatArtifact, SessionFormatEvent } from '@deepseek-ai/dsh-session-format';
+/**
+ * Validate the exact native V4 logical header.
+ * @param header - decoded or otherwise untrusted V4 Session header candidate.
+ */
+export declare function assertReleasedV4Header(header: unknown): void;
+/**
+ * Validate V4 inheritance, vocabulary, native message admission, and
+ * lifecycle, compaction, tool, retry, title, command, catalog, and delivery ownership.
+ * Installed Session restoration owns common event envelopes and message acceptance.
+ * @param artifact - complete detached V4 artifact.
+ * @param knownEventTypes - event types understood by the installed Session package.
+ * @returns the same validated artifact and event objects.
+ */
+export declare function restoreReleasedV4Artifact(artifact: SessionFormatArtifact, knownEventTypes: ReadonlySet<string>): SessionFormatArtifact;
+/**
+ * Validate delivery generation and active-generation coordinates before evaluating ownership.
+ * @param event - decoded event whose delivery payload may be inspected.
+ * @param currentVersion - generation whose watermark coordinates are active.
+ * @returns the active delivery's nonempty Session id, or undefined for other events and generations.
+ */
+export declare function validateDeliveryAccepted(event: SessionFormatEvent, currentVersion: 3 | 4): string | undefined;
+/**
+ * Validate native developer fields, message sources, lifecycle, catalog, and delivery
+ * relationships without changing event vocabulary or tail recovery.
+ * The owning admission stage rejects unknown required events;
+ * unknown ignorable records retain their uninterpreted payloads.
+ * @param artifact - decoded artifact with its final inherited cut.
+ * @param knownEventTypes - installed event types whose payloads this reader interprets.
+ */
+export declare function assertReleasedV4Relationships(artifact: SessionFormatArtifact, knownEventTypes: ReadonlySet<string>): void;
+//# sourceMappingURL=validation.d.ts.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-session-format-v3-to-v4",
+  "description": "Streaming tool-role migration and delivery validation from Session V3 to V4",
+  "version": "0.1.7-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-format-v3-to-v4"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "sessionFormatMigration": {
+      "from": 3,
+      "to": 4,
+      "export": ".",
+      "migration": "sessionFormatV3ToV4",
+      "sourceCodec": "releasedV3SessionFormatCodec",
+      "targetCodec": "releasedV4SessionFormatCodec",
+      "targetHeaderValidator": "assertReleasedV4Header",
+      "targetRestorer": "restoreReleasedV4Artifact"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-session-format": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-format-v2-to-v3": "^0.1.7-alpha.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.3"
+  }
+}