# 03 — Config generator (DB → Asterisk)

This is the heart of the product. Read all of it before changing any call-routing code.

Code lives in `apps/api/src/generator/`.

## 1. Interface

```ts
// load.ts
export type Snapshot = { /* every table from 02-data-model.md that the generator needs, fully loaded,
                            plus resolved settings and decrypted secrets */ };
export async function loadSnapshot(db: Db): Promise<Snapshot>;

// index.ts
export type RenderedFiles = Record<GeneratedFileName, string>;
export function render(snap: Snapshot): RenderedFiles;        // PURE: no I/O, no Date.now(), no randomness
export async function apply(opts: { trigger: string; force?: boolean }): Promise<ApplyResult>;
export function requestApply(trigger: string): void;          // debounced 1000 ms, calls apply()
```

Rules for `render()`:
- **Pure and deterministic.** Same snapshot → byte-identical output. Sort
  everything: users by number, routes by position, members by position, and
  objects without a natural order by `id`.
- The current date is not read inside `render()`. Holiday filtering needs
  "today", so `loadSnapshot` puts `snap.today` (a `YYYY-MM-DD` string in `general.timezone`) into the snapshot.
- Every file starts with the header
  `; GENERATED BY SelfPhoneNG — DO NOT EDIT. Changes will be overwritten.`
- Never put a value into output without passing it through a sanitizer (§2).

`apply()` steps:
1. Take a process-wide mutex. Only one apply runs at a time.
2. `loadSnapshot()` → `render()`.
3. For each file, compare with what is on disk. Collect `changed`.
4. If nothing changed and not `force`: record a `generator_runs` row and return.
5. Copy the current files to `/etc/asterisk/selfphoneng/.prev/` (keep one previous version).
6. For each changed file, write `<name>.tmp` then `rename()` it over the old one (atomic).
7. Work out reload commands from the changed files (§3), or from every file when `force`. If the PJSIP
   transport sections changed, don't reload PJSIP. Set
   `system.restartRequired = true` instead (see `01-infrastructure.md` §4.3). Exception: the very first
   apply (no stored `system.transportHash`) reloads PJSIP normally, since it only adds transports to an
   Asterisk that booted with none.
8. Send each command as AMI `Action: Command`. If AMI is down, mark the run
   `ok=false, error='ami-disconnected'`. The AMI reconnect handler calls `apply({force:true})` later.
9. After `queue reload`: re-send every paused queue member (`QueuePause`), because a reload resets pause state.
10. Insert a `generator_runs` row. Broadcast `system.configApplied` on the live WebSocket.

`POST /api/system/config/rollback` copies `.prev/*` back and reloads everything.

## 2. Sanitizers (`sanitize.ts`)

Dialplan and config files are code. A display name containing `)` or `;` or
a newline could break or inject dialplan. Every value goes through one of these:

| Function | Allowed | Used for | On bad input |
|---|---|---|---|
| `digits(v)` | `^[0-9]+$` | internal numbers, DIDs | throw |
| `dialable(v)` | `^[0-9*#+]+$` | forward targets, external numbers | throw |
| `pattern(v)` | `^[0-9XZN.!\[\]\-]+$`, max 32 | outbound route patterns | throw |
| `name(v)` | removes `" ' \ ; , ( ) [ ] { } $ < > \|` and control chars, trims, max 40 chars | caller ID names, labels | clean silently |
| `sound(v)` | `^[a-z0-9/_-]+$` | sound file names for Playback | throw |
| `ident(v)` | `^[a-z0-9-]+$` | context-name parts (uuids), MOH class names | throw |
| `secret(v)` | `^[A-Za-z0-9]+$` | generated SIP passwords | throw |
| `pin(v)` | `^[0-9]{4,10}$` | voicemail / conference PINs | throw |
| `host(v)` | hostname or IPv4 regex | trunk server host | throw |
| `cidr(v)` | IPv4 CIDR regex | local nets | throw |

The API validates with the same rules (shared zod schemas in `packages/shared`),
so a throw here means a bug, and the apply fails loudly. Also write a
unit test for each sanitizer with hostile input (`101); System(rm -rf /`, newlines, unicode).

## 3. Generated files and reload commands

All files go to `/etc/asterisk/selfphoneng/`.

| File | Module | AMI `Command:` after change |
|---|---|---|
| `pjsip_selfphoneng.conf` | res_pjsip | `module reload res_pjsip.so` (or restart-required if transports changed). Asterisk 24 has no `pjsip reload` CLI command. |
| `extensions_selfphoneng.conf` | pbx_config | `dialplan reload` |
| `extensions_globals_selfphoneng.conf` | pbx_config | `dialplan reload` |
| `voicemail_selfphoneng.conf` | app_voicemail | `voicemail reload` |
| `queues_selfphoneng.conf` | app_queue | `queue reload all` |
| `musiconhold_selfphoneng.conf` | res_musiconhold | `moh reload` |
| `rtp_selfphoneng.conf` | res_rtp_asterisk | `module reload res_rtp_asterisk.so` |
| `confbridge_selfphoneng.conf` | app_confbridge | `module reload app_confbridge.so` |

Each command is sent once per apply, even if several files map to it.

**Transport-change detection:** the "transport block" is every section with
`type=transport` plus `[global]` and `[system]`. Render it as its own string
(`renderTransports(snap)`) and compare its sha256 with the one stored in
`settings['system.transportHash']`.

## 4. `rtp_selfphoneng.conf`

