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

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

@@ -0,0 +1,7 @@
+import { type TaskStoreFailure, type TaskStoreResult } from './collab-task-store.js';
+export declare const COLLAB_STATE_SCHEMA = "pappra/collaboration-state/1";
+export type StateAction = 'show' | 'doctor' | 'epoch-check';
+export declare function showTaskState(taskRoot: string): Promise<TaskStoreResult<Record<string, unknown>>>;
+export declare function doctorTaskState(taskRoot: string): Promise<TaskStoreResult<Record<string, unknown>>>;
+export declare function checkTaskEpoch(taskRoot: string, ownerEpoch: number): Promise<TaskStoreResult<Record<string, unknown>>>;
+export type { TaskStoreFailure };

package/dist/app/collab-state.js

@@ -0,0 +1,162 @@
+import { checkOwnerEpoch } from '../collab/lifecycle.js';
+import { activeClaims } from '../collab/resources.js';
+import { doctor, readLock } from '../collab/store.js';
+import { openTaskStore, } from './collab-task-store.js';
+export const COLLAB_STATE_SCHEMA = 'pappra/collaboration-state/1';
+const MAX_COLLECTION_ROWS = 50;
+function limitRows(items) {
+    return {
+        rows: items.slice(0, MAX_COLLECTION_ROWS),
+        total: items.length,
+        truncated: items.length > MAX_COLLECTION_ROWS,
+    };
+}
+function lockSummary(taskRoot) {
+    const lock = readLock(taskRoot);
+    return {
+        held: lock.held,
+        holder: lock.held ? lock.holder : null,
+        holder_process_alive: lock.held ? lock.holder_process_alive : false,
+        transaction_count: lock.transaction_files?.length ?? 0,
+    };
+}
+export async function showTaskState(taskRoot) {
+    const opened = await openTaskStore(taskRoot);
+    if (!opened.ok)
+        return opened;
+    const { record, taskRoot: canonical } = opened.value;
+    const attempts = limitRows((record.attempts ?? []).map((item) => ({
+        subtask_id: item.subtask_id,
+        attempt: item.attempt,
+        state: item.state,
+        ownership: item.ownership ?? null,
+        native: item.native,
+    })));
+    const claims = limitRows(activeClaims(record));
+    const handoffs = limitRows((record.handoffs ?? []).map((item) => ({
+        handoff_id: item.handoff_id,
+        kind: item.kind,
+        state: item.state,
+    })));
+    const uncertainty = limitRows((record.uncertainty ?? [])
+        .filter((item) => !item.resolved_at)
+        .map((item) => ({
+        uncertainty_id: item.uncertainty_id,
+        kind: item.kind,
+        subtask_id: item.subtask_id,
+        attempt: item.attempt,
+        detail: item.detail,
+    })));
+    const results = limitRows((record.results ?? []).map((item) => ({
+        subtask_id: item.subtask_id,
+        attempt: item.attempt,
+        status: item.status,
+        classification: item.classification,
+        message_id: item.message_id,
+    })));
+    const lock = lockSummary(canonical);
+    return {
+        ok: true,
+        value: {
+            schema: COLLAB_STATE_SCHEMA,
+            ok: true,
+            action: 'show',
+            task_root: canonical,
+            task_id: record.task_id,
+            state_revision: record.state_revision,
+            coordinator: record.coordinator ?? null,
+            dispatch_frozen: record.dispatch_frozen === true,
+            attempts: attempts.rows,
+            messages: (record.messages ?? []).length,
+            claims: claims.rows,
+            handoffs: handoffs.rows,
+            open_uncertainty: uncertainty.rows,
+            results: results.rows,
+            lock,
+            counts: {
+                attempts: attempts.total,
+                messages: (record.messages ?? []).length,
+                claims: claims.total,
+                handoffs: handoffs.total,
+                open_uncertainty: uncertainty.total,
+                results: results.total,
+            },
+            truncated: {
+                attempts: attempts.truncated,
+                claims: claims.truncated,
+                handoffs: handoffs.truncated,
+                open_uncertainty: uncertainty.truncated,
+                results: results.truncated,
+            },
+            limits: ['reported_state_only', 'native_execution_not_queried'],
+        },
+    };
+}
+export async function doctorTaskState(taskRoot) {
+    const opened = await openTaskStore(taskRoot);
+    if (!opened.ok)
+        return opened;
+    const { taskRoot: canonical } = opened.value;
+    let report;
+    try {
+        report = doctor(canonical);
+    }
+    catch {
+        return {
+            ok: false,
+            code: 'task_state_unreadable',
+            message: 'The task state could not be diagnosed.',
+            nextAction: 'Inspect the task record, lock and transaction paths; nothing was repaired.',
+        };
+    }
+    const findings = limitRows(report.findings);
+    const blocking = report.findings.filter((finding) => finding.severity === 'invalid').length;
+    const uncertain = report.findings.filter((finding) => finding.severity === 'uncertain').length;
+    const active = report.findings.filter((finding) => finding.severity === 'active').length;
+    return {
+        ok: true,
+        value: {
+            schema: COLLAB_STATE_SCHEMA,
+            // A live lock observation is diagnostic but not a readiness failure.
+            // Unresolved uncertain evidence and invalid layout/records need input.
+            ok: blocking === 0 && uncertain === 0,
+            action: 'doctor',
+            task_root: report.task_root,
+            state_revision: report.state_revision,
+            findings: findings.rows,
+            counts: { findings: findings.total, blocking, uncertain, active },
+            truncated: findings.truncated,
+            lock: lockSummary(canonical),
+            limits: ['diagnostic_only', 'no_repair_or_lock_break'],
+        },
+    };
+}
+export async function checkTaskEpoch(taskRoot, ownerEpoch) {
+    const opened = await openTaskStore(taskRoot);
+    if (!opened.ok)
+        return opened;
+    const { record, taskRoot: canonical } = opened.value;
+    const result = checkOwnerEpoch(record, ownerEpoch);
+    const subtasks = limitRows((record.attempts ?? []).map((item) => ({
+        subtask_id: item.subtask_id,
+        attempt: item.attempt,
+        state: item.state,
+    })));
+    return {
+        ok: true,
+        value: {
+            schema: COLLAB_STATE_SCHEMA,
+            ok: result.ok,
+            action: 'epoch-check',
+            task_root: canonical,
+            owner_epoch: result.ok ? result.owner_epoch : null,
+            expected: record.coordinator?.owner_epoch ?? null,
+            actual: ownerEpoch,
+            reason: result.ok ? null : result.reason,
+            subtasks: subtasks.rows,
+            counts: { subtasks: subtasks.total },
+            truncated: subtasks.truncated,
+            limits: ['reported_epoch_only', 'no_authority_transition'],
+        },
+    };
+}

