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

package/dist/collab/canonical.js

@@ -18,7 +18,7 @@ export const RESOURCE_KINDS = Object.freeze([...PATH_KINDS, ...OPAQUE_KINDS].sor
 /**
  * Resolve the longest existing ancestor with realpath and append the not-yet-existing
  * suffix. Symlink aliases therefore collapse to one key. The suffix keeps the caller's
- * spelling, so a differently-cased non-existent target is not normalised.
+ * spelling for I/O; comparison keys account for the containing filesystem's case behavior.
  */
 export function canonicalizeTarget(input) {
     if (typeof input !== 'string' || input.trim().length === 0)
@@ -29,7 +29,7 @@ export function canonicalizeTarget(input) {
     let probe = path.normalize(input);
     for (;;) {
         try {
-            const real = fs.realpathSync(probe);
+            const real = fs.realpathSync.native(probe);
             return {
                 path: path.join(real, ...missing.slice().reverse()),
                 existing: missing.length === 0,
@@ -47,8 +47,49 @@ export function canonicalizeTarget(input) {
         }
     }
 }
+/** Probe existing directory aliases without creating files or assuming all macOS volumes match. */
+function caseInsensitiveAt(input) {
+    let probe = input;
+    for (;;) {
+        try {
+            const observed = fs.statSync(probe);
+            if (!observed.isDirectory()) {
+                probe = path.dirname(probe);
+                continue;
+            }
+            const name = path.basename(probe);
+            const flipped = name.replace(/[a-zA-Z]/, (letter) => letter === letter.toLowerCase()
+                ? letter.toUpperCase()
+                : letter.toLowerCase());
+            if (flipped !== name) {
+                try {
+                    const alias = fs.statSync(path.join(path.dirname(probe), flipped));
+                    return alias.dev === observed.dev && alias.ino === observed.ino;
+                }
+                catch {
+                    return false;
+                }
+            }
+        }
+        catch {
+            // Missing suffixes inherit the closest existing directory's behavior.
+        }
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            return process.platform === 'win32';
+        probe = parent;
+    }
+}
+function comparisonPath(input) {
+    const resolved = canonicalizeTarget(input);
+    return caseInsensitiveAt(resolved.nearest_ancestor)
+        ? resolved.path.normalize('NFC').toUpperCase().toLowerCase()
+        : resolved.path;
+}
 /** `same`, `ancestor`, `descendant` or `disjoint` on path-segment boundaries. */
 export function pathRelation(left, right) {
+    left = comparisonPath(left);
+    right = comparisonPath(right);
     if (left === right)
         return 'same';
     const a = left.split(path.sep).filter(Boolean);
@@ -110,7 +151,7 @@ export function describeResource(input) {
     return {
         kind,
         scope,
-        key: `${kind}:${resolved.path}`,
+        key: `${kind}:${comparisonPath(resolved.path)}`,
         path: resolved.path,
         existing: resolved.existing,
         label: input.label ?? `${kind} ${resolved.path}`,

package/dist/collab/envelope.d.ts

@@ -1,11 +1,10 @@
 import type { Message, MessageInput } from './types.js';
+export { canonicalJson } from '../infra/json.js';
 export declare const MESSAGE_SCHEMA = "harness-collab/message/1";
 export declare const MESSAGE_TYPES: readonly string[];
 export declare const REPORT_STATUSES: readonly string[];
 export declare const BLOCK_KINDS: readonly string[];
 export declare function validateEnvelope(message: unknown): Message;
-/** Stable JSON with sorted object keys, used for content-identity digests. */
-export declare function canonicalJson(value: unknown): string;
 /**
  * Content identity of a message: everything that decides what the message means.
  * `created_at` and `content_digest` are excluded so an honest resend is still the
@@ -15,6 +14,7 @@ export declare function contentDigest(message: Message): string;
 export declare function buildMessage(input: MessageInput, { clock }?: {
     clock?: number | undefined;
 }): Message;
+export declare function isSafeMessageId(value: unknown): value is string;
 export declare function messageFile(taskRoot: string, messageId: string): string;
 export declare function readRegisteredMessage(taskRoot: string, messageId: string): Message | null;
 /**

package/dist/collab/envelope.js

@@ -2,6 +2,8 @@ import { errorCode, parseJson, object, text, isMessage } from './validation.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createNonce, digestText, messagesDir, nowIso } from './store.js';
+import { canonicalJson } from '../infra/json.js';
+export { canonicalJson } from '../infra/json.js';
 // Message envelopes and their idempotency rules.
 //
 // Registration is an exclusive create of `messages/<message_id>.json`, which is atomic,
@@ -99,17 +101,6 @@ export function validateEnvelope(message) {
     // Unknown extension fields are tolerated on purpose; unknown semantics are not inferred.
     return message;
 }
-/** Stable JSON with sorted object keys, used for content-identity digests. */
-export function canonicalJson(value) {
-    if (value === null || typeof value !== 'object')
-        return JSON.stringify(value ?? null);
-    if (Array.isArray(value))
-        return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
-    if (!object(value))
-        throw new Error('Canonical JSON requires an object');
-    const keys = Object.keys(value).sort();
-    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
-}
 /**
  * Content identity of a message: everything that decides what the message means.
  * `created_at` and `content_digest` are excluded so an honest resend is still the
@@ -149,8 +140,17 @@ export function buildMessage(input, { clock = Date.now() } = {}) {
     message.content_digest = contentDigest(message);
     return message;
 }
+/**
+ * Message ids are single path segments: a letter or digit followed by letters,
+ * digits, dot, dash or underscore, bounded at 128 characters. Anything else
+ * (`..`, separators, control characters) is rejected before any path is built.
+ */
+const SAFE_MESSAGE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function isSafeMessageId(value) {
+    return typeof value === 'string' && SAFE_MESSAGE_ID.test(value);
+}
 export function messageFile(taskRoot, messageId) {
-    if (/[\\/\0]/.test(messageId))
+    if (!isSafeMessageId(messageId))
         throw new Error('Invalid message field: message.message_id');
     return path.join(messagesDir(taskRoot), `${messageId}.json`);
 }

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

@@ -0,0 +1,3 @@
+import type { ResultEntry, RolloverIntent } from './types.js';
+/** A native turn may prove succession while the attempt remains active. */
+export declare function isNativeFirstWorkResult(result: ResultEntry, intent: RolloverIntent): boolean;

package/dist/collab/first-work.js

@@ -0,0 +1,15 @@
+/** A native turn may prove succession while the attempt remains active. */
+export function isNativeFirstWorkResult(result, intent) {
+    if (result.status !== 'running' ||
+        typeof result.native_ref !== 'object' ||
+        result.native_ref === null)
+        return false;
+    const ref = result.native_ref;
+    return (ref.schema === 'pappra/native-first-work/1' &&
+        ref.handoff_id === intent.handoff_id &&
+        ref.generation === intent.generation &&
+        ref.session_id === intent.to.session_id &&
+        ref.observation === 'native_agent_settled' &&
+        typeof ref.evidence_ref === 'string' &&
+        ref.evidence_ref.length > 0);
+}

package/dist/collab/handoff.d.ts

@@ -21,6 +21,7 @@ export declare function beginHandoff(record: TaskRecord, { handoffId, kind, subt
     other_state?: never;
     expected?: never;
     actual?: never;
+    claim_id?: never;
     handoff_id?: never;
     state?: never;
 } | {
@@ -31,6 +32,7 @@ export declare function beginHandoff(record: TaskRecord, { handoffId, kind, subt
     shared_resources: string[];
     expected?: never;
     actual?: never;
+    claim_id?: never;
     handoff_id?: never;
     state?: never;
 } | {
@@ -41,6 +43,7 @@ export declare function beginHandoff(record: TaskRecord, { handoffId, kind, subt
     other_state: string;
     expected?: never;
     actual?: never;
+    claim_id?: never;
     handoff_id?: never;
     state?: never;
 } | {
@@ -51,15 +54,28 @@ export declare function beginHandoff(record: TaskRecord, { handoffId, kind, subt
     reason: string;
     expected: number | null;
     actual: number;
+    claim_id?: never;
     handoff_id?: never;
     state?: never;
 } | {
     shared_resources?: never;
     other_handoff?: never;
     other_state?: never;
+    expected?: never;
+    actual?: never;
+    ok: false;
+    reason: string;
+    claim_id: string;
+    handoff_id?: never;
+    state?: never;
+} | {
     reason?: never;
+    shared_resources?: never;
+    other_handoff?: never;
+    other_state?: never;
     expected?: never;
     actual?: never;
+    claim_id?: never;
     ok: true;
     handoff_id: string;
     state: string;

package/dist/collab/handoff.js

@@ -71,12 +71,46 @@ export function beginHandoff(record, { handoffId, kind, subtaskId = null, attemp
             actual: ownerEpoch ?? null,
         };
     }
-    if (kind === 'writer') {
-        const target = findAttempt(record, subtaskId, attempt);
-        if (!target)
-            return { ok: false, reason: 'unknown_attempt' };
-        target.ownership = 'transferring';
+    const target = kind === 'writer' ? findAttempt(record, subtaskId, attempt) : null;
+    if (kind === 'writer' && !target)
+        return { ok: false, reason: 'unknown_attempt' };
+    const authority = kind === 'writer' ? target?.assignee : record.coordinator;
+    if (!authority ||
+        authority.agent_id !== from.agent_id ||
+        authority.session_id !== from.session_id)
+        return { ok: false, reason: 'unauthorized_sender' };
+    const seen = new Set();
+    for (const claimId of resources) {
+        if (seen.has(claimId))
+            return {
+                ok: false,
+                reason: 'duplicate_handoff_resource',
+                claim_id: claimId,
+            };
+        seen.add(claimId);
+        const matches = (record.claims ?? []).filter((claim) => claim.claim_id === claimId);
+        if (matches.length !== 1)
+            return {
+                ok: false,
+                reason: matches.length ? 'ambiguous_claim_id' : 'unknown_claim',
+                claim_id: claimId,
+            };
+        const claim = matches[0];
+        if (claim.released_at ||
+            claim.holder?.agent_id !== from.agent_id ||
+            claim.holder?.session_id !== from.session_id ||
+            (kind === 'writer' &&
+                ((claim.subtask_id !== null && claim.subtask_id !== subtaskId) ||
+                    (claim.attempt !== null && claim.attempt !== attempt))))
+            return {
+                ok: false,
+                reason: 'handoff_resource_not_owned',
+                claim_id: claimId,
+            };
     }
+    // Validate the entire inventory before reserving an attempt or freezing dispatch.
+    if (target)
+        target.ownership = 'transferring';
     const at = nowIso(clock);
     const entry = {
         schema: 'harness-collab/handoff/1',

package/dist/collab/index.d.ts

@@ -1,4 +1,4 @@
-export * as store from './store.js';
+import * as storeInternals from './store.js';
 export * as canonical from './canonical.js';
 export * as resources from './resources.js';
 export * as envelope from './envelope.js';
@@ -6,4 +6,100 @@ export * as messages from './messages.js';
 export * as lifecycle from './lifecycle.js';
 export * as handoff from './handoff.js';
 export * as notify from './notify.js';
+export * as workPlan from './work-plan.js';
+export * as rollover from './rollover.js';
 export type * from './types.js';
+declare const storeSurface: {
+    STATE_SCHEMA: "harness-collab/state/1";
+    LEDGER_SCHEMA: "harness-collab/ledger/1";
+    RECORD_FILE: "task.json";
+    LEDGER_FILE: "ledger.jsonl";
+    DEFAULT_DOMAIN_ROOT: string;
+    LockHeldError: typeof storeInternals.LockHeldError;
+    RevisionConflictError: typeof storeInternals.RevisionConflictError;
+    digestBytes: (value: string | Uint8Array) => string;
+    digestText: (value: string | Uint8Array) => string;
+    createNonce(): string;
+    nowIso(clock?: number): string;
+    isAbsoluteExistingDirectory(value: unknown): boolean;
+    resolveDomainRoot(input?: string | null): string;
+    taskRootFor(domainRoot: string, taskId: string): string;
+    recordPath: (taskRoot: string) => string;
+    ledgerPath: (taskRoot: string) => string;
+    lockPath: (taskRoot: string) => string;
+    messagesDir: (taskRoot: string) => string;
+    resultsDir: (taskRoot: string) => string;
+    nativeDir: (taskRoot: string) => string;
+    abortedDir: (taskRoot: string) => string;
+    brokenLocksDir: (taskRoot: string) => string;
+    notificationsDir: (taskRoot: string) => string;
+    domainIdOf(domainRoot: string): string;
+    readRecord(taskRoot: string): import("./types.js").TaskRecord | null;
+    readLock(taskRoot: string): {
+        held: boolean;
+        holder?: never;
+        holder_process_alive?: never;
+        transaction_files?: never;
+    } | {
+        held: boolean;
+        holder: import("./types.js").LockHolder | null;
+        holder_process_alive: boolean;
+        transaction_files: string[];
+    };
+    listTransactions(taskRoot: string): import("./types.js").TransactionFile[];
+    acquireLock(taskRoot: string, { actor, purpose, waitMs, pollMs, }?: {
+        actor?: string;
+        purpose?: string;
+        waitMs?: number;
+        pollMs?: number;
+    }): {
+        schema: string;
+        nonce: string;
+        actor: string;
+        purpose: string;
+        pid: number;
+        hostname: string;
+        acquired_at: string;
+    };
+    releaseLock(taskRoot: string, holder: import("./types.js").LockHolder | null): boolean;
+    archiveAbortedTransaction(taskRoot: string, file: string, { actor, at, }?: {
+        actor?: string;
+        reason?: string;
+        confirmHolderStopped?: boolean;
+        at?: string;
+    }): string;
+    transact<T = unknown>(taskRoot: string, { actor, purpose, expectRevision, waitMs, apply, clock, }: {
+        actor?: string;
+        purpose?: string;
+        expectRevision?: number | null | undefined;
+        waitMs?: number;
+        apply: (record: import("./types.js").TaskRecord) => import("./types.js").Mutation<T> | import("./types.js").Failure | null | undefined;
+        clock?: number;
+    }): import("./types.js").TransactionResult<T>;
+    newRecord({ taskId, domainRoot, taskRoot, coordinator, clock, }: {
+        taskId: string;
+        domainRoot: string;
+        taskRoot: string;
+        coordinator?: import("./types.js").Coordinator | null;
+        clock?: number;
+    }): import("./types.js").TaskRecord;
+    initTask(taskRoot: string, { taskId, coordinator, domainRoot: explicitDomainRoot, clock, }: {
+        taskId: string;
+        coordinator?: import("./types.js").Coordinator | null;
+        domainRoot?: string | null;
+        clock?: number;
+    }): {
+        created: boolean;
+        record: import("./types.js").TaskRecord | null;
+    };
+    doctor(taskRoot: string): {
+        task_root: string;
+        state_revision: null;
+        findings: import("./types.js").Finding[];
+    } | {
+        task_root: string;
+        state_revision: number;
+        findings: import("./types.js").Finding[];
+    };
+};
+export { storeSurface as store };

package/dist/collab/index.js

@@ -1,4 +1,4 @@
-export * as store from './store.js';
+import * as storeInternals from './store.js';
 export * as canonical from './canonical.js';
 export * as resources from './resources.js';
 export * as envelope from './envelope.js';
@@ -6,3 +6,11 @@ export * as messages from './messages.js';
 export * as lifecycle from './lifecycle.js';
 export * as handoff from './handoff.js';
 export * as notify from './notify.js';
+export * as workPlan from './work-plan.js';
+export * as rollover from './rollover.js';
+// The public barrel curates the store surface. `breakLock` stays in
+// `./store.js` because the operator-only `collab recovery lock-break` command
+// owns the confirmation flow; exposing the bare primitive invites a caller to
+// break a live writer's lock without that evidence.
+const { breakLock: _unsafeBreakLock, ...storeSurface } = storeInternals;
+export { storeSurface as store };

package/dist/collab/messages.js

@@ -35,6 +35,104 @@ function findMessage(record, messageId) {
     return ((record.messages ?? []).find((item) => item.message_id === messageId) ??
         null);
 }
+function sameSender(sender, expected) {
+    return (expected?.agent_id === sender.agent_id &&
+        expected.session_id === sender.session_id);
+}
+/** An epoch identifies the generation of authority, not the agent holding it. */
+function authorizeSender(record, message) {
+    let expected;
+    switch (message.type) {
+        case 'ASSIGN':
+        case 'CANCEL':
+            expected = record.coordinator;
+            break;
+        case 'HANDOFF': {
+            if (message.body.phase !== 'request') {
+                const handoff = record.handoffs.find((item) => item.handoff_id === message.body.handoff_id);
+                if (handoff &&
+                    (sameSender(message.from, handoff.from) ||
+                        sameSender(message.from, handoff.to)))
+                    return null;
+                return { ok: false, reason: 'unauthorized_sender' };
+            }
+            if (message.body.kind === 'coordinator') {
+                expected = record.coordinator;
+                break;
+            }
+            expected = findAttempt(record, message.subtask_id, message.attempt)?.assignee;
+            break;
+        }
+        case 'ACK':
+        case 'BLOCK':
+        case 'CANCELLED': {
+            const referenced = message.reply_to
+                ? findMessage(record, message.reply_to)
+                : null;
+            const subtaskId = message.subtask_id ?? referenced?.subtask_id ?? null;
+            const attempt = message.attempt ?? referenced?.attempt ?? null;
+            const target = findAttempt(record, subtaskId, attempt);
+            if (message.type === 'ACK') {
+                const handoff = record.handoffs.find((item) => (item.handoff_id === message.body.handoff_id ||
+                    item.handoff_id === message.reply_to) &&
+                    (item.kind === 'coordinator' ||
+                        (item.subtask_id === subtaskId && item.attempt === attempt)) &&
+                    !['completed', 'aborted'].includes(item.state) &&
+                    sameSender(item.from, item.kind === 'coordinator'
+                        ? record.coordinator
+                        : target?.assignee) &&
+                    sameSender(message.from, item.to));
+                if (handoff)
+                    return null;
+            }
+            if (!target)
+                return { ok: false, reason: 'unknown_attempt' };
+            if (message.type === 'BLOCK' &&
+                sameSender(message.from, record.coordinator))
+                return null;
+            expected = target.assignee;
+            break;
+        }
+        case 'ANSWER': {
+            const referenced = message.reply_to
+                ? findMessage(record, message.reply_to)
+                : null;
+            if (!referenced)
+                return { ok: false, reason: 'unknown_question' };
+            // Coordinator decisions and instructions are evidence consumed by work-plan
+            // and recovery validation. They are not clarification state transitions.
+            if (!['ASK', 'BLOCK'].includes(referenced.type)) {
+                return sameSender(message.from, record.coordinator)
+                    ? null
+                    : { ok: false, reason: 'unauthorized_sender' };
+            }
+            if (referenced.type === 'BLOCK' && referenced.body_kind === 'approval')
+                return { ok: false, reason: 'approval_not_auto_answerable' };
+            if (referenced.subtask_id && referenced.attempt) {
+                const target = findAttempt(record, referenced.subtask_id, referenced.attempt);
+                if ((referenced.type === 'BLOCK' && referenced.state !== 'applied') ||
+                    !(sameSender(referenced.from, target?.assignee) ||
+                        (sameSender(referenced.from, record.coordinator) &&
+                            referenced.to !== null &&
+                            sameSender(referenced.to, target?.assignee))))
+                    return { ok: false, reason: 'stale_question' };
+            }
+            if ((message.subtask_id && message.subtask_id !== referenced.subtask_id) ||
+                (message.attempt && message.attempt !== referenced.attempt) ||
+                !sameSender(message.to, referenced.from))
+                return { ok: false, reason: 'reply_identity_mismatch' };
+            expected = referenced.to;
+            break;
+        }
+        // REPORT classifies a previous owner's result as evidence without changing the
+        // current attempt. Questions and status exchanges confer no execution authority.
+        default:
+            return null;
+    }
+    return sameSender(message.from, expected)
+        ? null
+        : { ok: false, reason: 'unauthorized_sender' };
+}
 /**
  * Pure-ish apply function for `transact`: returns the outcome object or `{ok:false,...}`.
  */
@@ -62,6 +160,9 @@ export function applyMessage(record, message, { clock = Date.now(), nativeDir: _
             reason: 'task_mismatch',
             expected: record.task_id,
         };
+    const authorization = authorizeSender(record, message);
+    if (authorization)
+        return authorization;
     if (DISPATCH_TYPES.has(message.type)) {
         if (record.dispatch_frozen && message.type === 'ASSIGN') {
             return {
@@ -155,7 +256,7 @@ export function applyMessage(record, message, { clock = Date.now(), nativeDir: _
                     subtask_id: subtaskId,
                     attempt,
                 };
-            const transition = target.state === 'assigned'
+            const transition = target.state === 'assigned' && sameSender(message.from, target.assignee)
                 ? transitionAttempt(record, {
                     subtaskId,
                     attempt,
@@ -178,6 +279,24 @@ export function applyMessage(record, message, { clock = Date.now(), nativeDir: _
                 result: transition,
             };
         }
+        case 'ASK': {
+            // A question is evidence, not a transition. Blocking a clarification stays
+            // BLOCK(kind=clarification); ANSWER resolves only that state. This branch completes
+            // the advertised envelope vocabulary without adding authority or execution.
+            const subtaskId = message.subtask_id ?? null;
+            const attempt = message.attempt ?? null;
+            recordMessage(record, message, 'recorded', 'question recorded; no task state change', clock);
+            return {
+                record,
+                op: 'ask',
+                summary: { subtask_id: subtaskId, attempt },
+                result: {
+                    ok: true,
+                    awaiting: 'response',
+                    state_changed: false,
+                },
+            };
+        }
         case 'ANSWER': {
             const referenced = message.reply_to
                 ? findMessage(record, message.reply_to)
@@ -192,7 +311,9 @@ export function applyMessage(record, message, { clock = Date.now(), nativeDir: _
             const subtaskId = message.subtask_id ?? referenced?.subtask_id ?? null;
             const attempt = message.attempt ?? referenced?.attempt ?? null;
             const target = subtaskId && attempt ? findAttempt(record, subtaskId, attempt) : null;
-            const transition = target &&
+            const transition = referenced !== null &&
+                ['ASK', 'BLOCK'].includes(referenced.type) &&
+                target &&
                 target.state === 'needs_input' &&
                 target.awaiting === 'clarification'
                 ? transitionAttempt(record, {
@@ -209,7 +330,9 @@ export function applyMessage(record, message, { clock = Date.now(), nativeDir: _
                     reason: 'no_open_clarification',
                     state: target?.state ?? null,
                 };
-            recordMessage(record, message, 'applied', 'clarification answer', clock);
+            recordMessage(record, message, 'applied', referenced && ['ASK', 'BLOCK'].includes(referenced.type)
+                ? 'clarification answer'
+                : 'coordinator decision recorded; no task state change', clock);
             return {
                 record,
                 op: 'answer',