# Gravity Migration — AI Reference

> **Status:** Draft 0.1, 2026-11-05. The condensed method for turning a mainframe estate into Gravity Standard specifications. Read it with the [Gravity Standard AI Reference](https://gravitystandard.com/gravity-standard.md), which it builds on and never overrides. Worked examples for every translation are in [tidewater-estate.md](https://gravitymigration.com/tidewater-estate.md).

## 0. How to use this reference

You are helping a person turn an existing IBM Z (z/OS) or IBM i estate into Gravity Standard specifications. Your output is specifications and evidence, not translated code.

- Follow every MIG rule below and every rule in the Gravity Standard reference. If they appear to conflict, the Standard wins and you raise the conflict with a person.
- You may read, extract, and propose. A person confirms each claim and decides each difference.
- Must not build on a guess. An unanswered question goes under `Open questions` in the spec's Notes, and whatever depends on it waits (CONV-047).

## 1. What it is

The estate is the only complete record of how the business really works, so its mass is useful. A gravity assist uses a massive body's pull to gain speed without burning fuel. Gravity Migration uses decades of encoded behavior to produce a specification faster and more accurately than interviews alone could.

**Central idea:** migrate the behavior the business needs, not the components that happen to deliver it. Nothing is translated one-for-one.

**The chain:** Artifact → Evidence → Rule → Test → Proof.

**What it is not:** not a code converter, not a rehosting method, and not a promise that everything moves. Gravity Standard's SCOPE-001 stands: it does not hold ledger-class data, such as balances. An estate's ledger stays where it is or moves to a product, so **this method alone won't get most core systems off the mainframe**: the machine stays on until the ledger has a home.

## 2. Glossary

| Term | Meaning |
|---|---|
| Estate | Everything the existing platform does: programs, data, jobs, messages, screens, grants, reports, and people's habits |
| Artifact | A real source object, such as a copybook, a COBOL paragraph, a JCL step, a RACF profile, or a job log |
| Capability | Something the business needs done, stated without reference to the system that does it |
| Disposition | The recorded fate of a capability: move, retain, replace, or retire |
| Evidence entry | `EV-nnn`: one claim about what the system does, with its source and a confirmation status |
| Rule | A Gravity Standard rule, `<CODE>-<nnn>`: one plain, testable sentence stating an outcome |
| Parallel run | The old and new systems process the same captured or live inputs, and their outcomes are compared |
| Shadow environment | An environment with production-grade protection and no route to any real system, partner, or person, where a parallel run happens under a Production permit that names only `shadow` |
| Difference | `DIFF-nnn`: a compared outcome that doesn't match, with one classification and one named decider |
| Authoritative record | Data the Standard may hold as the only source once a system retires, decided by its business owner and data steward |
| Ledger-class data | Data where its value accumulates from many postings rather than being recorded as a fact; someone outside the team must be able to reconstruct its value as of a past date, including corrections recorded later; or a wrong value can only be caught by reconciling against an independent control total (SCOPE-001) |
| Slice | The smallest piece that can be cut over and reversed on its own |

## 3. Chapters and what each produces

| # | Chapter | Question | Produces |
|---|---|---|---|
| 1 | Survey | What do we have, and what is its fate? | Inventory, usage evidence, disposition per capability |
| 2 | Evidence | What does it actually do? | Evidence ledger with confirmed claims |
| 3 | Data | What is true, and who owns it? | Domains, record types, field mapping |
| 4 | Rules | What must stay true? | Numbered rules, open questions |
| 5 | Processes | What happens, and when? | Process specs, integration choices |
| 6 | Access | Who may do what, and why? | Actors, skills, access rules |
| 7 | Screens | What do people need to get done? | Task specs and speed baselines |
| 8 | Proof | How do we know it's right? | Rule tests, parallel-run results, decided differences |
| 9 | Cutover | How do we move safely? | Slice plan, one-writer plan, rehearsed rollback |

## 4. The rules

### Survey
- **MIG-001:** Every production artifact in scope appears in the inventory with a named owner, or with "no owner" stated.
- **MIG-002:** Whether something is alive is decided by usage evidence covering a full business cycle, not by its presence in a library.
- **MIG-003:** Every capability has exactly one recorded disposition: move, retain, replace, or retire.
- **MIG-046:** Each report that survives has its route recorded, and the method prescribes no reporting product.
- **MIG-004:** Ledger-class data stays off the Standard, so it is retained or replaced; any other data becomes authoritative there only by the recorded decision of its business owner and data steward.

### Evidence
- **MIG-005:** Every proposed rule cites at least one evidence entry.
- **MIG-006:** A claim extracted by an AI stays `proposed` until a named person confirms it.
- **MIG-007:** Evidence records what the system does; only a person decides whether it should keep doing it.
- **MIG-008:** Where sources disagree, production behavior is the evidence of what happens, and the disagreement becomes an open question.

### Data
- **MIG-009:** Every source field maps to a typed, classified field or is recorded as dropped with a reason.
- **MIG-010:** A source field holding more than one meaning becomes separately named fields, each with its own type and class.
- **MIG-011:** Special values such as all nines, spaces, or zero dates are given stated meanings and never carried forward as magic values.
- **MIG-012:** Every record type's tenant boundary is identified from the data and confirmed by a person, never assumed.
- **MIG-013:** Converted data reaches a domain only through a validated commit step, and each load reconciles by record count and control total.
- **MIG-045:** The data migration strategy records, for each record type, whether it comes in as a transferred record or keeps its history, based on whether the future system needs that history, and it preserves whatever that history depends on.
- **MIG-043:** Which records convert is a recorded decision for each record type, and records that don't convert stay in a readable archive.

### Rules
- **MIG-014:** A rule states the business outcome and never names the paragraph, step, or program it came from; that link belongs in the evidence ledger.
- **MIG-015:** Every calculation rule states its precision, rounding, and order of operations exactly.
- **MIG-016:** A hard-coded customer, date, or code value becomes a tenant parameter, a stated rule, or a retired behavior, by a recorded decision.
- **MIG-017:** A capability marked replace still gets rules, because they become the acceptance test for the product.
- **MIG-039:** A behavior deliberately not carried forward is recorded in the spec's Out of scope section, so the decision outlives the evidence ledger.

### Processes
- **MIG-018:** A batch job is specified by its business purpose and its deadline, not by its sequence of steps.
- **MIG-019:** An ordering between jobs is kept only where a data dependency is shown.
- **MIG-020:** Restart and rerun procedures become idempotent stages, with progress visible while they run.
- **MIG-021:** Every message flow uses one pattern from the Standard's integration list, or a recorded design decision.
- **MIG-042:** A job that stays bulk becomes a scheduled process that runs in chunks and declares its volume, with its business calendar in the first stage.
- **MIG-040:** Every posting to a retained system is a documented process stating what the business does when the target accepts, refuses, or does not answer.

### Access
- **MIG-022:** Source security grants are evidence of what was permitted, never a specification of what should be.
- **MIG-023:** Every access rule names an actor and a business reason.
- **MIG-024:** A source grant with no evidence of use across the business cycle is not carried forward without a person's approval.
- **MIG-041:** A shared technical ID or file-transfer credential is not carried forward; each outside system proves itself through a registered identity provider.

### Screens
- **MIG-025:** A screen is specified by the task it serves, not by its layout.
- **MIG-026:** A high-volume task's time on the terminal is measured, and its replacement is accepted against that number.
- **MIG-027:** Data that a source transaction committed together is stated as a rule about what succeeds or fails together.
- **MIG-028:** A rule found only in a user interface is restated in a spec, so that every path into the system obeys it.

### Proof
- **MIG-029:** Every rule has a rule test that cites its ID, and rules in moved capabilities are also checked against captured production cases.
- **MIG-030:** A parallel run covers at least one complete business cycle, including the period-ends that matter to the business.
- **MIG-031:** Every difference gets exactly one classification and a named decider.
- **MIG-032:** An unexplained difference blocks cutover of the slice it belongs to.
- **MIG-033:** Captured production data keeps its classification and production-grade protection wherever it is used.
- **MIG-038:** A parallel run on real data happens only in a shadow environment, which holds a Production permit naming only that environment and can't reach any real system, partner, or person.

### Cutover
- **MIG-044:** Each slice names its in-flight work, and a process starts that work as of the moment the new system takes over.
- **MIG-034:** Each slice is the smallest piece that can be cut over and reversed on its own.
- **MIG-035:** Each piece of data has exactly one writer at any moment, and the cutover plan names that writer.
- **MIG-036:** Rollback is rehearsed, including what happens to data written after cutover.
- **MIG-037:** The source is decommissioned only after its retention obligations are met and a read-only period has passed with no need to return.

## 5. Translation table

| Source | Extract as | Gravity Standard target | Classic trap |
|---|---|---|---|
| COBOL, PL/I | Rules, plus logic specs can't express | Rule enforcement kinds; hand-written Go where the kind is `code` | Truncation and packed-decimal arithmetic |
| RPG, CL | Rules, plus logic specs can't express | Same | Indicators and logic in file-level definitions |
| Java on the platform | Rules and API contracts | Synchronous APIs, Go handlers | Behavior in app-server config |
| MQ | Who talks to whom, and why | SQS, EventBridge or SNS, or the outbox, by need | Hidden order dependencies; full records in messages |
| Flat files, VSAM | Record types | Postgres domains; object data in S3 | REDEFINES and magic values |
| Db2 | Domains, statuses, constraints | Postgres with row level security | EBCDIC sort order; rules in stored procedures |
| RACF, IBM i object authority | Actors, skills, access rules | Generated Verified Permissions policies, RLS | Stale grants; shared technical IDs; no tenant boundary |
| CICS, 3270, 5250 | Tasks and transaction boundaries | Task forms, htmx, server-side rendering for restricted data | Keystroke speed; pseudo-conversational state |
| Web interfaces | Tasks, API contracts, UI-only rules | htmx screens, server-enforced rules | Rules that exist only in the browser |
| JCL, CL, schedulers | Purpose and deadline | A process with a timer; for true bulk, a scheduled process in chunks with a declared volume | Implicit ordering; rules in sort cards |
| Postings to a retained system | Direct and indirect rules | A documented process, compiled to Step Functions | Double-posting from a retry after a timeout |
| Existing records | What converts, and exceptions | A process in the writing application, in chunks, starting no work | Loading records that trigger real notices; forgetting in-flight work |
| Partner system access | Actors, providers, tenant roles | A registered identity provider and a role in one tenant | Standing access across every bank |
| Partner file exchange | Partners and formats | OIDC sign-in and presigned upload into quarantine, one ingestion sub-process per format | Silent repairs; writing directly to domains (DATA-025) |
| Reports and print | Who acts on what | A task, a screen, the company's reporting tool, a scheduled document, or retirement | Reports nobody reads |
| Code tables | Choices and parameters | `choice(...)`, tenant parameters | Meaning that lives in a shared table |
| Archives and audit | Retention obligations | `Retention:` headers, archive plan | Tapes nobody can read after decommissioning |

## 6. Where migration work lives

Specs stay clean. Everything about the source lives beside them, and can be deleted when the source is gone:

```
domains/ and apps/          Gravity Standard specs, unchanged in form
migration/
  survey/inventory.md       artifacts, owners, usage
  survey/dispositions.md    capability, disposition, decider, reason
  data-strategy.md          what converts, and transferred or history kept
  evidence/<spec>.md        EV-nnn entries for one spec
  differences/DIFF-nnn.md   one per difference
  slices/<slice>.md         one per cutover slice
```

A rule cites no source. An evidence entry cites both its artifact and the rule it supports (MIG-014).

## 7. How an AI assistant works on an estate

1. **Inventory** artifacts and pull usage evidence. Report what you could not read.
2. **Propose dispositions** with reasons. A person decides.
3. **Extract claims** into the ledger as `proposed`, each citing its artifact and lines. Look beyond the main program: sort cards, config files, stored procedures, code tables, and scheduler definitions.
4. **Confirm:** ask a person about each claim in business terms, most consequential first. Never ask how to build (CONV-002).
5. **Write specs** in the Standard's templates, using its type catalog and classes. Say what the data means, not how it was stored. Record what's deliberately left behind under `Out of scope` (MIG-039).
6. **Compile** by the Standard's normal route: spec, definition, implementation, rule tests.
7. **Compare:** in the shadow environment (MIG-038), run captured cases, list differences, propose a classification for each, and leave the decision to the named decider.

Never restate platform rules, such as tenant isolation or audit history, in a spec (CONV-017).

## 8. Differences

| Classification | Meaning | Action |
|---|---|---|
| Regression | The new build is wrong; the rule was already clear | Fix the build |
| Kept quirk | The old behavior is odd, but the business keeps it | Sharpen the rule to say so |
| Fixed defect | The old behavior was wrong, and the business won't keep it | Change the rule; plan any remediation of past results |
| Discovered rule | The behavior is right, and the spec never said so | Add the rule, its evidence, and its test |

Filters that hide comparison noise, such as timestamps, are themselves recorded decisions.

## 9. Templates

Published at `/templates/`: `survey-sheet.md`, `evidence-entry.md`, `rule-card.md`, `difference-report.md`, `cutover-slice.md`.

## 10. Questions settled with the Standard

Writing this method raised nine questions for Gravity Standard. All are now resolved there, under these numbers, and the Standard wins if anything here differs.

| ID | Question | Answer | Where |
|---|---|---|---|
| QUESTION-016 | The hand-off to a retained system | A documented process with direct and indirect rules | Architecture 6.4, CONV-049 |
| QUESTION-069 | The system-of-record non-goal | Authoritative records may move; ledger-class data stays out | SCOPE-001, BACKLOG-005 |
| QUESTION-070 | Long-running bulk work | A process that an EventBridge schedule starts, in chunks, with declared volume | Architecture 6.4, CONV-051, PERMIT-082 |
| QUESTION-071 | Authentication across organizations | Named identity providers and a role in one tenant; OIDC is the minimum | Architecture 8.9, CONV-050, PERMIT-081 |
| QUESTION-072 | Bulk conversion of existing records | A process in the writing application; a loaded record starts no work | DATA-037, CONV-052 |
| QUESTION-073 | History of converted records | A design decision per record type, in the data migration strategy | DATA-038 |
| QUESTION-074 | Operational reporting | No prescribed solution; each report picks its route | SCOPE-007, Architecture 5.7 |
| QUESTION-075 | Permits for parallel runs | A Production permit naming only `shadow`; production takes a new permit | Architecture 10.2, PERMIT-079, PERMIT-080 |
| QUESTION-076 | Reserved prefixes | `MIG`, `EV`, and `DIFF` are reserved | CONV-012 |

## 11. Platform dialects

| Concern | z/OS | IBM i |
|---|---|---|
| Languages | COBOL, PL/I, Assembler | RPG, CL, COBOL |
| Records | VSAM, sequential datasets, copybooks | Physical and logical files, DDS |
| Relational | Db2 for z/OS, sometimes IMS | Db2 for i, integrated with the OS |
| Batch | JCL, JES, an enterprise scheduler | CL, job queues (`SBMJOB`), job scheduler; `WRKACTJOB` shows active jobs |
| Messaging | IBM MQ | IBM MQ, data queues |
| Security | RACF, ACF2, or Top Secret | User profiles, object authority, adopted authority |
| Terminals | 3270, BMS maps in CICS, or IMS | 5250, DDS display files |
| Usage evidence | SMF records, scheduler history | `QHST`, job logs, audit journal `QAUDJRN` |

Both use EBCDIC by default, and both need decimal arithmetic checked carefully.

## 12. Reference estate: Tidewater

Tidewater is the fictional lender from Gravity Standard. Its legacy estate is **Anchor Core** (z/OS: COBOL, CICS, Db2, VSAM, MQ, RACF), **BankLink** (a Java portal for partner banks), and **KeelTrack** (IBM i: RPG, inherited with an acquired servicer). Anchor Core's ledger is retained, consistent with the Standard. The workflow around it moves into Tidewater's Payments and Lending applications. All programs, numbers, and incidents are invented. See [tidewater-estate.md](https://gravitymigration.com/tidewater-estate.md).