package/dist/app/collab-task-store.d.ts

@@ -0,0 +1,22 @@
+import type { Outcome } from '../schemas/outcome.js';
+import { type MessageServiceFailure, type OpenedMessageTask } from './collab-messages.js';
+/**
+ * Task-store namespace proof for state and resource operations.
+ *
+ * The message namespace validator is authoritative for the domain/tasks/task
+ * root, task record and messages directory. This module additionally inspects
+ * the nested paths the new routes may read or mutate: the write lock and its
+ * transaction files, ledger, aborted/broken-lock directories, the resource
+ * domain lock, and neighboring task records used by domain-wide scans. Symlinks
+ * and special files in those paths are refused instead of being followed.
+ */
+export type TaskStoreFailure = MessageServiceFailure;
+export type TaskStoreResult<T> = Outcome<T, TaskStoreFailure>;
+export type OpenedTaskStore = OpenedMessageTask;
+export declare function openTaskStore(taskRoot: string): Promise<TaskStoreResult<OpenedTaskStore>>;
+/** Revalidate namespace identity and nested state immediately before apply. */
+export declare function assertTaskStoreCurrent(opened: OpenedTaskStore): Promise<TaskStoreFailure | null>;
+/** Domain-wide scan validation for `resource list` and `claim`. */
+export declare function validateDomainTaskState(domainRoot: string): TaskStoreFailure | null;
+/** Mutation-path validation for `claim` (the domain lock is never followed). */
+export declare function validateDomainMutationPaths(domainRoot: string): TaskStoreFailure | null;

package/dist/app/collab-task-store.js

