What this is. The Lab has five NCR Atleos machines on its floor. This document says how
they are joined to the Virtual Financial Ecosystem Simulation, what is still unknown about
them, and the order the work goes in.

What this is not. It is not a statement of how an NCR Atleos works. **NCR's reference
manual for these machines has not been read**, no NCR document was consulted, and every
protocol value the scaffold carries is the Lab's reading of publicly circulating descriptions
of NDC - recorded as assumptions A-46, A-47 and A-48 in
[../spec/assumptions.md](../spec/assumptions.md) and overridable, machine by machine, from
nodes/floor/<machine>.yaml. Nothing here should be taken as describing what the machines on
the floor actually do until the inventory below is done.

---

Why a floor node exists at all

A real NCR self-service terminal does not decide anything. Its state tables say *"in this
state, send a transaction request and wait"*, and what happens next - which screen, which
device action, how much comes out of the cassettes - is decided by a host that owns those
screens and answers over NDC (NCR Direct Connect), on a TCP link.

The simulated ecosystem lives on Cloud Run, and Cloud Run cannot accept raw TCP. A Cloud
Run service is reached over HTTP(S) through Google's front end on the one port the container
declares; there is no second listener a machine can open a socket to, and nothing in the
service's configuration can publish one. The same paragraph is already in
[../deploy/README.md](../deploy/README.md) about the ISO 8583 listener, for the same reason.

So the Lab runs the same image twice:

The floor node is a participant of the cloud world, not a second world. It keeps no
ledger, settles nothing, and holds no state a restart would lose except the day's journal it
has not handed over yet. Everything a machine asks for is answered by the simulated switch in
the cloud, over /v1/atm/**, exactly as an integration calling those endpoints from a laptop
would be answered. The floor node adds a protocol, not a capability.

---

The research checklist

Nothing below is known yet. Each line is a question with an owner (Carlos), and each one
blocks something specific - which is why the list is a table and not a wish.

The VLAN is the security boundary, and that is a decision

There is no credential on the NDC link, and that is stated rather than omitted. An NDC
terminal has no field to carry a team key in and no notion of presenting one, so a listener
that demanded one would be a listener no machine can talk to.

What protects the link is the network it is on. The machines and the floor node sit on a
VLAN of their own; the floor node is the only thing on that VLAN that can reach the
internet; and the team key lives on the floor node, is presented by the floor node to the
cloud lane, and never travels on the machine link in either direction. Anything that can
reach the NDC port can drive a machine's screens, so the answer to "who may reach the port"
is "the machines, and nothing else".

On any link that leaves the floor, set NDC_TLS_CERT and NDC_TLS_KEY (and the ISO 8583
pair beside them). Plain TCP is the default because floor hardware often cannot do better and
a listener that refuses the machine is not a listener.

---

Assets the Lab already holds

3D renders and animations of the SelfServ 62, a Blender model of it, and realistic photographs exist and can be provided on request (Carlos, 2026-09-06). They are not in this repository. They serve the films, the public simulation page and a physical-layout rehearsal of the floor; they are not needed for the host, which only ever sees the machine's messages.

The four steps

The wire and NDC ride the same floor node. One box, one team key, two ports: NDC_TCP_PORT
for the machines that speak NDC and ISO8583_TCP_PORT for a machine or a POS on the same floor
that speaks ISO 8583 instead. That is not a convenience, it is the arrangement — both listeners
need raw TCP, Cloud Run carries neither, and a second box would mean a second team key, a second
journal to reconcile and two places to get the VLAN wrong. The ISO 8583 half has its own profile
([../spec/iso8583-wire.md](../spec/iso8583-wire.md)), its own sign-on and its own conformance
pack (npm run wire:conformance); everything below about the VLAN, the key file and the service
recipes applies to it word for word. The same pairing is what the Compute Engine recipe in
[../deploy/README.md](../deploy/README.md) stands up when the link has to leave the floor.

1. Inventory. Work the checklist above, machine by machine, and write what is found into
nodes/floor/<machine>.yaml - the dialect block for what the manual says, the pending list
for what is still open. No machine is put on the network in this step.

2. Floor node and host, driven by the virtual ATM and the virtual switch. *(This is what
exists today.)* The floor node runs, both listeners are up, and each is exercised by a
client-shaped test double that dials a real socket and sends real frames: NDC by
packages/ndc-host/test/virtual-atm.ts - which carries out the function id it is given and
reports back - and ISO 8583 by packages/iso8583-wire/test/virtual-switch.ts, which signs on,
authorizes, reverses, withdraws with a card and without one, and is answered by the same world
the REST lanes answer from. Both are proved before a machine exists, which is the only way to
arrive at step three with something worth plugging in.

3. The first no-cash transaction, on ONE machine. One machine, on the VLAN, dialling the
floor node. Balance inquiry only: it reads an account, prints a figure, moves nothing and
dispenses nothing. It is the safest transaction that exists and the right first thing to run
on a machine whose supervisor access and journal have only just been understood. What is
being proved here is the link and the dialect, not the ecosystem - the ecosystem has been
answering these operations over REST for months.

4a. Cardless withdrawal with test notes. The one-time code the holder's phone was given
is keyed at the machine, the switch spends the order exactly once, and the notes come out -
in cash test mode if the machines have it, and with test notes if they do not. No card,
no PIN, no EMV, which is what makes this runnable before a single key is loaded. The
electronic journal is read off the machine at the end of the run and reconciled through
POST /v1/atm/journal.

4b. Chip and PIN, after key loading. Only after items 5, 6 and 7 of the checklist are
settled. It needs an EPP with keys, cards in the Lab BIN range, CA keys the machines accept,
and a dialect that has been read rather than assumed. Nothing in the scaffold computes a
PIN block, holds a key or verifies a certificate today, and nothing should until this step.

---

Running a floor node

The floor node is the ordinary image with floor-node environment. It needs no build of its
own and no code branch.

docker run -d --name finlab-floor \
  --restart unless-stopped \
  -p 8583:8583 -p 9100:9100 -p 8787:8787 \
  -e FLOOR_NODE=1 \
  -e NDC_TCP_PORT=9100 \
  -e ISO8583_TCP_PORT=8583 \
  -e CLOUD_GATEWAY_URL=https://ecosystem.financial \
  -e FLOOR_TEAM_KEY_FILE=/run/secrets/floor-team-key \
  -v /etc/finlab/floor-team-key:/run/secrets/floor-team-key:ro \
  -v /etc/finlab/nodes/floor:/app/nodes/floor:ro \
  ecosystem-gateway:latest

The environment

**A floor node started without a key, or without a gateway to forward to, refuses to come
up.** That is the right severity: a box that accepts a machine's socket and then fails every
transaction on it is worse for the person at the machine than a box that never answered.

As a systemd service (Linux floor PC)

/etc/systemd/system/finlab-floor.service:

[Unit]
Description=FinLab floor node - NDC and ISO 8583 listeners for the Lab machines
After=network-online.target docker.service
Requires=docker.service

[Service]
Type=simple
Restart=always
RestartSec=5
# the key is a file the service user can read and nothing else can: 0400, owned by root
ExecStartPre=-/usr/bin/docker rm -f finlab-floor
ExecStart=/usr/bin/docker run --rm --name finlab-floor \
  -p 9100:9100 -p 8583:8583 -p 8787:8787 \
  -e FLOOR_NODE=1 -e NDC_TCP_PORT=9100 -e ISO8583_TCP_PORT=8583 \
  -e CLOUD_GATEWAY_URL=https://ecosystem.financial \
  -e FLOOR_TEAM_KEY_FILE=/run/secrets/floor-team-key \
  -v /etc/finlab/floor-team-key:/run/secrets/floor-team-key:ro \
  -v /etc/finlab/nodes/floor:/app/nodes/floor:ro \
  ecosystem-gateway:latest
ExecStop=/usr/bin/docker stop finlab-floor

[Install]
WantedBy=multi-user.target

sudo install -m 0400 -o root -g root floor-team-key /etc/finlab/floor-team-key
sudo systemctl daemon-reload && sudo systemctl enable --now finlab-floor
journalctl -u finlab-floor -f

As a Windows service (the machines are Windows-based, and so may the floor PC be)

Windows has no native "run this as a service" wrapper, so use one. With
[NSSM](https://nssm.cc/) and Node 22 installed, running the repository directly rather than
the container:

# the key, readable by the service account and nobody else
icacls C:\finlab\floor-team-key /inheritance:r /grant:r "NT SERVICE\finlab-floor:(R)"

nssm install finlab-floor "C:\Program Files\nodejs\npm.cmd" "run gateway"
nssm set finlab-floor AppDirectory C:\finlab\finlab-ecosystem
nssm set finlab-floor AppEnvironmentExtra ^
  FLOOR_NODE=1 ^
  NDC_TCP_PORT=9100 ^
  ISO8583_TCP_PORT=8583 ^
  CLOUD_GATEWAY_URL=https://ecosystem.financial ^
  FLOOR_TEAM_KEY_FILE=C:\finlab\floor-team-key
nssm set finlab-floor AppStdout C:\finlab\logs\floor.log
nssm set finlab-floor AppStderr C:\finlab\logs\floor.log
nssm set finlab-floor Start SERVICE_AUTO_START
nssm start finlab-floor

Open the two ports to the machines' VLAN and to nothing else:

New-NetFirewallRule -DisplayName "FinLab NDC" -Direction Inbound -Protocol TCP `
  -LocalPort 9100 -RemoteAddress 10.20.30.0/24 -Action Allow
New-NetFirewallRule -DisplayName "FinLab ISO 8583" -Direction Inbound -Protocol TCP `
  -LocalPort 8583 -RemoteAddress 10.20.30.0/24 -Action Allow

---

The two flows the host answers today

Both are mapped onto operations the simulated switch already publishes
(packages/atm-network/src/network.ts) and endpoints the machine lane already carries
(/v1/atm/**). The host adds no capability of its own.

Balance inquiry

machine  ->  Transaction Request   opcode buffer = the balance-inquiry code (A-47)
                                   general-purpose buffer B = the account number
host     ->  /v1/atm/balance-inquiries  { terminalId, issuerId, accountNumber }
host     ->  Transaction Reply     function id = print only, screen = the balance screen,
                                   the figure in the screen update and on the receipt
machine  ->  Solicited Status      the reply was carried out

Nothing moves and nothing comes out. The function id is print only on every path through
this flow.

Cardless withdrawal by code

(phone)  ->  /v1/atm/cardless/orders   the holder's OWN institution mints the one-time code.
                                       A machine never raises an order.
machine  ->  Transaction Request   opcode buffer = the cardless-withdrawal code (A-47)
                                   general-purpose buffer B = the one-time code
host     ->  /v1/atm/cardless/redemptions  { terminalId, code }
host     ->  Transaction Reply     approved: function id = dispense and print, and the
                                     amount is THE ORDER'S, never the machine's
                                   declined: function id = print only, the decline screen,
                                     and the ISO 8583 DE039 on the receipt
machine  ->  Solicited Status      the notes went out, or they did not
host     ->  a journal line, completed by that status

Four properties hold, and each one is asserted in packages/ndc-host/test/flows.test.ts:

1. Every request gets a reply. A machine that receives silence prints nothing, times out, and teaches a customer that the Lab's machines hang.
2. A decline dispenses nothing. The function id is set from the outcome, and there is no path where a non-approval reaches dispense and print.
3. The amount is the switch's. What the customer keyed at the machine is recorded and then ignored: the order is the authority, and a machine that could name its own amount would be a machine that could pay itself.
4. Nothing is dispensed twice. The switch spends the order before it authorizes, and the host sends the same reply to a repeated coordination number rather than starting a second transaction - which is what a machine that missed a reply and re-sent actually needs.

---

Reconciling the electronic journal

Every machine keeps its own record of the day. The switch keeps its own. Reconciliation is
finding where they disagree, and the interesting direction is the machine's: a journal
line the switch has no record of is a payout nobody is going to settle, and it is the shape of
a dispense that happened after the link dropped. The other direction gets found anyway, when
the cassettes are counted.

curl -sS https://ecosystem.financial/v1/atm/journal \
  -H "x-lab-api-key: $FLOOR_TEAM_KEY" \
  -H 'content-type: application/json' \
  -d '{"journal":"2026-09-06T13:00:00.000Z|TERM-LAB-0001|cardless-withdrawal|ATM-atm-network-00001|200000|DOP|00|A"}'

The report says what matched (on the reference, or - for a line with no reference - on the
amount and the terminal), what a matched pair disagrees about, what is in the journal only,
what is at the switch only, and the two totals with their difference.

The line format is the Lab's own, and it is a placeholder (assumption A-48). The format
of these machines' journals is item 9 of the checklist. When it arrives, a parser for it
produces the same JournalLine objects and nothing downstream changes - not the matcher, not
the report, not the endpoint. That is what makes this a scaffold rather than a guess: the
shape of the answer is settled and the reading of the bytes is not.

---

Where the code is

packages/ndc-host/
├── src/dialect.ts    the dialect table - READ THIS FIRST. A-46, A-47, all profile-driven
├── src/messages.ts   the six NDC message families as objects
├── src/codec.ts      bytes to messages and back, and the TCP stream framer
├── src/profile.ts    nodes/floor/<machine>.yaml, and the dialect overrides in it
├── src/lane.ts       the three switch operations, over HTTP or in-process
├── src/host.ts       the state machine: the two flows above
├── src/server.ts     the TCP listener, one host per connected machine
├── src/floor.ts      FLOOR_NODE and the environment
├── src/journal.ts    the journal line and the matcher
└── test/virtual-atm.ts   the machine that does not exist, on a socket that does

---

How a partner switch connects, and the conformance pack

How a partner switch connects

The address is wire.ecosystem.financial:8583, and it is a PLACEHOLDER. It is written here
so an integration has one name to configure and one place to change when a link is actually
stood up. Nothing is listening on it today, and no listener is deployed anywhere. Saying
otherwise would be the easiest false claim in this repository to make and the most expensive
to have made.

Why there is nothing to dial yet, plainly:

The listener needs a TCP-capable host, and the deployed gateway is not one. The ecosystem's gateway runs on Cloud Run, which is reached over HTTP(S) through Google's front end on the one port the container declares; there is no second listener a switch can open a socket to, and no configuration that publishes one. So the listener runs where raw TCP is possible, which today means one of exactly two places: the Lab floor node - this same image on a small PC on the machines' own network segment - or a small Compute Engine VM the deployer starts, running the same image with ISO8583_TCP_PORT set. Both are recipes a person follows; neither is running. docs/deploy/README.md carries the VM recipe as written-out gcloud commands, and they have not been run.

What a partner does, in order:

1. Ask for a team key. The wire sign-on takes a team key - the same value the REST lanes take in x-lab-api-key, from FINLAB_API_KEYS. A service identity is an HTTP credential and is not accepted here: its scope is expressed in HTTP methods and lanes, which a socket does not have.
2. Say which addresses the switch dials from. They go in ISO8583_ALLOWED_CIDRS on the listener. A peer outside it is destroyed at the socket without an answer - no refusal to read, no connection slot spent, nothing to learn from. On a floor VLAN the list may be left empty and the network is the boundary; on any link that leaves the floor it is not optional.
3. Take TLS. ISO8583_TLS_CERT and ISO8583_TLS_KEY, both or neither. Remember what is inside the message: DE052 carries a Lab PIN in the clear - the simulation holds no keys and computes no PIN block, and §3 says so in the table - so the transport is the only thing protecting it. Simulated PIN or not, a link that leaks one teaches a bad habit. The Lab's floor certificate is self-signed; a partner should pin it rather than turn verification off.
4. Run the conformance pack (§9) against the listener, from the switch's own network, and keep the report.
5. Sign on, and stay signed on. One connection, one world, one credential presented once. The link is expected to hold the socket and echo (0800 DE070 301) rather than reconnect per transaction.

The environment the listener reads

Every one of these is read by the gateway process that holds the port. Empty means the
listener does not exist; that is what every Cloud Run instance uses.

Every message is in the world's trace

A signed-on connection writes into the team's own trace, under the actor iso8583-wire: an
event for the sign-on, then a message and a reply per exchange, each carrying the
connection's name (iso8583-0007), the peer, the team, and an **eight-hex fingerprint of the
key** — enough to tell a floor node's credential from a bench key six weeks later, useless as
a credential itself. The rendering is the same one the log uses, so **DE052 and DE127 are
dropped before a character is written**. That is what makes a wire withdrawal and a REST
withdrawal distinguishable after the fact, which is the question a reconciliation asks.

---

The conformance pack

The list of what a switch has to get right, and a runner for it:

npm run wire:conformance -- --host=127.0.0.1 --port=8583 --key=<team key> \
                            --gateway=http://127.0.0.1:8787
npm run wire:conformance -- --host=wire.example --port=8583 --key=… --tls --json

It dials the listener with packages/iso8583-wire/test/virtual-switch.ts — the same virtual
card switch the test suite drives, which is the point: **the pack is not a description of the
tests, it is the tests, pointed somewhere else.** Without --gateway the cases that need Lab
material (a card, an acceptor, a terminal, a cardless order) report SKIP with the reason
and are never counted as passes; the link discipline runs against anything. The exit code is
0 when nothing failed, 1 when anything did, and --json prints the whole report.

**A pass says the listener speaks this profile. It says nothing about any card scheme's
certification, and a run is never a substitute for one.**

_19 cases, 10 of which run against any listener with nothing but a host, a port and a key. Generated from packages/iso8583-wire/src/conformance.ts by npm run spec:wire._

There is deliberately **no clearing message in the pack, because there is none in the
profile (§2: no 0320, no 0500, no 0600). Clearing and settlement here are a cycle** the
acquirer runs, so the clearing case proves that a transaction authorized on the wire is
the one that cycle picks up and settles net — through POST /v1/cards/cycles, not through an
invented MTI. For the same reason a 0420 reversal advice is in the pack only as something a
switch must refuse with 12: the profile's reversal is 0400/0410.

---