--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Number-database	Sun Nov 26 14:51:22 2023 -0800
@@ -0,0 +1,176 @@
+Database of locally owned numbers
+=================================
+
+The database of locally owned phone numbers is a ThemWi-invented ad hoc data
+structure that is absolutely required for ThemWi system sw to work.  The human-
+edited ASCII source form of this database resides in /var/gsm/number-db2 and
+its compiled binary form resides in /var/gsm/number-db2.bin, compiled with
+themwi-update-numdb2 utility.  (The "db2" in file and utility names refers to
+database version 2, which is the current version.)  This database contains two
+types of entries:
+
+1) Locally owned 10-digit NANP numbers;
+2) Internally defined 4-digit short numbers.
+
+NANP number ownership information
+=================================
+
+ThemWi system sw is written with the assumption that the local instance operator
+obtains (rents) real NANP phone numbers from a provider such as BulkVS and
+assigns these numbers to individual GSM subscribers in OsmoHLR.  However, in
+order for ThemWi system sw to work correctly, there is one more step needed:
+each locally owned number (i.e., each NANP number you rent from BulkVS or
+whoever your upstream is) needs to be entered into ThemWi local number database.
+
+The step of obtaining (a batch of) NANP phone numbers from your SIP trunk
+provider and the step of assigning individual numbers to specific GSM
+subscribers (by way of OsmoHLR subscriber database) are almost always separated
+in time: as an operator, you will typically obtain a batch of TNs (telephone
+numbers) in one go, and from the perspective of your upstream, all of these TNs
+route to your server.  How you then assign them to GSM subscribers (make them
+into MSISDNs associated with IMSIs) is your own business, and you can change
+these associations any time you like, without affecting your interconnection
+with your PSTN upstream.
+
+ThemWi local number database needs to list all TNs (10-digit NANP numbers) that
+are currently owned by your local fiefdom, irrespective of whether or not they
+are assigned to a GSM subscriber.  If a given TN belongs to your local fiefdom
+in the sense that the global worldwide PSTN will direct any incoming calls to
+this TN to your server, but you haven't assigned it to a GSM subscriber yet,
+ThemWi system sw still needs to know that this number is locally owned: call
+attempts to that TN should never be sent to the outbound gateway, in particular.
+
+Owned NANP number entry syntax
+------------------------------
+
+By way of example, suppose that a set of telephone numbers in the range
+310-555-01XX is yours - how do you enter them into /var/gsm/number-db2?  You
+have a choice of two syntax forms:
+
+1) If you have many numbers in the same NPA-NXX prefix (as in the present
+   example), you can enter them using this syntax:
+
+prefix 310-555 [allow-abbrev]
+
+suffix 0101
+suffix 0102
+suffix 0103
+...
+
+In this form, all owned TNs under the same prefix are clearly grouped together,
+and you have the option of allowing abbreviations - if you wish to allow
+abbreviated 4-digit dialing, add 'allow-abbrev' keyword to the prefix line.
+When abbreviations are enabled, each suffix line not only creates an entry in
+the owned-NANP portion of the local number database, but also adds an entry to
+the list of defined 4-digit short dialing numbers, mapping to the corresponding
+full number.
+
+2) If you have individual 10-digit NANP numbers that don't form a neat group
+   under a single NPA-NXX prefix, you can enter them using this alternative
+   syntax for single numbers:
+
+full10 310-123-5678
+full10 216-555-0166
+full10 949-011-1234
+...
+
+(The example uses invalid NANP numbers, whereas in actual usage you have to
+enter real valid ones - but the syntax is the same.)  With this number entry
+method, there is no possibility of allow-abbrev: no 4-digit short dialing number
+is created, and the owned NANP number in question can only be dialed in full
+10-digit form.
+
+The given syntax examples for prefix and full10 lines use hyphens.  These
+hyphens are optional and can be placed anywhere in the number - but we recommend
+following the standard notation for NANP numbers.
+
+NANP number usage information
+=============================
+
+The entry formats given above provide only number ownership information: they
+tell ThemWi system sw which NANP numbers belong in the local fiefdom (all listed
+numbers) and which ones don't (the remaining space of all other possible NANP
+numbers outside listed ones).  However, this number ownership information does
+not include any usage or assignment information, and this additional info needs
+to be provided via number attributes.
+
+If number ownership information is entered exactly as shown in the examples
+above, without any additional attributes, ThemWi system sw will treat each of
+its owned numbers as being unassigned: any call attempts to that number, from
+the inside or from the outside, will return "unassigned number" error to the
+caller in the form of GSM CC cause value or SIP error code.  When locally owned
+numbers are assigned to GSM subscribers, a 'gsm-sub' attribute needs to be added
+to each thus-assigned number; following the already given examples, the new
+syntax becomes:
+
+prefix 310-555 [allow-abbrev]
+
+suffix 0101 gsm-sub
+suffix 0102 gsm-sub
+suffix 0103 gsm-sub
+
+full10 310-123-5678 gsm-sub
+full10 216-555-0166 gsm-sub
+full10 949-011-1234 gsm-sub
+...
+
+Note the absence of indication as to which GSM subscriber each number is
+assigned to: when ThemWi system sw sees that the called number is assigned to
+gsm-sub usage, it sends the call to OsmoMSC, which will then look for a
+connected subscriber whose MSISDN equals the called party number.  The mapping
+from phone numbers to specific subscribers as in IMSIs thus happens by way of
+OsmoHLR subscriber database, just like in "bare" Osmocom CNI setups without
+ThemWi system sw.
+
+Alias numbers
+-------------
+
+ThemWi system sw supports the notion of alias or redirecting numbers.  Suppose
+you have a single GSM subscriber who needs to be reachable at more than one NANP
+number - for example, someone who got a native ThemWi number (from BulkVS etc)
+at one point in time, but then ported their number from some national carrier
+(of evil 2G-killing kind) to BulkVS/ThemWi - how to make the same GSM subscriber
+reachable via both numbers?  Each GSM subscriber has a primary MSISDN (phone
+number) that is configured in OsmoHLR: this number is returned by *#100# query,
+and appears as the "from" number on all outgoing calls.  Any additional numbers
+that should route to the same subscriber need to be handled via ThemWi alias
+number facility, i.e., handled at ThemWi system sw level rather than at OsmoCNI
+level.
+
+The syntax for entering alias numbers is as follows (using example fake numbers
+from above):
+
+prefix 310-555 [allow-abbrev]
+suffix 0123 map-to 216-555-0166
+
+or
+
+full10 310-555-0123 map-to 216-555-0166
+
+In this example the "native" number of the GSM subscriber is 216-555-0166, but
+alias number 310-555-0123 is configured to route to the same subscriber.  In the
+case of full10 number lines, the map-to target number must always be entered in
+full 10-digit notation just like the alias number; in the case of prefix and
+suffix lines, the map-to target number can be either a full 10-digit number or
+a 4-digit number in the same prefix.
+
+Irrespective of entry notation used, every map-to target number must be a
+locally owned NANP number (cannot be an outside number) of gsm-sub usage type,
+i.e., some local GSM subscriber's primary number.
+
+Additional number flags for SMS and E911
+========================================
+
+The following additional flags can be set on each locally owned NANP number's
+suffix or full10 line:
+
+e911	This flag indicates that the number in question is provisioned for E911
+	at the level of BulkVS or whoever is the upstream provider from whom
+	the number is rented.  Having a number provisioned for E911 (which costs
+	additional money every month) means that emergency 911 calls can be sent
+	to that PSTN-via-SIP provider with this number as source or "from",
+	without paying a hefty fine for an unprovisioned E911 call.
+
+sms	This flag indicates that the number in question is provisioned for
+	outside SMS connectivity, meaning that it is possible to send SMS to
+	the outside world with this number as source or "from".