@@ -0,0 +1,204 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertMessageTaskCurrent, openMessageTask, } from './collab-messages.js';
+import { abortedDir, brokenLocksDir, ledgerPath, lockPath, } from '../collab/store.js';
+import { isPathInside } from '../schemas/paths.js';
+class UnsafeNestedState extends Error {
+    code;
+    nextAction;
+    constructor(code, message, nextAction) {
+        super(message);
+        this.code = code;
+        this.nextAction = nextAction;
+        this.name = 'UnsafeNestedState';
+    }
+}
+function failure(error) {
+    return {
+        ok: false,
+        code: error.code,
+        message: error.message,
+        nextAction: error.nextAction,
+    };
+}
+const MISSING = new Set(['ENOENT', 'ENOTDIR']);
+function lstatOptional(file) {
+    try {
+        return fs.lstatSync(file);
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error
+            ? String(error.code)
+            : null;
+        if (code !== null && MISSING.has(code))
+            return null;
+        throw new UnsafeNestedState('task_state_unreadable', `Cannot inspect nested task state: ${file}`, 'Inspect permissions and the path; nothing was mutated.');
+    }
+}
+function requireRealDirectory(file, base, code) {
+    const stats = lstatOptional(file);
+    if (stats === null)
+        return;
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new UnsafeNestedState(code, `Nested task state is not a real directory: ${file}`, 'Restore a real directory; Pappra does not follow redirected state.');
+    }
+    const real = fs.realpathSync(file);
+    if (real !== file || !isPathInside(base, real)) {
+        throw new UnsafeNestedState(code, `Nested task state is redirected: ${file}`, 'Restore the real directory inside its task/domain root.');
+    }
+}
+function requireRealRegularFile(file, base, code, maxBytes) {
+    const stats = lstatOptional(file);
+    if (stats === null)
+        return;
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+        throw new UnsafeNestedState(code, `Nested task state is not a regular file: ${file}`, 'Restore a regular file; Pappra does not follow redirected state.');
+    }
+    if (maxBytes !== undefined && stats.size > maxBytes) {
+        throw new UnsafeNestedState(code, `Nested task state exceeds the supported size: ${file}`, 'Inspect the oversized nested state; nothing was read or mutated.');
+    }
+    const real = fs.realpathSync(file);
+    if (real !== file || !isPathInside(base, real)) {
+        throw new UnsafeNestedState(code, `Nested task state is redirected: ${file}`, 'Restore the real file inside its task/domain root.');
+    }
+}
+function inspectLockDirectory(taskRoot) {
+    const directory = lockPath(taskRoot);
+    const stats = lstatOptional(directory);
+    if (stats === null)
+        return;
+    requireRealDirectory(directory, taskRoot, 'task_lock_unsafe');
+    for (const name of fs.readdirSync(directory)) {
+        requireRealRegularFile(path.join(directory, name), taskRoot, 'task_transaction_unsafe', 8 * 1024 * 1024);
+    }
+}
+function inspectTaskPrivateState(taskRoot) {
+    inspectLockDirectory(taskRoot);
+    requireRealDirectory(abortedDir(taskRoot), taskRoot, 'task_aborted_unsafe');
+    requireRealDirectory(brokenLocksDir(taskRoot), taskRoot, 'task_broken_locks_unsafe');
+    requireRealRegularFile(ledgerPath(taskRoot), taskRoot, 'task_ledger_unsafe');
+}
+function inspectDomainLock(domainRoot) {
+    const directory = path.join(domainRoot, '.domain.lock');
+    const stats = lstatOptional(directory);
+    if (stats === null)
+        return;
+    requireRealDirectory(directory, domainRoot, 'domain_lock_unsafe');
+    for (const name of fs.readdirSync(directory)) {
+        requireRealRegularFile(path.join(directory, name), domainRoot, 'domain_lock_unsafe', 1024 * 1024);
+    }
+}
+/**
+ * Validate the neighboring task roots/records read by a domain-wide resource
+ * scan. Missing or malformed regular records remain unreadable evidence for the
+ * core; a symlinked root or record is a namespace redirect and is refused.
+ */
+function inspectDomainTasks(domainRoot) {
+    const tasksDirectory = path.join(domainRoot, 'tasks');
+    let names;
+    try {
+        names = fs.readdirSync(tasksDirectory).sort();
+    }
+    catch {
+        throw new UnsafeNestedState('task_state_unreadable', `Cannot inspect the domain tasks directory: ${tasksDirectory}`, 'Inspect permissions; nothing was mutated.');
+    }
+    for (const name of names) {
+        const taskRoot = path.join(tasksDirectory, name);
+        const stats = lstatOptional(taskRoot);
+        if (stats === null)
+            continue;
+        if (stats.isSymbolicLink()) {
+            throw new UnsafeNestedState('domain_state_redirected', `Neighboring task root is a symlink: ${taskRoot}`, 'Restore a real task root; Pappra does not follow redirected task state.');
+        }
+        if (!stats.isDirectory())
+            continue;
+        const realTask = fs.realpathSync(taskRoot);
+        if (realTask !== taskRoot || !isPathInside(tasksDirectory, realTask)) {
+            throw new UnsafeNestedState('domain_state_redirected', `Neighboring task root is redirected: ${taskRoot}`, 'Restore the real task root inside the domain.');
+        }
+        const record = path.join(taskRoot, 'task.json');
+        const recordStats = lstatOptional(record);
+        if (recordStats === null)
+            continue;
+        if (recordStats.isSymbolicLink() || !recordStats.isFile()) {
+            throw new UnsafeNestedState('domain_state_unsafe', `Neighboring task record is not a regular file: ${record}`, 'Restore a regular task record; redirected state is not scanned.');
+        }
+        const realRecord = fs.realpathSync(record);
+        if (realRecord !== record || !isPathInside(taskRoot, realRecord)) {
+            throw new UnsafeNestedState('domain_state_redirected', `Neighboring task record is redirected: ${record}`, 'Restore the real task record inside its task root.');
+        }
+    }
+}
+export async function openTaskStore(taskRoot) {
+    const opened = await openMessageTask(taskRoot);
+    if (!opened.ok)
+        return opened;
+    try {
+        inspectTaskPrivateState(opened.value.taskRoot);
+    }
+    catch (error) {
+        if (error instanceof UnsafeNestedState)
+            return failure(error);
+        return {
+            ok: false,
+            code: 'task_state_unreadable',
+            message: 'Nested task state could not be inspected.',
+            nextAction: 'Inspect the task lock, ledger and transaction paths; nothing was mutated.',
+        };
+    }
+    return opened;
+}
+/** Revalidate namespace identity and nested state immediately before apply. */
+export async function assertTaskStoreCurrent(opened) {
+    const changed = await assertMessageTaskCurrent(opened);
+    if (changed !== null)
+        return changed;
+    try {
+        inspectTaskPrivateState(opened.taskRoot);
+    }
+    catch (error) {
+        if (error instanceof UnsafeNestedState)
+            return failure(error);
+        return {
+            ok: false,
+            code: 'task_state_unreadable',
+            message: 'Nested task state could not be inspected.',
+            nextAction: 'Inspect the task lock, ledger and transaction paths; nothing was mutated.',
+        };
+    }
+    return null;
+}
+/** Domain-wide scan validation for `resource list` and `claim`. */
+export function validateDomainTaskState(domainRoot) {
+    try {
+        inspectDomainTasks(domainRoot);
+    }
+    catch (error) {
+        if (error instanceof UnsafeNestedState)
+            return failure(error);
+        return {
+            ok: false,
+            code: 'task_state_unreadable',
+            message: 'The domain task state could not be inspected.',
+            nextAction: 'Inspect the domain tasks directory and records; nothing was mutated.',
+        };
+    }
+    return null;
+}
+/** Mutation-path validation for `claim` (the domain lock is never followed). */
+export function validateDomainMutationPaths(domainRoot) {
+    try {
+        inspectDomainLock(domainRoot);
+    }
+    catch (error) {
+        if (error instanceof UnsafeNestedState)
+            return failure(error);
+        return {
+            ok: false,
+            code: 'task_state_unreadable',
+            message: 'The domain lock path could not be inspected.',
+            nextAction: 'Inspect the domain lock directory; nothing was mutated.',
+        };
+    }
+    return null;
+}

