# 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},include_local_address
{/if}
```
(`network.lanIp` is the server's own LAN address, see `02-data-model.md` §3.)
`include_local_address` keeps the LAN host candidate next to the public one. Without it a browser
on the LAN only gets the public address and needs hairpin NAT, which many routers lack (M5-T1).

## 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
verify_server = yes                       ; as built (M11-T2): check the provider (08 §2.1)
ca_list_file = /etc/ssl/certs/ca-certificates.crt
{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`. Added in M11-T2 (the api mounts it read-only too, as `TLS_DIR`).
- 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
mwi_subscribe_replaces_unsolicited = yes  ; omit if voicemail disabled. The AOR also sends unsolicited MWI;
                                   ; without this a phone that SUBSCRIBEs gets 500 "already configured
                                   ; for unsolicited MWI" (checked on 24.0.0-rc2, M4-T1)
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
from_domain = selfphoneng.invalid  ; else the From host is the machine's hostname; SIP.js drops
                                   ; INVITEs whose host label starts with a digit (M5-T1)
callerid = "Dan Doe" <101>
mailboxes = 101@default
mwi_subscribe_replaces_unsolicited = yes
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}
identify_by = ip                    ; M11-T8: no inbound auth, so never match by From username
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`.
As built (M11-T2): TLS trunks get `qualify_frequency = 0` (Asterisk 24 checks a qualify's certificate
against the IP, see 08 §2.1); their health comes from the registration.
`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).
; A call from outside shows the caller's name from this user's contacts (11 §6 C4): set on each
; ringing leg only (sp-predial-cnam), never on the call itself, so a forward or the next member
; never sees someone else's contact name.
[sp-sub-dial-user]
exten => s,1,Set(DS=)
 same => n,Gosub(sp-sub-contacts,s,1(${ARG1}))
 same => n,Gosub(sp-sub-contacts,s,1(${ARG1}-web))
 same => n,GotoIf($["${DS}" = ""]?unavail)
 same => n,GotoIf($["${SP_DIRECTION}" != "inbound" | "${SP_CNAM_URL}" = ""]?plain)
 same => n,Gosub(sp-sub-cnam,s,1(${ARG1}))
 same => n,GotoIf($["${GOSUB_RETVAL}" = ""]?plain)
 same => n,Set(_SP_CNAM=${SP_CNAM_PREFIX}${GOSUB_RETVAL})
 same => n,Dial(${DS},${ARG2},txb(sp-predial-cnam^s^1))
 same => n,Set(_SP_CNAM=)
 same => n,Return()
 same => n(plain),Dial(${DS},${ARG2},tx)
 same => n,Return()
 same => n(unavail),Set(DIALSTATUS=CHANUNAVAIL)
 same => n,Return()

; ─── The caller's name in user ARG1's contacts, or "" (none, or the api didn't answer in 2 s).
; The api only answers this machine with the key, and only letters, digits and . ' & @ - come back.
[sp-sub-cnam]
exten => s,1,Set(CURLOPT(conntimeout)=1)
 same => n,Set(CURLOPT(httptimeout)=2)
 same => n,Return(${CURL(${SP_CNAM_URL}?ext=${FILTER(0-9,${ARG1})}&number=${FILTER(0-9,${CALLERID(num)})}&token=${SP_CNAM_TOKEN})})

; ─── Pre-dial handler on each ringing leg: the name its phone shows.
[sp-predial-cnam]
exten => s,1,Set(CONNECTEDLINE(name,i)=${SP_CNAM})
 same => n,Return()

; ─── Add AOR ARG1's reachable contacts to DS as PJSIP/<ARG1>/<uri>. Not PJSIP_DIAL_CONTACTS: iOS
; Linphone's push params (pn-prid=…:voip&…:remote) hold '&', which splits Dial's device list.
; pn-* only matter to a push server, so they're dropped; FILTER keeps whatever else a phone puts
; in its Contact from reaching Dial's options (',') or another device ('&').
[sp-sub-contacts]
exten => s,1,Set(LOCAL(CL)=${PJSIP_AOR(${ARG1},contact)})
 same => n(next),Set(LOCAL(C)=${POP(CL)})
 same => n,GotoIf($["${C}" = ""]?done)
 same => n,Set(LOCAL(ST)=${PJSIP_CONTACT(${C},status)})
 same => n,GotoIf($["${ST}" = "Unavailable" | "${ST}" = "Unreachable"]?next)
 same => n,Set(LOCAL(U)=${PJSIP_CONTACT(${C},uri)})
 same => n,Set(LOCAL(D)=${CUT(U,\;,1)})
 same => n,Set(LOCAL(I)=1)
 same => n(param),Set(I=$[${I} + 1])
 same => n,GotoIf($[${I} > ${FIELDQTY(U,\;)}]?add)
 same => n,Set(LOCAL(P)=${CUT(U,\;,${I})})
 same => n,GotoIf($["${P:0:3}" = "pn-"]?param)
 same => n,Set(D=${D}\;${P})
 same => n,Goto(param)
 same => n(add),Set(DS=${DS}${IF($["${DS}" = ""]?:&)}PJSIP/${ARG1}/${FILTER(0-9a-zA-Z.:@\;=_+%[]\x2d,${D})})
 same => n,Goto(next)
 same => n(done),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_LIMITEXT=${ARG2})                    ; counts toward that extension's call limit
 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.
