@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/orchestration-shell/gate-decision-submit.d.ts

@@ -0,0 +1,245 @@
+import type { OrchestrationStore } from './store';
+import type { ConversationEntry, PostDecisionAction } from './types';
+/**
+ * Minimal SDK contract for the `applyUserDecision` wire. Structurally
+ * compatible with the full `AppSyncClient.applyUserDecision` signature — keeps
+ * the orchestration shell decoupled from the heavier AppSync surface (tests can
+ * inject a stub). Mirrors `ApplyUserDecisionClient` in `<OrchestrationApp>`.
+ */
+export interface ApplyUserDecisionClient {
+    applyUserDecision(input: {
+        gateId: string;
+        taskId: string;
+        sessionId: string;
+        currentRound: number;
+        decision: string;
+        notes?: string;
+    }, sessionKeyBase64?: string): Promise<{
+        decision: string;
+        postAction: PostDecisionAction;
+    }>;
+}
+/** Dependencies common to both the TTY + non-TTY gate-resolution paths. */
+export interface GateDecisionSubmitDeps {
+    store: OrchestrationStore;
+    /** The desktop AppSync transport (or a stub in tests). */
+    appsyncClient: ApplyUserDecisionClient;
+    /** Just-in-time session-key resolver (only consulted when notes are present). */
+    getSessionKey: (sessionId: string) => Promise<string | null>;
+    /**
+     * Optional — notified after a successful `applyUserDecision` with the engine's
+     * `postAction` (the QuorumLoop wires it to discard the shadow on a
+     * non-authorize terminal AND flip the resolved track's team render-terminal).
+     * ABSENT → no-op.
+     *
+     * #607 RESIDUAL #2 — the FIRST arg is the `taskId` of the GATE being resolved
+     * (`entry.envelope.taskId`), NOT the loop's global `activeTask`. For a
+     * multi-track team the resolved gate is NOT necessarily the loop's active
+     * task, so `reportTeamTrackUserResolved` MUST key on the resolved gate's
+     * taskId or it flips the WRONG track / no-ops (the user-Approved track stays
+     * `InFlight`). The shell closure threads this through to the loop.
+     *
+     * `expectedShadow` is the shadow INSTANCE captured at decision time (see
+     * `captureShadow`) so the discard is instance-pinned: a RESTART reuses the same
+     * taskId and the engine emits a fresh round-0 GATE_DISPATCH that can replace the
+     * task's mapped shadow before this fires. Pinning to the captured instance stops
+     * the discard from destroying the restart's NEW shadow (live dogfood race
+     * 2026-06-11, option-4 "Reject and restart"). `undefined` when no shadow was
+     * mapped at decision time (or no loop is wired).
+     */
+    onTerminalDecision?: (taskId: string, postAction: PostDecisionAction, expectedShadow?: unknown) => void;
+    /**
+     * Optional — resolves the live shadow INSTANCE for a task at decision time. Read
+     * ONCE at the TOP of `submitGateDecision` (BEFORE the `applyUserDecision` SDK
+     * await) so the captured instance is the OLD (rejected) shadow, not whatever a
+     * racing restart dispatch may have swapped into the map by the time
+     * `onTerminalDecision` fires. The QuorumLoop binds this to `shadowForTask`.
+     * Returns an opaque handle threaded straight back into `onTerminalDecision`.
+     */
+    captureShadow?: (taskId: string) => unknown;
+    /**
+     * PHASE-589/469 W3.2 — the two-phase group-escalation decision deps. Present
+     * ONLY for a TEAM session (built in `cli.ts` alongside the team LE). When a
+     * resolved gate-prompt entry carries the `groupEscalation` marker (a desktop-
+     * synthesized team halt prompt, NOT an engine per-track gate),
+     * `routeGatePromptInput` routes its resolution through `submitGroupDecision`
+     * (CLAIM→revert→COMMIT) using these deps instead of the per-track
+     * `applyUserDecision`. ABSENT (single-impl / tests) → a group prompt can never
+     * appear, so this is never consulted.
+     */
+    groupDecision?: GroupDecisionSubmitDeps;
+}
+/** The active unfinalized gate-prompt conversation entry. */
+type GatePromptEntry = Extract<ConversationEntry, {
+    kind: 'gate-prompt';
+}>;
+/**
+ * §5.1 + #C8M-11 active-gate-prompt scan. Tail-to-head walk for the first
+ * `kind:'gate-prompt'` entry with `final === false`. Pure; safe to call from a
+ * render path. Returns the entry verbatim so callers can pattern-match the
+ * discriminated union directly. (Shared so the TTY component + non-TTY loop use
+ * the identical scan.)
+ */
+export declare function findActiveGatePromptEntry(conversation: ReadonlyArray<ConversationEntry>): GatePromptEntry | null;
+/**
+ * Submit a gate decision: dispatch SUBMIT_STARTED, fire the SDK, dispatch
+ * RESOLVED on success (and notify `onTerminalDecision`) or SUBMIT_FAILED on
+ * error. Verbatim port of the `<OrchestrationApp>` `submitDecision` useCallback
+ * so both surfaces share one implementation. NEVER throws (every failure becomes
+ * a SUBMIT_FAILED — or, for a terminal already-resolved error, a
+ * GATE_PROMPT_RESOLVED_EXTERNALLY — dispatch).
+ */
+export declare function submitGateDecision(deps: GateDecisionSubmitDeps, promptEntryId: string, payload: {
+    gateId: string;
+    taskId: string;
+    sessionId: string;
+    currentRound: number;
+    decision: string;
+    notes?: string;
+}): Promise<void>;
+/** The closed 5-option group-escalation decision labels (mirror gate-prompts). */
+export type GroupDecisionLabel = 'ACCEPT' | 'ACCEPT_WITH_NOTES' | 'REJECT_WITH_NOTES' | 'REJECT_RESTART' | 'ABORT_TASK';
+/** Minimal SDK contract for the two-phase `claimGroupDecision` wire. */
+export interface ClaimGroupDecisionClient {
+    claimGroupDecision(input: {
+        taskGroupId: string;
+        sessionId: string;
+        phase: 'claim' | 'commit';
+        decision: GroupDecisionLabel;
+        verdictIdempotencyKey: string;
+        claimToken?: string;
+        notes?: string;
+    }, sessionKeyBase64?: string): Promise<{
+        phase: 'claimed' | 'committed' | 'already_claimed' | 'already_committed';
+        decision: string;
+        claimToken: string;
+        groupStatus?: string;
+    }>;
+}
+/** The result the desktop surfaces after a group decision completes. */
+export interface GroupDecisionResult {
+    /** The terminal phase the engine recorded. */
+    phase: 'committed' | 'already_committed';
+    decision: GroupDecisionLabel;
+    /** Reject-family only — the revert outcome (clean-where-safe + surface). */
+    revert?: {
+        reverted: string[];
+        alreadyReverted: string[];
+        conflicts: string[];
+    };
+}
+/** Dependencies for the two-phase group-escalation decision. */
+export interface GroupDecisionSubmitDeps {
+    store: OrchestrationStore;
+    /** The two-phase group-decision transport (or a stub in tests). */
+    claimClient: ClaimGroupDecisionClient;
+    /** Session-key resolver (consulted only when notes are present). */
+    getSessionKey: (sessionId: string) => Promise<string | null>;
+    /**
+     * The reject-family workspace side-effect — revert the group's applied tracks
+     * (clean-where-safe + surface). The CLAIM→revert→COMMIT ordering pins the
+     * revert BETWEEN the CLAIM lock and the terminal COMMIT (LOCK #589-J): no
+     * terminal decision is recorded before the side-effect finishes. ABSENT (tests
+     * / accept-only) → no workspace effect.
+     */
+    revertGroup?: (taskGroupId: string) => Promise<{
+        reverted: string[];
+        alreadyReverted: string[];
+        conflicts: string[];
+    }>;
+    /**
+     * Mark the group's durable manifest ACCEPTED (the GC predicate flips). Called
+     * after an accept-family COMMIT. ABSENT → no-op (tests).
+     */
+    markAccepted?: (taskGroupId: string) => Promise<void>;
+    /**
+     * HIGH-1 / LOCK #589-J — persist the CLAIMED-but-not-COMMITted decision to the
+     * durable record, called IMMEDIATELY after the CLAIM phase mints `claimToken`
+     * and BEFORE the revert side-effect runs. This is the durable marker a startup
+     * reconcile uses to resume the revert + drive the COMMIT after a CLAIM-crash
+     * (the in-memory token is lost on crash; the persisted one is the recovery
+     * path). ABSENT → not persisted (tests that don't exercise crash recovery).
+     */
+    persistPendingDecision?: (taskGroupId: string, pending: {
+        decision: GroupDecisionLabel;
+        claimToken: string;
+        notes?: string;
+    }) => Promise<void>;
+    /**
+     * HIGH-1 — clear the persisted pending decision after the terminal COMMIT lands
+     * (so a later reconcile never re-drives it). ABSENT → no-op (tests).
+     */
+    clearPendingDecision?: (taskGroupId: string) => Promise<void>;
+    /**
+     * Drive the per-track render flip through the SAME `emitGroupConvergence`
+     * chokepoint (D2): accept-family → tracks stay/flip `Passed`; reject-family →
+     * tracks flip `Failed`/reverted + the group resolves. ABSENT → render-less
+     * (tests). This is what closes the "track stays InFlight after abort_task" gap.
+     */
+    driveGroupConvergence?: (taskGroupId: string, outcome: string) => Promise<void>;
+    /**
+     * REJECT_RESTART only — the desktop re-issues the WHOLE team from its OWN
+     * retained ORIGINAL `/team` launch spec (work-items + briefs; the engine retains
+     * nothing, §5 RISK 1 / RESIDUAL 1). The active orchestration `store` is passed in
+     * (this dep's heavy half is built in `cli.ts` BEFORE `runOrchestrationShell`
+     * creates the store, so the store is threaded at call time from THIS deps'
+     * `store`). ABSENT → the restart degrades to a plain terminal-reject (the user
+     * re-runs `/team`). A THROW surfaces the "re-run /team" advisory.
+     */
+    reissueTeam?: (taskGroupId: string, store: OrchestrationStore) => Promise<void>;
+}
+/**
+ * PHASE-589/469 W3.2 — resolve the group 5-option escalation via the two-phase
+ * CLAIM → (desktop side-effect) → COMMIT (LOCK #589-J). The desktop OWNS the
+ * workspace regardless of which surface initiated, so it runs the revert here.
+ *
+ * Ordering (closes the cross-surface race): (1) CLAIM atomically locks the gate;
+ * (2) for a reject-family decision RUN THE REVERT to completion-or-conflict-stop;
+ * (3) COMMIT (terminal). A competing mobile Accept mid-revert is rejected by the
+ * CLAIM lock. NEVER throws — every failure surfaces a `SHELL_ADVISORY` and
+ * returns; the in-flight group's manifest survives for startup reconcile.
+ */
+export declare function submitGroupDecision(deps: GroupDecisionSubmitDeps, args: {
+    taskGroupId: string;
+    sessionId: string;
+    decision: GroupDecisionLabel;
+    notes?: string;
+}): Promise<GroupDecisionResult | null>;
+/**
+ * Outcome of routing a typed line against an active gate prompt. `handled`
+ * distinguishes "the line was consumed by gate resolution" (a digit / notes /
+ * the cancel sentinel) from "the line is not for this gate" (so the caller falls
+ * back to its normal text path — planner / slash). When `handled` is true the
+ * submit (if any) has already been kicked off via `submitGateDecision` and the
+ * returned promise resolves when it settles.
+ */
+export interface GateInputRouteResult {
+    handled: boolean;
+}
+/**
+ * Route a typed line against the active gate-prompt entry's phase, mirroring the
+ * TTY `<OrchestrationApp>` `handleInputBarSubmit` gate branch EXACTLY:
+ *
+ *   • awaiting-number: a valid EXACT single digit 1..N → either transition to
+ *     notes-entry (`_WITH_NOTES`) or submit immediately. A digit-SHAPED but
+ *     invalid input (a partial numeric parse like `"1abc"` / `"01"` /
+ *     `"1 approve"`, OR an out-of-range single digit like `"6"`) is CONSUMED
+ *     (`handled:true`) WITHOUT submitting — a `SHELL_ADVISORY` hint is dispatched
+ *     and the prompt stays active, so a `parseInt`-style partial parse can NEVER
+ *     silently resolve a destructive option (the v1-options rule: never
+ *     accept/destroy work on a typo). NON-numeric free text (no leading digit) is
+ *     reported `handled:false` so it falls through to the planner — matching the
+ *     TTY where `<InputBar>` only intercepts digit input and lets free text chat.
+ *     NOTE: the TTY InputBar pre-validates with the identical `/^[0-9]$/` exact-
+ *     single-digit rule (`components/InputBar.tsx:102`); for the non-TTY loop THIS
+ *     router is the PRIMARY validation (`non-tty-fallback.ts:169`).
+ *   • awaiting-notes: the `/cancel` sentinel → NOTES_CANCELLED; otherwise the
+ *     text is the notes plaintext → submit with notes.
+ *   • submitting: input is disabled — consumed (handled) but a no-op.
+ *
+ * Returns `{ handled:false }` when there is no active gate (the caller routes the
+ * line to its normal text path). Awaits the submit so a non-TTY caller's
+ * sequential loop blocks until the decision settles.
+ */
+export declare function routeGatePromptInput(deps: GateDecisionSubmitDeps, activeEntry: GatePromptEntry | null, text: string): Promise<GateInputRouteResult>;
+export {};