Files
rick 212f19ac19 Add v6-rewrite OpenSpec: proposal, design, specs, and tasks
Complete specification for rewriting Swarmops v5 as using.cash v6:
- Proposal: scope buckets (Working Rewrite / First Beyond Working / Maybe),
  non-goals (governance, geography, memberships permanently cut)
- Design: 18 architectural decisions including preserved patterns
  (Basic/Logic, stored procs, credential split), new patterns (repository
  classes, chain abstraction, rate providers), and operational concerns
  (Galera awareness, continuation transactions, VAT booking, OOD
  denormalization)
- Specs: 17 capability specifications with SHALL/MUST requirements and
  WHEN/THEN scenarios, covering accounting core, AP/AR, crypto treasury,
  exchange rates, organizations, users/auth, documents, comms, dashboard,
  end-of-month, backend worker, event bus, data migration, API layer,
  frontend app, and CI/packaging
- Tasks: 145 implementation tasks grouped by subsystem, ordered by
  dependency (migration gates API/frontend work)

Two rounds of adversarial review incorporated.

Made-with: Cursor
2026-04-08 16:02:58 +02:00

7.2 KiB

ADDED Requirements

Requirement: One-time ETL migration tool

The system SHALL include a migration tool that reads from a v5 Swarmops MySQL database and populates a v6 UsingCash MySQL database. The v5 database MUST NOT be modified by the migration. The tool runs as a standalone CLI application.

Scenario: Run migration

  • WHEN an administrator runs the migration tool pointing to v5 and v6 database connection strings
  • THEN the tool reads v5 data, transforms it to v6 schema, and writes to the v6 database

Scenario: v5 database untouched

  • WHEN the migration completes
  • THEN the v5 database has zero modifications (no rows inserted, updated, or deleted)

Requirement: Financial data migration

The tool SHALL migrate: financial accounts (chart of accounts with OwnerUserId), financial transactions and transaction rows (including foreign currency amounts from FinancialTransactionRowsNativeCurrency), transaction tags and tag sets, budget allocations, expense claims, inbound invoices, outbound invoices (including credit-link optional data), payouts, payments, payment groups, refunds, and continuation transaction dependency chains. All monetary amounts SHALL be preserved exactly (Int64 cents/satoshis, no rounding). OrganizationSequenceId values SHALL be preserved exactly.

Scenario: Ledger data fidelity

  • WHEN financial transactions are migrated
  • THEN every transaction row's amount in v6 is identical to v5, and account balances computed from v6 data match v5 exactly

Scenario: Foreign currency amounts preserved

  • WHEN v5 transaction rows have associated native currency data in FinancialTransactionRowsNativeCurrency
  • THEN the foreign currency code and amount are migrated to the corresponding v6 columns

Scenario: Continuation chains preserved

  • WHEN v5 has continuation transactions linked via FinancialTransactionDependencies with type FinancialTransaction
  • THEN the dependency chain is preserved in v6

Scenario: Closed-period marking

  • WHEN an organization's FiscalBooksClosedUntilYear (stored as OrgBooksClosedForYear in v5 ObjectOptionalData) is N
  • THEN the v6 organization's ClosedThroughYear is set to N and all transactions in years <= N are marked as belonging to a closed period

Requirement: ObjectOptionalData denormalization

The tool SHALL read the v5 ObjectOptionalData EAV table and denormalize kept keys into first-class v6 columns per the mapping in design decision D16. The tool SHALL report any EAV keys found in v5 data that are not in the explicit keep/drop mapping, so nothing is silently lost.

Scenario: Org settings denormalized

  • WHEN v5 has OrgEconomyEnabled, OrgCurrency, OrgFirstFiscalYear, OrgBooksClosedForYear, OrgValueAddedTaxEnabled, OrgGovtRegistrationId, etc. in ObjectOptionalData
  • THEN these become first-class columns on the v6 Organizations table

Scenario: Financial account metadata denormalized

  • WHEN v5 has FinancialAccountNativeCurrency, FinancialAccountBitcoinPublicAddress, BankTransactionTag, etc.
  • THEN these become first-class columns on the v6 FinancialAccounts table

Scenario: Unknown EAV key warning

  • WHEN the migration encounters an ObjectOptionalData key not in the keep or drop list
  • THEN it logs a warning with the key name, object type, and object ID

Requirement: Entity migration

The tool SHALL migrate: organizations (flat, dropping tree hierarchy and ParentOrganizationId), people (as users, dropping membership/activist data but preserving bank details, bitcoin payout address, preferred culture, and other kept optional data), currencies and exchange rate history (with micro-BTC scaling preserved), crypto hot wallet addresses and UTXOs, documents metadata (storage paths preserved pointing to existing filesystem), and system settings.

Scenario: People to users

  • WHEN v5 People records are migrated
  • THEN they become v6 User records with name, email, a flag indicating password reset is required, and denormalized optional data (bank details, bitcoin payout address, preferred culture)

Scenario: Organization flattening

  • WHEN v5 organizations with parent-child relationships are migrated
  • THEN each becomes a flat v6 organization with no hierarchy reference; ParentOrganizationId is dropped

Scenario: Exchange rate history preserved

  • WHEN v5 exchange rate snapshots and datapoints are migrated
  • THEN the micro-BTC scaling convention and BCH exception are preserved exactly

Requirement: Auth/access migration

The tool SHALL create v6 role assignments based on v5 position/access data. Users who held positions with system-level or org-level access in v5 SHALL be assigned corresponding v6 roles. The mapping from v5 position types to v6 roles SHALL be documented and auditable.

Scenario: Admin position migrated

  • WHEN a v5 person held a system-admin-level position
  • THEN they receive the system administrator role in v6

Scenario: Org-level access migrated

  • WHEN a v5 person held an org-level financial position
  • THEN they receive an appropriate financial role in v6

Requirement: Selective migration

The tool SHALL NOT migrate: governance data (elections, ballots, motions, polls), geography hierarchies, membership records, activist/volunteer data, parleys, media entries, PirateWeb/Activizr-era event data, or ObjectOptionalData keys explicitly classified as "dropped" in design D16.

Scenario: Governance data skipped

  • WHEN the migration tool encounters governance-related tables
  • THEN it skips them entirely

Requirement: Multi-level verification pass

The migration tool SHALL include a verification mode with multiple levels of checking:

  1. Aggregate level: Balance sheets and P&L reports for all closed periods, compared between v5 and v6
  2. Account level: Per-account-per-year transaction totals, compared between v5 and v6
  3. Transaction level: Spot checks on individual transactions (row counts, amounts, foreign currency data)
  4. Checksum level: Per-organization-per-year hash of all transaction row amounts, ensuring no drift

Scenario: Aggregate verification succeeds

  • WHEN the verification pass compares all closed-period balance sheets and P&L
  • THEN every figure matches exactly between v5 and v6

Scenario: Account-level verification succeeds

  • WHEN the verification pass compares per-account annual totals
  • THEN every account's annual total matches exactly

Scenario: Verification finds discrepancy

  • WHEN any figure differs at any verification level
  • THEN the tool reports the specific level, accounts, periods, and amounts that differ and exits with a failure code

Requirement: Idempotent re-run

The migration tool SHALL support re-running against a v6 database. Re-running drops and recreates the v6 data (or uses an upsert strategy) so that the migration can be repeated during development and testing without manual cleanup.

Scenario: Re-run migration

  • WHEN the migration tool is run against a v6 database that already contains migrated data
  • THEN the existing data is replaced with a fresh migration from v5