botmux 2.111.0 → 2.112.0

package/dist/workflows/resume.d.ts

@@ -1,263 +0,0 @@
-/**
- * Resume + reconcile algorithm (events doc v0.1.2 §4.3 + §4.3.1).
- *
- * Entry point for daemon restart / hand-off.  Walks the event log,
- * replays a snapshot, then drives reconcile decisions for each dangling
- * `effectAttempted` and writes terminal events for `pure skill`
- * activities that crashed mid-flight (workerLost path).
- *
- * Step 7 boundaries:
- *   - Resume DOES NOT execute activity logic; reconcile uses provider
- *     capabilities (`readOnlyLookup` / `idempotentSubmit`) to decide
- *     terminal state without re-issuing user-visible work beyond what
- *     idempotency guarantees.
- *   - Resume DOES NOT decide retry policy.  A `freshRetry` decision
- *     leaves the attempt dangling — the scheduler (Step 8+) is
- *     responsible for spawning the actual replacement attempt.
- *   - Dangling waits are left alone (waiting for external signal).
- *
- * Round 1 fixes (codex review of `1d14081`):
- *   F1 — replay surfaces the latest reconcileResult per attempt; resume
- *        consumes it before re-running the decision tree, so a crash
- *        between reconcileResult and the terminal event is recoverable.
- *   F2 — reconcilers receive the materialized effect input via the
- *        caller-supplied `loadEffectInput` callback.  Reconcilers that
- *        require input (e.g. Feishu — chatId/rootMessageId/content can't
- *        be reconstructed from idempotencyKey alone) fail explicitly
- *        when input is unrecoverable.
- *   F3 — `retryable` failures from idempotentSubmit do NOT terminate
- *        the attempt; the activity stays dangling and is surfaced in
- *        `ResumeResult.transientFailures` for the caller to retry.
- *   F4 — `resumeStarted` is written ONLY after a preflight validates
- *        the log is replayable; bad inputs throw without polluting the
- *        run event log.
- */
-import type { EventLog } from './events/append.js';
-import { type Snapshot, type AttemptState } from './events/replay.js';
-import type { ActivityCanceledEvent, ActivityFailedEvent, ActivitySucceededEvent, ReconcileResultEvent, ResumeStartedEvent } from './events/types.js';
-export type ReconcileCapability = 'readOnlyLookup' | 'idempotentSubmit' | 'none';
-export type ReconcileDecision = 'replayed' | 'completedByIdempotentSubmit' | 'manual' | 'freshRetry';
-export type ReadOnlyLookupResult = {
-    found: true;
-    externalRefs: Record<string, unknown>;
-    evidence?: Record<string, unknown>;
-} | {
-    found: false;
-    evidence?: Record<string, unknown>;
-};
-export type IdempotentSubmitResult = {
-    ok: true;
-    externalRefs: Record<string, unknown>;
-    evidence?: Record<string, unknown>;
-} | {
-    ok: false;
-    errorCode: string;
-    errorClass: 'retryable' | 'fatal' | 'userFault' | 'manual';
-    errorMessage: string;
-    evidence?: Record<string, unknown>;
-};
-/**
- * Per-provider capability bundle.  Resume looks up the reconciler by the
- * `effectAttempted.provider` field; missing entries fall through to
- * manual/UnknownProviderError.
- *
- * Reconcilers receive the materialized effect input alongside the
- * idempotencyKey: providers like Feishu can't re-construct the request
- * body from the key alone (the key is a hash, not the body).  When the
- * caller doesn't supply `loadEffectInput`, resume treats the input as
- * `undefined`; reconcilers that NEED input MUST declare so via
- * `requiresEffectInput` so resume can fail fast with a clear error
- * instead of letting the reconciler silently misbehave.
- */
-export interface ProviderReconciler {
-    readonly provider: string;
-    /**
-     * When `true`, resume refuses to call this reconciler without a
-     * materialized effect input — i.e. it writes manual/InputUnrecoverable
-     * if `loadEffectInput` is absent or throws.  Feishu sets this; schedule
-     * does not (idempotencyKey is the full key).
-     */
-    readonly requiresEffectInput?: boolean;
-    /**
-     * Pure read against the provider keyed by `idempotencyKey`.  Has no
-     * side effects; safe to call from resume even when we don't intend to
-     * complete the effect.  Schedule has it (`getTask(id)`); Feishu does
-     * not (no uuid-reverse-lookup API).
-     */
-    readOnlyLookup?(idempotencyKey: string, input: unknown): Promise<ReadOnlyLookupResult>;
-    /**
-     * Re-submit the effect with the same `idempotencyKey`.  MAY produce
-     * the side effect for real (if the original pre-invoke crash never
-     * reached the provider); provider dedupe inside TTL guarantees the
-     * second submit returns the original ref instead of a duplicate.
-     */
-    idempotentSubmit?(idempotencyKey: string, input: unknown): Promise<IdempotentSubmitResult>;
-    /**
-     * Canonical form of the loaded effect input — used at resume time to
-     * recompute `inputHash` and compare against `effectAttempted.inputHash`.
-     * MUST mirror the executor's `canonicalInput` exactly; mismatched
-     * canonicalization across resume/dispatch silently breaks idempotency.
-     *
-     * Reconcilers with `requiresEffectInput=true` SHOULD implement this;
-     * resume writes `IdempotencyInputMismatch/manual` if a tampered or
-     * drifted sidecar would otherwise reach the provider with a different
-     * body than the original attempt promised.
-     */
-    canonicalInput?(input: unknown): unknown;
-}
-export type ResumeContext = {
-    /** Authoritative event log for this run.  Resume writes events into it. */
-    log: EventLog;
-    /** Match `log.runId`; passed explicitly so the contract is visible. */
-    runId: string;
-    /** Daemon identifier for the resumeStarted audit event. */
-    daemonId: string;
-    /** Reconcilers keyed by provider name (`feishu-im`, `botmux-schedule`). */
-    reconcilers: Map<string, ProviderReconciler>;
-    /**
-     * Load the materialized effect input that was passed to the original
-     * attempt.  Required for providers that re-submit (Feishu).  Resume
-     * passes the returned value to the reconciler's readOnlyLookup /
-     * idempotentSubmit.
-     *
-     * v0: the caller (daemon) decides where to persist or recover this —
-     * in-memory while alive, or some external storage on cold start.
-     * Resume only consumes the callback.
-     *
-     * Returning `undefined` is treated as "input unrecoverable" and
-     * triggers the manual/InputUnrecoverable path for reconcilers that
-     * declared `requiresEffectInput`.
-     */
-    loadEffectInput?(activityId: string, attemptId: string): Promise<unknown>;
-    /** Injectable clock for deterministic tests.  Defaults to Date.now. */
-    now?: () => number;
-};
-export type ReconcileOutcome = {
-    activityId: string;
-    attemptId: string;
-    idempotencyKey: string;
-    provider: string;
-    capability: ReconcileCapability;
-    decision: ReconcileDecision;
-    evidence: Record<string, unknown>;
-    /**
-     * Terminal event written as a consequence.  null for `replayed` (the
-     * pre-existing terminal IS the consequence) and `freshRetry` (scheduler
-     * issues a new attempt later, not Step 7's job).
-     */
-    terminalEvent: ActivitySucceededEvent | ActivityFailedEvent | null;
-    /** The reconcileResult event written, or null if this outcome reused
-     *  a pre-existing reconcileResult (recovery path — codex F1). */
-    reconcileEvent: ReconcileResultEvent | null;
-    /** True when this outcome recovered a prior crashed reconcile cycle
-     *  rather than running the decision tree from scratch. */
-    recovered: boolean;
-};
-export type WorkerCrashedOutcome = {
-    activityId: string;
-    attemptId: string;
-    terminalEvent: ActivityFailedEvent;
-};
-/**
- * Recovery of a wait whose resolution event landed but whose activity
- * terminal was never written (crash between `waitResolved` /
- * `waitDeadlineExceeded` and the terminal).  Step 8: replay surfaces
- * these as `Snapshot.danglingWaitResolutions`; resume materializes the
- * terminal from the recorded resolution.
- */
-export type WaitRecoveryOutcome = {
-    activityId: string;
-    attemptId: string;
-    /** What the recovery decided to write. */
-    kind: 'succeeded' | 'failed';
-    source: 'resolved' | 'deadlineExceeded';
-    terminalEvent: ActivitySucceededEvent | ActivityFailedEvent;
-};
-/**
- * Recovery of a cancel whose request landed but whose activity
- * terminal was never written (crash between `cancelRequested` /
- * `cancelDelivered` and the terminal).  Step 9: replay surfaces these
- * as `Snapshot.danglingCancels`.
- *
- * The terminal resume writes depends on whether the cancelled
- * attempt also had a dangling `effectAttempted` (Step 9 round 1
- * finding 1):
- *
- *   - **No effectAttempted** (plain cancel): resume writes
- *     `activityCanceled` directly, with `cancelOriginEventId`
- *     pointing at the originating `cancelRequested`.
- *   - **effectAttempted present** (cancel + effect): resume FIRST
- *     runs reconcile to capture provider evidence (writes
- *     `reconcileResult` with cancel-coupled keys — see
- *     payloads.ts `ReconcileResultPayload` doc), THEN decides:
- *       - `completedByIdempotentSubmit` / `freshRetry` →
- *         `activityCanceled` (cancel wins as terminal reason; the
- *         provider's outcome is preserved in reconcileResult evidence)
- *       - `manual` (TTL expired / unknown provider / submit errored
- *         fatally) → `activityFailed{manual}` — we deliberately do
- *         NOT write `activityCanceled` because provider state is
- *         unknown and pretending the cancel cleanly succeeded would
- *         lie to forensics
- *       - `transient` → NO terminal; the activity stays dangling and
- *         the next resume cycle retries (surfaces as a
- *         `TransientReconcileFailure` on `ResumeResult.transientFailures`)
- */
-export type CancelRecoveryOutcome = {
-    activityId: string;
-    attemptId: string;
-    cancelOriginEventId: string;
-    /** True if cancelDelivered was already written; false means we
-     *  short-circuited a never-delivered cancel.  Both still terminate
-     *  the activity (cancel intent is authoritative). */
-    delivered: boolean;
-    /**
-     * What terminal we ended up writing.  `cancelled` is the regular
-     * cancel terminal; `failed` is the "manual escalation" path when
-     * reconcile evidence is non-conclusive (Step 9 finding 1).
-     */
-    kind: 'cancelled' | 'failed';
-    /** Present when reconcile ran alongside cancel — i.e. the activity
-     *  had a dangling effectAttempted.  Pure cancels (no effect) leave
-     *  this undefined. */
-    reconcileEvent?: ReconcileResultEvent;
-    /**
-     * The reconcile decision that informed the cancel terminal (only
-     * populated when the activity had a dangling effectAttempted).
-     * - For `completedByIdempotentSubmit` and `freshRetry`, terminal is
-     *   `activityCanceled`.
-     * - For `manual`, terminal is `activityFailed{manual}`.
-     */
-    reconcileDecision?: ReconcileDecision;
-    terminalEvent: ActivityCanceledEvent | ActivityFailedEvent;
-};
-/**
- * Reconcile failures that resume DELIBERATELY does not terminate (codex
- * F3): a retryable provider failure during idempotentSubmit might mean
- * "request landed, response lost", and writing a manual terminal there
- * would freeze the activity in a wrong terminal state.  Resume reports
- * these back to the caller and leaves the activity dangling so the next
- * resume cycle can retry.
- */
-export type TransientReconcileFailure = {
-    activityId: string;
-    attemptId: string;
-    provider: string;
-    idempotencyKey: string;
-    errorCode: string;
-    errorClass: 'retryable';
-    errorMessage: string;
-};
-export type ResumeResult = {
-    resumeStartedEvent: ResumeStartedEvent;
-    /** Snapshot captured after `resumeStarted` is appended.  Returned for
-     *  observability — caller can inspect dangling sets it consumed. */
-    snapshot: Snapshot;
-    reconcileOutcomes: ReconcileOutcome[];
-    workerCrashedOutcomes: WorkerCrashedOutcome[];
-    transientFailures: TransientReconcileFailure[];
-    waitRecoveryOutcomes: WaitRecoveryOutcome[];
-    cancelRecoveryOutcomes: CancelRecoveryOutcome[];
-};
-export declare function resume(ctx: ResumeContext): Promise<ResumeResult>;
-export type { AttemptState };
-//# sourceMappingURL=resume.d.ts.map

package/dist/workflows/resume.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resume.d.ts","sourceRoot":"","sources":["../../src/workflows/resume.ts"],"names":[],"mappings":"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"}