The caller-name prefix (here and on DIDs) goes through `name()`, which trims, so one space is
always put between it and the caller's name: `Set(CALLERID(name)={prefix} ${CALLERID(name)})`.
Golden case `ringgroups`; `scripts/e2e/m6-t2.mjs` checks ring-all and hunt with real calls (M6-T2).

### 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),UserEvent(SpQueueExit,Queue: 550,Status: ${QUEUESTATUS})
 same => n,{destApp(timeout_destination)}
```
The api handles agent pause/unpause with AMI `QueuePause`, using `Interface: Local/<ext>@sp-queue-member/n`.
`SpQueueExit` is for the stats (04 §7.3): Asterisk 24 raises `QueueCallerAbandon` for timeouts too, and
callers turned away (`FULL`, `JOINEMPTY`) never join. Member lines are sorted by extension; a member
name that sanitizes to nothing is replaced by the extension number.
As built (M8-T1): golden case `queue`; `pnpm test:asterisk` also checks `queue show <n>` lists each
queue's members; `scripts/e2e/m8-t1.mjs` runs 3 callers, 2 agents, `*45550`, a UI pause and a timeout
with real phones.

### 6.9 IVR

```ini
[sp-ivr-{id}]
include => sp-ivr-direct                                         ; 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)}
```
Changed in M11-T8: direct dial used to include `sp-local-numbers`, which let an outside caller dial a
paging group (the office speakers, and with duplex, listen in) or a parking slot (someone else's
call). `sp-ivr-direct` (rendered when any IVR has direct dial) holds one
`exten => {n},1,Goto(sp-local-numbers,{n},1)` per user, ring group, queue, conference room and IVR;
`ivr-direct.test.ts`.
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.
Options are sorted by key; `#` and `*` work as extension names (checked by the `ivr` golden case
loading into Asterisk 24). An option may point at its own IVR ("press 9 to hear this again"); the
api drops an IVR's own options before checking references on delete (M6-T3).

### 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).

As built (M6-T4):
- A range's `end` is exclusive ("closed at 17:00") but `GotoIfTime`'s end minute is inclusive, so
  ranges render one minute short: `08:00-16:59`; `24:00` (end of day) renders `23:59`.
- Holiday days are deduplicated and sorted by month/day; a range over New Year works.
- `[sp-tc-override]` is always rendered, ending with `exten => _*3[123]X` → `ss-noservice` for
  digits no office hours use. `*33N` plays `de-activated`.
- The api's "open now" (`timeConditionStatus` in `packages/shared`) makes the same decision.
- Holidays roll over by re-rendering when the company date changes (a 10-minute check in
  `index.ts`) instead of a croner job at 00:05; M11-T4 can move it into the jobs.
- Golden cases `holidays` and `ivr-business-hours`; `scripts/e2e/m6-t4.mjs` checks force
  open/closed routing, `*321`/`*331` from an admin phone, and refusal for a non-admin.

### 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,Set(__SP_TARGET={number})
 same => n,Answer()
 same => n,Gosub(sp-sub-record,s,1)                               ; only if record
 same => n,ConfBridge({number},sp_room_{number},default_user,default_menu)
 same => n,Hangup()

