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

package/dist/collab/handoff.d.ts

@@ -0,0 +1,350 @@
+import type { TaskRecord, Identity, Message, Handoff } from './types.js';
+export declare const HANDOFF_KINDS: readonly string[];
+export declare const HANDOFF_STATES: readonly string[];
+export declare function findHandoff(record: TaskRecord, handoffId: string): Handoff | null;
+export declare function beginHandoff(record: TaskRecord, { handoffId, kind, subtaskId, attempt, from, to, resources, ownerEpoch, clock, reason, }: {
+    handoffId: string;
+    kind: string;
+    subtaskId?: string | null;
+    attempt?: number | null;
+    from: Identity;
+    to: Identity;
+    resources?: string[];
+    ownerEpoch: number;
+    clock?: number;
+    reason?: string | null;
+}): {
+    ok: false;
+    reason: string;
+    shared_resources?: never;
+    other_handoff?: never;
+    other_state?: never;
+    expected?: never;
+    actual?: never;
+    handoff_id?: never;
+    state?: never;
+} | {
+    ok: false;
+    reason: string;
+    other_handoff: string;
+    other_state: string;
+    shared_resources: string[];
+    expected?: never;
+    actual?: never;
+    handoff_id?: never;
+    state?: never;
+} | {
+    shared_resources?: never;
+    ok: false;
+    reason: string;
+    other_handoff: string;
+    other_state: string;
+    expected?: never;
+    actual?: never;
+    handoff_id?: never;
+    state?: never;
+} | {
+    shared_resources?: never;
+    other_handoff?: never;
+    other_state?: never;
+    ok: false;
+    reason: string;
+    expected: number | null;
+    actual: number;
+    handoff_id?: never;
+    state?: never;
+} | {
+    shared_resources?: never;
+    other_handoff?: never;
+    other_state?: never;
+    reason?: never;
+    expected?: never;
+    actual?: never;
+    ok: true;
+    handoff_id: string;
+    state: string;
+};
+/**
+ * Record that the previous writer stopped. An `unknown` observation is refused: without
+ * confirmed stopping, overlapping resources stay where they are.
+ */
+export declare function markOldWriterStopped(record: TaskRecord, { handoffId, observation, evidenceRef, detail, actor, clock, }: {
+    handoffId: string;
+    observation: string;
+    evidenceRef?: string | null;
+    detail?: string | null;
+    actor?: string;
+    clock?: number;
+}): {
+    state?: never;
+    ok: false;
+    reason: string;
+    from: string;
+    to: string;
+    expected: string | null | undefined;
+    at?: never;
+} | {
+    reason?: never;
+    expected?: never;
+    from?: never;
+    to?: never;
+    ok: true;
+    state: string;
+    at: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Bind the receiver's real identity once its native session is observed. A handoff may be
+ * requested before the receiver session exists; the identity is then a placeholder and the
+ * confirmation would not correlate. Rebinding requires native evidence and is recorded.
+ */
+export declare function rebindReceiver(record: TaskRecord, { handoffId, to, evidenceRef, actor, clock, }: {
+    handoffId: string;
+    to: Identity;
+    evidenceRef: string;
+    actor?: string;
+    clock?: number;
+}): {
+    state?: never;
+    to?: never;
+    ok: false;
+    reason: string;
+    detail?: never;
+    confirmed_receiver?: never;
+    previous?: never;
+} | {
+    to?: never;
+    ok: false;
+    reason: string;
+    state: string;
+    detail?: never;
+    confirmed_receiver?: never;
+    previous?: never;
+} | {
+    state?: never;
+    to?: never;
+    ok: false;
+    reason: string;
+    detail: string;
+    confirmed_receiver: Identity;
+    previous?: never;
+} | {
+    reason?: never;
+    state?: never;
+    detail?: never;
+    confirmed_receiver?: never;
+    ok: true;
+    to: Identity;
+    previous: Identity;
+};
+export declare function markTransferring(record: TaskRecord, { handoffId, partialOutputs, inflight, pendingApprovals, actor, clock, }: {
+    handoffId: string;
+    partialOutputs?: unknown[];
+    inflight?: unknown[];
+    pendingApprovals?: unknown[];
+    actor?: string;
+    clock?: number;
+}): {
+    state?: never;
+    ok: false;
+    reason: string;
+    from: string;
+    to: string;
+    expected: string | null | undefined;
+    at?: never;
+} | {
+    reason?: never;
+    expected?: never;
+    from?: never;
+    to?: never;
+    ok: true;
+    state: string;
+    at: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The receiver's acknowledgement must be a stored message that replies to this handoff. */
+export declare function confirmReceiver(record: TaskRecord, { handoffId, message, clock, }: {
+    handoffId: string;
+    message: Message | null;
+    clock?: number;
+}): {
+    state?: never;
+    ok: false;
+    reason: string;
+    from: string;
+    to: string;
+    expected: string | null | undefined;
+    at?: never;
+} | {
+    reason?: never;
+    expected?: never;
+    from?: never;
+    to?: never;
+    ok: true;
+    state: string;
+    at: string;
+} | {
+    ok: false;
+    reason: string;
+    type?: never;
+} | {
+    ok: false;
+    reason: string;
+    type: string;
+};
+/**
+ * Complete the handoff: move ownership and raise the epoch. Old-epoch commands are
+ * rejected by the epoch check, so the previous owner cannot keep dispatching.
+ */
+export declare function completeHandoff(record: TaskRecord, { handoffId, actor, clock, }: {
+    handoffId: string;
+    actor?: string;
+    clock?: number;
+}): {
+    state?: never;
+    ok: false;
+    reason: string;
+    from: string;
+    to: string;
+    expected: string | null | undefined;
+    at?: never;
+} | {
+    reason?: never;
+    expected?: never;
+    from?: never;
+    to?: never;
+    ok: true;
+    state: string;
+    at: string;
+} | {
+    expected?: never;
+    actual?: never;
+    ok: false;
+    reason: string;
+    drift?: never;
+} | {
+    expected?: never;
+    actual?: never;
+    ok: false;
+    reason: string;
+    drift: ({
+        expected?: never;
+        actual?: never;
+        from?: never;
+        claim_id: string;
+        reason: string;
+    } | {
+        from?: never;
+        claim_id: string;
+        reason: string;
+        expected: number | null | undefined;
+        actual: number;
+    } | {
+        from?: never;
+        claim_id: string;
+        reason: string;
+        expected: Identity | null | undefined;
+        actual: Identity;
+    } | {
+        expected?: never;
+        claim_id: string;
+        reason: string;
+        from: Identity;
+        actual: Identity;
+    })[];
+} | {
+    drift?: never;
+    ok: false;
+    reason: string;
+    expected: number;
+    actual: number | null;
+};
+export declare function abortHandoff(record: TaskRecord, { handoffId, actor, reason, clock, }: {
+    handoffId: string;
+    actor?: string;
+    reason?: string;
+    clock?: number;
+}): {
+    state?: never;
+    ok: false;
+    reason: string;
+} | {
+    reason?: never;
+    ok: true;
+    state: string;
+};
+export declare function releaseDispatchFreeze(record: TaskRecord, { actor, ownerEpoch, clock, }: {
+    actor?: string;
+    ownerEpoch: number;
+    clock?: number;
+}): {
+    ok: false;
+    reason: string;
+    expected: number | null;
+    actual: number;
+    dispatch_frozen?: never;
+} | {
+    reason?: never;
+    expected?: never;
+    actual?: never;
+    ok: true;
+    dispatch_frozen: boolean;
+};
+/** Snapshot of what a handing-over owner must account for. */
+export declare function handoffInventory(record: TaskRecord, { subtaskId, attempt, }: {
+    subtaskId?: string | null;
+    attempt?: number | null;
+}): {
+    inflight: {
+        subtask_id: string;
+        attempt: number;
+        state: string;
+        native: import("./types.js").NativeBinding;
+    }[];
+    closed: {
+        subtask_id: string;
+        attempt: number;
+        state: string;
+    }[];
+    pending_approvals: {
+        subtask_id: string;
+        attempt: number;
+    }[];
+    uncertainty: {
+        uncertainty_id: string;
+        kind: string;
+        subtask_id: string | null;
+        attempt: number | null;
+    }[];
+    resources: {
+        claim_id: string;
+        key: string;
+        holder: Identity;
+        resource_epoch: number;
+    }[];
+    results: {
+        subtask_id: string;
+        attempt: number;
+        status: string;
+        classification: string;
+        message_id: string;
+        outputs: unknown[];
+    }[];
+    handoffs: {
+        handoff_id: string;
+        kind: string;
+        state: string;
+    }[];
+    coordinator: import("./types.js").Coordinator | null;
+    epoch_semantics: {
+        owner_epoch: string;
+        state_revision: number;
+        resource_epoch: string;
+        note: string;
+    };
+};
+export declare function newHandoffId(prefix?: string): string;