Skip to content

A human phrase decision commits with its own recomputation job and answers 202 - #876

Merged
WaylandYang merged 2 commits into
devfrom
feat/phrase-decision-delivery
Sep 23, 2026
Merged

WaylandYang merged 2 commits into
devfrom
feat/phrase-decision-delivery

Conversation

@WaylandYang

Copy link
Copy Markdown
Contributor

Implements the production half of ADR 0051. The store refactors and the isolated delivery regression landed in #841; this wires the route, the job kind and the page.

What changes

  • phrase_bindings::decide_with_delivery writes the person's decision and enqueues a materialize_typed job in one transaction. The job's payload carries only kb_id; the worker reads the current bindings and never replays the decision's old payload, so out-of-order jobs converge on the last decision (0051 §"Why a late decision is not lost").
  • materialize::try_materialize is the job's entry: pg_try_advisory_xact_lock on typed_materialize, run the existing materialize_in_tx on that connection, commit. Busy rolls back and the handler returns Deferred (10 s) through the existing bounded deferral path; it is not a successful job.
  • POST /kbs/{id}/review/alignment/phrases/{binding_id} now answers 202 with { ok, job_id, status: "accepted" } and no invented typed counts. The audit row carries the job id; the job writes alignment.materialized when the projection changed.
  • GET /kbs/{id}/jobs/{job_id}: Viewer-level status read, scoped by the job payload's kb_id (another base's job id answers 404, like an invisible document).
  • Review page: the toast says the decision is saved and the graph is recomputing; completion arrives as the existing review / graph events. Copy in both language packs.
  • materialize_human (Bound lock waits for human phrase alignment review decisions (#798, #800) #864, merged earlier today) is retired: it bounded the route's synchronous wait for the lock, and the route no longer waits at all, so there is nothing left to bound. 0051 §Alternatives is the reasoning ("blocking on the materialization lock retains scarce connections; a bounded Deferred outcome preserves work"). The kind-word route's Bound lock waits for human kind-word review decisions #828 timeout is untouched. Its test file goes with it.
  • 0051 status line and a dated revision note; design/ontology.md states the new contract.

Verified against pgvector/pgvector:pg16 on a fresh database:

cargo fmt --all --check                                     ok
cargo clippy --workspace --all-targets -- -D warnings       clean
cargo test -p utopia-store   (UTOPIA_TEST_REQUIRE_DB=1)      331 passed, 0 failed
cargo test -p utopia-server  (UTOPIA_TEST_REQUIRE_DB=1)      385 passed, 0 failed
cd web && pnpm build && pnpm test                            tsc clean, 132 passed

New coverage: decision and job commit together with a kb-scoped payload; an enqueue failure after the decision write rolls both back; a held lock is declined in under a second rather than waited for; jobs processed in either order converge on the last decision; the route answers 202, a Viewer can read the job in its base and gets 404 from another base, a Viewer cannot decide.

Stacked: feat/alignment-cut2 continues from this commit with the #807 lifecycle work; that PR will show only its own diff once this merges.

🤖 Generated with Claude Code

WaylandYang and others added 2 commits September 23, 2026 16:24
…swers 202

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: WaylandYang <145302500+WaylandYang@users.noreply.github.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: WaylandYang <145302500+WaylandYang@users.noreply.github.com>
@WaylandYang
WaylandYang merged commit 60cd5d3 into dev Sep 23, 2026
4 checks passed
@WaylandYang
WaylandYang deleted the feat/phrase-decision-delivery branch September 23, 2026 08:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant