feat: add reusable session preparation

packages/core/session/src/preparation.ts

@@ -0,0 +1,49 @@
+/**
+ * Ownership of one unpublished Session before registry publication.
+ * @module @deepseek-ai/dsh-session/preparation
+ */
+
+import type { Session } from './index.ts'
+
+/** Options for a preparation whose provider retains unpublished state. */
+export interface SessionPreparationOptions {
+  /** Release provider-owned state when the Session was not published. */
+  readonly release?: () => void
+}
+
+/**
+ * One exact unpublished Session and the provider state that keeps it usable.
+ * Disposal is synchronous and idempotent. Providers decide whether release
+ * returns the Session to a cache or discards it; publication may consume that
+ * state before disposal, making the callback a no-op.
+ */
+export class SessionPreparation implements Disposable {
+  private released = false
+
+  /** The exact Session to use for setup and publication. */
+  readonly session: Session
+
+  private constructor(
+    session: Session,
+    private readonly options: SessionPreparationOptions,
+  ) {
+    this.session = session
+  }
+
+  /**
+   * Wrap an unpublished Session in one preparation lifetime.
+   * @param session - exact unpublished Session.
+   * @param options - optional provider release behavior.
+   * @returns a preparation disposed after publication or rollback.
+   */
+  static create(session: Session, options?: SessionPreparationOptions): SessionPreparation {
+    return new SessionPreparation(session, options ?? {})
+  }
+
+  /** Release provider state once when this preparation leaves its caller. */
+  [Symbol.dispose](): void {
+    if (this.released) return
+    this.released = true
+    this.options.release?.()
+  }
+}