@phyzess/pappra 0.0.0-stage → 0.1.0-beta.2

package/dist/collab/lifecycle.d.ts

@@ -0,0 +1,449 @@
+import type { TaskRecord, Message, ResultEntry } from './types.js';
+export declare const ATTEMPT_STATES: readonly string[];
+export declare const ACTIVE_STATES: readonly string[];
+export declare const TERMINAL_STATES: readonly string[];
+/** Outcomes that genuinely end an execution. `needs_input` is a recoverable block, so it is
+ *  terminal for transitions but NOT closed for the purpose of starting a new attempt. */
+export declare const CLOSED_STATES: readonly string[];
+export declare const UNCERTAINTY_KINDS: readonly string[];
+export declare function attemptKey(subtaskId: string, attempt: number): string;
+export declare function findAttempt(record: TaskRecord, subtaskId: string | null, attempt: number | null): import("./types.js").Attempt | null;
+export declare function attemptsFor(record: TaskRecord, subtaskId: string): import("./types.js").Attempt[];
+export declare function latestAttemptNumber(record: TaskRecord, subtaskId: string): number;
+export declare function checkOwnerEpoch(record: TaskRecord, epoch: number): {
+    ok: false;
+    reason: string;
+    expected?: never;
+    actual?: never;
+    owner_epoch?: never;
+} | {
+    ok: false;
+    reason: string;
+    expected: number;
+    actual: number;
+    owner_epoch?: never;
+} | {
+    reason?: never;
+    expected?: never;
+    actual?: never;
+    ok: true;
+    owner_epoch: number;
+};
+/** Every state change is appended as a transition record; history is never rewritten. */
+export declare function transitionAttempt(record: TaskRecord, { subtaskId, attempt, to, actor, reason, evidence, clock, force, }: {
+    subtaskId: string | null;
+    attempt: number | null;
+    to: string;
+    actor?: string;
+    reason?: string;
+    evidence?: unknown;
+    clock?: number;
+    force?: boolean;
+}): {
+    ok: false;
+    reason: string;
+    subtask_id: string | null;
+    attempt: number | null;
+    from?: never;
+    to?: never;
+    detail?: never;
+    state?: never;
+    at?: never;
+} | {
+    subtask_id?: never;
+    attempt?: never;
+    ok: false;
+    reason: string;
+    state: string;
+    from?: never;
+    to?: never;
+    detail?: never;
+    at?: never;
+} | {
+    subtask_id?: never;
+    attempt?: never;
+    ok: false;
+    reason: string;
+    from: string;
+    to: string;
+    detail?: never;
+    state?: never;
+    at?: never;
+} | {
+    subtask_id?: never;
+    attempt?: never;
+    from?: never;
+    to?: never;
+    ok: false;
+    reason: string;
+    detail: string;
+    state?: never;
+    at?: never;
+} | {
+    reason?: never;
+    subtask_id?: never;
+    attempt?: never;
+    from?: never;
+    to?: never;
+    detail?: never;
+    ok: true;
+    state: string;
+    at: string;
+};
+export declare function upsertAssignment(record: TaskRecord, { message, assignmentRef, assignmentDigest, inputRevision, clock, }: {
+    message: Message;
+    assignmentRef?: string | null;
+    assignmentDigest?: string | null;
+    inputRevision?: string | null;
+    clock?: number;
+}): {
+    subtask_id?: never;
+    attempt?: never;
+    detail?: never;
+    state?: never;
+    ok: false;
+    reason: string;
+    latest?: never;
+    requested?: never;
+    still_active?: never;
+} | {
+    detail?: never;
+    state?: never;
+    ok: false;
+    reason: string;
+    subtask_id: string;
+    attempt: number;
+    latest?: never;
+    requested?: never;
+    still_active?: never;
+} | {
+    detail?: never;
+    ok: false;
+    reason: string;
+    state: string;
+    subtask_id: string;
+    attempt: number;
+    latest?: never;
+    requested?: never;
+    still_active?: never;
+} | {
+    subtask_id?: never;
+    attempt?: never;
+    detail?: never;
+    state?: never;
+    ok: false;
+    reason: string;
+    latest: number;
+    requested: number;
+    still_active?: never;
+} | {
+    subtask_id?: never;
+    attempt?: never;
+    state?: never;
+    latest?: never;
+    requested?: never;
+    ok: false;
+    reason: string;
+    detail: string;
+    still_active?: never;
+} | {
+    subtask_id?: never;
+    attempt?: never;
+    state?: never;
+    latest?: never;
+    requested?: never;
+    ok: false;
+    reason: string;
+    detail: string;
+    still_active: string[];
+} | {
+    reason?: never;
+    detail?: never;
+    latest?: never;
+    requested?: never;
+    still_active?: never;
+    ok: true;
+    subtask_id: string;
+    attempt: number;
+    state: string;
+};
+/**
+ * Record native evidence for an attempt. `observation: confirmed` requires an evidence
+ * reference; `unknown` is a first-class observation and never means failure.
+ */
+export declare function bindNative(record: TaskRecord, { subtaskId, attempt, runner, sessionId, runId, missionId, observation, evidenceRef, observedAt, clock, }: {
+    subtaskId: string;
+    attempt: number;
+    runner?: string | null;
+    sessionId?: string | null;
+    runId?: string | null;
+    missionId?: string | null;
+    observation: string;
+    evidenceRef?: string | null;
+    observedAt?: string | null;
+    clock?: number;
+}): {
+    ok: false;
+    reason: string;
+    native?: never;
+    reconciled_uncertainty?: never;
+} | {
+    reason?: never;
+    ok: true;
+    native: import("./types.js").NativeBinding;
+    reconciled_uncertainty: string | null;
+};
+/**
+ * Admit a reported result. Classification:
+ *   applied      the attempt is active and its input revision still matches
+ *   late         the attempt already has a different admitted result: evidence only
+ *   superseded   a newer attempt or a different input revision is authoritative
+ *   duplicate    the same message was already admitted
+ */
+export declare function recordResult(record: TaskRecord, { subtaskId, attempt, status, messageId, inputRevision, outputs, nativeRef, clock, evidenceRef, }: {
+    subtaskId: string;
+    attempt: number;
+    status: string;
+    messageId: string;
+    inputRevision?: string | null;
+    outputs?: unknown[];
+    nativeRef?: unknown;
+    clock?: number;
+    evidenceRef?: string | null;
+}): {
+    ok: false;
+    reason: string;
+    note?: never;
+    classification?: never;
+    entry?: never;
+    transition?: never;
+    transitions?: never;
+} | {
+    reason?: never;
+    ok: true;
+    classification: string;
+    entry: ResultEntry;
+    note?: never;
+    transition?: never;
+    transitions?: never;
+} | {
+    reason?: never;
+    ok: true;
+    classification: string;
+    entry: ResultEntry;
+    note: string;
+    transitions: ({
+        ok: false;
+        reason: string;
+        subtask_id: string | null;
+        attempt: number | null;
+        from?: never;
+        to?: never;
+        detail?: never;
+        state?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        ok: false;
+        reason: string;
+        state: string;
+        from?: never;
+        to?: never;
+        detail?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        ok: false;
+        reason: string;
+        from: string;
+        to: string;
+        detail?: never;
+        state?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        from?: never;
+        to?: never;
+        ok: false;
+        reason: string;
+        detail: string;
+        state?: never;
+        at?: never;
+    } | {
+        reason?: never;
+        subtask_id?: never;
+        attempt?: never;
+        from?: never;
+        to?: never;
+        detail?: never;
+        ok: true;
+        state: string;
+        at: string;
+    })[];
+    transition?: never;
+} | {
+    reason?: never;
+    note?: never;
+    ok: true;
+    classification: string;
+    entry: ResultEntry;
+    transition: {
+        ok: false;
+        reason: string;
+        subtask_id: string | null;
+        attempt: number | null;
+        from?: never;
+        to?: never;
+        detail?: never;
+        state?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        ok: false;
+        reason: string;
+        state: string;
+        from?: never;
+        to?: never;
+        detail?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        ok: false;
+        reason: string;
+        from: string;
+        to: string;
+        detail?: never;
+        state?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        from?: never;
+        to?: never;
+        ok: false;
+        reason: string;
+        detail: string;
+        state?: never;
+        at?: never;
+    } | {
+        reason?: never;
+        subtask_id?: never;
+        attempt?: never;
+        from?: never;
+        to?: never;
+        detail?: never;
+        ok: true;
+        state: string;
+        at: string;
+    } | undefined;
+    transitions: ({
+        ok: false;
+        reason: string;
+        subtask_id: string | null;
+        attempt: number | null;
+        from?: never;
+        to?: never;
+        detail?: never;
+        state?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        ok: false;
+        reason: string;
+        state: string;
+        from?: never;
+        to?: never;
+        detail?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        ok: false;
+        reason: string;
+        from: string;
+        to: string;
+        detail?: never;
+        state?: never;
+        at?: never;
+    } | {
+        subtask_id?: never;
+        attempt?: never;
+        from?: never;
+        to?: never;
+        ok: false;
+        reason: string;
+        detail: string;
+        state?: never;
+        at?: never;
+    } | {
+        reason?: never;
+        subtask_id?: never;
+        attempt?: never;
+        from?: never;
+        to?: never;
+        detail?: never;
+        ok: true;
+        state: string;
+        at: string;
+    })[];
+};
+export declare function writeResultEvidence(taskRoot: string, entry: ResultEntry): string;
+export declare function openUncertainty(record: TaskRecord, { kind, subtaskId, attempt, detail, evidenceRef, resolutionHint, clock, }: {
+    kind: string;
+    subtaskId?: string | null;
+    attempt?: number | null;
+    detail?: string | null;
+    evidenceRef?: string | null;
+    resolutionHint?: string | null;
+    clock?: number;
+}): {
+    ok: false;
+    reason: string;
+    kind: string;
+    duplicate?: never;
+    uncertainty_id?: never;
+} | {
+    reason?: never;
+    kind?: never;
+    ok: true;
+    uncertainty_id: string;
+    duplicate: boolean;
+} | {
+    reason?: never;
+    kind?: never;
+    duplicate?: never;
+    ok: true;
+    uncertainty_id: string;
+};
+export declare function resolveUncertainty(record: TaskRecord, { uncertaintyId, resolution, resolutionEvidence, actor, clock, }: {
+    uncertaintyId: string;
+    resolution: string;
+    resolutionEvidence?: unknown;
+    actor?: string;
+    clock?: number;
+}): {
+    uncertainty_id?: never;
+    ok: false;
+    reason: string;
+    resolved_at?: never;
+    resolution?: never;
+} | {
+    uncertainty_id?: never;
+    ok: false;
+    reason: string;
+    resolved_at: string;
+    resolution?: never;
+} | {
+    reason?: never;
+    resolved_at?: never;
+    ok: true;
+    uncertainty_id: string;
+    resolution: string;
+};
+export declare function recordDigest(record: TaskRecord): string;