@sema-agent/client-core 0.110.0 → 0.112.0

package/dist/hitl/planReviewWire.d.ts

@@ -41,6 +41,8 @@ export interface PlanReviewCardView {
     readonly note?: string;
 }
 export declare function planReviewCardViewOf(frame: object | null | undefined, lang?: UiLanguage): PlanReviewCardView | undefined;
+export type PlanReviewEvidenceMove = 'same' | 'moved' | 'unknown';
+export declare function planReviewEvidenceMovedOf(shown: object | null | undefined, latest: object | null | undefined): PlanReviewEvidenceMove;
 export declare function notePlanReviewAnsweredIfDecisive(questionId: unknown, answer: QuestionAnswer | null | undefined): void;
 export { isPlanReviewPark };
 export declare function _resetArmedPlanReviewsForTest(): void;
@@ -79,6 +81,7 @@ export interface PlanReviewOutcomeMeta {
     decision: 'approve' | 'reject' | 'ask_again';
     effect: PlanReviewDecisionEffect;
     cause?: 'stored_form_unsupported';
+    questionId?: string;
 }
 export declare function planReviewOutcomeTail(taskId: string, decision: 'approve' | 'reject', effect: PlanReviewDecisionEffect, cause?: 'stored_form_unsupported'): string;
 export type PlanReviewWireClient = {

package/dist/hitl/planReviewWire.js

@@ -150,6 +150,22 @@ export function planReviewCardViewOf(frame, lang) {
         return Object.freeze({ options: OPTIONS_BY_SHAPE.withheld, note: renderMessage(planReviewUnreadableNoteRef(), lang) });
     }
 }
+export function planReviewEvidenceMovedOf(shown, latest) {
+    try {
+        const a = planReviewCardFactsFrom(shown);
+        const b = planReviewCardFactsFrom(latest);
+        if (a === undefined || b === undefined || a.taskId !== b.taskId)
+            return 'unknown';
+        if (a.checkpointId !== undefined && b.checkpointId !== undefined && a.checkpointId !== b.checkpointId)
+            return 'moved';
+        if (a.evidenceRevision === undefined || b.evidenceRevision === undefined)
+            return 'unknown';
+        return a.evidenceRevision === b.evidenceRevision ? 'same' : 'moved';
+    }
+    catch {
+        return 'unknown';
+    }
+}
 export function notePlanReviewAnsweredIfDecisive(questionId, answer) {
     notePlanReviewAnsweredIfDecisiveFor(DEFAULT_SESSION_KEY, questionId, answer);
 }
@@ -524,7 +540,7 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             const cardDelivery = cardReason !== undefined ? { ...delivery, reason: cardReason } : delivery;
             notePlanReviewAnswered(questionId);
             hostLog('debug', `planReviewWire: arm responder delivering ${decided} for task ${taskId} (path=arm)`);
-            void decidePlanReviewFor(taskId, decided, modeAfter, cardDelivery, facts);
+            void decidePlanReviewFor(taskId, decided, modeAfter, cardDelivery, facts, questionId);
             return { ok: true };
         };
         unregister = registerLocalQuestionResponder(questionId, responder, onWithdraw);
@@ -725,7 +741,7 @@ function askAgainReasonOf(card, opts) {
         return renderMessage(msg('approval.planReview.askAgain.unknown'), DATA_FACE_LANGUAGE);
     }
 }
-async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, card) {
+async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, card, cardId) {
     if (typeof taskId === 'string' && planReviewOpsOf(taskId).some((op) => op.phase === 'posting')) {
         hostLog('error', `planReviewWire: decidePlanReview(${decision}) for task ${taskId} REFUSED — a decision for this task is already in flight (duplicate delivery latched)`);
         return;
@@ -758,7 +774,7 @@ async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts,
     try {
         const wireDecision = decision === 'ask_again' ? 'reject' : decision;
         const wireOpts = decision === 'ask_again' ? { ...opts, reason: askAgainReasonOf(card, opts) } : opts;
-        await decidePlanReviewInner(taskId, wireDecision, permissionModeAfter, dispatchNo, releaseLatch, settle, wireOpts, card, decision);
+        await decidePlanReviewInner(taskId, wireDecision, permissionModeAfter, dispatchNo, releaseLatch, settle, wireOpts, card, decision, cardId);
     }
     finally {
         releaseLatch();
@@ -779,7 +795,7 @@ function planReviewClientsFor(resolved) {
         repull: () => resolved.make({ timeoutMs: 15_000 }),
     };
 }
-async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, card, semanticDecision) {
+async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, card, semanticDecision, cardId) {
     let outcome;
     let decisionReason;
     const gateBefore = card?.checkpointId;
@@ -1019,7 +1035,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
     const onOutcome = opts?.onOutcome;
     settle(effect === 'not_sent' || effect === 'still_parked');
     try {
-        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision: semanticDecision, effect, ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}) });
+        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision: semanticDecision, effect, ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}), ...(cardId !== undefined ? { questionId: cardId } : {}) });
         if (!delivered) {
             if (onOutcome !== undefined) {
                 hostLog('debug', `planReviewWire: outcome queue port not installed for task ${taskId} — outcome handed to the host's onOutcome callback only`);
@@ -1039,6 +1055,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
             decision: semanticDecision,
             effect,
             ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}),
