Repository navigation
fix(extraction): the background writeback never changes reviewed lines - #625
Open
privatejoel wants to merge 1 commit into
Open
privatejoel wants to merge 1 commit into
privatejoel wants to merge 1 commit into
Conversation
Plan C-2 (R-F1 b), with decision C-D1. The background job wrote its lines without a read of the order status. On a large PO, a person can review, approve and push the page-1 lines before the job ends. The job then replaced every line, with the operator edits and item mappings. Nothing recorded it. Now the job writes lines only to a DRAFT, and maps them to the item master. Past DRAFT, it keeps the reviewed lines. It holds the new lines on a blocking finding, lines_changed_after_review. An order in review or approved goes back to DRAFT with the reason, and loses its approval. A later status keeps its status and approval. A cancelled order gets no write. The order write is compare-and-set on updated_at. A save or a cancel that lands during the job is not overwritten. The job reads the order again once. If the order changes again, the job fails and keeps its result. Each job stage is compare-and-set on its status, so an operator cancel stays. The cancel endpoint refuses a job that is merging. A queued or running job is the row extraction_in_flight. It blocks send. Co-Authored-By: Claude Opus 5.5 <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Plan C-2 (docs/SO_EXECUTION_COHESION.md, R-F1 (b)), with decision C-D1 accepted.
The defect: the background extraction writeback did not read the order status. On a large PO, a person can review, approve and push the page-1 lines before the job ends. The job then replaced every line, with the operator edits and
_mapped_item. Nothing recorded it. Also, a cancel that landed during the merge was overwritten.What the writeback does now (
src/api/cron/extraction_jobs.js):mapLinesToItemMastercorrection_reason(C-D1)[id].jslines_changed_after_reviewinorders.rule_findings. The finding hasblocks: trueandsource: "extraction", so:blocking-findings.js);rule_findingsoverwrite carries it forward (mergeBlockersForward).lines_changed_after_reviewwithblocks: "approval".order_lines_held_after_reviewrecords each hold.Races:
updated_at(the 001_init trigger moves it on every write). If 0 rows change, the job reads the order again and applies the rule once more. If the order changes again, the job fails withlast_error"order writeback failed: the order changed twice while the job wrote it".job.resultkeeps the merged extraction. A write error fails the job as before.extractingormerging, and the job then wrote the order.orders/extraction_jobs_id.js) refuses a job inmergingwith 409JOB_WRITING, because the job is writing the order. Its update is compare-and-set on the status it read: if the worker moved the job on, it returns 409JOB_MOVED.In-flight job:
GET /api/orders/exceptionsreads the order's newest queued or runningextraction_jobsrow (tenant-scoped). The builder raisesextraction_in_flightwithblocks: "send". The next step "Send for approval" is then disabled.docs/AGENT_READY_SO_FLOW.mdlists the two new types and the optionsuse_new_linesandcancel_extraction.Deploy notes
orders.rule_findings(jsonb, exists since 001).requireAction. No new permission.Tests
New, behavioural:
src/v3-app/api-extraction-writeback-guard.test.js(15 tests): DRAFT writes and maps; PENDING_REVIEW goes to DRAFT with the reason and holds the lines; approve then gets 409ORDER_HAS_UNRESOLVED_BLOCKER; the same lines write nothing; APPROVED keeps its lines and loses its approval; EXPORTED_TO_TALLY keeps lines, status and approval; a second late job replaces the open held lines; CANCELLED gets no write; an order cancel between the read and the write is not overwritten; a send for review between the read and the write gets a hold; an order that changes on both tries fails the job and keepsjob.result; a job cancel during a chunk is not overwritten; the cancel endpoint refuses a merging job and a job the worker moved on.src/v3-app/api-order-exceptions.in-flight.test.js(6 tests): the row for each in-flight status, none for a terminal job, Send for approval stays disabled, and the real endpoint reads only this tenant's job.Changed:
api-order-reconcile.hash.test.js: three C-1 cases used a PENDING_REVIEW order to show that the writeback moves the hash. That writeback no longer happens, so those cases use a DRAFT. The approved-order case now checks the C-2 rule: the lines and the hash stay, and the approval goes.api-extraction-jobs-continuation.test.js: the double now reads the order as a DRAFT and returns the written row.Mutation check. I undid each fix, ran the two new files, and restored it. A no-op control passed. All 18 mutations failed at least one test:
mapLinesToItemMasterupdated_atcompare-and-setlines_changed_after_reviewrow typeGates, on a clean
npm ciin this worktree:npm run check: pass.npm run lint: 0 errors (511 warnings, none on a changed line).npm run build: pass. Build outputs are not committed.npm run verify: pass. It rewrotedocs/RBAC_AUDIT.mdanddocs/WRITE_PATH_AUDIT.mdwith changes this PR did not cause (admin screen, roles). I restored both.npm run eval:golden: pass, aggregate 1.000.NODE_OPTIONS=--no-experimental-webstorage npx vitest run --maxWorkers=2: 628 files, 7388 tests, all pass.Note: with the shared
node_modulessymlink (installed 2026-07-07),check:importsandbuildfail on origin/main too. The symlink has@simplewebauthn/server11.0.0 (the code needs 14) and no@fontsourcepackages. A clean install fixes both.Not covered
extraction_in_flightrow. The server list, which the workspace uses when it answers, has it.mergingcannot be cancelled from the API. The worker retries it when its lease ends. This is markedshortcut:in the cancel endpoint.rule_findingslarge on a long PO.Open questions for the owner:
🤖 Generated with Claude Code