brainclaw 1.26.2 → 1.27.0

package/dist/core/loops/turn-execution.js

@@ -0,0 +1,480 @@
+/** Common projections-before-crossing contract for every worker-backed LoopKind phase. */
+import { ensureAgentRunProjection } from '../agentruns.js';
+import { ensureAssignmentProjection } from '../assignments.js';
+import { ensureClaimAssignmentBinding, loadClaim } from '../claims.js';
+import { CapabilityRequirementSchema, ExecutionContractSchema, attestHarnessContractAcceptance, executionContractRef, resolveCapabilitySnapshot, validateWorkerContractAcceptance, HarnessCapabilityBindingSchema, } from '../execution-contract.js';
+import { resolveHarnessBinding } from '../harness-adapters/index.js';
+import { bindTurnProjection } from './verbs.js';
+import { deriveChildIds, getReservation, launchGrant, resolveTurnId } from './attempt-reservation.js';
+import { bootstrapAttemptAuthorityV2, crossActiveAttemptGenerationV2, executionContractForGeneration, prepareAttempt, projectAndCross, } from './attempt-authority.js';
+import { resolveTurnGenerationChain } from './attempt-generations.js';
+import { readLocalAuthorityHome, resolveActiveAttemptRollout } from './attempt-rollout.js';
+import { getLoop } from './store.js';
+import { phasePolicy } from './kind-policies.js';
+/** Idempotently materialize every child projection required before launch. */
+export function ensureTurnExecutionProjections(reservation, input, cwd) {
+    if (reservation.claim_id === '')
+        throw new Error('attempt reservation has no claim');
+    ensureAssignmentProjection({
+        id: input.assignment_id,
+        short_label: input.assignment_id,
+        claim_id: reservation.claim_id,
+        agent: input.agent,
+        agent_id: input.agent_id,
+        dispatcher_agent: input.dispatcher_agent,
+        dispatcher_session_id: input.dispatcher_session_id,
+        scope: input.scope,
+        description: input.description,
+        // Assignment is the stable logical attempt. Its contract projection stays
+        // generation-zero; each physical AgentRun below carries its own contract.
+        execution_contract_ref: reservation.execution_contract_ref,
+        capability_snapshot: reservation.capability_snapshot,
+        tags: input.assignment_tags ?? ['coordinate', 'loop', 'turn-owned'],
+    }, cwd);
+    input.on_projection?.('assignment');
+    ensureAgentRunProjection({
+        id: input.run_id,
+        short_label: input.run_id,
+        assignment_id: input.assignment_id,
+        claim_id: reservation.claim_id,
+        attempt_index: input.attempt_index ?? 1,
+        agent: input.agent,
+        agent_id: input.agent_id,
+        transport: 'cli_spawn',
+        status: 'created',
+        scope: input.scope,
+        description: input.description,
+        worktree_path: input.worktree_path,
+        execution_contract_ref: input.execution_contract_ref ?? reservation.execution_contract_ref,
+        capability_snapshot: input.capability_snapshot ?? reservation.capability_snapshot,
+        tags: input.run_tags ?? ['turn-owned', 'loop'],
+    }, cwd);
+    input.on_projection?.('run');
+    ensureClaimAssignmentBinding(reservation.claim_id, input.assignment_id, cwd, {
+        worktreePath: input.worktree_path,
+    });
+    input.on_projection?.('claim_binding');
+    bindTurnProjection({
+        id: input.loop_id,
+        slot_id: input.slot_id,
+        actor: input.dispatcher_agent_id ?? input.dispatcher_agent,
+        input: input.task,
+        turn_id: input.turn_id,
+        assignment_id: input.assignment_id,
+        claim_id: reservation.claim_id,
+    }, cwd);
+    input.on_projection?.('slot_binding');
+    input.on_projection?.('before_crossing');
+}
+function preconditionDenied(reason) {
+    return { kind: 'denied', reason, code: 'precondition', authority_claimed: false, claim_disposition: 'release' };
+}
+function authorityDenied(input, turnId, reason) {
+    const reservation = getReservation(turnId, input.cwd);
+    const ownsAuthority = reservation?.claim_id === input.claim_id;
+    const crossed = reservation?.launch?.status === 'crossed';
+    return {
+        kind: 'denied',
+        reason,
+        code: ownsAuthority ? (crossed ? 'already_crossed' : 'repairable') : 'authority_conflict',
+        authority_claimed: ownsAuthority,
+        claim_disposition: ownsAuthority ? 'retain' : 'release',
+        turn_id: turnId,
+    };
+}
+function defaultRequiredRole(kind, phase) {
+    if (kind === 'review')
+        return phase === 'author_response' ? 'execute' : 'review';
+    if (kind === 'ideation')
+        return 'review';
+    if (kind === 'research')
+        return 'consult';
+    return 'execute';
+}
+/**
+ * Common worker-attempt path. It refuses engine/manual phases and never advances
+ * a phase or evaluates a gate; those decisions stay in the Loop Engine.
+ * The first phase in a `(loop, slot, iteration)` retains the historical identity.
+ * If the same slot executes another worker phase without an iteration bump, the
+ * resolver uses a phase-qualified identity while preserving compatible legacy
+ * reservations for crash and upgrade replay.
+ */
+export function prepareTurnExecution(input) {
+    const loop = getLoop(input.loop_id, input.cwd);
+    if (!loop)
+        return preconditionDenied(`loop ${input.loop_id} not found`);
+    if (loop.kind !== input.kind)
+        return preconditionDenied(`loop kind mismatch: ${loop.kind} != ${input.kind}`);
+    if (loop.status !== 'open')
+        return preconditionDenied(`loop ${loop.id} is ${loop.status}, not open`);
+    if (loop.current_phase !== input.phase) {
+        return preconditionDenied(`phase mismatch: loop is '${loop.current_phase}', attempt requested '${input.phase}'`);
+    }
+    const execution = phasePolicy(input.kind, input.phase);
+    if (!execution)
+        return preconditionDenied(`unknown ${input.kind} phase '${input.phase}'`);
+    if (execution.execution !== 'worker') {
+        return preconditionDenied(`${input.kind}.${input.phase} is ${execution.execution}, not a worker phase`);
+    }
+    const iteration = loop.iteration_count;
+    const slot = loop.slots.find((candidate) => candidate.slot_id === input.slot_id);
+    if (!slot)
+        return preconditionDenied(`slot ${input.slot_id} not found in loop ${loop.id}`);
+    const turnId = resolveTurnId({
+        loop_id: loop.id,
+        slot_id: input.slot_id,
+        phase: input.phase,
+        iteration,
+        current_turn_id: slot.current_turn_id,
+    }, input.cwd);
+    const childIds = deriveChildIds(turnId);
+    const existingReservation = getReservation(turnId, input.cwd);
+    if (slot.agent !== undefined && slot.agent !== input.agent) {
+        return preconditionDenied(`slot ${input.slot_id} belongs to agent '${slot.agent}', not '${input.agent}'`);
+    }
+    if (slot.agent_id !== undefined && slot.agent_id !== input.agent_id) {
+        return preconditionDenied(`slot ${input.slot_id} belongs to agent_id '${slot.agent_id}', not '${input.agent_id ?? 'none'}'`);
+    }
+    if (slot.claim_id !== undefined && slot.claim_id !== input.claim_id) {
+        return preconditionDenied(`slot ${input.slot_id} is bound to claim ${slot.claim_id}, not ${input.claim_id}`);
+    }
+    if (slot.current_turn_id !== undefined
+        && slot.current_turn_id !== turnId
+        && ['assigned', 'working', 'waiting_input'].includes(slot.status)) {
+        return preconditionDenied(`slot ${input.slot_id} has active turn ${slot.current_turn_id}, not ${turnId}`);
+    }
+    const claim = (() => {
+        try {
+            return loadClaim(input.claim_id, input.cwd);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (!claim)
+        return preconditionDenied(`claim ${input.claim_id} not found`);
+    if (claim.status !== 'active')
+        return preconditionDenied(`claim ${input.claim_id} is ${claim.status}, not active`);
+    if (claim.agent !== input.agent) {
+        return preconditionDenied(`claim ${input.claim_id} belongs to agent '${claim.agent}', not '${input.agent}'`);
+    }
+    if (claim.scope !== input.scope) {
+        return preconditionDenied(`claim ${input.claim_id} covers '${claim.scope}', not '${input.scope}'`);
+    }
+    if (claim.worktree_path && input.worktree_path && claim.worktree_path !== input.worktree_path) {
+        return preconditionDenied(`claim ${input.claim_id} worktree does not match the dispatch worktree`);
+    }
+    const dispatchLeaseMs = input.dispatch_lease_ms ?? 30 * 60_000;
+    const grantLeaseMs = input.grant_lease_ms ?? 10 * 60_000;
+    const hasCompleteExistingContract = Boolean(existingReservation?.execution_contract
+        && existingReservation.execution_contract_ref
+        && existingReservation.capability_snapshot);
+    const hasPartialExistingContract = Boolean(existingReservation) && !hasCompleteExistingContract && Boolean(existingReservation?.execution_contract
+        || existingReservation?.execution_contract_ref
+        || existingReservation?.capability_snapshot);
+    if (hasPartialExistingContract) {
+        return preconditionDenied('existing reservation has an incomplete execution-contract triplet');
+    }
+    const legacyUncontracted = Boolean(existingReservation) && !hasCompleteExistingContract;
+    const capabilityRequirement = CapabilityRequirementSchema.parse(input.capability_requirement
+        ?? existingReservation?.execution_contract?.capability_requirement
+        ?? {
+            roles: [defaultRequiredRole(input.kind, input.phase)],
+            required_surfaces: ['cli_spawn'],
+            // The transport requirement is CLI spawnability. Some integrations (for
+            // example Cline) expose a spawnable CLI while their native interaction
+            // surface remains an extension; callers can still constrain that native
+            // surface explicitly through capability_requirement.execution_surfaces.
+            execution_surfaces: [],
+            model: input.model,
+            required_tools: [],
+        });
+    if (input.capability_requirement
+        && existingReservation?.execution_contract
+        && JSON.stringify(capabilityRequirement) !== JSON.stringify(existingReservation.execution_contract.capability_requirement)) {
+        return preconditionDenied('capability requirement differs from the immutable existing execution contract');
+    }
+    let requestedHarnessBinding;
+    try {
+        const resolved = input.harness_binding ?? resolveHarnessBinding(input.agent, input.model);
+        requestedHarnessBinding = HarnessCapabilityBindingSchema.parse(resolved);
+    }
+    catch (error) {
+        return preconditionDenied(error instanceof Error ? error.message : String(error));
+    }
+    const frozenHarnessBinding = existingReservation?.capability_snapshot?.resolved.harness;
+    if (frozenHarnessBinding && JSON.stringify(frozenHarnessBinding) !== JSON.stringify(requestedHarnessBinding)) {
+        return preconditionDenied(`harness binding differs from immutable capability snapshot: frozen `
+            + `${frozenHarnessBinding.adapter_id}@${frozenHarnessBinding.adapter_version}, requested `
+            + `${requestedHarnessBinding.adapter_id}@${requestedHarnessBinding.adapter_version}`);
+    }
+    const capabilitySnapshot = existingReservation?.capability_snapshot
+        ?? resolveCapabilitySnapshot(input.agent, capabilityRequirement, input.agent_id, requestedHarnessBinding);
+    if (!capabilitySnapshot.accepted) {
+        const reasons = capabilitySnapshot.reasons.map((reason) => reason.code).join(', ');
+        return preconditionDenied(`capability requirements rejected for ${input.agent}: ${reasons}`);
+    }
+    const effectiveCompletionMode = existingReservation?.completion_mode ?? execution.completion_mode;
+    const effectiveExpectedArtifacts = existingReservation?.expected_artifacts ?? execution.expected_artifacts;
+    const contract = legacyUncontracted ? undefined : (existingReservation?.execution_contract ?? ExecutionContractSchema.parse({
+        schema_version: 1,
+        minimum_reader_version: 1,
+        identity: {
+            loop_id: loop.id,
+            turn_id: turnId,
+            logical_attempt_epoch: existingReservation?.epoch ?? 0,
+            assignment_id: childIds.assignment_id,
+            run_id: childIds.run_id,
+            kind: input.kind,
+            phase: input.phase,
+            iteration,
+        },
+        artifact_contract: {
+            completion_mode: effectiveCompletionMode,
+            expected_artifacts: effectiveExpectedArtifacts,
+        },
+        capability_requirement: capabilityRequirement,
+        workspace_policy: {
+            scope: input.scope,
+            cwd: input.cwd,
+            worktree_path: input.worktree_path,
+            isolation: input.workspace_policy?.isolation ?? (input.worktree_path ? 'worktree' : 'shared_checkout'),
+            write_access: input.workspace_policy?.write_access ?? 'workspace',
+        },
+        timeout_policy: {
+            dispatch_lease_ms: dispatchLeaseMs,
+            grant_lease_ms: grantLeaseMs,
+        },
+        evidence_policy: {
+            require_turn_id: true,
+            require_run_id: true,
+            require_nonce: true,
+            artifact_hash: 'optional',
+        },
+        protocol: { name: 'attempt-authority', minimum_version: 1 },
+    }));
+    const contractRef = contract
+        ? (existingReservation?.execution_contract_ref ?? executionContractRef(contract, capabilitySnapshot))
+        : undefined;
+    const v2 = resolveTurnGenerationChain(input.cwd, turnId);
+    const activeRollout = resolveActiveAttemptRollout(input.cwd);
+    const localHome = readLocalAuthorityHome(input.cwd);
+    if (activeRollout && (!localHome || !contractRef)) {
+        return preconditionDenied(!localHome
+            ? 'AttemptAuthority v2 rollout is active but this store/device has no local authority_home'
+            : 'AttemptAuthority v2 rollout is active but the turn has no immutable execution contract');
+    }
+    // Crash-safe v1→v2 cutover repair. The legacy launch fence is crossed before
+    // the immutable generation-zero cells are published. If the coordinator dies
+    // in that narrow window, a replay must materialize/adopt the v2 anchor so the
+    // turn can be fenced/taken over. It MUST NOT return spawn authority: the
+    // pre-crash caller may have received the crossed grant, so only a successor
+    // generation can safely recover liveness without a duplicate launch.
+    if (activeRollout
+        && localHome
+        && contractRef
+        && !v2
+        && existingReservation?.decision === 'committed'
+        && launchGrant(turnId, input.cwd)?.status === 'crossed') {
+        try {
+            bootstrapAttemptAuthorityV2({
+                turn_id: turnId,
+                authority_home: localHome,
+                actor: input.dispatcher_agent_id ?? input.dispatcher_agent,
+                writer_id: input.dispatcher_agent_id ?? input.dispatcher_agent,
+                cwd: input.cwd,
+                workspace_path: input.worktree_path ?? input.cwd,
+                on_stage: (stage) => input.on_cutover_stage?.(stage === 'initial_anchored' ? 'initial_anchored' : 'v2_anchored'),
+            });
+            return authorityDenied(input, turnId, 'repaired v1→v2 cutover after a crossed legacy launch; spawn authority remains fenced — use takeover');
+        }
+        catch (error) {
+            return authorityDenied(input, turnId, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (v2?.status === 'active' && v2.latest_generation.attempt_epoch === 0) {
+        if (activeRollout && localHome && contractRef) {
+            try {
+                bootstrapAttemptAuthorityV2({
+                    turn_id: turnId,
+                    authority_home: localHome,
+                    actor: input.dispatcher_agent_id ?? input.dispatcher_agent,
+                    writer_id: input.dispatcher_agent_id ?? input.dispatcher_agent,
+                    cwd: input.cwd,
+                    workspace_path: v2.latest_generation.workspace_path,
+                });
+            }
+            catch (error) {
+                return authorityDenied(input, turnId, error instanceof Error ? error.message : String(error));
+            }
+        }
+        return authorityDenied(input, turnId, 'generation zero launch is already crossed; use takeover for recovery');
+    }
+    if (input.accepted_execution_contract && !contractRef) {
+        return preconditionDenied('legacy uncontracted reservation cannot claim worker contract acceptance');
+    }
+    if (contractRef && !(v2?.status === 'active' && v2.latest_generation.attempt_epoch > 0)) {
+        let accepted;
+        try {
+            accepted = input.accepted_execution_contract
+                ?? attestHarnessContractAcceptance(contractRef, capabilitySnapshot, requestedHarnessBinding);
+        }
+        catch (error) {
+            return preconditionDenied(`worker contract acceptance unavailable before crossing: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const acceptance = validateWorkerContractAcceptance(contractRef, accepted, undefined);
+        if (acceptance.kind !== 'accepted') {
+            return preconditionDenied(`worker contract mismatch before crossing: expected ${contractRef.hash}/${contractRef.snapshot_hash}, accepted ${accepted.contract_hash}/${accepted.capability_snapshot_hash}; abort and reselect`);
+        }
+    }
+    // A takeover closes the old epoch and embeds a fresh active generation in
+    // close(epoch). Re-entering the common worker path projects that generation
+    // and contends on its immutable launch cell; the first caller wins spawn
+    // authority, every replay is adopted and MUST NOT spawn.
+    if (v2?.status === 'active' && v2.latest_generation.attempt_epoch > 0) {
+        const reservation = existingReservation;
+        if (!reservation || !localHome) {
+            return authorityDenied(input, turnId, 'AttemptAuthority v2 authority_home is unavailable');
+        }
+        try {
+            const generation = v2.latest_generation;
+            const generationContract = executionContractForGeneration(reservation, generation);
+            let accepted;
+            try {
+                accepted = input.accepted_execution_contract
+                    ?? attestHarnessContractAcceptance(generationContract.ref, reservation.capability_snapshot, requestedHarnessBinding);
+            }
+            catch (error) {
+                return preconditionDenied(`worker contract acceptance unavailable before crossing: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const acceptance = validateWorkerContractAcceptance(generationContract.ref, accepted, undefined);
+            if (acceptance.kind !== 'accepted') {
+                return preconditionDenied('worker rejected the active generation execution contract before crossing; abort and reselect');
+            }
+            ensureTurnExecutionProjections(reservation, {
+                loop_id: loop.id,
+                slot_id: input.slot_id,
+                turn_id: turnId,
+                assignment_id: generation.assignment_id,
+                run_id: generation.run_id,
+                agent: input.agent,
+                agent_id: input.agent_id,
+                dispatcher_agent: input.dispatcher_agent,
+                dispatcher_agent_id: input.dispatcher_agent_id,
+                dispatcher_session_id: input.dispatcher_session_id,
+                scope: input.scope,
+                description: input.description,
+                task: input.task,
+                worktree_path: generation.workspace_path,
+                assignment_tags: input.assignment_tags,
+                run_tags: [...(input.run_tags ?? ['turn-owned', 'loop']), `attempt-generation:${generation.attempt_epoch}`],
+                attempt_index: generation.attempt_epoch + 1,
+                execution_contract_ref: generationContract.ref,
+                capability_snapshot: reservation.capability_snapshot,
+                on_projection: input.on_projection,
+            }, input.cwd);
+            const crossing = crossActiveAttemptGenerationV2(turnId, generation.attempt_epoch, localHome, input.dispatcher_agent_id ?? input.dispatcher_agent, input.dispatcher_agent_id ?? input.dispatcher_agent, input.cwd);
+            if (!crossing.won)
+                return authorityDenied(input, turnId, 'attempt generation launch already crossed');
+            return {
+                kind: 'won',
+                turn_id: turnId,
+                assignment_id: generation.assignment_id,
+                run_id: generation.run_id,
+                nonce: generation.launch_nonce,
+                attempt_epoch: generation.attempt_epoch,
+                workspace_digest: generation.workspace_digest,
+                workspace_path: generation.workspace_path,
+                contract_status: 'contracted',
+                execution_contract_ref: generationContract.ref,
+                capability_snapshot: reservation.capability_snapshot,
+            };
+        }
+        catch (error) {
+            return authorityDenied(input, turnId, error instanceof Error ? error.message : String(error));
+        }
+    }
+    try {
+        const now = Date.now();
+        const prepared = prepareAttempt({
+            turn_id: turnId,
+            loop_id: loop.id,
+            slot_id: input.slot_id,
+            target_slot_generation: iteration,
+            loop_version_at_reserve: loop.version,
+            agent: input.agent,
+            agent_id: input.agent_id,
+            claim_id: input.claim_id,
+            phase: input.phase,
+            iteration,
+            completion_mode: effectiveCompletionMode,
+            expected_artifacts: effectiveExpectedArtifacts,
+            execution_contract: contract,
+            execution_contract_ref: contractRef,
+            capability_snapshot: contractRef ? capabilitySnapshot : undefined,
+            store_root: input.cwd,
+            cwd: input.cwd,
+            lease_deadline: new Date(now + dispatchLeaseMs).toISOString(),
+            grant_lease_deadline: new Date(now + grantLeaseMs).toISOString(),
+            authority_actor: input.dispatcher_agent_id ?? input.dispatcher_agent,
+            on_stage: input.on_authority_stage,
+        }, input.cwd);
+        if (prepared.launch_status !== 'armed') {
+            return authorityDenied(input, turnId, `launch grant is ${prepared.launch_status}`);
+        }
+        const crossing = projectAndCross(prepared, (reservation) => ensureTurnExecutionProjections(reservation, {
+            loop_id: loop.id,
+            slot_id: input.slot_id,
+            turn_id: turnId,
+            assignment_id: childIds.assignment_id,
+            run_id: childIds.run_id,
+            agent: input.agent,
+            agent_id: input.agent_id,
+            dispatcher_agent: input.dispatcher_agent,
+            dispatcher_agent_id: input.dispatcher_agent_id,
+            dispatcher_session_id: input.dispatcher_session_id,
+            scope: input.scope,
+            description: input.description,
+            task: input.task,
+            worktree_path: input.worktree_path,
+            assignment_tags: input.assignment_tags,
+            run_tags: input.run_tags,
+            on_projection: input.on_projection,
+        }, input.cwd), input.cwd, input.dispatcher_agent_id ?? input.dispatcher_agent);
+        if (crossing.kind !== 'won')
+            return authorityDenied(input, turnId, 'launch grant already crossed');
+        input.on_cutover_stage?.('legacy_crossed');
+        let generationFence = {};
+        if (activeRollout && localHome && contractRef) {
+            const generation = bootstrapAttemptAuthorityV2({
+                turn_id: turnId,
+                authority_home: localHome,
+                actor: input.dispatcher_agent_id ?? input.dispatcher_agent,
+                writer_id: input.dispatcher_agent_id ?? input.dispatcher_agent,
+                cwd: input.cwd,
+                workspace_path: input.worktree_path ?? input.cwd,
+                on_stage: (stage) => input.on_cutover_stage?.(stage === 'initial_anchored' ? 'initial_anchored' : 'v2_anchored'),
+            });
+            generationFence = {
+                attempt_epoch: generation.attempt_epoch,
+                workspace_digest: generation.workspace_digest,
+            };
+        }
+        return {
+            kind: 'won',
+            turn_id: turnId,
+            assignment_id: childIds.assignment_id,
+            run_id: childIds.run_id,
+            nonce: prepared.token,
+            contract_status: contractRef ? 'contracted' : 'legacy_uncontracted',
+            execution_contract_ref: contractRef,
+            capability_snapshot: contractRef ? capabilitySnapshot : undefined,
+            workspace_path: input.worktree_path ?? input.cwd,
+            ...generationFence,
+        };
+    }
+    catch (error) {
+        return authorityDenied(input, turnId, error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=turn-execution.js.map

package/dist/core/loops/types.js

@@ -312,6 +312,74 @@ export const REF_BASED_ARTIFACT_TYPES = new Set([
     'signals_report',
     'file_diff',
 ]);
+export const EVIDENCE_ATTESTATION_KINDS = ['claim', 'observation', 'verification', 'approval'];
+export const EVIDENCE_PRODUCER_KINDS = ['engine', 'slot', 'coordinator', 'operator'];
+export const EVIDENCE_CHANNELS = [
+    'complete_turn',
+    'reconcile_turn',
+    'verify_command',
+    'add_artifact',
+    'operator_input',
+    'system_hook',
+];
+export const EvidenceSubjectSchema = z.object({
+    loop_id: z.string().regex(/^lop_[0-9a-z]+$/),
+    artifact_id: z.string().min(1),
+    phase: z.string().min(1),
+    iteration: z.number().int().nonnegative(),
+    slot_id: z.string().optional(),
+    turn_id: z.string().optional(),
+    assignment_id: z.string().optional(),
+    claim_id: z.string().optional(),
+    run_id: z.string().optional(),
+    nonce_digest: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    attempt_epoch: z.number().int().nonnegative().optional(),
+    execution_contract_hash: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    command_digest: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    workspace_digest: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+});
+export const EvidenceProducerSchema = z.object({
+    kind: z.enum(EVIDENCE_PRODUCER_KINDS),
+    id: z.string().min(1),
+    agent_id: z.string().optional(),
+    channel: z.enum(EVIDENCE_CHANNELS),
+});
+export const EvidenceAttestationSchema = z.object({
+    kind: z.enum(EVIDENCE_ATTESTATION_KINDS),
+    issuer: z.string().min(1),
+    issued_at: z.string().datetime(),
+    subject_digest: z.string().regex(/^[0-9a-f]{64}$/),
+    rights: z.array(z.string().min(1)).min(1),
+});
+/**
+ * EvidenceEnvelope v1 is sealed by the loop engine at the artifact commit
+ * boundary. The seal is an integrity checksum, not a remote identity
+ * signature: ingress schemas never accept this object from a caller.
+ */
+export const EvidenceEnvelopeSchema = z.object({
+    version: z.literal(1),
+    evidence_id: z.string().regex(/^evd_[0-9a-z]+$/),
+    evidence_type: z.literal('artifact_commit'),
+    policy_version: z.literal('gate-policy-v1'),
+    subject: EvidenceSubjectSchema,
+    producer: EvidenceProducerSchema,
+    artifact_digest: z.string().regex(/^[0-9a-f]{64}$/),
+    issued_at: z.string().datetime(),
+    observed_at: z.string().datetime(),
+    validity: z.object({
+        not_before: z.string().datetime(),
+        not_after: z.string().datetime().optional(),
+    }),
+    attestations: z.array(EvidenceAttestationSchema).min(1),
+    seal: z.object({
+        algorithm: z.literal('sha256'),
+        digest: z.string().regex(/^[0-9a-f]{64}$/),
+    }),
+});
+export const EvidencePolicyBindingSchema = z.object({
+    version: z.literal('gate-policy-v1'),
+    mode: z.enum(['shadow', 'strict']),
+});
 /**
  * Lookup table mapping known artifact types to their body Zod schemas.
  * Step 2 handlers (request_input/provide_input) parse `artifact.body` as
@@ -339,6 +407,7 @@ export const REF_BASED_ARTIFACT_TYPES = new Set([
  */
 export const VerifyReportBodySchema = z.object({
     command: z.string().min(1),
+    command_argv: z.array(z.string()).min(1).optional(),
     exit_code: z.number().int().nullable(),
     passed: z.boolean(),
     duration_ms: z.number().int().nonnegative().optional(),
@@ -346,6 +415,9 @@ export const VerifyReportBodySchema = z.object({
     timed_out: z.boolean().optional(),
     stdout_tail: z.string().max(1024).optional(),
     stderr_tail: z.string().max(1024).optional(),
+    command_digest: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    workspace_digest: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    workspace_stable: z.boolean().optional(),
 });
 export const KNOWN_ARTIFACT_BODY_SCHEMAS = {
     // inline JSON body: body = JSON.stringify({ ...fields per OperatorQuestionBodySchema })
@@ -394,6 +466,14 @@ export const LoopArtifactSchema = z
      * at artifact creation time so callers don't have to track it.
      */
     iteration: z.number().int().nonnegative().optional(),
+    /**
+     * Explicit migration provenance. Optional on read so artifacts persisted
+     * before P2 remain valid; use artifactEvidenceProvenance() to infer their
+     * effective value without rewriting historical records.
+     */
+    provenance: z.enum(['legacy', 'attested']).optional(),
+    /** Server-sealed provenance and independent attestations (P2). */
+    evidence: EvidenceEnvelopeSchema.optional(),
 })
     .superRefine((artifact, ctx) => {
     if (artifact.body !== undefined && Buffer.byteLength(artifact.body, 'utf8') > LOOP_ARTIFACT_BODY_MAX_BYTES) {
@@ -500,6 +580,8 @@ export const LoopThreadSchema = z
     artifacts: z.array(LoopArtifactSchema),
     linked: LoopLinksSchema.optional(),
     stop_condition: StopConditionSchema.optional(),
+    /** Absent means a pre-policy/legacy thread. New loops bind this at open. */
+    evidence_policy: EvidencePolicyBindingSchema.optional(),
     /**
      * pln#508 step 1 — set of unresolved operator_question artifact ids.
      * The engine maintains this on every request_input / provide_input
@@ -580,6 +662,17 @@ const LoopEventBaseShape = {
     by: z.string().optional(),
     mutation_id: z.string().min(1),
 };
+export const GateDecisionSchema = z.object({
+    passed: z.boolean(),
+    /** Strict and legacy dimensions remain observable during a shadow rollout. */
+    strict_passed: z.boolean().optional(),
+    legacy_passed: z.boolean().optional(),
+    policy_version: z.enum(['legacy', 'gate-policy-v1']),
+    mode: z.enum(['legacy', 'shadow', 'strict']),
+    condition_digest: z.string().regex(/^[0-9a-f]{64}$/),
+    accepted_evidence_ids: z.array(z.string()),
+    rejected: z.array(z.object({ artifact_id: z.string(), reason: z.string() })),
+});
 export const LoopEventSchema = z.discriminatedUnion('kind', [
     z.object({
         ...LoopEventBaseShape,
@@ -594,6 +687,7 @@ export const LoopEventSchema = z.discriminatedUnion('kind', [
         to_phase: z.string().min(1),
         iteration: z.number().int().nonnegative(),
         reason: z.string().optional(),
+        gate_decision: GateDecisionSchema.optional(),
     }),
     z.object({
         ...LoopEventBaseShape,
@@ -615,6 +709,19 @@ export const LoopEventSchema = z.discriminatedUnion('kind', [
         phase: z.string().min(1),
         turn_id: z.string().min(1),
     }),
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('attempt_generation_changed'),
+        slot_id: z.string().min(1),
+        turn_id: z.string().min(1),
+        assignment_id: z.string().min(1),
+        from_epoch: z.number().int().nonnegative(),
+        to_epoch: z.number().int().positive(),
+        from_run_id: z.string().min(1),
+        to_run_id: z.string().min(1),
+        close_digest: z.string().regex(/^[a-f0-9]{64}$/),
+        cause: z.string().min(1),
+    }),
     z.object({
         ...LoopEventBaseShape,
         kind: z.literal('turn_completed'),
@@ -631,6 +738,7 @@ export const LoopEventSchema = z.discriminatedUnion('kind', [
         phase: z.string().min(1),
         type: z.string().min(1),
         produced_by: z.string().optional(),
+        evidence_id: z.string().optional(),
     }),
     z.object({
         ...LoopEventBaseShape,
@@ -651,6 +759,7 @@ export const LoopEventSchema = z.discriminatedUnion('kind', [
         kind: z.literal('closed'),
         final_status: z.enum(['completed', 'cancelled', 'blocked']),
         reason: z.string().optional(),
+        gate_decision: GateDecisionSchema.optional(),
     }),
     // pln#492 — system events emitted by the iteration / phase-advance gate.
     // Carried in the same event journal rather than as artifacts so consumers
@@ -660,6 +769,7 @@ export const LoopEventSchema = z.discriminatedUnion('kind', [
         kind: z.literal('phase_advance_blocked'),
         phase: z.string().min(1),
         gate_reason: z.string().min(1),
+        gate_decision: GateDecisionSchema.optional(),
     }),
     z.object({
         ...LoopEventBaseShape,
@@ -783,8 +893,9 @@ export const DEFAULT_PROTOCOLS = {
     },
     // pln#609 — implementation loop v2. The loop ADDS to the dispatch pipeline
     // what it lacked: a deterministic command_green gate + a bounded fix↔verify
-    // cycle + per-phase context sculpting. `bind` is an ENGINE action (bind
-    // plan+sequence and dispatch) not narration; execute↔verify iterates until
+    // cycle + per-phase context sculpting. `bind` is an engine-only link
+    // validation/advance; worker launch belongs to turn(dispatch=true).
+    // execute↔verify iterates until
     // the verify command is green (a passing verify_report this iteration) or
     // the cycle cap is hit (→ handoff_ready with the red report → blocked).
     implementation: {