fix(plugin-email): refuse a fractional SMTP port at construction, in the sentence that promised to (#13375)

`isValidSmtpPort` was `Number.isFinite && >= SMTP_PORT_MIN && <= SMTP_PORT_MAX`
with no integrality test, so `port: 587.5` was accepted at construction and
`describe()` read it straight back. It can never connect: `net.connect` refuses
a fractional port with `ERR_SOCKET_BAD_PORT`, and once nodemailer has re-coded
it the operator sees, at send time, a bare `RangeError` (`code: 'ECONNECTION'`)
reading `Port should be >= 0 and < 65536. Received type number (587.5).` — a TCP
rule naming no part of the Settings field they typed it into.

The refusal the guard did emit stated the integer rule without enforcing it:
`587.5` is inside `1-65535`, so `(expected 1-65535)` described a door that had
just let it through. Both move together — the guard tests `Number.isInteger`
(which subsumes the old finiteness check) and the generated sentence now reads
`(expected an integer 1-65535)`. The range is still rendered from the constants;
neither bound was re-spelled.

The deliberate accept-set pin in `smtp-port-contract.test.ts` is UPDATED, not
deleted: the legacy oracle stays, an exhaustive sweep over every integer from
below the floor to above the ceiling shows the integer accept set did not move
at all, and the one axis that did move is named value by value.


Claude-Session: https://claude.ai/code/session_012WkdHQwHr2KQmaX7P1BHzi

Co-authored-by: Claude <noreply@anthropic.com>

Author: Elon Musk

.changeset/smtp-port-integrality.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/plugin-email": patch
+---
+
+fix(plugin-email): refuse a fractional SMTP port at construction, in the sentence that promised to (#13189)
+
+`SmtpTransport`'s port guard was `Number.isFinite && >= 1 && <= 65535` — no
+integrality test — so `port: 587.5` was ACCEPTED at construction and
+`describe()` read it straight back. It could never connect. `net.connect`
+refuses a fractional port with `ERR_SOCKET_BAD_PORT`, and by the time
+nodemailer has re-coded it the operator sees, at SEND time, a bare
+`RangeError` (`code: 'ECONNECTION'`) reading `Port should be >= 0 and < 65536.
+Received type number (587.5).` — a TCP rule naming no part of the
+Settings → Mail → Port field they typed it into.
+
+⭐ And the refusal this door *did* emit stated the integer rule without
+enforcing it: `587.5` **is** inside `1-65535`, so `(expected 1-65535)`
+described a door that had just let it through. The check and its own sentence
+disagreed, and only one of them could be satisfied.
+
+Both move together, or the lie moves instead of leaving:
+
+| `port` | before | after |
+|:---|:---|:---|
+| `587.5` | accepted; `RangeError` at send time | refused at construction: `SmtpTransport: invalid port '587.5' (expected an integer 1-65535)` |
+| `1` / `465` / `587` / `65535` | accepted | accepted — unchanged |
+| `0` / `-1` / `99999` | refused | refused — unchanged |
+| `NaN` / `±Infinity` | refused | refused — unchanged |
+| absent, or `smtp_port: ''` | 587 | 587 — unchanged; an empty field spells "not set" |
+
+The sentence stays GENERATED from `SMTP_PORT_MIN` / `SMTP_PORT_MAX` (#12993) —
+"an integer" is prose about the predicate, and neither bound was re-spelled.
+⚠️ It therefore reads `(expected an integer 1-65535)` from this release on,
+including in the refusal quoted by the #13190 entry above, which was written
+before this change landed.
+
+This narrows the accept set, deliberately and in exactly one dimension. The
+values affected are the fractions strictly inside the range: they were
+unbindable addresses, and a deployment carrying one has never delivered mail on
+it — it was failing at send time, under a name that pointed nowhere near the
+setting. It now fails at boot, saying which value and which rule.
+
+⚠️ This is not a divergence from the CLI's port contract but a convergence with
+it. `packages/cli/src/utils/port-contract.ts` is emphatic that a door may not
+narrow what boots, and it is read as a precedent the other way — but its width
+is about how a port may be *spelled* (`3e3`, `0x0BB8`, `3000.0`, `+3000`,
+`08080`), every one of which `parseInt` reduces to an integer before any range
+check. Both of its readers then test `Number.isInteger` outright. On
+integrality that contract has been strict all along.

packages/plugins/plugin-email/src/transports/smtp-port-contract.test.ts

@@ -31,6 +31,17 @@
  * mechanism `mail-manifest-providers.contract.test.ts` already uses for the
  * provider dropdown over that same devDependency.
  *
+ * ## #13189 — the accept set narrowed, and this file is where that is visible
+ *
+ * `isValidSmtpPort` now tests INTEGRALITY. That is a deliberate narrowing of
+ * the set #12993 pinned, and the pin below was written to make exactly this
+ * kind of change loud rather than to forbid it — so it was UPDATED, never
+ * deleted: the legacy oracle stays, an exhaustive integer sweep says the
+ * integer accept set did not move at all, and the one axis that did move is
+ * named value by value. The sentence moved with the guard (`expected an
+ * integer 1-65535`), because `587.5` is inside `1-65535` and a door that
+ * refuses it while saying only that is stating a rule it does not enforce.
+ *
  * ## ⛔ The floor is 1 and must never become 0
  *
  * The CLI's listen range floors at 0 ("let the OS choose"). This one floors at
@@ -181,7 +192,7 @@ describe('#12993 — one SMTP port range, every door states it from there', () =
     // independent spelling, so there is nothing left to drift.
     expect(SMTP_PORT_RANGE_TEXT).toBe(`${SMTP_PORT_MIN}-${SMTP_PORT_MAX}`);
     expect(formatInvalidSmtpPortNotice('abc'))
-      .toBe(`SmtpTransport: invalid port 'abc' (expected ${SMTP_PORT_MIN}-${SMTP_PORT_MAX})`);
+      .toBe(`SmtpTransport: invalid port 'abc' (expected an integer ${SMTP_PORT_MIN}-${SMTP_PORT_MAX})`);
 
     // The ceiling is typed exactly once even inside its own module — if the
     // notice re-spelled the range, this would be 2.
@@ -211,27 +222,146 @@ describe('#12993 — one SMTP port range, every door states it from there', () =
       .toBe(true);
   });
 
-  it('refactors the enforcement without narrowing what it accepts', () => {
-    // The predicate `smtp.ts` had before this card, kept verbatim as the
-    // oracle. Reading the bound from the module here would assert `x === x`;
-    // the point is that the OLD expression and the NEW function agree.
+  it('narrows the accept set in exactly ONE dimension — integrality — and nowhere else (#13189)', () => {
+    // ⚠️ This case was `refactors the enforcement without narrowing what it
+    // accepts` when #12993 moved the predicate here, and `587.5` sat in its
+    // table as MEASURED, not endorsed. #13189 is the card that SPENDS that
+    // pin: the accept set really does narrow now, and the pin's job was always
+    // to make such a change visible rather than to prevent one. So the oracle
+    // and the values stay exactly where they were; what changed is that the
+    // two are now expected to disagree on ONE axis, asserted term by term so
+    // that a second narrowing — or any widening — still fails right here.
     const legacyAccepts = (port: number): boolean =>
       !(!Number.isFinite(port) || port < 1 || port > 65535);
 
-    const table = [
+    const integers = [
       1, 25, 465, 587, 2525, 65535, // inside
       0, -1, 65536, 99999, // outside
+    ];
+    const nonIntegers = [
+      587.5, 1.5, 2525.25, 65534.5, // INSIDE the range — accepted until this card
+      0.5, 65535.5, -0.5, 65536.5, // outside it — the old bounds refused these too
       Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY, // not finite
-      587.5, 0.5, 65535.5, // non-integers: accepted iff they were accepted before
     ];
-    for (const port of table) {
+
+    // ── UNCHANGED: on every integer the predicate is still, bound for bound,
+    // the expression `smtp.ts` carried before #12993.
+    for (const port of integers) {
       expect(isValidSmtpPort(port), `accept set changed for ${String(port)}`)
         .toBe(legacyAccepts(port));
     }
 
-    // The table is not vacuous in either direction.
-    expect(table.filter(legacyAccepts).length).toBeGreaterThan(0);
-    expect(table.filter((p) => !legacyAccepts(p)).length).toBeGreaterThan(0);
+    // ⭐ …and the strongest available form of "and nowhere else": EVERY
+    // integer from below the floor to above the ceiling, not ten sampled
+    // ones. 65k comparisons of two cheap predicates costs milliseconds and
+    // closes the gap a table cannot.
+    let divergences = 0;
+    for (let port = -2; port <= SMTP_PORT_MAX + 2; port += 1) {
+      if (isValidSmtpPort(port) !== legacyAccepts(port)) divergences += 1;
+    }
+    expect(divergences, 'the integer accept set moved somewhere the table does not sample')
+      .toBe(0);
+
+    // Control for that zero — the same sweep against a floor deliberately one
+    // too high, which MUST find the one integer it disagrees about. Without
+    // this the loop above could be counting nothing at all.
+    let seen = 0;
+    for (let port = -2; port <= SMTP_PORT_MAX + 2; port += 1) {
+      if ((port >= 2 && port <= SMTP_PORT_MAX) !== legacyAccepts(port)) seen += 1;
+    }
+    expect(seen, 'the integer sweep is a dead loop').toBe(1);
+
+    // ── THE ONE CHANGE: nothing non-integral is accepted any more.
+    for (const port of nonIntegers) {
+      expect(isValidSmtpPort(port), `${String(port)} is still accepted`).toBe(false);
+    }
+
+    // …and exactly WHICH values this card moved, spelled out rather than
+    // summarised: accepted yesterday, refused today, and not one of them could
+    // ever have completed a connection.
+    //
+    // ⚠️ MEASURED, and it corrected a first draft of this very list: a
+    // fraction only moved if it was INSIDE the range, so `0.5` and `65535.5`
+    // belong in the half below, not here. `0.5 < SMTP_PORT_MIN` and
+    // `65535.5 > SMTP_PORT_MAX`, so the old bounds already refused both — and
+    // listing them as "narrowed by this card" would have overstated the
+    // change while still passing a weaker assertion.
+    const moved = [587.5, 1.5, 2525.25, 65534.5];
+    expect(moved.filter(legacyAccepts), 'these were not accepted before, so nothing moved')
+      .toEqual(moved);
+    expect(moved.filter((port) => isValidSmtpPort(port)), 'a fractional port is accepted again')
+      .toEqual([]);
+
+    // The other half, asserted rather than left implied: every remaining
+    // non-integer was ALREADY refused, so this card narrowed the in-range
+    // fractions and nothing else.
+    const unmoved = nonIntegers.filter((port) => !moved.includes(port));
+    expect(unmoved.filter(legacyAccepts), 'this card narrowed more than the in-range fractions')
+      .toEqual([]);
+    expect(unmoved.length, 'the unmoved half is empty — it asserts nothing').toBeGreaterThan(0);
+
+    // The tables are not vacuous in either direction.
+    expect(integers.filter(legacyAccepts).length).toBeGreaterThan(0);
+    expect(integers.filter((p) => !legacyAccepts(p)).length).toBeGreaterThan(0);
+    expect(nonIntegers.filter(legacyAccepts).length).toBeGreaterThan(0);
+  });
+
+  it('⭐ states the rule it enforces — the sentence and the guard cannot disagree (#13189)', () => {
+    // The defect this card repairs, in one line: `587.5` **is** inside
+    // `1-65535`, so a refusal reading `(expected 1-65535)` described a door
+    // that had just let it through. The sentence is the operator's only view
+    // of the rule, so a guard that tests integrality without saying so would
+    // have moved the lie rather than removed it.
+    const notice = formatInvalidSmtpPortNotice(587.5);
+    expect(notice, 'the refusal states a range the guard no longer enforces alone')
+      .toContain('integer');
+
+    // ⭐ The mechanical form, and the reason this is not a `toContain` on a
+    // word: read the range back OUT of the rendered sentence and confirm that
+    // a value satisfying it is refused anyway — which is precisely why the
+    // range can no longer be the whole sentence.
+    const rendered = notice.match(/\((?:[^()]*?)(\d+)-(\d+)\)/);
+    expect(rendered, 'the refusal no longer renders the range at all').not.toBeNull();
+    const low = Number(rendered![1]);
+    const high = Number(rendered![2]);
+    expect(low, 'the rendered floor drifted from the constant').toBe(SMTP_PORT_MIN);
+    expect(high, 'the rendered ceiling drifted from the constant').toBe(SMTP_PORT_MAX);
+    expect(587.5 >= low && 587.5 <= high, 'the example stopped being inside the stated range')
+      .toBe(true);
+    expect(isValidSmtpPort(587.5), '587.5 is accepted again').toBe(false);
+
+    // ⛔ The range is still GENERATED, never re-typed — the word added above
+    // is prose about the predicate and must not have dragged a literal in
+    // with it. (`SMTP_PORT_RANGE_TEXT` is asserted against the constants two
+    // cases up; this holds the notice to that same construct.)
+    expect(notice).toContain(SMTP_PORT_RANGE_TEXT);
+  });
+
+  it('refuses a fractional port AT CONSTRUCTION, under its own name (#13189)', () => {
+    // BEFORE, MEASURED on `origin/main@56c5b1dbe` through the built
+    // `dist/index.js`: construction ACCEPTED `587.5`, `describe().port` read
+    // it straight back, and the operator's first sight of the problem came at
+    // SEND time as a bare `RangeError` — `code: 'ECONNECTION'` once nodemailer
+    // has re-coded `ERR_SOCKET_BAD_PORT` — reading `Port should be >= 0 and <
+    // 65536. Received type number (587.5).`, which names a TCP rule and no
+    // part of the Settings field the operator typed in.
+    expect(() => new SmtpTransport({ host: 'smtp.example.test', port: 587.5 }))
+      .toThrow(formatInvalidSmtpPortNotice(587.5));
+
+    // The refusal carries the operator's OWN value. Asserted through the
+    // contract's generator above and then, separately, on the spelling — a
+    // bare `.toThrow()` here would also pass on the `host is required`
+    // refusal that guards the line before it.
+    expect(() => new SmtpTransport({ host: 'smtp.example.test', port: 587.5 }))
+      .toThrow(/invalid port '587\.5'/);
+
+    // ⛔ The fence on the repair: integer ports still construct, at both
+    // bounds. A guard that refused `587.5` by refusing everything would
+    // satisfy every line above this one.
+    for (const port of [SMTP_PORT_MIN, 25, 465, 587, SMTP_PORT_MAX]) {
+      expect(new SmtpTransport({ host: 'smtp.example.test', port }).describe().port)
+        .toBe(port);
+    }
   });
 
   it('⛔ floors at 1, not at 0 — this range is not the CLI listen range', () => {

packages/plugins/plugin-email/src/transports/smtp-port-contract.ts

@@ -79,28 +79,67 @@ export const SMTP_PORT_MAX = 65535;
 export const SMTP_PORT_RANGE_TEXT = `${SMTP_PORT_MIN}-${SMTP_PORT_MAX}`;
 
 /**
- * Is `port` inside the range this transport will connect on?
- *
- * ⚠️ This is the enforcement `smtp.ts` already had, moved and NOT narrowed.
- * The accept set is unchanged in both directions, deliberately: a refactor
- * that quietly rejected a value which worked yesterday would be a behaviour
- * change wearing a cleanup's clothes. In particular a **non-integer** inside
- * the range (`587.5`) is accepted here exactly as it was before, and is
- * refused later by `net.connect` under an internal name — filed separately
- * rather than repaired here, because that is an accept-set defect and this
- * card is about the duplication.
+ * Is `port` a port this transport can actually connect on?
+ *
+ * Three conditions, and `Number.isInteger` carries the first two of them:
+ * finite (it refuses `NaN` and both infinities), whole, and inside the range.
+ *
+ * ## ⭐ Why integrality is part of the contract (#13189)
+ *
+ * This predicate arrived from `smtp.ts` as `Number.isFinite` and no more, and
+ * #12993 kept it that way on purpose — narrowing an accept set inside a
+ * refactor whose whole claim is behaviour preservation would have been a
+ * behaviour change wearing a cleanup's clothes. It is narrowed here, in a card
+ * that is about nothing else, for a reason that is measured rather than
+ * stylistic:
+ *
+ * A fractional port **cannot ever connect**. MEASURED on Node 22:
+ * `net.connect({ port: 587.5 })` throws `ERR_SOCKET_BAD_PORT`, and by the time
+ * nodemailer has re-coded it the operator is shown a bare `RangeError`
+ * (`code: 'ECONNECTION'`) reading `Port should be >= 0 and < 65536. Received
+ * type number (587.5).` — at SEND time, naming a TCP rule and not the
+ * Settings field they typed in. So admitting `587.5` here bought nothing: it
+ * deferred a certain refusal by three layers and stripped the transport's name
+ * off it on the way.
+ *
+ * ⭐ And the refusal this door already emitted **stated the integer rule
+ * without enforcing it**: `587.5` is inside `1-65535` on any reading of
+ * `(expected 1-65535)`. The sentence and the check disagreed. Exactly one of
+ * them had to move, and the one that can never be satisfied is the value.
+ *
+ * ## ⚠️ This is NOT the CLI contract diverging — it is the two converging
+ *
+ * `packages/cli/src/utils/port-contract.ts` is often read as the precedent
+ * *against* this, because its module header is emphatic that a door may not
+ * narrow what boots. Read to the end of it: `parseRequestedPort` is
+ * `if (!Number.isInteger(parsed)) return null;` and `strictPortReading` is
+ * `Number.isInteger` behind `/^[+-]?\d+$/`. That module's width is about
+ * **string spellings** — `3e3`, `0x0BB8`, `3000.0`, `3000abc`, `+3000`,
+ * `08080` — every one of which `parseInt` reduces to an INTEGER before it is
+ * ever range-checked. It governs how an operator may *spell* a port, never
+ * whether a fractional one is admitted. On integrality the CLI has been strict
+ * all along, in code. `smtp-port-contract.test.ts` holds that reading.
  */
 export function isValidSmtpPort(port: number): boolean {
-  return Number.isFinite(port) && port >= SMTP_PORT_MIN && port <= SMTP_PORT_MAX;
+  return Number.isInteger(port) && port >= SMTP_PORT_MIN && port <= SMTP_PORT_MAX;
 }
 
 /**
- * The refusal for a port outside the range, naming the value the caller
- * actually supplied and the range from the constants above.
+ * The refusal for a port this transport will not connect on, naming the value
+ * the caller actually supplied and the rule from the constants above.
  *
  * `raw` is the caller's ORIGINAL value, not the coerced number: an operator
  * who configured `"abc"` needs to see `abc`, not `NaN`.
+ *
+ * ⭐ **"an integer" is load-bearing, not decoration (#13189).** This sentence
+ * used to read `(expected 1-65535)` while the guard admitted `587.5` — which
+ * IS in 1-65535 — so the door stated a rule it did not enforce. Now that the
+ * guard tests integrality, the sentence has to say so or the lie has merely
+ * moved from the check to the message. The range itself stays GENERATED from
+ * {@link SMTP_PORT_MIN} / {@link SMTP_PORT_MAX}: the word is prose about the
+ * predicate, and ⛔ re-spelling either bound here would rebuild the exact
+ * duplication #12993 deleted.
  */
 export function formatInvalidSmtpPortNotice(raw: unknown): string {
-  return `SmtpTransport: invalid port '${String(raw)}' (expected ${SMTP_PORT_RANGE_TEXT})`;
+  return `SmtpTransport: invalid port '${String(raw)}' (expected an integer ${SMTP_PORT_RANGE_TEXT})`;
 }