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

package/dist/collab/work-plan.d.ts

@@ -0,0 +1,105 @@
+import type { Message, TaskRecord } from './types.js';
+/**
+ * Bounded, read-only role and dependency planning over the authoritative task record.
+ *
+ * This module never writes a record, never claims a resource, never dispatches and never
+ * refreshes evidence. It reads the caller's `TaskRecord` plus the full registered message
+ * envelopes the caller already holds, and reports what the current record says about each
+ * planned node. Every dependency is gated on an explicit coordinator acceptance whose
+ * meaning is re-derived here from the registered envelope, the record entry and the digest
+ * of the accepted report; a finished report alone never unlocks dependent work. The result
+ * is advisory and must be re-evaluated before a later explicit claim or dispatch: role
+ * labels select responsibilities, never authority.
+ */
+export declare const WORK_PLAN_SCHEMA = "pappra/collab-work-plan/1";
+export declare const WORK_PLAN_EVALUATION_SCHEMA = "pappra/collab-work-plan-evaluation/1";
+export interface WorkPlanResource {
+    readonly path: string;
+    readonly access: 'read' | 'write';
+}
+export interface WorkPlanNode {
+    readonly node_id: string;
+    readonly role: string;
+    /** Assignment identity this node expects; correlation is validated, never granted. */
+    readonly assignment_id: string;
+    readonly attempt: number;
+    /** Pinned input revision the node expects to run against. */
+    readonly input_revision: string;
+    readonly assignee: {
+        readonly agent_id: string;
+        readonly session_id: string;
+    };
+    readonly depends_on: readonly string[];
+    readonly resources: readonly WorkPlanResource[];
+}
+export interface WorkPlan {
+    readonly schema: typeof WORK_PLAN_SCHEMA;
+    readonly plan_id: string;
+    readonly task_id: string;
+    readonly owner_epoch: number;
+    readonly nodes: readonly WorkPlanNode[];
+}
+export interface WorkPlanDiagnostic {
+    readonly code: string;
+    readonly node_id: string | null;
+    readonly detail: string;
+}
+export type WorkPlanValidation = {
+    readonly ok: true;
+    readonly plan: WorkPlan;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly WorkPlanDiagnostic[];
+};
+export type WorkNodeStatus = 'ready' | 'running' | 'awaiting_acceptance' | 'accepted' | 'blocked';
+export interface WorkNodeBlocker {
+    readonly code: string;
+    readonly detail: string;
+}
+export interface WorkNodeEvaluation {
+    readonly node_id: string;
+    readonly role: string;
+    readonly status: WorkNodeStatus;
+    readonly blockers: readonly WorkNodeBlocker[];
+    readonly recovery: string | null;
+    /** This node's decision, distinct from blockers inherited from predecessors. */
+    readonly acceptance_blocker?: WorkNodeBlocker | null;
+}
+export interface WorkPlanEvaluation {
+    readonly schema: typeof WORK_PLAN_EVALUATION_SCHEMA;
+    readonly ok: true;
+    readonly plan_id: string;
+    readonly task_id: string;
+    readonly owner_epoch: number;
+    readonly nodes: readonly WorkNodeEvaluation[];
+    readonly ready_nodes: readonly string[];
+    readonly running_nodes: readonly string[];
+    readonly awaiting_acceptance_nodes: readonly string[];
+    readonly accepted_nodes: readonly string[];
+    readonly blocked_nodes: readonly string[];
+    readonly limits: readonly string[];
+}
+export interface WorkPlanRefusal {
+    readonly ok: false;
+    readonly diagnostics: readonly WorkPlanDiagnostic[];
+}
+/**
+ * Caller-supplied evidence. `record` is the authoritative `TaskRecord` that was read from
+ * the task root; `messages` are the full envelopes the caller holds for it. An acceptance
+ * that is registered in the record but not supplied here cannot be verified, so it never
+ * unlocks work.
+ */
+export interface WorkPlanEvidence {
+    readonly plan: unknown;
+    readonly record: TaskRecord;
+    readonly messages?: readonly Message[];
+}
+/** Validates shape, bounds and the dependency graph before any evaluation. */
+export declare function validateWorkPlan(input: unknown): WorkPlanValidation;
+/**
+ * Evaluates a validated plan against the authoritative record and the supplied envelopes.
+ *
+ * Returns a refusal with diagnostics when the plan, the record or the supplied evidence is
+ * malformed or oversized; readiness is never reported from facts that could not be read.
+ */
+export declare function evaluateWorkPlan(evidence: WorkPlanEvidence): WorkPlanEvaluation | WorkPlanRefusal;