COBOL integration patterns for enterprise AI agents — Reference Architecture

Reference architecture · published 2026-10-16 · regulated enterprise · SOC 2 Type II · layout troubleshooting · implementation executed in CI before publish

The control that resolves this is an Idempotent System-of-Record Bridge, evaluated before the request reaches a model provider rather than audited afterwards. In regulated enterprise the binding constraint is SOC 2 Type II, and the question it actually asks is did this control operate effectively for the whole observation window. The specific problem here is COBOL / mainframe batch. The shape below holds p95 ≤ 2400ms over durable queue (SQS / Kafka) with an outbox, and ships with a standard-library implementation that runs as written.

The architecture friction point

Agents can read the legacy estate and cannot safely write to it. A retry after a gateway timeout creates a duplicate posting, and in an ERP a duplicate journal entry is a finance incident. So the team that owns the system of record withholds write access, and the automation stalls at read-only.

What makes COBOL / mainframe batch specifically hard

The system of record runs COBOL batch on a fixed window. There is no API to call: work arrives as a dataset, is processed in a job step, and the result exists only when the window closes. An agent that expects request/response semantics has nowhere to attach.

What resolves it is a file-level contract with a processed-ledger and a reconciliation step. The failure to design against: a partial dataset processed as complete because the transfer finished but the job had not.

What SOC 2 Type II specifically requires

SOC 2 Type II is not a point-in-time assertion. The auditor samples evidence across a 3-12 month observation window and asks whether the control operated on every day of it, not whether it exists today.

The artifact that satisfies it is a sampled, time-ordered population the auditor can draw from. The way teams most often fail it: the control was added mid-window, so the population has a hole and the observation period restarts.

What the auditor will ask

• Show me the control-execution population for the full window, and the days where it is empty.
  Every request emits an execution record, so the population is continuous by construction. A gap is an alertable incident, not something discovered during the audit.
• A transfer is interrupted halfway. What stops the batch being processed as if it were complete?
  Every file carries a trailer with its row count and content hash. A file that does not reconcile is quarantined rather than partially applied, and the ledger records the rejection.
• If the gateway times out and the agent retries, how many documents exist — and what proves it?
  One. The idempotency key is derived from the business keys, so both attempts collide on the same claim; the retry observes the completed claim and replays the original result. The transport is invoked once, which the test asserts.
• Which exact fields may an agent write per document type, and what happens to a field outside that list?
  Only the fields in that document type's allow-list, and all of them — the projection rejects both unknown fields and incomplete payloads. A field outside the contract raises rather than posting hopefully.
• What does the system-of-record owner see when a posting is wrong, and what reverses it?
  The reconciliation job compares posted documents against recorded intents and surfaces drift; each writable document type has a defined, rehearsed compensating action for reversal.
• Where is the intent recorded before the transport call, and what resolves a mid-flight crash?
  In the outbox, written before the transport call. On restart, reconciliation resolves anything left in flight, so a crash leaves a recoverable state rather than an ambiguous one.
• Is the extract pulling the minimum field set, with a justification per field?
  It should be — projection applies on read as well as write, with a recorded justification per field, so the extract schema matches the documented minimum field set.

Technical parameters

Every value below is a parameter you can hold a vendor or an internal team to. Adjectives are not acceptance criteria.

The implementation — Trailer-reconciled batch ingest

Standard-library Python, no external dependencies, runs as written. Executed by the publish gate: if it raises, this page does not ship. Wire it behind durable queue (SQS / Kafka) with an outbox; the failure mode it guards against is a consumer crash between side effect and acknowledgement. The output you hand the assessor is the observation-window evidence export.

"""Trailer-reconciled batch ingest for a COBOL system of record.

Why this shape: a mainframe batch hands you a dataset, not a response. The
failure that costs money is a TRUNCATED file processed as a complete one --
the transfer succeeded, the job had not finished writing, and you just posted
60% of a day's transactions as if that were the whole day.

The control is a trailer record carrying the expected row count and a content
hash. A file that does not reconcile is quarantined whole; it is never
partially applied, because a partial apply is the thing you cannot unwind.
"""
import hashlib
from dataclasses import dataclass, field


class Unreconciled(Exception):
    """The file does not match its own trailer. Quarantine, never apply."""


@dataclass(frozen=True)
class Trailer:
    rows: int
    sha256: str
    business_date: str

    @classmethod
    def parse(cls, line: str) -> "Trailer":
        # Fixed-width, as the copybook defines it. Positions are the contract.
        if not line.startswith("TRL"):
            raise Unreconciled("last record is not a trailer: file truncated")
        try:
            return cls(rows=int(line[3:12]), sha256=line[12:76].strip(),
                       business_date=line[76:84])
        except ValueError as e:
            raise Unreconciled(f"malformed trailer: {e}") from e


