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

package/dist/code/text.js

@@ -0,0 +1,202 @@
+import { join } from 'node:path';
+import { runGit } from '../infra/git.js';
+import { observePath, readFileBounded, sha256Digest } from '../infra/fs.js';
+import { isPathInside } from '../schemas/paths.js';
+import { ensureCodeMutationBoundary } from './registration.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { failed, succeeded } from '../schemas/outcome.js';
+import { boundCodeItems } from './budget.js';
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_FILE_COUNT = 5000;
+const EXCLUDES = [
+    ':(exclude).codegraph',
+    ':(exclude).pappra/local',
+    ':(exclude).pappra/generated',
+];
+function lineAt(text, offset) {
+    const before = text.slice(0, offset);
+    const lines = before.split('\n');
+    return {
+        line: lines.length,
+        column: (lines[lines.length - 1]?.length ?? 0) + 1,
+    };
+}
+function snippetAt(text, offset, length) {
+    const start = Math.max(0, offset - 120);
+    const end = Math.min(text.length, offset + length + 160);
+    return text.slice(start, end).replace(/\s+/g, ' ').trim().slice(0, 4096);
+}
+function normalizeRelative(path) {
+    const normalized = path.replaceAll('\\', '/');
+    if (normalized.length === 0 ||
+        normalized.startsWith('/') ||
+        normalized.split('/').some((part) => part === '..' || part === '')) {
+        return null;
+    }
+    return normalized;
+}
+function evidenceFor(root, path, bytes) {
+    return {
+        kind: 'file',
+        ref: join(root, path),
+        digest: sha256Digest(bytes),
+        observedAt: new Date().toISOString(),
+        scope: 'live-owned',
+    };
+}
+function structureMatches(text, query) {
+    const items = [];
+    const pattern = /(?:^|\n)\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|const|let|var)\s+([A-Za-z_$][\w$]*)/g;
+    for (const match of text.matchAll(pattern)) {
+        const name = match[1];
+        if (name === undefined ||
+            !name.toLowerCase().includes(query.toLowerCase())) {
+            continue;
+        }
+        const offset = match.index ?? 0;
+        const location = lineAt(text, offset);
+        items.push({
+            path: '',
+            line: location.line,
+            column: location.column,
+            kind: 'symbol',
+            name,
+            snippet: snippetAt(text, offset, match[0].length),
+            source: 'structure',
+        });
+    }
+    return items;
+}
+export async function runTextQuery(request, mode, signal) {
+    const root = request.identity.root;
+    const protectedRoots = [
+        join(root, '.pappra', 'local'),
+        join(root, '.pappra', 'generated'),
+        ...(request.excludedRoots ?? []),
+    ];
+    const list = await runGit({
+        cwd: root,
+        args: [
+            'ls-files',
+            '--cached',
+            '--others',
+            '--exclude-standard',
+            '-z',
+            '--',
+            '.',
+            ...EXCLUDES,
+        ],
+        timeoutMs: 10_000,
+        maxOutputBytes: 2 * 1024 * 1024,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (!list.ok) {
+        return failed(diagnosticCodes.code_query_invalid, `Cannot list selected repository files: ${list.message}`, { nextAction: 'Inspect Git availability and the selected repository.' });
+    }
+    const paths = [...new Set(list.value.stdout.split('\0').filter(Boolean))]
+        .map(normalizeRelative)
+        .filter((path) => path !== null)
+        .slice(0, Math.min(request.limits.maxFiles, MAX_FILE_COUNT));
+    const items = [];
+    const evidence = [];
+    const reasons = [];
+    let bytes = 0;
+    let truncated = list.value.stdout.split('\0').filter(Boolean).length > paths.length;
+    for (const path of paths) {
+        if (items.length >= request.limits.maxResults ||
+            bytes >= request.limits.maxBytes) {
+            truncated = true;
+            break;
+        }
+        const absolute = join(root, path);
+        if (!isPathInside(root, absolute)) {
+            reasons.push('path_unsafe');
+            continue;
+        }
+        if ((request.excludedRoots ?? []).some((excluded) => isPathInside(excluded, absolute))) {
+            continue;
+        }
+        const boundary = await ensureCodeMutationBoundary(root, absolute, protectedRoots);
+        if (!boundary.ok) {
+            reasons.push('canonical_path_unsafe');
+            continue;
+        }
+        const observation = await observePath(absolute).catch(() => null);
+        if (observation === null || observation.kind !== 'file') {
+            reasons.push('non_regular_skipped');
+            continue;
+        }
+        const read = await readFileBounded(absolute, MAX_FILE_BYTES);
+        if (!read.ok) {
+            reasons.push('file_unreadable_or_large');
+            continue;
+        }
+        if (read.value.bytes.includes(0)) {
+            reasons.push('binary_skipped');
+            continue;
+        }
+        bytes += read.value.size;
+        if (bytes > request.limits.maxBytes) {
+            bytes = request.limits.maxBytes;
+            truncated = true;
+            break;
+        }
+        const text = read.value.bytes.toString('utf8');
+        if (mode === 'text') {
+            const lower = text.toLowerCase();
+            const needle = request.query.toLowerCase();
+            let offset = lower.indexOf(needle);
+            while (offset !== -1 && items.length < request.limits.maxResults) {
+                const location = lineAt(text, offset);
+                items.push({
+                    path,
+                    line: location.line,
+                    column: location.column,
+                    kind: 'text',
+                    name: null,
+                    snippet: snippetAt(text, offset, request.query.length),
+                    source: 'text',
+                });
+                offset = lower.indexOf(needle, offset + Math.max(1, needle.length));
+            }
+            if (offset !== -1)
+                truncated = true;
+        }
+        else {
+            const matches = structureMatches(text, request.query);
+            for (const match of matches) {
+                if (items.length >= request.limits.maxResults) {
+                    truncated = true;
+                    break;
+                }
+                items.push({ ...match, path });
+            }
+        }
+        if (items.some((item) => item.path === path)) {
+            evidence.push(evidenceFor(root, path, read.value.bytes));
+        }
+    }
+    const bounded = boundCodeItems(items, request.limits.maxBytes, request.limits.maxResults, request.limits.maxFiles);
+    const includedEvidence = new Set(bounded.items.map((item) => join(root, item.path)));
+    return succeeded({
+        schema: 'pappra/code-query-result/1',
+        provider: mode,
+        kind: request.kind,
+        query: request.query,
+        identityDigest: sha256Digest(JSON.stringify(request.identity)),
+        observedIdentity: request.identity,
+        coverage: truncated || bounded.truncated || reasons.length > 0
+            ? 'partial'
+            : 'fallback',
+        items: bounded.items,
+        bytes: bounded.bytes,
+        truncated: truncated || bounded.truncated,
+        reasons: [...new Set([...reasons, ...bounded.reasons])].slice(0, 16),
+        evidence: evidence
+            .filter((entry) => includedEvidence.has(entry.ref))
+            .slice(0, 32),
+        unsupportedReason: mode === 'structure'
+            ? 'Structural fallback is a bounded declaration scan, not a semantic symbol index.'
+            : 'Text fallback scans bounded working-tree files, not the CodeGraph index.',
+    });
+}

package/dist/collab/admission.d.ts

@@ -0,0 +1,450 @@
+import type { TaskRecord, Resource, ReservationInput } from './types.js';
+export interface AdmissionOptions {
+    assignmentFile: string;
+    capabilitiesFile: string;
+    taskRoot: string;
+    cwd: string;
+    sessionId?: string | null;
+    harness?: string | null;
+    profile?: string | null;
+    launchKind?: string;
+    discovery?: boolean;
+    resumeSelector?: string | null;
+    now?: number;
+    maxAgeMinutes?: number;
+}
+export interface SettleOptions {
+    reservationId: string;
+    outcome: string;
+    exitCode?: number | null;
+    sessionId?: string | null;
+    runId?: string | null;
+    evidenceRef?: string | null;
+    runner?: string | null;
+    detail?: string | null;
+    expectedIdentity?: string | null;
+    capabilityEvidence?: string | null;
+    identityStatus?: string | null;
+    cleanExit?: boolean;
+    clock?: number;
+}
+export declare const TOOL_PROFILES: {
+    pi: {
+        writer: string;
+        reviewer: string;
+    };
+    claude: {
+        writer: string;
+        reviewer: string;
+    };
+};
+/**
+ * Pre-dispatch admission. A launcher that started a native process without checking the
+ * assignment, the capability snapshot, the collaboration record and the actual resource
+ * ownership would be an automatic entry that bypasses the whole contract, so it refuses.
+ *
+ * Two modes exist:
+ *   work       the default; requires a runtime-ready capability card
+ *   discovery  the restricted path that produces the first runtime observation; it may use a
+ *              declared card but must require no capability at all, so it cannot claim
+ *              anything it has not observed
+ */
+export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot, cwd, sessionId, harness, profile, launchKind, discovery, resumeSelector, now, maxAgeMinutes, }: AdmissionOptions): {
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    expected: string;
+    actual: string;
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    detail: string;
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    expected?: never;
+    actual?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    expected?: never;
+    actual?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    expected: number;
+    actual: number;
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    expected: import("./types.js").Identity;
+    actual: import("./types.js").Identity & {
+        harness: string;
+        cwd: string;
+        surface: string;
+        configuration_id: string;
+    };
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    expected: string;
+    actual: string;
+    detail: string;
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    required_skills: number;
+    required_tools: number;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    expected?: never;
+    actual?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    required_skills?: never;
+    required_tools?: never;
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    preflight: {
+        status: string;
+        errors: string[];
+        blockers: never[];
+        warnings: never[];
+        task_id?: never;
+        assignment_id?: never;
+        attempt?: never;
+        checked_at?: never;
+        limits?: never;
+    } | {
+        status: string;
+        task_id: string;
+        assignment_id: string;
+        attempt: number;
+        checked_at: string;
+        errors: never[];
+        blockers: import("./preflight.js").Check[];
+        warnings: import("./preflight.js").Check[];
+        limits: string[];
+    };
+    state?: never;
+    detail?: never;
+    expected?: never;
+    actual?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    state: string;
+    detail?: never;
+    expected?: never;
+    actual?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    expected: (string | null)[];
+    actual: string;
+    detail?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    resources?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    resources: Record<string, unknown>[];
+    detail: string;
+    expected?: never;
+    actual?: never;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    resources: Record<string, unknown>[];
+    expected: number | undefined;
+    actual: number;
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    expected?: never;
+    actual?: never;
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    resources: Record<string, unknown>[];
+    state_revision?: never;
+    owner_epoch?: never;
+    attempt_state?: never;
+    mode?: never;
+    launch_kind?: never;
+    resume_selector?: never;
+    pre_bound_identity?: never;
+    expected_identity?: never;
+    capability_evidence?: never;
+    assignment_digest?: never;
+    input_revision?: never;
+} | {
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
+    state?: never;
+    detail?: never;
+    expected?: never;
+    actual?: never;
+    reason?: never;
+    ok: true;
+    checks: Record<string, unknown>[];
+    state_revision: number;
+    owner_epoch: number | null;
+    attempt_state: string;
+    resources: Record<string, unknown>[];
+    mode: string;
+    launch_kind: string;
+    resume_selector: string | null;
+    pre_bound_identity: string | null;
+    expected_identity: string | null;
+    capability_evidence: string;
+    assignment_digest: string;
+    input_revision: string | null;
+};
+/** True when an existing claim covers the requested range (claim is equal to or above it). */
+export declare function hasPendingCancellation(record: TaskRecord, subtaskId: string, attempt: number): boolean;
+export declare function claimCovers(claim: Resource, requested: Resource): boolean;
+/**
+ * Atomically reserve the launch. A second launcher cannot reserve the same attempt, and the
+ * reservation distinguishes a first launch from a continuation, so "already started" is a
+ * recorded fact rather than an assumption.
+ */
+export declare function reserveLaunch(taskRoot: string, { reservation, expectRevision, clock, }: {
+    reservation: ReservationInput;
+    expectRevision?: number;
+    clock?: number;
+}): {
+    [key: string]: unknown;
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    reservation_id: string;
+    state_revision: number;
+};
+/**
+ * Settle a launch reservation and persist what actually happened.
+ *
+ * Outcomes are deliberately distinguished:
+ *   exited / exited_nonzero  the process ran; the attempt keeps a recorded native run, so a
+ *                            later `first` launch is refused with `already_launched`
+ *   timed_out / spawn_failed the process may be alive or may have started; the attempt moves to
+ *                            `unknown` with an uncertainty, so nothing may be dispatched over it
+ *                            until it is reconciled
+ *   not_started              nothing was spawned (a validation failure); the reservation is
+ *                            released and the attempt is left exactly as it was
+ */
+export declare function classifyIdentity({ ran, observed, expected, capabilityEvidence, }: {
+    ran: boolean;
+    observed?: string | null;
+    expected?: string | null;
+    capabilityEvidence?: string | null;
+}): {
+    status: string;
+    confirmed: boolean;
+};
+export declare function settleLaunch(taskRoot: string, { reservationId, outcome, exitCode, sessionId, runId, evidenceRef, runner, detail, expectedIdentity, capabilityEvidence, identityStatus, cleanExit, clock, }: SettleOptions): {
+    [key: string]: unknown;
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    outcome: string;
+    result: Record<string, unknown> | null;
+};