api_slice_1_plan_claim_loop_plan · supabase_json

Bezel API api_slice_1_plan_claim_loop_plan

api_slice_1_plan_claim_loop_plan artifact · for Bezel API · status draft

Planning Surface

Use this to decide what happens next.

Status

draft

open questions

Whether to add priority/order fields to tasks in Slice 1 or keep DB insertion order plus dependency readiness.

Agent Handoff

Start Here

api_slice_1_plan_claim_loop_plan artifact · for Bezel API · status draft

Completion Evidence

No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.

Goal

Make customer-submitted multi-task plans reliable while preserving Lite mode: task data stays in the Bezel DB, and HCS only records minimal claim proofs.

Open Questions

Whether to add priority/order fields to tasks in Slice 1 or keep DB insertion order plus dependency readiness.

Structured Payload

Machine-readable source fields

goal

Make customer-submitted multi-task plans reliable while preserving Lite mode: task data stays in the Bezel DB, and HCS only records minimal claim proofs.

status

draft

version

1.3

progress

completed

S1-T1 HEAD /healthz implemented, deployed, and verified over HTTPS.
S1-T2 partial: plan intake now rejects dependency cycles, non-string dependency ids, and unknown role queues before materialization.
S1-T5 dependency live smoke implemented and deployed; production smoke verifies blocked dependent tasks unlock after parent completion.
Production bug fixed: Postgres claim store now returns completed dependency ids for SQL-filtered ready candidates so the in-memory dependency guard does not filter them out.
S1-T3 materializePlan now persists workflow/task/dependency graphs transactionally; no partial task graph remains on failure.
S1-T6 partial: OpenAPI and JS SDK now expose POST /roles/{roleId}/claim-next so agents can claim by assigned role instead of queue id.
Production smoke now exercises role-based claim-next over https://api.bezeliq.ai with dependency unlock coverage.
S1-T4 verified complete: claim-next tries the next eligible candidate after a lost DB claim race and bounds internal attempts.
S1-T6 docs completed: runbook, root README, and JS SDK README document role-based polling, Lite HCS boundary, idempotency, race behavior, and rejection reasons.
S1-T2 completed: API boundary tests now cover duplicate task ids, missing dependency targets, and dependency cycles before materialization.

latest commits

0a040d3 fix: support head health checks
5eef79a feat: harden plan intake validation
351b2e2 test: cover dependency unlock in live smoke
cf7f404 fix: unlock dependency-ready postgres claims
dede5f2 fix: materialize plans transactionally
7fa1584 feat: add role-based claim endpoint
ae4fbd7 docs: document role claim loop
d0c57d1 test: cover plan graph errors at api boundary

remaining task ids

No items captured.

latest production smoke

role id

bc0be3ae-6eb7-441c-908e-def9ce7d37f0

queue id

75a7f72e-1df2-49c6-820d-7bf7812b4fb8

passed at

2026-05-08T17:47:30.000Z

api base url

https://api.bezeliq.ai

root claim id

2b09da32-732c-4bbb-84e6-ccc4a08e3628

workflow run id

380b262c-1f71-4083-8d33-f4fd6c3a3be0

dependency claim id

007964ce-0fcb-4fde-8779-97af53434150

non goals

Do not store customer task payloads, plan JSON, or artifact bodies in HCS in Lite mode.
Do not implement Pro/Verified lifecycle replay yet.
Do not build a customer UI in this slice.

updated at

2026-05-08T17:53:35.166Z

open questions

Whether to add priority/order fields to tasks in Slice 1 or keep DB insertion order plus dependency readiness.

hardening tasks

id	files	title	commit	status	acceptance
S1-T1	- apps/api/src/http-server.ts - apps/api/test/http-server.test.ts	Document and test HEAD health behavior	0a040d3 fix: support head health checks	done
S1-T2	- apps/api/test/plan-intake-route.test.ts - packages/store/test/materialize-plan.test.ts	Add plan intake validation contract tests	5eef79a feat: harden plan intake validation; d0c57d1 test: cover plan graph errors at api boundary	done	- Reject duplicate task ids in a plan. - Reject dependencies that reference unknown task ids. - Reject dependency cycles. - Reject tasks whose role_id is not visible to the agent workspace. - Return stable error reasons that SDK callers can handle.
S1-T3	- packages/store/src/plan-materialization.ts - apps/api/src/plan-intake-route.ts	Harden materializePlan graph persistence	dede5f2 fix: materialize plans transactionally	done	- Workflow definition/run and task rows are created transactionally. - Task dependencies are persisted only after validation passes. - No partial task graph remains when validation fails.
S1-T4	- packages/store/src/claim-next-adapter.ts - packages/store/test/claim-next-adapter.test.ts - apps/api/src/claim-next-route.ts	Make claim-next continue after a lost race	existing core tests plus ae4fbd7 docs: document role claim loop	done	- If candidate A cannot be claimed because another agent won first, API attempts candidate B before returning no_tasks. - The response remains a single claimed/no_tasks/rejected result. - HCS proof is written only after a DB claim succeeds.
S1-T5	- apps/api/src/live-smoke.ts - apps/api/test/live-smoke.test.ts	Add dependency unlock smoke coverage		done	- Live smoke can submit at least two tasks with a dependency. - First claim returns the dependency root task. - Second claim before root completion returns no_tasks or a different independent task. - After root completion, dependent task becomes claimable.
S1-T6	- apps/api/openapi.json - packages/sdk-js/src/client.ts - packages/sdk-js/test/client.test.ts - apps/api/RUNBOOK.md	Update OpenAPI and SDK behavior docs	ae4fbd7 docs: document role claim loop	done	- OpenAPI documents plan validation errors and HEAD /healthz. - SDK surfaces claim-next and plan-submit errors clearly. - Runbook includes Lite HCS boundary and agent polling contract.

product contract

plan submission

Customer submits a plan with tasks, role assignment, and dependencies. API validates the graph and stores workflow/task records in the isolated DB schema.

hcs lite boundary

Only claim proof is written to HCS: workspace hash, queue, role, task id, agent id, claim id, idempotency hash, lease, attempt number, timestamp. No task input or artifact content.

ready task selection

Agent does not choose a task. Agent calls claim-next for its role queue; API selects the next eligible task whose dependencies are complete and atomically claims it.

failed claim behavior

If another agent wins the race, claim-next should continue looking for the next eligible task in the same request before returning no_tasks.

agent polling endpoint

Preferred Lite endpoint is POST /roles/{roleId}/claim-next. Queue-based POST /queues/{queueId}/claim-next remains available for internal/back-compat callers.

completion unlocks dependencies

Completing a task makes dependent tasks eligible when all dependencies are complete.

verification gate

npm test: 33 files / 101 tests passed after d0c57d1
npm run typecheck: passed after d0c57d1
npm run build: passed after d0c57d1
npm audit --audit-level=moderate: 0 vulnerabilities
GET and HEAD https://api.bezeliq.ai/healthz: 200 OK after 7fa1584 deploy
Live smoke over https://api.bezeliq.ai passed using POST /roles/{roleId}/claim-next with dependency coverage after 7fa1584 deploy