refactor(todo): unify claim decision in TypeScript (#3972)

Signed-off-by: huangruiteng <huangrt01@163.com>

Author: huangruiteng

docs/architecture/rfcs/shared-goal-authority-state-provider-v0.md

@@ -2387,6 +2387,13 @@ export and cleanup. Each slice must prove an end-to-end transaction, not merely
 another schema identifier consolidation. Native contract acceptance alone is
 not permission to bypass any promotion hold.
 
+The first replacement-first `claim` slice routes both the default Markdown
+writer and the promoted provider transaction through one TypeScript decision.
+Python's default path retains only locked commit and existing projection-
+compatibility duties. This closes duplicate claim policy; it neither promotes
+Markdown to authority nor replaces the remaining unified
+create/update/complete/archive transactions and projection outbox.
+
 Use file-v0 for bounded conformance and import rehearsal only. Start the
 Section 7.2 embedded-store slice alongside the provider-first Todo caller; both
 converge before long-goal local qualification and promotion. PostgreSQL

docs/architecture/rfcs/shared-goal-authority-state-provider-v0.zh-CN.md

@@ -1893,6 +1893,11 @@ kernel 的近期顺序是：（1）真实 provider-first Todo lifecycle caller
 transaction，不能只做另一轮 schema identifier 统一。接受 native contract 不等于
 可以绕过任何 promotion hold。
 
+`claim` 的第一个 replacement-first 切片把默认 Markdown writer 与 promotion 后的
+provider transaction 接到同一个 TS decision；Python 默认路径只保留持锁提交和既有
+投影兼容职责。它关闭 claim policy 的双实现，但不把 Markdown 提升为 authority，
+也不替代剩余 create/update/complete/archive 的统一 transaction 与 projection outbox。
+
 file-v0 只用于有界 conformance 与 import 演练。第 7.2 节嵌入式存储切片与 provider-first
 Todo caller 同时推进，在长程本地资格化与晋升前汇合。PostgreSQL service/deployment
 继续并行，不成为本地晋升的依赖；NoKV 独立通过自己的 lineage/recovery 资格门禁。

docs/architecture/rfcs/typescript-control-plane-migration-v0.md

@@ -31,7 +31,11 @@ native creation, archival, receipt replay, and store reopen are tested without
 Markdown metadata. Python only adapts the typed read result to the compatibility
 summary. This is a contract checkpoint, not a completed CLI lifecycle cutover.
 
-After explicit promotion, `todo claim` now crosses once into a TS-owned
+The default Markdown and explicitly promoted `todo claim` paths now share one
+TypeScript claim decision for actor, registration, role, status, archive,
+exclusion, and existing-owner checks; the Python legacy writer only commits
+that decision while holding its lock. After explicit promotion, claim crosses
+once into the same TS-owned
 transaction for both native and v0 records. New claims require active, open
 Todos and the current actor/lease checks. Exact operation retries recover the
 original claim receipt before current-state eligibility; observation time and

docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md

@@ -28,7 +28,10 @@ coordination 路径使用同一份语言中立的 `coordination_state_contract_v
 仅将 typed read result 适配为兼容 summary。这是 contract 检查点，不是已经完成的
 CLI lifecycle cutover。
 
-显式 promotion 后，`todo claim` 现在只跨一次 runtime 边界，由 TS 事务同时处理原生
+默认 Markdown 与显式 promotion 两条 `todo claim` 路径现在都由同一个 TS claim
+decision 处理 actor、registration、role、status、archive、exclusion 与现有 owner
+检查；Python legacy writer 只在持锁后提交该 decision。显式 promotion 后，claim
+只跨一次 runtime 边界，由同一 TS 事务同时处理原生
 和 v0 记录。新 claim 要求 active、open Todo，并检查当前 actor/lease；同一 operation
 的重试先恢复原 claim receipt，再考虑当前资格。观测时间和当前注册信息不属于请求
 身份。回放 receipt 不续租，也不表示当前仍持有任务。非 preview 的成功 `no_change`

loopx/control_plane/coordination/todo_claim.ts

@@ -16,6 +16,8 @@ export const COORDINATION_TODO_CLAIM_RESULT_SCHEMA =
   "loopx_coordination_todo_claim_result_v0";
 export const COORDINATION_TODO_CLAIM_RECEIPT_SCHEMA =
   "loopx_coordination_todo_claim_receipt_v0";
+export const COORDINATION_TODO_CLAIM_DECISION_SCHEMA =
+  "loopx_coordination_todo_claim_decision_v0";
 
 export interface CoordinationTodoClaimInput {
   readonly goal_id: string;
@@ -33,6 +35,28 @@ export type CoordinationTodoClaimResult = JsonObject & {
   readonly schema_version: typeof COORDINATION_TODO_CLAIM_RESULT_SCHEMA;
 };
 
+export interface CoordinationTodoClaimAcceptedDecision extends JsonObject {
+  readonly schema_version: typeof COORDINATION_TODO_CLAIM_DECISION_SCHEMA;
+  readonly status: "accepted";
+  readonly owner: string;
+  readonly actor: string | null;
+  readonly mode: "single_agent_compatibility" | "registered_peer_actor";
+  readonly mutation_authority: JsonObject;
+}
+
+export interface CoordinationTodoClaimRejectedDecision extends JsonObject {
+  readonly schema_version: typeof COORDINATION_TODO_CLAIM_DECISION_SCHEMA;
+  readonly status: "rejected";
+  readonly reason_code: string;
+  readonly reason: string;
+}
+
+export type CoordinationTodoClaimDecision =
+  | CoordinationTodoClaimAcceptedDecision
+  | CoordinationTodoClaimRejectedDecision;
+
+type ClaimRejection = CoordinationTodoClaimRejectedDecision | null;
+
 function normalizeAgent(value: unknown, label: string): string {
   if (typeof value !== "string") {
     throw new AuthorityStoreProtocolError(`${label} must be a public-safe agent id`);
@@ -59,85 +83,155 @@ function normalizeRegisteredAgents(value: readonly string[]): string[] {
   return normalized;
 }
 
+function normalizeExcludedAgents(value: unknown): string[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new AuthorityStoreProtocolError("todo.excluded_agents must be an array");
+  }
+  const normalized = value.map((agent, index) =>
+    normalizeAgent(agent, `todo.excluded_agents[${index}]`)
+  );
+  if (new Set(normalized).size !== normalized.length) {
+    throw new AuthorityStoreProtocolError(
+      "todo.excluded_agents must contain unique public-safe agent ids",
+    );
+  }
+  return normalized;
+}
+
 function failure(code: string, reason: string, detail: JsonObject = {}): CoordinationTodoClaimResult {
   return {
+    ...detail,
     schema_version: COORDINATION_TODO_CLAIM_RESULT_SCHEMA,
     status: "failed",
     reason_code: code,
     reason,
+  };
+}
+
+function decisionFailure(
+  code: string,
+  reason: string,
+  detail: JsonObject = {},
+): CoordinationTodoClaimRejectedDecision {
+  return {
     ...detail,
+    schema_version: COORDINATION_TODO_CLAIM_DECISION_SCHEMA,
+    status: "rejected",
+    reason_code: code,
+    reason,
   };
 }
 
-function claimAuthority(
-  todo: JsonObject,
+function rejectInvalidClaimActor(
   input: CoordinationTodoClaimInput,
-): { owner: string; actor: string | null; mode: string } | CoordinationTodoClaimResult {
-  const registered = input.registered_agents;
-  const owner = input.claimed_by;
-  const actor = input.actor_agent_id;
+): ClaimRejection {
+  const { registered_agents: registered, claimed_by: owner, actor_agent_id: actor } = input;
   if (!registered.includes(owner)) {
-    return failure("actor_not_registered", "claimed_by is not registered for this goal", {
-      claimed_by: owner,
-    });
+    return decisionFailure(
+      "actor_not_registered",
+      "claimed_by is not registered for this goal",
+      { claimed_by: owner },
+    );
   }
   if (actor !== null && !registered.includes(actor)) {
-    return failure("actor_not_registered", "actor_agent_id is not registered for this goal", {
-      actor_agent_id: actor,
-    });
+    return decisionFailure(
+      "actor_not_registered",
+      "actor_agent_id is not registered for this goal",
+      { actor_agent_id: actor },
+    );
   }
   if (registered.length > 1 && actor === null) {
-    return failure("actor_required", "multi-agent Todo claim requires actor_agent_id");
+    return decisionFailure(
+      "actor_required",
+      "multi-agent Todo claim requires actor_agent_id",
+    );
   }
-  if (actor !== null && actor !== owner) {
-    return failure(
+  return actor !== null && actor !== owner
+    ? decisionFailure(
       "claim_actor_mismatch",
       "Todo claim requires claimed_by to match actor_agent_id",
       { actor_agent_id: actor, claimed_by: owner },
-    );
-  }
+    )
+    : null;
+}
+
+function rejectIneligibleTodo(
+  todo: JsonObject,
+  input: CoordinationTodoClaimInput,
+): ClaimRejection {
   if (todo.role !== "agent") {
-    return failure("todo_not_agent", "claimed_by is only valid for agent Todos");
+    return decisionFailure("todo_not_agent", "claimed_by is only valid for agent Todos");
   }
   if (input.expected_role !== null && input.expected_role !== todo.role) {
-    return failure("todo_role_mismatch", "Todo does not have the requested role", {
-      requested_role: input.expected_role,
-      todo_role: todo.role,
-    });
+    return decisionFailure(
+      "todo_role_mismatch",
+      "Todo does not have the requested role",
+      { requested_role: input.expected_role, todo_role: todo.role },
+    );
   }
   if (todo.status !== "open") {
-    return failure("todo_not_open", "Todo claim requires status=open", {
-      todo_status: todo.status,
-    });
+    return decisionFailure(
+      "todo_not_open",
+      "Todo claim requires status=open",
+      { todo_status: todo.status },
+    );
   }
   if (todo.archive_state !== "active") {
-    return failure("todo_archived", "Todo claim requires an active Todo");
+    return decisionFailure("todo_archived", "Todo claim requires an active Todo");
   }
-  if (typeof todo.removed_continuation_policy === "string" &&
-      todo.removed_continuation_policy.length > 0) {
-    return failure(
+  return typeof todo.removed_continuation_policy === "string" &&
+      todo.removed_continuation_policy.length > 0
+    ? decisionFailure(
       "removed_continuation_policy",
       "Todo uses a removed continuation policy and must be repaired before claiming",
-    );
-  }
-  const excluded = Array.isArray(todo.excluded_agents) ? todo.excluded_agents : [];
+    )
+    : null;
+}
+
+export function evaluateCoordinationTodoClaimDecision(
+  todo: JsonObject,
+  input: CoordinationTodoClaimInput,
+): CoordinationTodoClaimDecision {
+  const registered = input.registered_agents;
+  const owner = input.claimed_by;
+  const actor = input.actor_agent_id;
+  const rejection = rejectInvalidClaimActor(input) ?? rejectIneligibleTodo(todo, input);
+  if (rejection !== null) return rejection;
+  const excluded = normalizeExcludedAgents(todo.excluded_agents);
   if (excluded.includes(owner)) {
-    return failure("actor_excluded", "claiming agent is excluded from this Todo", {
-      actor_agent_id: owner,
-    });
+    return decisionFailure(
+      "actor_excluded",
+      "claiming agent is excluded from this Todo",
+      { actor_agent_id: owner },
+    );
   }
   const existing = typeof todo.claimed_by === "string" && todo.claimed_by.length > 0
     ? normalizeAgent(todo.claimed_by, "todo.claimed_by")
     : null;
   if (existing !== null && existing !== owner) {
-    return failure("claim_owner_mismatch", "Todo is already claimed by another agent", {
-      claim_owner: existing,
-    });
+    return decisionFailure(
+      "claim_owner_mismatch",
+      "Todo is already claimed by another agent",
+      { claim_owner: existing },
+    );
   }
+  const mode = registered.length <= 1 ? "single_agent_compatibility" : "registered_peer_actor";
   return {
+    schema_version: COORDINATION_TODO_CLAIM_DECISION_SCHEMA,
+    status: "accepted",
     owner,
     actor,
-    mode: registered.length <= 1 ? "single_agent_compatibility" : "registered_peer_actor",
+    mode,
+    mutation_authority: {
+      schema_version: "todo_mutation_authority_v0",
+      command: "claim",
+      mode,
+      actor_agent_id: actor,
+      todo_id: todo.todo_id,
+      registered_agent_count: registered.length,
+      ...(mode === "registered_peer_actor" ? { claim_owner: existing } : {}),
+    },
   };
 }
 
@@ -269,16 +363,22 @@ export async function executeCoordinationTodoClaim(
     });
   }
 
-  let authority: ReturnType<typeof claimAuthority>;
+  let authority: ReturnType<typeof evaluateCoordinationTodoClaimDecision>;
   try {
-    authority = claimAuthority(todo, input);
+    authority = evaluateCoordinationTodoClaimDecision(todo, input);
   } catch (error) {
     return failure(
       "invalid_coordination_todo_claim",
       error instanceof Error ? error.message : "invalid Todo claim",
     );
   }
-  if (typeof authority.owner !== "string") return authority as CoordinationTodoClaimResult;
+  if (authority.status !== "accepted" || typeof authority.owner !== "string") {
+    return failure(
+      typeof authority.reason_code === "string" ? authority.reason_code : "invalid_coordination_todo_claim",
+      typeof authority.reason === "string" ? authority.reason : "Todo claim was rejected",
+      authority,
+    );
+  }
 
   const handoffMode = typeof head.head.handoff_mode === "string"
     ? head.head.handoff_mode
@@ -295,17 +395,10 @@ export async function executeCoordinationTodoClaim(
     );
   }
 
-  const mutationAuthority = {
-    schema_version: "todo_mutation_authority_v0",
-    command: "claim",
-    mode: authority.mode,
-    actor_agent_id: authority.actor,
-    todo_id: input.todo_id,
-    registered_agent_count: input.registered_agents.length,
-    ...(authority.mode === "registered_peer_actor"
-      ? { claim_owner: typeof todo.claimed_by === "string" ? todo.claimed_by : null }
-      : {}),
-  };
+  const mutationAuthority = canonicalAuthorityObject(
+    authority.mutation_authority,
+    "Todo claim mutation authority",
+  );
   const updatedAt = input.now.toISOString().replace(/\.\d{3}Z$/u, "Z");
   const changed = todo.claimed_by !== authority.owner;
   const result = {

loopx/control_plane/effect_runtime_handlers.ts

@@ -120,6 +120,7 @@ import {
   promoteLocalCoordinationAuthority,
   readLocalCoordinationTodo,
 } from "./coordination/local_authority_runtime.ts";
+import { evaluateCoordinationTodoClaimDecision } from "./coordination/todo_claim.ts";
 import {
   checkLegacyCoordinationWriteAllowed,
   engageLegacyCoordinationWriterFence,
@@ -350,6 +351,25 @@ export function createEffectRuntimeHandlers(
     ["todo.completion_state.require_metadata", requireTodoCompletionMetadataValue],
     ["todo.completion_state.continuation_for_write", selectTodoCompletionContinuation],
     ["todo.completion_state.metadata_updates", buildTodoCompletionMetadataUpdates],
+    [
+      "todo.claim.decide",
+      (params) => evaluateCoordinationTodoClaimDecision(
+        requiredObject(params.todo, "todo"),
+        {
+          goal_id: requiredString(params.goal_id, "goal_id"),
+          todo_id: requiredString(params.todo_id, "todo_id"),
+          claimed_by: requiredString(params.claimed_by, "claimed_by"),
+          actor_agent_id: params.actor_agent_id === null
+            ? null : requiredString(params.actor_agent_id, "actor_agent_id"),
+          expected_role: params.expected_role === null
+            ? null : requiredString(params.expected_role, "expected_role"),
+          registered_agents: stringArray(params.registered_agents, "registered_agents"),
+          operation_id: "decision-only",
+          dry_run: true,
+          now: new Date(0),
+        },
+      ),
+    ],
     ["todo.completion.reduce", reduceTodoCompletionTransaction],
     ["todo.next_action.transition", transitionTodoNextAction],
     ["todo.resume_condition.normalize", normalizeTodoResumeWhen],