Concho Modernization Stakeholder Review

Section Takeaways

1. Introduction

1.1 Purpose and Scope

This document presents a comprehensive modernization analysis for the Payment Processing subsystem within the Applewood Computers Accounting System (ACAS), examining the transformation path from a legacy GnuCOBOL-on-Linux architecture with dual ISAM/MySQL data storage and a terminal-based UI to a containerized Python/FastAPI deployment running on Docker Compose for development and AWS ECS Fargate in production. The subsystem analyzed — Payment Processing — was selected by the customer, ensuring alignment with actual business modernization priorities rather than a generic recommendation.

The analysis addresses a critical business challenge facing organizations with decades-old COBOL systems: how to modernize proven accounting logic while eliminating platform-imposed constraints that hinder productivity. ACAS represents a 48+-year-old open-source accounting platform serving small-to-medium businesses with a terminal-based user interface (80×24 character screens) and a dual-mode ISAM-file and MySQL/MariaDB persistence layer. The Payment Processing subsystem handles cash posting, payment data entry, payment amendment, and payment proof processing — critical financial operations requiring behavioral fidelity during modernization while enabling modern user experience improvements and cloud-native scalability.

1.2 What Concho Provided

This report leverages two distinct Concho capabilities:

1. Pre-Built Legacy System Analysis: Before this modernization report was generated, Concho performed deep analysis of the entire ACAS codebase — 1.36 million total lines across the repository, with 381,073 lines classified into architectural layers — discovering 36 business functions, 6 behavioral rules specific to Payment Processing (within a broader catalog of 308 rules enforced across the system), architectural layers, data dependencies, and platform constraints. This foundational analysis (conducted once for the entire codebase) provides the raw intelligence that makes rapid, accurate modernization planning possible.

2. Concho Modernization Report Workflow: This document was generated in approximately 90 minutes using Concho's modernization workflow, which leverages the pre-built analysis to produce customer-specific modernization plans. The workflow combines Concho's pre-computed insights (business rules, constraints, dependencies, aggregate roots, integration boundaries) with AI-generated architecture designs, code translation examples, and deployment artifacts tailored to Docker Compose and AWS ECS Fargate patterns. This two-stage approach — comprehensive upfront analysis followed by rapid report generation — explains why Concho can produce in hours what traditionally requires weeks of manual effort.

The pre-built analysis achieved 100% code coverage (vs. 20-30% sampling in manual reviews), extracted 308 behavioral rules with source code traceability (for example, PaymentBatchControlLimits — the 99-items-per-batch ceiling — is grounded at purchase/pl080.cbl:733), and discovered platform constraints like the 80×24 terminal-dimension requirement and 40-line-item purchase-invoice ceiling that modernization can eliminate. The modernization workflow then used this intelligence to design a 3-microservice AWS ECS Fargate architecture, generate PostgreSQL schemas, create Python (FastAPI) code translations with behavioral rule cross-references, and document UI transformations from 80×24 terminal screens to responsive web interfaces. All analysis outputs include confidence scores and evidence classification, enabling architects to understand the certainty behind each finding.

1.3 Report Organization

This report is organized to serve both strategic decision-makers and implementation teams. Each numbered section produces a structured handoff that feeds the companion code-generation workflow described above:

• Section 1 — Introduction: Purpose, scope, and the two-stage Concho capability (this section).
• Section 2 — Modernization Scope: Subsystem selection rationale and the explicit candidate set considered.
• Section 3 — Legacy System Analysis: Baseline architecture, technology stack, business functions, and constraints across the ACAS codebase.
• Section 4 — Target Architecture: Docker Compose / AWS ECS Fargate service topology, runtime, and platform-level decisions.
• Section 5 — Platform Affinity Analysis: Per-component justification for the chosen target platform.
• Section 6 — Technical Debt Analysis: For ACAS the source has no external dependency manifest so this section is a deliberate stub — the legacy stack is itself the debt and is wholesale replaced by the target stack covered in Section 4. The full Tech Debt catalog (library EOL, CVE exposure, transitive-dep graph) re-engages on modernizations whose source has a real package manifest (npm, Maven, NuGet, pip, Gemfile, …).
• Section 7 — UI/UX Transformation Examples: Storyboarded transition from terminal screens to a modern web UI.
• Section 8 — Code Translation Examples: Side-by-side COBOL-to-Python (FastAPI) translations with behavioral-rule cross-references.
• Section 9 — Business Rules Analysis: Given/When/Then behavioral-rule catalog for Payment Processing.
• Section 10 — Data Mapping Strategy: Legacy ISAM/MySQL records to PostgreSQL schema.
• Section 11 — Modernization Strategy: Strangler-fig phasing, the SAROC coexistence bridge, and rollout sequencing.
• Section 12 — How Concho Helped This Modernization Planning: The Concho MCP query trace and analysis lineage that produced the findings — how the planning agents consumed the Context Graph.
• Appendix A — Multi-Agent Subsystem Selection: Three-run consensus selection log.
• Appendix B — Service Architecture: Per-service contracts, ports, and dependency map for the target.
• Appendix C — Deployment: docker-compose, ECS task definitions, and CI/CD pipeline artifacts.

What this report does not include: dollar-value cost estimates, calendar-date timelines, staffing plans, or organizational change management recommendations. Those belong in the engagement-specific delivery plan that follows stakeholder alignment on this analysis.

1.4 Stakeholder Reading Guide

2. Modernization Scope

This report leverages Concho's deep insight into all 36 subsystems in ACAS. A variety of criteria was applied against each one in order to find the right balance between technical feasibility, business value, and modernization risk in order to select a candidate subsystem for this first modernization project.

2.1 Customer-Specified Use Case

The Payment Processing subsystem was explicitly specified by the customer as the modernization target for this initiative. This decision was made by the customer's finance and IT leadership based on their assessment of business priorities and immediate operational needs. To validate that selection, Concho ran an independent multi-agent consensus methodology against the full 36-subsystem inventory; that methodology — described in Appendix A: Multi-Agent Subsystem Selection Methodology — arrived at the same recommendation through three independently-weighted scoring runs.

Why Payment Processing is the Right First Modernization

• Bounded, identifiable scope. Approximately 30 strong-association COBOL programs (~14,800 LOC) cluster cleanly across purchase/pl08x-pl9xx (supplier outflow), sales/sl08x-sl1xx (customer receipts), and a shared common/paymentsMT Data Access Layer — small enough for a first pilot, substantial enough to prove the modernization pattern.
• High executive visibility. Cash disbursement (supplier payments via cheque and BACS) and cash receipt allocation are the modules a CFO sees every day; the remittance advice output (pl960) is a customer-facing artifact. A successful pilot delivers tangible, finance-relevant business value rather than back-office plumbing.
• Exercises the full SAROC coexistence pattern. The watched artifacts already named in report-plan.json (pay.dat, openitm5.dat, purchled.dat) map one-to-one onto Payment Processing's strong-file set, so the file-watcher CDC → translator → RabbitMQ → Python/FastAPI consumer → PostgreSQL chain gets fully validated on this single subsystem.
• Lower blast radius than the alternatives. Payment Processing posts to the General Ledger but is not posted-from by other modules, so the strangler-fig bridge fans out from a smaller surface than GL, Stock Control, or the Invoicing subsystems would offer.
• Pattern reuse multiplier. Two parallel mirror flows (PL outflow and SL inflow) implement essentially the same workflow against different ledgers, so the second flow validates the pattern proven by the first — and the dual-storage adapter, GL-integration callback, and external-document generation patterns then transfer directly to the next subsystems on the roadmap.

2.2 Methodology Validation Reference

While Payment Processing was customer-specified, organizations needing assistance selecting modernization candidates can use Concho's multi-agent consensus methodology. Three independent agent runs — emphasizing standard weighted scoring, technical feasibility, and business value respectively — evaluated all 36 ACAS subsystems against quantified criteria and reached full consensus on Payment Processing. See Appendix A: Multi-Agent Subsystem Selection Methodology for the complete scoring tables, run-by-run analysis, and consensus details.

3. Legacy System Analysis

3.1 High-Level System Architecture

ACAS implements a classical layered architecture — presentation, application, data, integration, cross-cutting, infrastructure, build — with one distinguishing feature: a dual-mode storage strategy that allows runtime switching between traditional ISAM indexed files and MySQL/MariaDB databases through a unified Data Access Layer. The diagram below is the Concho-vended architecture layer artifact (artifact ID architecture_layer_diagram, confidence 0.95) emitted directly by the Context Graph; line counts on each layer come from the architectural classification of the codebase, not from this report.

graph TB
    subgraph Presentation["Presentation Layer (9,042 lines)"]
        MENUS["Terminal Menu Navigation
6,965 lines"]
        ENQUIRY["Business Enquiry Interface
2,077 lines"]
    end

    subgraph Application["Application Layer (87,374 lines)"]
        SALES["Sales Management
27,250 lines"]
        PURCHASE["Purchase Management
18,234 lines"]
        IRS["IRS Tax Processing
11,003 lines"]
        GL["General Ledger
11,127 lines"]
        PAYMENT["Payment Processing
7,142 lines"]
        STOCK["Stock Control
7,343 lines"]
        BACKORDER["Back Order Management
1,084 lines"]
        BATCH["Batch Processing
2,204 lines"]
    end

    subgraph CrossCutting["Cross-Cutting Concerns (3,588 lines)"]
        AUDIT["Audit Processing
356 lines"]
        ERROR["Error Handling
141 lines"]
        SECURITY["Security Framework
225 lines"]
        LOGGING["Logging Utilities
402 lines"]
        UTILITIES["Common Utilities
1,910 lines"]
    end

    subgraph Data["Data Layer (148,577 lines)"]
        DBACCESS["Database Access Layer
78,239 lines"]
        MIGRATION["Data Migration Utilities
30,104 lines"]
        ISAM["ISAM File Handlers
19,592 lines"]
        DBPROC["Database Procedures
13,844 lines"]
        SCHEMA["File Definitions
3,710 lines"]
        MYSQL["MySQL Schema
2,730 lines"]
    end

    subgraph Integration["Integration Layer (922 lines)"]
        BRIDGE["MySQL COBOL Bridge
922 lines"]
    end

    subgraph Infrastructure["Infrastructure (10,854 lines)"]
        DBCONN["Database Connectivity
5,023 lines"]
        CONFIG["System Configuration
4,759 lines"]
        BACKUP["Backup Scripts
101 lines"]
        MONITOR["System Monitoring
249 lines"]
    end

    MENUS --> SALES
    MENUS --> PURCHASE
    MENUS --> IRS
    MENUS --> GL
    ENQUIRY --> SALES
    ENQUIRY --> PURCHASE

    SALES --> DBACCESS
    PURCHASE --> DBACCESS
    IRS --> DBACCESS
    GL --> DBACCESS
    PAYMENT --> DBACCESS
    STOCK --> DBACCESS

    SALES --> ISAM
    PURCHASE --> ISAM
    IRS --> ISAM
    GL --> ISAM

    DBACCESS --> BRIDGE
    DBACCESS --> DBPROC
    ISAM --> SCHEMA

    BRIDGE --> DBCONN
    DBPROC --> DBCONN

    SALES --> AUDIT
    PURCHASE --> AUDIT
    GL --> AUDIT
    IRS --> AUDIT
    PAYMENT --> AUDIT

    DBACCESS --> CONFIG
    ISAM --> CONFIG
    

Source: Concho Context Graph — architecture_layer_diagram artifact (confidence 0.95). Line counts reflect Concho's architectural classification.

3.2 Architectural Layers

Concho's architectural classification distributes 381,073 lines of architectural code (excluding documentation and user-manual content) across seven primary layers. The Data Layer is by far the heaviest at 39.0%, reflecting the dual-storage abstraction (ISAM file handlers plus MySQL MT modules). The Application Layer at 22.9% holds the business-logic modules including Payment Processing. The Presentation Layer is unusually thin (2.4%) — characteristic of terminal-based systems where the UI is overwhelmingly menu navigation and screen formatting rather than rich client code.

Within the Application Layer, the eight major business sub-areas break down as: Sales Management (27,250 lines), Purchase Management (18,234), General Ledger (11,127), IRS Tax Processing (11,003), Stock Control (7,343), Payment Processing (7,142), Batch Processing (2,204), and Back Order Management (1,084). Payment Processing itself decomposes into four leaf-level capabilities: Payment Amendment (3,240 lines), Payment Data Entry (1,742), Cash Posting (1,602), and Payment Proof Processing (558).

3.3 Data Entities

Concho's deep scan identified 56 aggregate roots distributed across 37 bounded contexts, with an average of 6.86 relationships per entity and 308 business rules enforced across the entire domain model. Every aggregate root carries STRUCTURAL evidence (derived from code structure rather than inferred behavior), giving high confidence in the domain model. The table below shows the top aggregate roots by confidence score — including the Payment aggregate that this modernization centers on.

The relationships among these aggregates form a recognizable accounting domain model, with Transaction and DataAccessLayer acting as relational hubs. The simplified entity-relationship diagram below is derived from Concho's aggregate-root and bounded-context discovery; it is an agent-constructed view of the domain rather than a Concho-vended artifact.

erDiagram
    Customer ||--o{ SalesInvoice : "is billed via"
    SalesInvoice ||--o{ Transaction : "generates"
    PurchaseInvoice ||--o{ Transaction : "generates"
    Payment ||--o{ Transaction : "settles"
    Transaction }o--|| GeneralLedger : "posts to"
    Transaction }o--|| Batch : "is grouped in"
    GeneralLedger ||--|{ ChartOfAccounts : "uses"
    Payment }o--o{ PurchaseInvoice : "appropriates"
    Payment }o--o{ SalesInvoice : "appropriates"
    StockItem ||--o{ Transaction : "moves via"
    CustomerStatement }o--|| Customer : "summarizes"
    DataAccessLayer ||..o{ Customer : "persists"
    DataAccessLayer ||..o{ SalesInvoice : "persists"
    DataAccessLayer ||..o{ PurchaseInvoice : "persists"
    DataAccessLayer ||..o{ Payment : "persists"
    DataAccessLayer ||..o{ GeneralLedger : "persists"
    DataAccessLayer ||..o{ StockItem : "persists"
    SecurityControl ||..o{ Customer : "guards"
    SecurityControl ||..o{ Payment : "guards"
    ErrorHandlingSystem ||..o{ DataAccessLayer : "translates errors for"
    

Derived from Concho aggregate-root and bounded-context discovery. Solid lines indicate domain relationships; dotted lines indicate cross-cutting infrastructure relationships.

Field-level mapping from the legacy WS-Pay-Record and related copybooks to the target data model is covered in Section 10 (Data Mapping Strategy).

3.4 Business Rules & Behavior

Concho cataloged 308 business rules across the ACAS domain, with the Payment aggregate root contributing 6 directly. Among the Payment-specific rules are PaymentBatchControlLimits (99-item batch ceiling, enforced by the PIC 99 count field WS-Pay-Nos at copybooks/wspay.cob:13; sequential batch numbering at purchase/pl080.cbl:325; composite-key construction, batch × 1000 + item, at purchase/pl080.cbl:733), PaymentAppropriationLogic (automatic allocation against outstanding invoices with overpayment prevention and timing-based early-payment discount; purchase/pl080.cbl:421/492/592), PaymentPostingValidation, RemittanceAdviceProcessingRules, UnappliedBalanceAllocation, and PaymentReversalProcessing.

Detailed Given/When/Then specifications for these rules — including the full source-evidence trail and the corresponding behavioral tests — are presented in Section 9 (Business Rules Analysis).

3.5 Technology Stack

The ACAS technology stack reflects its origin as a GnuCOBOL system that has been extended with modern RDBMS integration while preserving backward compatibility with traditional file-based storage. Concho identified 32 distinct technology subjects across the codebase.

Reading the table: “Prevalence” is the share of all cataloged source files (~630) in which each technology appears. The first three rows all report 449 files (71%) because the language (COBOL), its runtime (GnuCOBOL), and the legacy ISAM file storage are three properties of the same 449-file COBOL core — this is one file set described from three angles, not three separate counts. Rows below it (MySQL, shell, C, SQL) describe progressively narrower technology layers.

Three implications stand out for modernization. First, the dual-mode storage strategy means business logic is already decoupled from physical storage at the source-code level via the MT (MySQL Table) modules and ACAS file handlers (acas000-acas015) — this dramatically reduces the structural risk of swapping the persistence layer to PostgreSQL. Second, the COMP-3 packed-decimal precision (8 digits integer + 2 decimal) is a hard contract: any modernization must use a decimal type (Python Decimal, PostgreSQL NUMERIC(10,2)) and never IEEE-754 floats. Third, the terminal UI's 80×24 footprint sets an upper bound on field density per screen; modernized layouts can comfortably exceed it without behavioral risk because no business rule is keyed to screen position.

3.6 Integration Patterns

Concho identified 136 integration points across 189 files, dominated by file integrations (47, 35%) and internal RPC-style COBOL CALL operations (43, 32%). Critically, 63 of the integrations are bidirectional, indicating tight synchronous coupling characteristic of monolithic financial applications. The diagram below is the Concho-vended data-flow artifact (artifact ID data_flow_diagram, confidence 0.90) and shows how data enters the system through CLI and terminal interfaces, is routed by the Database Access Layer based on the FA-RDBMS-Flat-Statuses flag (value '66' means MySQL mode, otherwise ISAM), and exits via CUPS print spooling, PDF generation, and email delivery.

graph LR
    subgraph Entry["Data Entry Points"]
        CLI["CLI Interfaces
49% of entry points"]
        MAIN["Main Programs
39% of entry points"]
        SCHED["Scheduled Processes
3% of entry points"]
        TERM["Terminal Interface
st010, sl810"]
    end

    subgraph Processing["Application Processing Layer"]
        SALES["Sales Management
12.3% - domain core"]
        PURCH["Purchase Management
7.5% - domain core"]
        GL["General Ledger
5.0% - domain core"]
        STOCK["Stock Control
3.4% - domain core"]
        IRS["IRS Tax Processing
5.1% - domain core"]
        PAY["Payment Processing
3.3% - domain core"]
    end

    subgraph Storage["Dual Storage Architecture"]
        DAL["Database Access Layer
22.3% - data access"]
        FH["ISAM File Handlers
7.6% - data access"]
        MT["MySQL MT Modules
analMT, salesMT, etc."]
    end

    subgraph Persistence["Data Persistence"]
        ISAM[("ISAM Files
Traditional Storage")]
        MYSQL[("MySQL Database
39 Tables")]
        AUDIT[("Audit Logs
fhlogger")]
    end

    subgraph Integration["External Integration"]
        PDF["PDF Generation
enscript + ps2pdf14"]
        EMAIL["Email Delivery
mailx/mutt"]
        PRINT["CUPS Print Spooling"]
        BACKUP["Backup Archives
tar.gz timestamped"]
    end

    CLI -->|user input| SALES
    MAIN -->|batch data| PURCH
    TERM -->|terminal forms| STOCK
    SCHED -->|recurring transactions| PAY

    SALES -->|invoice data| DAL
    PURCH -->|supplier transactions| DAL
    GL -->|journal entries| DAL
    STOCK -->|inventory movements| DAL
    IRS -->|tax reporting data| DAL
    PAY -->|payment records| DAL

    DAL -->|FA-RDBMS-Flat-Statuses='66'| MT
    DAL -->|FS-Cobol-Files-Used=0| FH

    FH -->|ISAM operations| ISAM
    MT -->|SQL operations| MYSQL

    DAL -->|audit trail| AUDIT

    SALES -->|invoice reports| PDF
    PDF -->|attachments| EMAIL
    DAL -->|financial reports| PRINT
    ISAM -->|.seq backup| BACKUP
    MYSQL -->|database dump| BACKUP
    

Source: Concho Context Graph — data_flow_diagram artifact (confidence 0.90). Percentages reflect Concho's architectural-element weighting of the codebase.

Five integration patterns dominate and shape the modernization strategy:

• Dual-storage routing — every file operation passes through acas000-acas015 handlers that inspect FA-RDBMS-Flat-Statuses and dispatch to ISAM or MySQL. This is the SAROC coexistence bridge's natural seam.
• COBOL-to-MySQL host-variable mapping — MT modules (analMT.cbl, salesMT.cbl, etc.) translate COBOL record structures with COMP-3 fields into MySQL parameter binds via the C-level MySQL Bridge (922 lines, Integration Layer).
• Error-code translation — SQL state codes (23000 duplicate key, 0200n not found) are mapped to COBOL file-status codes (22, 10, 23) and ACAS-specific 99xxx codes for validation errors. Modernization preserves this contract via mapped error responses.
• External-process integration — CUPS (lpr), enscript/ps2pdf14 for PDF generation, and mailx/mutt for email delivery are invoked via shell-out from COBOL. Each becomes a microservice boundary in the target.
• Centralized audit logging — fhlogger.cbl writes a fixed 512-byte log record for every file/database operation. This is a single point of failure in the legacy system; modernization splits it into per-service structured logging plus a system-wide audit stream.

4. Target Architecture

This section defines the target Docker Compose / AWS ECS Fargate architecture for the modernized Payment Processing subsystem (~30 strong-association COBOL programs, ~14,800 LOC across purchase, sales, and shared payment modules). It covers the target architecture overview, target technology stack, code-level architecture decisions, target data model, and target service decomposition. A multi-agent service architecture analysis determined the optimal decomposition: 3 microservices (payment-api, payment-batch, payment-reporting) for this modernization. Migration sequencing, the SAROC coexistence bridge, and rollback approach are covered separately in Section 11.

The 3-service architecture was selected through consensus of Domain-Driven Design, Technical Architecture, and Business Capability analyses, with the Technical perspective winning a weighted score of 7.80 / 10 (passing the 7.0 quality gate). The decomposition aligns with the report-plan.json declared serviceCount = 3 and preserves the inline-GL-posting decision recorded below. Full multi-perspective analysis is summarized in Section 4.5 and detailed in Appendix B.

4.1 Target Architecture Overview

The modernized Payment Processing subsystem replaces the existing COBOL programs (the purchase-side pl080–pl100 and pl900–pl960 chain, the mirrored sales-side sl080–sl100 chain, and the shared common/paymentsMT data access layer) with a containerized Python application deployed on AWS ECS Fargate. The architecture preserves the single bounded context identified by Concho — PaymentProcessing (confidence 0.90) — while decomposing monolithic COBOL programs into well-defined API endpoints organized around the existing workflow stages: data entry, validation, appropriation, proof generation, cash posting, remittance advice generation, and amendment.

The target design exploits the natural modernization seam already present in the legacy system: the acas032 dual-mode file handler, which abstracts ISAM and MySQL access behind a unified interface and inspects the FA-RDBMS-Flat-Statuses switch to dispatch between backends. A file-watcher CDC adapter observes the three watched artifacts (pay.dat, openitm5.dat, purchled.dat) declared in report-plan.json, translates COBOL binary record changes into JSON domain events conforming to the sage-domain-event-v1 envelope, and publishes them to a durable RabbitMQ topic exchange. The modern Python/FastAPI consumer applies the events to PostgreSQL with natural-key idempotency — enabling zero-disruption modernization via the SAROC pattern described in Section 11: Modernization Strategy.

Key Target Architecture Principles

• API-First Design. All payment operations are exposed through versioned RESTful APIs with OpenAPI documentation auto-generated from Pydantic models, replacing the terminal-based menu navigation in pl900 (6-option dispatcher to pl910–pl960) with structured HTTP endpoints.
• Domain-Driven Boundaries. The single aggregate root (Payment, confidence 0.90) and single bounded context (PaymentProcessing, confidence 0.90) inform service boundaries. The 6 business rules (PaymentBatchControlLimits, PaymentAppropriationLogic, PaymentPostingValidation, RemittanceAdviceProcessingRules, UnappliedBalanceAllocation, PaymentReversalProcessing) and 4 integration boundaries are preserved as explicit domain logic rather than embedded in procedural COBOL paragraphs.
• Inline GL Posting. General Ledger journal entries are written in the same database transaction as the payment allocation, replacing the legacy overnight batch posting cycle (pl100) with immediate, balanced GL entries that emit a domain event for downstream subsystems.
• Observability by Default. Every service includes OpenTelemetry distributed tracing, structured JSON logging via structlog with correlation IDs propagated across all calls, and health-check endpoints (readiness, liveness, startup) for ECS task lifecycle management — capabilities entirely absent from the legacy terminal-based system where COBOL DISPLAY was the only diagnostic.
• Infrastructure as Code. All infrastructure — ECS task definitions, RDS instance, RabbitMQ broker, message queue topology, and IAM policies — is declared in AWS CDK (TypeScript) for repeatable deployments. Local development runs an equivalent Docker Compose topology that mirrors the cloud composition.
• Legacy Stays Authoritative. Throughout modernization, the legacy COBOL system is never modified and remains the system of record. The SAROC bridge is passive: CDC observes ISAM file changes, the translator emits idempotent domain events, and the modern consumer applies them with natural-key idempotency so duplicate events are safely no-ops. Detailed coexistence sequencing, dual-write phasing, and rollback are owned by Section 11.
• Pattern Reuse for Follow-On Subsystems. The two parallel payment flows (purchase ledger supplier outflow and sales ledger customer receipts) implement essentially the same workflow against different ledgers. The dual-storage adapter, GL-integration callback, and external-document generation patterns proven on this subsystem then transfer directly to Supplier Management, Purchase Invoicing, and Sales Invoicing.

4.2 Target Architecture Diagram

graph TB
    subgraph Client["Client Layer"]
        WebUI["Payment Processing UI
(SPA)"]
    end

    subgraph AWS["AWS Cloud"]
        ALB["Application Load Balancer"]

        subgraph ECS["ECS Fargate Cluster"]
            SVC1["Payment API Service
(FastAPI)"]
            SVC2["Payment Batch Service
(FastAPI)"]
            SVC3["Reporting Service
(FastAPI)"]
        end

        subgraph Data["Data Layer"]
            RDS[("PostgreSQL RDS
payment, open_item,
batch_control, gl_posting,
payment_audit")]
        end

        subgraph Observability["Observability"]
            OTEL["OpenTelemetry Collector
(traces, metrics, logs)"]
        end

        subgraph Secrets["Configuration"]
            SM["AWS Secrets Manager
+ SSM Parameter Store"]
        end
    end

    subgraph Bridge["SAROC Coexistence Bridge (Section 11)"]
        CDC["File-Watcher CDC
(pay.dat / openitm5.dat /
purchled.dat)"]
        TR["Event Translator
(sage-domain-event-v1)"]
        MQ["RabbitMQ
(topic exchange,
persistent, DLQ)"]
        CON["Background Consumer
(natural-key idempotency)"]
    end

    subgraph Legacy["Legacy ACAS (unchanged)"]
        COBOL["COBOL Payment Programs
(pl080-pl100, pl900-pl960,
sl080-sl100, paymentsMT)"]
        LegacyDB[("ISAM / MySQL
via acas032 dual-mode")]
    end

    WebUI --> ALB
    ALB --> SVC1
    ALB --> SVC2
    ALB --> SVC3

    SVC1 --> RDS
    SVC2 --> RDS
    SVC3 --> RDS

    SVC1 -.->|"read config/secrets"| SM
    SVC2 -.->|"read config/secrets"| SM
    SVC3 -.->|"read config/secrets"| SM

    COBOL --> LegacyDB
    LegacyDB -.->|"file-watcher CDC"| CDC
    CDC --> TR
    TR -.->|"JSON domain events"| MQ
    MQ -.->|"persistent subscribe"| CON
    CON --> RDS

    SVC1 --> OTEL
    SVC2 --> OTEL
    SVC3 --> OTEL
    CON --> OTEL

    style Client fill:#f5efe4,stroke:#1a2b3c,color:#1a2b3c
    style AWS fill:#ffffff,stroke:#1a2b3c,color:#1a2b3c
    style ECS fill:#c4dad2,stroke:#1a2b3c,color:#1a2b3c
    style Data fill:#1b7a78,stroke:#1a2b3c,color:#1a2b3c
    style Observability fill:#e8a598,stroke:#1a2b3c,color:#1a2b3c
    style Secrets fill:#f0f9ff,stroke:#1a2b3c,color:#1a2b3c
    style Legacy fill:#f5efe4,stroke:#999,color:#666,stroke-dasharray: 5 5
    style Bridge fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 5 5
        

4.3 Target Technology Stack

The technology stack was selected to maximize developer productivity and operational reliability while minimizing modernization risk. Python and FastAPI were chosen because Pydantic's strict typing maps cleanly to COBOL's strict data typing — every PIC X(N) and PIC S9(N)V9(M) field has a corresponding Pydantic field with equivalent validation constraints, and COMP-3 packed-decimal values translate to Python Decimal with explicit precision and scale.

PostgreSQL replaces the dual-mode ISAM/MySQL storage currently abstracted by acas032. The legacy copybooks (fdpay.cob, wspay.cob, plwspay.cob, selpay.cob) and the paymentsMT/paymentsLD/paymentsRES/paymentsUNL data access layer consolidate into SQLAlchemy models with Alembic-managed migrations. This eliminates the dual-storage complexity while preserving the data-access abstraction that already exists as a natural architectural seam.

General Ledger posting is performed inline — the appropriation endpoint creates GL journal entries in the same database transaction as the payment allocation, replacing the legacy overnight batch posting cycle in pl100. RabbitMQ provides the SAROC bridge substrate (Section 11), enabling zero-disruption modernization with ordered, idempotent event replay.

4.3.1 Target Code-Level Architecture Decisions

The following table documents the code-level conventions that all Payment Processing services must follow. These decisions are derived from the resolved targetPatterns for the Docker / ECS Fargate platform (skill defaults merged with the architecture template's platform-conditional overrides; no plan-level overrides in run-012) and govern all code examples in subsequent sections and downstream code-generation artifacts.

4.4 Target Data Model

The target data model consolidates the legacy dual-mode storage (ISAM files plus MySQL tables) into a single PostgreSQL schema. The model preserves the Payment aggregate root (confidence 0.90) and its relationships to open items, batch control records, and ledger accounts as identified by Concho's entity analysis. The 25 entities that Concho surfaces for the Payment Processing subsystem at cycle 8 are normalized into 5 core PostgreSQL tables that capture the full payment lifecycle for both purchase ledger (supplier outflow) and sales ledger (customer receipts) flows.

erDiagram
    PAYMENT {
        uuid id PK
        varchar payment_reference
        int transaction_type
        date payment_date
        varchar supplier_code FK
        varchar customer_code FK
        decimal gross_amount
        decimal discount_amount
        decimal net_amount
        int batch_number FK
        int payment_flag
        varchar payment_method
        varchar cheque_number
        varchar bank_reference
        varchar legacy_natural_key
        timestamp created_at
        timestamp updated_at
    }

    OPEN_ITEM {
        uuid id PK
        uuid payment_id FK
        varchar invoice_reference
        int folio_number
        date invoice_date
        decimal invoice_amount
        decimal applied_amount
        decimal discount_taken
        decimal deduction_amount
        int age_days
        varchar age_bucket
        varchar transaction_type
        timestamp created_at
    }

    BATCH_CONTROL {
        int batch_number PK
        date batch_date
        int item_count
        decimal batch_total
        varchar batch_status
        varchar created_by
        timestamp created_at
        timestamp closed_at
    }

    GL_POSTING {
        uuid id PK
        uuid payment_id FK
        int batch_number FK
        varchar debit_account
        varchar credit_account
        decimal amount
        varchar posting_reference
        boolean posted
        timestamp posted_at
    }

    PAYMENT_AUDIT {
        uuid id PK
        uuid payment_id FK
        varchar action
        jsonb old_values
        jsonb new_values
        varchar performed_by
        timestamp performed_at
    }

    PAYMENT ||--o{ OPEN_ITEM : "appropriates"
    PAYMENT }o--|| BATCH_CONTROL : "belongs to"
    PAYMENT ||--o{ GL_POSTING : "generates"
    PAYMENT ||--o{ PAYMENT_AUDIT : "tracks"
    BATCH_CONTROL ||--o{ GL_POSTING : "groups"
        

For detailed schema mappings from legacy data structures to this target data model, see Section 10: Data Mapping Strategy.

4.5 Target Service Architecture

Decision Process

Service Decomposition

1. payment-api — Interactive payment lifecycle: entry (pl080/sl080), amendment (pl085/sl085), batch open / lookup, and the synchronous read surface that replaces the pl900 terminal menu. Sub-second p95 latency budget; autoscales on ALB request count (2–6 tasks).
2. payment-batch — Proof sort (pl090), proof report (pl095), cash posting with inline GL writes (pl100), cheque batch (pl940), and payment register (pl950). Also hosts the SAROC consumer (background-thread RabbitMQ subscriber with natural-key idempotency) because the same async-runtime shape serves both legacy-event consumption and batch job execution. Autoscales on queue depth (1–4 tasks).
3. payment-reporting — Aged-creditor / aged-debtor analysis (pl910/pl930) and remittance advice generation (pl960) with S3-backed PDF output. Reads route to a PostgreSQL read replica; only remittance-tracking writes hit the primary. Replaces the legacy lpr print integration with S3 + optional email/portal delivery.

Integration Pattern

All three services share a single PostgreSQL schema (5 tables — payment, open_item, batch_control, gl_posting, payment_audit) and a shared payment-models Pydantic package. Write paths are gated by service-specific repository methods so the shared schema does not become a shared-database anti-pattern. Asynchronous communication uses the SAROC RabbitMQ topic exchange (envelope sage-domain-event-v1): payment-api emits payment.created/payment.amended/payment.reversed; payment-batch emits payment.posted/gl.journal-entry-created/cheque-batch.generated; payment-reporting consumes cheque-batch.generated to trigger remittance generation and emits remittance.generated/remittance.delivered. Inline GL posting is preserved: GL journal entries are written by payment-batch in the same database transaction as the payment-appropriation update.

For complete three-perspective analysis, scoring matrix, per-service API specifications, AWS topology diagrams, and the strangler-fig sequencing roadmap, see Appendix B: Target Service Architecture Analysis.

5. Platform Affinity Analysis

Platform affinity analysis classifies each legacy constraint as either platform-driven (ELIMINATE — the limit exists because of hardware/software limitations of the source platform, not because of a business rule), business-driven (PRESERVE — the limit exists because of a genuine business requirement that must survive modernization), or hybrid (the constraint contains both a platform-imposed ceiling that should be eliminated and a business intent that should be preserved in a more flexible form). Getting this distinction wrong replicates legacy limitations into the modern system, or breaks business rules that were disguised as platform constraints.

The catalog backing Section 5 is the 149–197 implementation_constraint entities Concho cycle 8 discovered across the full ACAS codebase. From that catalog, three independent platform-affinity agent runs each filtered for Payment-Processing relevance, scored each candidate for platform-vs-business driver, and emitted ELIMINATE / HYBRID / PRESERVE verdicts. The reconciler then took inclusion by majority (a constraint is in if 2 of 3 runs included it), classification by majority (the dominant verdict wins; ties resolve to the more conservative side), and category by majority (5.1/5.2/5.3/5.4). The 12 constraints below reflect that consensus.

5.1 Capacity Constraints

Capacity constraints impose a numeric ceiling on a count, length, or buffer size — how many items, how many bytes, how many characters. All four 5.1 entries below are platform artifacts of fixed-width COBOL records, OCCURS-clause array sizes, or fixed-length string buffers. PostgreSQL row-sets and SQLAlchemy streaming retire them outright; the modern stack has no per-cycle row caps, no per-statement buffer ceilings, and no fixed-width record allocation.

5.1.1 Batch Size Limitation (99-item per-batch ceiling)

5.1.2 Remittance Advice Format Limitations (9-invoice cap, 5×32 address block, 645-byte cheque record)

5.1.3 Purchase Invoice Line Item Limit (40-line ceiling)

5.1.4 MySQL Command Buffer Limitation (4096-char SQL statement budget)

5.2 Processing Model Constraints

Processing-model constraints shape how code executes — the dispatch pattern, the file-organization requirement, the procedural-skip logic in a read loop. The two entries below are platform artifacts of COBOL's lack of polymorphism, the dual-storage abstraction, and procedural-filter idioms.

5.2.1 Dual Storage Architectural Pattern (acas032 flag-driven dispatch)

5.2.2 Payment Transaction Type Filter (admit types 5 & 6; exclude 1 & 3)

Platform vs Business Driver Analysis

5.3 User Interface Constraints

UI constraints below cover the platform-level display surface — terminal grid, fixed screen coordinates, credential-form field widths. Per-screen layout transformation (multi-screen-to-single-page consolidation, function-key replacement, accessibility) is owned by Section 7.

5.3.1 Terminal Dimension Requirements (80×24 startup gate)

5.3.2 Terminal Display Positioning (fixed error-message coordinates)

5.3.3 Credential Length Constraints (4-char password ceiling)

5.4 Data Type Constraints

Data-type constraints define the shape of a field or record — precision, byte width, format string. The three entries below are platform artifacts of COBOL's PIC declarations and COMP-3 packed-decimal encoding. Modern strongly-typed Python plus rich PostgreSQL types retire them.

5.4.1 Financial Data Precision Requirement (COMP-3 s9(8)v99)

5.4.2 Date Format Standardization (binary-long yyyymmdd, century=20 hard-code)

5.4.3 Payment Record Structural Integrity (237-byte fixed Payment record, 113-byte sort record)

6. Technical Debt Analysis

6.1 What This Section Looks Like for Other Modernizations

When the modernization target is a more recent stack — ASP.NET 4.7 on Windows Server 2012 R2, a Java 8 monolith on JBoss, a Rails 4 app on Ruby 2.4 — the analysis surfaces concrete artifacts:

• A row-per-dependency table of every .csproj / pom.xml / Gemfile entry, the version pinned today, the upstream EOL date, the CVE backlog, and the modern replacement the target architecture imports.
• Architecture anti-patterns the legacy code has accreted — God classes, distributed monoliths, shared mutable session state, RPC-over-HTTP — with a refactoring path per pattern.
• Dependency-graph hotspots: which libraries fan in to the most code, and which of those have no maintained successor (the "you must rewrite this" set).
• Operating-system / runtime end-of-life timelines that constrain how long the lift-and-shift option remains viable before vendor support expires.

Those reports run 10–30 pages and feed directly into the dependency-replacement steps of the artifact-generation workflow. They matter when the modernization is mostly a refresh — same language, same paradigm, modern infrastructure.

6.2 Why ACAS Is Different

ACAS is a fully-legacy COBOL system: dual ISAM/MySQL storage, terminal UI, packed-decimal data types, and a runtime (GnuCOBOL on Linux) that exists almost exclusively to keep applications like this one running. There is no library-by-library upgrade path because there are no libraries in the modern sense — the data structures are copybooks, the persistence layer is hand-rolled file I/O, and the UI is ACCEPT/DISPLAY statements writing directly to an 80×24 screen. The "tech debt" is the whole stack.

So instead of a dependency catalog, the case for the modernization compresses into a short list of motivations that anyone considering a project like this already knows:

1. Vendor / runtime lock-in. Mainframe operators charge mainframe prices; even off-mainframe COBOL runtimes carry licensing and support overhead disproportionate to the code's business value. The platform vendor's roadmap is not your roadmap.
2. Workforce attrition. The engineers who built and maintained ACAS-class systems through the 1980s and 1990s are retired, retiring, or no longer alive. The talent pipeline for COBOL maintenance is functionally closed; new hires arrive with Python, TypeScript, and Go on their résumés, not PIC 9(8) COMP-3.
3. Integration friction. Modern business systems — CRM, BI, analytics, accounts-payable automation, regulatory reporting — speak REST, GraphQL, event streams, and OAuth. Every integration with the legacy stack is a custom adapter; every adapter is a fragile dependency. The cost is paid every quarter forever.
4. User experience ceiling. An 80×24 terminal restricts what the business process itself can become. Cross-screen workflows, real-time validation, mobile access, and audit trails that span multiple actors are all available the moment the UI moves to the web; none are reachable while users are pressing function keys against a fixed grid.
5. Platform stagnation. The legacy runtime receives security patches and not much else. Every new capability — observability, autoscaling, managed databases, AI/ML services, modern CI/CD — is something the modern stack ships with and the legacy stack will never have.

If you are reading this report you already know the above, which is why the list is short. The substantive analysis — what specifically gets built to replace the legacy stack — lives in Section 4: Target Architecture, Section 5: Platform Affinity Analysis, and the technical chapters that follow.

7. UI/UX Transformation Examples

7.1 UI Affinity Analysis

Before walking through individual screen transformations, the table below maps every salient legacy UI element to a modernization disposition. Every legacy element traces to actual COBOL source code discovered by Concho; the dispositions follow the platform-affinity reconciliation in Section 5.

7.2 Payment Processing Menu (pl900) → SPA Sidebar Routing

The Payments Menu (pl900) is the legacy entry point: 6 numbered options plus an X-to-exit. In the modern system the menu disappears entirely — the operator lands on the Payment Cycle Workbench (7.7) and side-bar items expose direct access to the constituent screens. The legacy mockup below uses DISPLAY literals verified against purchase/pl900.cbl:130-195.

PL900 (3.02.05)               Payment Menu              21/05/2026


Select one of the following by number :- [ ]


(1)  Generate Payments to be made

(2)  Amend Payments

(3)  Proof Payments

(4)  Generate Payments

(5)  Print Payment Register

(6)  Print remittance advices


(X)  Return to system menu

7.3 Payment Data Entry (pl080) → Live Appropriation Preview

The Payment Data Entry program (pl080) is the heart of the payment cycle. The operator keys in a payment date, supplier account, and value, and the program then walks the supplier's outstanding invoices one by one, prompting the operator to accept or modify each appropriation. The modern interface collapses that imperative loop into one form with a live appropriation preview — the operator sees the full result before clicking Save.

PL080 (3.02.05)            Payment Data Entry            21/05/2026

ACME ELECTRICAL SUPPLIES LTD
12 INDUSTRIAL ESTATE
CRANBORNE ROAD
POTTERS BAR
HERTS EN6 3JN
   ****************************************
   *Date  [21/05/2026]*A/C Nos   [SUP0001]*
   ***                                  ***
   *Value [  1250.00 ]*Batch   [00042/017]*
   ****************************************

Current Balance - 8,742.55     Unapplied Balance - 25.00
Do you wish to allocate the unapplied Balance to this account?  [Y]


   Inv# 00042001  21/04/2026  Net 1000.00  Disc 25.00  Apply 975.00  ....Fully Paid
   Inv# 00042002  18/04/2026  Net  250.00  Disc  0.00  Apply 250.00  ....Fully Paid

Batch Total - 1,250.00

7.4 Batch Dashboard / Proof Sort (pl090) → Sortable Batch Table

The proof sort program (pl090) reads open-item records, filters them by transaction type (BR-PAY-003 — only type 2 invoices and type 4 debits qualify), and emits a printed listing that the controller signs off. The modern interface materializes the sort output as an interactive table with status pills for the batch lifecycle (BR-PAY-006).

              PAYMENT PROOF SORT - BATCH 00042             21/05/2026

SUPPLIER  NAME                          BATCH/ITEM   APPROP   DEDUCT   PAID    TYPE
========  ============================  ==========   ======   ======   ======  =====
SUP0001   ACME ELECTRICAL SUPPLIES LTD  00042/001    1000.00   25.00   975.00  Pay
SUP0001   ACME ELECTRICAL SUPPLIES LTD  00042/002     250.00    0.00   250.00  Pay
SUP0002   BAKER BUILDING SUPPLIES LTD   00042/003     500.00    0.00   500.00  Pay
SUP0003   COMET COURIERS LIMITED        00042/004     750.00   15.00   735.00  Pay
SUP0004   DELTA DEALS WHOLESALE         00042/005    1200.00   30.00  1170.00  Pay
SUP0005   ECHO ENTERPRISES LLP          00042/006     400.00    0.00   400.00  Pay

Payment Totals                                       4100.00   70.00  4030.00
Journal Totals                                          0.00    0.00     0.00

7.5 Purchase Cash Posting (pl100) → Inline GL Preview & Commit

Cash posting (pl100) reads the proofed batch and applies each payment to the supplier's purch-current balance, writing inline GL journal entries via the BL-Write call. The legacy operator confirms with a 3-character YES/NO at pl100.cbl:312; the modern interface shows the GL debit/credit pair before commit.

PL100 (3.02.05)        Purchase Cash Posting        21/05/2026










  OK to post payment transactions (YES/NO) ? <   > enter {CR}

7.6 Cheque / BACS Run (pl940) & Remittance Inbox (pl960) → Per-Payment PDF

After posting, pl940 inspects each payment's pay-sortcode field: zero means a cheque (the cheque-number counter increments), non-zero means a BACS payment (the c-cheque field is filled with the literal BACS). pl960 then reads the resulting cheque-file and emits one remittance per record — with the 9-line OCCURS limit on the invoice list (pl960.cbl:208-216) hard-coded by the COBOL record format. The modern flow splits cheque output from BACS (two pipelines, one per method), removes the 9-line ceiling, and materializes each remittance as an S3-backed PDF.

+--------------------------------------------------+
| REMITTANCE ADVICE                                |
+--------------------------------------------------+

To  ACME ELECTRICAL SUPPLIES LTD     From  ACAS LTD
    12 INDUSTRIAL ESTATE                   12 HIGH STREET
    CRANBORNE ROAD                         POTTERS BAR
    POTTERS BAR
    HERTS EN6 3JN

  A/C: SUP0001                  Date: 21/05/2026

  ----------------------------------------------
  Invoice      Folio       Amount
  ----------------------------------------------
  INV-00042001 F-000001       975.00
  INV-00042002 F-000002       250.00
  ----------------------------------------------

  Cheque   00012345              Total: $1,225.00

  + + + + + + + + + + + + + + + + + + + + + + +

To  BAKER BUILDING SUPPLIES LTD   From  ACAS LTD
    ...

7.7 Payment Cycle Workbench — "Beyond 1:1" Consolidated View

The legacy system spreads the payment lifecycle across five programs (pl080 entry, pl090 proof, pl100 post, pl940 cheque, pl960 remit) and four physical files (pay.dat, openitm5.dat, fdbatch records, GL batch records). The operator must remember the program names, the navigation sequence, and which file is authoritative at each step. The Payment Cycle Workbench collapses all five programs into one SPA page; every cell is one SQL JOIN away from payment, open_item, batch_control, gl_posting, and remittance_advice. This is the "Beyond 1:1" consolidation called out in the use-case storyboard — impossible on the 80×24 terminal, easy on the modern stack.

Every cell on this workbench is a JOIN that was structurally impossible on the legacy terminal: each row lived in a different physical file managed by a different COBOL program. With the shared 5-table PostgreSQL schema and the FastAPI service surface, the Workbench is a single React route backed by a small set of read-side endpoints from payment-api and payment-reporting. This is the canonical demo screen: open the Workbench, click "Advance cycle" five times, and watch a payment travel from ENTERED to REMITTED with no program switches.

Scene 1: Three Screens Become One

The unified payment screen replaces three separate legacy programs — the entry → proof → post trio that the operator walked across three terminal sessions. The comparison below shows the three green-screen terminals that the modern single page replaces. These match the legacy mockups embedded in the generated SPA (Workbench Scene 1).

PL080 (3.02.05)        Payment Data Entry
ACME MANUFACTURING LTD
 ****************************************
 *Date [21/05/2026] *A/C Nos [ACME006 ] *
 *Value [4,250.00 ] *Batch  [00042/017] *
 ****************************************
 Select option : [_]
  (1) Show outstanding invoices
  (2) Enter payment
  (3) Apply discount
  (4) Save and exit

 Enter further payments? (Y/N)  [Y]

PL090 (3.02.05)        Proof Sort
 Batch 00042  Items: 17 of 99
 -- Released to sort stream --
 ACME006  INV2026001  525.00 (2)
 ACME006  INV2026002  800.00 (2)
 ACME006  INV2026003  305.00 (2)
 ACME006  INV2026004  620.00 (2)
 ACME006  INV2026005  410.00 (2)
 ...

 Sign-off: [___] PROOF PRINTED

PL100 (3.02.05)        Cash Posting
 Batch 00042  Posted

 GL pair (BL-Write inline):
   Dr 410000 Creditors  4,250.00
   Cr 200100 Bank       4,225.00
   Cr 4090   Discount      25.00

 OK to post (YES/NO)? [YES]

Three separate programs. Three separate terminal sessions. A numbered menu (pl900) to navigate between them. In the legacy system, an operator entering a payment must invoke pl080 to capture the line items, exit to the menu, invoke pl090 to run proof, exit again, and invoke pl100 to post and write GL — with hand-offs between sessions and no shared view. The modern unified screen presents the entire entry → proof → post chain on a single page; the operator never leaves the view, and the GL pair lands inline as part of the post result.

Scene 2: Supplier Autocomplete

The operator types "ACM" in the supplier search field. An autocomplete dropdown appears showing matching suppliers with their account codes, outstanding balances, and open invoice counts — financial context that was invisible in the legacy system until after the supplier was selected. In the legacy PL080, the operator typed the exact 7-character account code (accept pay-customer at 0572) at a blank prompt with no search capability and no financial preview.

The autocomplete reveals the second platform affinity win: the same business need (find and select a supplier) with a completely modernized interaction model. Fuzzy search, financial preview, and immediate visual feedback replace the legacy's exact-code-or-nothing approach.

Scene 3: Allocation Preview — Pending State

After selecting ACME Corporation and entering a payment amount, the allocation preview table populates automatically. This is the pending state — nothing has been committed. The table shows how the payment will be applied to outstanding invoices, with BR-PAY-002 (Payment Appropriation Logic) calculating discount eligibility in real time. Invoices are sorted oldest-first, with estimated discount amounts prefixed by a tilde (~) to signal they are projections, not final values.

The allocation preview shows BR-PAY-002 in action: invoices are allocated oldest-first, with discount eligibility calculated per the legacy algorithm (add 1 to oi-deduct-days, compare against payment date). Invoice 48503 has an early payment discount — it falls within the deduction terms window relative to the payment date. The first three invoices are too old for discount eligibility. The operator has exercised BR-PAY-008 (Selective Invoice Exclusion) by unchecking invoices 48621 and 48744 — these are greyed out with an "Excluded" badge and carry no allocation. The remaining four checked invoices are fully funded at $11,625.50, with an estimated discount of ~$46.80 on invoice 48503. In the legacy system, the only way to skip an invoice was to enter zero during line-by-line terminal interaction in the accept-money2 loop — there was no pre-selection mechanism.

Scene 4: Post Payment — Confirmed State

The operator clicks "Post Payment." The Payment API Service validates the batch (BR-PAY-001), the Payment Batch Service executes cash posting with GL integration, and the allocation table transitions from amber (pending) to green (confirmed). The same table structure is preserved — only colors, labels, and values change, making the state transition unmistakable.

The state transition is visible in every element: amber rows become green, "Will Pay" becomes "Paid," tilde-prefixed discount estimates become final amounts, column headers change from "Pending Allocation" to "Allocated" and from "Est. Discount" to "Discount," the amber summary bar becomes green, and the "Post Payment" button disappears because the action is complete. The two excluded invoices (48621 and 48744) do not appear in the confirmed state — they were filtered out before posting. The "View GL Postings" link on the success banner leads directly to Scene 5.

Scene 5: View GL Postings — Double-Entry Accounting

Clicking "View GL Postings" on the success banner navigates directly to the GL journal entries for this payment. No manual lookup, no switching programs, no re-entering the batch number. Three balanced journal entries are displayed with account names and descriptions alongside the codes — information that required memorization or a separate lookup in the legacy GL051 screen.

What took six separate program invocations, a numbered menu, and overnight batch latency for GL updates now happens on a single page with real-time feedback and full business rule transparency. The entire flow — from supplier search through allocation preview through posting through GL verification — completes in approximately 2 seconds of processing time, compared to the legacy's 12-hour gap between payment entry and GL visibility.

Scene 6: Reverse a Posted Payment — BR-PAY-009

Mistakes happen — a payment posted to the wrong supplier, a duplicated batch. In the legacy system, correcting a posted payment meant a separate program (pl085, Payment Amendment) and a hand-keyed compensating journal. The workbench surfaces it inline: a Reverse action available on any posted payment.

Clicking Reverse flips the payment POSTED → REVERSED and writes a compensating double-entry — the original debit/credit pair mirrored — in the same transaction, so the ledger nets to zero and stays balanced. This is BR-PAY-009 (Payment Reversal Processing), which Concho extracted from the legacy reversal/amendment logic in purchase/pl085.cbl. The affinity win: what was a separate green-screen program plus a hand-keyed correcting journal is now one auditable action — the reversing entries written automatically, and the original payment preserved (struck-through, never deleted) for the audit trail.

# UI Storyboard: Payment Cycle — Draft (Inferred from Concho Context Graph Analysis)

**Source:** Concho Context Graph entities: `PaymentProcessingAndAllocation` (12 steps, conf 0.82), `PaymentProofProcessing` (7 steps, 0.77), `PaymentProcessingWorkflow` (7 steps, 0.64), `RemittanceAdviceGeneration` (8 steps, 0.70)
**Programs Combined:** `pl080` (Payment Data Entry), `pl085` (Payment Amendment), `pl090` (Payment Proof Sort), `pl100` (Cash Posting + GL), `pl940` (Cheque/BACS Generation), `pl960` (Remittance Advice)
**Spine:** `use-case-storyboard-012.md` — Use Case 1, "The Payment Cycle: Entry to Posted GL & Remittance"
**Status:** DRAFT — inferred from `use-case-storyboard-012.md` and Concho MCP source extracts; review and refine before next-pass generation.

**Inferred state machine (composite of four workflows):**
```
ENTRY -> VALIDATION -> APPROPRIATION -> BATCH_CONTROL ->
PROOF_GENERATION -> POSTING -> CHEQUE_GENERATION ->
REMITTANCE_GENERATION -> AUDIT_COMPLETE
```

**Storyboard rule applied:** every state transition has an explicit triggering user action, rendered as a real form element in the corresponding scene mockup.

---

## Scene 1: Three Screens Become One

**User:** Sarah, an AP clerk (the payment operator)
**User action:** Sarah opens the Payment Cycle Workbench from the sidebar nav (default route `/payments/cycle`)
**Visible state:** the unified workbench renders in its empty initial state. The left-hand sidebar shows the legacy menu items (`Generate Payments to be made`, `Amend Payments`, `Proof Payments`, `Generate Payments` — pl940 cheque run, `Print Payment Register`, `Print remittance advices`) as deep-linked routes inside one application. A banner at the top of the page explains that five legacy programs (`pl080`, `pl090`, `pl100`, `pl940`, `pl960`) have been collapsed into one route, with the same business outcome.
**Business rule fired:** none yet (no data entered).
**Platform affinity win:** the `pl900` numbered-menu dispatch (`accept menu-reply at 0543` — one-character keypress drives `call pl910..pl960`) is replaced by URL routing. The operator's context (selected supplier, batch in progress, audit trail) survives between sections; the legacy `call ... goback` cycle reset the screen on every menu transition.

---

## Scene 2: Supplier Autocomplete

**User:** Sarah (same session)
**User action:** Sarah clicks the "New Payment" button on the workbench and starts typing `ACM` in the supplier search field
**Visible state:** an autocomplete dropdown appears below the supplier field. Each row shows the supplier code (7-character, e.g. `ACME001`), the supplier name, the current outstanding balance, the count of open invoices, and a MOD-11 verification badge (green check — computed inline on every keystroke after 3 characters, with 200ms debounce). The legacy `pl080` "type the exact 7-character code at row 5, col 72" prompt has become a financial-context search.
**Business rule fired:** `BR-PAY-002` Supplier Account Number Format (MOD-11) — the check-digit algorithm from `common/maps09.cbl:90-145` runs inline on each keystroke; supplier codes that fail check-digit are dimmed in the dropdown.
**Platform affinity win:** the legacy `accept pay-customer at 0572` with `PIC X(7)` required the operator to know the exact code. The autocomplete with balance + open-invoice preview surfaces financial context that the 80x24 terminal could not show at the input stage.

---

## Scene 3: Allocation Preview — Pending State

**User:** Sarah (same session); `ACME ELECTRICAL LIMITED` (`ACME001`) selected, current balance $4,521.00, 6 open invoices
**User action:** Sarah enters the payment date `21/05/2026`, tabs to the Amount field, types `4,250.00`, and tabs out
**Visible state:** the outstanding-invoices table loads below the form (oldest-first per the `pl080` pay-loop's `OTM5-Read-Next` order). All 6 invoice rows render with **amber row backgrounds** and **amber status badges** — the table is in *pending / preview* state, not yet committed. For each row the table shows:
- Invoice number (`INV-00042001` .. `INV-00042006`)
- Invoice date and due date
- Outstanding net amount
- Estimated discount (prefixed with `~`, shown for rows where today's date is inside the `oi-deduct-days` window per `BR-PAY-004`; zero for rows outside the window)
- Amount that will be applied (`Will Pay` / `Partial (est.)` / `Skip` status)

The running total at the bottom of the table shows "Pending allocation: $4,250.00" against a "Remaining balance: $0.00". An amber summary bar reads: "5 invoices fully paid, 1 partial, $25 early-payment discount projected. Click Post Payment to commit."
**Business rule fired:** `BR-PAY-004` Early Payment Discount Calculation (per appropriated line; `purchase/pl080.cbl:585-605` — if `u-bin = oi-date + oi-deduct-days > pay-date` then `display-5 = oi-deduct-amt`); `BR-PAY-007` Unapplied Balance Allocation (preview if `purch-unapplied > 0`).
**Platform affinity win:** the legacy `pl080` showed appropriation **after** submit, one line at a time, via `display display-inv at curs` inside the `pay-loop`. The modern view shows the full appropriation **before** commit, in a real-time pending state the operator can adjust.

---

## Scene 4: Post Payment — Confirmed State

**User:** Sarah (same session)
**User action:** Sarah reviews the pending allocation, then clicks the "Post Payment" button at the bottom of the table
**Visible state:** a brief ~2-second processing indicator appears. Every row transitions from **amber to green** in unison. Status badges flip: "Will Pay" -> "Paid", "Partial (est.)" -> "Partial". The tilde-prefixed estimated discount values become final values (no tilde). Column headers update from "Pending Allocation" -> "Allocated", "Est. Discount" -> "Discount Taken". The amber summary bar turns green: "Allocated $4,225.00, discounts taken $25.00, batch 42 item 17 of 99 (BR-PAY-008 soft cap)." A new "View GL Postings" link appears in the summary footer.
**Business rule fired:** `BR-PAY-001` Payment Posting Validation (the global posting-gate check from `pl080.cbl:288-293`, evaluated server-side as `purchase_posting_state = posted`); `BR-PAY-006` Batch Status Lifecycle (the batch transitions from `OPEN` to `OPEN-WITH-PAYMENTS` if first payment, stays `OPEN` otherwise; from `copybooks/fdbatch.cob:20-30`); `BR-PAY-008` Payment Batch Control Limits (99-item soft cap on `fdbatch.cob:23 Items pic 99`; `pl080.cbl:731-735` composite key `oi-invoice = oi-b-nos * 1000 + oi-b-item`).
**Platform affinity win:** the legacy posting path was a 12-hour batch window: `pl080` wrote `OTM5` records, the day ended, `pl090` ran proof-sort overnight, `pl100` posted to supplier balances and the GL the next morning. The modern path is a single ~2-second synchronous commit with the appropriation result visible as a state transition the operator can see.

---

## Scene 5: View GL Postings — Double-Entry Accounting

**User:** Sarah (same session)
**User action:** Sarah clicks the "View GL Postings" link in the green summary footer
**Visible state:** a GL journal panel slides in from the right (the same workbench page; no navigation). It shows the balanced double-entry pair that `pl100.cbl:329, 414` wrote inline in the same DB transaction as the payment row:

| Account | Dr | Cr |
|---|---:|---:|
| 1100 — Bank (cash account) | | $4,225.00 |
| 2000 — Accounts Payable — ACME001 | $4,250.00 | |
| 4090 — Discount Received | | $25.00 |
| **Totals** | **$4,250.00** | **$4,250.00** |

A "Balance" pill reads **ZERO** with a green check. Each row links to the originating payment id (`PAY-2026-00042-017`) for traceability.
**Business rule fired:** `BR-PAY-005` Payment Method Determination (BACS vs Cheque); General Ledger Posting Integration (the inline `BL-Write` from `pl100.cbl:414`, mapped to the modern `gl_posting` table written in the same transaction as `payment.status = POSTED`).
**Platform affinity win:** the legacy GL visibility required exiting `pl100`, returning to the system menu, launching `gl051` (GL Transaction Enquiry) under the General Ledger module, and re-keying the batch number to see the posting. The modern view shows the GL pair without leaving the page, with per-line traceability back to the payment id.

---

## Scene 6: Reverse a Posted Payment (BR-PAY-009)

**User:** the payment operator.
**User action:** on a POSTED payment, the operator clicks **Reverse Payment**.
**Visible state:** the payment row flips `POSTED → REVERSED`; the GL panel gains a *compensating* journal — the original debit/credit pair mirrored (DR Bank / CR Trade Creditors) — and the Balance pill still reads ZERO. The original payment is retained, struck-through, for the audit trail (never deleted).
**Business rule fired:** `BR-PAY-009` Payment Reversal Processing — writes the mirrored journal in the same transaction so the ledger stays balanced. Concho extracted this from the legacy reversal/amendment logic in `purchase/pl085.cbl`.
**Platform affinity win:** legacy ran reversal/amendment as a separate program (`pl085`) plus a hand-keyed correcting journal; the modern workbench makes it one inline, auditable action with the reversing entries written automatically.

---

## Scene 7 (optional): Side-by-Side Coexistence — SAROC Steady State

**User:** Sarah (same session); operations manager peering over shoulder
**User action:** Sarah switches to the "SAROC Bridge" tab in the workbench
**Visible state:** two panels side-by-side. **Left** shows the legacy `pay.dat`/`openitm5.dat` files via the SAROC adapter — the same payment Sarah just posted appears as a record in the legacy file format, with the BACS-tagged record (`pay-sortcode != zero`) confirmed. **Right** shows the modern `payment` and `gl_posting` rows. A small status indicator reads: "SAROC bridge in dual-write mode — legacy and modern stores converged. Queue drain: 0 messages pending."
**Business rule fired:** `BR-PAY-005` (the BACS vs cheque split that the SAROC bridge enforces during coexistence); `BR-PAY-008` (the 99-item soft cap that the SAROC translator depends on for 1-to-1 legacy translation).
**Platform affinity win:** the dual-storage coexistence window lets the legacy users still run `pl080`/`pl100` against `pay.dat` while modern users post via the workbench, with the SAROC bridge keeping both stores in sync. There is no "cutover weekend" — both systems run side-by-side until the legacy ramp-down completes.

---

## Why these scenes (and not others)

- **Scene 1** is the "consolidated view's empty state" canonical opener (per `ui-storyboard-transformation` SKILL Part 2 Step 5, scene-1 template).
- **Scene 2** demonstrates the "exact code at blank prompt -> autocomplete with preview" affinity win (scene-2 template).
- **Scene 3** shows the unified view in *pending* state with amber/yellow color treatment and per-row preview calculations (scene-3 template).
- **Scene 4** is the commit transition — amber-to-green, will-to-did, estimated-to-final (scene-4 template).
- **Scene 5** is the downstream-consequence view that previously required a different program/screen (scene-5 template — "everything visible without leaving the page").
- **Scene 6** is the SAROC coexistence story that the run-012 charter emphasizes (the optional scene-6 template for projects with a coexistence window).

Each scene includes the five required elements per `ui-storyboard-transformation` SKILL Part 2 Step 5: user, user action, visible state, business rule fired, platform-affinity win.

**End of draft storyboard.**

7.8 UI Pattern Library & Accessibility

Accessibility improvements layered across every screen:

• Semantic HTML: form labels are wired to inputs with for=; ARIA aria-required, aria-invalid, aria-describedby on every input.
• Keyboard navigation: Esc still cancels (legacy parity). Ctrl+S saves; Ctrl+Enter submits; Tab order matches visual order.
• Screen-reader announcements: appropriation preview updates use aria-live="polite"; status pills are read as "PROOFED" not "yellow pill".
• Colour contrast: all status pills tested at WCAG AA contrast on the report's brand palette.
• Focus indicators: 2px ring on every focusable element; never relying on browser default.

7.9 Field Inventory Reference

The field inventory table that follows is auto-generated from the storyboard JSON at inputs/ui-storyboards/payment-cycle.storyboard.json. This table enumerates every user-facing field shown across screens 7.2–7.7 — the ground truth that the mockups above, the modern React components in the artifact-generation workflow, and the Playwright drift-detection spec all derive from. Every row traces back to a real COBOL artifact (copybook PIC clause, accept statement, or display literal) via the evidence column.

(The table is rendered into a separate fragment, modernization-technical-examples-section-7-9-012.html, and inserted by the report-assembler at this point.)

8. Code Translation Examples

8.1 Translation Principles

8.2 Example 1 — Supplier MOD-11 Check Digit Validation

The maps09 utility implements the MOD-11 check digit algorithm shared between customer and supplier identifiers. Each of the first six characters is weighted by position via (8 - position), the weighted sum is divided by 11, and the remainder is subtracted from 11 to yield the check digit. The target translates this verbatim into a Pydantic validator that runs on every payment-entry submit.

main.
    move     customer-nos  to  work-array.
    move     zero  to  suma.
    perform  addition-loop through addition-end
             varying a from 1 by 1 until a > 6.

    if       suma = zero
             move  "N"  to  maps09-reply
             go to  main-exit.

    divide   suma  by  11  giving  z.
    compute  a  =  11 - (suma - (11 * z)).

    if       maps09-reply = "C"
             move   a   to  check-digit
             move  "Y"  to  maps09-reply.

    if       maps09-reply = "V"
      and    a = check-digit
             move  "Y"  to  maps09-reply.

    go       to main-exit.

addition-loop.
    set      q  to  1.
    search   ar1  at end  go to  addition-error
             when ar1 (q) = array (a)
                  go to  addition-do.

addition-do.
    set      y  to  q.
    compute  z  =   y * (8 - a).
    add      z  to  suma.

from __future__ import annotations
from pydantic import BaseModel, field_validator
import structlog

logger = structlog.get_logger()

ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"


def compute_mod11_check_digit(identity: str) -> int:
    """Return the MOD-11 check digit for the 6-char identity portion."""
    if len(identity) != 6:
        raise ValueError("identity must be 6 characters")
    total = 0
    for position, ch in enumerate(identity, start=1):
        q = ALPHABET.index(ch) + 1   # 'set q to 1' + search ar1
        total += q * (8 - position)  # compute z = y * (8 - a)
    if total == 0:
        raise ValueError("invalid identity (zero weighted sum)")
    remainder = total % 11
    return 11 - remainder


class SupplierId(BaseModel):
    value: str  # 7 chars: 6 identity + 1 check digit

    @field_validator("value")
    @classmethod
    def verify(cls, v: str) -> str:
        if len(v) != 7:
            raise ValueError("supplier id must be 7 chars")
        identity, supplied = v[:6], v[6]
        computed = compute_mod11_check_digit(identity)
        if str(computed) != supplied:
            logger.warning(
                "supplier_id.check_digit_mismatch",
                identity=identity,
                supplied=supplied,
                computed=computed,
            )
            raise ValueError("MOD-11 check digit mismatch")
        return v

8.3 Example 2 — Posting Gate Guard (P-Flag-I check)

The legacy posting gate at pl080.cbl:288-293 uses a global flag (P-Flag-I) to block payment entry whenever a prior purchase-ledger step left unposted transactions. The target replaces the global with an explicit state table and returns RFC 7807 409 Conflict from the FastAPI handler.

if       P-Flag-I = 1
         display PL121   at 0501
         display PL116   at 2401
         accept ws-reply at 2440
         go to main-exit.

from fastapi import APIRouter, Depends, status
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
from opentelemetry import trace
import structlog

from .deps import get_session
from .models import PaymentCreate, PaymentRead
from .exceptions import PostingRequiredError
from .db import PurchasePostingState

router = APIRouter(prefix="/api/v1/payments", tags=["payments"])
logger = structlog.get_logger()
tracer = trace.get_tracer("payment-api")


@router.post("", response_model=PaymentRead,
             status_code=status.HTTP_201_CREATED)
async def create_payment(
    body: PaymentCreate,
    session: AsyncSession = Depends(get_session),
) -> PaymentRead:
    with tracer.start_as_current_span("payment.create") as span:
        span.set_attribute("supplier.code", body.counterparty_code)
        # BR-PAY-001 — posting gate guard (replaces P-Flag-I global)
        state = (await session.execute(
            select(PurchasePostingState).limit(1)
        )).scalar_one()
        if state.flag != "posted":
            logger.warning(
                "payment.create.blocked_posting_required",
                state=state.flag,
            )
            raise PostingRequiredError(state=state.flag)
        # ... appropriation, persistence, event emission elided ...

8.4 Example 3 — Early-Payment Discount Calculation

The most arithmetic-heavy of the catalog rules. Legacy computes u-bin = oi-date + oi-deduct-days, tests u-bin > pay-date, and subtracts the configured deduction from the outstanding net when the payment falls inside the discount window. Target translates the formula verbatim into a Decimal-based pure function with an OpenTelemetry span for traceability.

move     oi-date  to  u-bin.
perform  zz060-Convert-Date.
move     11 to cole.
display  u-date at curs with foreground-color 3.

move     work-net to work-1.
move     work-ded to work-2.

add      1  oi-deduct-days  to  u-bin.
if       u-bin  >  pay-date
         subtract  work-2  from  work-1
         move work-2 to display-5
else
         move zero   to display-5.

subtract oi-paid  from  work-1.
move     work-1 to pay-paid.
move     work-1 to display-8.

from __future__ import annotations
from dataclasses import dataclass
from datetime import date, timedelta
from decimal import Decimal
from opentelemetry import trace
import structlog

logger = structlog.get_logger()
tracer = trace.get_tracer("payment-api.discounts")

ZERO = Decimal("0.00")


@dataclass(frozen=True)
class Invoice:
    invoice_ref: str
    invoice_date: date
    deduct_days: int       # oi-deduct-days
    work_net: Decimal      # oi-net (outstanding net)
    work_ded: Decimal      # oi-deduct-amt (configured deduction)
    oi_paid: Decimal       # prior paid amount


@dataclass(frozen=True)
class AppropriationLine:
    invoice_ref: str
    new_outstanding: Decimal   # work-1
    discount_taken: Decimal    # display-5


def compute_appropriation(inv: Invoice,
                          payment_date: date) -> AppropriationLine:
    with tracer.start_as_current_span("discount.compute") as span:
        span.set_attribute("invoice.ref", inv.invoice_ref)
        # u-bin = oi-date + 1 + oi-deduct-days
        cutoff = inv.invoice_date + timedelta(days=1 + inv.deduct_days)
        work_1 = inv.work_net
        if cutoff > payment_date:                       # within window
            work_1 -= inv.work_ded                      # subtract deduction
            discount = inv.work_ded
        else:
            discount = ZERO
        work_1 -= inv.oi_paid
        span.set_attribute("discount.taken", str(discount))
        logger.info(
            "discount.computed",
            invoice_ref=inv.invoice_ref,
            cutoff=cutoff.isoformat(),
            within_window=bool(cutoff > payment_date),
            discount_taken=str(discount),
            new_outstanding=str(work_1),
        )
        return AppropriationLine(
            invoice_ref=inv.invoice_ref,
            new_outstanding=work_1,
            discount_taken=discount,
        )

8.5 Example 4 — Unapplied-Balance Prompt

BR-PAY-007 surfaces a Y/N prompt when the supplier has a non-zero purch-unapplied balance. Answering Y flips transaction-type from 5 (plain payment) to 6 (unapplied allocation) and consumes the unapplied amount. The target represents the choice as a boolean field on the request body; the UI surfaces a conditional checkbox; the same 5/6 sentinel values are preserved server-side for SAROC bridge compatibility.

move     5 to transaction-type.
if       purch-unapplied = zero
         go to value-input.

move     purch-unapplied to display-8 amt-ok.
display  "Unapplied Balance - " at 0645
         with foreground-color 2.
display  display-8 at 0665 with foreground-color 3.
display  "Do you wish to allocate the unapplied Balance to this account?  [Y]"
         at 1601 with foreground-color 2.
move     "Y" to ws-reply.

accept-unappl-reqst.
    move     zero to cob-crt-status.
    accept   ws-reply at 1666 with foreground-color 6 update.
    if       cob-crt-status = cob-scr-esc
             go to new-payment-Main.
    move     function upper-case (ws-reply) to ws-reply.
    if       ws-reply not = "Y" and not = "N"
             go to accept-unappl-reqst.
    if       ws-reply = "N"
             display space at 1601 with erase eol
             go to value-input.

move     6 to transaction-type.

from decimal import Decimal
from enum import IntEnum
from pydantic import BaseModel, Field
import structlog

logger = structlog.get_logger()


class TransactionType(IntEnum):
    PAYMENT = 5               # legacy oi-type sentinel
    UNAPPLIED_ALLOCATION = 6


class PaymentCreate(BaseModel):
    counterparty_code: str
    payment_date: date
    amount_total: Decimal
    allocate_unapplied: bool = Field(
        default=False,
        description="BR-PAY-007: consume the supplier's "
                    "purch-unapplied balance.",
    )


async def assign_transaction_type(
    supplier_unapplied: Decimal,
    allocate_unapplied: bool,
) -> TransactionType:
    """Replaces accept-unappl-reqst loop."""
    if supplier_unapplied > Decimal("0") and allocate_unapplied:
        logger.info("payment.transaction_type.unapplied_consumed",
                    amount=str(supplier_unapplied))
        return TransactionType.UNAPPLIED_ALLOCATION
    return TransactionType.PAYMENT

8.6 Example 5 — Payment Method Determination (BACS vs Cheque)

BR-PAY-005 is the strongest cross-service example in the catalog. pl940.cbl:517-525 inspects the supplier sort-code, increments the cheque counter on zero, and tags the record BACS otherwise. The target splits this single physical file path into two pipelines: cheque payments produce a printable cheque PDF in payment-batch; BACS payments publish a payment.issued.bacs event consumed downstream. The mitigation is a smoke test asserting no payment is dropped between the legacy single-file path and the dual-path target.

if       pay-sortcode = zero
         move cheque-nos to c-cheque
         move cheque-nos to pay-cheque
         add  1 to cheque-nos
else
         move zero   to pay-cheque
         move "BACS" to c-cheque-x.

from enum import StrEnum
from opentelemetry import trace
from aio_pika import Message, DeliveryMode
import structlog

logger = structlog.get_logger()
tracer = trace.get_tracer("payment-batch.cheque_run")


class PaymentMethod(StrEnum):
    CHEQUE = "CHEQUE"
    BACS = "BACS"


async def route_payment(payment, *, cheque_counter, channel):
    """Replaces pl940's single physical file with two pipelines."""
    with tracer.start_as_current_span("payment.route") as span:
        span.set_attribute("payment.id", str(payment.id))
        if payment.sort_code == 0:
            method = PaymentMethod.CHEQUE
            cheque_no = cheque_counter.next()
            payment.cheque_no = cheque_no
            span.set_attribute("payment.method", "CHEQUE")
            span.set_attribute("cheque.no", cheque_no)
            logger.info("payment.routed.cheque",
                        payment_id=str(payment.id),
                        cheque_no=cheque_no)
        else:
            method = PaymentMethod.BACS
            payment.cheque_no = None
            span.set_attribute("payment.method", "BACS")
            await channel.default_exchange.publish(
                Message(
                    body=payment.to_event_bytes(method),
                    delivery_mode=DeliveryMode.PERSISTENT,
                    content_type="application/json",
                ),
                routing_key="acas.payment.issued.bacs",
            )
            logger.info("payment.routed.bacs",
                        payment_id=str(payment.id),
                        sort_code=payment.sort_code)
        payment.method = method
        return method

8.7 Example 6 — Inline Cash Posting + GL Journal (single DB transaction)

pl100.cbl:329-414 walks open-item records, updates the supplier's purch-current balance, and inline-writes a GL batch row via BL-Write. The target collapses this into a single SQLAlchemy 2.0 async unit-of-work that updates the payment status, inserts the GL postings, and commits atomically — eliminating the legacy overnight-cycle latency.

loop.
    perform  OTM5-Read-Next.
    if       fs-reply = 10
             go to  main-end.

    if       oi-type = 2 and
             oi-b-nos not = zero and
             oi-b-item not = zero
             perform compute-purch-pay thru csp-exit
             move zeros to oi-b-nos oi-b-item oi-cr
             perform OTM5-Rewrite
             go to loop.
    ...
cust-update.
    move     oi-supplier  to  WS-Purch-Key.
    perform  Purch-Read-Indexed.
    subtract oi-approp     from purch-current.
    subtract oi-deduct-amt from purch-current.
    move     oi-approp to oi-paid.
    perform  Purch-Rewrite.

    if       G-L
             perform  BL-Write.        *> inline GL journal
    move     1  to  oi-status.
    perform  OTM5-Rewrite.

from decimal import Decimal
from sqlalchemy import select, update
from sqlalchemy.ext.asyncio import AsyncSession
from opentelemetry import trace
import structlog

from .db import Payment, OpenItem, GlPosting, PaymentAudit
from .exceptions import PostingError

logger = structlog.get_logger()
tracer = trace.get_tracer("payment-batch.posting")


async def post_batch(batch_number: int,
                     posted_by: str,
                     session: AsyncSession) -> int:
    with tracer.start_as_current_span("batch.post") as span:
        span.set_attribute("batch.number", batch_number)
        # Single DB transaction: all writes commit or roll back together
        items = (await session.execute(
            select(OpenItem).where(
                OpenItem.batch_number == batch_number,
                OpenItem.type.in_([5, 6]),         # BR-PAY-003 carry-through
            )
        )).scalars().all()
        if not items:
            raise PostingError("nothing to post")

        gl_debit = Decimal("0.00")
        gl_credit = Decimal("0.00")
        for it in items:
            # Mirror pl100 cust-update: subtract approp + deduct from balance
            session.add(GlPosting(
                payment_id=it.payment_id,
                account="5000",      # Trade Creditors (DR)
                amount=it.approp_amount,
                direction="DR",
            ))
            session.add(GlPosting(
                payment_id=it.payment_id,
                account="1200",      # Bank (CR)
                amount=it.approp_amount,
                direction="CR",
            ))
            gl_debit += it.approp_amount
            gl_credit += it.approp_amount
            it.posting_reference = f"BATCH-{batch_number}"

        await session.execute(
            update(Payment)
            .where(Payment.batch_number == batch_number)
            .values(status="POSTED", posted_by=posted_by)
        )
        session.add(PaymentAudit(
            batch_number=batch_number,
            actor=posted_by,
            event="batch.posted",
            payload={"gl_debit": str(gl_debit),
                     "gl_credit": str(gl_credit),
                     "items_posted": len(items)},
        ))
        await session.commit()        # atomic: payment + GL together
        span.set_attribute("payments.posted", len(items))
        logger.info("batch.posted",
                    batch_number=batch_number,
                    items=len(items),
                    gl_total=str(gl_debit))
        return len(items)

8.8 Data Access Patterns

The legacy code accesses data through the Payment File Handler Abstraction (Concho entity acas032, ~650 LOC, conf 0.80) — a dual-mode ISAM/MySQL switch driven by FA-RDBMS-Flat-Statuses. Every perform OTM5-Open / Read-Next / Rewrite / Close branches on the storage-mode flag and either calls the ISAM handler or the MySQL bridge. Modern code replaces this entirely with the SQLAlchemy repository pattern:

8.9 Error Handling Patterns

COBOL's classical error idiom is if fs-reply ≠ 0 after every file operation, with display "PLnnn"-style on-screen messages. The target uses an explicit domain-exception hierarchy mapped to RFC 7807 Problem Details responses by a single FastAPI exception handler. The legacy idiom and its target replacement, side by side:

     move     pay-customer  to  WS-Purch-Key.
*>
     perform  Purch-Read-Indexed.  *> read purchase-file
*>                                     record invalid key
     if       fs-reply = 21
              move  zero  to  c-check.
*>
     if       not  c-exists
              go to  customer-input.
*>
*>  Every file op is followed by an inline fs-reply test;
*>  status 21 = "record not found", 10 = end-of-file.
*>  On-screen "PLnnn" messages report the error to the
*>  operator — no structured error contract exists.

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from opentelemetry import trace
import structlog

from .exceptions import (
    DomainError, ValidationError, NotFoundError,
    ConflictError, PostingRequiredError,
)

logger = structlog.get_logger()


def install_error_handlers(app: FastAPI) -> None:
    @app.exception_handler(DomainError)
    async def handle_domain_error(request: Request, exc: DomainError):
        span = trace.get_current_span()
        span.record_exception(exc)
        span.set_attribute("error.code", exc.code)
        logger.warning("api.domain_error",
                       code=exc.code,
                       path=request.url.path)
        return JSONResponse(
            status_code=exc.status_code,
            content={
                "type": f"https://acas.example/errors/{exc.code}",
                "title": exc.title,
                "status": exc.status_code,
                "detail": exc.detail,
                "instance": str(request.url),
            },
            media_type="application/problem+json",
        )

Concrete subclasses:

• ValidationError → HTTP 422 (replaces COBOL "re-prompt on invalid reply" loops).
• NotFoundError → HTTP 404 (replaces fs-reply = 21 "record not found" branches).
• ConflictError → HTTP 409 (replaces sentinel-flag blocking like BR-PAY-001 posting gate).
• PostingRequiredError → HTTP 409 + code: POSTING_REQUIRED (specific to BR-PAY-001).
• DependencyError → HTTP 503 (downstream RabbitMQ / S3 / RDS unavailable).

8.10 Testing Approach for Translated Code

This subsection covers verification at the translated-code layer (pytest + pytest-asyncio, 80% coverage floor per resolved targetPatterns.testing). The broader testing posture — Playwright behavior tests auto-derived from the Section 9 BR catalog + the Section 9.8 field-level rules, run inside the iterate-till-green loop in the artifact-generation workflow — is described as part of that downstream workflow and is the gate that decides whether artifacts ship; the pytest layers below are what those Playwright tests stand on.

1. Unit tests against pure functions (e.g., compute_appropriation, compute_mod11_check_digit) using table-driven cases generated from the COBOL examples in the Concho Cycle 8 entities. Each business-rule entry in the catalog (behavioral-rules-catalog-012.md) yields at least one happy-path test and one boundary test.
2. Integration tests against an in-process FastAPI + an ephemeral PostgreSQL container (via testcontainers); these exercise the SQLAlchemy unit-of-work, the GL inline posting, and the RabbitMQ event emission (with an in-memory broker).
3. Playwright behavior tests (handoff to the artifact workflow) — the render-playwright-br-spec and render-playwright-spec generators emit a .spec.ts per BR + per field-level rule + per user-journey scene. The artifact-generation workflow runs these in an iterate-till-green loop driven by mig-adversarial-validator: a Playwright failure rejects the artifact, the validator emits a diff against the spec, the artifact agent regenerates, the loop repeats until 100% green. PASS-DEFERRED is forbidden. See the artifact workflow's RUNTIME-VERIFICATION-RETROSPECTIVE.md for the per-defect log produced by this loop in run-012.
4. Adversarial / consensus tests — only the BR-PAY-008 cap-relaxation mitigation requires a SAROC dual-storage fixture comparing legacy COBOL output against modern output side-by-side, because it is the one rule whose per-payment behavior actually changes (hard cap → soft cap → no cap). BR-PAY-005 and BR-PAY-010 are delivery refactors — their per-payment behavior is identical, so they are covered by the unit/integration/Playwright layers above without needing a side-by-side comparison.

A future revision of this report will lift testing into its own top-level section so it is not buried inside “Code Translation Examples.” The content above is the code-translation slice; the artifact-workflow slice (iterate-till-green, Playwright auto-derivation, per-step validators) is owned by the companion code-generation workflow.

8.11 Code Translation Summary

The artifact-generation workflow scales this pattern across the rest of the 30-strong file set: each COBOL program in purchase/pl08x-pl9xx and common/maps* maps to a FastAPI router, a service-layer module, and a SQLAlchemy data-access layer, with the resolved targetPatterns consistently applied.

9. Business Rules Analysis

This section documents the behavioral rules extracted from the ACAS Payment Processing subsystem, showing COBOL source implementation alongside Python (FastAPI) translations with formal Given-When-Then specifications. All 10 rules were discovered through Concho's Context Graph analysis (cycle 8) and verified against COBOL source code via the Concho MCP get_file_content_in_range tool. A companion subsection — Section 9.8: Field-Level Business Rules — extends this catalog with per-field validation and formatting rules auto-derived from the UI field inventory; those field-level rules feed directly into Playwright test generation for the artifact workflow.

9.1 Business Rules Overview

Concho cycle 8 catalogued 214 system-wide business rules across the ACAS codebase. Filtering to the Payment Processing subsystem and applying a confidence floor of 0.60 produced the 10 rules documented here. The rule extraction uses Concho's converged-entity model (the canonical merge of redundant rule statements across files) which is why a single rule like SupplierAccountNumberFormat consolidates four duplicate source statements into one BR. Concho confidence scores range from 0.60 to 0.88; the most confident rule (BR-PAY-002, MOD-11 check digit) has STRUCTURAL evidence from a 60-line algorithm in common/maps09.cbl, while the lowest-confidence rules (BR-PAY-007 Unapplied Balance, BR-PAY-009 Payment Reversal) are INFERRED from flow patterns rather than explicit declarations.

ACAS is a COBOL/GnuCOBOL codebase with no automated test suite cataloged by Concho (search_files for file_category=Test returned 0 results). Per the legacy-test-discovery skill, the COBOL short-circuit applies: every BR's testEvidence[] is empty and every GWT carries origin: code-inferred. This is expected for mainframe-shaped projects — absence of test corroboration is a fact about the source repository, not a quality flag against this catalog. The artifact-generation workflow that follows this report will generate Playwright behavior tests from each BR's GWT specification (combined with the field-level rules in Section 9.8), giving the modernized stack the regression coverage the legacy never had.

Rule Distribution by Category

Rule Discovery Methodology

Concho's get_insight(insight_type='business_rules', detail_level='detailed') surfaced the system-wide rule inventory with confidence and evidence-quality distributions. get_entities_by_subject(subject_name='Payment Processing', entity_type='business_rule') and a series of search_entities queries (filtered by name patterns Payment / Batch / Supplier / Remittance and confidence_gte = 0.6 to 0.8) narrowed the catalog to the Payment Processing scope. For each candidate rule, get_entity retrieved the converged description, source-file list, and line references. Workflow-assigned BR-PAY-NNN identifiers were applied during this report-generation step — the BR-PAY-NNN tokens do NOT exist in the COBOL source code and never appear inside the legacy-code panels below.

For each cited line reference, get_file_content_in_range retrieved the actual COBOL implementation, which is the source for the COBOL panels shown below. The Given-When-Then specifications were derived from a combination of the Concho entity description (canonical statement of intent) and the verified COBOL implementation (literal facts about flow control, comparison operators, and field semantics). No COBOL code was fabricated; no line references were invented.

9.2 Validation Rules

BR-PAY-001: Payment Posting Validation

     if       P-Flag-I = 1
              display PL121   at 0501
              display PL116   at 2401
              accept ws-reply at 2440
              go to main-exit.
*>
     if       FS-Cobol-Files-Used  *> code added to match sl080
              call  "CBL_CHECK_FILE_EXIST" using File-29    *> Open ITM5 file
                                                 File-Info
              if    return-code not = zero          *> not = zero - No file found
                    display  PL119  at 2301
                    display  PL116  at 2401
                    accept ws-reply at 2440
                    go to main-exit
              end-if
     end-if.

@router.post("/payments", status_code=201)
async def create_payment(
    body: NewPaymentRequest,
    ledger: PurchaseLedgerState = Depends(get_ledger_state),
) -> PaymentCreated:
    if ledger.posting_state != PostingState.POSTED:
        raise HTTPException(
            status_code=409,
            detail={
                "code": "POSTING_REQUIRED",
                "message": (
                    "Purchase ledger has unposted transactions; "
                    "complete posting before recording payments."
                ),
            },
        )
    # ... payment-entry path proceeds ...

BR-PAY-002: Supplier Account Number Format (MOD-11 Check Digit)

Reassigned from Section 5: The platform-affinity reconciler explicitly relocated SupplierAccountNumberFormat from the platform-constraints section to Section 9 because the MOD-11 check digit is a genuine business identity invariant, not a platform artifact. Concho's canonical entity name is CustomerNumberMOD11CheckDigitValidation — the algorithm is shared across customer and supplier identifiers via the maps09 utility.

 main.
     move     customer-nos  to  work-array.
     move     zero  to  suma.
     perform  addition-loop through addition-end
              varying a from 1 by 1 until a > 6.
*>
     if       suma = zero
              move  "N"  to  maps09-reply
              go to  main-exit.
*>
     divide   suma  by  11  giving  z.
     compute  a  =  11 - (suma - (11 * z)).
*>
     if       maps09-reply = "C"
              move   a   to  check-digit
              move  "Y"  to  maps09-reply.
*>
     if       maps09-reply = "V"
       and    a = check-digit
              move  "Y"  to  maps09-reply.
*>
 addition-do.
     set      y  to  q.
     compute  z  =   y * (8 - a).
     add      z  to  suma.

ACAS_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"

def _mod11_sum(identifier: str) -> int:
    """Weighted sum: position p (1..6) uses weight (8 - p)."""
    suma = 0
    for position, ch in enumerate(identifier[:6], start=1):
        weight = 8 - position
        ordinal = ACAS_ALPHABET.index(ch) + 1
        suma += ordinal * weight
    return suma

def compute_check_digit(identifier_6: str) -> int | None:
    suma = _mod11_sum(identifier_6)
    if suma == 0:
        return None
    z = suma // 11
    return 11 - (suma - (11 * z))

def verify_supplier_id(supplier_id: str) -> bool:
    if len(supplier_id) != 7:
        return False
    expected = compute_check_digit(supplier_id[:6])
    if expected is None:
        return False
    return str(expected) == supplier_id[6]

BR-PAY-003: Payment Type Filtering (Sort Eligibility)

     perform  OTM3-Read-Next.   *> read open-item-file-3 next record
     if       fs-reply = 10
              go to  end-of-input.
*>
     if       oi-type = 1 or 3            *> Ignore Receipts & Cr. Notes
              go to process-input.
     if       zero = oi-b-nos and oi-b-item   *> batch data zero
              go to process-input.
*>
     release  sort-record from  open-item-record-3.
     go       to  process-input.

class OpenItemType(IntEnum):
    RECEIPT = 1
    INVOICE = 2
    CREDIT_NOTE = 3
    DEBIT = 4

# Eligible for payment-proof sort:
PROOF_ELIGIBLE_TYPES = {OpenItemType.INVOICE, OpenItemType.DEBIT}

def select_proof_candidates(session: Session) -> list[OpenItem]:
    return (
        session.query(OpenItem)
        .filter(OpenItem.type.in_(PROOF_ELIGIBLE_TYPES))
        .filter(or_(OpenItem.batch_no != 0,
                    OpenItem.batch_item != 0))
        .order_by(OpenItem.batch_no, OpenItem.batch_item)
        .all()
    )

9.3 Calculation Rules

BR-PAY-004: Early Payment Discount Calculation

     move     work-net to work-1.
     move     work-ded to work-2.
*>
     add      1  oi-deduct-days  to  u-bin.
     if       u-bin  >  pay-date
              subtract  work-2  from  work-1
              move work-2 to display-5
     else
              move zero   to display-5.
*>
     subtract oi-paid  from  work-1.
     move     work-1 to pay-paid.
     move     work-1 to display-8.

from decimal import Decimal
from datetime import date, timedelta
from dataclasses import dataclass

@dataclass(frozen=True)
class DiscountResult:
    discount_taken: Decimal     # display-5 in legacy
    appropriation:  Decimal     # work-1 / pay-paid in legacy

def compute_early_discount(
    *, work_net: Decimal, work_ded: Decimal,
    oi_deduct_days: int, oi_date: date, oi_paid: Decimal,
    pay_date: date,
) -> DiscountResult:
    discount_deadline = oi_date + timedelta(days=1 + oi_deduct_days)
    if discount_deadline > pay_date:
        appropriation = work_net - work_ded - oi_paid
        return DiscountResult(work_ded, appropriation)
    return DiscountResult(Decimal("0"), work_net - oi_paid)

BR-PAY-005: Payment Method Determination (BACS vs Cheque) delivery refactor

     if       pay-sortcode = zero
              move cheque-nos to c-cheque pay-cheque
              add 1 to cheque-nos
     else
              move zero     to pay-cheque
              move "BACS"   to c-cheque-x
     end-if
     write cheque-record from cheque.
*>
     move     u-bin  to  pay-date.
     perform  Payments-Rewrite.
*>
*> now loop back for next item....
*>
     go       to read-purchase.

class PaymentMethod(str, Enum):
    CHEQUE = "cheque"
    BACS   = "bacs"

def determine_method(supplier: Supplier) -> PaymentMethod:
    """pl940:517 — sort_code == 0 means physical cheque."""
    if supplier.sort_code == 0:
        return PaymentMethod.CHEQUE
    return PaymentMethod.BACS

async def finalize_payment(
    payment: Payment, supplier: Supplier,
    cheque_seq: ChequeSequence, broker: MessageBroker,
) -> None:
    method = determine_method(supplier)
    if method is PaymentMethod.CHEQUE:
        payment.cheque_no = await cheque_seq.next_value()
        await ledger.persist(payment)
        await broker.publish("payment.issued.cheque", payment.dict())
    else:
        payment.cheque_no = 0
        await ledger.persist(payment)
        await broker.publish("payment.issued.bacs",   payment.dict())

9.4 State Transition Rules

BR-PAY-006: Batch Status Lifecycle

             88  PL-Batch                   value 2.
             88  SL-Batch                   value 3.
         05  Batch-Nos       pic 9(5).
     03  Items               pic 99.
*>
     03  Batch-Status        pic 9.
         88  Status-Open                    value 0.
         88  Status-Closed                  value 1.
*>
     03  Cleared-Status      pic 9.
         88  Waiting                        value 0.
         88  Processed                      value 1.
         88  Archived                       value 2.
*>
     03  Bcycle              pic 99.
     03  Dates.
         05  Entered         binary-long.
         05  Proofed         binary-long.
         05  Posted          binary-long.
         05  Stored          binary-long.

class BatchStatus(IntEnum):
    OPEN   = 0
    CLOSED = 1

class ClearedStatus(IntEnum):
    WAITING   = 0
    PROCESSED = 1
    ARCHIVED  = 2

# Permitted transitions enforced at the DB layer via CHECK constraint
# and at the service layer via this map:
_BATCH_TRANSITIONS = {BatchStatus.OPEN: {BatchStatus.CLOSED}}
_CLEARED_TRANSITIONS = {
    ClearedStatus.WAITING:   {ClearedStatus.PROCESSED},
    ClearedStatus.PROCESSED: {ClearedStatus.ARCHIVED},
}

def transition_batch(b: Batch, target: BatchStatus, posted: Decimal) -> None:
    if target not in _BATCH_TRANSITIONS.get(b.status, set()):
        raise InvalidTransition(b.status, target)
    if target is BatchStatus.CLOSED and posted != b.header_total:
        raise BatchTotalsMismatch(expected=b.header_total, actual=posted)
    b.status = target
    audit_log.record(b.id, "batch.status", b.status, target)

BR-PAY-007: Unapplied Balance Allocation

     move     5 to transaction-type.
     if       purch-unapplied = zero
              go to value-input.
*>
     move     purch-unapplied to display-8 amt-ok.
     display  "Unapplied Balance - " at 0645 with foreground-color 2.
     display  display-8 at 0665 with foreground-color 3.
     display  "Do you wish to allocate the unapplied Balance to this account?  [Y]"
              at 1601 with foreground-color 2.
     move     "Y" to ws-reply.
*>
 accept-unappl-reqst.
     move     zero to cob-crt-status.
     accept   ws-reply at 1666 with foreground-color 6 update.
     move     function upper-case (ws-reply) to ws-reply.
     if       ws-reply not = "Y" and not = "N"
              go to accept-unappl-reqst.
     if       ws-reply = "N"
              display space at 1601 with erase eol
              go to value-input.
*>
     move     6 to transaction-type.

class TransactionType(IntEnum):
    PAYMENT             = 5
    UNAPPLIED_ALLOCATION = 6

class NewPaymentRequest(BaseModel):
    supplier_id: str
    amount:      Decimal
    pay_date:    date
    # When the supplier has a non-zero unapplied balance, the UI
    # surfaces a checkbox bound to this field:
    allocate_unapplied: bool = False

@router.post("/payments", status_code=201)
async def create_payment(body: NewPaymentRequest, ...):
    supplier = await suppliers.get(body.supplier_id)
    if supplier.unapplied_balance > 0 and body.allocate_unapplied:
        txn_type = TransactionType.UNAPPLIED_ALLOCATION  # 6
        supplier.unapplied_balance = Decimal("0")
    else:
        txn_type = TransactionType.PAYMENT                # 5
    # ... record payment with txn_type ...

9.5 Workflow Rules

BR-PAY-008: Payment Batch Control Limits (99-item cap + composite key) mitigation required

*> copybooks/fdbatch.cob: header layout
     03  Items               pic 99.    *> max 99 per batch
     03  Batch-Status        pic 9.
*>
*> purchase/pl080.cbl:731 — composite invoice key
     move     pay-customer  to  oi-supplier.
     move     pay-date  to  oi-date.
     move     transaction-type to  oi-type.
     move     pay-value to  oi-paid.
     move     approp-amount  to  oi-approp.
     move     deduct-taken   to  oi-deduct-amt.
     move     bl-next-batch  to  oi-b-nos.
     move     k           to  oi-b-item.
     multiply oi-b-nos by 1000 giving oi-invoice.
     add      oi-b-item to oi-invoice.
*>
     move     OI-Header to WS-OTM5-Record.
     perform  OTM5-Write.

SAROC_COEXISTENCE_ITEM_CAP = 99   # feature-flag-gated soft cap

class Batch(SQLModel, table=True):
    id:            UUID = Field(default_factory=uuid4, primary_key=True)
    batch_no:      int  = Field(index=True, unique=True)
    items_count:   int  = Field(default=0)  # PG BIGINT, no 99 ceiling
    status:        BatchStatus = BatchStatus.OPEN
    header_total:  Decimal     = Decimal("0")

def add_item(batch: Batch, item: OpenItem,
             coexistence_mode: bool) -> OpenItem:
    if coexistence_mode and batch.items_count >= SAROC_COEXISTENCE_ITEM_CAP:
        raise BatchFullDuringCoexistence(batch_no=batch.batch_no)
    batch.items_count += 1
    item.batch_no  = batch.batch_no
    item.batch_item = batch.items_count
    # Composite legacy key emitted for SAROC bridge translation only:
    item.legacy_invoice_key = batch.batch_no * 1000 + item.batch_item
    return item

BR-PAY-009: Payment Reversal Processing

*>
     if       oi-approp = zero
              go to  skip-pay-approp.
     move     oi-deduct-amt  to si-deduct-amt.
*>
 data-input.
     perform  payment-appropriate.
*>
 skip-pay-approp.
*>
     if       trans-unapplied
              add hold-pay to purch-unapplied
              perform Purch-Rewrite.
     move     14  to  lin.
     perform  erase-screen.
     display  "Make further corrections? (Y/N)  [Y]"
              at 1629 with foreground-color 2.
*>
 more-data.
     move     "Y"  to   ws-reply.
     accept   ws-reply at 1663 with foreground-color 6 update.
     move     function upper-case (ws-reply) to ws-reply.

class PaymentCorrection(SQLModel, table=True):
    id:                UUID
    original_id:       UUID   # FK to payments.id (immutable)
    correction_id:     UUID   # FK to payments.id (the new amount)
    delta_amount:      Decimal
    created_at:        datetime
    actor:             str

@router.post("/payments/{payment_id}/reverse",
             status_code=200,
             response_model=PaymentReversed)
async def reverse_payment(
    payment_id: UUID, body: ReversalRequest,
    broker: MessageBroker, ...
) -> PaymentReversed:
    original = await payments.require(payment_id)
    if original.transaction_type == TransactionType.UNAPPLIED_ALLOCATION:
        # Mirrors pl085:445 — trans-unapplied path
        supplier = await suppliers.get(original.supplier_id)
        supplier.unapplied_balance += original.amount
    correction = await payments.create_correction(
        original=original, new_amount=body.corrected_amount,
        actor=body.actor,
    )
    await broker.publish("payment.reversed", correction.event())
    return PaymentReversed.from_orm(correction)

BR-PAY-010: Remittance Advice Processing delivery refactor

     perform  varying z from 1 by 1 until z > 9
              move  c-inv (z)    to  l4-inv
              move  c-folio (z)  to  l4-folio
              move  c-value (z)  to  l4-amount
              if    l4-amount  not equal  spaces
                    write  print-record  from  line-4 after 1
     end-perform.
*>
     write     print-record  from  line-5 after 3  lines.
*>
     if       C-Cheque not = "BACS"
              move "Cheque"  to  l6-chq-bacs
              move C-Cheque  to  l6-cheque
     else
              move "BACS" to l6-chq-bacs
              move "to your Bank" to l6-cheque.
     move     c-gross   to  l6-total.
*>
     write    print-record  from  line-6 after 1.

async def render_remittance(payment: Payment, supplier: Supplier,
                            invoices: list[InvoiceLine]) -> bytes:
    # Equivalent of pl960 zero-amount skip:
    visible_lines = [
        ln for ln in invoices
        if ln.amount and ln.amount != Decimal("0")
    ]
    method_text = (
        f"Cheque {payment.cheque_no}"
        if payment.method is PaymentMethod.CHEQUE
        else "BACS to your Bank"
    )
    ctx = {
        "supplier":     supplier,
        "lines":        visible_lines,
        "method_text":  method_text,
        "total":        payment.amount,
    }
    pdf = await render_pdf_template("remittance.html.j2", ctx)
    s3_key = f"remittance/{payment.id}.pdf"
    await s3.put_object(bucket=REMITTANCE_BUCKET, key=s3_key, body=pdf)
    return s3_key

9.6 Test Cases (Representative)

The following table illustrates representative test cases for each rule category. The companion artifact-generation workflow auto-derives complete Playwright behavior tests from each BR's Given-When-Then specification and from the field-level rules in Section 9.8.

9.7 Business Rule Traceability

For the testing approach that validates rule preservation (unit, integration, regression) at the artifact level, see Section 8.7: Testing Approach. The artifact-generation workflow auto-derives Playwright behavior tests from this section's Given-When-Then specifications and the field-level rules in Section 9.8 — that is where rule validation actually executes.

10. Data Mapping Strategy

For the complete target data model ER diagram showing all entity relationships, see Section 4.4: Data Model.

10.1 Legacy Data Analysis

The Payment-Processing subsystem reads/writes five physical files in the legacy GnuCOBOL stack. Each is defined by a COBOL FD (file descriptor) + working-storage copybook pair under copybooks/:

Three files (pay.dat, openitm5.dat, purchled.dat) are the watched artifacts the SAROC file-watcher monitors (per report-plan.json.coexistencePattern.source.watchedArtifacts); the file-watcher emits diff events that the SAROC consumer in payment-batch applies to the PostgreSQL schema with natural-key idempotency.

10.2 Schema Mappings — 3 worked entity examples

For the complete target data model ER diagram showing all entity relationships, see Section 4.4: Data Model. The mappings below illustrate the per-entity 4-zone layout: 3 code columns on top (Legacy COBOL / PostgreSQL DDL / SQLAlchemy ORM) followed by full-width Schema Mapping Notes.

10.2.1 Payment — fdpay.cob → payment + payment_line

fd  Pay-File.
01  Pay-Record.
    03  Pay-Key.
        05  Pay-Supl-Key    pic x(7).
        05  Pay-Nos         pic 99.
    03  Pay-Cont            pic x.
    03  Pay-Date            pic 9(8)  comp.
    03  Pay-Cheque          pic 9(8)  comp.
    03  Pay-SortCode        pic 9(6)  comp.
    03  Pay-Account         pic 9(8)  comp.
    03  Pay-Gross           pic s9(7)v99    comp-3.
    03  filler                      occurs 9.
        05  Pay-Folio       pic 9(8)  comp.
        05  Pay-Period      pic 99    comp.
        05  Pay-Value       pic s9(7)v99    comp-3.
        05  Pay-Deduct      pic s999v99     comp-3.
        05  Pay-Invoice     pic x(10).

CREATE TABLE payment (
  id                  UUID PRIMARY KEY
                       DEFAULT gen_random_uuid(),
  legacy_natural_key  VARCHAR(64)
                       UNIQUE NOT NULL,
  supplier_code       VARCHAR(7) NOT NULL,
  payment_number      SMALLINT NOT NULL,
  payment_method      VARCHAR(8) NOT NULL
                       CHECK (payment_method IN ('CHEQUE',
                                                  'BACS')),
  payment_date        DATE NOT NULL,
  cheque_no           BIGINT,
  sort_code           INTEGER,
  bank_account        BIGINT,
  amount_total        NUMERIC(9, 2) NOT NULL,
  currency            CHAR(3) NOT NULL DEFAULT 'USD',
  batch_number        INTEGER NOT NULL
                       REFERENCES batch_control(batch_number),
  status              VARCHAR(16) NOT NULL DEFAULT 'ENTERED',
  created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
  created_by          VARCHAR(64),
  updated_by          VARCHAR(64),
  posted_at           TIMESTAMPTZ,
  posted_by           VARCHAR(64),
  UNIQUE (supplier_code, payment_number)
);

CREATE INDEX idx_payment_batch ON payment(batch_number);
CREATE INDEX idx_payment_supplier ON payment(supplier_code);

CREATE TABLE payment_line (
  id              UUID PRIMARY KEY
                   DEFAULT gen_random_uuid(),
  payment_id      UUID NOT NULL
                   REFERENCES payment(id) ON DELETE CASCADE,
  line_seq        SMALLINT NOT NULL,
  folio           BIGINT,
  period          SMALLINT,
  amount_applied  NUMERIC(9, 2) NOT NULL,
  discount_taken  NUMERIC(5, 2) NOT NULL DEFAULT 0,
  invoice_ref     VARCHAR(10),
  UNIQUE (payment_id, line_seq)
);

from datetime import date, datetime
from decimal import Decimal
from uuid import UUID, uuid4
from sqlalchemy import (
    String, Integer, SmallInteger, Numeric, Date,
    DateTime, ForeignKey, CheckConstraint,
)
from sqlalchemy.orm import (
    Mapped, mapped_column, relationship, DeclarativeBase,
)


class Base(DeclarativeBase):
    pass


class Payment(Base):
    __tablename__ = "payment"

    id: Mapped[UUID] = mapped_column(primary_key=True,
                                     default=uuid4)
    legacy_natural_key: Mapped[str] = mapped_column(
        String(64), unique=True)
    supplier_code: Mapped[str] = mapped_column(String(7))
    payment_number: Mapped[int] = mapped_column(SmallInteger)
    payment_method: Mapped[str] = mapped_column(String(8))
    payment_date: Mapped[date] = mapped_column(Date)
    cheque_no: Mapped[int | None] = mapped_column(nullable=True)
    sort_code: Mapped[int | None] = mapped_column(nullable=True)
    bank_account: Mapped[int | None] = mapped_column(nullable=True)
    amount_total: Mapped[Decimal] = mapped_column(Numeric(9, 2))
    currency: Mapped[str] = mapped_column(String(3),
                                          default="USD")
    batch_number: Mapped[int] = mapped_column(
        ForeignKey("batch_control.batch_number"))
    status: Mapped[str] = mapped_column(String(16),
                                        default="ENTERED")
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=datetime.utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=datetime.utcnow)
    posted_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True)

    lines: Mapped[list["PaymentLine"]] = relationship(
        back_populates="payment", cascade="all, delete-orphan")

    __table_args__ = (
        CheckConstraint(
            "payment_method IN ('CHEQUE','BACS')",
            name="payment_method_valid"),
    )


class PaymentLine(Base):
    __tablename__ = "payment_line"

    id: Mapped[UUID] = mapped_column(primary_key=True,
                                     default=uuid4)
    payment_id: Mapped[UUID] = mapped_column(
        ForeignKey("payment.id", ondelete="CASCADE"))
    line_seq: Mapped[int] = mapped_column(SmallInteger)
    folio: Mapped[int | None] = mapped_column(nullable=True)
    period: Mapped[int | None] = mapped_column(SmallInteger,
                                               nullable=True)
    amount_applied: Mapped[Decimal] = mapped_column(Numeric(9, 2))
    discount_taken: Mapped[Decimal] = mapped_column(
        Numeric(5, 2), default=Decimal("0"))
    invoice_ref: Mapped[str | None] = mapped_column(String(10),
                                                    nullable=True)

    payment: Mapped[Payment] = relationship(
        back_populates="lines")

10.2.2 Open Item — plwsoi.cob → open_item

01  OI-Header.
    03  OI-Key.
        05  OI-Customer.
            07  OI-Supplier.
                09  OI-Nos    Pic X(6).
                09  OI-Check  Pic 9.
        05  OI-Invoice        Pic 9(8).
    03  OI-Date         Binary-long.
    03  OI-Batch                  Comp.
        05  OI-B-Nos    Pic 9(5).
        05  OI-B-Item   Pic 999.
    03  OI-Type         pic 9.
    03  OI-ref          pic x(10).
    03  OI-order        pic x(10).
    03  OI-hold-flag    pic x.
    03  OI-unapl        pic x.
    03  filler                          comp-3.
        05  OI-P-C      pic s9(7)v99.
        05  OI-Net      pic s9(7)v99.
        05  OI-Extra    pic s9(7)v99.
        05  OI-Carriage pic s9(7)v99.
        05  OI-Vat      pic s9(7)v99.
        05  OI-Discount pic s9(7)v99.
        05  OI-E-Vat    pic s9(7)v99.
        05  OI-C-Vat    pic s9(7)v99.
        05  OI-Paid     pic s9(7)v99.
    03  OI-Status       pic 9.
    03  OI-Deduct-Days  binary-char.
    03  OI-Deduct-Amt   pic s999v99    comp.
    03  OI-Deduct-Vat   pic s999v99    comp.
    03  OI-Days         binary-char.
    03  OI-CR           binary-long.
    03  OI-Applied      pic x.
    03  OI-Date-Cleared binary-long.

CREATE TABLE open_item (
  id                  UUID PRIMARY KEY
                       DEFAULT gen_random_uuid(),
  legacy_natural_key  VARCHAR(64) UNIQUE NOT NULL,
  supplier_code       VARCHAR(7) NOT NULL,
  invoice_ref         VARCHAR(10) NOT NULL,
  invoice_date        DATE NOT NULL,
  batch_number        INTEGER NOT NULL
                       REFERENCES batch_control(batch_number),
  batch_item          SMALLINT NOT NULL,
  payment_id          UUID
                       REFERENCES payment(id) ON DELETE SET NULL,
  type                SMALLINT NOT NULL
                       CHECK (type BETWEEN 1 AND 9),
  status              SMALLINT NOT NULL DEFAULT 0,
  hold_flag           CHAR(1),
  unapplied_flag      CHAR(1),
  amount_p_c          NUMERIC(9, 2) DEFAULT 0,
  amount_net          NUMERIC(9, 2) DEFAULT 0,
  amount_extra        NUMERIC(9, 2) DEFAULT 0,
  amount_carriage     NUMERIC(9, 2) DEFAULT 0,
  amount_vat          NUMERIC(9, 2) DEFAULT 0,
  amount_discount     NUMERIC(9, 2) DEFAULT 0,
  amount_extra_vat    NUMERIC(9, 2) DEFAULT 0,
  amount_carr_vat     NUMERIC(9, 2) DEFAULT 0,
  amount_paid         NUMERIC(9, 2) DEFAULT 0,
  deduct_days         SMALLINT,
  deduct_amount       NUMERIC(5, 2) DEFAULT 0,
  deduct_vat          NUMERIC(5, 2) DEFAULT 0,
  days_to_pay         SMALLINT,
  date_cleared        DATE,
  posting_reference   VARCHAR(32),
  created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (supplier_code, invoice_ref)
);

CREATE INDEX idx_open_item_batch
  ON open_item(batch_number, batch_item);

CREATE INDEX idx_open_item_type_status
  ON open_item(type, status)
  WHERE status = 0;        -- BR-PAY-003 hot path

from datetime import date, datetime
from decimal import Decimal
from uuid import UUID, uuid4
from sqlalchemy import (
    String, Integer, SmallInteger, Numeric, Date, DateTime,
    ForeignKey, CheckConstraint, Index,
)
from sqlalchemy.orm import Mapped, mapped_column, relationship


class OpenItem(Base):
    __tablename__ = "open_item"

    id: Mapped[UUID] = mapped_column(primary_key=True,
                                     default=uuid4)
    legacy_natural_key: Mapped[str] = mapped_column(
        String(64), unique=True)
    supplier_code: Mapped[str] = mapped_column(String(7))
    invoice_ref: Mapped[str] = mapped_column(String(10))
    invoice_date: Mapped[date] = mapped_column(Date)
    batch_number: Mapped[int] = mapped_column(
        ForeignKey("batch_control.batch_number"))
    batch_item: Mapped[int] = mapped_column(SmallInteger)
    payment_id: Mapped[UUID | None] = mapped_column(
        ForeignKey("payment.id", ondelete="SET NULL"),
        nullable=True,
    )
    type: Mapped[int] = mapped_column(SmallInteger)
    status: Mapped[int] = mapped_column(SmallInteger, default=0)
    hold_flag: Mapped[str | None] = mapped_column(String(1),
                                                   nullable=True)
    unapplied_flag: Mapped[str | None] = mapped_column(
        String(1), nullable=True)
    amount_net: Mapped[Decimal] = mapped_column(
        Numeric(9, 2), default=Decimal("0"))
    amount_paid: Mapped[Decimal] = mapped_column(
        Numeric(9, 2), default=Decimal("0"))
    amount_vat: Mapped[Decimal] = mapped_column(
        Numeric(9, 2), default=Decimal("0"))
    deduct_days: Mapped[int | None] = mapped_column(
        SmallInteger, nullable=True)
    deduct_amount: Mapped[Decimal] = mapped_column(
        Numeric(5, 2), default=Decimal("0"))
    date_cleared: Mapped[date | None] = mapped_column(
        Date, nullable=True)
    posting_reference: Mapped[str | None] = mapped_column(
        String(32), nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=datetime.utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=datetime.utcnow)

    __table_args__ = (
        CheckConstraint("type BETWEEN 1 AND 9", name="oi_type_range"),
        Index("idx_open_item_batch", "batch_number", "batch_item"),
    )

10.2.3 Batch Control — fdbatch.cob → batch_control

fd  Batch-File.
01  Batch-Record.
    03  Batch-Key.
        05  Ledger          pic 9.
            88  GL-Batch              value 1.
            88  PL-Batch              value 2.
            88  SL-Batch              value 3.
        05  Batch-Nos       pic 9(5).
    03  Items               pic 99.
    03  Batch-Status        pic 9.
        88  Status-Open               value 0.
        88  Status-Closed             value 1.
    03  Cleared-Status      pic 9.
        88  Waiting                   value 0.
        88  Processed                 value 1.
        88  Archived                  value 2.
    03  Bcycle              pic 99.
    03  Dates.
        05  Entered         binary-long.
        05  Proofed         binary-long.
        05  Posted          binary-long.
        05  Stored          binary-long.
    03  Amounts                       comp-3.
        05  Input-Gross     pic 9(9)v99.
        05  Input-Vat       pic 9(9)v99.
        05  Actual-Gross    pic 9(9)v99.
        05  Actual-Vat      pic 9(9)v99.
    03  Description         pic x(24).
    03  posting-data.
        05  bDefault        pic 99.
        05  Convention      pic xx.
        05  Batch-Def-AC    pic 9(6).
        05  Batch-Def-PC    pic 99.
        05  Batch-Def-Code  pic xx.
        05  Batch-Def-Vat   pic x.
    03  Batch-Start         pic 9(5).

CREATE TABLE batch_control (
  batch_number     INTEGER PRIMARY KEY,
  ledger           CHAR(2) NOT NULL
                    CHECK (ledger IN ('GL', 'PL', 'SL')),
  items_count      BIGINT NOT NULL DEFAULT 0,
  batch_status     SMALLINT NOT NULL DEFAULT 0
                    CHECK (batch_status IN (0, 1)),
  cleared_status   SMALLINT NOT NULL DEFAULT 0
                    CHECK (cleared_status IN (0, 1, 2)),
  bcycle           SMALLINT,
  entered_at       TIMESTAMPTZ,
  proofed_at       TIMESTAMPTZ,
  posted_at        TIMESTAMPTZ,
  stored_at        TIMESTAMPTZ,
  input_gross      NUMERIC(11, 2),
  input_vat        NUMERIC(11, 2),
  actual_gross     NUMERIC(11, 2),
  actual_vat       NUMERIC(11, 2),
  description      VARCHAR(24),
  default_ac       INTEGER,
  default_pc       SMALLINT,
  default_code     CHAR(2),
  default_vat      CHAR(1),
  convention       CHAR(2),
  batch_start      INTEGER,
  created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  -- BR-PAY-008 soft cap during SAROC coexistence; gated by
  -- application feature flag, removed at cutover
  CONSTRAINT items_soft_cap CHECK (items_count <= 999999)
);

CREATE INDEX idx_batch_status
  ON batch_control(batch_status, cleared_status);

from datetime import datetime
from decimal import Decimal
from sqlalchemy import (
    String, Integer, SmallInteger, BigInteger, Numeric,
    DateTime, CheckConstraint, Index,
)
from sqlalchemy.orm import Mapped, mapped_column


class BatchControl(Base):
    __tablename__ = "batch_control"

    batch_number: Mapped[int] = mapped_column(Integer,
                                              primary_key=True)
    ledger: Mapped[str] = mapped_column(String(2))
    items_count: Mapped[int] = mapped_column(BigInteger,
                                             default=0)
    batch_status: Mapped[int] = mapped_column(SmallInteger,
                                              default=0)
    cleared_status: Mapped[int] = mapped_column(SmallInteger,
                                                default=0)
    entered_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True)
    proofed_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True)
    posted_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True)
    stored_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), nullable=True)
    input_gross: Mapped[Decimal | None] = mapped_column(
        Numeric(11, 2), nullable=True)
    input_vat: Mapped[Decimal | None] = mapped_column(
        Numeric(11, 2), nullable=True)
    actual_gross: Mapped[Decimal | None] = mapped_column(
        Numeric(11, 2), nullable=True)
    actual_vat: Mapped[Decimal | None] = mapped_column(
        Numeric(11, 2), nullable=True)
    description: Mapped[str | None] = mapped_column(
        String(24), nullable=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=datetime.utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=datetime.utcnow)

    __table_args__ = (
        CheckConstraint("ledger IN ('GL','PL','SL')",
                        name="batch_ledger_valid"),
        CheckConstraint("batch_status IN (0, 1)",
                        name="batch_status_valid"),
        CheckConstraint("cleared_status IN (0, 1, 2)",
                        name="cleared_status_valid"),
        Index("idx_batch_status", "batch_status",
              "cleared_status"),
    )

10.3 Data Type Mappings

The cross-platform conversion table the artifact-generation workflow applies to every COBOL field across the subsystem:

10.4 Data Transfer Procedures

ACAS uses the SAROC coexistence pattern (per report-plan.json.coexistencePattern.pattern = saroc), so the data-transfer mechanism during coexistence is the SAROC bridge itself rather than a one-shot ETL. Three procedure tracks:

1. Continuous CDC (Phase 1: SAROC active, legacy authoritative).
   • File-watcher polls pay.dat, openitm5.dat, purchled.dat every 1000ms.
   • Snapshot-diff against the prior pass; each changed record is encoded into the sage-domain-event-v1 envelope.
   • Published to RabbitMQ topic exchange (persistent, DLQ enabled) with routing keys acas.legacy.payment.*, acas.legacy.open-item.*, acas.legacy.batch-control.*.
   • payment-batch SAROC consumer applies with INSERT ... ON CONFLICT (legacy_natural_key) DO UPDATE — idempotent on re-delivery.
2. Initial back-fill (one-time, before SAROC goes hot).
   • cobcrun-driven export programs walk each ISAM file, write CSV/Parquet snapshots to S3.
   • An Alembic-managed schema deploys the empty target tables; a one-shot payment-schema-migrations ECS task runs the back-fill via COPY ... FROM.
   • Row-count + checksum reconciliation per file before SAROC is turned on.
3. Cutover (Phase 2: modern authoritative, legacy archived).
   • Detailed cutover sequencing is out-of-scope for this section; see Section 11.
   • Schema-side concern: at cutover, the legacy_natural_key column is retained for archive-trail purposes but no longer constrained as UNIQUE NOT NULL; future records get a NULL.

10.5 Data Validation Strategy

• Row-count parity: for every SAROC sync cycle, the consumer compares SELECT count(*) FROM open_item WHERE created_at > ? against the file-watcher's emitted-event count for the same window. Mismatch fires an alert + halts apply until reconciled.
• Checksum parity: per-record SHA-256 over the canonicalized field set; embedded in the SAROC envelope; consumer verifies before commit.
• BR-PAY-002 MOD-11 re-verification: every supplier_code insert re-runs the check-digit calculation server-side, regardless of source.
• Type+status filter (BR-PAY-003) negative test: nightly job asserts no records with type IN (1, 3) ever made it into a posted-payment proof report.
• Spot-sample reconciliation: for 1% of payments at random, the SAROC consumer fetches the legacy purch-current via the bridge and compares against the target's running balance projection.

10.6 Rollback Procedures

• During SAROC dual-write: the modern side is non-authoritative, so a "rollback" is simply turning off SAROC consumer application and clearing the target tables. Legacy ISAM files are untouched.
• After cutover: the legacy COBOL system remains deployable in read-only mode for ~6 months. If a critical defect surfaces, SAROC reverses direction (modern is the source, legacy is the consumer) using a per-record export to ISAM via cobcrun writer programs.
• Schema rollback: Alembic down revisions are tested before each deploy; payment-schema-migrations task supports forward / backward.
• Audit preservation: the immutable payment_audit JSONB chain is preserved across any rollback; a "rollback" is itself an audit event.

10.7 Performance Considerations

• Indexes added beyond legacy keys: idx_open_item_type_status partial index (WHERE status = 0) makes BR-PAY-003 proof-sort O(log N) on the active subset rather than O(N) full-scan; idx_payment_batch serves the batch-dashboard hot path.
• Read replica routing: payment-reporting service reads from a PostgreSQL read replica for aged-creditor reports; writer is reserved for hot-path operations.
• Connection pooling: SQLAlchemy application-side pool (per resolved targetPatterns.connectionPooling = true); 20 connections per Fargate task, scales horizontally with task count.
• Batch size: the SAROC consumer applies events in batches of 50 with one COMMIT per batch; reduces lock contention versus per-event commit.

10.8 Data Mapping Summary

10.9 Schema Migration Design Rules

Two-layer rule set: Universal Rules apply regardless of target database engine; Engine-Specific Rules show implementation details for PostgreSQL/Aurora, DynamoDB, and MongoDB/DocumentDB. For ACAS run-012 the target is PostgreSQL (per report-plan.json.architecture.databaseEngine = postgres), so the PostgreSQL column in the engine-specific table is the active one; the other columns document portability for future projects.

Universal Rules

Engine-Specific Rules

Section 10 is the contract between this planning workflow and the artifact-generation workflow. The migration-artifacts agents reference it for every data model decision.

For the overall modernization execution plan including phased cutover, dual-write implementation, and rollback procedures, see Section 11: Modernization Strategy.

11. Modernization Strategy

Sections 4 and 10 define what the target architecture looks like and how data maps from legacy ISAM into PostgreSQL. This section defines how the transition happens: the chosen coexistence pattern, the EIP building blocks of the bridge between legacy and modern, the cutover choreography, why ordering and idempotency are non-negotiable for a financial ledger, and the operational controls that govern the queue once it is running.

11.1 Why SAROC Fits ACAS Payment Processing

The legacy-coexistence skill defines three admissible coexistence patterns and one decision tree for picking among them:

Does the source have a request-routing surface (LB, API gateway, reverse proxy)?
├── No  →  SAROC
└── Yes →  Are writes idempotent and is divergence acceptable for short windows?
           ├── No  →  Classical strangler fig (route reads first, then writes)
           └── Yes →  Symmetric dual-write

Applied to ACAS Payment Processing: the legacy interaction surface is a green-screen COBOL terminal application. Users interact directly with ACCEPT and DISPLAY statements in programs such as pl080.cbl, pl085.cbl, pl100.cbl, and pl960.cbl, presented through GnuCOBOL's screen runtime on an 80×24 terminal. There is no load balancer, no API gateway, no reverse proxy, and no HTTP request path of any kind. Both classical strangler-fig (which requires a request-routing surface to fork) and symmetric dual-write (which requires the legacy and modern systems to both accept writes through a common gateway) are structurally ruled out — not preferred against, but impossible to implement — because the routing layer they depend on does not exist.

SAROC is the remaining branch and the one that fits the system's actual shape. Its mechanism is to passively observe data-plane mutations on the legacy storage tier through Change Data Capture, translate them into ordered domain events, and replay them into the modern system. The legacy COBOL application is never modified, intercepted, or wrapped; the CDC adapter only reads. This is exactly the affordance required to modernize a green-screen system without rewriting the legacy code or coordinating a downtime window.

Pattern parameter declaration (from report-plan.json)

The full coexistencePattern block driving Sections 4 and 11 of this report — and the mig-coexistence-bridge agent in the artifacts workflow:

11.2 EIP Notation Diagram of the Bridge

Whatever the coexistence pattern, the bridge between legacy and modern always decomposes into four functional roles from Hohpe & Woolf's Enterprise Integration Patterns (2003). Figure 11.1 shows the four roles for the ACAS SAROC bridge in canonical EIP notation, with the legend at the bottom matching the iconography on every component.

Figure 11.1 — Reliable Message Queue Pattern (EIP component view). Each shape encodes pattern intent: the rounded-rectangle Channel Adapter reads the legacy ISAM files without modifying them; the chevron Message Translator decodes COBOL copybook records (COMP-3 packed decimal, PIC X fields, BINARY-LONG dates) into JSON domain events shaped per the sage-domain-event-v1 envelope; the pill Message Channel is a RabbitMQ topic exchange providing FIFO ordering, persistence across broker restart, and consumer-ACK at-least-once delivery, with a dead-letter queue catching poison messages; the rounded-rectangle Message Endpoint is the background-thread consumer inside the modern FastAPI service, applying each event idempotently to PostgreSQL.

Independence of the four components is the lever that makes the same pattern reusable across very different legacy estates. If a future modernization needs to bridge from a SQL Server source instead, the Channel Adapter becomes a Debezium connector and the Translator switches from copybook to row-shape decoding — the Channel and Endpoint shapes are unchanged. If the messaging substrate moves from RabbitMQ to AWS SQS FIFO for a Lambda-hosted modern stack, only the Channel changes. The pattern is the contract; the components are interchangeable.

11.3 Cutover Choreography

SAROC's defining property is that data flows from legacy to modern via two distinct paths — a one-shot bulk ETL of the historical snapshot, and an ongoing replay of the mutations that occur while that ETL is running and afterwards. Figure 11.2 shows the topology view (the parts and how data moves between them); Figure 11.3 shows the temporal view (when the steps happen and in what order); the step-details table after the diagrams makes the per-step state explicit.

Figure 11.2 — SAROC topology view. Path 1 (bulk ETL, red) loads the historical data snapshot — legacy continues to run while the modern consumer is OFF. Path 2 (change replay, green) drains the message queue after the ETL completes; idempotent application against the loaded snapshot brings the modern PostgreSQL store into convergence with legacy. The center callout is the trick that makes the pattern work: the queue accumulates every legacy mutation during the bulk load, then plays them back in order against the loaded state.

Figure 11.3 below shows the same flow on a time axis — who talks to whom, and when.

sequenceDiagram
    participant U as Users
    participant L as Legacy ACAS
    participant CDC as CDC Adapter
    participant Q as Ordered Message Queue
    participant ETL as "ETL / Bulk Load"
    participant M as Modern System
    participant DB as PostgreSQL

    Note over U,DB: Step 1 — Activate CDC Bridge
    U->>L: Continue normal operations (green screen)
    L->>CDC: CDC observes data mutations
    CDC->>Q: Queue ordered domain events
    Note right of Q: Queue begins accumulating
mutations from this point forward

    Note over U,DB: Step 2 — Take Point-in-Time Snapshot
    Note over L: Snapshot of legacy ISAM files
(consistent read / quiesce window)
    L-->>ETL: Extract snapshot

    Note over U,DB: Step 3 — Bulk Migration (consumer OFF)
    Note over M: Consumer is OFF — messages accumulate
    ETL->>DB: Load snapshot into PostgreSQL
    Note over L: Legacy continues processing
New transactions queue in order
    Note right of Q: Queue grows during
bulk load (minutes to hours)

    Note over U,DB: Step 4 — Start Consumer, Replay Queue
    M->>Q: Consumer connects
    Q->>M: Replay queued events (FIFO order)
    M->>DB: Apply each mutation sequentially
    Note right of Q: Queue drains to zero

    Note over U,DB: Step 5 — Verify Synchronization
    Note right of DB: Reconciliation check:
record counts, checksums,
batch totals, GL balances

    Note over U,DB: Step 5b — Side-by-Side Coexistence (indefinite)
    U->>L: Users continue on COBOL / ISAM
    L->>CDC: CDC captures every transaction
    CDC->>Q: Ordered events (real-time)
    Q->>M: Consumer applies to target
    Note right of DB: Both systems in sync
Duration is a business decision

    Note over U,DB: Step 6 — User Cutover (when business is ready)
    U->>M: Users directed to modern web UI
    Note over L: Legacy interface retired
    Note over CDC: CDC bridge stopped
    Note over Q: Queue drained and removed
        

Figure 11.3 — SAROC cutover sequence (temporal view). The seven labelled phases (Steps 1, 2, 3, 4, 5, 5b, 6) interleave actor interactions over a timeline that runs vertically. The two paths from Figure 11.2 show up here as Step 3 (Path 1, the ETL load) overlapping with Steps 1–3 (Path 2, the CDC adapter filling the queue), and Step 4 (Path 2 draining into the modern store) running after Path 1 completes.

Step Details

11.4 Why Ordering and Idempotency Matter for ACAS

Two of the six verified Payment Processing business rules from Concho cycle 8 make ordering and idempotency non-negotiable for the SAROC bridge: PaymentBatchControlLimits (confidence 0.75, source purchase/pl080.cbl:733) and PaymentReversalProcessing (confidence 0.60, source pl085 / sl085).

Worked example: a 99-item batch followed by a reversal

PaymentBatchControlLimits caps each payment batch at 99 items with sequential numbering. A batch is opened, items are added with monotonically increasing sequence numbers within the batch, then the batch is proofed (P-Flag-I = 2, per PaymentPostingValidation) and posted. Posting writes payment records into pay.dat, open-item updates into openitm5.dat, and GL postings via the overnight cycle in pl100. PaymentReversalProcessing then allows an amendment to reverse the appropriations and redistribute amounts across related invoices with an audit trail in pl085.

Suppose an operator opens batch BATCH-0042, adds 99 payment items in sequence (BATCH-0042/001 through BATCH-0042/099), proofs the batch, and posts it. A few hours later, a single item — say BATCH-0042/057 — needs reversal because the supplier code was wrong. The operator runs the pl085 amendment flow, which reverses the appropriations for item 057 and redistributes the amount across the corrected supplier's open items.

Now consider what each delivery property guarantees about the bridge replay:

Reversal compounds the problem because the pl085 amendment touches the same set of open items the original batch touched. If the original-batch events and the reversal events interleave incorrectly during replay, the open-item balances in modern PostgreSQL diverge from legacy ISAM — and at that point the SAROC contract is broken: modern is not legacy. A reconciliation check at Step 5 will catch the divergence, but the recovery is to re-run Path 1 (drop and reload), not a surgical fix.

11.5 Proof-of-Concept Results

A working SAROC bridge for ACAS has been implemented and exercised end to end. The implementation lives under projects/acas-payment-processing/strangler-bridge/ in the modernization repository, plus the per-target deployment under migration-artifacts/migration-artifacts-acas-docker-006/. Results below are qualitative — throughput, latency, and queue-depth measurements were not captured in a controlled benchmark and are not reported here.

What was built and verified

End-to-end scenarios exercised

1. Real-time bridge. Open ACAS in one terminal, the bridge watcher in another, the RabbitMQ management UI in a browser, and the modern web UI in another browser tab. Entering a payment through pl080 on the green screen produces a message in the RabbitMQ queue, the consumer ACKs it, and the payment with its allocations and GL postings appears in the modern UI — all without touching the legacy COBOL code. Walkthrough script: strangler-bridge/DEMO-INSTRUCTIONS.md; live demo script: strangler-bridge/saroc-live-demo.sh.
2. Deferred replay (SAROC Steps 3–4). The consumer was disconnected to simulate the bulk-migration window; payments entered in ACAS accumulated in the queue (visible as growing depth in the RabbitMQ management UI); the consumer was reconnected and drained the backlog; every payment was applied against the freshly loaded snapshot data in the correct sequence.
3. Idempotent replay. The same message was re-delivered to the consumer; the second delivery upserted against the natural-key constraint without producing a duplicate payment row or duplicate GL postings.
4. Demo reset script. migration-artifacts-acas-docker-006/setup-demo.sh resets both the Docker-side PostgreSQL and the legacy ACAS data, purges RabbitMQ queues, and reseeds a known supplier (ACME001) on both sides, providing a repeatable starting point for between-walkthrough runs.

11.6 Operational Considerations

Section 4’s observability declarations are the source of truth for thresholds; the values below align with those decisions (structlog JSON, OpenTelemetry traces and metrics, CloudWatch & X-Ray exporters via the ADOT sidecar, RFC 7807 error responses, exponential-backoff retries).

Dead-letter queue (DLQ) behavior

• Every bridge queue has a paired DLQ (messaging.deadLetter = true). A message that exceeds its retry budget — default 5 retries with exponential backoff — is moved to the DLQ rather than blocking the live queue.
• DLQ messages preserve the full sage-domain-event-v1 envelope plus an x-dead-letter-reason annotation identifying the failure mode (parse error, FK violation, idempotency conflict).
• The operator runbook for the DLQ is binary: fix the consumer or fix the data, then either replay from the DLQ back to the live queue or drop the messages after reconciling against legacy. A poisoned message is never silently discarded.

Queue-depth alert thresholds

Concrete thresholds are deliberately tied to the cutover phase the system is in — what is healthy during Step 3 (bulk-load backlog) is alarming during Step 5b (steady-state coexistence).

Consumer lag SLO

• Steady-state SLO: P50 consumer lag ≤ 2 s, P99 ≤ 10 s, measured from CDC detection timestamp on the event envelope to consumer-ACK timestamp.
• Drain SLO (Step 4): backlog drained within the smaller of (a) twice the bulk-load duration or (b) 30 minutes, whichever is smaller. Beyond that, the consumer is suspect — the runbook is to pause replay, root-cause via DLQ entries and consumer logs, and resume.
• Instrumentation: the consumer emits OpenTelemetry spans for every message processed (parent span carried via the event envelope’s correlation ID), and a gauge metric for current lag per queue. Both are routed through the ADOT sidecar to CloudWatch / X-Ray per Section 4’s observability stack.

Cutover rollback plan

12. How Concho Helped This Modernization Planning

This analysis demonstrates three distinct approaches: (1) Concho + Claude — Concho's pre-computed codebase intelligence consumed by Claude Code planning agents, (2) Claude Code Alone — analyzing the same codebase with only Read / Grep / Glob, without Concho's pre-analyzed knowledge graph, and (3) Traditional Manual Review — senior architects working through interviews, documentation, and selective code reading. Every comparison in this section includes all three columns so the value of Concho is visible relative to both AI-without-Concho and a human consulting baseline. The Applewood Computers Accounting System (ACAS) Payment Processing modernization plan was produced by an orchestrated workflow of 14 planning phases against Concho cycle 8; the numbers, file references, and confidence scores that appear throughout this report are quoted from that pre-analysis. This section explains what the Concho Analysis Engine made possible and what would have been infeasible without it.