--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Local-short-numbers	Sun Nov 26 17:08:10 2023 -0800
@@ -0,0 +1,118 @@
+Network-internal short dialing numbers
+======================================
+
+In addition to obviously necessary support for standard E.164 phone numbers
+(assigning real NANP numbers to local subscribers, calling any other NANP
+numbers whether they are local or not, calling international numbers outside of
+NANP), ThemWi system sw implements an additional, entirely private and network-
+internal, numbering space for 4-digit short dialing numbers.  Any time a ThemWi
+GSM subscriber dials a number that consists of only (exactly) 4 digits, that
+short number is looked up in this private ThemWi-defined numbering space.
+
+In the present implementation, three different types of numbers can exist in
+this private, network-internal short 4-digit number space, each described in
+its own section below.
+
+Abbreviated NANP numbers
+------------------------
+
+If you have a bunch of real NANP numbers from the same NPA-NXX prefix, you can
+enter them into the master database of locally owned numbers (see
+Number-database article) using this notation:
+
+prefix NPA-NXX allow-abbrev
+
+If the 'allow-abbrev' flag keyword is included, each NANP number entered under
+this prefix (each following suffix line) gets added to the short 4-digit number
+space: in addition to the standard option of dialing all 10 digits, the same
+number can be reached by dialing only the last 4 digits, considered to be the
+"station" part of the number (under a given "exchange") per NANP rules.
+
+You do need to be careful with this facility, as conflicting numbers are not
+allowed.  Enabling allow-abbrev mode makes sense under the following conditions:
+
+1) You have one preferred NPA-NXX prefix, presumably corresponding to your
+   geographic locality, and you reserve all of your native numbers (via BulkVS
+   portal or equivalent from other providers) from that one preferred prefix.
+   In this case you should set allow-abbrev on your "home" prefix, but whenever
+   you have to add non-native numbers to your network (customer port-ins etc),
+   those don't get the abbreviated dialing option, only full10.
+
+2) You may enable allow-abbrev for more than one prefix if you reserve your
+   numbers from multiple prefixes in a judicious manner, selecting 4-digit
+   suffixes that don't overlap across your two (or more) prefixes.
+
+Internal test numbers (ITNs)
+----------------------------
+
+An ITN is a 4-digit short dialing number (meaningful only inside your local GSM
+network) that is assigned to a GSM subscriber and entered as such (4 digits
+only) into OsmoHLR subscriber database.  When ITNs are used, a GSM subscriber
+who gets an ITN is *not* given a real NANP telephone number, and thus cannot
+make any calls to or receive any calls from the outside world.
+
+Our own Themyscira Wireless operation does not presently use any ITNs.  This
+facility was invented before we realized how cheap NANP numbers can be when they
+are ordered "raw" or "bare": a basic reservation of a real 10-digit NANP number
+from BulkVS *without* E911 provision and without SMS capability (regular,
+non-emergency calls only) costs only $0.06 (6 cents) per number per month.  At
+this insanely cheap price, it makes no sense to introduce ITNs, it is easier to
+give a real NANP number to every GSM subscriber including lab-use-only test
+SIMs - but the Mother does not believe in removing implemented functionality
+without extremely strong justification, hence support for ITNs remains in our
+software.
+
+To define an ITN, enter a line like this into your master database of locally
+owned numbers:
+
+itn XXXX
+
+where XXXX is the 4-digit number to be defined as an ITN.
+
+Test sink numbers
+-----------------
+
+A test sink number is a private, network-internal 4-digit number that is
+intended to serve as a destination or "sink" for test calls and test SMS.  Any
+calls dialed to a test sink number will be handled by a special process which
+only exists for that purpose (remains to be implemented), and any SMS sent to a
+test sink number will be simply written into log-structured storage without any
+further delivery to anywhere.  The purpose of test sink numbers is to exercise
+outgoing call and outgoing SMS functions of GSM MS without needing a "real"
+second party to serve as the recipient.
+
+To define a test sink number, enter a line like this into your master database
+of locally owned numbers:
+
+test-sink XXXX
+
+where XXXX is the 4-digit number to be defined as a test sink.
+
+Historical perspective
+======================
+
+In the original design of ThemWi system sw, 4-digit short dialing numbers were
+intended to be ITNs only, forming an internal-only numbering space that is
+entirely disjoint from public E.164 numbers.  Operating on the assumption that
+external NANP numbers would be expensive, the design model was that every GSM
+subscriber would have an ITN, and then additionally some subscriber lines (those
+belonging to human users, rather than lab test SIMs) would be given real
+external phone numbers in NANP.  The fixed 4-digit length for internal short
+numbers was chosen, contrary to the apparent custom in Osmocom community of
+using 5-digit numbers for such internal "extensions", because a 5-digit number
+can be a valid SMS short code in USA, and human users of Themyscira Wireless GSM
+service need to be able to access these SMS short-code public services just like
+customers of any other cell carrier in this country.
+
+Shortly after beginning to implement the initial design described above, we
+discovered how cheap real NANP numbers actually are, and got a batch of numbers
+from our choice of NPA-NXX prefix.  We were then sitting on a batch of numbers
+that had the same 6-digit prefix, but different 4-digit suffixes, and that was
+how we got the idea of abbreviated dialing numbers: instead of completely
+made-up ITNs, allow "home block" NANP numbers to be dialed (from one local GSM
+phone to another) by just the last 4 digits of the external, globally valid
+E.164 number.
+
+Test sink numbers are our latest-so-far addition to the network-internal 4-digit
+dialing number space, and we have yet to implement them beyond mere definition
+in the local number database.