```ini
; GENERATED ...
icesupport = yes
stunaddr = {network.stunServer}          ; omit line when null
{if network.lanIp and network.publicIp}
[ice_host_candidates]
{network.lanIp} => {network.publicIp}
{/if}
```
(`network.lanIp` is the server's own LAN address, see `02-data-model.md` §3.)

## 5. `pjsip_selfphoneng.conf`

Render the sections in this order: global, system, transports, extensions
(sorted by number), trunks (sorted by name).

### 5.1 Global, system, transports

```ini
[global]
type = global
user_agent = SelfPhoneNG
endpoint_identifier_order = ip,username,anonymous
keep_alive_interval = 90
max_initial_qualify_time = 4

[system]
type = system
timer_t1 = 500
timer_b = 32000

[transport-udp]
type = transport
protocol = udp
bind = 0.0.0.0:{sip.udpPort}
{natLines}

{if sip.tcpEnabled}
[transport-tcp]
type = transport
protocol = tcp
bind = 0.0.0.0:{sip.udpPort}
{natLines}
{/if}

{if sip.tlsEnabled}
[transport-tls]
type = transport
protocol = tls
bind = 0.0.0.0:{sip.tlsPort}
cert_file = /var/lib/selfphoneng/tls/fullchain.pem
priv_key_file = /var/lib/selfphoneng/tls/privkey.pem
method = tlsv1_2
{natLines}
{/if}

[transport-ws]
type = transport
protocol = ws
bind = 0.0.0.0
```
`{natLines}` is empty when `network.publicIp` is null. Otherwise:
```ini
external_media_address = {publicIp}
external_signaling_address = {publicIp}
local_net = {each localNets entry on its own line}
```

Notes:
- The WebSocket bind address is ignored. The browser connects through Asterisk's HTTP server (`http.conf`).
  If browser registration fails with a "no transport" error, change
  `protocol = ws` to `protocol = wss` and fix the spec.
- The asterisk container needs `./data/tls:/var/lib/selfphoneng/tls:ro`. Add it to the compose file when TLS is first used (M11).
- No `anonymous` endpoint is ever generated, so unauthenticated calls from the internet are rejected.

### 5.2 One extension (example: 101, Dan Doe, webrtc on)

```ini
; ── extension 101 (Dan Doe) ──
[101]
type = endpoint
context = sp-from-ext
disallow = all
allow = g722,ulaw,alaw
auth = 101-auth
aors = 101
callerid = "Dan Doe" <101>
mailboxes = 101@default            ; omit if voicemail disabled
direct_media = no
rtp_symmetric = yes
force_rport = yes
rewrite_contact = yes
dtmf_mode = rfc4733
send_pai = yes
allow_subscribe = yes
named_call_group = sales           ; omit if pickup_group null
named_pickup_group = sales         ; omit if pickup_group null
language = en
moh_suggest = default
tone_zone = us
set_var = SP_EXT=101
set_var = SP_CLASS=2               ; internal=0 local=1 national=2 international=3
set_var = SP_OUTCID=13125551234    ; omit if outbound_caller_id_did_id null
set_var = SP_E911CID=13125551234   ; omit if emergency_caller_id_did_id null
set_var = SP_RECMODE=never
set_var = __SP_DIRECTION=internal  ; loads as variable "__SP_DIRECTION" (checked on 24.0.0-rc2); inheritance to
                                   ; dialed channels still to be proven by a call test (M2-T6)

[101-auth]
type = auth
auth_type = userpass
username = 101
password = {decrypted sip password}

[101]
type = aor
max_contacts = 5
remove_existing = yes
qualify_frequency = 30
mailboxes = 101@default            ; omit if voicemail disabled

{if webrtc_enabled}
[101-web]
type = endpoint
context = sp-from-ext
webrtc = yes                       ; turns on ICE, AVPF, DTLS-SRTP, rtcp-mux
disallow = all
allow = g722,ulaw                  ; NO opus: no open source transcoder in Asterisk (AGENTS rule 4)
auth = 101-web-auth
aors = 101-web
callerid = "Dan Doe" <101>
mailboxes = 101@default
dtmf_mode = rfc4733
allow_subscribe = yes
named_call_group = sales
named_pickup_group = sales
language = en
set_var = (same set_var lines as [101])

[101-web-auth]
type = auth
auth_type = userpass
username = 101-web
password = {same decrypted sip password}

[101-web]
type = aor
max_contacts = 3
remove_existing = yes
qualify_frequency = 0              ; browsers don't answer OPTIONS reliably
{/if}
```

Desk phones and softphones register as user `101`. The browser softphone
registers as `101-web`. Dialing user 101 rings both (§6.2).

### 5.3 One voip.ms trunk (registration mode)

Trunk section names use the trunk id: `trunk-{id}`. Example values: server
`chicago1.voip.ms`, sub-account `123456_pbx`.

```ini
; ── trunk "voip.ms" ──
[trunk-{id}-auth]
type = auth
auth_type = userpass
username = 123456_pbx
password = {decrypted}

[trunk-{id}-reg]
type = registration
transport = transport-udp           ; transport-tls when transport=tls
outbound_auth = trunk-{id}-auth
server_uri = sip:chicago1.voip.ms:5060
client_uri = sip:123456_pbx@chicago1.voip.ms:5060
contact_user = 123456_pbx
retry_interval = 60
forbidden_retry_interval = 600
fatal_retry_interval = 600
max_retries = 10000
expiration = 300
line = yes
endpoint = trunk-{id}

[trunk-{id}]
type = aor
contact = sip:chicago1.voip.ms:5060
qualify_frequency = 60

[trunk-{id}]
type = endpoint
transport = transport-udp
context = sp-from-trunk-{id}
disallow = all
allow = ulaw                        ; from trunks.codecs
outbound_auth = trunk-{id}-auth
aors = trunk-{id}
from_user = 123456_pbx
from_domain = chicago1.voip.ms
direct_media = no
rtp_symmetric = yes
force_rport = yes
rewrite_contact = yes
send_rpid = yes                     ; carries our caller ID to voip.ms
trust_id_inbound = yes
dtmf_mode = rfc4733
media_encryption = sdes             ; only when srtp = true (requires transport = tls)

[trunk-{id}-identify]
type = identify
endpoint = trunk-{id}
match = chicago1.voip.ms
```
For `auth_mode = 'ip'`, leave out the `-auth` and `-reg` sections and the `outbound_auth` line
(and `from_user` when there is no username).
Skip disabled trunks entirely.
For TCP/TLS trunks, `server_uri`, `client_uri` and the AOR `contact` get `;transport=tcp|tls`.
`identify` resolves `match` when the config loads, and an unresolvable name is an ERROR that drops the
trunk's identify (verified), so the API refuses a server name that doesn't resolve, and a transport
that isn't turned on in Settings → SIP.

## 6. Dialplan: `extensions_selfphoneng.conf`

### 6.0 Destination → dialplan (`destinations.ts`)

`destApp(dest, snap): string` returns ONE dialplan application call that sends the call there:

| Destination | Output |
|---|---|
| `user` | `Goto(sp-local-numbers,{ext.number},1)` |
| `voicemail` | `Goto(sp-vm-direct,{ext.number},1)` |
| `ring_group` | `Goto(sp-rg-{id},s,1)` |
| `queue` | `Goto(sp-queue-{id},s,1)` |
| `ivr` | `Goto(sp-ivr-{id},s,1)` |
| `time_condition` | `Goto(sp-tc-{id},s,1)` |
| `conference` | `Goto(sp-conf-{id},s,1)` |
| `announcement` | `Goto(sp-ann-{id},s,1)` |
| `external` | `Goto(sp-ext-forward,{dialable(number)},1)` |
| `hangup` | `Hangup()` |

If the target row is missing (should be impossible, see 02 §1), output `Hangup()` and log a warning.

### 6.1 Contexts: complete list

| Context | Kind | Purpose |
|---|---|---|
| `sp-from-ext` | static | Entry point for calls from our phones |
| `sp-from-trunk-{id}` | per trunk | Entry point for calls from a trunk |
| `sp-did-exists` | generated | One empty exten per DID, used to check "is this one of ours?" |
| `sp-inbound` | generated | DID → destination |
| `sp-local-numbers` | generated | Every internal number + hints |
| `sp-featurecodes` | static | `*` codes |
| `sp-emergency-dial` / `sp-emergency` | generated | 911 |
| `sp-outbound-routes` | generated | Pattern → route |
| `sp-route-{id}` | per route | Permission check, caller ID, trunk failover |
| `sp-rg-{id}` | per ring group | |
| `sp-queue-{id}` | per queue | |
| `sp-ivr-{id}` | per IVR | |
| `sp-tc-{id}` | per time condition | |
| `sp-ann-{id}` | per announcement | |
| `sp-conf-{id}` | per conference | |
| `sp-page-{id}` | per paging group | |
| `sp-vm-direct`, `sp-ext-forward`, `sp-rg-member`, `sp-queue-member` | static | helpers |
| `sp-sub-*` | static | Gosub subroutines |
| `sp-parkedcalls` | made by res_parking | included by `sp-local-numbers` |

"static" means the text is a constant string in the generator (`dialplan/static.ts`)
with no DB data, so all dialplan stays in one place in code.

### 6.2 Static subroutines and helpers

```ini
; ─── Normalize a number. ARG1 = raw. Returns normalized in GOSUB_RETVAL. (matches 00 §8)
[sp-sub-normalize]
exten => s,1,Set(N=${FILTER(0123456789+,${ARG1})})
 same => n,ExecIf($["${N:0:2}" = "+1"]?Set(N=${N:1}))
 same => n,ExecIf($["${N:0:1}" = "+"]?Set(N=011${N:1}))
 same => n,ExecIf($[${LEN(${N})} = 10]?Set(N=1${N}))
 same => n,Return(${N})

; ─── Ring every registered device of a user. ARG1 = ext, ARG2 = seconds.
; Sets DIALSTATUS. Rings desk/softphone contacts (PJSIP/101) and browser (PJSIP/101-web).
[sp-sub-dial-user]
exten => s,1,Set(DS=${PJSIP_DIAL_CONTACTS(${ARG1})})
 same => n,Set(WS=${PJSIP_DIAL_CONTACTS(${ARG1}-web)})
 same => n,ExecIf($["${DS}" != "" & "${WS}" != ""]?Set(DS=${DS}&${WS}))
 same => n,ExecIf($["${DS}" = ""]?Set(DS=${WS}))
 same => n,GotoIf($["${DS}" = ""]?unavail)
 same => n,Dial(${DS},${ARG2},tx)
 same => n,Return()
 same => n(unavail),Set(DIALSTATUS=CHANUNAVAIL)
 same => n,Return()

; ─── Call a user with all their personal rules.
; ARG1 = ext, ARG2 = ring seconds, ARG3 = voicemail enabled (1/0), ARG4 = record mode
[sp-sub-user]
exten => s,1,Set(__SP_TARGET=${ARG1})
 same => n,ExecIf($["${SP_DIRECTION}" = "inbound" & ("${ARG4}" = "inbound" | "${ARG4}" = "all")]?Gosub(sp-sub-record,s,1))
 same => n,GotoIf($["${DB(SP/DND/${ARG1})}" = "1"]?busy)
 same => n,Set(FWD=${DB(SP/CFU/${ARG1})})
 same => n,GotoIf($["${FWD}" != ""]?forward)
 same => n,Gosub(sp-sub-dial-user,s,1(${ARG1},${ARG2}))
 same => n,GotoIf($["${DIALSTATUS}" = "ANSWER"]?done)
 same => n,GotoIf($["${DIALSTATUS}" = "BUSY"]?busy)
 same => n(noanswer),Set(FWD=${DB(SP/CFNA/${ARG1})})
 same => n,GotoIf($["${FWD}" != ""]?forward)
 same => n,GotoIf($["${ARG3}" = "1"]?vmu)
 same => n,Return()
 same => n(vmu),VoiceMail(${ARG1}@default,u)
 same => n,Return()
 same => n(busy),Set(FWD=${DB(SP/CFB/${ARG1})})
 same => n,GotoIf($["${FWD}" != ""]?forward)
 same => n,GotoIf($["${ARG3}" = "1"]?vmb)
 same => n,Busy(5)
 same => n,Return()
 same => n(vmb),VoiceMail(${ARG1}@default,b)
 same => n,Return()
 same => n(forward),Gosub(sp-sub-forward,s,1(${FWD},${ARG1}))
 same => n(done),Return()

; ─── Forward a call. ARG1 = target number, ARG2 = ext whose forward rule this is.
; Stops after 3 hops so 101→102→101 can't loop forever.
[sp-sub-forward]
exten => s,1,Set(__SP_FWDHOPS=$[${IF($["${SP_FWDHOPS}" = ""]?0:${SP_FWDHOPS})} + 1])
 same => n,GotoIf($[${SP_FWDHOPS} > 3]?stop)
 same => n,GotoIf($[${DIALPLAN_EXISTS(sp-local-numbers,${ARG1},1)}]?internal)
 same => n,Set(SP_CLASS=${GLOBAL(SP_CLASS_${ARG2})})
 same => n,Set(__SP_FORWARDED=1)
 same => n,Goto(sp-outbound-routes,${ARG1},1)
 same => n(internal),Goto(sp-local-numbers,${ARG1},1)
 same => n(stop),Return()

; ─── Start recording this call once. File: YYYY/MM/DD/<uniqueid>.wav under the monitor dir.
[sp-sub-record]
exten => s,1,GotoIf($["${SP_REC}" != ""]?done)
 same => n,Set(__SP_REC=${STRFTIME(${EPOCH},,%Y/%m/%d)}/${UNIQUEID}.wav)
 same => n,MixMonitor(${SP_REC},b)
 same => n(done),Return()

; ─── Auto-answer headers for paging/intercom (Yealink, Grandstream, Polycom, Snom)
[sp-sub-autoanswer]
exten => s,1,Set(PJSIP_HEADER(add,Call-Info)=<sip:${SP_EXT}>\;answer-after=0)
 same => n,Set(PJSIP_HEADER(add,Alert-Info)=info=alert-autoanswer)
 same => n,Return()

[sp-vm-direct]
exten => _X.,1,Answer()
 same => n,VoiceMail(${EXTEN}@default,u)
 same => n,Hangup()

[sp-ext-forward]
exten => _[0-9*#+].,1,Set(SP_CLASS=3)          ; admin-configured external destination
 same => n,Set(__SP_FORWARDED=1)
 same => n,Goto(sp-outbound-routes,${EXTEN},1)

[sp-rg-member]                                  ; one member of a ring group (Local channel)
exten => _X.,1,GotoIf($["${DB(SP/DND/${EXTEN})}" = "1"]?skip)
 same => n,Gosub(sp-sub-dial-user,s,1(${EXTEN},600))
 same => n(skip),Hangup()

[sp-queue-member]                               ; one queue agent (Local channel)
exten => _X.,1,Gosub(sp-sub-dial-user,s,1(${EXTEN},600))
 same => n,Hangup()

[sp-from-ext]
include => sp-emergency-dial
include => sp-featurecodes
include => sp-local-numbers
include => sp-outbound-routes
```

### 6.3 Globals file `extensions_globals_selfphoneng.conf`

```ini
SP_DEFAULT_CID={routing.defaultCallerIdDidId → number, or empty}
SP_DEFAULT_E911_CID={emergency.defaultCallerIdDidId → number, or SP_DEFAULT_CID}
SP_REC_ANNOUNCE={recordings.announcementSoundId → asterisk_name, or empty}
SP_CLASS_101=2            ; one per extension, used by sp-sub-forward
SP_TCADMIN_101=1          ; one per extension whose user is an admin (time-condition override codes)
```
(`routing.defaultCallerIdDidId` is in 02 §3.)

### 6.4 Trunk entry `sp-from-trunk-{id}`

```ini
[sp-from-trunk-{id}]
exten => s,1,Goto(sp-from-trunk-{id},unknown,1)
exten => _[+0-9a-zA-Z].,1,Set(__SP_DIRECTION=inbound)
 same => n,Gosub(sp-sub-normalize,s,1(${EXTEN}))
 same => n,Set(SP_IN=${GOSUB_RETVAL})
 same => n,GotoIf($["${SP_IN}" != "" & ${DIALPLAN_EXISTS(sp-did-exists,${SP_IN},1)}]?caller)
 ; Request-URI didn't hold one of our DIDs: try the To header (see 06 §3)
 same => n,Set(TOU=${CUT(CUT(PJSIP_HEADER(read,To),@,1),:,2)})
 same => n,Gosub(sp-sub-normalize,s,1(${TOU}))
 same => n,Set(SP_IN=${GOSUB_RETVAL})
 same => n(caller),Gosub(sp-sub-normalize,s,1(${CALLERID(num)}))
 same => n,Set(CALLERID(num)=${GOSUB_RETVAL})
 same => n,GotoIf($["${DB(SP/BLOCK/${CALLERID(num)})}" = "1"]?blocked)
 same => n,Goto(sp-inbound,${IF($["${SP_IN}" = ""]?unknown:${SP_IN})},1)
 same => n(blocked),Hangup(21)
```

### 6.5 `sp-did-exists` and `sp-inbound`

```ini
[sp-did-exists]
exten => 13125551234,1,NoOp()            ; one line per DID

[sp-inbound]
; DID 13125551234 "Main line"
exten => 13125551234,1,Set(__SP_DID=13125551234)
 same => n,Set(CALLERID(name)=SALES:${CALLERID(name)})          ; only if caller_id_name_prefix
 same => n,Answer()                                              ; only if record_inbound and announcement set
 same => n,Playback({SP_REC_ANNOUNCE sound})                     ; only if record_inbound and announcement set
 same => n,Gosub(sp-sub-record,s,1)                              ; only if record_inbound
 same => n,{destApp(did.destination)}

; anything else
exten => _[0-9a-z].,1,{destApp(routing.unmatchedDidDestination)}
```
Leave `[sp-did-exists]` out when there are no DIDs: Asterisk doesn't create an empty context, and
`DIALPLAN_EXISTS` on a missing context is simply false. `record_inbound` arrives with recording (M7).

### 6.6 `sp-local-numbers`

```ini
[sp-local-numbers]
include => sp-parkedcalls

; users (sorted by number)
exten => 101,1,Gosub(sp-sub-user,s,1(101,25,1,never))   ; (ext, ring_seconds, voicemail 1/0, record_mode)
 same => n,Hangup()
exten => 101,hint,PJSIP/101&PJSIP/101-web               ; just PJSIP/101 when webrtc disabled

; ring groups, queues, ivrs, conferences, paging groups (each one line)
exten => 500,1,Goto(sp-rg-{id},s,1)
exten => 550,1,Goto(sp-queue-{id},s,1)
exten => 600,1,Goto(sp-ivr-{id},s,1)
exten => 800,1,Goto(sp-conf-{id},s,1)
exten => 850,1,Goto(sp-page-{id},s,1)
```

### 6.7 Ring groups

`ringall`:
```ini
[sp-rg-{id}]
exten => s,1,Set(__SP_TARGET=500)
 same => n,Set(CALLERID(name)={prefix}${CALLERID(name)})        ; only if prefix
 same => n,Dial(Local/101@sp-rg-member&Local/102@sp-rg-member,{ring_seconds},t{m if music_instead_of_ring})
 same => n,GotoIf($["${DIALSTATUS}" = "ANSWER"]?done)
 same => n,{destApp(no_answer_destination)}
 same => n(done),Hangup()
```
`hunt` (one member at a time, in `position` order):
```ini
[sp-rg-{id}]
exten => s,1,Set(__SP_TARGET=500)
 same => n,Dial(Local/101@sp-rg-member,{ring_seconds},t)
 same => n,GotoIf($["${DIALSTATUS}" = "ANSWER"]?done)
 same => n,Dial(Local/102@sp-rg-member,{ring_seconds},t)
 same => n,GotoIf($["${DIALSTATUS}" = "ANSWER"]?done)
 same => n,{destApp(no_answer_destination)}
 same => n(done),Hangup()
```
With zero members, leave out the Dial lines.
Ring groups deliberately **ignore** members' call forwarding and send nobody to voicemail.

### 6.8 Queues

`queues_selfphoneng.conf` (the queue name is its number):
```ini
[550]
strategy = rrmemory
timeout = 15                 ; member_ring_seconds
retry = 5
wrapuptime = 10
maxlen = 0
musicclass = default
announce-frequency = 60      ; 0 when announce_position = false
announce-position = yes
ringinuse = no
setinterfacevar = yes
; when join_when_no_agents = false add these two lines:
joinempty = paused,unavailable,invalid,unknown
leavewhenempty = paused,unavailable,invalid,unknown
member => Local/101@sp-queue-member/n,0,Dan Doe,hint:101@sp-local-numbers
member => Local/102@sp-queue-member/n,0,Ann Lee,hint:102@sp-local-numbers
```
Dialplan:
```ini
[sp-queue-{id}]
exten => s,1,Set(__SP_TARGET=550)
 same => n,Answer()
 same => n,Set(CALLERID(name)={prefix}${CALLERID(name)})         ; only if prefix
 same => n,Gosub(sp-sub-record,s,1)                               ; only if record
 same => n,Queue(550,t,,,{max_wait_seconds})
 same => n,GotoIf($["${QUEUESTATUS}" = "TIMEOUT" | "${QUEUESTATUS}" = "FULL" | "${QUEUESTATUS}" = "JOINEMPTY" | "${QUEUESTATUS}" = "LEAVEEMPTY" | "${QUEUESTATUS}" = "JOINUNAVAIL" | "${QUEUESTATUS}" = "LEAVEUNAVAIL"]?fail)
 same => n,Hangup()
 same => n(fail),{destApp(timeout_destination)}
```
The api handles agent pause/unpause with AMI `QueuePause`, using `Interface: Local/<ext>@sp-queue-member/n`.

### 6.9 IVR

```ini
[sp-ivr-{id}]
include => sp-local-numbers                                      ; only if allow_direct_dial
exten => s,1,Answer()
 same => n,Set(SP_IVR_TRIES=0)
 same => n(menu),Set(TIMEOUT(digit)=3)
 same => n,Background({greeting.asterisk_name})
 same => n,WaitExten({timeout_seconds})
exten => 1,1,{destApp(option 1)}                                 ; one per ivr_options row
exten => i,1,Set(SP_IVR_TRIES=$[${SP_IVR_TRIES} + 1])
 same => n,GotoIf($[${SP_IVR_TRIES} >= {max_retries}]?giveup)
 same => n,Playback({invalid sound or pbx-invalid})
 same => n,Goto(s,menu)
 same => n(giveup),{destApp(invalid_destination)}
exten => t,1,Set(SP_IVR_TRIES=$[${SP_IVR_TRIES} + 1])
 same => n,GotoIf($[${SP_IVR_TRIES} >= {max_retries}]?giveup)
 same => n,Goto(s,menu)
 same => n(giveup),{destApp(timeout_destination)}
```
Known behavior to mention in the UI: with direct dial on, option `1` waits up to
3 s (digit timeout) when internal numbers also start with 1.

### 6.10 Time conditions (business hours)

```ini
[sp-tc-{id}]
exten => s,1,Set(OVR=${DB(SP/TCOVR/{id})})
 same => n,GotoIf($["${OVR}" = "open"]?open)
 same => n,GotoIf($["${OVR}" = "closed"]?closed)
 ; holidays (only if use_holidays): one line per DAY
 same => n,GotoIfTime(*,*,25,dec,America/Chicago?holiday)
 ; open ranges: one line per range
 same => n,GotoIfTime(08:00-17:00,mon&tue&wed&thu&fri,*,*,America/Chicago?open)
 same => n,Goto(closed)
 same => n(open),{destApp(open_destination)}
 same => n(closed),{destApp(closed_destination)}
 same => n(holiday),{destApp(holiday_destination ?? closed_destination)}
```
Holiday rules:
- Expand `start_date..end_date` to single days (max 31; validation rejects longer).
- `GotoIfTime` can't match a year. So a non-recurring holiday is rendered
  only if its date is between `snap.today` and `snap.today + 364 days`.
  Job `nightlyRegenerate` (04 §8) runs at 00:05 local time so past ones drop out.
- Months are written `jan feb mar apr may jun jul aug sep oct nov dec`. Days
  are written `mon tue wed thu fri sat sun`, joined with `&`.
- Validation: `start < end` within a range (no ranges across midnight; the user adds two).

Override codes use `time_conditions.override_digit` (02). Feature codes `*31N` force open,
`*32N` force closed, `*33N` automatic (§6.13).

### 6.11 Announcements, conferences, paging

```ini
[sp-ann-{id}]
exten => s,1,Answer()
 same => n,Playback({sound})
 same => n,{destApp(destination)}

; conference without PINs
[sp-conf-{id}]
exten => s,1,Answer()
 same => n,Set(CONFBRIDGE(bridge,max_members)={max_members})
 same => n,Set(CONFBRIDGE(bridge,record_conference)=yes)           ; only if record
 same => n,ConfBridge({number},default_bridge,default_user,default_menu)
 same => n,Hangup()

; conference with PIN (and optional admin PIN)
[sp-conf-{id}]
exten => s,1,Answer()
 same => n,Set(TRIES=0)
 same => n(ask),Read(PIN,conf-getpin,10,,1,8)
 same => n,GotoIf($["${PIN}" = "{admin_pin}"]?admin)               ; only if admin_pin
 same => n,GotoIf($["${PIN}" = "{pin}"]?user)
 same => n,Set(TRIES=$[${TRIES} + 1])
 same => n,GotoIf($[${TRIES} < 3]?bad)
 same => n,Hangup()
 same => n(bad),Playback(conf-invalidpin)
 same => n,Goto(ask)
 same => n(admin),ConfBridge({number},default_bridge,sp_admin_user,default_menu)
 same => n,Hangup()
 same => n(user),ConfBridge({number},default_bridge,default_user,default_menu)
 same => n,Hangup()

[sp-page-{id}]
exten => s,1,Page(PJSIP/101&PJSIP/102,{d if duplex}iqb(sp-sub-autoanswer^s^1),30)
 same => n,Hangup()
```
Paging only rings desk endpoints (`PJSIP/<ext>`), not `-web`.

`confbridge_selfphoneng.conf` always contains:
```ini
[sp_admin_user]
type = user
admin = yes
marked = yes
music_on_hold_when_empty = yes
```

### 6.12 Outbound routes

Asterisk sorts the patterns inside one context by how specific they are, not by file order, so
"routes in position order" needs one context per route, included in position order (an include
is searched only after the ones before it; verified by the load test and `outbound.test.ts`).
Duplicate patterns inside a route are dropped (a duplicate extension is a load error). When
there are no enabled routes, `sp-outbound-routes` holds `exten => pending,1,Hangup()`.

```ini
[sp-outbound-routes]
; one include per enabled route, in position order
include => sp-or-{id}        ; route name
include => sp-or-{id2}

[sp-or-{id}]
exten => _NXXNXXXXXX,1,Goto(sp-route-{id},1${EXTEN:0},1)     ; strip=0 prepend=1
exten => _1NXXNXXXXXX,1,Goto(sp-route-{id},${EXTEN:0},1)

[sp-or-{id2}]
exten => _011.,1,Goto(sp-route-{id2},${EXTEN},1)

[sp-route-{id}]
exten => _X.,1,Set(__SP_DIRECTION=outbound)
 same => n,GotoIf($[${IF($["${SP_CLASS}" = ""]?0:${SP_CLASS})} < {required_class_number}]?denied)
 same => n,ExecIf($["${SP_RECMODE}" = "outbound" | "${SP_RECMODE}" = "all"]?Gosub(sp-sub-record,s,1))
 ; caller ID priority: route override > user's SP_OUTCID > inbound DID (forwards) > default
 same => n,Set(CID={route override number, or empty})
 same => n,ExecIf($["${CID}" = ""]?Set(CID=${SP_OUTCID}))
 same => n,ExecIf($["${CID}" = ""]?Set(CID=${SP_DID}))
 same => n,ExecIf($["${CID}" = ""]?Set(CID=${SP_DEFAULT_CID}))
 same => n,ExecIf($["${CID}" != ""]?Set(CALLERID(num)=${CID}))
 ; trunk 1 (with optional channel limit)
 same => n,Set(GROUP(sptrunk)={trunk1id})
 same => n,GotoIf($[${GROUP_COUNT({trunk1id}@sptrunk)} > {max_channels}]?t1)   ; only if max_channels (last trunk: ?busy)
 same => n,Dial(PJSIP/${EXTEN}@trunk-{trunk1id},120)
 same => n,GotoIf($["${DIALSTATUS}" != "CHANUNAVAIL" & "${DIALSTATUS}" != "CONGESTION"]?done)
 same => n(t1),Set(GROUP(sptrunk)={trunk2id})                                   ; repeat per trunk
 same => n,Dial(PJSIP/${EXTEN}@trunk-{trunk2id},120)
 same => n,GotoIf($["${DIALSTATUS}" != "CHANUNAVAIL" & "${DIALSTATUS}" != "CONGESTION"]?done)
 same => n(busy),Playback(all-circuits-busy-now)                               ; every trunk full, down or off
 same => n(done),Hangup()
 same => n(denied),Playback(ss-noservice)
 same => n,Hangup()
```
Default routes, created with the first trunk (06 §4), in this order. Toll-free comes first because
`1NXXNXXXXXX` also matches `1800…` and the first matching route wins:

| Name | Patterns | Required class |
|---|---|---|
| Toll-free | `1800NXXXXXX`, `1888NXXXXXX`, `1877NXXXXXX`, `1866NXXXXXX`, `1855NXXXXXX`, `1844NXXXXXX`, `1833NXXXXXX` | local |
| Local/National (NANP) | `NXXNXXXXXX` (prepend `1`), `1NXXNXXXXXX` | national |
| International | `011.` | international — **created disabled** |


### 6.13 Feature codes `sp-featurecodes`

```ini
[sp-featurecodes]
exten => *97,1,Answer()                                     ; my voicemail
 same => n,VoiceMailMain(${SP_EXT}@default)
 same => n,Hangup()
exten => *98,1,Answer()                                     ; any voicemail (asks mailbox)
 same => n,VoiceMailMain(@default)
 same => n,Hangup()
exten => *78,1,Answer()                                     ; DND on
 same => n,Set(DB(SP/DND/${SP_EXT})=1)
 same => n,UserEvent(SpToggle,Key: DND,Ext: ${SP_EXT},Value: 1)
 same => n,Playback(do-not-disturb&activated)
 same => n,Hangup()
exten => *79,1,Answer()                                     ; DND off
 same => n,Set(X=${DB_DELETE(SP/DND/${SP_EXT})})
 same => n,UserEvent(SpToggle,Key: DND,Ext: ${SP_EXT},Value: 0)
 same => n,Playback(do-not-disturb&de-activated)
 same => n,Hangup()
exten => _*72X.,1,Answer()                                  ; *72<number> forward always
 same => n,Gosub(sp-sub-normalize,s,1(${EXTEN:3}))
 same => n,Set(DB(SP/CFU/${SP_EXT})=${GOSUB_RETVAL})
 same => n,UserEvent(SpToggle,Key: CFU,Ext: ${SP_EXT},Value: ${GOSUB_RETVAL})
 same => n,Playback(call-fwd-unconditional&activated)
 same => n,Hangup()
exten => *73,1,Answer()                                     ; cancel forward always
 same => n,Set(X=${DB_DELETE(SP/CFU/${SP_EXT})})
 same => n,UserEvent(SpToggle,Key: CFU,Ext: ${SP_EXT},Value: )
 same => n,Playback(call-fwd-unconditional&de-activated)
 same => n,Hangup()
exten => _**X.,1,PickupChan(PJSIP/${EXTEN:2}-&PJSIP/${EXTEN:2}-web-)   ; directed pickup **101
 same => n,Hangup()
; *8 group pickup is handled by features.conf pickupexten + named pickup groups
exten => *43,1,Answer()                                     ; echo test
 same => n,Playback(demo-echotest)
 same => n,Echo()
 same => n,Playback(demo-echodone)
 same => n,Hangup()
exten => *65,1,Answer()                                     ; say my extension
 same => n,SayDigits(${SP_EXT})
 same => n,Hangup()
exten => _*45X.,1,Answer()                                  ; *45<queue> toggle queue login
 same => n,Set(Q=${EXTEN:3})
 same => n,Set(K=SP/QPAUSE/${Q}/${SP_EXT})
 same => n,GotoIf($["${DB(${K})}" = "1"]?login)
 same => n,Set(DB(${K})=1)
 same => n,PauseQueueMember(${Q},Local/${SP_EXT}@sp-queue-member/n)
 same => n,UserEvent(SpToggle,Key: QPAUSE,Queue: ${Q},Ext: ${SP_EXT},Value: 1)
 same => n,Playback(agent-loggedoff)
 same => n,Hangup()
 same => n(login),Set(X=${DB_DELETE(${K})})
 same => n,UnpauseQueueMember(${Q},Local/${SP_EXT}@sp-queue-member/n)
 same => n,UserEvent(SpToggle,Key: QPAUSE,Queue: ${Q},Ext: ${SP_EXT},Value: 0)
 same => n,Playback(agent-loginok)
 same => n,Hangup()
exten => _*80X.,1,Page(PJSIP/${EXTEN:3},db(sp-sub-autoanswer^s^1),30)   ; intercom
 same => n,Hangup()
; time condition overrides *31N open, *32N closed, *33N auto (admins only)
exten => _*3[123]X,1,Answer()
 same => n,GotoIf($["${GLOBAL(SP_TCADMIN_${SP_EXT})}" != "1"]?deny)
 same => n,Goto(sp-tc-override,${EXTEN},1)
 same => n(deny),Playback(ss-noservice)
 same => n,Hangup()
```
The generator also writes `[sp-tc-override]`, with three lines per time condition that has an `override_digit`:
```ini
[sp-tc-override]
exten => *311,1,Set(DB(SP/TCOVR/{id})=open)
 same => n,UserEvent(SpToggle,Key: TCOVR,Id: {id},Value: open)
 same => n,Playback(activated)
 same => n,Hangup()
exten => *321,1,Set(DB(SP/TCOVR/{id})=closed)  ... (same shape, Value: closed)
exten => *331,1,Set(X=${DB_DELETE(SP/TCOVR/{id})}) ... (Value: auto)
```
**Forward validation:** when the api receives `SpToggle Key: CFU` it checks the
target against the user's outbound class (04 §5.3). If it isn't allowed, the api
deletes the AstDB key, stores nothing, and logs an audit entry. Dialplan also
limits forwards via `SP_CLASS_<ext>` in `sp-sub-forward`.

Sound names like `do-not-disturb`, `call-fwd-unconditional`, `agent-loginok`
come from the Asterisk core/extra sound packs. If one is missing, swap in
`beep` and note it in the spec.

### 6.14 Emergency calls

**Never block a 911 call for any reason.** Not class, not missing caller ID,
not trunk limits, not DND.

```ini
[sp-emergency-dial]
exten => 911,1,Goto(sp-emergency,s,1)
exten => 9911,1,Goto(sp-emergency,s,1)          ; people who dial 9 first out of habit

[sp-emergency]
exten => s,1,Set(CID=${IF($["${SP_E911CID}" != ""]?${SP_E911CID}:${SP_DEFAULT_E911_CID})})
 same => n,UserEvent(SpEmergency,Ext: ${SP_EXT},CallerId: ${CID},Dialed: 911)
 same => n,ExecIf($["${CID}" != ""]?Set(CALLERID(num)=${CID}))
 same => n,Set(__SP_DIRECTION=outbound)
 same => n,Dial(PJSIP/911@trunk-{trunk1id})     ; every ENABLED trunk, in name order, no limits
 same => n,Dial(PJSIP/911@trunk-{trunk2id})
 same => n,Hangup()
```
The `SpEmergency` event triggers notifications (04 §5.3, 06 §6). For the
"ring a notification phone" part, the api originates a call into this static context:

```ini
[sp-emergency-alert]
; Originated by the api: Channel PJSIP/<notify ext>, Context sp-emergency-alert, Exten <caller ext>
exten => _X!,1,Answer()        ; X! also matches a one-digit "0" (caller unknown, or a test)
 same => n,Wait(1)
 same => n,Playback(beep&beep&beep)
 same => n,Playback(extension)
 same => n,SayDigits(${EXTEN})
 same => n,Playback(beep&beep&beep)
 same => n,Playback(extension)
 same => n,SayDigits(${EXTEN})
 same => n,Hangup()
```
(If an admin uploads a sound named `emergency-alert`, play `custom/emergency-alert` first.)

## 7. `voicemail_selfphoneng.conf`

```ini
[general]
format = wav
attach = no                 ; the api sends emails itself
maxmsg = {voicemail.maxMessages}
maxsecs = {voicemail.maxMessageSeconds}
minsecs = 1
maxsilence = 10
silencethreshold = 128
maxlogins = 3
envelope = yes
saycid = yes
review = no
nextaftercmd = yes
sendvoicemail = no
pollmailboxes = yes
pollfreq = 30

[zonemessages]
local = {general.timezone}|'vm-received' Q 'digits/at' IMp

[default]
101 => {pin},{name},,,tz=local|attach=no
```
Only extensions with `voicemail_enabled` get a line.

## 8. `musiconhold_selfphoneng.conf`

```ini
[{class.name}]
mode = files
directory = /var/lib/asterisk/moh/{class.name}
sort = random
```
One per `moh_classes` row. The api keeps the folder contents in sync with `sound_files` (04 §6).

## 9. Snapshot → endpoint variables summary

| Variable | Where set | Read by |
|---|---|---|
| `SP_EXT` | endpoint `set_var` | feature codes, emergency |
| `SP_CLASS` | endpoint `set_var`; `sp-sub-forward`; `sp-ext-forward` | `sp-route-*` |
| `SP_OUTCID` | endpoint `set_var` | `sp-route-*` |
| `SP_E911CID` | endpoint `set_var` | `sp-emergency` |
| `SP_RECMODE` | endpoint `set_var` | `sp-route-*` |
| `SP_DIRECTION` | `sp-from-trunk-*`, `sp-route-*`, endpoint | `sp-sub-user`, CDR |
| `SP_DID` | `sp-inbound` | `sp-route-*` (forwards), CDR |
| `SP_TARGET` | object contexts | live state |
| `SP_REC` | `sp-sub-record` | CDR → recordings |
| `SP_FWDHOPS`, `SP_FORWARDED` | forwards | loop guard |

## 10. Example: life of an inbound call

voip.ms sends `INVITE sip:3125551234@us` → PJSIP matches identify →
endpoint `trunk-X` → context `sp-from-trunk-X`, exten `3125551234` →
normalize to `13125551234` → it's in `sp-did-exists` → caller number
normalized, not blocked → `Goto(sp-inbound,13125551234,1)` → sets `SP_DID`
→ `Goto(sp-tc-T,s,1)` → it's Tuesday 10:00, open → `Goto(sp-ivr-I,s,1)` →
caller presses 2 → `Goto(sp-local-numbers,101,1)` → `sp-sub-user(101,25,1,never)`
→ not DND, no forward → rings `PJSIP/101` desk phone + `PJSIP/101-web` browser
→ no answer in 25 s → `VoiceMail(101@default,u)` → the api sees a new
`msg0000.txt` → emails the user.

## 11. Things the generator must NOT do

- Hard-code any number, DID, IP or password.
- Emit `chan_sip` config.
- Use `System()`, `Shell()`, `AGI()` or `TrySystem()`. Talk to the api with `UserEvent` only.
- Write anything outside `/etc/asterisk/selfphoneng/`.

## 12. Tests

1. **Golden tests** (`apps/api/src/generator/__golden__/<case>/`):
   `snapshot.json` + `expected/<file>.conf`. Test: `render(snapshot)` equals
   expected byte for byte. `UPDATE_GOLDEN=1 pnpm test` rewrites the expected
   files. **A human (or reviewer agent) must read the diff** before committing.
   Required cases: `empty`, `one-user`, `voipms-basic` (2 users, 1 trunk, 1 DID → user),
   `ivr-business-hours`, `ringgroups`, `queue`, `outbound-routes`, `holidays`,
   `hostile-names` (sanitizer coverage), `webrtc-disabled`.
2. **Determinism test:** render the same snapshot twice with shuffled array order → identical output.
3. **Asterisk load test** (integration, `pnpm test:asterisk`): start the asterisk
   container with each golden case's files, then run over AMI
   `dialplan show sp-local-numbers`, `pjsip show endpoints`, `queue show`.
   Fail if Asterisk logs `ERROR` while loading.
4. **Call tests** (M3+, SIPp scenarios in `apps/api/test/sipp/`): register 101,
   call 102, answer, BYE. Inbound from a fake trunk → IVR → digit → user.