AGENTS.md

@@ -280,6 +280,8 @@ the file.
 - A GSM 03.38 message declares `data_coding` 0x00, and an inbound 0x01 is still read as GSM.
 - Every text field on the wire is latin1, and what the field cannot carry is refused rather than
   truncated.
+- A TLV input is keyed by its tag name, or by its decimal id where the table names none, and a
+  `tagId` beside the key is accepted only where it agrees.
 
 ### [The session's life](docs/decisions.md#the-sessions-life)
 

docs/decisions.md

@@ -490,6 +490,15 @@ rule and an index of the titles below.
   text field, which would buy one spelling by taking a legitimate octet away from the
   length-prefixed Octet String, whose length octet is what ends it.
 
+- **A TLV input is keyed by its tag name, or by its decimal id where the table names none, and a
+  `tagId` beside the key is accepted only where it agrees.** Settled in the architecture and
+  product-owner reviews of [#30](https://gitea.larvit.se/larvit/smpp-js/pulls/30), 2026-09-27. The
+  key is the one spelling, because a name and a `tagId` that disagreed sent the `tagId`'s tag under
+  a record keyed as another. A parsed TLV carries its `tagId`, and goal 8's passthrough means a
+  parsed PDU's `tlvs` relay as they are, so an agreeing copy is read past rather than refused.
+  Rejected: refusing every `tagId`, which breaks relaying. Rejected: a `tagId` overriding the key,
+  the 0.5.0 behaviour. Valid while parsed TLVs carry `tagId`.
+
 ## The session's life
 
 - **A close arriving after our own `unbind` is a clean unbind, not an error.** Maintainer's call,

src/defs/tlvs.ts

@@ -167,7 +167,7 @@ function entryOf(name: string, input: unknown): Result<{ tagId: number; tagValue
 	if (keyed.err) return { err: keyed.err };
 
 	if ('tagId' in input && input.tagId !== undefined && input.tagId !== keyed.tagId) {
-		return { err: new Error(`TLV "${name}": its tagId is not ${String(keyed.tagId)}, the tag its key names; drop the tagId`) };
+		return { err: new Error(`TLV "${name}": its tagId does not match ${String(keyed.tagId)}, the tag its key names; drop the tagId`) };
 	}
 
 	return { tagId: keyed.tagId, tagValue: input.tagValue };

test/pdu.test.ts

@@ -443,9 +443,9 @@ describe('TLVs', () => {
 		const refusals = [
 			// @ts-expect-error nils is no tag name
 			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { nils: { tagValue: 'blajfoo' } } }), reason: /decimal id/ },
-			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { 5142: { tagId: 5143, tagValue: 'blajfoo' } } }), reason: /its tagId is not 5142/ },
+			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { 5142: { tagId: 5143, tagValue: 'blajfoo' } } }), reason: /does not match 5142/ },
 			// @ts-expect-error the key names the tag
-			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { message_state: { tagId: 5, tagValue: 2 } } }), reason: /its tagId is not 1063/ },
+			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { message_state: { tagId: 5, tagValue: 2 } } }), reason: /does not match 1063/ },
 			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { 5142: { tagValue: 300 } } }), reason: /Buffer/ },
 			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { 65536: { tagValue: 'blajfoo' } } }), reason: /out of range/ },
 			{ built: objToPdu({ cmdName: 'deliver_sm', params, tlvs: { '05142': { tagValue: 'blajfoo' } } }), reason: /decimal id/ },