@sublang/playbook 12.3.0 → 13.0.0

package/reference/sdlc/code.playbook/session-store.js

@@ -21,14 +21,17 @@ export function openSessionStore(sessionsDir) {
 }
 
 function wrapStore(store) {
+  let preparation;
+  const prepared = async (operation) => {
+    await (preparation ??= store.prepare());
+    return operation();
+  };
   return Object.freeze({
     sessionsDir: store.sessionsDir,
-    list: async () => projectListResult(await store.listSummaries()),
-    read: async (sessionId) =>
-      projectSummary(await store.readSummary(sessionId)),
-    readStream: async (sessionId, options) =>
-      projectReadResult(await store.readStream(sessionId, options)),
-    acquire: async (sessionId) => wrapLease(await store.acquire(sessionId)),
+    list: () => prepared(async () => projectListResult(await store.listSummaries())),
+    read: (sessionId) => prepared(async () => projectSummary(await store.readSummary(sessionId))),
+    readStream: (sessionId, options) => prepared(async () => projectReadResult(await store.readStream(sessionId, options))),
+    acquire: (sessionId) => prepared(async () => wrapLease(await store.acquire(sessionId))),
   });
 }
 
@@ -111,3 +114,16 @@ function projectStatus(status) {
     incomplete: status.incomplete,
   });
 }
+
+export {
+  createCaptainSessionStore as createSessionStore,
+  projectCaptainSessionStructure,
+  validateCaptainSessionExecutionProjection,
+  validateCaptainSessionStructuralProjection,
+  assertCaptainSessionExecutionCompatible,
+} from './bin/session-store.js';
+export {
+  validateSessionManifest,
+  validateSessionContext,
+  attachSessionHints,
+} from './bin/portable-codec.js';

package/src/xstate-playbook-runtime.js

@@ -2847,7 +2847,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             };
         }
         function detachedPlayerContinuation(roleId, playerId) {
-            return snapshotJsonValue(selectPlayerResume(roleId, playerId), `${label} deferred player continuation`);
+            return snapshotJsonValue({ v: 1, playerId: playerId ?? roleId }, `${label} deferred player continuation`);
         }
         function completionEvidenceFor(input, roleId, playerId, signal, operationId) {
             return async (completion) => {
@@ -4979,6 +4979,15 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 throw new Error(`${label} deferred continuation requires repository.runDeferred`);
             }
             const effectBoundary = continuationBoundarySeed(operation, turnId);
+            const boundPlayerId = resolvedPlayerId(effectBoundary.roleId);
+            const validateBinding = (value) => {
+                if (!isPlainObject(value) || Object.keys(value).length !== 2 ||
+                    value.v !== 1 ||
+                    value.playerId !== (boundPlayerId ?? effectBoundary.roleId)) {
+                    throw new TypeError(`${label} bound deferred player continuation is invalid`);
+                }
+            };
+            validateBinding(operation.playerContinuation);
             const continuation = {
                 operationId: operation.operationId,
                 effectBoundary,
@@ -5004,18 +5013,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     operationId: operation.operationId,
                     effectBoundary,
                     operation: async ({ playerContinuation }) => {
-                        const selectedContinuation = retainedEffectSourceSessionId === undefined
-                            ? playerContinuation
-                            : selectPlayerResume(effectBoundary.roleId, resolvedPlayerId(effectBoundary.roleId));
-                        if (selectedContinuation !== false &&
-                            (typeof selectedContinuation !== 'string' ||
-                                selectedContinuation.trim().length === 0)) {
-                            throw new TypeError(`${label} bound deferred player continuation is invalid`);
-                        }
-                        // Retained adoption owns a fresh Captain-session player ledger;
-                        // no source token becomes target ownership. Same-engagement
-                        // continuation still uses the exact durable binding.
-                        continuation.playerContinuation = selectedContinuation;
+                        validateBinding(playerContinuation);
+                        continuation.playerContinuation = selectPlayerResume(effectBoundary.roleId, boundPlayerId);
                         continuationStarted = true;
                         actor.send(event);
                         // The host has durably started this boundary and the FSM has

package/src/xstate-playbook-runtime.ts

@@ -4523,7 +4523,7 @@ export function createXStatePlaybookRuntime<
       playerId: string | undefined,
     ): JsonValue {
       return snapshotJsonValue(
-        selectPlayerResume(roleId, playerId),
+        { v: 1, playerId: playerId ?? roleId },
         `${label} deferred player continuation`,
       );
     }
@@ -7324,6 +7324,15 @@ export function createXStatePlaybookRuntime<
         );
       }
       const effectBoundary = continuationBoundarySeed(operation, turnId);
+      const boundPlayerId = resolvedPlayerId(effectBoundary.roleId);
+      const validateBinding = (value: unknown): void => {
+        if (!isPlainObject(value) || Object.keys(value).length !== 2 ||
+            value.v !== 1 ||
+            value.playerId !== (boundPlayerId ?? effectBoundary.roleId)) {
+          throw new TypeError(`${label} bound deferred player continuation is invalid`);
+        }
+      };
+      validateBinding(operation.playerContinuation);
       const continuation: NonNullable<typeof activeDeferredContinuation> = {
         operationId: operation.operationId,
         effectBoundary,
@@ -7349,26 +7358,10 @@ export function createXStatePlaybookRuntime<
           operationId: operation.operationId,
           effectBoundary,
           operation: async ({ playerContinuation }) => {
-            const selectedContinuation =
-              retainedEffectSourceSessionId === undefined
-                ? playerContinuation
-                : selectPlayerResume(
-                    effectBoundary.roleId,
-                    resolvedPlayerId(effectBoundary.roleId),
-                  );
-            if (
-              selectedContinuation !== false &&
-              (typeof selectedContinuation !== 'string' ||
-                selectedContinuation.trim().length === 0)
-            ) {
-              throw new TypeError(
-                `${label} bound deferred player continuation is invalid`,
-              );
-            }
-            // Retained adoption owns a fresh Captain-session player ledger;
-            // no source token becomes target ownership. Same-engagement
-            // continuation still uses the exact durable binding.
-            continuation.playerContinuation = selectedContinuation;
+            validateBinding(playerContinuation);
+            continuation.playerContinuation = selectPlayerResume(
+              effectBoundary.roleId, boundPlayerId,
+            );
             continuationStarted = true;
             actor!.send(event);
             // The host has durably started this boundary and the FSM has