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

package/dist/collab/resources.js

@@ -267,11 +267,31 @@ function nextResourceEpoch(records, keys) {
     }
     return epoch + 1;
 }
+/** Check recorded protocol roles; this is not authentication of a same-user caller. */
+export function checkClaimParticipant(record, holder, subtaskId, attempt) {
+    if (record.coordinator?.agent_id === holder.agent_id &&
+        record.coordinator.session_id === holder.session_id)
+        return { ok: true };
+    if (subtaskId === null || attempt === null)
+        return { ok: false, reason: 'assigned_holder_required' };
+    const assigned = record.attempts.find((item) => item.subtask_id === subtaskId && item.attempt === attempt);
+    if (!assigned ||
+        assigned.assignee.agent_id !== holder.agent_id ||
+        assigned.assignee.session_id !== holder.session_id)
+        return { ok: false, reason: 'holder_assignment_mismatch' };
+    if (!['assigned', 'accepted', 'running'].includes(assigned.state))
+        return { ok: false, reason: 'holder_attempt_not_active' };
+    if (record.dispatch_frozen)
+        return { ok: false, reason: 'dispatch_frozen' };
+    return { ok: true };
+}
 /**
  * Claim resources for one task. The domain lock serialises the decision so two tasks
  * cannot both observe an empty domain and then claim the same path.
+ * Trusted internal preparation may claim for an assignee before ASSIGN is recorded;
+ * public request adapters must enable requireAssignedHolder.
  */
