@sublang/playbook 12.2.2 → 13.0.0

package/reference/sdlc/code.playbook/code.fsm.js

@@ -77,6 +77,18 @@ function playbookMeta(stateId, role) {
         },
     };
 }
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so a caller learns that from the machine
+// rather than from CODE's output fields.
+function terminalMeta(stateId, terminal) {
+    return {
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            terminal,
+        },
+    };
+}
 function isRecord(value) {
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {
         return false;
@@ -206,6 +218,16 @@ function nestedResultFromError(error) {
     const result = error.result;
     return isRecord(result) ? result : undefined;
 }
+function isFailureTerminalRecord(value) {
+    if (!isRecord(value))
+        return false;
+    const allowed = new Set(['stateId', 'kind', 'description']);
+    return (Reflect.ownKeys(value).every((key) => typeof key === 'string' && allowed.has(key)) &&
+        isNonEmptyString(value.stateId) &&
+        value.kind === 'failure' &&
+        (!Object.prototype.hasOwnProperty.call(value, 'description') ||
+            typeof value.description === 'string'));
+}
 function normalizedReviewFailure(error) {
     const result = nestedResultFromError(error);
     if (result === undefined)
@@ -215,10 +237,12 @@ function normalizedReviewFailure(error) {
         'playbookId',
         'childSessionId',
         'state',
-        'error',
+        ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
     ]);
     if (Reflect.ownKeys(result).some((key) => typeof key !== 'string' || !allowed.has(key)) ||
-        (result.status !== 'aborted' && result.status !== 'error') ||
+        (result.status !== 'aborted' &&
+            result.status !== 'error' &&
+            result.status !== 'ok') ||
         result.playbookId !== 'review') {
         return undefined;
     }
@@ -230,6 +254,19 @@ function normalizedReviewFailure(error) {
         !isPlaybookState(result.state)) {
         return undefined;
     }
+    if (result.status === 'ok') {
+        if (!Object.prototype.hasOwnProperty.call(result, 'terminal') ||
+            !isFailureTerminalRecord(result.terminal) ||
+            !isNonEmptyString(result.childSessionId)) {
+            return undefined;
+        }
+        return {
+            status: 'ok',
+            ...(result.output === undefined
+                ? {}
+                : { output: result.output }),
+        };
+    }
     let normalizedError;
     if (Object.prototype.hasOwnProperty.call(result, 'error')) {
         if (!isRecord(result.error))
@@ -274,8 +311,9 @@ function compactError(value) {
 function authoredReviewError(event) {
     const outer = isRecord(event) ? event.error : undefined;
     const failure = normalizedReviewFailure(outer);
-    if (failure?.error !== undefined)
+    if (failure !== undefined && failure.status !== 'ok' && failure.error) {
         return failure.error;
+    }
     if (failure?.status === 'aborted') {
         return { name: 'AbortError', message: 'REVIEW was aborted.' };
     }
@@ -787,13 +825,13 @@ export const codingMachine = machineSetup.createMachine({
         reportedReviewFailure: {
             id: 'reportedReviewFailure',
             description: STATE_DESCRIPTIONS.reportedReviewFailure,
-            meta: playbookMeta('reportedReviewFailure'),
+            meta: terminalMeta('reportedReviewFailure', 'failure'),
             type: 'final',
         },
         done: {
             id: 'done',
             description: STATE_DESCRIPTIONS.done,
-            meta: playbookMeta('done'),
+            meta: terminalMeta('done', 'success'),
             type: 'final',
         },
     },

package/reference/sdlc/code.playbook/code.fsm.ts

@@ -241,6 +241,22 @@ function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
   };
 }
 
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so a caller learns that from the machine
+// rather than from CODE's output fields.
+function terminalMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
+  stateId: StateId,
+  terminal: 'success' | 'failure',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      terminal,
+    },
+  };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return false;
@@ -419,10 +435,32 @@ function nestedResultFromError(error: unknown): Record<string, unknown> | undefi
   return isRecord(result) ? result : undefined;
 }
 
-type AuthoredReviewFailure = {
-  readonly status: 'aborted' | 'error';
-  readonly error?: CompactError;
-};
+type AuthoredReviewFailure =
+  | {
+      readonly status: 'aborted' | 'error';
+      readonly error?: CompactError;
+    }
+  // DR-048: a child that completed at an authored failure terminal. The
+  // bridge rejects it through the same error path, so CODE recognizes the
+  // failure from REVIEW's own machine and never from its output fields.
+  | {
+      readonly status: 'ok';
+      readonly output?: JsonValue;
+    };
+
+function isFailureTerminalRecord(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const allowed = new Set(['stateId', 'kind', 'description']);
+  return (
+    Reflect.ownKeys(value).every(
+      (key) => typeof key === 'string' && allowed.has(key),
+    ) &&
+    isNonEmptyString(value.stateId) &&
+    value.kind === 'failure' &&
+    (!Object.prototype.hasOwnProperty.call(value, 'description') ||
+      typeof value.description === 'string')
+  );
+}
 
 function normalizedReviewFailure(
   error: unknown,
@@ -434,13 +472,15 @@ function normalizedReviewFailure(
     'playbookId',
     'childSessionId',
     'state',
-    'error',
+    ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
   ]);
   if (
     Reflect.ownKeys(result).some(
       (key) => typeof key !== 'string' || !allowed.has(key),
     ) ||
-    (result.status !== 'aborted' && result.status !== 'error') ||
+    (result.status !== 'aborted' &&
+      result.status !== 'error' &&
+      result.status !== 'ok') ||
     result.playbookId !== 'review'
   ) {
     return undefined;
@@ -457,6 +497,21 @@ function normalizedReviewFailure(
   ) {
     return undefined;
   }
+  if (result.status === 'ok') {
+    if (
+      !Object.prototype.hasOwnProperty.call(result, 'terminal') ||
+      !isFailureTerminalRecord(result.terminal) ||
+      !isNonEmptyString(result.childSessionId)
+    ) {
+      return undefined;
+    }
+    return {
+      status: 'ok',
+      ...(result.output === undefined
+        ? {}
+        : { output: result.output as JsonValue }),
+    };
+  }
   let normalizedError: CompactError | undefined;
   if (Object.prototype.hasOwnProperty.call(result, 'error')) {
     if (!isRecord(result.error)) return undefined;
@@ -507,7 +562,9 @@ function compactError(value: unknown): CompactError {
 function authoredReviewError(event: unknown): CompactError {
   const outer = isRecord(event) ? event.error : undefined;
   const failure = normalizedReviewFailure(outer);
-  if (failure?.error !== undefined) return failure.error;
+  if (failure !== undefined && failure.status !== 'ok' && failure.error) {
+    return failure.error;
+  }
   if (failure?.status === 'aborted') {
     return { name: 'AbortError', message: 'REVIEW was aborted.' };
   }
@@ -1052,13 +1109,13 @@ export const codingMachine = machineSetup.createMachine({
     reportedReviewFailure: {
       id: 'reportedReviewFailure',
       description: STATE_DESCRIPTIONS.reportedReviewFailure,
-      meta: playbookMeta('reportedReviewFailure'),
+      meta: terminalMeta('reportedReviewFailure', 'failure'),
       type: 'final',
     },
     done: {
       id: 'done',
       description: STATE_DESCRIPTIONS.done,
-      meta: playbookMeta('done'),
+      meta: terminalMeta('done', 'success'),
       type: 'final',
     },
   },

package/reference/sdlc/code.playbook/playbook-captain.d.ts

@@ -35,6 +35,11 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
 type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, 'model' | 'effort' | 'fastMode'>>;
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 export interface PlaybookCaptainDeps {
+    continuity?: {
+        beforeCall(participantId: string): Promise<void>;
+        acknowledged(participantId: string, token: string): void;
+        reset(participantId: string, reason: 'missing_hint' | 'rejected_hint'): Promise<void>;
+    };
     loadModule?: (specifier: string) => Promise<unknown>;
     createSessionId?: () => string;
     hostCapabilities?: Readonly<Record<string, PlaybookHostConstructionCapabilities>>;

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -60,8 +60,21 @@ const SHELL_FSM_TOPIC = 'playbook.captain.fsm.state';
 const INTERNAL_CAPTAIN_ID = 'captain';
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PLAYER_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
-const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const ROLE_ID_WHITESPACE_OR_CONTROL = /[\s\p{Cc}]/u;
 const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
+// PBCLI-4: a local role id is its source role name lowercased by Unicode case
+// mapping — nonempty, free of whitespace and control characters, and equal to
+// its own lowercase form. The rule restricts neither script nor alphabet, so
+// `coder`, `编码者`, and `作者` are canonical while `Coder` is not. Callers
+// enforce the reserved `captain` name separately. The CLI host owns the same
+// predicate in `bin/session-store.js`; that private module already imports
+// this one, so the text is repeated here rather than cycled back.
+function isCanonicalLocalRoleId(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value === value.toLowerCase() &&
+        !ROLE_ID_WHITESPACE_OR_CONTROL.test(value));
+}
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
 // The fixed machine-syntax guard of a player's Boss-question suspension
@@ -685,9 +698,7 @@ function isValidRegistryEntry(value, artifactSchema) {
         return false;
     const e = value;
     if (!Array.isArray(e.requiredRoleIds) ||
-        e.requiredRoleIds.some((role) => typeof role !== 'string' ||
-            !ROLE_ID_PATTERN.test(role) ||
-            role === INTERNAL_CAPTAIN_ID) ||
+        e.requiredRoleIds.some((role) => !isCanonicalLocalRoleId(role) || role === INTERNAL_CAPTAIN_ID) ||
         new Set(e.requiredRoleIds).size !== e.requiredRoleIds.length ||
         !Array.isArray(e.concurrentRoleSets)) {
         return false;
@@ -911,7 +922,7 @@ function snapshotPlayerSessions(value, path) {
 function snapshotFrameRoleBindings(value, path) {
     const bindings = snapshotRecord(value, path);
     return Object.fromEntries(Object.entries(bindings).map(([roleId, raw]) => {
-        if (!ROLE_ID_PATTERN.test(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
+        if (!isCanonicalLocalRoleId(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
             throw new TypeError(`${path} has invalid role id ${JSON.stringify(roleId)}`);
         }
         const playerId = snapshotString(raw, `${path}.${roleId}`);
@@ -938,6 +949,7 @@ function normalizeHostPlayerResult(value, expectedPlayerId) {
         'resumeToken',
         'finalText',
         'error',
+        'errorCode',
     ]);
     const normalized = {};
     for (const key of Reflect.ownKeys(descriptors)) {
@@ -959,11 +971,16 @@ function normalizeHostPlayerResult(value, expectedPlayerId) {
             normalized[key] = descriptor.value;
     }
     const record = snapshotRecord(snapshotJsonValue(normalized, path), path);
-    rejectSnapshotKeys(record, ['status', 'playerId', 'turnId', 'resumeToken', 'finalText', 'error'], path);
+    rejectSnapshotKeys(record, ['status', 'playerId', 'turnId', 'resumeToken', 'finalText', 'error', 'errorCode'], path);
     if (record.playerId !== expectedPlayerId) {
         throw new TypeError(`${path}.playerId does not match the requested player`);
     }
     snapshotInteger(record.turnId, `${path}.turnId`, 1);
+    if (record.errorCode !== undefined &&
+        (record.errorCode !== 'SESSION_RESUME_REJECTED' ||
+            record.status !== 'error' || record.resumeToken !== undefined)) {
+        throw new TypeError(`${path}.errorCode is not a definite resume rejection`);
+    }
     return validatePlayerResult({
         status: record.status,
         ...(record.resumeToken === undefined
@@ -1618,6 +1635,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const createSessionId = deps.createSessionId ?? randomUUID;
     const createCaptainRuntime = deps.createCaptainRuntime ?? createDefaultCaptainRuntime;
     const unresolvedEffectSettlement = deps.unresolvedEffectSettlement;
+    const continuity = deps.continuity;
     let pendingHostCapabilities = deps.hostCapabilities;
     let currentEffectLedger = () => emptyPlaybookEffectLedger();
     // The returned shell must not retain the caller's aggregate dependency
@@ -2604,11 +2622,32 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             try {
                 let rawResult;
                 try {
-                    rawResult = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, prompt, {
-                        resume: options.resume,
-                        settings,
-                    })));
-                    hostResolved = true;
+                    const call = async (resume) => {
+                        await continuity?.beforeCall(binding.playerId);
+                        signal.throwIfAborted();
+                        const raw = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, prompt, { resume, settings })));
+                        hostResolved = true;
+                        return raw;
+                    };
+                    if (options.resume === false) {
+                        await continuity?.reset(binding.playerId, 'missing_hint');
+                    }
+                    rawResult = await call(options.resume);
+                    normalizeHostPlayerResult(rawResult, binding.playerId);
+                    if (typeof options.resume === 'string' && options.resume.length > 0 &&
+                        Object.getOwnPropertyDescriptor(rawResult, 'errorCode')?.value ===
+                            'SESSION_RESUME_REJECTED') {
+                        if (playerTransactions.get(binding.playerId) !== calling ||
+                            calling.abandoned || signal.aborted || activeTurn !== admittedTurn ||
+                            frame.playerCallScope !== scope || !frames.includes(frame)) {
+                            signal.throwIfAborted();
+                            throw new Error(`${frameLabel(frame)} player rejection arrived after its runtime operation ended`);
+                        }
+                        delete ledger.resumeToken;
+                        await continuity?.reset(binding.playerId, 'rejected_hint');
+                        hostResolved = false;
+                        rawResult = await call(false);
+                    }
                 }
                 catch (error) {
                     if (error instanceof AgentSettingsPreflightError) {
@@ -2903,6 +2942,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     delete ledger.resumeToken;
                 else
                     ledger.resumeToken = resumeToken;
+                if (pending.status === 'ok' && resumeToken !== undefined) {
+                    continuity?.acknowledged(binding.playerId, resumeToken);
+                }
             }
             finally {
                 playerTransactions.delete(binding.playerId);
@@ -3305,6 +3347,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 childSessionId: frame.sessionId,
                 state: result.state,
                 ...(result.output !== undefined ? { output: result.output } : {}),
+                // DR-048: the child runtime read this record from its own artifact;
+                // the host relays it unchanged so the caller's bridge can route a
+                // failure terminal without knowing the callee's output fields.
+                ...(result.terminal !== undefined
+                    ? { terminal: result.terminal }
+                    : {}),
             };
         }
         if (result.outcome === 'aborted') {
@@ -4092,7 +4140,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     };
     class CaptainContinuityError extends Error {
         constructor(cause) {
-            super('the session Captain conversation could not be resynchronized after one reseeded re-issue', { cause });
+            super('the session Captain conversation lost continuity', { cause });
             this.name = 'CaptainContinuityError';
         }
     }
@@ -4104,6 +4152,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     }
     const rawDurableCall = async (context, prompt, resume, attempt) => {
         const queued = captainQueue.add(async () => {
+            context.signal.throwIfAborted();
+            await continuity?.beforeCall('captain');
             context.signal.throwIfAborted();
             attempt.providerBoundaryEntered = true;
             const result = await classifySettingsCall(() => context.callCaptain(prompt, {
@@ -4117,11 +4167,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         });
         return trackTurnCall(queued);
     };
-    // CAPTAIN-35: unsynchronized when the call throws, returns non-`ok`, or
-    // returns `ok` without a token. Exactly one re-issue on a fresh conversation
-    // seeded with the reseed digest plus the current ControlView digest. A
-    // conversation that is owed a reseed carries the digest on its very next
-    // call, so the turn after a failed reseed starts seeded rather than blank.
+    // Only proven pre-execution rejection permits an immediate fresh call.
+    // Other continuity loss leaves the journal reseed for the next Boss turn.
     const durableCall = async (context, compose) => {
         const startingConversation = conversation;
         const resume = startingConversation.kind === 'pinned'
@@ -4136,6 +4183,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         let result;
         let failure;
         try {
+            if (resume === false)
+                await continuity?.reset('captain', 'missing_hint');
             result = await rawDurableCall(context, compose(seedFirstCall
                 ? { reseedDigest: reseedDigest() }
                 : startingConversation.kind === 'needsCatchUp'
@@ -4170,9 +4219,10 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         const unsynchronized = failure !== undefined ||
             result === undefined ||
             result.status !== 'ok' ||
-            result.resumeToken === undefined;
+            typeof result.resumeToken !== 'string' || result.resumeToken.trim().length === 0;
         if (!unsynchronized) {
             conversation = { kind: 'pinned', token: result.resumeToken };
+            continuity?.acknowledged('captain', result.resumeToken);
             if (activeTurn) {
                 activeTurn.captainSyncedJournalSeq = representedJournalSeq;
             }
@@ -4188,6 +4238,11 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         // stays `needsSeeding` until a call comes back with a token, so a reseed
         // that itself fails leaves the obligation standing for the next turn.
         conversation = { kind: 'needsSeeding' };
+        if (typeof resume !== 'string' || resume.length === 0 ||
+            result?.status !== 'error' || result.errorCode !== 'SESSION_RESUME_REJECTED') {
+            throw markControlFailure(new CaptainContinuityError(failure ?? result?.error ?? 'callCaptain did not establish continuation'));
+        }
+        await continuity?.reset('captain', 'rejected_hint');
         const recap = reseedDigest();
         let reissued;
         const reissueAttempt = { providerBoundaryEntered: false };
@@ -4204,11 +4259,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             }
             throw markControlFailure(new CaptainContinuityError(error));
         }
-        if (reissued.status !== 'ok' || reissued.resumeToken === undefined) {
+        if (reissued.status !== 'ok' || typeof reissued.resumeToken !== 'string' || reissued.resumeToken.trim().length === 0) {
             throw markControlFailure(new CaptainContinuityError(reissued.error ??
                 `callCaptain status "${reissued.status}" without a resume token`));
         }
         conversation = { kind: 'pinned', token: reissued.resumeToken };
+        continuity?.acknowledged('captain', reissued.resumeToken);
         if (activeTurn)
             activeTurn.captainSyncedJournalSeq = journalSeq;
         return {