--- type: idea title: Accounting Context Runtime - Codex Build Spec created: 2026-06-21 status: seed origin_sources: - "[[2026-06-21 Accounting Context Runtime for Vendor Spend]]" related_auto: [] used_in: [] --- # Accounting Context Runtime - Codex Build Spec ## Purpose This spec is written for Codex to build an autonomous prototype of the Accounting Context Runtime. The product is an always-on close preparation layer for vendor spend. It watches an Accounting Inbox, turns vendor commercial context into accrual/prepaid accounting cases, prepares evidence-backed schedules and draft artifacts, and routes cases to an accounting manager for review. The prototype should prove the core workflow without requiring live ERP integrations. ## Build philosophy Build a working local prototype, not a slideware mockup. The system should demonstrate this loop end to end: ```text Accounting Inbox artifacts -> artifact classification -> vendor/case linking -> term extraction -> accrual/prepaid case detection -> evidence-backed case preparation -> deterministic schedule / draft JE generation -> accounting manager review -> exportable workpaper packet ``` The prototype can use heuristic extraction and deterministic fixture data before introducing model calls. The architecture should leave a clean seam where model-backed extraction and treatment proposal can later plug in. ## Non-negotiable product boundaries V1 must not: - post directly to an ERP or GL - mutate approved schedules without review - make final accounting judgments without human approval - require NetSuite or any ERP connector - depend on Slack/email firehose ingestion - support revenue recognition - support complex multi-book consolidation - hide uncertainty V1 must: - accept messy accounting artifacts through an Accounting Inbox - create cases only when an accounting question is detected - support accrual and prepaid cases - produce reviewable evidence packages - produce deterministic schedules and draft JE exports - expose missing evidence and duplicate-accrual risk - require approval before a case is compiled/closed - maintain an audit trail of actions ## Recommended implementation shape If building from scratch, prefer a local-first web app. Recommended stack: - TypeScript - React frontend - Node server or full-stack framework - SQLite for durable local state - file-system storage for uploaded artifacts - CSV/XLSX export for schedules and draft JEs - Playwright or similar browser tests for key flows If the existing workspace already has a stronger local app convention, follow that convention. Do not overbuild infrastructure. ## Core screens Build only three screens first. ### 1. Accounting Inbox Purpose: show artifacts that have landed in the runtime. Must include: - upload or import sample artifacts - artifact list - artifact type classification - vendor link - extraction status - linked case, if any - action to run/re-run processing Supported artifact types: - contract - renewal - invoice - PO - schedule - policy - approval - other ### 2. Close Prep Queue Purpose: show accounting cases requiring review or evidence. Must include: - case list - status - vendor - accounting question type - amount - close-period impact - evidence completeness - proposed treatment - exception flags - filters by status and treatment type ### 3. Case Review Purpose: let an accounting manager review a case and approve/edit/defer/reject. Above the fold: - why the case exists - proposed treatment - dollar impact - close-period impact - evidence completeness - required action Main panels: - Trigger - Evidence - Extracted terms - Proposed treatment - Prepared schedule - Draft JE / reversal - Exceptions and controls - Comments / audit trail Actions: - approve treatment - request evidence - edit treatment - edit schedule - mark no entry needed - defer - escalate - compile artifact Do not include a generic homepage chat. If chat exists, make it case-scoped and optional. ## Data model Implement these core objects. ```text Artifact - id - filename - artifact_type - uploaded_at - source_text or parsed_text - vendor_id - extracted_fields - status - linked_case_ids Vendor - id - name - aliases - usual_treatment - prior_case_ids - prior_schedule_ids ClosePeriod - id - label - start_date - end_date - close_deadline - accrual_threshold - prepaid_threshold - materiality_threshold - status AccountingCase - id - vendor_id - close_period_id - trigger_type - question_type - status - amount - proposed_treatment_id - evidence_artifact_ids - exception_flags - required_action - created_at - updated_at Treatment - id - case_id - treatment_type - rationale - policy_basis - confidence - reviewer_decision - reviewed_by - reviewed_at PreparedSchedule - id - case_id - schedule_type - start_date - end_date - recognition_pattern - account_mapping - periods - generated_entries - approval_state CompiledArtifact - id - case_id - artifact_type - export_path - generated_at ControlEvent - id - object_type - object_id - event_type - actor - timestamp - details ``` Allowed case statuses: - Detected - Prepared - Needs Evidence - Ready for Review - Approved - Compiled - Closed - Deferred - Rejected Allowed treatment types: - accrual - prepaid - no-entry-needed - needs-review Allowed trigger types: - new-contract - renewal - new-invoice - open-po - expected-invoice-missing - invoice-without-support - material-change-from-prior-treatment ## Runtime jobs Implement the runtime as explicit jobs. Each job should be callable independently and runnable as a pipeline. ### Intake classifier Classify artifacts as contract, invoice, PO, renewal, schedule, policy, approval, or other. Prototype may use filename patterns and extracted text heuristics. ### Vendor linker Link artifacts to vendors using: - explicit vendor name in extracted text - filename hints - aliases - prior case/schedule matches ### Term extractor Extract: - vendor name - amount - invoice date - contract or service start date - contract or service end date - billing cadence - renewal indicators - approval clues - PO number - invoice number Every extracted field should preserve a source reference when possible. ### Case detector Create or update an accounting case only when an accounting question is detected. V1 accounting questions: - Does this need an accrual? - Does this need prepaid treatment? - Does this change an existing schedule? - Is there enough evidence? - Is this materially different from prior treatment? - Is a duplicate accrual or already-invoiced risk present? - Is no entry needed? ### Evidence builder Assemble: - source artifacts - extracted terms - prior treatment - missing fields - policy notes - exceptions ### Treatment proposer Suggest: - accrual - prepaid - no-entry-needed - needs-review Include rationale and confidence. Confidence must not be used as approval. ### Compiler / validator Deterministically generate: - prepaid schedule - accrual support - draft JE - reversal JE, when applicable - duplicate-accrual check result - already-invoiced check result - validation summary The compiler must validate: - debits equal credits - required evidence exists for material cases - case is in an open period - approved treatment exists before compilation - duplicate accrual check has passed or been overridden ### Notification router For prototype, notifications can be in-app flags only. Alert when: - case is Ready for Review - case Needs Evidence - duplicate risk exists - material case needs approval - compile failed validation ## Deterministic accounting behavior ### Prepaid schedule Given: - amount - service start date - service end date - close period - account mapping Generate: - prepaid asset entry - monthly recognition schedule - amortization entries by period - remaining balance by period Use straight-line recognition for v1. ### Accrual support Given: - estimated amount - service period or incurred period - close period - evidence strength - account mapping Generate: - accrual support summary - draft accrual JE - draft reversal JE for next period ### No-entry-needed Allow a case to close with no entry needed only if: - reviewer approves - rationale is present - evidence is linked - control event is recorded ## Controls Implement these controls in code, not only in UI copy: - no compile without approved treatment - no approved material case without evidence unless override rationale exists - no duplicate accrual compilation without override - no case close without final disposition - every approval/edit/override/compile creates a ControlEvent - every generated schedule links to a case - every draft JE links to a schedule or case - model/heuristic extraction must be reviewable in the case screen ## Seed data Create seed data sufficient to demonstrate the product without external integrations. Include at least: 1. **Open PO / missing invoice accrual case** - approved PO - no invoice - active service period - prior vendor pattern - generates accrual support and reversal JE 2. **Vendor renewal prepaid case** - renewal contract - invoice - 12-month service period crossing close - prior prepaid treatment - generates prepaid schedule and monthly JE 3. **Invoice without support** - invoice above threshold - no contract/PO - marked Needs Evidence 4. **No-entry-needed case** - low-dollar invoice below threshold - reviewer can close with rationale 5. **Duplicate accrual risk** - open PO or missing invoice signal - matching invoice or prior accrual exists - compile blocked until reviewer resolves or overrides Use realistic but fictional vendors and amounts. ## Export requirements Support exports for: - prepared schedule CSV - draft JE CSV - workpaper packet as Markdown or HTML Each export should include: - case ID - vendor - close period - treatment - evidence list - schedule or JE lines - approval state - generated timestamp ## Testing requirements At minimum, add tests for: - artifact classification - vendor linking - term extraction from seed artifacts - case detection - prepaid schedule math - accrual and reversal JE generation - debit/credit balance validation - duplicate accrual blocking - approval required before compile - ControlEvent creation - full happy-path UI flow Browser test happy path: ```text 1. Load seeded Accounting Inbox. 2. Process artifacts. 3. Open Close Prep Queue. 4. Open prepaid case. 5. Review evidence and schedule. 6. Approve treatment. 7. Compile artifact. 8. Export schedule or draft JE. ``` ## Quality bar The prototype is acceptable when: - a user can run it locally - seed data loads without manual setup - the three screens are usable - each seed scenario produces the expected case behavior - schedules and draft JEs are deterministic - controls block unsafe actions - tests pass - README explains how to run, process seed data, and inspect exports ## Suggested `/goal` prompts These are written so Codex can build incrementally and autonomously. ### Goal 1 - Scaffold the Prototype ```text /goal Build the first local prototype scaffold for the Accounting Context Runtime. Create a local-first web app with durable state, seed data, and three screens: Accounting Inbox, Close Prep Queue, and Case Review. Do not implement live ERP integrations. The app should run locally with one command and include a README. Stop only when the app boots and seeded placeholder data is visible. ``` Acceptance: - app runs locally - seed data visible - navigation between three screens works - README present ### Goal 2 - Implement Core Data Model and Runtime Pipeline ```text /goal Implement the v1 data model and runtime pipeline for the Accounting Context Runtime. Add Artifact, Vendor, ClosePeriod, AccountingCase, Treatment, PreparedSchedule, CompiledArtifact, and ControlEvent. Implement jobs for intake classification, vendor linking, term extraction, case detection, evidence building, treatment proposal, compiler/validator, and notification flags. Use seed artifacts and deterministic heuristics first. Stop only when processing seed data creates realistic accrual/prepaid cases. ``` Acceptance: - all core objects represented in persistent state - seed artifacts process into cases - cases have statuses and evidence - jobs can be run independently and as a pipeline ### Goal 3 - Build Deterministic Accounting Compiler ```text /goal Build the deterministic accounting compiler. Implement prepaid schedule generation, accrual support generation, draft JE lines, reversal JE lines, duplicate-accrual blocking, approval-before-compile controls, and ControlEvent audit logging. Stop only when generated schedules and JEs are deterministic, balanced, linked to cases, and blocked when controls fail. ``` Acceptance: - prepaid schedule math works - accrual and reversal JE generation works - debits equal credits - duplicate risk blocks compile - unapproved cases cannot compile - audit events are recorded ### Goal 4 - Complete Review UI ```text /goal Complete the accounting manager review UI. The Case Review screen must show trigger, evidence, extracted terms, proposed treatment, prepared schedule, draft JE, exceptions, controls, and audit trail. Add actions to approve treatment, request evidence, edit treatment, edit schedule, mark no entry needed, defer, reject, and compile artifact. Stop only when the seeded cases can be reviewed end to end from the UI. ``` Acceptance: - case review screen has all required panels - actions update state correctly - controls are visible and enforced - audit trail updates after actions ### Goal 5 - Add Exports and Workpaper Packets ```text /goal Add export support for prepared schedules, draft JEs, and workpaper packets. Exports must include case ID, vendor, close period, treatment, evidence list, schedule or JE lines, approval state, and generated timestamp. Stop only when a user can export artifacts from approved/compiled cases and inspect the files locally. ``` Acceptance: - schedule CSV export works - draft JE CSV export works - workpaper Markdown or HTML export works - exports are linked to CompiledArtifact records ### Goal 6 - Add Tests and Polish ```text /goal Add automated tests and polish for the Accounting Context Runtime prototype. Cover artifact classification, vendor linking, term extraction, case detection, schedule math, JE generation, duplicate blocking, approval controls, audit logging, and the happy-path UI flow. Run the test suite and fix failures. Stop only when tests pass and the README accurately describes setup, seed data, runtime processing, and exports. ``` Acceptance: - unit tests pass - browser happy path passes - README is accurate - no broken seeded flows ## Autonomy instructions for Codex When building from this spec: - Implement the smallest useful version first. - Prefer deterministic fixtures and heuristics before adding model calls. - Keep the UI functional and dense, not decorative. - Do not add unrelated features. - Do not build ERP posting. - Do not add generic chat as a main surface. - Keep controls enforced server-side or in the state layer, not only in the UI. - Leave clear seams for future model-backed extraction and treatment proposal. - Use tests to lock accounting math and control behavior. - If a requirement is ambiguous, choose the safer accounting-control interpretation. ## Definition of done for prototype The prototype is done when an accounting manager can: 1. Load an Accounting Inbox with sample vendor artifacts. 2. Run processing. 3. See a Close Prep Queue with accrual/prepaid cases. 4. Open a case and review evidence, extracted terms, proposed treatment, schedule, and draft JE. 5. Approve or reject the treatment. 6. Compile approved cases into schedules and draft exports. 7. See audit events for every review, edit, approval, override, and compile action. The final user reaction should be: > This is the work I normally reconstruct during close, prepared before close starts.