@dataclass
class ProcessedLedger:
    """Stands in for a real table. In production this is a row committed in
    the same transaction as the apply, so a crash cannot double-apply."""
    seen: dict = field(default_factory=dict)

    def claim(self, digest: str, business_date: str) -> bool:
        key = (digest, business_date)
        if key in self.seen:
            return False
        self.seen[key] = "in_flight"
        return True

    def complete(self, digest: str, business_date: str, rows: int):
        self.seen[(digest, business_date)] = f"applied:{rows}"


def reconcile(records: list, trailer_line: str) -> Trailer:
    """-> Trailer, or raise. Both checks matter and neither is redundant:
    the count catches truncation, the hash catches silent corruption."""
    trailer = Trailer.parse(trailer_line)
    if len(records) != trailer.rows:
        raise Unreconciled(
            f"row count {len(records)} != trailer {trailer.rows} "
            f"-- file is truncated or padded")
    body = "\n".join(records).encode()
    digest = hashlib.sha256(body).hexdigest()
    if digest != trailer.sha256:
        raise Unreconciled("content hash mismatch -- file corrupted in transit")
    return trailer


def ingest(records: list, trailer_line: str, ledger: ProcessedLedger,
           apply_fn) -> dict:
    trailer = reconcile(records, trailer_line)
    digest = trailer.sha256
    if not ledger.claim(digest, trailer.business_date):
        # Re-delivery of a file already applied. Mainframes resend; that is
        # normal, and the correct response is to do nothing.
        return {"status": "already_applied", "rows": 0,
                "business_date": trailer.business_date}
    applied = apply_fn(records)
    ledger.complete(digest, trailer.business_date, applied)
    return {"status": "applied", "rows": applied,
            "business_date": trailer.business_date}


if __name__ == "__main__":
    rows = [f"DTL{i:09d}000000{i * 7:08d}" for i in range(1, 251)]
    body = "\n".join(rows).encode()
    good = f"TRL{250:09d}{hashlib.sha256(body).hexdigest():<64}20261016"

    ledger = ProcessedLedger()
    print("complete file :", ingest(rows, good, ledger, lambda r: len(r)))
    print("re-delivery   :", ingest(rows, good, ledger, lambda r: len(r)))

    try:                                    # the expensive failure
        ingest(rows[:150], good, ProcessedLedger(), lambda r: len(r))
    except Unreconciled as e:
        print("truncated file:", e)
    try:
        tampered = list(rows)
        tampered[7] = "DTL000000008000099999999"
        ingest(tampered, good, ProcessedLedger(), lambda r: len(r))
    except Unreconciled as e:
        print("corrupted file:", e)

System architecture

Idempotent System-of-Record Bridge — the request path, with the decision points that must exist before the first model call:

flowchart LR
    AG[Agent] --> PR[Projection<br/>allow-listed fields]
    PR -->|unknown field| REJ[Reject - loud]
    PR --> IK[Idempotency key<br/>sha256 of business keys]
    IK --> CL{Claim table}
    CL -->|already done| RP[Replay original result]
    CL -->|in flight| DUP[Refuse duplicate]
    CL -->|new| OB[(Outbox)]
    OB --> TR[Transport - OData / IDoc / RFC]
    TR --> SOR[(System of record<br/>SAP / ERP / AS400)]
    SOR --> RC[Reconciliation]
    RC -->|drift| CMP[Compensating action]

Controls and acceptance parameters

Each row carries an acceptance parameter rather than an adjective, because "low latency" cannot be signed off. Retention here is bound by per the data class retention schedule, enforced automatically.

Implementation components

1. Content-derived idempotency key — Derived from business keys, so two attempts at one intent collide.
2. Claim table — Transactional claim in the same database as the outbox; a retry observes the first attempt.
3. Typed write contract — Allow-listed fields per document type; unknown fields are rejected loudly.
4. Outbox — Durable intent record, so a crash mid-flight is recoverable rather than ambiguous.
5. Reconciliation job — Compares posted documents against intents and surfaces drift.
6. Compensating action — A defined reversal path per document type, because some writes must be undoable.

Observed in the field

This page exists because the problem is reported publicly. The threads below are the primary sources, linked unmodified and not affiliated with this site.

• AI migrated legacy COBOL programs to Java, bugs included hackernews · hn/comment · 2026-08-03
• AI helps break the cost barrier to COBOL modernization hackernews · hn/story · 2026-02-23
• Anthropic: AI helps break the cost barrier to COBOL modernization hackernews · hn/story · 2026-02-24
• AI's Role in Rescuing Legacy Systems – The COBOL Modernization Revolution hackernews · hn/story · 2025-07-02
• Rocket Software Expert on Modernizing and Securing COBOL Systems hackernews · hn/story · 2025-11-07
• Anyone tried Thoughtworks' new AI/works legacy modernization platform hackernews · hn/comment · 2026-01-21
• Launch HN: Hypercubic (YC F25) – AI for COBOL and Mainframes hackernews · hn/comment · 2025-11-10

Related reference architectures

• Part of legacy system integration with ai agents.
• Where this interacts with another regime, see legacy integration patterns for enterprise AI agents.
• A different failure mode of the same component: latency integration patterns for enterprise AI agents.
• If this is the blocker in front of you: enterprise AI infrastructure review.