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

package/dist/continuity/context.js

@@ -0,0 +1,179 @@
+import { join } from 'node:path';
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/config.js';
+import { discoverRepositories } from '../workspace/repositories.js';
+import { runGit } from '../infra/git.js';
+import { observePath, readFileBounded, sha256Digest } from '../infra/fs.js';
+import { readlink } from 'node:fs/promises';
+import { isPathInside } from '../schemas/paths.js';
+import { CONTINUITY_PAYLOAD_MAX_BYTES } from './paths.js';
+const discoveryOptions = {
+    scanDepth: 0,
+    maxDirectories: 1,
+    maxDocuments: 1,
+    maxEntriesPerDirectory: 1,
+    gitTimeoutMs: 5_000,
+};
+export async function loadContinuityWorkspace(root) {
+    const config = await inspectWorkspaceConfig(root);
+    const diagnostics = [...config.diagnostics];
+    if (config.value === null) {
+        return { ok: false, workspace: null, diagnostics };
+    }
+    const machine = await inspectMachineConfig(config.root);
+    diagnostics.push(...machine.diagnostics);
+    const repositories = await discoverRepositories({
+        root: config.root,
+        config: config.value,
+        machine: machine.value,
+        configPath: config.path,
+        options: discoveryOptions,
+    });
+    diagnostics.push(...repositories.diagnostics);
+    return {
+        ok: true,
+        workspace: {
+            root: config.root,
+            config: config.value,
+            machine: machine.value,
+            repositories: repositories.repositories,
+            diagnostics,
+        },
+        diagnostics,
+    };
+}
+function repoId(repository, index) {
+    return (repository.id ?? (index === 0 ? 'workspace' : `workspace-${index + 1}`));
+}
+function repoScope(repository) {
+    return repository.external ? 'external' : 'workspace';
+}
+export async function snapshotRepository(workspace, repository, index) {
+    const status = await runGit({
+        cwd: repository.root,
+        args: [
+            'status',
+            '--porcelain=v1',
+            '--untracked-files=all',
+            '--',
+            '.',
+            ':(exclude).pappra/local',
+            ':(exclude).pappra/generated',
+        ],
+        timeoutMs: 5_000,
+        maxOutputBytes: 2 * 1024 * 1024,
+    });
+    const diff = await runGit({
+        cwd: repository.root,
+        args: [
+            'diff',
+            '--binary',
+            'HEAD',
+            '--',
+            '.',
+            ':(exclude).pappra/local',
+            ':(exclude).pappra/generated',
+        ],
+        timeoutMs: 5_000,
+        maxOutputBytes: 4 * 1024 * 1024,
+    });
+    const statusText = status.ok ? status.value.stdout : '';
+    const diffText = diff.ok ? diff.value.stdout : '';
+    const dirty = status.ok ? statusText.trim().length > 0 : repository.git.dirty;
+    let captureStatus = status.ok && diff.ok ? 'complete' : 'unknown';
+    let patchBytes = null;
+    if (dirty === true && status.ok && diff.ok) {
+        const statusBytes = Buffer.from(statusText, 'utf8');
+        const diffBytes = Buffer.from(diffText, 'utf8');
+        const parts = [
+            Buffer.from(`PAPPRA-UNTRACKED/2\nP ${statusBytes.length} ${diffBytes.length}\n`, 'utf8'),
+            statusBytes,
+            diffBytes,
+        ];
+        let total = parts.reduce((sum, part) => sum + part.length, 0);
+        if (total > CONTINUITY_PAYLOAD_MAX_BYTES) {
+            captureStatus = 'partial';
+        }
+        const untracked = statusText
+            .split('\n')
+            .filter((line) => line.startsWith('?? '))
+            .map((line) => line.slice(3));
+        for (const path of untracked) {
+            if (total > CONTINUITY_PAYLOAD_MAX_BYTES)
+                break;
+            const absolute = join(repository.root, path);
+            if (!isPathInside(repository.root, absolute)) {
+                captureStatus = 'partial';
+                continue;
+            }
+            const observation = await observePath(absolute).catch(() => null);
+            if (observation === null) {
+                captureStatus = 'partial';
+                continue;
+            }
+            let body;
+            let entryKind;
+            if (observation.kind === 'file') {
+                const read = await readFileBounded(absolute, CONTINUITY_PAYLOAD_MAX_BYTES);
+                if (!read.ok) {
+                    captureStatus = 'partial';
+                    continue;
+                }
+                body = read.value.bytes;
+                entryKind = 'F';
+            }
+            else if (observation.kind === 'symlink') {
+                const target = await readlink(absolute).catch(() => null);
+                if (target === null) {
+                    captureStatus = 'partial';
+                    continue;
+                }
+                body = Buffer.from(target, 'utf8');
+                entryKind = 'L';
+            }
+            else {
+                captureStatus = 'partial';
+                continue;
+            }
+            const pathBytes = Buffer.from(path, 'utf8');
+            // F/L is part of the identity: a regular file body and a symlink target
+            // with identical bytes are still different source objects. The target
+            // text is read with readlink and never resolved or opened.
+            const header = Buffer.from(`${entryKind} ${pathBytes.length} ${body.length}\n`, 'utf8');
+            if (total + header.length + pathBytes.length + body.length >
+                CONTINUITY_PAYLOAD_MAX_BYTES) {
+                captureStatus = 'partial';
+                break;
+            }
+            parts.push(header, pathBytes, body);
+            total += header.length + pathBytes.length + body.length;
+        }
+        patchBytes = Buffer.concat(parts);
+    }
+    const patchDigest = patchBytes === null ? null : sha256Digest(patchBytes);
+    const checkoutId = workspace.machine?.checkoutId ?? sha256Digest(repository.root);
+    return {
+        record: {
+            repoId: repoId(repository, index),
+            checkoutId,
+            root: repository.root,
+            head: repository.git.head,
+            branch: repository.git.branch,
+            dirty,
+            patchDigest,
+            captureStatus,
+            scope: repoScope(repository),
+        },
+        patchBytes,
+    };
+}
+export function continuityDiagnostic(message, source, hint) {
+    return createDiagnostic({
+        code: diagnosticCodes.document_path_unsafe,
+        severity: 'error',
+        message,
+        source,
+        hint,
+    });
+}

