--- id: DOM-ACC-BKS-006 title: Accounting Workspace realises: CON-ACC-BKS-006 product_area: accounting module: books revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-ACC-BKS-books readable_by: - SVC-ACC-BKS-maintenance lifecycle: STATE-ACC-BKS-005 custom_fields: none identity: >- Platform assigns the workspace identity. Accounting keeps shared definitions under configuration identities, one optional settings row under the workspace key, and schedules identified independently with one schedule per work kind and owning subject. attributes: - name: payment terms kind: collection required: false computed: false notes: >- Named invoice durations range from zero to one thousand days with up to two decimal places; duplicate names are permitted and no unit is required. - name: payment methods kind: collection required: false computed: false notes: >- Methods combine fixed card, bank-debit or offline behavior with names, reference prompts, channels, offline handling and ordering; provisioning creates five protected methods. - name: tax classes kind: collection required: false computed: false notes: >- Workspace classifications supply the transitional tax vocabulary until the Commerce ownership change. - name: tax zones and rates kind: collection required: false computed: false notes: >- Zones store geographic criteria and priority, with up to twenty rates carrying class percentages and payable destinations by unit. - name: settings kind: collection required: true computed: false notes: >- Defaults are returned at version zero without inserting a row. Stored policies include the statement default, overpayment and refund choices, deferral handling and service-period requirement; Reconciliation and Close switches are stored but absent from this API. - name: schedules and their runs kind: collection required: false computed: false notes: >- Maintenance stores recurrence definitions, enablement, timing, run results, failure counts and pause reasons; a claimed occurrence has one run row that can be attempted repeatedly. - name: lifecycle standing kind: computed required: true computed: true notes: >- The availability gate reads Platform state and status using a per-process cache lasting up to thirty seconds. - name: workspace time zone and date kind: computed required: true computed: true notes: >- Platform supplies the workspace time zone used for local dates and recurrence defaults. relationships: - to: DOM-ACC-BKS-001 cardinality: A workspace contains multiple sets of books ownership: >- Shared definitions are maintained at workspace level and apply across units. cross_service: false - to: DOM-ACC-BKS-002 cardinality: Each tax rate can select a payable destination in multiple units ownership: >- Each rate owns its payable links; the referenced account stays in its unit’s chart. cross_service: false - to: DOM-ACC-BKS-004 cardinality: The settings record optionally selects one statement template ownership: Workspace settings own the optional reference to shared statement content. cross_service: false invariants: - id: INV-DOM-ACC-BKS-006-01 statement: >- A saved payment method retains its behavior. A provisioned system method also retains active standing and its deposit handling through ordinary replacement. enforced_at: - service - database provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/payment-methods.integration.spec.js#refuses to be deactivated, 409 payment_method_system - id: INV-DOM-ACC-BKS-006-02 statement: >- Offline methods are offered only to console users, and bounce or undeposited handling belongs only to offline behavior. enforced_at: - service - database provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/payment-methods.integration.spec.js#refuses an offline method offered in the portal, naming the rule - id: INV-DOM-ACC-BKS-006-03 statement: >- Declared restricting references prevent deletion of payment terms and tax classes that are still in use. enforced_at: - service - database provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/tax-classes.integration.spec.js#translates the refusal of each restrict foreign key to a tax class into a 409 naming it, the invoice lines among them - id: INV-DOM-ACC-BKS-006-04 statement: >- There is at most one settings row per workspace, with an empty default or an active same-workspace statement template. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/books/db/settings.table.ts:settings_template_references_trigger - id: INV-DOM-ACC-BKS-006-05 statement: >- A claimed schedule occurrence has a single run row; disabled schedules receive no new claims, but unfinished runs may execute again. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/maintenance/db/schedules.table.ts; services-accounting:modules/maintenance/aws/lambda/CONSUMER.ts:handler; services-accounting:package-lock.json - id: INV-DOM-ACC-BKS-006-06 statement: >- Recording five consecutive failed runs disables an enabled schedule with a pause reason. enforced_at: - service provenance: test source: >- services-accounting:modules/maintenance/tests/integration/services/scheduling/schedules-end-to-end.integration.spec.js#pauses the schedule after the fifth failure in a row - id: INV-DOM-ACC-BKS-006-07 statement: >- Lifecycle declarations assign each customer Accounting table to one participant, and workspace purge operates only on the selected workspace’s records. enforced_at: - service - database provenance: test source: >- services-accounting:modules/maintenance/tests/integration/db/declaration-completeness.integration.spec.js#leaves no tenant-keyed table undeclared - id: INV-DOM-ACC-BKS-006-08 statement: >- A part is blocked when its serialized records match the secret guard’s recognized Stripe patterns. enforced_at: - service provenance: test source: >- services-accounting:modules/maintenance/tests/integration/services/exports/seed-everything.integration.spec.js#stops a batch whose record carries a Stripe secret’s shape, blocked with nothing staged - id: INV-DOM-ACC-BKS-006-09 statement: >- The request gate refuses ordinary users outside an active enabled workspace, permits data-job routes during loading and reserves deleting-workspace reads for staff. enforced_at: - api provenance: test source: >- services-accounting:modules/maintenance/tests/unit/lifecycle/tenant-availability.spec.js#serves only an active tenant that is not disabled, and refuses every other combination physical: - accounting.payment_terms - accounting.payment_methods - accounting.tax_classes - accounting.tax_zones - accounting.tax_rates - accounting.tax_rate_classes - accounting.settings - accounting.schedules - accounting.schedule_runs - platform.tenants (read only) evidence: - >- services-accounting at f47cb263: modules/books/db/payment-terms.table.ts, payment-methods.table.ts, payment-method-seeds.ts, tax-classes.table.ts, tax-zones.table.ts, tax-zone-rates.table.ts, settings.table.ts - >- services-accounting at f47cb263: modules/maintenance/db/schedules.table.ts; services/persistence/schedules.ts, tenants.ts; services/lifecycle/*; services/participants/*; services/exports/* --- # Accounting Workspace ## What It Models The Accounting workspace collects configuration shared across the customer’s sets of books. It includes terms, payment methods, transitional tax setup, policy settings and recurring timing. It also represents Accounting’s participation in Platform’s workspace provisioning, export and erasure. ## Identity and Attributes Accounting uses Platform’s workspace key and reads its time zone and availability state. Shared vocabularies have independent configuration identities. Payment methods combine editable presentation with fixed engine behavior; provisioning adds the protected starting set atomically. Settings are returned as defaults at version zero until first saved. Schedules store definitions and execution history in maintenance. One occurrence has one history identity, but its unfinished handler may run more than once. ## Relationships Definitions and policies apply to every unit. Tax-rate links select accounts in unit charts, and settings reference statement content. Scheduled work belongs to its subject’s module; maintenance supplies timing and history rather than ownership of the subject. ## Invariants The implementation protects method behavior, declared financial references, singleton settings and valid template choices. Scheduling prevents duplicate run identities and pauses repeated failure; it does not promise one handler execution. Export blocks recognized secret patterns. Purge checks the workspace state before each bounded removal. ## How It Is Stored and Shared Books maintains shared definitions and settings. Maintenance owns the schedule tables and serves lifecycle calls; its reads and purge writes span Accounting. Other financial modules consume shared configuration directly. Platform retains ownership of the workspace record and lifecycle transitions. Customer tables use forced row-level security, with narrow cross-workspace policies for schedule claims. The registered configuration has no custom-field capability or configuration history stream. ## Open Design Questions Tax ownership, history and Billing’s scheduling boundary remain unsettled. Several policy settings have no console control, and the Reconciliation and Close switches have no change path in this API. The single conceptual owner spans Books and maintenance, so responsibility must be read together with the physical ownership boundary.