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

package/dist/app/capability-evidence/shared.d.ts

@@ -0,0 +1,69 @@
+import type { Assignment, Capability, CapabilityCard } from '../../collab/contracts.js';
+export declare const MAX_NATIVE_EVIDENCE_BYTES: number;
+export declare const MAX_ASSIGNMENT_BYTES: number;
+export declare const MAX_EVENTS = 20000;
+export declare class EvidenceError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function fail(code: string): never;
+export interface EvidenceFile {
+    readonly bytes: Buffer;
+    readonly text: string;
+    readonly digest: string;
+}
+/**
+ * Read one native evidence file. The bounded loader refuses final symlinks and
+ * special entries without blocking and enforces descriptor-level type and size.
+ */
+export declare function readNativeEvidence(file: string): EvidenceFile;
+export declare function parseExecution(text: string): Record<string, unknown>;
+export declare function record(value: unknown): value is Record<string, unknown>;
+export declare function digestOf(bytes: Buffer): string;
+export declare function evidenceRecords(evidenceFile: EvidenceFile, evidenceRef: string, executionFile: EvidenceFile, executionRef: string): {
+    ref: string;
+    digest: string;
+}[];
+export declare function isTimestamp(value: unknown): boolean;
+/**
+ * Interpret one recorded Pi timestamp. A message-level value is numeric Unix
+ * milliseconds; a record-level value is an explicit-zone ISO string. Numeric
+ * strings are not accepted as a substitute for either form.
+ */
+export declare function piTimestamp(value: unknown): number | null;
+export declare function samePath(left: unknown, right: unknown): boolean;
+export declare function realPath(value: string): string;
+export declare function argumentStrings(value: unknown, found?: string[]): string[];
+export declare function payloadStrings(item: unknown): string[];
+/** Assert the template still claims exactly the assignment's assignee identity. */
+export declare function assertTemplateIdentity(assignment: Assignment, template: CapabilityCard, harness: string): void;
+export interface SkillSnapshot {
+    readonly entry: string;
+    readonly directory: string;
+    readonly bundleDigest: string;
+}
+/**
+ * Reproduce the maintained fingerprint check: the template's pinned digest must
+ * still describe the selected skill before evidence can promote it.
+ */
+export declare function fingerprintTemplateSkill(skill: Capability): SkillSnapshot;
+export type CapabilityDerivation = {
+    readonly status: 'derived';
+    readonly card: CapabilityCard;
+    readonly limitations?: readonly string[];
+} | {
+    readonly status: 'needs_input';
+    readonly blockers: readonly string[];
+} | {
+    readonly status: 'invalid';
+    readonly blockers: readonly string[];
+};
+/**
+ * Validate the pinned contract/template and translate adapter failures into the
+ * maintained outcome shapes. A derived card remains a claim derived from the
+ * supplied evidence; nothing here authenticates, launches or dispatches.
+ */
+export declare function deriveOutcome(assignment: Assignment, template: CapabilityCard, work: () => {
+    readonly card: CapabilityCard;
+    readonly limitations?: readonly string[];
+}): CapabilityDerivation;

package/dist/app/capability-evidence/shared.js