; conference with PIN (and optional admin PIN)
[sp-conf-{id}]
exten => s,1,Set(__SP_TARGET={number})
 same => n,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},sp_room_{number},sp_admin_user,default_menu)   ; (admin) on the Gosub when recorded
 same => n,Hangup()
 same => n(user),ConfBridge({number},sp_room_{number},default_user,default_menu)
 same => n,Hangup()

[sp-page-{id}]
exten => s,1,Page(PJSIP/101&PJSIP/102,{d if duplex}iqsb(sp-sub-autoanswer^s^1),30)
 same => n,Hangup()
```
Paging only rings desk endpoints (`PJSIP/<ext>`), not `-web`. As built (M8-T4): `s` added, so phones
already on a call aren't paged; that includes the pager when they're a member themselves. A group
with no members is `exten => s,1,Hangup()`. Paging groups aren't call destinations. Golden case
`paging`; `scripts/e2e/m8-t4.mjs` pages with real calls (baresip phones that honor the auto-answer
headers, like Yealink/Grandstream do; a real desk phone is still to be checked).

`confbridge_selfphoneng.conf` always contains the admin profile, plus one bridge profile per room:
```ini
[sp_admin_user]
type = user
admin = yes
marked = yes
music_on_hold_when_empty = yes

[sp_room_800](default_bridge)        ; room 800
max_members = 20
```
As built (M8-T3), changed from the first draft: `Set(CONFBRIDGE(bridge,max_members)=…)` before
`ConfBridge(…,default_bridge,…)` is ignored (a 4th caller got into a room of 3 on Asterisk 24), so
each room has its own bridge profile. A recorded room runs `sp-sub-record` on each caller's leg,
just before `ConfBridge()`, instead of `record_conference`: the files are ordinary call recordings
(call history, Recordings page, retention). That is one file per participant, and a caller turned
away from a full room leaves a few seconds of recording too. Golden case `conferences`;
`scripts/e2e/m8-t3.mjs` checks PIN, admin PIN, the limit and recordings with real calls.

### 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${FILTER(0-9*#+,${EXTEN:0})},1)     ; strip=0 prepend=1
exten => _1NXXNXXXXXX,1,Goto(sp-route-{id},${FILTER(0-9*#+,${EXTEN:0})},1)

[sp-or-{id2}]
exten => _011.,1,Goto(sp-route-{id2},${FILTER(0-9*#+,${EXTEN:0})},1)
; FILTER (M11-T8): SIP allows "," and "&" in a dialed number. "011…,4" made this
; Goto(sp-route-{id2},011…,4,1), which starts past the class check (trunk-test.ts proves it).

[sp-route-{id}]
exten => _X.,1,Set(__SP_DIRECTION=outbound)
 same => n,GotoIf($[${IF($["${SP_CLASS}" = ""]?0:${SP_CLASS})} < {required_class_number}]?denied)
 ; outside calls at once (calls.maxPerExtension, calls.maxTotal; a line pair is left out when its
 ; setting is 0, and with no total the per-extension skip goes to n(counted),NoOp()). A forward
 ; counts for the extension whose forward it is (SP_LIMITEXT from sp-sub-forward); a call with no
 ; extension (sp-ext-forward) only in the total. call-limits.test.ts, trunk-test.ts.
 same => n,Set(SP_LIMITEXT=${IF($["${SP_LIMITEXT}" = ""]?${SP_EXT}:${SP_LIMITEXT})})
 same => n,GotoIf($["${SP_LIMITEXT}" = ""]?total)
 same => n,Set(GROUP(spext)=${SP_LIMITEXT})
 same => n,GotoIf($[${GROUP_COUNT(${SP_LIMITEXT}@spext)} > {calls.maxPerExtension}]?busy)
 same => n(total),Set(GROUP(spout)=all)
 same => n,GotoIf($[${GROUP_COUNT(all@spout)} > {calls.maxTotal}]?busy)
 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,Gosub(sp-sub-vmlimit,s,1)                         ; 1 at a time, 10/hour per phone (08 §6)
 same => n,GotoIf($["${GOSUB_RETVAL}" != "ok"]?full)
 same => n,VoiceMailMain(${SP_EXT}@default)
 same => n,Hangup()
 same => n(full),Playback(an-error-has-occurred)
 same => n,Hangup()
exten => *98,1,Answer()                                     ; any voicemail (asks mailbox)
 same => n,Gosub(sp-sub-vmlimit,s,1)
 same => n,GotoIf($["${GOSUB_RETVAL}" != "ok"]?full)
 same => n,VoiceMailMain(@default)
 same => n,Hangup()
 same => n(full),Playback(an-error-has-occurred)
 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,Set(T=${FILTER(0-9,${EXTEN:2})})        ; digits only: "&" or "," would add arguments
 same => n,PickupChan(PJSIP/${T}-&PJSIP/${T}-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=${FILTER(0-9,${EXTEN:3})})
 same => n,Set(K=SP/QPAUSE/${Q}/${SP_EXT})
 same => n,GotoIf($["${DB(${K})}" = "1"]?login)
 same => n,PauseQueueMember(${Q},Local/${SP_EXT}@sp-queue-member/n)
 same => n,GotoIf($["${PQMSTATUS}" != "PAUSED"]?deny)        ; not an agent of that queue
 same => n,Set(DB(${K})=1)
 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,GotoIf($["${UPQMSTATUS}" != "UNPAUSED"]?deny)
 same => n,UserEvent(SpToggle,Key: QPAUSE,Queue: ${Q},Ext: ${SP_EXT},Value: 0)
 same => n,Playback(agent-loginok)
 same => n,Hangup()
 same => n(deny),Playback(ss-noservice)
 same => n,Hangup()
exten => _*80X.,1,Set(T=${FILTER(0-9,${EXTEN:3})})            ; *80<ext> intercom, both ways
 same => n,GotoIf($["${T}" != "${EXTEN:3}"]?deny)
 same => n,GotoIf($["${PJSIP_ENDPOINT(${T},context)}" != "sp-from-ext"]?deny)   ; desk phones only
 same => n,Page(PJSIP/${T},db(sp-sub-autoanswer^s^1),30)
 same => n,Hangup()
 same => n(deny),Answer()
 same => n,Playback(ss-noservice)
 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`.