-export function claimResources(taskRoot, { resources, access = 'write', holder, waitMs = 5000, clock = Date.now(), includeSharedGit = false, note = null, subtaskId = null, attempt = null, }) {
+export function claimResources(taskRoot, { resources, access = 'write', holder, waitMs = 5000, clock = Date.now(), includeSharedGit = false, note = null, subtaskId = null, attempt = null, requireAssignedHolder = false, }) {
     const record = readRecord(taskRoot);
     if (!record)
         return { ok: false, reason: 'not_initialised' };
@@ -279,6 +299,11 @@ export function claimResources(taskRoot, { resources, access = 'write', holder,
         return { ok: false, reason: 'invalid_access' };
     if (!holder?.agent_id || !holder?.session_id)
         return { ok: false, reason: 'holder_required' };
+    if (requireAssignedHolder) {
+        const participant = checkClaimParticipant(record, holder, subtaskId, attempt);
+        if (!participant.ok)
+            return participant;
+    }
     const domainRoot = record.domain_root;
     const domainLock = acquireDomainLock(domainRoot, {
         waitMs,
@@ -339,6 +364,11 @@ export function claimResources(taskRoot, { resources, access = 'write', holder,
             waitMs,
             clock,
             apply: (current) => {
+                if (requireAssignedHolder) {
+                    const participant = checkClaimParticipant(current, holder, subtaskId, attempt);
+                    if (!participant.ok)
+                        return participant;
+                }
                 const fresh = scanConflicts([
                     current,
                     ...records.filter((item) => item.task_id !== current.task_id),
@@ -383,11 +413,13 @@ function claimIdDigest(identity) {
         .slice(0, 32);
 }
 export function releaseClaim(taskRoot, { claimId, holder, reason, clock = Date.now(), }) {
+    if (!holder?.agent_id || !holder?.session_id)
+        return { ok: false, reason: 'holder_required' };
     const record = readRecord(taskRoot);
     if (!record)
         return { ok: false, reason: 'not_initialised' };
     const outcome = transact(taskRoot, {
-        actor: holder?.agent_id ?? 'unattributed',
+        actor: holder.agent_id,
         purpose: 'release',
         clock,
         apply: (current) => {
@@ -410,9 +442,8 @@ export function releaseClaim(taskRoot, { claimId, holder, reason, clock = Date.n
             const claim = matches[0];
             if (claim.released_at)
                 return { ok: false, reason: 'already_released' };
-            if (holder &&
-                (claim.holder?.agent_id !== holder.agent_id ||
-                    claim.holder?.session_id !== holder.session_id)) {
+            if (claim.holder?.agent_id !== holder.agent_id ||
+                claim.holder?.session_id !== holder.session_id) {
                 return {
                     ok: false,
                     reason: 'holder_mismatch',
@@ -426,7 +457,7 @@ export function releaseClaim(taskRoot, { claimId, holder, reason, clock = Date.n
                     detail: 'a cancel request does not prove the holder stopped',
                 };
             claim.released_at = nowIso(clock);
-            claim.released_by = holder?.agent_id ?? 'unattributed';
+            claim.released_by = holder.agent_id;
             claim.release_reason = reason ?? null;
             return {
                 record: current,

package/dist/collab/rollover.d.ts

@@ -0,0 +1,311 @@
+import type { Identity, TaskRecord } from './types.js';
+/**
+ * Bounded, record-level writer rollover correlation.
+ *
+ * This module only reduces the existing task record: handoff state and claims stay
+ * authoritative, and no second authority store, filesystem access, native control or
+ * continuity import is introduced. An intent pins the immutable inputs of one
+ * writer-to-writer transfer, including the confirmed source native identity; confirmation
+ * and first-work evidence must be stored, digest-verified protocol messages correlated to
+ * that intent. A caller-supplied object is never treated as authenticated native proof.
+ */
+export declare const ROLLOVER_INTENT_SCHEMA = "pappra/collab-rollover-intent/1";
+export declare const ROLLOVER_SUCCESSION_SCHEMA = "pappra/collab-succession/1";
+export interface RolloverClaimReference {
+    readonly claim_id: string;
+    readonly resource_epoch: number;
+}
+export interface RolloverBundleReference {
+    readonly ref: string;
+    readonly digest: string;
+}
+/** The native session identity of one writer; never inferred from another pointer. */
+export interface RolloverNativeIdentity {
+    readonly agent_id: string | null;
+    readonly runner: string | null;
+    readonly session_id: string | null;
+    readonly run_id: string | null;
+    readonly mission_id: string | null;
+}
+export interface RolloverNativeBindingInput extends RolloverNativeIdentity {
+    readonly evidence_ref: string;
+    readonly observed_at?: string | null;
+}
+export interface RolloverTransferBoundary {
+    /** Message-application position at completion; never a sender timestamp. */
+    readonly message_count: number;
+    readonly state_revision: number;
+    readonly at: string;
+}
+/** Explicit quiescence inventory. Unknown or partial completeness never authorizes transfer. */
+export interface RolloverInventory {
+    readonly completeness: 'complete' | 'partial' | 'unknown';
+    readonly inflight: readonly unknown[];
+    readonly pending_approvals: readonly unknown[];
+    /** Required: absent message completeness can never be treated as "none". */
+    readonly pending_messages?: readonly unknown[];
+    /** Captured partial outputs; part of the pinned inventory identity. */
+    readonly partial_outputs?: readonly unknown[];
+}
+export interface CreateRolloverIntentInput {
+    readonly intent_id: string;
+    readonly generation: number;
+    readonly handoff_id: string;
+    readonly subtask_id: string;
+    readonly attempt: number;
+    readonly input_revision: string;
+    readonly from: Identity;
+    readonly to: Identity;
+    readonly claims: readonly RolloverClaimReference[];
+    readonly bundle: RolloverBundleReference;
+    readonly coordinator_epoch: number;
+    readonly clock?: number;
+}
+export interface RolloverFailure {
+    readonly ok: false;
+    readonly reason: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Records the immutable intent and opens the underlying writer handoff. An exact replay of
+ * the same intent inputs returns the existing intent without another mutation.
+ */
+export declare function createRolloverIntent(record: TaskRecord, input: CreateRolloverIntentInput): RolloverFailure | {
+    ok: false;
+    reason: string;
+    shared_resources?: never;
+    other_handoff?: never;
+    other_state?: never;
+    expected?: never;
+    actual?: never;
+    claim_id?: never;
+    handoff_id?: never;
+    state?: never;
+} | {
+    ok: false;
+    reason: string;
+    other_handoff: string;
+    other_state: string;
+    shared_resources: string[];
+    expected?: never;
+    actual?: never;
+    claim_id?: never;
+    handoff_id?: never;
+    state?: never;
+} | {
+    shared_resources?: never;
+    ok: false;
+    reason: string;
+    other_handoff: string;
+    other_state: string;
+    expected?: never;
+    actual?: never;
+    claim_id?: never;
+    handoff_id?: never;
+    state?: never;
+} | {
+    shared_resources?: never;
+    other_handoff?: never;
+    other_state?: never;
+    ok: false;
+    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;
+} | {
+    ok: true;
+    intent: import("./types.js").RolloverIntent;
+    handoff_state: string | null;
+    replayed: boolean;
+};
+/** Read-only projection of one intent, its handoff progress and any recorded succession. */
+export declare function inspectRolloverIntent(record: TaskRecord, intentId: string): RolloverFailure | {
+    ok: true;
+    intent: import("./types.js").RolloverIntent;
+    handoff_state: string | null;
+    ownership: string | null;
+    assignee: Identity | null;
+    claims: {
+        claim_id: string;
+        expected_resource_epoch: number;
+        holder: Identity | null;
+        resource_epoch: number | null;
+        released_at: string | null;
+    }[];
+    transfer_boundary: import("./types.js").RolloverTransferBoundary | null;
+    succession: import("./types.js").SuccessionEntry | null;
+    routing: string;
+    native_archive: string;
+};
+/**
+ * Records confirmed quiescence and freezes the transfer inventory. An absent or non-complete
+ * inventory, unknown stop evidence, a blocked writer and any drift are refused without
+ * mutation; an exact replay of a completed step is a no-op.
+ */
+export declare function prepareRolloverTransfer(record: TaskRecord, { intent_id, observation, evidence_ref, inventory, actor, clock, }: {
+    intent_id: string;
+    observation: string;
+    evidence_ref: string | null;
+    inventory: RolloverInventory;
+    actor?: string;
+    clock?: number;
+}): RolloverFailure | {
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    handoff_state: string;
+    replayed: boolean;
+};
+/**
+ * Confirms the successor only from a stored, digest-verified ACK envelope that carries the
+ * pinned input revision, the current coordinator epoch and recipient, the intent/handoff/
+ * generation correlation and this attempt's registered assignment as its bootstrap.
+ */
+export declare function confirmRolloverReceiver(record: TaskRecord, { intent_id, message, clock, }: {
+    intent_id: string;
+    message: unknown;
+    clock?: number;
+}): RolloverFailure | {
+    state?: never;
+    ok: false;
+    reason: string;
+    from: string;
+    to: string;
+    expected: string | null | undefined;
+    at?: never;
+} | {
+    ok: false;
+    reason: string;
+    type?: never;
+} | {
+    ok: false;
+    reason: string;
+    type: string;
+} | {
+    ok: true;
+    handoff_state: string;
+    replayed: boolean;
+};
+/**
+ * Completes the writer transfer: claims move to the successor with a raised resource epoch,
+ * the attempt is reassigned and its native identity is rebound explicitly. The coordinator
+ * owner epoch is never raised here.
+ */
+export declare function completeRolloverTransfer(record: TaskRecord, { intent_id, successor_native, actor, clock, }: {
+    intent_id: string;
+    successor_native: RolloverNativeBindingInput;
+    actor?: string;
+    clock?: number;
+}): RolloverFailure | {
+    ok: false;
+    reason: string;
+    native?: never;
+    reconciled_uncertainty?: never;
+} | {
+    state?: never;
+    ok: false;
+    reason: string;
+    from: string;
+    to: string;
+    expected: string | null | undefined;
+    at?: never;
+} | {
+    expected?: never;
+    actual?: never;
+    ok: false;
+    reason: string;
+    drift?: never;
+} | {
+    expected?: never;
+    actual?: never;
+    ok: false;
+    reason: string;
+    drift: ({
+        expected?: never;
+        actual?: never;
+        from?: never;
+        claim_id: string;
+        reason: string;
+    } | {
+        from?: never;
+        claim_id: string;
+        reason: string;
+        expected: number | null | undefined;
+        actual: number;
+    } | {
+        from?: never;
+        claim_id: string;
+        reason: string;
+        expected: Identity | null | undefined;
+        actual: Identity;
+    } | {
+        expected?: never;
+        claim_id: string;
+        reason: string;
+        from: Identity;
+        actual: Identity;
+    })[];
+} | {
+    drift?: never;
+    ok: false;
+    reason: string;
+    expected: number;
+    actual: number | null;
+} | {
+    ok: true;
+    handoff_state: string;
+    transfer_boundary: import("./types.js").RolloverTransferBoundary;
+    replayed: boolean;
+    owner_epoch?: never;
+} | {
+    ok: true;
+    handoff_state: string;
+    transfer_boundary: RolloverTransferBoundary;
+    owner_epoch: number | null;
+    replayed: boolean;
+};
+/**
+ * Records the source-session history marker only when a stored, admitted successor REPORT
+ * proves first work after the recorded transfer boundary, under the pinned input, current
+ * attempt, exact post-transfer claim epochs and the pinned successor native identity.
+ */
+export declare function recordRolloverFirstWork(record: TaskRecord, { intent_id, message, clock, }: {
+    intent_id: string;
+    message: unknown;
+    clock?: number;
+}): RolloverFailure | {
+    ok: true;
+    succession: {
+        schema: string;
+        intent_id: string;
+        handoff_id: string;
+        generation: number;
+        old_native: RolloverNativeIdentity;
+        successor_native: RolloverNativeIdentity;
+        archived_at: string;
+        history_retained: true;
+        routing: 'pending';
+        native_archive: 'unavailable';
+        proof: {
+            message_id: string;
+            digest: string;
+        };
+    };
+    replayed: boolean;
+    routing: string;
+    native_archive: string;
+};