@@ -0,0 +1,195 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fingerprintSkill } from '../../collab/fingerprint.js';
+import { validateContractAndCard } from '../../collab/preflight.js';
+import { readBoundedFile } from '../bounded-file.js';
+export const MAX_NATIVE_EVIDENCE_BYTES = 16 * 1024 * 1024;
+export const MAX_ASSIGNMENT_BYTES = 1024 * 1024;
+export const MAX_EVENTS = 20000;
+export class EvidenceError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'EvidenceError';
+    }
+}
+export function fail(code) {
+    throw new EvidenceError(code);
+}
+/**
+ * Read one native evidence file. The bounded loader refuses final symlinks and
+ * special entries without blocking and enforces descriptor-level type and size.
+ */
+export function readNativeEvidence(file) {
+    const read = readBoundedFile(file, MAX_NATIVE_EVIDENCE_BYTES);
+    if (!read.ok) {
+        switch (read.code) {
+            case 'path_not_absolute':
+                return fail('evidence_path_must_be_absolute');
+            case 'unreadable':
+                return fail('native_evidence_unavailable');
+            default:
+                return fail('unsupported_evidence_file');
+        }
+    }
+    return { bytes: read.bytes, text: read.text, digest: read.digest };
+}
+export function parseExecution(text) {
+    try {
+        const value = JSON.parse(text);
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            return fail('invalid_native_json');
+        }
+        return value;
+    }
+    catch {
+        return fail('invalid_native_json');
+    }
+}
+export function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function digestOf(bytes) {
+    return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+export function evidenceRecords(evidenceFile, evidenceRef, executionFile, executionRef) {
+    return [
+        { ref: evidenceRef, digest: evidenceFile.digest },
+        { ref: executionRef, digest: executionFile.digest },
+    ];
+}
+export function isTimestamp(value) {
+    return (typeof value === 'string' &&
+        /(?:Z|[+-]\d\d:\d\d)$/.test(value) &&
+        Number.isFinite(Date.parse(value)));
+}
+const DATE_MS_LIMIT = 8.64e15;
+/**
+ * Interpret one recorded Pi timestamp. A message-level value is numeric Unix
+ * milliseconds; a record-level value is an explicit-zone ISO string. Numeric
+ * strings are not accepted as a substitute for either form.
+ */
+export function piTimestamp(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) && Math.abs(value) <= DATE_MS_LIMIT
+            ? value
+            : null;
+    }
+    if (typeof value === 'string' && /(?:Z|[+-]\d\d:\d\d)$/.test(value)) {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+export function samePath(left, right) {
+    if (typeof left !== 'string' || typeof right !== 'string')
+        return false;
+    try {
+        return fs.realpathSync(left) === fs.realpathSync(right);
+    }
+    catch {
+        return false;
+    }
+}
+export function realPath(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return fail('native_evidence_unavailable');
+    }
+}
+export function argumentStrings(value, found = []) {
+    if (typeof value === 'string') {
+        if (value.includes('/') || value.toLowerCase().endsWith('.md'))
+            found.push(value);
+        return found;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            argumentStrings(item, found);
+        return found;
+    }
+    if (record(value)) {
+        for (const item of Object.values(value))
+            argumentStrings(item, found);
+    }
+    return found;
+}
+export function payloadStrings(item) {
+    const found = [];
+    const visit = (value) => {
+        if (typeof value === 'string')
+            found.push(value);
+        else if (Array.isArray(value))
+            value.forEach(visit);
+        else if (record(value))
+            Object.values(value).forEach(visit);
+    };
+    visit(item);
+    return found;
+}
+/** Assert the template still claims exactly the assignment's assignee identity. */
+export function assertTemplateIdentity(assignment, template, harness) {
+    if (assignment.assignee.harness !== harness)
+        fail('unsupported_harness');
+    for (const key of [
+        'agent_id',
+        'session_id',
+        'harness',
+        'surface',
+        'configuration_id',
+    ]) {
+        if (template[key] !== assignment.assignee[key])
+            fail('template_identity_mismatch');
+    }
+    if (!samePath(template.cwd, assignment.assignee.cwd))
+        fail('template_cwd_mismatch');
+}
+/**
+ * Reproduce the maintained fingerprint check: the template's pinned digest must
+ * still describe the selected skill before evidence can promote it.
+ */
+export function fingerprintTemplateSkill(skill) {
+    if (typeof skill.path !== 'string')
+        fail('skill_path_missing');
+    const snapshot = fingerprintSkill(skill.path);
+    if (snapshot.bundle_digest !== skill.bundle_digest)
+        fail('skill_files_changed');
+    return {
+        entry: snapshot.path,
+        directory: path.dirname(snapshot.path),
+        bundleDigest: snapshot.bundle_digest,
+    };
+}
+function errorCode(error) {
+    if (error instanceof EvidenceError)
+        return error.code;
+    const message = error instanceof Error ? error.message : String(error);
+    if (/^[a-z_]+$/.test(message))
+        return message;
+    if (/^unsupported_row_types/.test(message))
+        return message;
+    return 'native_evidence_unavailable';
+}
+/**
+ * Validate the pinned contract/template and translate adapter failures into the
+ * maintained outcome shapes. A derived card remains a claim derived from the
+ * supplied evidence; nothing here authenticates, launches or dispatches.
+ */
+export function deriveOutcome(assignment, template, work) {
+    try {
+        validateContractAndCard(assignment, template);
+    }
+    catch {
+        return { status: 'invalid', blockers: ['invalid_contract_or_template'] };
+    }
+    try {
+        return { status: 'derived', ...work() };
+    }
+    catch (error) {
+        return { status: 'needs_input', blockers: [errorCode(error)] };
+    }
+}

