3. Review commands, calculations, and workflow
Trace an edit through save and approval. Understand why a calculation can be saved yet no longer be current.
An edit is a command
A command names an action, such as updating household facts, saving a computation scenario, applying final results, or submitting work. The UI gives immediate feedback by calling shared domain code. The server calls that code again before storage. A browser preview is not evidence that the command was accepted.
Input event → CommandDraft / local preview → pending command batch
→ POST /api/reviews/{UUID} with version + requestId + commands
→ getActor → body schema → saveCommands → execute → typed handler
→ appendReview → snapshot + index + events transaction
→ saved response → browser replaces its saved base
Source: draft coalescing, saveCommands, execute, and append. Repeated edits to a compatible draft coalesce. The system does not write a complete historical snapshot for every keystroke.
Save, autosave, undo, Clear, and Reset
| Action | Current meaning | Limit |
|---|---|---|
| Save | Flush drafts and queued commands. Saved time comes from the accepted response. | An unsaved preview can fail server validation. Read Retry or conflict feedback. |
| Autosave | Optional preference, off by default. Ordinary navigation and page-hide save paths still exist. | A closed tab or failed network cannot guarantee a save. Confirm saved status before leaving important work. |
| Computation Save | Commits the edited column before Apply Final Results. | Column drafts are explicit. A visible edited number may still be uncommitted. |
| Undo | Short browser stack, up to 30 registered undo actions in the provider. | It is not durable revision history. Conflict recovery clears local edits/undo. |
| Clear | An explicit command that clears the selected fact section and records Activity. | It must obey examiner/state guards. |
| Reset | Restore the captured received fact copy for that role/stage. | Received copies exclude Activity. No historic copy is invented when absent. |
Four computation columns
Eligibility represents the CAO calculation. Comp I and Comp II are examiner scenarios. Final SAQC holds the selected result and inputs. Money uses integer cents. Displayed dollars are formatting. Inputs, rounding, policy tables, and algorithm versions all affect the result.
With Eligibility $0, Comp I $608, and Comp II $488, the absolute differences are $608 and $488. Comp II wins because the difference is smaller. With equal absolute differences, Comp I wins. If only one examiner scenario is complete, that scenario wins. The error value is CAO benefit minus selected QC benefit, so this example has error -$488.
The selection rule comes from selectFinal and retained workbook evidence. It is a defined selection rule, not a general instruction to minimize findings. Human policy review must verify the scenarios and their inputs.
Versioned behavior
Calculation v4 includes dated policy and self-employment profit/loss. v3 added education net and application-day proration. v1 and v2 retain earlier behavior. The current edit-check version is snap-negative-full-v3. Publishing a new amount table does not automatically change the algorithm identifier. Applying rules to an existing review is a controlled action.
The current code subtracts a self-employment loss consistently under the active specification. One legacy Eligibility workbook cell adds it. Treat that known difference as an acceptance case. Do not say the demo exactly reproduces every workbook formula. See the computation evidence.
Why a final result becomes stale
facts.inputsRevision changes when supported calculation inputs change. Final Results record the input revision they used. finalCurrent compares them. A stored result can still exist while that comparison fails. Reapply Final Results after committing the changed inputs. Undo does not make an old result current by declaration.
Required inputs and findings are different
Required or invalid coded values block submission. Cross-field edit-check findings are stored on submission and do not all block entry to Awaiting supervisor. Senior approval checks current inputs/results and unresolved findings. A senior refusal needs evidence. Changed facts need a fresh check. These checks are the versioned checks implemented here, not a certified full federal ruleset.
Example: recorded reason accuracy 2 with finding other than 2 produces a finding. Notice clarity 2 without narrative also produces a finding. Read validation.ts and its tests. Code 1 is not a universal correct answer. Some questions use 2, 3, 4, or padded multi-digit codes for valid responses.
Approvals and the active blocker
| Stage | Guard or result |
|---|---|
| Examiner submit | Active or Needs Changes, outcome set, current final/required inputs for non-drops. Captures validation evidence. |
| Supervisor return | Senior role, Awaiting supervisor, reason required. Returns fact editing to examiner. |
| Supervisor approve drop | Moves to Awaiting manager. Drops do not route to PEC. |
| Manager approve drop | Requires supervisor evidence and records dropApproved. |
| Supervisor approve or route non-drop | Current code throws PEC_ROUTING_PENDING after prerequisite checks. Management must supply the Review-tab defect map. |
| PEC decision | On eligible seeded PEC-stage work, records approve, deny, or conditional decision. Approval generates a manager memo draft. |
| Manager memo | Draft type remains unresolved for newly generated memos. A missing type blocks approval. Actual delivery is not implemented. |
| Reporting release | Requires approved memo and CAO agreement with root cause, or recorded no response after the deadline. A dispute blocks release. |
Source: transition, workflow handlers, and downstream guards. The no-response date comparison is strictly after the saved deadline date. Production needs an approved timezone, holiday calendar, and delivery clock.
Exercise and answer key
- A review is saved at database version 12. Its final input revision is 5. You edit income so inputsRevision becomes 6. Can it submit as a non-drop?
- After correcting and submitting it, can the supervisor route it to PEC today?
- Can a seeded memo-approved review with a CAO dispute enter Program Error Summary?
Answer
- The saved final result is stale. Commit the computation and apply Final Results against input revision 6 before submission.
- The defect-map guard blocks new non-drop routing even if its other prerequisites pass. Document the required management decision.
- No. A dispute blocks manager reporting release. Seeded later states only demonstrate the behavior of those states.
Next: lesson 4. Deep reading: computation, workspace.