docs(plugin-email): re-anchor the dead tracker citations to the commits that decided them

.changeset/20596-plugin-email-provenance-anchors.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/plugin-email': patch
+---
+
+Provenance comments in `plugin-email` were re-anchored
+
+Comment and docblock lines under `src/` that cited tracker numbers which no
+longer resolve on GitHub now cite the commit in this repository's history that
+decided the matter, and say in their own words what was decided. Comments
+only: no type, schema, export, log or refusal text, or runtime behaviour changes.

packages/plugins/plugin-email/src/email-headers-internal.integration.test.ts

@@ -248,7 +248,7 @@ describe('sys_email.headers_json — authored headers vs the data API (#8149)',
   });
 
   it('a message authored WITHOUT headers still delivers — the optional-column trap', async () => {
-    // The regression PR #8675 measured on a sibling card: `headers_json` is
+    // The regression commit c9f595083 records from a sibling card: `headers_json` is
     // `required: false`, and the overwhelming majority of real rows have no
     // custom headers at all. A seam that inferred "key missing ⇒ the strip
     // ran" would treat every ordinary email as a redacted row. This pins that

packages/plugins/plugin-email/src/email-service.test.ts

@@ -339,7 +339,7 @@ describe('rowToNormalized', () => {
   });
 });
 
-// ── #11741 — sys_email organization stamping ────────────────────────────────
+// ── Commit b706af987 — sys_email organization stamping ──────────────────────
 // The writer runs under a constant SYSTEM context, so the ONLY organization a
 // row can carry is the one the input carries: `SendEmailInput.organizationId`
 // is stamped onto `sys_email.organization_id` verbatim (pass-through), and its

packages/plugins/plugin-email/src/email-service.ts

@@ -739,7 +739,7 @@ export class EmailService implements IEmailService {
       ...(input.relatedObject ? { related_object: input.relatedObject } : {}),
       ...(input.relatedId ? { related_id: input.relatedId } : {}),
       ...(input.sentBy ? { sent_by: input.sentBy } : {}),
-      // #11741 — pass-through ONLY. This writer runs under a constant system
+      // Commit b706af987 — pass-through ONLY. This writer runs under a constant system
       // context, so the input's organization is the one fact it may stamp:
       // no resolution, no default, no fabrication (a wrong organization_id is
       // worse than a null). Absent ⇒ the column stays unwritten.
@@ -1436,7 +1436,7 @@ export class EmailService implements IEmailService {
       ...(input.relatedObject ? { relatedObject: input.relatedObject } : {}),
       ...(input.relatedId ? { relatedId: input.relatedId } : {}),
       ...(input.sentBy ? { sentBy: input.sentBy } : {}),
-      // #11741 — sendTemplate is itself a producer of send(): forward the
+      // Commit b706af987 — sendTemplate is itself a producer of send(): forward the
       // caller's organization so the sys_email row it persists is stamped.
       ...(input.organizationId ? { organizationId: input.organizationId } : {}),
     };

packages/plugins/plugin-email/src/internal-header-readback.ts

@@ -34,7 +34,7 @@
  * majority of real rows have no custom headers at all. Under a key-absence
  * inference every ordinary header-less email would look like a redacted row
  * and force a privileged read, and an engine without the accessor would fail
- * every ordinary send. (PR #8675 hit exactly this on `sys_account`'s optional
+ * every ordinary send. (Commit c9f595083 records exactly this on `sys_account`'s optional
  * token columns: inheriting "key missing ⇒ the strip ran" from a
  * `required: true` column broke ordinary sign-in, 16 red tests.) The schema
  * flag is cardinality-independent: it is true when the engine redacts and

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

@@ -31,7 +31,7 @@
  * 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
+ * ## Commit 33fbd3566 — 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
@@ -225,7 +225,7 @@ describe('#12993 — one SMTP port range, every door states it from there', () =
   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
+    // table as MEASURED, not endorsed. Commit 33fbd3566 is the change 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

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

@@ -84,7 +84,7 @@ export const SMTP_PORT_RANGE_TEXT = `${SMTP_PORT_MIN}-${SMTP_PORT_MAX}`;
  * 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)
+ * ## ⭐ Why integrality is part of the contract (commit 33fbd3566)
  *
  * 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
@@ -131,7 +131,7 @@ export function isValidSmtpPort(port: number): boolean {
  * `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
+ * ⭐ **"an integer" is load-bearing, not decoration (commit 33fbd3566).** 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

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

@@ -218,7 +218,7 @@ describe('smtpOptionsFromMailSettings', () => {
     expect(smtpOptionsFromMailSettings({ smtp_host: 'smtp.x' })).toEqual({ host: 'smtp.x' });
   });
 
-  // #13190 — `absent` vs `present but unreadable`, which this function used to
+  // Commit 56c5b1dbe — `absent` vs `present but unreadable`, which this function used to
   // collapse into one bucket. A port that could not be read was DELETED here,
   // and `SmtpTransport` then applied its built-in 587: a configured `abc`
   // became a working-looking connection nobody chose, and `describe()`
@@ -269,18 +269,18 @@ describe('smtpOptionsFromMailSettings', () => {
     });
 
     it('refuses a READABLE but FRACTIONAL port by name, without a second door (#13189)', () => {
-      // The bucket #13190 never had to name, because the guard below it
+      // The bucket commit 56c5b1dbe never had to name, because the guard below it
       // admitted the value: `'587.5'` is present, readable, finite and inside
       // `1-65535`, so it mapped straight through and died at SEND time under
       // `RangeError: Port should be >= 0 and < 65536` — a TCP rule, naming no
-      // part of Settings → Mail → Port. #13189 made the guard test
+      // part of Settings → Mail → Port. Commit 33fbd3566 made the guard test
       // integrality, so it is refused at construction now, in this
       // transport's own sentence, carrying what the operator actually typed.
       const opts = smtpOptionsFromMailSettings({ smtp_host: 'smtp.x', smtp_port: '587.5' });
 
-      // ⛔ The mapping still PASSES IT THROUGH. #13190's rule is that this
+      // ⛔ The mapping still PASSES IT THROUGH. Commit 56c5b1dbe's rule is that this
       // function hides nothing from the guard and adds no parallel refusal of
-      // its own; #13189 changed which numbers the guard refuses, not where
+      // its own; commit 33fbd3566 changed which numbers the guard refuses, not where
       // the refusal lives. A repair that started rejecting here instead would
       // pass the next line and quietly rebuild the second door.
       expect(opts, 'the mapping dropped the key instead of passing it down')

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

@@ -65,7 +65,7 @@ export interface SmtpTransportOptions {
    *
    * ⚠️ An **integer** in `1-65535`, refused at construction otherwise —
    * `number` cannot say that in the type, and a fractional port is not a
-   * near miss but an address `net.connect` will never accept (#13189).
+   * near miss but an address `net.connect` will never accept (commit 33fbd3566).
    */
   port?: number;
   /**
@@ -124,7 +124,7 @@ export class SmtpTransport implements IEmailTransport {
     // below is GENERATED from it. A hand-written `(expected 1-65535)` on this
     // line is exactly the drift #12993 removed: it sat next to the check it
     // described, so the two could disagree and nothing would fail — which is
-    // not hypothetical. They DID disagree until #13189: the check admitted
+    // not hypothetical. They DID disagree until commit 33fbd3566: the check admitted
     // `587.5` and the sentence said `1-65535`, a range `587.5` satisfies. The
     // guard tests integrality now and the generated sentence says so, so the
     // two still cannot drift apart without one of them being rewritten.