package/dist/app/collab-auto-handoff.d.ts

@@ -0,0 +1,55 @@
+import type { RolloverInventory } from '../collab/rollover.js';
+import { type SaveCheckpointInput, type HandoffSourceNativeSession } from '../continuity/index.js';
+import type { ManagedPiReadinessConfig } from './managed-pi-readiness.js';
+import { type SessionTransitionDependencies, type SessionTransitionReport, type SessionTransitionRequest } from './collab-session-transition.js';
+export declare const AUTO_HANDOFF_SCHEMA = "pappra/automatic-handoff/1";
+export interface AutomaticHandoffConfig {
+    readonly schema: typeof AUTO_HANDOFF_SCHEMA;
+    readonly id: string;
+    readonly thresholdPercent: number;
+    readonly workspaceRoot: string;
+    readonly checkpoint: SaveCheckpointInput & {
+        readonly objective: string;
+        readonly acceptance: readonly string[];
+    };
+    readonly bundleId: string;
+    readonly nextAction: string;
+    /** Approved output locations for this source's independently observed admission. */
+    readonly sourceReadiness?: ManagedPiReadinessConfig;
+    readonly transition: Omit<SessionTransitionRequest, 'bundle'>;
+}
+/** Provided by an owned runtime, never deserialized from a claimed proof file. */
+export interface AutomaticHandoffRuntime {
+    /** Native eligibility is checked before reserving a provider call or fencing input. */
+    canCaptureSummary?(): boolean;
+    /** Trusted app callback; refreshes only the source capability pin after native compaction. */
+    prepareBootstrapAdmission?(original: {
+        readonly ref: string;
+        readonly digest: string;
+    }): Promise<{
+        readonly ref: string;
+        readonly digest: string;
+    }>;
+    observe(): {
+        readonly native: HandoffSourceNativeSession;
+        readonly cwd: string;
+        readonly contextPercent: number | null;
+    };
+    /** Real native model summary; an absent/failed summary must never be filled in. */
+    captureSummary(causeId: string): Promise<{
+        readonly summary: string;
+        readonly complete: boolean;
+        readonly sessionFile?: string | null;
+    }>;
+    inventory(): Promise<RolloverInventory>;
+}
+export interface AutomaticHandoffResult {
+    readonly schema: typeof AUTO_HANDOFF_SCHEMA;
+    readonly status: 'below-threshold' | 'waiting' | 'progressed' | 'complete' | 'blocked' | 'reconcile_required';
+    readonly code: string | null;
+    readonly transition: SessionTransitionReport | null;
+    /** Exact revalidated request used for the guarded transition, including admitted evidence. */
+    readonly request?: SessionTransitionRequest;
+}
+/** One supported event advances one bounded transition. Existing transition effects remain authoritative. */
+export declare function tickAutomaticHandoff(config: AutomaticHandoffConfig, runtime: AutomaticHandoffRuntime, dependencies?: SessionTransitionDependencies): Promise<AutomaticHandoffResult>;