package/dist/app/collab-work-execution.d.ts

@@ -0,0 +1,127 @@
+import { type HerdrTransport } from './collab-notify.js';
+import type { Identity } from '../collab/types.js';
+export declare const COLLAB_WORK_EXECUTION_SCHEMA = "pappra/collab-work-execution/1";
+export interface WorkExecutionCardInput {
+    readonly assignment_id: string;
+    readonly capabilities_file: string;
+}
+export interface WorkExecutionRequest {
+    readonly task_root: string;
+    readonly plan_file: string;
+    readonly binding_file: string;
+    readonly caller: Identity & {
+        readonly cwd: string;
+    };
+    readonly caller_pane: string;
+    readonly capability_cards: readonly WorkExecutionCardInput[];
+    readonly max_concurrency?: number;
+}
+export interface WorkExecutionOptions {
+    readonly request: WorkExecutionRequest;
+    readonly apply: boolean;
+}
+export interface WorkExecutionDispatchRequest {
+    readonly taskRoot: string;
+    readonly messageId: string;
+    readonly bindingFile: string;
+    readonly callerPane: string;
+    readonly finalAuthorityCheck?: () => Promise<{
+        readonly ok: boolean;
+        readonly reason: string;
+    }>;
+}
+export interface WorkExecutionAdapter {
+    /** Read-only routing validation. It must never submit a notification. */
+    preflight(request: WorkExecutionDispatchRequest): Promise<WorkExecutionObservation>;
+    /** One notification attempt; unknown outcomes are never replayed by this layer. */
+    dispatch(request: WorkExecutionDispatchRequest): Promise<WorkExecutionObservation>;
+}
+export interface WorkExecutionObservation {
+    readonly ok: boolean;
+    readonly status: string;
+    readonly detail: string | null;
+    readonly delivery_path?: string | null;
+    readonly message_digest?: string | null;
+    readonly target_pane?: string | null;
+}
+export interface WorkExecutionNodeResult {
+    readonly node_id: string;
+    readonly role: string;
+    readonly assignment_id: string;
+    readonly attempt: number;
+    readonly input_revision: string;
+    readonly work_plan_status: string;
+    readonly execution_status: 'accepted' | 'awaiting_acceptance' | 'planned' | 'dispatched' | 'blocked' | 'reconciliation-required' | 'not-dispatchable';
+    readonly blockers: readonly string[];
+    readonly next_action: string | null;
+    readonly assignment: {
+        readonly ref: string | null;
+        readonly digest: string | null;
+    };
+    readonly capabilities: {
+        readonly ref: string | null;
+        readonly digest: string | null;
+    };
+    readonly intent_message_id: string | null;
+    readonly delivery: {
+        readonly status: string | null;
+        readonly message_digest: string | null;
+        readonly delivery_path: string | null;
+        readonly target_pane: string | null;
+    } | null;
+    readonly acceptance: 'accepted' | 'awaiting_acceptance' | 'rejected' | 'not-applicable';
+}
+export interface WorkExecutionReportPointer {
+    readonly node_id: string;
+    readonly assignment_id: string;
+    readonly attempt: number;
+    readonly status: string;
+    readonly message_id: string;
+    readonly digest: string;
+    readonly input_revision: string | null;
+    readonly evidence_ref: string | null;
+    readonly outputs: readonly {
+        readonly ref: string;
+        readonly digest: string;
+    }[];
+}
+export interface WorkExecutionReport {
+    readonly schema: typeof COLLAB_WORK_EXECUTION_SCHEMA;
+    readonly ok: boolean;
+    readonly status: 'planned' | 'applied' | 'blocked' | 'needs-reconciliation' | 'invalid';
+    readonly diagnostics: readonly string[];
+    readonly apply: boolean;
+    readonly task_root: string;
+    readonly task_id: string | null;
+    readonly plan: {
+        readonly ref: string;
+        readonly digest: string | null;
+        readonly plan_id: string | null;
+        readonly owner_epoch: number | null;
+    };
+    readonly concurrency: {
+        readonly limit: number;
+        readonly selected: number;
+        readonly actual_overlap: boolean;
+    };
+    readonly nodes: readonly WorkExecutionNodeResult[];
+    readonly reports: readonly WorkExecutionReportPointer[];
+    readonly acceptance: {
+        readonly accepted_nodes: readonly string[];
+        readonly awaiting_acceptance_nodes: readonly string[];
+        readonly rejected_nodes: readonly string[];
+    };
+    readonly limits: readonly string[];
+}
+export interface WorkExecutionHerdrAdapterOptions {
+    readonly transport?: HerdrTransport;
+}
+export declare function createHerdrWorkExecutionAdapter(options?: WorkExecutionHerdrAdapterOptions): WorkExecutionAdapter;
+/**
+ * Applies one bounded batch of already assigned work. Plan mode is read-only. Apply
+ * persists a deterministic STATUS_QUERY intent with the existing message transaction before
+ * one visible notification attempt; duplicate intents are reconciliation-only.
+ */
+export declare function runWorkExecution(options: WorkExecutionOptions, deps?: {
+    readonly adapter?: WorkExecutionAdapter;
+}): Promise<WorkExecutionReport>;