# AGENTS.md

Guidance for LLM agents working in this repository. What each file in it is for is under
[Documentation](#documentation).

## What this is

A ground-up TypeScript rewrite of `larvitsmpp` 0.4.0, published as `@larvit/smpp` 1.0.0. The branch
started from an orphan commit — no history from 0.4.0 is carried over. The 0.4.0 source is still
readable on the `master` branch of the same repository and is the reference for protocol behaviour,
not for structure or style.

## Goals

In priority order, and the order is the point: where two of them pull against each other, the earlier
one wins. They do not override the hard rules below.

1. **Correct on the wire.** SMPP 3.4 as SMSCs actually run it. Every other goal yields to this one;
   the defect table below is what the alternative costs.
2. **Never give the application a wrong answer about what happened.** An outcome we cannot determine
   is reported as undetermined rather than guessed; a report the peer marked as not final settles
   nothing, so nothing the library concludes may rest on one; a request the peer may already have
   taken is never re-sent on the library's own initiative; work the peer has no reason to send again
   is not dropped.
3. **Strict in what we send, generous in what we read.** The library's own senders follow 3.4, and
   the codec parses whatever arrives. Where the letter of the spec would discard traffic a real SMSC
   sends, keep the traffic.
4. **A peer an operator never has to complain about.** No bind flooding, nothing a bind direction
   forbids, no optional parameters to a peer that declared none, nothing held without a bound.
5. **The session layer is in here, and its defaults are what most applications should run.**
   Keepalive, reconnect, the send window, reassembly and receipt correlation. What the network says
   about a message the application sent reaches it as a report rather than as an inbound message, and
   says whether it is final, so nothing has to read the PDU to tell those apart. An option retunes a
   default or opts out of it; an option does not switch on the thing the caller obviously wanted.
6. **A small, stable public surface over reshapeable internals.** Only what `src/index.ts` exports is
   published. A new option has to beat "the application can do this itself", and has to keep a
   promise this library can verify. The low-level surface is a passthrough: policy binds what the
   library composes, never what the caller wrote.
7. **Nothing that needs state wider than one session.** No throughput throttling, no persistence
   across a restart, no coordination between processes — and no seam handing the application state to
   persist for one of those either, which commits to the same scope through the back door and
   publishes an internal shape to do it. This is the scope floor, and it is why an otherwise
   reasonable feature is declined without a fresh argument each time.
8. **It builds, tests and runs the same everywhere.** Container-only toolchain, no runtime
   dependencies, the Node 18 floor verified in CI rather than asserted, every README example executed
   by the suite.

## Hard rules

These are not preferences. Breaking one is a defect.

1. **Nothing throws.** Every fallible function returns (or resolves to) a DTO carrying an optional
   `err`. No `throw`, no rejected promises, no exceptions as control flow. Node APIs that throw are
   wrapped at the boundary and converted into a result. Programmer errors (bad arguments) are
   results too.
2. **Log messages are static strings.** Every dynamic value goes into the log metadata. Never
   interpolate, never concatenate.
   - GOOD: `log.debug('sendSms() - splitting message', { parts: msgs.length, to });`
   - BANNED: `log.debug('sendSms() - splitting into ' + msgs.length + ' parts');`
3. **No `error` event.** Node makes an unhandled `error` event throw, which would break rule 1.
   Sessions emit `sessionError`, servers emit `serverError`.
4. **No casts, no non-null assertions.** `as`, `as unknown as` and `!` are all banned. Parse untyped
   input once through a type guard at the boundary; everything past it is typed. `noUncheckedIndexedAccess`
   is on, so every lookup into a record or buffer is `T | undefined` until you handle it — that is the
   point, not an obstacle to route around.

## Architecture

```
src/
	index.ts             Public surface. Named exports only, no default export.
	client.ts            client() -> { err, session }
	server.ts            server() -> { err, server }, server owns the listener + close()
	session.ts           Session: the socket's life, dispatch, events, and the collaborators below
	sms.ts               The live handle emitted as the 'sms' event (sendResp/sendDlr)
	dlr.ts               Delivery receipts: text and TLV parsing, receipt status codes
	dlr-merger.ts        DlrMerger: per-segment receipts counted into one MessageDlr
	error-from.ts        errorFrom(): whatever was thrown or rejected, as an Error
	expiring-groups.ts   ExpiringGroups: the capped, expiring store both of those share
	held-messages.ts     HeldMessages: capped, expiring messages the application has not answered
	idle-waiters.ts      IdleWaiters: waiting for a count to fall to zero, and what is left of a budget
	incoming-requests.ts Every request the peer sends: messages, receipts, links, unknown commands
	link-gate.ts         LinkGate: where a request with no link to go out on waits for the next one
	link-timers.ts       LinkTimers: the enquire_link heartbeat and the idle timeout
	log.ts               SmppLog, the logger contract, and silentLog — the default
	message.ts           Encoding detection, splitting, bit counting, SMPP date formatting
	outgoing-requests.ts OutgoingRequests: the gate, the window, the pending map and the retry
	pdu.ts               pduToObj / objToPdu / pduReturn — synchronous, result-returning
	pdu-framer.ts        PduFramer: a byte stream cut into complete PDUs
	pdu-refusal.ts       A PDU the codec would not read, and the answer SMPP names for it
	pdu-transport.ts     PduTransport: the socket a session reads complete PDUs off
	pending-requests.ts  PendingRequests: sequence numbers, correlation, timeout, abort
	reassembly.ts        Reassembler: capped, expiring multipart groups
	reconnect-loop.ts    ReconnectLoop: backoff, retry timer, stopped-ness
	result.ts            Result<T> — the shape every fallible call returns
	send-sms.ts          submitSms composition and the submitSmParams builder
	send-window.ts       SendWindow: the maxOutstanding semaphore
	session-options.ts   SessionOptions, ReconnectOptions, bind direction and the session defaults
	sms-id.ts            The notation a peer writes message ids in, normalised for comparison
	udh.ts               User data header: its length, the concatenation fields of a long SMS and their reference
	unanswered-error.ts  UnansweredError: it went out and no answer came back
	uuid.ts              uuidv7() — the ids the library generates for messages
	defs/
		commands.ts      The 33 commands, their ids and ordered parameter lists
		constants.ts     consts + constsById, and the SMPP version constants
		encodings.ts     GSM 03.38, LATIN1, UCS2, detection, data_coding resolution
		errors.ts        errors + errorsById (ESME_*)
		tlvs.ts          TLV definitions, tlvsById
		types.ts         Wire types: int8/int16/int32/string/cstring/buffer/arrays
```

Dependency direction is one way: `defs` knows nothing above it, `pdu` uses `defs`, `session` uses
`pdu`, and `client`/`server` use `session`. Nothing reaches back up.

**Parameter order is wire order.** The key order inside `cmds.*.params` is the order the fields are
written to and read from the buffer. Never sort those alphabetically — the alphabetical-ordering
convention applies everywhere else, but here it corrupts every PDU.

## Toolchain

Run everything through the container; never invoke node or npm on the host.

```bash
docker compose run --rm node npm install
docker compose run --rm node npm test
docker compose run --rm node npm run build
```

- Tests are `.ts` and run directly under Node's type stripping — no build step in the dev loop.
- Source imports use `.ts` extensions; `rewriteRelativeImportExtensions` emits `.js` into `dist`.
- `erasableSyntaxOnly` is on, so no enums, no namespaces, no parameter properties. Use `as const`
  objects plus union types.
- The published floor is Node 18, but the dev container runs Node 24 (type stripping needs it). CI
  compiles the tests and runs them on 18/20/22/24, so the floor is verified rather than asserted.
- `typescript` is pinned to the 6.x line because `typescript-eslint` peer-requires `<6.1.0`. Move to
  TypeScript 7 once that constraint lifts.

## Defects found in 0.4.0

Every row names what 0.4.0's own code did, so it is not rebuilt here.
[README.md](README.md#behaviour-that-changed-on-the-wire) names what changed for a consumer, and is
the only place that does. Confirmed by reading the 0.4.0 source; each row has a regression test
naming the behaviour.

| Defect | 0.4.0 behaviour |
| --- | --- |
| LATIN1 never decodes | `decodeMsg` loops `consts.ENCODING` without breaking, so `data_coding` 0x03 lands on the alias `ISO_8859_1`, which has no decoder, and silently falls back to ASCII |
| Short segments | `splitMsg` accumulates a full segment then pushes `msgPart.slice(0, -1)`, so every segment is one character short: 152 GSM characters instead of 153, 66 UCS2 instead of 67. Long messages are split into more segments than they need, and each extra segment is billed |
| DLR month off by one | `smppDate()` uses `getMonth()` (0-based) without `+1`, so January renders as `00` |
| Non-standard DLR status | Receipts emit `stat:UNDELIVERABLE`; the spec's field is 7 characters (`UNDELIV`) |
| Flash destroys UCS2 | `flash: true` overwrites `data_coding` with 0x10, discarding the UCS2 alphabet, which needs 0x18 |
| Shared concat reference | The concatenation reference counter is a module-level global shared by every session in the process |
| `send()` never times out | Each call adds a listener keyed on the sequence number; a peer that never answers leaks it and the promise never settles |
| `tls: true` is not TLS | Constructs a bare `new tls.Socket()` with no handshake instead of `tls.connect()` |
| Alphanumeric sender TON | `sendSms` hardcodes `source_addr_ton` to 1 (international) even for alphanumeric senders, which require TON 5 |
| Text-only DLRs refused | `deliver_sm` without both `message_state` and `receipted_message_id` TLVs is rejected with `ESME_RINVTLVSTREAM`, so Kannel-style receipts are unusable |
| Unbounded reassembly | Incomplete long-SMS groups are capped by nothing and swept only when other traffic arrives, after 24 hours |
| Dead DLR aggregation | `longSmsDlrs` is allocated to merge per-segment receipts and then never used |
| Trailing NULL truncation | `types.buffer.size()` subtracts one whenever the value's last octet is `0x00`, so the PDU is allocated one octet short while `sm_length` still reports the full length. Any UCS2 message ending in a character like U+4E00 or U+3000 goes out corrupt |
| Dormant filters | `defs.filters` is declared on commands and TLVs but never invoked anywhere |
| Unchecked reads | Wire reads index straight into the buffer, so a short or malformed PDU throws out of the codec |
| Unrangechecked writes | Integer params are handed to `writeUInt8`/`writeUInt16BE` unvalidated, so an out-of-range value throws from inside Node |
| `submit_multi` missing `sm_length` | The field is commented out of the command table, so `short_message` never round-trips for that command |
| Per-parameter defaults never applied | `calcCmdLength` reads `paramType.default` (the wire type's) rather than the parameter's, so `interface_version: 0x50` on the bind commands did nothing and every bind declared version 0x00 |
| `source_telematics_id` width | Defined as a 2-octet integer; SMPP 3.4 5.3.2.8 makes it 1 octet, unlike `dest_telematics_id`, which really is 2 |
| Binary payloads decoded as text | `data_coding` 0x02, 0x04, 0x14 and 0xF4-0xF7 are 8-bit binary and land on the GSM 03.38 table, which rewrites every octet outside it |
| Binary TLVs round-trip corrupt | `pduToObj` turns a `Buffer` TLV value into a hex string (`utils.js:307`), and `objToPdu` writes that string back as its own ASCII, so `message_payload`, `network_error_code`, `callback_num` and the rest are destroyed by any round trip |
| `ESME_RINVBCASTCHANIND` typo | Defined as `0x011`, three hex digits; the spec value is `0x0112` |

## Multipart sends and the send window

`sendSms` puts every segment of a message on the wire together instead of waiting for each response
in turn. This is not an optimisation: this library's own server holds segments until the whole
message is reassembled before it answers any of them, so sending them one-after-a-response
deadlocks. It follows that a message with more segments than `maxOutstanding` cannot be delivered to
a server that defers responses that way — real SMSCs answer each `submit_sm` immediately, so this
only bites when both ends are this library.

## GSM 7-bit is sent unpacked

Over SMPP the ESME puts one GSM character per octet in `short_message` and the SMSC packs it into
septets. The 140-octet limit applies to that packed result, not to what goes on the wire here, which
is why a concatenated segment is 153 characters plus a 6-octet UDH — 159 octets in `short_message`,
and entirely correct. Do not "fix" this to 134; that number is the packed payload size and would
truncate every long message by a fifth.

UCS2 is not packed, so there the two coincide: 67 characters = 134 octets, plus the 6-octet UDH is
exactly 140.

## Conventions

- Hard tabs. Alphabetical ordering for keys, imports and lists unless order is logic-significant.
  Two deliberate exceptions: command parameters are in wire order (above), and the `errors` and TLV
  tables are ordered by their numeric id so they can be diffed against the spec and gaps stay visible.
- Comments are the exception, not the default — see the root `CLAUDE.md` rules. Do not write file
  preambles or restate what the code says.
- Test data uses real randomised UUID v7 values, never `aaaa-0000` placeholders.
- Fixtures that encode the wire are shared so no two files can drift on it: `test/raw-pdus.ts` builds
  the octets a test writes straight to a socket, the PDUs `objToPdu()` refuses to build included. The
  waiting helpers each file carries are copies, tolerated because a wrong one fails that file's own
  tests and nothing else.
- `message_id` values the library generates are UUID v7.
- A test that needs a dummy peer must `resume()` its sockets. An unread socket never processes the
  peer's FIN, so `server.close()` hangs forever — that is a test bug, not a library one.
- Everything a test opens gets its teardown registered as it is opened, never closed on the test's
  last line: an assertion that throws skips that line, and the listener it leaves behind keeps
  `node --test` alive until CI's ten-minute cap. `test/teardown.ts` covers a session, a server and a
  listener; anything else takes a bare `t.after`. Its close aborts rather than drains, so a test that
  fails holding the send window still ends.
- `t.after` hooks run in registration order, so registering at creation tears the outermost resource
  down first. A teardown that waits on a listener must destroy that listener's own connections before
  it waits, or be registered after the hook that does — `net.Server.close()` does not call back until
  every connection on it is gone.
- `assert.equal` from `node:assert/strict` narrows its first argument, so a following `?.` on the
  same value is flagged as unnecessary. Assert once with `assert.ok(x)` and use plain access after.

## Documentation

Each file answers one question, and a fact belongs to the file whose question it answers:

- **README.md — what you can rely on.** Observable behaviour, for someone using the package. It
  carries a reason only where the reason changes how you would call the thing.
- **AGENTS.md — what may not change, and why.** Goals, hard rules, architecture, conventions, and the
  decisions the goals do not already settle. It does not restate behaviour README states.
- **todo.md** is a temporary working file that sets its own rules; nothing here governs it.

A sentence living in two of them is a defect: delete the copy in the file whose question it does not
answer. The toolchain commands are the one deliberate exception — README's copy serves a contributor
who never opens this file, and this file's copy carries the constraint that nothing runs on the host.

**Write a decision down only when it cannot be put better as a goal.** A goal decides every case that
follows from it; a decision record decides one. So reach for the goal list first — sharpen a goal,
add one, or move one up the order — and write a decision only for what is left over: a choice a
competent change would otherwise re-open, that no goal implies. Give the claim, the constraint that
settled it and the alternative rejected, and nothing the code or README already says. Where a
compiler or a test already forbids the other way, it is not a decision, it is a test name. Delete one
once it no longer constrains anything; this is not a changelog.

## Decisions

Grouped by what each one constrains.

### The public surface

- **`Session` is publicly constructible, which is what makes `SessionOptions` and `ReconnectOptions`
  public too.** Raised twice as a leak; it is not one. The collaborators `session.ts` delegates to
  (`Reassembler`, `PendingRequests`, `SendWindow`, `ReconnectLoop`, `LinkTimers`, `LinkGate`,
  `DlrMerger`, `PduTransport`, `submitSms`) stay unpublished so they can be reshaped.

- **`acceptsOptionalParams()` and `bindAllows()` are predicates, not chokepoints.** The library's own
  senders consult them; `session.send({ tlvs })` is passed through as written, because silently
  stripping a caller's explicit TLVs off a deliberately public low-level surface would be worse than
  sending them. Only `submit_sm` and `deliver_sm` are policed by bind direction — the only two the
  library sends and dispatches by it.

- **`session.sock` is a getter over `PduTransport`.** Reading it is unchanged; assigning it no longer
  compiles, which never rewired the handlers and so never worked.

- **Both emitters re-declare their listener methods to accept a promise.** Maintainer's call,
  2026-08-27: `EventEmitter` types every listener as void-returning, so the
  `session.on('sms', async sms => …)` README documents reads as a misused promise in any strict
  consumer. `declare on: …` and its six siblings re-type the inherited methods to return `unknown`,
  which emits nothing and needs no cast; overriding them as real methods cannot work, because the
  `super.on()` call needs one. The cost is that a subclass can no longer reach those seven through
  `super` — re-declaring them the same way is its way out. `unknown` rather than
  `void | Promise<void>` because a listener may return anything: `session.on('close', () =>
  set.delete(session))` returns a boolean. This also settles what the drain can wait on: a listener's
  own promise would be the better completion signal, and reaching it needs `listeners()`, which
  cannot be re-declared the same way — Node types it invariantly enough that widening `void` to
  `unknown` is `TS2416`. Re-probed 2026-09-01; `sendResp()` stays the signal.

- **`PduRefusedError` is exported, and `sessionError` names it in the event's type.** Maintainer's
  call, 2026-09-05, from a product review: one event carries both a PDU the peer malformed and the
  session's own failure, and `instanceof` is the only way to separate them that hard rule 4 allows —
  without the class as a value an application is left string-matching `err.message`. Goal 6 is paid by
  exporting the discriminant and the struct it carries and nothing else: `PduHeader` is named because
  an application that logs or forwards a header wants a name for it, `PduRefusalReason` is not
  because `reason` is compared against string literals, and an accessor
  (`PduRefusedError['header']`) names either one where a signature wants it. The payload union
  enforces nothing — a subclass narrows out of `Error` either way — and is there so the event's own
  type names what to narrow to, which is also what makes it a half-truth if a second `Error` subclass
  ever reaches this event without joining it. Rejected: a `SessionError` alias for that union, a
  third name for a type that is structurally `Error`. Rejected: a separate `pduRefused` event, which
  splits the failure channel so an application that wants every failure listens twice and an existing
  listener silently stops seeing refusals. Rejected: coalescing or rate-limiting them, which re-opens
  the standing decision that `sessionError` carries every failure, never coalesced or suppressed —
  the filtering belongs where the application is, since only it knows which peer is routinely sloppy.
  Rejected: an error code on a plain `Error`, which reads back off an `unknown` property only through
  a cast and types nothing it carries. Accepted: a second copy of the package installed alongside
  this one defeats `instanceof`, where `err.name` still reads `PduRefusedError`.

### The wire

- **The declared interface version is an option on both `client()` and `server()`, and is not the
  optional-parameter threshold.** That threshold is fixed at 0x34 by the spec, so an implementation
  that must declare 5.0 throughout can, without moving it.

- **A peer that declared no version is pre-3.4, and `undefined` means no bind yet.** `acceptBind()`
  records what the ESME declared and the client's `bind()` records the `sc_interface_version` the
  SMSC answered with; a peer that declared nothing is recorded as `undeclaredInterfaceVersion` (0x00)
  and sent no optional parameters, which is how the spec reads an absent `sc_interface_version`.

- **`esm_class` decides what a `deliver_sm` is, and the body is read only when it names nothing.**
  The two types the MC writes about a message we submitted — `MC_DELIVERY_RECEIPT` (0x04) and
  `INTERMEDIATE_DELIVERY` (0x20) — are reports whatever the body parses to, so one in a format
  `dlrFromPdu()` cannot read reaches `dlr` with `smsId` undefined instead of arriving as an inbound
  SMS. The three the far-end SME writes (0x08, 0x10, 0x18) are messages and their bodies are not
  scraped: Kannel reads 0x08 as report-bearing and this does not, because a delivery acknowledgement
  is the handset's word about a message, not the network's. A message type of 0 or one of the ten
  reserved keeps the scrape, and a non-empty `receipted_message_id` TLV marks a report on the same
  footing. A report this library recognises never reaches the reassembler, so an SMSC that splits one
  across segments gets a `dlr` per segment rather than one merged report. The `message_state` TLV is
  authoritative only where it names a state in the table — SMPP reserves 0x80-0xFF for
  MC-vendor-specific values, so an unnameable one keeps its raw `statusId` and leaves `statusMsg` to
  the body.

- **A receipt's body is read as octets, and its own `data_coding` never says how.** Maintainer's
  call, 2026-09-05 via the SMPPSim interop run: SMPPSim copies the reported message's `data_coding`
  onto a receipt whose body it always writes as plain text, and Melrose Labs documents the same
  echo, so decoding by that field turns an Appendix B receipt into UCS-2 garbage — total loss
  against the many peers that send no TLVs to fall back on. `dlrFromPdu()` reads
  `PduObject.shortMessageOctets` through Latin-1, the one codec that maps every octet to a
  character, so the fixed fields parse whatever the PDU claims; the codec keeps both spellings
  because a message needs the text and a receipt needs the octets. Rejected: honouring `data_coding`
  where the octets yield no field, which reads one body two ways for the sake of a peer writing a
  UCS-2 receipt body that no researched SMSC is — that peer's receipt yields no fields at all here,
  which goal 2 reports as undetermined rather than guessed. An inbound message is untouched: nothing
  but `data_coding` can say how a message was written.

- **A report is final unless its `esm_class` or its state says otherwise, and only `ENROUTE` and
  `SCHEDULED` say otherwise.** SMPP 3.4 Appendix B lists every other receipt state as final,
  `UNKNOWN` and `ACCEPTED` included, so a peer writing `ACCEPTD` for a carrier-accepted step is taken
  at its word. Rejected: reading `UNKNOWN` as non-final, which leaves a peer whose receipt body this
  library cannot read with no `messageDlr` at all — goal 2 wants that reported as undetermined, not
  withheld. Both spellings resolve into `Dlr.intermediate` at the boundary rather than being read a
  second time in `DlrMerger`, so the library cannot answer the application one way and conclude the
  other. Not every peer marks a transient report 0x20 — an ordinary receipt carrying `stat:ENROUTE`
  is common — so the state test is what the marker test cannot replace. `message_state` 0 is 5.0's
  `SCHEDULED` and undefined in 3.4; a peer that writes it is read as transient rather than as saying
  nothing, maintainer's call, 2026-09-03, since the codec refuses a zero-length integer TLV and so an
  absent one cannot land there.

- **A transient state goes out as an intermediate delivery notification (0x20), every other state as
  a delivery receipt (0x04).** Appendix B makes a receipt's `stat` the message's final status, so
  0x04 over `ENROUTE` emits the two disagreeing spellings of finality the reading side above has to
  reconcile, and goal 3 has our own senders write the marker 3.4 defines. `sendDlr()` takes the list
  from `transientStates` in `dlr.ts`, the same one the reader uses, so the two cannot drift.
  Rejected: 0x04 for every state, for the sake of a peer that classifies on the marker — the cost
  accepted here is that such a peer stops recognising a transient report as a report at all and hands
  its application receipt text as an inbound message, where under 0x04 it would have read the state
  from `stat:` and been right. A transient state also carries `err:000`, since a message still on its
  way has not failed.

- **A refused PDU is answered from its header, and any 32-bit `sequence_number` is echoed as it
  arrived.** Maintainer's call, 2026-09-05 via the interop plan. The header of a framed PDU always
  parses, so it carries the answer SMPP 3.4 4.3 asks for, with the status 3.4 names for the part
  that would not parse. Rejected: nacking a refused *response*, whose sequence number is one of
  ours — the `generic_nack` would land in the peer's own numbering and nack a request of the peer's
  we never saw, so a refused response is written back nothing and settles the request it names
  instead. An unknown command id with the response bit set takes that branch too: a peer echoing a
  sequence number of ours is answering something, and settling it reaches the undetermined outcome
  `responseTimeout` would have reached anyway, sooner. Rejected: clamping a sequence number outside 4.7.1's 0x00000001–0x7FFFFFFF into range
  before answering, which correlates with nothing at the peer — stacks write the field as a plain
  uint32 (ukarim/smscsim signs every unprompted `deliver_sm` with a raw `rand.Int()`), so goal 3
  keeps that traffic and `PendingRequests.nextSeqNr()`, the only thing that invents one, is what
  holds our own sends inside the spec.

- **`smsIdFormat` names a notation per place, and normalisation never reaches inside a `<base>-<n>`
  id.** An SMSC may answer `submit_sm_resp` in hex and write the receipt's `id:` in decimal, so one
  transform over both sides cannot make them equal. `submitResp` covers the `receipted_message_id`
  TLV too, which SMPP 3.4 5.3.2.26 defines as the id the `submit_sm_resp` carried: naming one
  notation for whichever id a receipt yields would break the peer that sends both. Omitting a place
  is what leaving it alone means, so there is no `raw` notation, and a caller-supplied formatter is
  refused because it would make the promise that the two ids are comparable unverifiable — `onRequest`
  and the PDU on the `dlr` event are the escape hatches. A `<base>-<n>` id parses as no number and so
  reaches `expect()` and `collect()` unchanged, which is what keeps `DlrMerger` working; normalising
  the base instead would break that pair. The option is on `client()` only, since a `server()` session
  writes both ids itself.

### The session's life

- **A close arriving after our own `unbind` is a clean unbind, not an error.** Maintainer's call,
  2026-08-26: most SMSCs drop the socket instead of answering, so the documented shutdown would
  otherwise always report a failure. It does mask a socket that died mid-unbind for an unrelated
  reason, which is accepted — the peer sees the same TCP close either way.

- **`close` means the session is over, and a drop the loop will retry is `disconnected`.**
  Maintainer's call, 2026-08-31: without the split, an application that opens a replacement client on
  `close` ends up holding two binds on one account. `teardown()` picks the event by whether the
  reconnect loop is still live, and `end()` stops that loop before tearing down, so every deliberate
  shutdown emits `close`. A retry that opens a socket and then loses it clears `closed` through
  `attach()`, which is why a second drop emits again.

- **An answer belongs to the link the message arrived on; a receipt does not.** Maintainer's call,
  2026-09-01. Rejected: answering on the new link, which succeeds and reports `{}` for a response
  that correlates with nothing — goal 2's wrong answer. Accepted: a receipt sent after a refused
  response names an id the peer has no record of.

- **`reconnect` takes `{ minDelay, maxDelay }` to retune and `false` to turn off**, so absent means
  on and there is one spelling for each. Only `client()` reconnects — a `server()` session is a
  connection the peer opened, and nothing at this end can reopen it. The retry timer is `unref()`'d,
  so a process with nothing else left to do still exits between attempts.

- **Coming up is not proof a link works, so only one that outlasted `maxDelay` resets the backoff.**
  An unreadable stream is found after the bind returns, so resetting on connect gave a link that died
  on arrival a fresh `minDelay` every cycle — one TCP connect and bind per second, forever. A drop
  after a healthy link still retries at `minDelay`.

- **`reconnect: { fromStart: true }` puts the first connect and bind through that same loop, and
  `client()` then resolves only once it is bound.** Maintainer's call, 2026-09-05: an application
  started before its SMSC is up otherwise writes that retry itself, around the one this library
  already owns. A field on `reconnect` rather than an option of its own, so the combination that
  would contradict `false` cannot be written at all — `false` carries no fields — and a top-level
  `fromStart` is refused by name rather than ignored. Nothing but the caller's `signal` ends the
  wait: a bound of its own would be a second spelling of a deadline the caller already writes with
  that signal, and giving up after one is what the default does. A bind the SMSC refuses is
  retried like any other failure — rejected: giving up on `ESME_RINVPASWD` and `ESME_RBINDFAIL`,
  which would have the initial attempts and a rebind disagree about what a refused bind means, and
  gives up on the operator whose provisioning lands a minute later; the backoff is what bounds the
  rate goal 4 cares about. The attempts before the first link report nothing, because the session
  running one has not reached the application: `disconnected` would have no listener and `close`
  would be a lie. Its wait is the one retry timer that is not `unref()`'d, for the reason
  `LinkGate`'s hold is not — it is awaited with no other handle, so a process whose only work is
  `client()` would exit unbound.

- **A stream this library cannot frame is a dead link; one PDU it cannot parse is not.**
  Maintainer's call, 2026-08-31, narrowed 2026-09-05 via the interop plan: a `command_length` below
  16 or above `maxPduLength` leaves nothing that can say where the next PDU starts, so it tears the
  link down through `teardown()` and the reconnect loop retries it on a fresh socket with a fresh
  framer. Every other codec failure honoured `command_length`, so the stream is still in sync and
  the next PDU starts where it says — tearing the link down there cost one peer half its receipts
  and its MO to a reconnect loop (`interop-tests/findings/01-smscsim.md`), and left the peer waiting
  for answers it was owed. `sessionError` carries every failure of either kind, never coalesced or
  suppressed, so a peer that only ever sends garbage is visible in the log rather than silent.

- **A deliberate shutdown drains; an unusable link and an abort do not.** `close()` and `unbind()`
  wait on the send window rather than the pending map — the map misses a segment still queued behind
  a full window, and finishing a half-sent multipart message is the point. The window counts slots,
  never outcomes, and empties on a drop too, where `teardown()` settles everything the link was
  carrying, which is why `drain()` reads `closed` before it reads the count. A stream the framer or
  the codec cannot read takes `teardown()` instead, and `close({ signal })` on an aborted signal and
  a peer's own `unbind` take `end()`: nothing on a dead link can answer, an abort means stop now, and
  a peer that has declared itself finished will not answer what it still owes, so draining any of the
  three would only hold a socket open for the timeout. `unbind()` sends its own PDU through
  `request()` past both the window and the drain gate, because it must go out either way.
  `shutdownTimeout` stays a session option rather than a `close()` argument: `server()` builds
  sessions on the caller's behalf, so the option is the only composition point. `SmppServer.close()`
  reports each session's unfinished drain through `serverError`, because its own result says nothing
  but that the listener stopped.

- **The drain waits on the messages the application holds, and `sendResp()` is what says it is done
  with one.** Maintainer's call, 2026-09-01: waiting on the send window alone tore a server session
  down while the application was still answering a `submit_sm`, so the peer timed out and re-sent —
  the duplicate goal 2 forbids, in the direction the window already covers. No completion signal was
  added to the `sms` event: `sendResp()` is the answer the peer is waiting for, so it is the one the
  drain waits for. Counting every inbound request until `sendReturn()` answered it was rejected —
  an `onRequest` that deliberately answers nothing would then cost a full `shutdownTimeout` on every
  close — and a message no listener took is released at once, since nothing is going to answer it.
  A listener that failed before answering gives it up the same way, but only once every listener has:
  a throw stops `emit()` where it stands, while a rejection leaves the others running, so the release
  waits for the last of them rather than answering on their behalf. What ends the wait is the response
  reaching the wire, not the call — a `sendResp()` the library refused, or one the socket would not
  carry, leaves the message held, so `close()` still reports the one the peer is owed. `teardown()`
  drops what is still held for the same reason it drops inbound segments. The release is one turn
  late, so a listener that sends its receipt straight after the response is still holding when the
  drain looks; `sendDlr()` is the one send that goes out past the drain's refusal, and only while the
  message is still held — past that it is an ordinary send, because the drain it would slip past is
  no longer waiting for it. `shutdownTimeout: 0` does not carry over to this half:
  waiting forever is safe for the peer, whose every request is bounded by `responseTimeout` unless the
  caller set that to 0 as well, and unsafe for the application, which nothing bounds — `close()` is
  what you reach for when the application is stuck, so it may not block on the application coming
  unstuck. That half falls back to `responseTimeout`, the same answer the link gate's hold already
  takes — and to that option's default where it is 0 as well, since neither option is an answer about
  the application. What is held is capped and expiring like every other inbound store, on constants
  rather than options, because a bound the application cannot raise is the point: an application that
  answers nothing would otherwise grow it for the life of the link, which goal 4 forbids. A message
  that falls out of the bound is one the drain stops waiting for, so `close()` can report fewer
  unanswered than there were — accepted, because the alternative is holding what nothing will answer,
  and both exits are logged.

- **A reconnect keeps the delivery-receipt merges; everything else the link held is dropped.**
  `onDeliverSm()` answers each receipt before the group it belongs to is complete, and `teardown()`
  runs on every path — an idle timeout and a failed rebind, not only `close()` — so clearing the
  merges there loses receipts no peer has a reason to send again. They are cleared where the session
  is over instead. Inbound segments stay in `teardown()`, because they go unanswered until the
  message is whole: the peer still holds them, and answering it on a later link with the old
  segments' sequence numbers would correlate with nothing.

- **A message id base is merged at most once.** A receipt carries nothing but `<base>-<n>`, so a
  straggler for a message whose group is gone cannot be told from a receipt for a later message the
  peer handed the same ids — an SMSC whose id counter restarts with its process is the realistic
  case. `DlrMerger` remembers the bases it has finished with, capped and expiring exactly like the
  groups, and refuses to open one a second time: the later message gets no `messageDlr`, and an
  earlier one whose receipts are still arriving is dropped rather than left to collect the later
  one's. Every segment still reaches the application as a `dlr`. `expect()` ignores a lone id, so a
  single-part message never claims a base.

- **A send that never reached the socket waits for the next link; one that did is counted, not
  resent.** Maintainer's call, 2026-09-01: re-queueing everything unanswered would resend a
  `submit_sm` the SMSC accepted and answered into a dead socket, which is delivered and billed twice,
  while a request that never left this process can be lost for free. `attempt()` therefore wraps all
  three ways a written request can fail in `UnansweredError`; counting only the dropped-link case, as
  the first cut did, would have called the commonest one safe to resend. A count rather than a
  boolean because `sendSms()` aggregates segments into one `err` slot, and required rather than
  optional so every construction site answers. `UnansweredError` stays unexported: `unanswered` is
  the one spelling on the public surface. The hold is bounded by `responseTimeout` rather than an
  option of its own — that is already the answer to how long one request may wait — and its clock
  starts when the send is issued rather than when it first finds the gate shut, so one budget covers
  every hold a single call makes. That timer is the one here that is not `unref()`'d: a held request
  is awaited with the socket already destroyed, so an unref'd one lets a process whose only remaining
  work is that send exit without settling it.

- **The gate decides whether a link can carry a request, and a bind is what makes it one.**
  Maintainer's call, 2026-09-01: `attach()` clears `closed` the moment a socket is handed over, one
  round trip before the bind is answered, so gating on `closed` let a send arriving in that window go
  out unbound and come back `ESME_RINVBNDSTS`. `LinkGate` owns the answer instead — `shut(returning)`
  on every teardown, `open()` only once `comeBackUp()` has a bound link — and
  `OutgoingRequests.linkDown()` reads it rather than `closed`. The bind itself cannot wait for what it
  creates, so `pastDrain()` lets the three bind commands past the gate and the window, the same door
  `unbind()` takes through `now()`. The gate is told what happened and never reads back into the
  session: a collaborator that has to ask does not own its decision, which is how the first cut ended
  up answering the same question two different ways at admit and at release. For the same reason the
  retry in `pastDrain()` asks `gate.isUp()` rather than `linkDown()`, which also reads the socket — a
  condition that loops on something the gate does not gate on spins against a gate that admits it
  straight back. `LinkGate.returning` is a copy of `retrying()` taken at teardown, and stays true
  only because nothing stops the reconnect loop without `emitClose()` following it: `drain()` and
  `end()` are the only callers of `stop()`. A third caller has to shut the gate itself.

### Internals and tests

- **A listener that rejects is routed by Node's `captureRejections`, not by hand-dispatching.** Both
  emitters construct with `captureRejections: true` and implement
  `[EventEmitter.captureRejectionSymbol]`, which lands a rejected `async` listener on `sessionError`
  or `serverError` beside the synchronous guard in `emit()`. Dispatching `rawListeners()` from
  `emit()` instead needs a cast to call them with the event's argument tuple, which hard rule 4
  forbids. A rejection reason is `unknown` and `String()` throws on a null-prototype object, so both
  handlers normalise through `errorFrom()` rather than inline — a route out of the handler would land
  on a bare `process.nextTick` with nothing to catch it.

- **`SmppLog` is a five-method contract this library declares, not a dependency.** `debug`, `error`,
  `info`, `verbose` and `warn` are what the code actually calls, so an application can satisfy it
  with an object literal. `@larvit/log` implements it structurally and stays a devDependency, where
  `test/tls.test.ts` passing a real `Log` as the server's logger keeps that compatibility compiled.

- **The TLS tests build their own self-signed certificate in DER** (`test/tls.test.ts`) instead of
  adding a devDependency or shelling out to openssl. Maintainer's call, 2026-08-26: the dev image
  `node:24.18.0-bookworm-slim` ships no openssl binary, so a shelled-out fixture would pass in CI and
  fail on every developer machine, and a committed key leaks in a public repository. Valid while the
  dev image has no openssl.