deadbyte-mcp 0.8.10 → 0.10.0

package/src/autonomous-loop-state.mjs

@@ -0,0 +1,304 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+import { activePlanStep } from './autonomous-plan.mjs';
+
+export const AUTONOMOUS_LOOP_STATE_SCHEMA = 'deadbyte.autonomous-loop-state.v2';
+export const AUTONOMOUS_LOOP_PHASES = Object.freeze([
+  'PLAN','INSPECT','ACT','VERIFY','CRITIC','REPAIR','RELEASE','WAITING','SUCCEEDED','FAILED'
+]);
+
+const PHASES = new Set(AUTONOMOUS_LOOP_PHASES);
+const LEGACY_PHASES = new Map([
+  ['PLANNING','PLAN'],['INSPECTING','INSPECT'],['ACTING','ACT'],['VERIFYING','VERIFY'],
+  ['REPLANNING','REPAIR'],['WAITING','WAITING'],['COMPLETE','SUCCEEDED']
+]);
+const HEX64 = /^[0-9a-f]{64}$/;
+const ZERO_HASH = '0'.repeat(64);
+const FAILURE_CLASSES = new Set([
+  'verification_failure','stale_precondition','no_progress','insufficient_proof','provider_failure','other'
+]);
+const MUTABLE_TERMINAL_EVENTS = new Set([
+  'plan_created','plan_replanned','action_started','action_completed','inspection_completed','inspect_completed',
+  'progress_judged','critic_classified','repair_started','repair_completed','waiting_entered','waiting_resumed',
+  'native_diff_committed','step_completed','phase_changed'
+]);
+
+function sha256Object(value) {
+  return createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+}
+function hash(value,label) {
+  if (typeof value !== 'string' || !HEX64.test(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+function requireObject(value,label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+function requireText(value,label,max=1024) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > max) throw new Error(`${label} invalid`);
+  return value;
+}
+function normalizePhase(value,label) {
+  const normalized = LEGACY_PHASES.get(value) ?? value;
+  if (!PHASES.has(normalized)) throw new Error(`${label} invalid`);
+  return normalized;
+}
+function isLegacyPhase(value) { return LEGACY_PHASES.has(value) && !PHASES.has(value); }
+function terminal(phase) { return phase === 'SUCCEEDED' || phase === 'FAILED'; }
+
+function normalizedPlanForRepair(plan) {
+  if (!plan) return null;
+  return {
+    schema:plan.schema ?? null,
+    title:plan.title ?? null,
+    steps:Array.isArray(plan.steps) ? plan.steps.map(step => ({
+      step_id:step.step_id,
+      intent:step.intent,
+      status:step.status,
+      ...(Array.isArray(step.evidence) ? {evidence:step.evidence} : {})
+    })) : []
+  };
+}
+
+export function repairFingerprint({plan,hypothesis}) {
+  requireText(hypothesis,'repair hypothesis',2048);
+  return sha256Object({
+    schema:'deadbyte.autonomous-repair-fingerprint.v1',
+    hypothesis,
+    plan:normalizedPlanForRepair(plan)
+  });
+}
+
+function setPlan(state,plan,{replanned=false}={}) {
+  requireObject(plan,'loop plan');
+  const current = activePlanStep(plan);
+  state.plan = structuredClone(plan);
+  state.plan_id = hash(plan.plan_id,'loop plan_id');
+  if (!Number.isInteger(plan.plan_version) || plan.plan_version < 1) throw new Error('loop plan_version invalid');
+  state.plan_version = plan.plan_version;
+  state.current_step = current ? structuredClone(current) : null;
+  if (replanned) state.replan_count += 1;
+}
+
+function setPhase(state,rawFrom,rawTo) {
+  const from=normalizePhase(rawFrom,'loop phase from');
+  const to=normalizePhase(rawTo,'loop phase to');
+  if (state.phase !== from) throw new Error(`loop phase mismatch: journal says ${from} but derived phase is ${state.phase}`);
+  if (terminal(state.phase) && to !== state.phase) throw new Error(`loop ${state.phase} phase is terminal`);
+  const legacyTransition=isLegacyPhase(rawFrom)||isLegacyPhase(rawTo);
+  if (!legacyTransition && from === 'REPAIR' && ['ACT','INSPECT'].includes(to)) {
+    if (!state.repair?.completed || state.repair.previous_fingerprint === state.repair.repair_fingerprint) {
+      throw new Error('loop REPAIR requires repair fingerprint change before another ACT/INSPECT');
+    }
+  }
+  state.phase=to;
+  if (to !== 'WAITING') {
+    state.wait_reason=null;
+    state.pending_approval=false;
+  }
+}
+
+function classifyCritic(payload) {
+  const failureClass=requireText(payload.failure_class,'loop critic failure_class',64);
+  if (!FAILURE_CLASSES.has(failureClass)) throw new Error('loop critic failure_class invalid');
+  return {
+    failure_class:failureClass,
+    evidence_fingerprint:hash(payload.evidence_fingerprint,'loop critic evidence_fingerprint'),
+    detail:requireText(payload.detail,'loop critic detail',1024)
+  };
+}
+
+function repairStart(state,payload) {
+  if (state.phase !== 'REPAIR') throw new Error(`loop repair_started requires REPAIR phase, got ${state.phase}`);
+  const hypothesis=requireText(payload.hypothesis,'loop repair hypothesis',2048);
+  const previous=hash(payload.previous_fingerprint,'loop repair previous_fingerprint');
+  const expected=repairFingerprint({plan:state.plan,hypothesis});
+  if (previous !== expected) throw new Error('loop repair previous fingerprint mismatch');
+  state.repair={previous_fingerprint:previous,repair_fingerprint:null,hypothesis,completed:false};
+}
+
+function repairComplete(state,payload) {
+  if (state.phase !== 'REPAIR') throw new Error(`loop repair_completed requires REPAIR phase, got ${state.phase}`);
+  if (!state.repair) throw new Error('loop repair_completed requires repair_started');
+  const previous=hash(payload.previous_fingerprint,'loop repair completed previous_fingerprint');
+  const next=hash(payload.repair_fingerprint,'loop repair completed repair_fingerprint');
+  const hypothesis=requireText(payload.hypothesis,'loop repair completed hypothesis',2048);
+  if (previous !== state.repair.previous_fingerprint) throw new Error('loop repair previous fingerprint changed');
+  const expected=repairFingerprint({plan:state.plan,hypothesis});
+  if (next !== expected) throw new Error('loop repair fingerprint does not bind current plan/hypothesis');
+  if (next === previous) throw new Error('loop repair fingerprint must change before another ACT');
+  state.repair={previous_fingerprint:previous,repair_fingerprint:next,hypothesis,completed:true};
+}
+
+export function deriveLoopState(goal,events) {
+  requireObject(goal,'loop goal');
+  const goalId=hash(goal.goal_id,'loop goal_id');
+  if (!Array.isArray(events)) throw new Error('loop events must be an array');
+  const state={
+    schema:AUTONOMOUS_LOOP_STATE_SCHEMA,
+    phase:'PLAN',
+    plan:null,
+    plan_id:null,
+    plan_version:null,
+    current_step:null,
+    mutation_epoch:0,
+    planner_round:0,
+    replan_count:0,
+    pending_action:null,
+    pending_approval:false,
+    progress:null,
+    critic:null,
+    repair:null,
+    wait_reason:null,
+    evidence_head_sha256:null,
+    journal_head_sha256:ZERO_HASH
+  };
+
+  for (let index=0; index<events.length; index+=1) {
+    const event=requireObject(events[index],`loop event ${index+1}`);
+    if (event.goal_id !== goalId) throw new Error(`loop event ${index+1} goal mismatch`);
+    if (event.seq !== index+1) throw new Error(`loop event sequence mismatch at ${index+1}`);
+    hash(event.event_sha256,`loop event ${index+1} hash`);
+    const payload=event.payload===undefined?{}:requireObject(event.payload,`loop event ${index+1} payload`);
+
+    if (terminal(state.phase) && event.type !== 'release_completed' && event.type !== 'goal_cancelled') {
+      if (event.type === 'phase_changed') {
+        const to=normalizePhase(payload.to,'loop terminal phase to');
+        if (to !== state.phase) throw new Error(`loop ${state.phase} phase is terminal`);
+      } else if (MUTABLE_TERMINAL_EVENTS.has(event.type)) {
+        throw new Error(`loop ${state.phase} phase is terminal; event '${event.type}' is mutable`);
+      }
+    }
+
+    switch (event.type) {
+      case 'plan_created':
+        setPlan(state,payload.plan);
+        break;
+      case 'plan_replanned':
+        setPlan(state,payload.plan,{replanned:true});
+        break;
+      case 'step_completed':
+        if (payload.plan) setPlan(state,payload.plan);
+        break;
+      case 'phase_changed':
+        setPhase(state,payload.from,payload.to);
+        break;
+      case 'inspection_completed':
+      case 'inspect_completed':
+        if (payload.evidence_head_sha256 !== undefined) {
+          state.evidence_head_sha256=hash(payload.evidence_head_sha256,'loop evidence head');
+        }
+        break;
+      case 'action_started': {
+        const actionId=hash(payload.action_id,'loop action_id');
+        const requestSha=hash(payload.request_sha256,'loop action request_sha256');
+        if (state.pending_action) throw new Error('loop action_started while another action is pending');
+        state.pending_action={...structuredClone(payload),action_id:actionId,request_sha256:requestSha};
+        break;
+      }
+      case 'action_completed':
+        if (state.pending_action && payload.action_id !== state.pending_action.action_id) {
+          throw new Error('loop action completion identity mismatch');
+        }
+        if (payload.action_id !== undefined) hash(payload.action_id,'loop completed action_id');
+        state.pending_action=null;
+        break;
+      case 'action_reconciled':
+        if (payload.action_id !== undefined) hash(payload.action_id,'loop reconciled action_id');
+        break;
+      case 'progress_judged':
+        if (!['progress','stalled','regressed'].includes(payload.verdict)) throw new Error('loop progress verdict invalid');
+        state.progress=structuredClone(payload);
+        break;
+      case 'critic_classified':
+        state.critic=classifyCritic(payload);
+        break;
+      case 'repair_started':
+        repairStart(state,payload);
+        break;
+      case 'repair_completed':
+        repairComplete(state,payload);
+        break;
+      case 'waiting_entered':
+        state.phase='WAITING';
+        state.wait_reason=requireText(payload.reason,'loop wait reason');
+        state.pending_approval=payload.requires_approval===true;
+        break;
+      case 'waiting_resumed': {
+        if (state.phase !== 'WAITING') throw new Error('loop waiting_resumed outside WAITING phase');
+        const resumed=payload.to===undefined?'PLAN':normalizePhase(payload.to,'loop resume phase');
+        if (resumed === 'WAITING' || terminal(resumed)) throw new Error('loop waiting resume target invalid');
+        state.phase=resumed;
+        state.wait_reason=null;
+        state.pending_approval=false;
+        break;
+      }
+      case 'planner_requested':
+      case 'planner_decision':
+        if (Number.isInteger(payload.planner_round) && payload.planner_round >= 0) {
+          state.planner_round=Math.max(state.planner_round,payload.planner_round);
+        }
+        break;
+      case 'native_diff_committed':
+        if (!Number.isInteger(payload.mutation_epoch) || payload.mutation_epoch < state.mutation_epoch) {
+          throw new Error('loop mutation_epoch invalid');
+        }
+        state.mutation_epoch=payload.mutation_epoch;
+        break;
+      case 'goal_paused':
+        state.phase='WAITING';
+        state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'paused';
+        state.pending_approval=true;
+        break;
+      case 'goal_resumed':
+        if (state.phase === 'WAITING') {
+          state.phase='PLAN';
+          state.wait_reason=null;
+          state.pending_approval=false;
+        }
+        break;
+      case 'goal_cancelled':
+        state.phase='FAILED';
+        state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'cancelled';
+        state.pending_approval=false;
+        state.pending_action=null;
+        break;
+      case 'goal_failed':
+        state.phase='FAILED';
+        state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'failed';
+        state.pending_approval=false;
+        state.pending_action=null;
+        break;
+      case 'release_completed':
+        state.phase='SUCCEEDED';
+        state.wait_reason=null;
+        state.pending_approval=false;
+        state.pending_action=null;
+        break;
+      default:
+        break;
+    }
+    state.journal_head_sha256=event.event_sha256;
+  }
+
+  if (state.plan) state.current_step=activePlanStep(state.plan);
+  return state;
+}
+
+export function deriveTodoProjection(goal,events) {
+  const state=deriveLoopState(goal,events);
+  return Object.freeze({
+    schema:'deadbyte.autonomous-todo-projection.v1',
+    goal_id:goal.goal_id,
+    phase:state.phase,
+    plan_id:state.plan_id,
+    plan_version:state.plan_version,
+    journal_head_sha256:state.journal_head_sha256,
+    items:Object.freeze((state.plan?.steps ?? []).map(step => Object.freeze({
+      step_id:step.step_id,
+      intent:step.intent,
+      status:step.status,
+      ...(Array.isArray(step.evidence) ? {evidence:structuredClone(step.evidence)} : {})
+    })))
+  });
+}

package/src/autonomous-mcp-tools.mjs

@@ -18,7 +18,11 @@ const replaceOperation = z.strictObject({ kind:z.literal('replace'), path:relPat
   expected_sha256:hex64, old_string:z.string().min(1).max(262144), new_string:z.string().max(524288),
   expected_replacements:z.number().int().min(1).max(64).default(1) });
 const deleteOperation = z.strictObject({ kind:z.literal('delete'), path:relPath, expected_sha256:hex64 });
-const nativeOperation = z.union([writeOperation,replaceOperation,deleteOperation]);
+const mkdirOperation = z.strictObject({ kind:z.literal('mkdir'), path:relPath });
+const moveOperation = z.strictObject({ kind:z.literal('move'), source_path:relPath, destination_path:relPath,
+  expected_source_identity:hex64, expected_destination_identity:z.union([z.literal('absent'),hex64]).default('absent') });
+const rmdirOperation = z.strictObject({ kind:z.literal('rmdir'), path:relPath, expected_source_identity:hex64 });
+const nativeOperation = z.union([writeOperation,replaceOperation,deleteOperation,mkdirOperation,moveOperation,rmdirOperation]);
 const plannerResponse = z.strictObject({ request_id:hex64, raw_text:z.string().min(2).max(8*1024*1024),
   model:z.string().min(1).max(128).default('client-model') });
 function result(schema,value,isError=false) { return autonomousStructuredResult(schema,value,isError); }

package/src/autonomous-output-contracts.mjs

@@ -4,6 +4,24 @@ const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
 const goalId = hex64;
 const jsonObject = z.record(z.string(),z.json());
 const goalState = z.enum(['pending','running','paused','cancelled','succeeded']);
+const loopPhase = z.enum(['PLANNING','INSPECTING','ACTING','VERIFYING','REPLANNING','WAITING','COMPLETE']);
+const loopStep = z.strictObject({
+  step_id:z.string().regex(/^[A-Za-z0-9._-]{1,64}$/), intent:z.string().min(1).max(512), status:z.literal('active')
+});
+const loopProgress = z.strictObject({
+  verdict:z.enum(['progress','stalled','regressed']), score:z.number(),
+  reason_codes:z.array(z.string().regex(/^[A-Za-z0-9._-]{1,64}$/)).max(32), fingerprint:hex64
+});
+const loopPendingAction = z.strictObject({
+  action_id:hex64, request_sha256:hex64, kind:z.string().regex(/^[A-Za-z0-9._-]{1,64}$/)
+});
+const publicLoopSchema = z.strictObject({
+  schema:z.literal('deadbyte.autonomous-loop-state.v1'), phase:loopPhase,
+  plan_id:hex64.nullable(), plan_version:z.number().int().min(1).nullable(),
+  current_step:loopStep.nullable(), replan_count:z.number().int().min(0),
+  progress:loopProgress.nullable(), pending_action:loopPendingAction.nullable(),
+  pending_approval:z.boolean(), wait_reason:z.string().min(1).max(1024).nullable()
+});
 function requireFields(value,ctx,fields) {
   for (const field of fields) if (value[field] === undefined) ctx.addIssue({ code:'custom', path:[field], message:`${field} is required` });
 }
@@ -40,21 +58,21 @@ export const autonomousSessionStatusOutputSchema = statusContract({
 
 export const nativeDiffPreviewOutputSchema = statusContract({
   statuses:['ready','failed'], success:['ready'], required:['diff_id','root_id','operation_count','payload_bytes','paths','operations'],
-  shape:{ diff_id:hex64.optional(), root_id:z.string().min(1).max(64).optional(), operation_count:z.number().int().min(1).max(32).optional(),
-    payload_bytes:z.number().int().min(0).optional(), paths:z.array(z.string()).max(32).optional(),
+  shape:{ schema:z.enum(['deadbyte.native-diff.v1','deadbyte.native-diff.v2']).optional(), diff_id:hex64.optional(), root_id:z.string().min(1).max(64).optional(), operation_count:z.number().int().min(1).max(32).optional(),
+    payload_bytes:z.number().int().min(0).optional(), paths:z.array(z.string()).max(64).optional(),
     operations:z.array(jsonObject).max(32).optional() }
 });
 export const nativeDiffApplyOutputSchema = statusContract({
   statuses:['committed','existing','failed'], success:['committed','existing'],
   required:['diff_id','receipt_sha256','operation_count'],
   shape:{ diff_id:hex64.optional(), receipt_sha256:hex64.optional(), operation_count:z.number().int().min(1).max(32).optional(),
-    current_state_matches:z.boolean().optional(), coding_receipts:z.array(jsonObject).max(32).optional() }
+    current_state_matches:z.boolean().optional(), coding_receipts:z.array(jsonObject).max(32).optional(), operation_receipts:z.array(jsonObject).max(32).optional() }
 });
 export const nativeDiffVerifyOutputSchema = z.strictObject({
   status:z.literal('failed').optional(), error:z.string().optional(), ok:z.boolean().optional(), reason:z.string().optional(),
   diff_id:hex64.optional(), receipt_sha256:hex64.optional(), signature_valid:z.literal(true).optional(),
   root_id:z.string().min(1).max(64).optional(), operation_count:z.number().int().min(1).max(32).optional(),
-  coding_receipts_verified:z.number().int().min(0).max(32).optional(), final_states:z.array(jsonObject).max(32).optional(),
+  coding_receipts_verified:z.number().int().min(0).max(32).optional(), operation_receipts_verified:z.number().int().min(0).max(32).optional(), final_states:z.array(jsonObject).max(32).optional(),
   current_state_matches:z.boolean().optional(), journal_head_sha256:hex64.optional()
 }).superRefine((value,ctx) => {
   if (value.status === 'failed') { requireFields(value,ctx,['error']); return; }
@@ -72,7 +90,8 @@ export const autonomousGoalSubmitOutputSchema = statusContract({
 const runShape = Object.fromEntries(Object.entries(derivedShape).map(([key,schema]) => [key,schema.optional()]));
 export const autonomousGoalRunOutputSchema = z.strictObject({
   status:z.enum(['terminal','paused','cancelled','completed','yielded','running','input_required','failed']), error:z.string().optional(),
-  goal_id:goalId.optional(), release:jsonObject.optional(), planner_request:jsonObject.optional(), ...runShape
+  goal_id:goalId.optional(), release:jsonObject.optional(), planner_request:jsonObject.optional(), loop:publicLoopSchema.optional(),
+  cycles:z.number().int().min(1).max(32).optional(), ...runShape
 }).superRefine((value,ctx) => {
   if (value.error !== undefined) { if (value.status !== 'failed') ctx.addIssue({code:'custom',path:['error'],message:'error wrapper requires failed'}); return; }
   requireFields(value,ctx,['goal_id',...Object.keys(derivedShape)]);
@@ -81,7 +100,7 @@ export const autonomousGoalRunOutputSchema = z.strictObject({
 export const autonomousGoalStatusOutputSchema = statusContract({
   statuses:['ok','failed'], success:['ok'], required:['goal_id','goal_sha256','title','root_id','journal_verified',...Object.keys(derivedShape)],
   shape:{ goal_id:goalId.optional(), goal_sha256:hex64.optional(), title:z.string().optional(), root_id:z.string().optional(),
-    journal_verified:z.literal(true).optional(), ...runShape }
+    journal_verified:z.literal(true).optional(), loop:publicLoopSchema.optional(), ...runShape }
 });
 export const autonomousGoalEventsOutputSchema = statusContract({
   statuses:['ok','failed'], success:['ok'], required:['goal_id','journal_verified','journal_head_sha256','events'],
@@ -94,7 +113,7 @@ export const autonomousGoalCancelOutputSchema = statusContract({
 });
 export const autonomousGoalApproveOutputSchema = statusContract({
   statuses:['terminal','approved','rejected','failed'], success:['terminal','approved','rejected'], required:['goal_id','state'],
-  shape:{ goal_id:goalId.optional(), state:goalState.optional() }
+  shape:{ goal_id:goalId.optional(), state:goalState.optional(), loop:publicLoopSchema.optional() }
 });
 export const autonomousReleaseGateOutputSchema = statusContract({
   statuses:['blocked','paused','failed','passed','existing','error'], success:['blocked','paused','failed','passed','existing'],

package/src/autonomous-plan.mjs

@@ -0,0 +1,181 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+export const AUTONOMOUS_PLAN_SCHEMA = 'deadbyte.autonomous-plan.v1';
+const PLAN_ID_SCHEMA = 'deadbyte.autonomous-plan-id.v1';
+const HEX64 = /^[0-9a-f]{64}$/;
+const ID = /^[A-Za-z0-9._-]{1,64}$/;
+
+function sha256Object(value) {
+  return createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+}
+
+function text(value,label,max) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > max) throw new Error(`${label} invalid`);
+  return value;
+}
+
+function id(value,label) {
+  if (typeof value !== 'string' || !ID.test(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+
+function hash(value,label) {
+  if (typeof value !== 'string' || !HEX64.test(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+
+function normalizeEvidence(evidence) {
+  if (!Array.isArray(evidence) || evidence.length < 1 || evidence.length > 32) {
+    throw new Error('plan step completion evidence required');
+  }
+  return evidence.map((item,index) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error(`plan evidence ${index} invalid`);
+    const keys = Object.keys(item).sort();
+    if (canonicalJson(keys) !== canonicalJson(['id','kind','sha256'])) throw new Error(`plan evidence ${index} fields invalid`);
+    return {
+      kind:id(item.kind,`plan evidence ${index} kind`),
+      id:id(item.id,`plan evidence ${index} id`),
+      sha256:hash(item.sha256,`plan evidence ${index} sha256`)
+    };
+  });
+}
+
+function normalizeStepIdentity(raw,index) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`plan step ${index} invalid`);
+  return {
+    step_id:id(raw.step_id,`plan step ${index} step_id`),
+    intent:text(raw.intent,`plan step ${index} intent`,512)
+  };
+}
+
+function assertUniqueStepIds(steps) {
+  const seen = new Set();
+  for (const step of steps) {
+    if (seen.has(step.step_id)) throw new Error(`plan step_id '${step.step_id}' duplicated`);
+    seen.add(step.step_id);
+  }
+}
+
+function assertPlan(plan) {
+  if (!plan || typeof plan !== 'object' || Array.isArray(plan) || plan.schema !== AUTONOMOUS_PLAN_SCHEMA) {
+    throw new Error('autonomous plan schema invalid');
+  }
+  hash(plan.plan_id,'plan_id');
+  if (!Number.isInteger(plan.plan_version) || plan.plan_version < 1) throw new Error('plan_version invalid');
+  if (plan.parent_plan_version !== null && (!Number.isInteger(plan.parent_plan_version) || plan.parent_plan_version < 1 || plan.parent_plan_version >= plan.plan_version)) {
+    throw new Error('parent_plan_version invalid');
+  }
+  text(plan.title,'plan title',160);
+  hash(plan.reason_sha256,'plan reason_sha256');
+  if (!Array.isArray(plan.steps) || plan.steps.length < 1 || plan.steps.length > 24) throw new Error('plan steps invalid');
+  assertUniqueStepIds(plan.steps);
+  let active = 0;
+  let seenMutable = false;
+  let seenPending = false;
+  for (const [index,step] of plan.steps.entries()) {
+    const identity = normalizeStepIdentity(step,index);
+    if (identity.step_id !== step.step_id || identity.intent !== step.intent) throw new Error(`plan step ${index} identity invalid`);
+    if (!['pending','active','completed'].includes(step.status)) throw new Error(`plan step ${index} status invalid`);
+    if (step.status === 'completed') {
+      if (seenMutable) throw new Error('plan completed steps must form an immutable prefix');
+      normalizeEvidence(step.evidence);
+    } else {
+      seenMutable = true;
+      if (step.evidence !== undefined) throw new Error(`plan step ${index} evidence requires completed status`);
+      if (step.status === 'active') {
+        if (seenPending || active > 0) throw new Error('plan may have at most one active step before pending suffix');
+        active += 1;
+      } else {
+        seenPending = true;
+      }
+    }
+  }
+  const complete = plan.steps.every(step => step.status === 'completed');
+  if (!complete && active !== 1) throw new Error('incomplete plan requires exactly one active step');
+  if (complete && active !== 0) throw new Error('complete plan cannot have active step');
+  return plan;
+}
+
+function completedPrefixLength(plan) {
+  let count = 0;
+  for (const step of plan.steps) {
+    if (step.status !== 'completed') break;
+    count += 1;
+  }
+  return count;
+}
+
+function normalizeSuffixStep(raw,index,status) {
+  const step = normalizeStepIdentity(raw,index);
+  if (raw.evidence !== undefined) throw new Error(`replan suffix step '${step.step_id}' cannot carry completion evidence`);
+  return { ...step, status };
+}
+
+export function createPlan({ goalId, title, steps, reasonHash }) {
+  hash(goalId,'goalId');
+  text(title,'plan title',160);
+  hash(reasonHash,'reasonHash');
+  if (!Array.isArray(steps) || steps.length < 1 || steps.length > 24) throw new Error('plan steps invalid');
+  const normalized = steps.map((step,index) => ({ ...normalizeStepIdentity(step,index), status:index === 0 ? 'active' : 'pending' }));
+  assertUniqueStepIds(normalized);
+  return assertPlan({
+    schema:AUTONOMOUS_PLAN_SCHEMA,
+    plan_id:sha256Object({ schema:PLAN_ID_SCHEMA, goal_id:goalId }),
+    plan_version:1,
+    parent_plan_version:null,
+    title,
+    steps:normalized,
+    reason_sha256:reasonHash
+  });
+}
+
+export function replanPlan(previous,{ steps, reasonHash }) {
+  assertPlan(previous);
+  hash(reasonHash,'reasonHash');
+  if (!Array.isArray(steps) || steps.length < 1 || steps.length > 24) throw new Error('replan steps invalid');
+  const locked = completedPrefixLength(previous);
+  if (steps.length < locked) throw new Error('replan cannot remove completed prefix');
+  for (let index = 0; index < locked; index += 1) {
+    if (canonicalJson(steps[index]) !== canonicalJson(previous.steps[index])) {
+      throw new Error(`replan cannot modify completed prefix step '${previous.steps[index].step_id}'`);
+    }
+  }
+  if (steps.length === locked) throw new Error('replan requires an active or pending suffix');
+  const completed = previous.steps.slice(0,locked).map(step => structuredClone(step));
+  const suffix = steps.slice(locked).map((step,index) => normalizeSuffixStep(step,locked + index,index === 0 ? 'active' : 'pending'));
+  const combined = [...completed,...suffix];
+  assertUniqueStepIds(combined);
+  return assertPlan({
+    schema:AUTONOMOUS_PLAN_SCHEMA,
+    plan_id:previous.plan_id,
+    plan_version:previous.plan_version + 1,
+    parent_plan_version:previous.plan_version,
+    title:previous.title,
+    steps:combined,
+    reason_sha256:reasonHash
+  });
+}
+
+export function completePlanStep(previous,{ stepId, evidence }) {
+  assertPlan(previous);
+  id(stepId,'stepId');
+  const activeIndex = previous.steps.findIndex(step => step.status === 'active');
+  if (activeIndex < 0) throw new Error('plan has no active step to complete');
+  if (previous.steps[activeIndex].step_id !== stepId) throw new Error(`plan step '${stepId}' is not active`);
+  const checkedEvidence = normalizeEvidence(evidence);
+  const steps = previous.steps.map(step => structuredClone(step));
+  steps[activeIndex] = { ...steps[activeIndex], status:'completed', evidence:checkedEvidence };
+  if (activeIndex + 1 < steps.length) steps[activeIndex + 1] = { ...steps[activeIndex + 1], status:'active' };
+  return assertPlan({ ...previous, steps });
+}
+
+export function planIsComplete(plan) {
+  assertPlan(plan);
+  return plan.steps.every(step => step.status === 'completed');
+}
+
+export function activePlanStep(plan) {
+  assertPlan(plan);
+  return plan.steps.find(step => step.status === 'active') ?? null;
+}

package/src/autonomous-planner-contracts.mjs

@@ -71,3 +71,82 @@ export function parseStrictJsonText(schema, text, label) {
   if (!checked.success) throw new Error(`${label} response contract mismatch`);
   return checked.data;
 }
+
+const r34PlanStepSchema = z.strictObject({
+  step_id:z.string().regex(ID),
+  intent:z.string().min(1).max(512)
+});
+const r34EvidenceSchema = z.strictObject({
+  kind:z.string().regex(ID),
+  id:z.string().regex(ID),
+  sha256:z.string().regex(HEX64)
+});
+const r34PatchOperationSchema = z.discriminatedUnion('kind',[
+  z.strictObject({kind:z.literal('write'),path:relPath,content:z.string().max(524288),
+    encoding:z.enum(['utf8','base64']).default('utf8'),expected_sha256:z.string().regex(/^(?:absent|[0-9a-f]{64})$/)}),
+  z.strictObject({kind:z.literal('replace'),path:relPath,old_string:z.string().min(1).max(262144),
+    new_string:z.string().max(524288),expected_sha256:z.string().regex(HEX64),
+    expected_replacements:z.number().int().min(1).max(64).default(1)}),
+  z.strictObject({kind:z.literal('delete'),path:relPath,expected_sha256:z.string().regex(HEX64)})
+]);
+const plannerCursor=z.string().max(4096).nullable().default(null);
+const plannerFiles=z.array(z.strictObject({path:relPath,encoding:z.enum(['utf8','base64']).default('utf8')})).min(1).max(32);
+const plannerSemanticPosition={path:relPath,line:z.number().int().min(0),column:z.number().int().min(0)};
+const r36TypedActionSchemas=[
+  z.strictObject({kind:z.literal('search'),path:relPath.default('.'),target:z.enum(['content','path']).default('content'),mode:z.enum(['literal','regex']).default('literal'),pattern:z.string().min(1).max(256),case_sensitive:z.boolean().default(false),max_results:z.number().int().min(1).max(1000).default(200),max_file_bytes:z.number().int().min(1).max(4194304).default(262144),max_scan_bytes:z.number().int().min(1).max(67108864).default(4194304),page_size:z.number().int().min(1).max(500).default(100),cursor:plannerCursor}),
+  z.strictObject({kind:z.literal('stat'),path:relPath.default('.'),hash:z.boolean().default(false)}),
+  z.strictObject({kind:z.literal('multi_read'),files:plannerFiles,max_total_bytes:z.number().int().min(1).max(2097152).default(1048576)}),
+  z.strictObject({kind:z.literal('semantic_outline'),path:relPath,max_symbols:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({kind:z.literal('semantic_definition'),...plannerSemanticPosition,max_results:z.number().int().min(1).max(200).default(50)}),
+  z.strictObject({kind:z.literal('semantic_references'),...plannerSemanticPosition,max_results:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({kind:z.literal('semantic_diagnostics'),path:relPath,max_results:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({kind:z.literal('semantic_implementations'),...plannerSemanticPosition,max_results:z.number().int().min(1).max(500).default(200)}),
+  z.strictObject({kind:z.literal('semantic_rename_preview'),...plannerSemanticPosition,new_name:z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/)}),
+  z.strictObject({kind:z.literal('native_diff_apply'),diff_id:z.string().regex(HEX64),expected_operation_count:z.number().int().min(1).max(32)}),
+  z.strictObject({kind:z.literal('native_diff_verify'),diff_id:z.string().regex(HEX64)}),
+  z.strictObject({kind:z.literal('process_start'),profile_id:z.string().regex(ID),cwd:relPath.default('.'),args:z.array(z.string().max(2048)).max(64).default([])}),
+  z.strictObject({kind:z.literal('process_read'),session_id:z.string().regex(HEX64),offset:z.number().int().min(0).default(0),max_bytes:z.number().int().min(1).max(262144).default(65536)}),
+  z.strictObject({kind:z.literal('process_status'),session_id:z.string().regex(HEX64)}),
+  z.strictObject({kind:z.literal('process_list')}),
+  z.strictObject({kind:z.literal('process_action'),session_id:z.string().regex(HEX64),action_id:z.string().regex(ID)}),
+  z.strictObject({kind:z.literal('process_terminate'),session_id:z.string().regex(HEX64)}),
+  z.strictObject({kind:z.literal('machine_fs_stat'),path:relPath.default('.'),hash:z.boolean().default(false)}),
+  z.strictObject({kind:z.literal('machine_fs_list'),path:relPath.default('.'),cursor:plannerCursor,limit:z.number().int().min(1).max(1000).default(100),hash_files:z.boolean().default(false)}),
+  z.strictObject({kind:z.literal('machine_fs_read'),path:relPath,offset:z.number().int().min(0).default(0),max_bytes:z.number().int().min(1).max(4194304).default(65536),hash_file:z.boolean().default(false)}),
+  z.strictObject({kind:z.literal('machine_fs_mkdir'),path:relPath}),
+  z.strictObject({kind:z.literal('machine_fs_move'),source_path:relPath,destination_path:relPath,expected_source_identity:z.string().regex(HEX64)}),
+  z.strictObject({kind:z.literal('machine_fs_delete'),path:relPath,expected_source_identity:z.string().regex(HEX64)}),
+  z.strictObject({kind:z.literal('observation_search_start'),path:relPath.default('.'),pattern:z.string().min(1).max(256),case_sensitive:z.boolean().default(false),max_results:z.number().int().min(1).max(1000).default(200),max_files:z.number().int().min(1).max(10000).default(2000),max_bytes:z.number().int().min(1).max(67108864).default(4194304),max_file_bytes:z.number().int().min(1).max(4194304).default(262144)}),
+  z.strictObject({kind:z.literal('observation_search_status'),search_id:z.string().regex(HEX64)}),
+  z.strictObject({kind:z.literal('observation_search_page'),search_id:z.string().regex(HEX64),cursor:plannerCursor,limit:z.number().int().min(1).max(500).default(100)}),
+  z.strictObject({kind:z.literal('observation_search_cancel'),search_id:z.string().regex(HEX64)}),
+  z.strictObject({kind:z.literal('observation_process_list'),include_external:z.boolean().default(false),cursor:plannerCursor,limit:z.number().int().min(1).max(256).default(100)}),
+  z.strictObject({kind:z.literal('observation_system_status')})
+];
+const r34ActionSchema = z.discriminatedUnion('kind',[
+  z.strictObject({kind:z.literal('patch'),operations:z.array(r34PatchOperationSchema).min(1).max(32)}),
+  z.strictObject({kind:z.literal('run_profile'),profile_id:z.string().regex(ID)}),
+  z.strictObject({kind:z.literal('delegate'),operation:z.record(z.string(),z.json())}),
+  ...r36TypedActionSchemas
+]);
+const r34ReadSchema = z.strictObject({
+  path:relPath,
+  max_bytes:z.number().int().min(1).max(262144).default(65536)
+});
+
+export const r34PlannerDecisionSchema = z.discriminatedUnion('kind',[
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('plan_create'),
+    title:z.string().min(1).max(160),reason:z.string().min(1).max(512).optional(),
+    steps:z.array(r34PlanStepSchema).min(1).max(24)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('inspect'),
+    reads:z.array(r34ReadSchema).min(1).max(8)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('act'),action:r34ActionSchema}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('step_complete'),
+    step_id:z.string().regex(ID),evidence:z.array(r34EvidenceSchema).min(1).max(32)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('replan'),
+    reason:z.string().min(1).max(512),steps:z.array(r34PlanStepSchema).min(1).max(24)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('pause'),
+    reason:z.string().min(1).max(1000)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('finish'),
+    summary:z.string().min(1).max(1024).optional()})
+]);