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

package/dist/app/collab-recovery-projection.d.ts

@@ -0,0 +1,103 @@
+import type { Identity, TaskRecord } from '../collab/types.js';
+/**
+ * Bounded, read-only recovery analysis over the existing typed task-record, work-plan and
+ * registered-message contracts.
+ *
+ * `inspectRecoveryProjection` reads one consistent persisted snapshot and reuses the shipped bounded
+ * work-plan evaluation to project the unresolved message-driven actions a recovery executor would still
+ * owe: continue an interrupted accepted attempt, progress a completed report into coordinator review, or
+ * observe an ambiguous effect. It NEVER acknowledges, claims, reserves, notifies, starts a model, mutates
+ * no file, and grants no authority: it computes an advisory projection and returns it.
+ *
+ * It is not an executor and not an authorization. Every answer reflects the persisted record at read time
+ * only; concurrent mutation (detected by revalidating the record/plan/namespace after all evidence reads),
+ * a truncated or refused read, a missing join or an unverifiable registered envelope yields an explicit
+ * incomplete/unknown coverage with a complete-evidence prerequisite rather than a quiet completion or an
+ * unqualified actionable recommendation.
+ */
+export declare const COLLAB_RECOVERY_PROJECTION_SCHEMA = "pappra/collab-recovery-projection/1";
+export type RecoveryRole = 'writer' | 'coordinator' | 'reviewer';
+export interface RecoveryPolicy {
+    readonly role: RecoveryRole;
+    /** When present, only these subtask ids are projected; everything else is ignored. */
+    readonly authorizedSubtasks?: readonly string[];
+}
+export type RecoveryActionStatus = 'pending' | 'blocked' | 'observed' | 'complete' | 'unknown';
+export type RecoveryActionKind = 'resume_work' | 'answer_supersedes_wait' | 'progress_report_to_review' | 'report_unadmitted' | 'blocked_awaiting_gate' | 'ambiguous_effect' | 'verified_completion' | 'none';
+export interface RecoveryAction {
+    /** Stable, unambiguous encoding of the action identity for a later reservation/executor. */
+    readonly key: string;
+    readonly kind: RecoveryActionKind;
+    readonly subtask_id: string | null;
+    readonly attempt: number | null;
+    readonly prerequisites: readonly string[];
+    readonly evidence: readonly string[];
+    readonly status: RecoveryActionStatus;
+}
+export interface RecoveryProjection {
+    readonly schema: typeof COLLAB_RECOVERY_PROJECTION_SCHEMA;
+    readonly self: Identity;
+    readonly task_root: string;
+    readonly task_id: string | null;
+    readonly plan_digest: string | null;
+    readonly record_revision: number;
+    readonly coverage: 'complete' | 'incomplete';
+    readonly coordinator_verified: boolean;
+    readonly actions: readonly RecoveryAction[];
+    readonly notes: readonly string[];
+    readonly limits: readonly string[];
+}
+export type RecoveryProjectionResult = {
+    readonly ok: true;
+    readonly value: RecoveryProjection;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly message: string;
+    readonly next_action: string | null;
+};
+export interface RecoveryInspectionOptions {
+    readonly taskRoot: string;
+    readonly planFile: string;
+    readonly self: Identity;
+    readonly policy: RecoveryPolicy;
+}
+/** Two identities match on agent id and session id; harness is compared when both carry one. */
+export declare function idEq(a: {
+    agent_id?: string;
+    session_id?: string;
+    harness?: string | null;
+} | null | undefined, b: {
+    agent_id?: string;
+    session_id?: string;
+    harness?: string | null;
+} | null | undefined): boolean;
+export type SafeRecordRead = {
+    readonly ok: true;
+    readonly record: TaskRecord;
+    readonly digest: string;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+/**
+ * Read the task record through the bounded, no-follow regular-file reader anchored at the task namespace,
+ * returning a structured refusal instead of throwing on a missing, oversized, redirected or corrupt record.
+ */
+export declare function readRecordSafe(taskRoot: string): SafeRecordRead;
+export interface TaskNamespaceAnchor {
+    readonly entries: readonly {
+        readonly path: string;
+        readonly dev: number;
+        readonly ino: number;
+    }[];
+}
+/**
+ * Pin the task root, its messages directory and two ancestors by device/inode so a same-revision
+ * replacement or a redirected task-root/messages namespace is detected across the whole inspection. A
+ * symlinked component makes the anchor unavailable (null).
+ */
+export declare function anchorTaskNamespace(taskRoot: string): TaskNamespaceAnchor | null;
+/** True when every pinned namespace entry still resolves to the same device/inode (no redirect). */
+export declare function verifyTaskNamespace(anchor: TaskNamespaceAnchor | null): boolean;
+export declare function inspectRecoveryProjection(options: RecoveryInspectionOptions): Promise<RecoveryProjectionResult>;