accounted/lib/pending-operations/risk-tiers.ts

/**
 * Risk tier classification for pending_operations.
 *
 * Used by lib/pending-operations/should-auto-commit.ts to decide whether a
 * staged proposal from a trusted agent can be auto-committed without human
 * review.
 *
 * Tiering principles:
 *   - **low**: no booking impact, no external side-effects, no audit risk.
 *     A reasonable bookkeeper would never want to manually approve these.
 *   - **medium**: reversible booking impact (drafts, transaction
 *     categorization that can be uncategorized). Auto-commit is allowed for
 *     trusted agents under a configurable monetary threshold.
 *   - **high**: irreversible or compliance-critical. Sends external messages,
 *     locks/closes periods, or affects tax filings. NEVER auto-committed,
 *     regardless of company opt-in or trust level.
 */

export type RiskLevel = 'low' | 'medium' | 'high'

export const OPERATION_RISK_TIERS: Record<string, RiskLevel> = {
  // ── Low: pure data, no booking impact ─────────────────────────────
  create_customer: 'low',
  // Article catalog (artikelregister) is app-level master data: no journal
  // impact, no external side-effect. Unlike create_supplier it carries no
  // payment-routing fields, so there's no BEC/fraud surface; both create and
  // update sit at the lowest tier next to create_customer.
  create_article: 'low',
  update_article: 'low',
  // Dimension values (kostnadsställe/projekt object codes, SIE #OBJEKT) are
  // reporting master data: no journal impact, no external side-effect, no
  // payment-routing surface. Staged (agents never silently mint reporting
  // values) but at the lowest tier next to create_customer/create_article.
  create_dimension_value: 'low',

  // ── Medium: reversible booking ─────────────────────────────────────
  categorize_transaction: 'medium',
  match_transaction_invoice: 'medium',
  // Link an existing posted verifikat as payment for an invoice. Reversible by
  // deleting the invoice_payments row and reverting invoice status; no journal
  // entry is created or modified. Sits next to match_transaction_invoice
  // semantically: both attach an existing booking to an invoice.
  link_invoice_voucher: 'medium',
  // Supplier-side mirror of link_invoice_voucher: link an existing posted
  // verifikat (Dr 2440) as payment for a leverantörsfaktura. Reversible by
  // deleting the supplier_invoice_payments row and reverting status; no journal
  // entry is created or modified.
  link_supplier_invoice_voucher: 'medium',
  create_invoice: 'medium', // creates as draft; sending is a separate op
  create_transaction: 'medium', // ingests an uncategorized row; reversible by delete
  // Supplier master data carries payment-routing fields (IBAN, BIC, bankgiro,
  // bank_account) that drive outgoing payment files and supplier invoice
  // postings. A wrong account or org_number can enable supplier-fraud / BEC
  // (silently rerouting payment), so always require explicit human approval
  // rather than auto-commit.
  create_supplier: 'medium',
  // Pinning a doc to a tx is reversible while pre-categorization, but the link
  // becomes part of the verifikation underlag (BFL 5 kap 6 §) once categorize
  // propagates it. A wrong attachment requires a rättelse, so require human
  // approval rather than auto-commit.
  attach_document_to_transaction: 'medium',
  // Linking a doc to a posted verifikation is part of räkenskapsinformation
  // (BFL 5 kap 6 §) and becomes immutable once the JE is posted. Medium so a
  // human confirms the doc-to-verifikat pairing before it locks.
  link_document_to_voucher: 'medium',
  // Dimension-only diff on posted lines (verifikat stays immutable), fully
  // audited via dimension_retag_log, but it rewrites reporting history, so
  // it crosses a human at medium.
  retag_line_dimensions: 'medium',

  // ── High: irreversible, compliance-critical, or external side-effects
  send_invoice: 'high',          // emails the customer
  mark_invoice_paid: 'high',     // posts payment journal entry
  mark_invoice_sent: 'high',     // assigns invoice number, accrual JE

  // ── Stream 1 Phase 1 ops (added when those tools land) ─────────────
  close_period: 'high',
  lock_period: 'high',
  unlock_period: 'high',
  set_opening_balances: 'high',
  run_year_end: 'high',
  run_currency_revaluation: 'high',
  // Planenlig avskrivning: one journal entry per asset, each independently
  // reversible (storno). Mid-stakes bokslut posting: staged and human-reviewed,
  // but not the irreversible tier that year-end close / period lock occupy.
  post_annual_depreciation: 'medium',
  import_sie: 'high',
  // Hard-deletes the import's journal entries + resets voucher sequences.
  // Same destructive reach as replace_sie_import; never auto-commit.
  undo_sie_import: 'high',
  explain_voucher_gap: 'medium',
  uncategorize_transaction: 'medium',
  approve_supplier_invoice: 'high',
  credit_supplier_invoice: 'high',
  // Create supplier invoice from inbox: stages a `registered` supplier invoice
  // + its line items + document attachment. Reversible until approved (the
  // approval is a separate high-risk op) but creates a leverantörsskuld row,
  // so we route it through human review at medium tier.
  create_supplier_invoice_from_inbox: 'medium',
  credit_invoice: 'high',
  convert_invoice: 'medium',

  // ── Phase 4: arbitrary-line bookkeeping primitives ─────────────────
  // Both accept caller-supplied account/amount/period: unlike
  // uncategorize_transaction (medium), which mirrors an existing entry.
  // The arbitrary-line capability is what makes these compliance-critical.
  create_voucher: 'high',
  correct_entry: 'high',
  reverse_entry: 'high',

  // ── Payroll ────────────────────────────────────────────────────────
  // Salary run creation materialises a draft + per-employee base lines. The
  // run is reversible while still draft, so 'medium' aligns with other
  // create-draft operations. AGI generation produces the Skatteverket
  // underlag (XML, BFL 7-year retention): statutory artifact, always
  // staged.
  create_salary_run: 'medium',
  generate_agi: 'high',
  // Payslip line edits are draft-run-only (BFL: once the run advances its
  // numbers feed a verifikation) and re-editable until then, but they change
  // a pay outcome: human review at medium, never silent.
  update_payslip_line: 'medium',
  // Absence rows drive sjuklön math and the statutory AGI Frånvarouppgift.
  // Reversible via delete, but not audit-free: medium.
  register_absence: 'medium',
  // Employee master data carries PII (personnummer, encrypted at staging
  // time: pending_operations.params never holds the plaintext) plus bank
  // payment-routing fields: same BEC rationale as create_supplier.
  create_employee: 'medium',
  update_employee: 'medium',
  // Cutover state for mid-year migrations (YTD, vacation balances, karens
  // adjustment). Editable until the employee has a booked run; wrong values
  // skew payslips and the vacation-liability report, so human review.
  set_employee_opening_balances: 'medium',
  // Semesterårsavslut: closes every employee's vacation year, rolls sparade
  // dagar (5-year expiry -> forced payout), and may post a 2920/2940
  // adjustment verifikation. Irreversible in practice (no reopen flow):
  // never auto-committed.
  vacation_year_close: 'high',

  // ── Multi-tx flows (PRs #603/#606/#608/#610) ───────────────────────
  // Allocate 1 bank tx across N customer or supplier invoices into one
  // combined verifikat. Reversible via storno + invoice_payments delete,
  // so 'medium' (same tier as match_transaction_invoice: its single-
  // invoice counterpart).
  match_batch_allocate: 'medium',
  // Bulk-book N bank txs into 1 verifikat. The create-new branch posts
  // a verifikat with caller-supplied lines (template-expanded or manual),
  // the same compliance-critical surface as create_voucher. 'high'.
  bulk_book_transactions: 'high',
  // Bulk-book N selected Underlag (Dokumentinkorgen): one posted verifikat per
  // matched bank transaction, each with VAT (incl. reverse charge) derived from
  // a shared category. Posting N verifikat at once is the same compliance-
  // critical surface as bulk_book_transactions, so 'high': never auto-commit;
  // approval requires confirmed=true.
  bulk_book_inbox_items: 'high',
  // Link a single bank tx to an already-posted verifikat (no new JE created).
  // Reversible by clearing transactions.journal_entry_id and deleting any
  // invoice_payments row: sits next to link_invoice_voucher semantically;
  // both attach an existing booking to a different entity.
  link_transaction_journal_entry: 'medium',

  // ── Skatteverket filing (PR5) ──────────────────────────────────────
  // External + irreversible once signed. Commit sends the declaration for
  // BankID signing; the user's signature in the browser is the filing act.
  // (getRiskLevel already defaults unknown → 'high'; explicit for intent.)
  submit_vat_declaration: 'high',
  submit_agi: 'high',
}

export function getRiskLevel(operationType: string): RiskLevel {
  // Default to 'high' for unknown ops, fail-safe: unknown means human review.
  return OPERATION_RISK_TIERS[operationType] ?? 'high'
}

/**
 * High-risk operations are NEVER auto-committed, regardless of company opt-in
 * or actor trust. Encoded here (not in DB config) so it can't be bypassed.
 */
export function isHighRisk(operationType: string): boolean {
  return getRiskLevel(operationType) === 'high'
}