package/dist/continuity/index.d.ts

@@ -0,0 +1,3 @@
+export { CheckpointService } from './service.js';
+export type { ContinuityServiceOptions, NativeRefInput, ResumeCheckpointInput, ResumeCheckpointResult, SaveCheckpointInput, SaveCheckpointResult, ValidationInput, } from './service.js';
+export type { Checkpoint, CheckpointPointer, ResumePacket, TaskContext, } from '../schemas/continuity.js';

package/dist/continuity/index.js

@@ -0,0 +1 @@
+export { CheckpointService } from './service.js';

package/dist/continuity/paths.d.ts

@@ -0,0 +1,37 @@
+import type { Outcome } from '../schemas/outcome.js';
+/**
+ * Shared bound for private recovery payloads. Capture, durable writes and
+ * resume reads all use this value; a payload over the bound is captured only
+ * partially and must never be reported as complete.
+ */
+export declare const CONTINUITY_PAYLOAD_MAX_BYTES: number;
+export interface ContinuityWriteOptions {
+    /** Test/fault-injection seam immediately before an exclusive publication. */
+    readonly beforeExclusivePublish?: () => Promise<void>;
+}
+export interface ContinuityTaskPaths {
+    readonly taskDir: string;
+    readonly contextPath: string;
+    readonly latestPath: string;
+    readonly checkpointsDir: string;
+    readonly patchesDir: string;
+    readonly lockPath: string;
+}
+export declare function continuityTaskPaths(root: string, taskId: string): ContinuityTaskPaths;
+export declare function ensureContinuityBoundary(root: string, path: string): Promise<Outcome<null>>;
+export declare function ensurePrivateTaskBoundary(root: string, taskId: string, path: string): Promise<Outcome<null>>;
+export declare function writeContinuityBytes(root: string, taskId: string, path: string, bytes: Buffer, exclusive: boolean, options?: ContinuityWriteOptions): Promise<Outcome<{
+    readonly digest: string;
+}>>;
+/**
+ * Replaces a file only if its current bytes still have the expected digest.
+ * The comparison happens after the temporary bytes are durable and immediately
+ * before rename; it is cooperative CAS, not a filesystem-wide transaction.
+ */
+export declare function replaceContinuityBytesIfDigest(root: string, taskId: string, path: string, bytes: Buffer, expectedDigest: string | null): Promise<Outcome<{
+    readonly digest: string;
+}>>;
+export declare function readContinuityText(root: string, taskId: string, path: string): Promise<Outcome<string>>;
+export declare function readContinuityBytes(root: string, taskId: string, path: string): Promise<Outcome<Buffer>>;
+export declare function removeContinuityFile(root: string, taskId: string, path: string): Promise<void>;
+export declare function readArtifactPath(root: string, artifactPath: string): Promise<Outcome<string>>;

package/dist/continuity/paths.js

