RFC / GRID NETWORK STANDARD

CITY EXCHANGE                                            RFC 20  -  THE GRID
Network Services and Terminal Reference                  (type MORE for more)

This is the manual for the public packet exchange. It tells you how to place a
call, carry a conversation, keep files, and stand up a service of your own.
Read it once; the net does not explain itself twice. Every line you type and
every line your programs run costs cycles from your daily allowance.
Type TARIFF for the current prices, CARD for the CANT programmer's card,
RFC for this page again. STATUS tells you who you are, what tick it is, and
what is left of today's cycles; HELP lists these. None of them cost a tick:
they answer while you wait.

1. THE NET
   One exchange. One flat space of numbers. Every number is either dead or
   answers. Behind an answer is a HOST: a deck (yours, that you carry) or a
   server (rented iron that stands on its own). You reach a host only by its
   number. There is no map. Finding what answers is called dialing the space,
   and it is how everything out there was found in the first place.

2. NUMBERS
   A number is written  PREFIX-NNNN , three digits, a dash, four digits, like
   555-0100. One number is spoken for while the exchange is being commissioned:
     555-0001  the rental desk -- send it  rent server  for a free box
   Other reserved numbers are not yet in service and do not answer. The rest
   are out there: taken by those who find them empty, or standing idle. Your
   own number came with your deck.

3. PLACING A CALL
   dial 555-0100
   The exchange rings the number. You get one of three replies back, next tick:
     CARRIER      something answered; a call is open
     NO CARRIER   the number is dead
     LINE BUSY    your host or the target has no free call slots
   What answers may be a program somebody wrote, or it may be the machine
   itself. See section 7.
   A call is a line held open between your host and that number. While it
   stands, either end may send to the other. Dialing a range of numbers one
   after another, and noting which give CARRIER, is how you survey the net.
   It costs a dial each. Nobody hands out a directory of the interesting ones.

4. TALKING
   send 555-0100 the eagle lands at noon
   Sends one line of text to a number you have a call open with. The other end
   receives your line and the number you are calling FROM. Everything on the
   net is in the clear: a line is text, read by whatever sits on the wire
   between you. Say less than you know.
   hangup 555-0100
   Ends the call. The other end is told the line dropped. Nothing on the wire
   decides for you who is worth talking to and who is a nuisance; you do, in
   your own program, and you spend your own cycles doing it.

5. WHO YOU SAY YOU ARE
   The number you call FROM is the number you CLAIM. By default it is your own.
   origin 555-0100
   From now your calls and your sends claim 555-0100. The net does not check;
   it never has. What answers takes you for whoever you say you are, and
   answers accordingly: a reply is sent to the number claimed, not to whoever
   claimed it. This is the exchange working as built, not a fault to report.
   origin reset      go back to claiming your own number.

CITY EXCHANGE                                            RFC 20  -  THE GRID
Network Services and Terminal Reference                             page 2

6. FILES
   A host keeps files. Yours are on your deck; a service's are on its server.
   You touch only the files of the host you are running on. You do not reach
   into someone else's host and read their disk -- you talk to whatever they
   are running, and it decides what to tell you. That program is only as
   careful as whoever wrote it.
     list /            names of files
     read /notes       the contents of a file, or nothing
     write /notes remember the number for the fixer
     append /notes and the second half of the number
     delete /notes     marks it gone
   Gone is not gone. The exchange never truly erases; a deleted file still sits
   in the archive, and a good enough runner reads it. Keep nothing you would
   not want dug up.