As built (M6-T7): everything above except `*45` (queues) and `*80` (intercom), which come with M8.
`*80` (M8-T4) only pages a desk phone: digits only (no `&` sneaking in another channel), and the
endpoint must exist with context `sp-from-ext`; anything else plays `ss-noservice`.
`*45` (M8-T1) checks `PQMSTATUS`/`UPQMSTATUS`, so a code for a queue the caller isn't an agent of plays
`ss-noservice` and stores nothing (the original snippet stored the key and said "logged off" anyway).
`*8` also has a dialplan line (`Pickup()`): `pickupexten` only catches it straight from a phone's
INVITE. All the sounds used exist in the image (checked).

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. Names go through `name()` (no commas or `|`),
the time zone through `timezone()`. Until M6-T7, `sp-featurecodes` holds only `*97`/`*98`.
Checked live by `apps/api/test/asterisk/voicemail-test.ts` (M4-T1): leave a message, MWI NOTIFY
to a subscribed phone, `*97` login and playback, MWI off.

## 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).

As built (M8-T5): one per `moh_classes` row **that has at least one file**. An empty class plays
silence in Asterisk 24; left out, a channel asking for it gets `default` instead (checked with a
real queue caller). Because only the first and last file change this file, the api also sends
`moh reload` after every file it adds or removes. Golden case `queue`; `scripts/e2e/m8-t5.mjs`.

Since 2026-10-21 (owner: "whichever was uploaded first is always queued first"), a class is a
playlist in the order set on Sounds & music, with an optional shuffle:

```ini
[{class.name}]
mode = playlist
entry = /var/lib/asterisk/moh/{class.name}/{sound_files.id}   ; by sound_files.position, no extension
sort = random                                                ; only with moh_classes.shuffle
```

New uploads go last; `PATCH /api/moh-classes/:id {shuffle, order}` (order: every file id once).
Without shuffle each caller on hold starts at the first entry. `sort = random` picks each next
file at random in playlist mode too (res_musiconhold's randomize flag). `moh-test.ts` plays both
kinds in a real Asterisk and reads the order of the files it opens from its debug log.

## 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 |
| `SP_LIMITEXT` | `sp-sub-forward`; else `SP_EXT` in `sp-route-*` | call limits (group `spext`) |

## 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.