+            ...(cardId !== undefined ? { questionId: cardId } : {}),
             detail: outcome,
             tail,
             prompt,
@@ -1160,7 +1177,7 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs, taken) {
         ((tid, decision, reason, card) => {
             hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
             const withReason = reason === undefined ? delivery : { ...delivery, reason };
-            void decidePlanReviewFor(tid, decision, undefined, withReason, card);
+            void decidePlanReviewFor(tid, decision, undefined, withReason, card, questionId);
         });
     const activeKey = `${sessionKey}\u0000${canonicalId}`;
     let unregister = () => { };

package/dist/hitl/policyDenyCause.d.ts

@@ -1,3 +1,3 @@
-export declare const POLICY_DENY_CAUSES: readonly ["no_approval_ui", "dont_ask", "deny_rule", "engine_floor"];
+export declare const POLICY_DENY_CAUSES: readonly ["no_approval_ui", "dont_ask", "deny_rule", "engine_floor", "hook"];
 export type PolicyDenyCause = (typeof POLICY_DENY_CAUSES)[number];
 export declare function readPolicyDenyCause(decision: object | null | undefined): PolicyDenyCause | undefined;

package/dist/hitl/policyDenyCause.js

@@ -1,4 +1,4 @@
-export const POLICY_DENY_CAUSES = Object.freeze(['no_approval_ui', 'dont_ask', 'deny_rule', 'engine_floor']);
+export const POLICY_DENY_CAUSES = Object.freeze(['no_approval_ui', 'dont_ask', 'deny_rule', 'engine_floor', 'hook']);
 export function readPolicyDenyCause(decision) {
     if (decision === null || typeof decision !== 'object')
         return undefined;

package/dist/hitl/resumeRunningCard.d.ts

@@ -21,6 +21,7 @@ export declare function runningAttachOffered(canAttach: boolean | undefined): bo
 export declare function resumeRunningOptions(i: ResumeRunningCardInput): ResumeRunningCardOption[];
 export declare function resumeChoiceFromLabels(selected: readonly string[] | null | undefined): ResumeRunningChoice;
 export declare const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
+export declare const ENGINE_UNAVAILABLE_EXIT_CODE = 69;
 export declare const RESUME_RUNNING_GUIDANCE_TAG = "sema: resume-running:";
 export declare function resumeRunningNoUiGuidance(i: {
     taskId: string;

package/dist/hitl/resumeRunningCard.js

@@ -50,6 +50,7 @@ export function resumeChoiceFromLabels(selected) {
     return 'background';
 }
 export const RESUME_RUNNING_NO_UI_EXIT_CODE = 75;
+export const ENGINE_UNAVAILABLE_EXIT_CODE = 69;
 export const RESUME_RUNNING_GUIDANCE_TAG = 'sema: resume-running:';
 export function resumeRunningNoUiGuidance(i) {
     const sid = typeof i.sessionId === 'string' && i.sessionId.length > 0 ? i.sessionId : null;

package/dist/hitl/screenCardCarriers.d.ts

@@ -0,0 +1,15 @@
+export declare const PARK_GATE_KEY = "_sema_parkGate";
+export declare function sourceGenerationNow(deps: {
+    readonly engineGeneration?: () => number;
+} | null | undefined): number | undefined;
+export declare function parkQuestionFrameBits(taskId: string, gatedCallId: string | undefined, sourceGeneration: number | undefined): {
+    readonly _sema_parkGate?: {
+        readonly taskId: string;
+        readonly gatedCallId: string;
+    };
+    readonly _sema_sourceGeneration?: number;
+};
+export declare function sourceGenerationBit(sourceGeneration: number | undefined): {
+    readonly sourceGeneration?: number;
+};
+export declare function questionFrameSourceGenerationOf(frame: object | null | undefined): number | undefined;

package/dist/hitl/screenCardCarriers.js

@@ -0,0 +1,41 @@
+import { slotReadOf } from '../wireFailureShape.js';
+import { engineGenerationReadingOf } from '../engineGenerationPort.js';
+export const PARK_GATE_KEY = '_sema_parkGate';
+const SOURCE_GENERATION_KEY = '_sema_sourceGeneration';
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+export function sourceGenerationNow(deps) {
+    try {
+        if (typeof deps !== 'object' || deps === null)
+            return undefined;
+        const read = deps.engineGeneration;
+        if (typeof read !== 'function')
+            return undefined;
+        const r = engineGenerationReadingOf(() => read.call(deps));
+        return r.known ? r.generation : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parkQuestionFrameBits(taskId, gatedCallId, sourceGeneration) {
+    return {
+        ...(nonEmpty(taskId) && nonEmpty(gatedCallId) ? { _sema_parkGate: Object.freeze({ taskId, gatedCallId }) } : {}),
+        ...(finite(sourceGeneration) ? { _sema_sourceGeneration: sourceGeneration } : {}),
+    };
+}
+export function sourceGenerationBit(sourceGeneration) {
+    return finite(sourceGeneration) ? { sourceGeneration } : {};
+}
+export function questionFrameSourceGenerationOf(frame) {
+    try {
+        if (typeof frame !== 'object' || frame === null)
+            return undefined;
+        const r = slotReadOf(frame, SOURCE_GENERATION_KEY);
+        const v = r.presence === 'present' ? r.value : undefined;
+        return finite(v) ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/screenDecisionCards.d.ts

@@ -0,0 +1,98 @@
+import { type ScreenCardOrigin } from './gateIdentity.js';
+import { type EndedGenerationOpenedCall, type EndedGenerationPhaseChange, type EndedGenerationPhaseHold } from '../engineGenerationConvergence.js';
+import type { HostWithdrawal } from './hostWithdrawal.js';
+export type ScreenCardGate = {
+    readonly kind: 'tool';
+    readonly taskId: string;
+    readonly gatedCallId: string;
+} | {
+    readonly kind: 'plan';
+    readonly taskId: string;
+    readonly checkpointId?: string;
+};
+export interface ScreenCardWindow {
+    readonly leftMs?: number;
+    readonly closedByEngine?: boolean;
+}
+export interface ScreenDecisionCard {
+    readonly instance: string;
+    readonly origin?: ScreenCardOrigin;
+    readonly gate?: ScreenCardGate;
+    readonly sourceGeneration?: number;
+    readonly toolCallId?: string;
+    readonly window?: ScreenCardWindow;
+}
+export declare const SCREEN_CARD_KEEP_REASONS: readonly ["not-ready", "generation-moved", "not-withdrawable", "no-gate", "not-early", "no-row", "not-owned", "verdict-ok", "verdict-absent"];
+export type ScreenCardKeepReason = (typeof SCREEN_CARD_KEEP_REASONS)[number];
+export interface EngineGenerationEndedCardFacts {
+    readonly phase: 'ended';
+    readonly endedGeneration: number;
+    readonly cards: readonly ScreenDecisionCard[];
+    readonly opened: readonly EndedGenerationOpenedCall[];
+    readonly phases?: readonly EndedGenerationPhaseHold[];
+}
+export interface EngineGenerationReadyCardFacts<R extends object> {
+    readonly phase: 'ready';
+    readonly generation: number;
+    readonly ready: boolean;
+    readonly readGeneration: number;
+    readonly cards: readonly ScreenDecisionCard[];
+    readonly rows: readonly R[];
+    readonly isOwned: (row: R) => boolean;
+    readonly withdrawable: readonly ScreenCardOrigin[];
+}
+export interface EngineGenerationEndedCardPlan {
+    readonly phase: 'ended';
+    readonly retract: readonly string[];
+    readonly phases: readonly EndedGenerationPhaseChange[];
+}
+export interface ScreenCardWithdrawal<R extends object> {
+    readonly instance: string;
+    readonly origin: ScreenCardOrigin;
+    readonly row: R;
+    readonly withdrawal: HostWithdrawal;
+}
+export interface ScreenCardKeep {
+    readonly instance: string;
+    readonly why: ScreenCardKeepReason;
+}
+export interface EngineGenerationReadyCardPlan<R extends object> {
+    readonly phase: 'ready';
+    readonly withdraw: readonly ScreenCardWithdrawal<R>[];
+    readonly keep: readonly ScreenCardKeep[];
+}
+export interface EngineGenerationCardRecheckDueFacts {
+    readonly generation: number;
+    readonly ready: boolean;
+    readonly cards: readonly ScreenDecisionCard[];
+    readonly withdrawable: readonly ScreenCardOrigin[];
+}
+export declare function questionFrameGateOf(frame: object | null | undefined): ScreenCardGate | undefined;
+export declare function approvalCardGateOf(card: object | null | undefined): ScreenCardGate | undefined;
+export declare function approvalCardOriginOf(card: object | null | undefined): 'live-approval' | 'park-approval';
+export declare function screenCardsHoldEngineDecision(cards: readonly {
+    readonly origin?: ScreenCardOrigin;
+}[] | null | undefined): boolean;
+export declare function engineGenerationCardPlan(facts: EngineGenerationEndedCardFacts): EngineGenerationEndedCardPlan;
+export declare function engineGenerationCardPlan<R extends object>(facts: EngineGenerationReadyCardFacts<R>): EngineGenerationReadyCardPlan<R>;
+export declare function engineGenerationCardRecheckDue(facts: EngineGenerationCardRecheckDueFacts): boolean;
+export interface ScreenCardGoldenRow {
+    readonly taskId?: string;
+    readonly toolCallId?: string;
+    readonly boundCallId?: string;
+    readonly checkpointId?: string;
+    readonly rowVerdict?: ScreenCardGoldenRowVerdict;
+    readonly owned: boolean;
+}
+export interface ScreenCardGoldenRowVerdict {
+    readonly kind: string;
+    readonly code?: string;
+    readonly reason?: string;
+    readonly sentence?: string;
+}
+export interface EngineGenerationCardPlanGoldenCase {
+    readonly name: string;
+    readonly facts: EngineGenerationEndedCardFacts | Omit<EngineGenerationReadyCardFacts<ScreenCardGoldenRow>, 'isOwned'>;
+    readonly plan: EngineGenerationEndedCardPlan | EngineGenerationReadyCardPlan<ScreenCardGoldenRow>;
+}
+export declare const ENGINE_GENERATION_CARD_PLAN_GOLDEN: readonly EngineGenerationCardPlanGoldenCase[];

package/dist/hitl/screenDecisionCards.js

@@ -0,0 +1,363 @@
+import { SCREEN_CARD_ORIGINS } from './gateIdentity.js';
+import { convergeEndedEngineGeneration, } from '../engineGenerationConvergence.js';
+import { checkpointRowVerdictOf } from '../checkpointRowVerdict.js';
+import { CHECKPOINT_INVALID_OUTCOME, CHECKPOINT_UNSUPPORTED_VERSION } from '../engineErrorCodes.js';
+import { planReviewCardFactsFrom } from '../planReviewCardFacts.js';
+import { slotReadOf } from '../wireFailureShape.js';
+import { PARK_GATE_KEY } from './screenCardCarriers.js';
+import { pendingRowAnswersCall } from './hitlBridge.js';
+import { cardIsOnParkRow } from './toolApprovalWire.js';
+export const SCREEN_CARD_KEEP_REASONS = Object.freeze(['not-ready', 'generation-moved', 'not-withdrawable', 'no-gate', 'not-early', 'no-row', 'not-owned', 'verdict-ok', 'verdict-absent']);
+const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+const ORIGIN_SET = new Set(SCREEN_CARD_ORIGINS);
+const PACKAGE_WITHDRAWABLE = new Set(['park-approval', 'park-question', 'plan-review', 'host-reopen-question']);
+const NOT_ENGINE_DECISION = new Set(['host-choice', 'local-permission']);
+function own(o, key) {
+    const r = slotReadOf(o, key);
+    return r.presence === 'present' ? r.value : undefined;
+}
+function originOf(v) {
+    return typeof v === 'string' && ORIGIN_SET.has(v) ? v : undefined;
+}
+function toolGateOf(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    const taskId = own(v, 'taskId');
+    const gatedCallId = own(v, 'gatedCallId');
+    return nonEmpty(taskId) && nonEmpty(gatedCallId) ? Object.freeze({ kind: 'tool', taskId, gatedCallId }) : undefined;
+}
+export function questionFrameGateOf(frame) {
+    try {
+        if (typeof frame !== 'object' || frame === null)
+            return undefined;
+        const park = slotReadOf(frame, PARK_GATE_KEY);
+        const plan = slotReadOf(frame, '_sema_planReview');
+        if (park.presence === 'unreadable' || plan.presence === 'unreadable')
+            return undefined;
+        const hasPark = park.presence === 'present' && park.value !== undefined;
+        const hasPlan = plan.presence === 'present' && plan.value !== undefined;
+        if (hasPark && hasPlan)
+            return undefined;
+        if (hasPark)
+            return toolGateOf(park.value);
+        if (!hasPlan)
+            return undefined;
+        const facts = planReviewCardFactsFrom(plan.value);
+        if (facts === undefined)
+            return undefined;
+        return Object.freeze({ kind: 'plan', taskId: facts.taskId, ...(facts.checkpointId !== undefined ? { checkpointId: facts.checkpointId } : {}) });
+    }
+    catch {
+        return undefined;
+    }
+}
+export function approvalCardGateOf(card) {
+    try {
+        if (typeof card !== 'object' || card === null || !cardIsOnParkRow(card))
+            return undefined;
+        const taskId = own(card, 'taskId');
+        const park = own(card, 'parkRow');
+        if (!nonEmpty(taskId) || typeof park !== 'object' || park === null)
+            return undefined;
+        const gatedCallId = own(park, 'gatedCallId');
+        return nonEmpty(gatedCallId) ? Object.freeze({ kind: 'tool', taskId, gatedCallId }) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function approvalCardOriginOf(card) {
+    try {
+        return cardIsOnParkRow(card) ? 'park-approval' : 'live-approval';
+    }
+    catch {
+        return 'live-approval';
+    }
+}
+export function screenCardsHoldEngineDecision(cards) {
+    return engineDecisionReadingOf(cards) !== 'none';
+}
+function engineDecisionReadingOf(cards) {
+    try {
+        if (!Array.isArray(cards))
+            return 'none';
+        const len = own(cards, 'length');
+        if (typeof len !== 'number' || !Number.isSafeInteger(len) || len < 0)
+            return 'unreadable';
+        for (let i = 0; i < len; i++) {
+            const card = own(cards, String(i));
+            const origin = typeof card === 'object' && card !== null ? originOf(own(card, 'origin')) : undefined;
+            if (origin === undefined || !NOT_ENGINE_DECISION.has(origin))
+                return 'holds';
+        }
+        return 'none';
+    }
+    catch {
+        return 'unreadable';
+    }
+}
+function cardReadingOf(card) {
+    try {
+        if (typeof card !== 'object' || card === null)
+            return undefined;
+        const instance = own(card, 'instance');
+        if (!nonEmpty(instance))
+            return undefined;
+        return {
+            instance,
+            origin: originOf(own(card, 'origin')),
+            gate: own(card, 'gate'),
+            sourceGeneration: own(card, 'sourceGeneration'),
+            toolCallId: own(card, 'toolCallId'),
+            window: own(card, 'window'),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function distinctCards(cards) {
+    if (!Array.isArray(cards))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const card of cards) {
+        const r = cardReadingOf(card);
+        if (r === undefined || seen.has(r.instance))
+            continue;
+        seen.add(r.instance);
+        out.push(r);
+    }
+    return out;
+}
+function usableGateOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    const kind = own(v, 'kind');
+    const taskId = own(v, 'taskId');
+    if (!nonEmpty(taskId))
+        return undefined;
+    if (kind === 'tool') {
+        const gatedCallId = own(v, 'gatedCallId');
+        return nonEmpty(gatedCallId) ? { kind: 'tool', taskId, gatedCallId } : undefined;
+    }
+    if (kind === 'plan') {
+        const checkpointId = own(v, 'checkpointId');
+        return nonEmpty(checkpointId) ? { kind: 'plan', taskId, checkpointId } : undefined;
+    }
+    return undefined;
+}
+function withdrawableSetOf(v) {
+    const out = new Set();
+    if (!Array.isArray(v))
+        return out;
+    for (const o of v) {
+        const origin = originOf(o);
+        if (origin !== undefined && PACKAGE_WITHDRAWABLE.has(origin))
+            out.add(origin);
+    }
+    return out;
+}
+function candidacyOf(card, generation, cap) {
+    if (card.origin === undefined || !cap.has(card.origin))
+        return { ok: false, why: 'not-withdrawable' };
+    const gate = usableGateOf(card.gate);
+    if (gate === undefined)
+        return { ok: false, why: 'no-gate' };
+    if (finite(card.sourceGeneration) && card.sourceGeneration >= generation)
+        return { ok: false, why: 'not-early' };
+    return { ok: true, origin: card.origin, gate };
+}
+function rowAnswersGate(row, gate) {
+    const r = row;
+    if (gate.kind === 'tool')
+        return pendingRowAnswersCall(r, gate.taskId, gate.gatedCallId);
+    return r.taskId === gate.taskId && r.checkpointId === gate.checkpointId;
+}
+function ownedSafely(isOwned, row) {
+    try {
+        return isOwned(row) === true;
+    }
+    catch {
+        return false;
+    }
+}
+const EMPTY_ENDED = Object.freeze({ phase: 'ended', retract: Object.freeze([]), phases: Object.freeze([]) });
+const EMPTY_READY = Object.freeze({ phase: 'ready', withdraw: Object.freeze([]), keep: Object.freeze([]) });
+function endedPlanOf(facts) {
+    const cards = distinctCards(own(facts, 'cards')).map((c) => {
+        const w = c.window;
+        const leftMs = typeof w === 'object' && w !== null ? own(w, 'leftMs') : undefined;
+        const closedByEngine = typeof w === 'object' && w !== null ? own(w, 'closedByEngine') : undefined;
+        return {
+            callKey: c.instance,
+            parkRow: c.origin !== 'live-approval',
+            ...(nonEmpty(c.toolCallId) ? { toolCallId: c.toolCallId } : {}),
+            ...(finite(leftMs) ? { windowLeftMs: leftMs } : {}),
+            ...(closedByEngine === true ? { closedByEngine: true } : {}),
+        };
+    });
+    const opened = own(facts, 'opened');
+    const phases = own(facts, 'phases');
+    const endedGeneration = own(facts, 'endedGeneration');
+    const plan = convergeEndedEngineGeneration({
+        cards,
+        opened: Array.isArray(opened) ? opened : [],
+        ...(Array.isArray(phases) ? { phases: phases } : {}),
+        endedGeneration: finite(endedGeneration) ? endedGeneration : Number.NaN,
+    });
+    return Object.freeze({ phase: 'ended', retract: plan.retract, phases: plan.phases });
+}
+function readyPlanOf(facts) {
+    const cards = distinctCards(own(facts, 'cards'));
+    const generation = own(facts, 'generation');
+    const keep = [];
+    const withdraw = [];
+    const keepAll = (why) => Object.freeze({ phase: 'ready', withdraw: Object.freeze([]), keep: Object.freeze(cards.map((c) => Object.freeze({ instance: c.instance, why }))) });
+    if (own(facts, 'ready') !== true || !finite(generation))
+        return keepAll('not-ready');
+    if (own(facts, 'readGeneration') !== generation)
+        return keepAll('generation-moved');
+    const cap = withdrawableSetOf(own(facts, 'withdrawable'));
+    const rowsRaw = own(facts, 'rows');
+    const rows = Array.isArray(rowsRaw) ? rowsRaw.filter((r) => typeof r === 'object' && r !== null) : [];
+    const isOwnedRaw = own(facts, 'isOwned');
+    const isOwned = typeof isOwnedRaw === 'function' ? isOwnedRaw : () => false;
+    for (const card of cards) {
+        const c = candidacyOf(card, generation, cap);
+        if (!c.ok) {
+            keep.push(Object.freeze({ instance: card.instance, why: c.why }));
+            continue;
+        }
+        const matched = rows.filter((r) => rowAnswersGate(r, c.gate));
+        if (matched.length === 0) {
+            keep.push(Object.freeze({ instance: card.instance, why: 'no-row' }));
+            continue;
+        }
+        const row = matched.find((r) => ownedSafely(isOwned, r));
+        if (row === undefined) {
+            keep.push(Object.freeze({ instance: card.instance, why: 'not-owned' }));
+            continue;
+        }
+        const verdict = checkpointRowVerdictOf(row);
+        if (verdict === undefined) {
+            keep.push(Object.freeze({ instance: card.instance, why: 'verdict-absent' }));
+            continue;
+        }
+        if (verdict.kind === 'ok') {
+            keep.push(Object.freeze({ instance: card.instance, why: 'verdict-ok' }));
+            continue;
+        }
+        const rowVerdict = verdict;
+        withdraw.push(Object.freeze({ instance: card.instance, origin: c.origin, row, withdrawal: Object.freeze({ toldBy: 'host', rowVerdict }) }));
+    }
+    return Object.freeze({ phase: 'ready', withdraw: Object.freeze(withdraw), keep: Object.freeze(keep) });
+}
+export function engineGenerationCardPlan(facts) {
+    let phase;
+    try {
+        if (typeof facts !== 'object' || facts === null)
+            return EMPTY_READY;
+        phase = own(facts, 'phase');
+        if (phase === 'ended')
+            return endedPlanOf(facts);
+        if (phase === 'ready')
+            return readyPlanOf(facts);
+        return EMPTY_READY;
+    }
+    catch {
+        return (phase === 'ended' ? EMPTY_ENDED : EMPTY_READY);
+    }
+}
+export function engineGenerationCardRecheckDue(facts) {
+    try {
+        if (typeof facts !== 'object' || facts === null)
+            return false;
+        const generation = own(facts, 'generation');
+        if (own(facts, 'ready') !== true || !finite(generation))
+            return false;
+        const cap = withdrawableSetOf(own(facts, 'withdrawable'));
+        return distinctCards(own(facts, 'cards')).some((c) => candidacyOf(c, generation, cap).ok);
+    }
+    catch {
+        return false;
+    }
+}
+function deepFreeze(v) {
+    if (typeof v === 'object' && v !== null && !Object.isFrozen(v)) {
+        Object.freeze(v);
+        for (const k of Object.keys(v))
+            deepFreeze(v[k]);
+    }
+    return v;
+}
+const GOLD_LACKING = { kind: 'lacking', code: CHECKPOINT_UNSUPPORTED_VERSION, reason: 'version_newer', sentence: 'Newer engine.' };
+const GOLD_DAMAGED = { kind: 'damaged', code: CHECKPOINT_INVALID_OUTCOME, reason: 'requirements_damaged', sentence: 'Row damaged.' };
+function goldenCases() {
+    const ALL = ['park-approval', 'park-question', 'plan-review', 'host-reopen-question'];
+    const ready = (name, cards, rows, pick, over = {}) => {
+        const facts = { phase: 'ready', generation: 2, ready: true, readGeneration: 2, cards, rows, withdrawable: ALL, ...over };
+        return { name, facts, plan: { phase: 'ready', ...pick(facts.rows) } };
+    };
+    const tool = (taskId, gatedCallId) => ({ kind: 'tool', taskId, gatedCallId });
+    const W = (instance, origin, row, rowVerdict) => ({ instance, origin, row, withdrawal: { toldBy: 'host', rowVerdict } });
+    const K = (instance, why) => ({ instance, why });
+    const lacking = GOLD_LACKING;
+    const damaged = GOLD_DAMAGED;
+    const cases = [
+        {
+            name: 'ended-live-window-open-only',
+            facts: {
+                phase: 'ended',
+                endedGeneration: 1,
+                cards: [
+                    { instance: 'live-open', origin: 'live-approval', toolCallId: 'call-1', window: { leftMs: 60_000 } },
+                    { instance: 'live-margin', origin: 'live-approval', toolCallId: 'call-2', window: { leftMs: 5_000 } },
+                    { instance: 'live-closed', origin: 'live-approval', toolCallId: 'call-3', window: { leftMs: 60_000, closedByEngine: true } },
+                    { instance: 'live-no-window', origin: 'live-approval', toolCallId: 'call-4' },
+                    { instance: 'parked', origin: 'park-approval', toolCallId: 'call-5', window: { leftMs: 60_000 } },
+                    { instance: 'no-origin', toolCallId: 'call-6', window: { leftMs: 60_000 } },
+                ],
+                opened: [{ toolCallId: 'call-7', generation: 1 }, { toolCallId: 'call-8', generation: 0 }],
+            },
+            plan: { phase: 'ended', retract: ['live-open'], phases: [{ toolCallId: 'call-1', phase: 'engine-stopped-awaiting-approval', viaCallKey: 'live-open' }, { toolCallId: 'call-7', phase: 'engine-stopped-before-result' }] },
+        },
+        {
+            name: 'ended-live-without-call-id',
+            facts: { phase: 'ended', endedGeneration: 3, cards: [{ instance: 'live', origin: 'live-approval', window: { leftMs: 9_000 } }], opened: [] },
+            plan: { phase: 'ended', retract: ['live'], phases: [] },
+        },
+        ready('ready-park-question-withdrawn', [{ instance: 'q', origin: 'park-question', gate: tool('run-1', 'call-1'), sourceGeneration: 1 }], [{ taskId: 'run-1', toolCallId: 'call-1', rowVerdict: GOLD_LACKING, owned: true }], (rows) => ({ withdraw: [W('q', 'park-question', rows[0], lacking)], keep: [] })),
+        ready('ready-bound-call-id-matches', [{ instance: 'a', origin: 'park-approval', gate: tool('run-2', 'call-2'), sourceGeneration: 1 }], [{ taskId: 'run-2', toolCallId: 'call-x', boundCallId: 'call-2', rowVerdict: GOLD_DAMAGED, owned: true }], (rows) => ({ withdraw: [W('a', 'park-approval', rows[0], damaged)], keep: [] })),
+        ready('ready-plan-by-checkpoint', [
+            { instance: 'plan-same', origin: 'plan-review', gate: { kind: 'plan', taskId: 'run-3', checkpointId: 'cp-1' } },
+            { instance: 'plan-moved', origin: 'plan-review', gate: { kind: 'plan', taskId: 'run-4', checkpointId: 'cp-old' }, sourceGeneration: 1 },
+            { instance: 'plan-no-checkpoint', origin: 'plan-review', gate: { kind: 'plan', taskId: 'run-5' }, sourceGeneration: 1 },
+        ], [{ taskId: 'run-3', checkpointId: 'cp-1', rowVerdict: GOLD_LACKING, owned: true }, { taskId: 'run-4', checkpointId: 'cp-new', rowVerdict: GOLD_LACKING, owned: true }, { taskId: 'run-5', checkpointId: 'cp-5', rowVerdict: GOLD_LACKING, owned: true }], (rows) => ({ withdraw: [W('plan-same', 'plan-review', rows[0], lacking)], keep: [K('plan-moved', 'no-row'), K('plan-no-checkpoint', 'no-gate')] })),
+        ready('ready-kinds-never-withdrawn', [
+            { instance: 'live', origin: 'live-approval', gate: tool('run-1', 'call-1'), sourceGeneration: 1 },
+            { instance: 'choice', origin: 'host-choice', gate: tool('run-1', 'call-1'), sourceGeneration: 1 },
+            { instance: 'unnamed', gate: tool('run-1', 'call-1'), sourceGeneration: 1 },
+            { instance: 'reopened', origin: 'host-reopen-question', gate: tool('run-1', 'call-1'), sourceGeneration: 1 },
+        ], [{ taskId: 'run-1', toolCallId: 'call-1', rowVerdict: GOLD_LACKING, owned: true }], (rows) => ({ withdraw: [W('reopened', 'host-reopen-question', rows[0], lacking)], keep: [K('live', 'not-withdrawable'), K('choice', 'not-withdrawable'), K('unnamed', 'not-withdrawable')] })),
+        ready('ready-host-withdrawable-only', [{ instance: 'q', origin: 'park-question', gate: tool('run-1', 'call-1'), sourceGeneration: 1 }, { instance: 'r', origin: 'host-reopen-question', gate: tool('run-1', 'call-1'), sourceGeneration: 1 }], [{ taskId: 'run-1', toolCallId: 'call-1', rowVerdict: GOLD_LACKING, owned: true }], (rows) => ({ withdraw: [W('r', 'host-reopen-question', rows[0], lacking)], keep: [K('q', 'not-withdrawable')] }), { withdrawable: ['host-reopen-question'] }),
+        ready('ready-current-generation-kept', [{ instance: 'q', origin: 'park-question', gate: tool('run-1', 'call-1'), sourceGeneration: 2 }], [{ taskId: 'run-1', toolCallId: 'call-1', rowVerdict: GOLD_LACKING, owned: true }], () => ({ withdraw: [], keep: [K('q', 'not-early')] })),
+        ready('ready-keep-reasons', [
+            { instance: 'no-gate', origin: 'park-question', sourceGeneration: 1 },
+            { instance: 'no-row', origin: 'park-question', gate: tool('run-9', 'call-9'), sourceGeneration: 1 },
+            { instance: 'foreign', origin: 'park-question', gate: tool('run-7', 'call-7'), sourceGeneration: 1 },
+            { instance: 'fine', origin: 'park-question', gate: tool('run-8', 'call-8'), sourceGeneration: 1 },
+            { instance: 'no-verdict', origin: 'park-question', gate: tool('run-6', 'call-6'), sourceGeneration: 1 },
+        ], [
+            { taskId: 'run-7', toolCallId: 'call-7', rowVerdict: GOLD_LACKING, owned: false },
+            { taskId: 'run-8', toolCallId: 'call-8', rowVerdict: { kind: 'ok' }, owned: true },
+            { taskId: 'run-6', toolCallId: 'call-6', owned: true },
+        ], () => ({ withdraw: [], keep: [K('no-gate', 'no-gate'), K('no-row', 'no-row'), K('foreign', 'not-owned'), K('fine', 'verdict-ok'), K('no-verdict', 'verdict-absent')] })),
+        ready('ready-not-ready', [{ instance: 'q', origin: 'park-question', gate: tool('run-1', 'call-1'), sourceGeneration: 1 }], [{ taskId: 'run-1', toolCallId: 'call-1', rowVerdict: GOLD_LACKING, owned: true }], () => ({ withdraw: [], keep: [K('q', 'not-ready')] }), { ready: false }),
+        ready('ready-generation-moved', [{ instance: 'q', origin: 'park-question', gate: tool('run-1', 'call-1'), sourceGeneration: 1 }], [{ taskId: 'run-1', toolCallId: 'call-1', rowVerdict: GOLD_LACKING, owned: true }], () => ({ withdraw: [], keep: [K('q', 'generation-moved')] }), { readGeneration: 1 }),
+        ready('ready-instance-judged-once', [{ instance: 'q', origin: 'park-question', gate: tool('run-8', 'call-8'), sourceGeneration: 1 }, { instance: 'q', origin: 'park-question', gate: tool('run-1', 'call-1'), sourceGeneration: 1 }], [{ taskId: 'run-1', toolCallId: 'call-1', rowVerdict: GOLD_LACKING, owned: true }, { taskId: 'run-8', toolCallId: 'call-8', rowVerdict: { kind: 'ok' }, owned: true }], () => ({ withdraw: [], keep: [K('q', 'verdict-ok')] })),
+    ];
+    return deepFreeze(cases);
+}
+export const ENGINE_GENERATION_CARD_PLAN_GOLDEN = goldenCases();