7. YOUR IRON
   A host is bare iron. It keeps files, it starts programs from those files, it
   stops them, it carries word between them, and it hands what arrives on the
   wire to whichever program has taken the number. Nothing else. What runs on
   your iron is what you put there.
     use 555-0200      work at another host you own
     spawn /board      start the program in a file; you get a number for it
     ps                what is running here
     kill 3            stop one
     signal 3 wake up  pass a line to another program on this host
   So a service is: write the program into a file (type CARD for how to write
   one), spawn it, and have it take the number with LISTEN. Only one program
   per host may hold the number. The reference programs the exchange ships --
   a notice board, a dead drop, a town crier -- are public and yours to copy.

   THE BARE MACHINE. When no program holds a server's number, the machine
   answers the number itself. Whoever is on the line sends it lines and it
   works them as its own commands: its files, its programs, its wire. It asks
   nothing of anyone; a machine with no program on it has no way to ask. That
   is how you bring a new server up -- dial it and work it -- and it is how
   anyone else works it too, for as long as it stands that way. Iron you have
   just rented stands that way from the moment you rent it. What it costs to
   work a machine is charged to that machine.
   Your deck is not like this. You are sitting at it, so when no program holds
   its number, calls and lines arrive at your terminal as events:
     events            anything waiting for you
     use 555-0200      work at iron of your own, instead of your deck

8. WHAT REACHES A PROGRAM
   A running program is handed each arrival as a signal (see the CARD). The
   kinds it will see on the net:
     connect   someone dialed in           -- from: who they claim to be
     line      a line arrived on a call    -- from, text
     hangup    the other end let go        -- from
     signal    another program here spoke  -- from: its number, body
   Answer with the verbs of sections 3 to 7, written in capitals in CANT:
   DIAL SEND HANGUP ORIGIN READ LIST WRITE APPEND DELETE SPAWN KILL SIGNAL PS,
   and three a program has that a hand at a terminal does not:
     LISTEN    take this host's number -- what arrives comes to you
     WAIT n    sleep n ticks, then carry on -- for polling and for backing off
     LOG text  write a line to your own log -- a private note to yourself

9. WHAT IT COSTS
   Everything above costs cycles. Dialing costs whether or not anything
   answers. Sending, reading, writing all have a price; a program
   also pays to think (see the CARD). Type TARIFF for the list.
   The exchange is not billing while it is being commissioned. Prices are
   charged and your meter runs, but the day's allowance is far beyond
   anything you can spend, and prices will be posted before they begin to
   bite. What your programs are metered at per turn has not changed.
   There is no other authority on the wire than what answers, what pays,
   and what the paper prints.

12. EXCHANGE UPDATE — RULES 2
   A failed new dial does not close old calls. SEND may use an old call.
   CANT DIAL returns 1 for carrier, 0 for no carrier, null for busy.
   ORIGIN RESET is case-insensitive; STATUS shows the attached host and origin.

   WRITE, APPEND, SEND and SIGNAL preserve all payload bytes after ONE
   separator following the final syntax argument. APPEND concatenates bytes;
   it adds no newline. Send physical newlines; literal backslash-n stays literal.
   The terminal accepts at most 512 UTF-8 bytes INCLUDING command/path prefixes.
   Output is at most 1024 encoded JSON bytes per response; large events page.

   READ proc:index/0           local process index, including stopped processes
   READ proc:1/meta/0           PID 1: status, global daemon ID, source path, fault
   READ proc:1/state/0          retained variables and execution position
   READ proc:1/source/0         source snapshot used at spawn
   READ proc:1/log/0            retained LOG ring as JSON
   READ proc:load/0             latest local SPAWN refusal, reason and source line
   These are host-local read-only records, charged at the ordinary READ price.
   Each chunk is at most 512 UTF-8 bytes. Replace the final 0 with the previous
   offset plus received byte length to read on. Absent (--) means EOF/no record.
   Assemble JSON chunks before parsing. Live records may change between reads.
   PS still shows live processes only. SPAWN still returns PID or 0.

   WAIT pauses execution, not signal arrival. Signals queue until the program
   returns to signal-receiving sleep. A rule that keeps firing prevents sleep.
   USE moves your console; it does not pause a service. The rental desk gives
   a number; successful installation claims unowned iron. USE requires ownership.