@phyzess/pappra 0.1.0-beta.13 → 0.1.0-beta.18

package/dist/app/collab-rollover.d.ts

@@ -0,0 +1,263 @@
+import * as rollover from '../collab/rollover.js';
+import type { Identity } from '../collab/types.js';
+import { type RouteExclusion, type RouteExclusionLookup } from './collab-route.js';
+/**
+ * Public read-only rollover inspection and planning.
+ *
+ * The entry reads the exact authoritative task record and the one exact linked continuity
+ * handoff bundle, then reports the current rollover facts and the steps a later execution
+ * would need. It never mutates the task, claims, bundle, binding, notification or delivery
+ * files, and it exposes no apply path: a caller-supplied stop observation or producer label
+ * is not authenticated native proof, so host stop/freeze evidence, native launch, native
+ * session archive and routing removal are reported as unavailable.
+ */
+export declare const COLLAB_ROLLOVER_REQUEST_SCHEMA = "pappra/collaboration-rollover-request/1";
+export declare const COLLAB_ROLLOVER_REPORT_SCHEMA = "pappra/collaboration-rollover-report/1";
+export type RolloverAction = 'inspect' | 'plan';
+export type RolloverStage = 'unknown' | 'pre-transfer' | 'old-writer-stopped' | 'transferring' | 'receiver-confirmed' | 'completed' | 'aborted';
+export interface RolloverIntentRequest {
+    readonly intent_id: string;
+    readonly generation: number;
+    readonly handoff_id: string;
+    readonly subtask_id: string;
+    readonly attempt: number;
+    readonly input_revision: string;
+    readonly from: Identity;
+    readonly to: Identity;
+    readonly claims: readonly {
+        readonly claim_id: string;
+        readonly resource_epoch: number;
+    }[];
+    readonly coordinator_epoch: number;
+}
+export interface RolloverBundleRequest {
+    readonly root: string;
+    readonly continuity_task_id: string;
+    readonly bundle_id: string;
+    readonly digest: string;
+}
+export interface RolloverEvidenceRequest {
+    readonly ack_message_id: string | null;
+    readonly report_message_id: string | null;
+}
+export interface RolloverRequest {
+    readonly schema: typeof COLLAB_ROLLOVER_REQUEST_SCHEMA;
+    readonly action: RolloverAction;
+    readonly task_root: string;
+    readonly intent_id: string | null;
+    readonly proposed_intent: RolloverIntentRequest | null;
+    readonly bundle: RolloverBundleRequest;
+    readonly evidence: RolloverEvidenceRequest;
+}
+export interface RolloverBlocker {
+    readonly code: string;
+    readonly detail: string;
+}
+export type RolloverStepStatus = 'satisfied' | 'ready' | 'blocked' | 'unavailable';
+export interface RolloverStepReport {
+    readonly step: 'create-intent' | 'prepare-transfer' | 'confirm-receiver' | 'complete-transfer' | 'record-first-work';
+    readonly status: RolloverStepStatus;
+    readonly requires: string;
+    readonly blockers: readonly RolloverBlocker[];
+}
+export interface RolloverClaimsReport {
+    readonly claim_id: string;
+    readonly holder: Identity | null;
+    readonly resource_epoch: number | null;
+    readonly expected_resource_epoch: number;
+    readonly expected_holder: Identity | null;
+    readonly expected_epoch: number | null;
+    readonly released_at: string | null;
+}
+export interface RolloverNativeReport {
+    readonly observation: string | null;
+    readonly session_id: string | null;
+    readonly run_id: string | null;
+    readonly runner: string | null;
+    readonly matches_expected: boolean | null;
+}
+export interface RolloverSnapshotClaim {
+    readonly claim_id: string;
+    readonly resource: string;
+    readonly resource_epoch: number;
+    readonly holder: string | null;
+}
+export interface RolloverEvidenceCorrelation {
+    readonly message_id: string;
+    readonly role: 'ack' | 'report';
+    readonly type: string;
+    readonly digest: string;
+    readonly sender: Identity;
+    readonly recipient: Identity | null;
+    readonly task_id: string;
+    readonly subtask_id: string | null;
+    readonly attempt: number | null;
+    readonly input_revision: string | null;
+    readonly intent_id: string | null;
+    readonly generation: number | null;
+    readonly owner_epoch: number | null;
+    readonly ledger_index: number;
+    readonly proof_order_ok: boolean | null;
+    readonly applies_to_intent: boolean;
+    readonly issues: readonly string[];
+}
+export interface RolloverReport {
+    readonly schema: typeof COLLAB_ROLLOVER_REPORT_SCHEMA;
+    readonly action: RolloverAction;
+    readonly ok: true;
+    readonly task_root: string;
+    readonly task_id: string;
+    readonly state_revision: number;
+    readonly owner_epoch: number | null;
+    readonly stage: RolloverStage;
+    readonly intent: {
+        readonly found: boolean;
+        readonly intent_id: string | null;
+        readonly generation: number | null;
+        readonly handoff_id: string | null;
+        readonly subtask_id: string | null;
+        readonly attempt: number | null;
+        readonly input_revision: string | null;
+        readonly from: Identity | null;
+        readonly to: Identity | null;
+        readonly source_native: rollover.RolloverNativeIdentity | null;
+        readonly bundle: rollover.RolloverBundleReference | null;
+        readonly transfer_boundary: rollover.RolloverTransferBoundary | null;
+        readonly successor_native: rollover.RolloverNativeIdentity | null;
+    };
+    readonly handoff: {
+        readonly state: string | null;
+        readonly from: Identity | null;
+        readonly to: Identity | null;
+        readonly owner_epoch: number | null;
+    };
+    readonly prepared: {
+        readonly recorded: boolean;
+        readonly evidence_ref: string | null;
+        readonly inventory: string | null;
+        readonly at: string | null;
+    };
+    readonly attempt: {
+        readonly state: string | null;
+        readonly assignee: Identity | null;
+        readonly input_revision: string | null;
+        readonly latest_attempt: number | null;
+        readonly native: RolloverNativeReport | null;
+        readonly expected: {
+            readonly assignee: Identity | null;
+            readonly input_revision: string | null;
+            readonly native: {
+                readonly session_id: string | null;
+                readonly run_id: string | null;
+                readonly runner: string | null;
+            } | null;
+        } | null;
+    } | null;
+    readonly claims: readonly RolloverClaimsReport[];
+    readonly succession: {
+        readonly recorded: boolean;
+        readonly valid: boolean;
+        readonly issue: string | null;
+        readonly intent_id: string | null;
+        readonly handoff_id: string | null;
+        readonly generation: number | null;
+        readonly archived_at: string | null;
+        readonly proof_message_id: string | null;
+        readonly proof_digest: string | null;
+        readonly routing: 'pending';
+        readonly native_archive: 'unavailable';
+    };
+    readonly bundle: {
+        readonly ref: string;
+        readonly continuity_task_id: string;
+        readonly digest: string;
+        readonly digest_matches: true;
+        readonly pinned: boolean;
+        readonly verified: true;
+        readonly context_integrity: 'complete' | 'incomplete' | 'unknown';
+        readonly checkpoint_present: true;
+        readonly workspace_identity_matches: true;
+        readonly execution_allowed: false;
+        readonly source_session: {
+            readonly harness: string;
+            readonly session_id: string;
+            readonly agent_id: string | null;
+            readonly matches_plan: boolean;
+        };
+        readonly collaboration: {
+            readonly task_id: string;
+            readonly subtask_id: string | null;
+            readonly attempt: number;
+            readonly owner_epoch: number;
+            readonly input_revision: string | null;
+            readonly association: string | null;
+            readonly matches_plan: boolean;
+        };
+        readonly handoff_snapshot: {
+            readonly claims: readonly RolloverSnapshotClaim[];
+            readonly claims_completeness: string;
+            readonly claims_match: boolean;
+            readonly inventory_complete: boolean;
+            readonly pending: readonly {
+                readonly kind: string;
+                readonly items: number;
+                readonly completeness: string;
+            }[];
+        };
+    };
+    readonly drift: readonly RolloverBlocker[];
+    readonly steps: readonly RolloverStepReport[];
+    readonly blockers: readonly RolloverBlocker[];
+    readonly notify_exclusion: {
+        readonly sender: RouteExclusionLookup;
+        readonly recipient: RouteExclusionLookup;
+        readonly exclusions: readonly RouteExclusion[];
+        readonly effective: 'excluded' | 'active' | 'unknown';
+    };
+    readonly capabilities: {
+        readonly record_reducer: 'available';
+        readonly bundle_verification: 'available';
+        readonly notify_exclusion: 'available';
+        readonly host_stop_proof: 'unavailable';
+        readonly native_launch: 'unavailable';
+        readonly native_session_archive: 'unavailable';
+        readonly routing_removal: 'pending';
+    };
+    readonly evidence: {
+        readonly requested: readonly string[];
+        readonly supplied: number;
+        readonly raw_bytes: number;
+        readonly over_budget: boolean;
+        readonly unreadable: readonly {
+            readonly message_id: string;
+            readonly code: string;
+        }[];
+        readonly issues: readonly RolloverBlocker[];
+        readonly correlations: readonly RolloverEvidenceCorrelation[];
+    };
+    readonly plan_complete: boolean;
+    readonly limits: readonly string[];
+}
+export interface RolloverFailure {
+    readonly ok: false;
+    readonly kind: 'invalid' | 'needs_input';
+    readonly code: string;
+    readonly message: string;
+    readonly nextAction: string | null;
+}
+export type RolloverRequestResult = {
+    readonly ok: true;
+    readonly value: RolloverRequest;
+} | RolloverFailure;
+export type RolloverResult = {
+    readonly ok: true;
+    readonly value: RolloverReport;
+} | RolloverFailure;
+/**
+ * Validates one request value. The CLI loader and the public app entry both call this, so a
+ * direct caller cannot skip the documented shape by constructing an object in memory.
+ */
+export declare function validateRolloverRequest(parsed: unknown): RolloverRequestResult;
+/** Loads one bounded request document; unsafe or oversized input is invalid, never read. */
+export declare function loadRolloverRequest(file: string): RolloverRequestResult;
+export declare function inspectOrPlanRollover(input: unknown): Promise<RolloverResult>;