@@ -0,0 +1,258 @@
+import { randomUUID } from 'node:crypto';
+import { link, mkdir, open, rename, rm, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { errorMessage, failed, succeeded } from '../schemas/outcome.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { isPathInside, resolvePortableRelativePath, samePath, } from '../schemas/paths.js';
+import { observePath, readFileBounded, readTextFileBounded, resolveRealpath, sha256Digest, } from '../infra/fs.js';
+import { resolveWorkspaceRoot } from '../workspace/resolve.js';
+const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Shared bound for private recovery payloads. Capture, durable writes and
+ * resume reads all use this value; a payload over the bound is captured only
+ * partially and must never be reported as complete.
+ */
+export const CONTINUITY_PAYLOAD_MAX_BYTES = 16 * 1024 * 1024;
+export function continuityTaskPaths(root, taskId) {
+    if (!TASK_ID.test(taskId) || taskId.length > 64) {
+        throw new RangeError(`Invalid task id: ${taskId}`);
+    }
+    const taskDir = join(root, '.pappra', 'local', 'tasks', taskId);
+    return {
+        taskDir,
+        contextPath: join(taskDir, 'task-context.json'),
+        latestPath: join(taskDir, 'latest.json'),
+        checkpointsDir: join(taskDir, 'checkpoints'),
+        patchesDir: join(taskDir, 'patches'),
+        lockPath: join(taskDir, 'checkpoint.lock'),
+    };
+}
+async function checkCanonicalAncestor(realRoot, target, path) {
+    let current = path;
+    for (;;) {
+        let observation;
+        try {
+            observation = await observePath(current);
+        }
+        catch (error) {
+            return failed(diagnosticCodes.fileUnreadable, `Cannot inspect continuity path ${current}: ${errorMessage(error)}`, {
+                nextAction: 'Inspect permissions; no private state was read or written.',
+            });
+        }
+        if (observation.kind !== 'missing') {
+            const isFinal = samePath(current, path);
+            if (observation.kind === 'symlink') {
+                return failed(diagnosticCodes.document_path_unsafe, `Continuity path is a symlink: ${current}`, {
+                    nextAction: 'Use regular private state files; symlinked continuity state is not followed.',
+                });
+            }
+            if (!isFinal && observation.kind !== 'directory') {
+                return failed(diagnosticCodes.document_path_unsafe, `Continuity parent is not a directory: ${current}`, {
+                    nextAction: 'Inspect the private task directory; no write was made.',
+                });
+            }
+            const real = await resolveRealpath(current);
+            if (real === null ||
+                !isPathInside(realRoot, real) ||
+                (!isPathInside(real, target) && !isPathInside(target, real))) {
+                return failed(diagnosticCodes.document_path_unsafe, `Continuity path resolves outside the private task namespace: ${current}`, {
+                    nextAction: 'Inspect or remove the redirected state path explicitly; Pappra does not repair it.',
+                });
+            }
+            return succeeded(null);
+        }
+        const parent = dirname(current);
+        if (samePath(parent, current)) {
+            return failed(diagnosticCodes.document_path_unsafe, `Cannot find an existing ancestor for ${path}`, { nextAction: 'Use a workspace-local private task directory.' });
+        }
+        current = parent;
+    }
+}
+export async function ensureContinuityBoundary(root, path) {
+    if (!isPathInside(root, path)) {
+        return failed(diagnosticCodes.document_path_unsafe, `Continuity path escapes workspace: ${path}`, {
+            nextAction: 'Use only the private task directory and current workspace.',
+        });
+    }
+    const realRoot = await resolveRealpath(root);
+    if (realRoot === null) {
+        return failed(diagnosticCodes.document_path_unsafe, `Cannot resolve workspace root: ${root}`, { nextAction: 'Use an existing readable workspace root.' });
+    }
+    const current = await resolveRealpath(path);
+    if (current !== null) {
+        return isPathInside(realRoot, current)
+            ? succeeded(null)
+            : failed(diagnosticCodes.document_path_unsafe, `Continuity path resolves outside workspace: ${path}`, { nextAction: 'Inspect symlinked state paths; no write was made.' });
+    }
+    return checkCanonicalAncestor(realRoot, path, path);
+}
+export async function ensurePrivateTaskBoundary(root, taskId, path) {
+    const paths = continuityTaskPaths(root, taskId);
+    if (!isPathInside(paths.taskDir, path)) {
+        return failed(diagnosticCodes.document_path_unsafe, `Continuity path is outside the private task directory: ${path}`, {
+            nextAction: 'Use only .pappra/local/tasks/<taskId> for checkpoints, pointers and patches.',
+        });
+    }
+    const realRoot = await resolveRealpath(root);
+    if (realRoot === null) {
+        return failed(diagnosticCodes.document_path_unsafe, `Cannot resolve workspace root: ${root}`, { nextAction: 'Use an existing readable workspace root.' });
+    }
+    const canonicalTask = join(realRoot, '.pappra', 'local', 'tasks', taskId);
+    return checkCanonicalAncestor(realRoot, canonicalTask, path);
+}
+async function writeTemporary(path, bytes) {
+    const temporary = `${path}.tmp-${randomUUID()}`;
+    try {
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        return { ok: true, temporary };
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        return {
+            ok: false,
+            message: `Cannot write continuity file ${path}: ${errorMessage(error)}`,
+        };
+    }
+}
+function errorCode(error) {
+    return typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string'
+        ? error.code
+        : null;
+}
+export async function writeContinuityBytes(root, taskId, path, bytes, exclusive, options = {}) {
+    const boundary = await ensurePrivateTaskBoundary(root, taskId, path);
+    if (!boundary.ok)
+        return boundary;
+    const temporary = await writeTemporary(path, bytes);
+    if (!temporary.ok) {
+        return failed(diagnosticCodes.fileUnreadable, temporary.message, {
+            nextAction: 'Inspect permissions and available disk space; no success was claimed.',
+        });
+    }
+    try {
+        if (exclusive) {
+            await options.beforeExclusivePublish?.();
+            // link(2) publishes atomically and fails with EEXIST if any target,
+            // including a concurrently created one, already exists. A precheck
+            // followed by rename would replace that target.
+            try {
+                await link(temporary.temporary, path);
+            }
+            catch (error) {
+                if (errorCode(error) === 'EEXIST') {
+                    return failed(diagnosticCodes.document_write_conflict, `Continuity target already exists: ${path}`, {
+                        nextAction: 'Use a fresh checkpoint revision; existing state is never replaced.',
+                    });
+                }
+                return failed(diagnosticCodes.fileUnreadable, `Cannot publish exclusive continuity file ${path}: ${errorMessage(error)}`, {
+                    nextAction: 'Use a filesystem that supports atomic no-replace publication; no fallback replaced the target.',
+                });
+            }
+            return succeeded({ digest: sha256Digest(bytes) });
+        }
+        await rename(temporary.temporary, path);
+        return succeeded({ digest: sha256Digest(bytes) });
+    }
+    catch (error) {
+        return failed(diagnosticCodes.fileUnreadable, `Cannot commit continuity file ${path}: ${errorMessage(error)}`, { nextAction: 'Inspect permissions; no success was claimed.' });
+    }
+    finally {
+        await rm(temporary.temporary, { force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Replaces a file only if its current bytes still have the expected digest.
+ * The comparison happens after the temporary bytes are durable and immediately
+ * before rename; it is cooperative CAS, not a filesystem-wide transaction.
+ */
+export async function replaceContinuityBytesIfDigest(root, taskId, path, bytes, expectedDigest) {
+    const boundary = await ensurePrivateTaskBoundary(root, taskId, path);
+    if (!boundary.ok)
+        return boundary;
+    const temporary = await writeTemporary(path, bytes);
+    if (!temporary.ok) {
+        return failed(diagnosticCodes.fileUnreadable, temporary.message, {
+            nextAction: 'Inspect permissions and available disk space; no success was claimed.',
+        });
+    }
+    try {
+        const current = await readFileBounded(path, CONTINUITY_PAYLOAD_MAX_BYTES);
+        const currentDigest = current.ok ? current.value.digest : null;
+        if ((!current.ok && current.code !== diagnosticCodes.fileNotFound) ||
+            currentDigest !== expectedDigest) {
+            return failed(current.ok || current.code === diagnosticCodes.fileNotFound
+                ? diagnosticCodes.document_proposal_stale
+                : current.code, `Continuity file changed before commit: ${path}`, {
+                nextAction: 'Reload the pointer and retry explicitly; concurrent bytes were preserved.',
+            });
+        }
+        await rename(temporary.temporary, path);
+        return succeeded({ digest: sha256Digest(bytes) });
+    }
+    catch (error) {
+        return failed(diagnosticCodes.fileUnreadable, `Cannot commit continuity file ${path}: ${errorMessage(error)}`, { nextAction: 'Inspect permissions; no success was claimed.' });
+    }
+    finally {
+        await rm(temporary.temporary, { force: true }).catch(() => undefined);
+    }
+}
+export async function readContinuityText(root, taskId, path) {
+    const boundary = await ensurePrivateTaskBoundary(root, taskId, path);
+    if (!boundary.ok)
+        return boundary;
+    const read = await readTextFileBounded(path);
+    return read.ok ? succeeded(read.value.text) : read;
+}
+export async function readContinuityBytes(root, taskId, path) {
+    const boundary = await ensurePrivateTaskBoundary(root, taskId, path);
+    if (!boundary.ok)
+        return boundary;
+    const read = await readFileBounded(path, CONTINUITY_PAYLOAD_MAX_BYTES);
+    return read.ok ? succeeded(read.value.bytes) : read;
+}
+export async function removeContinuityFile(root, taskId, path) {
+    const boundary = await ensurePrivateTaskBoundary(root, taskId, path);
+    if (!boundary.ok)
+        return;
+    await unlink(path).catch(() => undefined);
+}
+export async function readArtifactPath(root, artifactPath) {
+    let absolute;
+    try {
+        absolute = artifactPath.startsWith('/')
+            ? artifactPath
+            : resolvePortableRelativePath(root, artifactPath);
+    }
+    catch {
+        return failed(diagnosticCodes.document_path_unsafe, `Invalid artifact path: ${artifactPath}`, { nextAction: 'Use a workspace-relative artifact path.' });
+    }
+    if (!isPathInside(root, absolute)) {
+        return failed(diagnosticCodes.document_path_unsafe, `Artifact path escapes workspace: ${artifactPath}`, { nextAction: 'Keep checkpoint artifacts inside the workspace.' });
+    }
+    const boundary = await ensureContinuityBoundary(root, absolute);
+    if (!boundary.ok)
+        return boundary;
+    const resolution = await resolveWorkspaceRoot({
+        startPath: dirname(absolute),
+    });
+    const realRoot = await resolveRealpath(root);
+    const realNested = resolution.root === null ? null : await resolveRealpath(resolution.root);
+    if (resolution.state === 'registered' &&
+        realNested !== null &&
+        realRoot !== null &&
+        !samePath(realNested, realRoot)) {
+        return failed(diagnosticCodes.document_nested_workspace, `Artifact is inside nested workspace ${resolution.root}: ${artifactPath}`, { nextAction: 'Use an artifact from the current workspace.' });
+    }
+    return succeeded(absolute);
+}

package/dist/continuity/service.d.ts

@@ -0,0 +1,59 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import { type Checkpoint, type ResumePacket } from '../schemas/continuity.js';
+export interface NativeRefInput {
+    readonly harness: 'pi' | 'codex' | 'claude' | 'unknown';
+    readonly sessionId?: string | null;
+    readonly turnId?: string | null;
+    readonly runId?: string | null;
+}
+export interface ValidationInput {
+    readonly id: string;
+    readonly result: 'passed' | 'failed' | 'not-run' | 'unknown';
+    readonly inputVersion?: string | null;
+}
+export interface SaveCheckpointInput {
+    readonly taskId: string;
+    readonly objective?: string;
+    readonly acceptance?: readonly string[];
+    readonly constraints?: readonly string[];
+    readonly artifacts?: readonly string[];
+    readonly collaborationRecordRef?: string | null;
+    readonly decisions?: readonly string[];
+    readonly attempted?: readonly string[];
+    readonly nextActions?: readonly string[];
+    readonly limitations?: readonly string[];
+    readonly contextCompleteness?: 'complete' | 'partial';
+    readonly authorSession?: string | null;
+    readonly nativeRefs?: readonly NativeRefInput[];
+    readonly validations?: readonly ValidationInput[];
+}
+export interface SaveCheckpointResult {
+    readonly ok: boolean;
+    readonly status: 'saved' | 'partial' | 'conflict' | 'failed';
+    readonly checkpoint: Checkpoint | null;
+    readonly checkpointPath: string | null;
+    readonly latestPath: string | null;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly residualPaths: readonly string[];
+}
+export interface ResumeCheckpointInput {
+    readonly taskId: string;
+    readonly currentSession?: string | null;
+}
+export interface ResumeCheckpointResult {
+    readonly ok: boolean;
+    readonly status: 'ready' | 'blocked' | 'not-found' | 'invalid' | 'failed';
+    readonly packet: ResumePacket | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface ContinuityServiceOptions {
+    /** Test seam: runs after checkpoint bytes are durable, before latest pointer. */
+    readonly beforeLatestPointerPersist?: () => Promise<void> | void;
+}
+export declare class CheckpointService {
+    #private;
+    readonly root: string;
+    constructor(root: string, options?: ContinuityServiceOptions);
+    save(input: SaveCheckpointInput): Promise<SaveCheckpointResult>;
+    resume(input: ResumeCheckpointInput): Promise<ResumeCheckpointResult>;
+}