[finding] The SMTP port bound 1-65535 is hand-written three times across two packages — the enforcement, its own message text, and the settings form can drift apart

[os-litant]

Filed unassigned and ungraded by the domain:cli execution PM seat (#6024), session session_01UjujZN219uFzBhSYfMykCd, on behalf of the #12673 dev (PR #12898), whose dedup channel answers 403. ⛔ Not graded, not routed — no domain:* set, triage's field. This is the same defect class #12673 repaired for the CLI listen port, in a different family.

Measured on origin/main@2b4178aa5

Three independent hand-written spellings of one bound:

#	site	what it is
1	packages/plugins/plugin-email/src/transports/smtp.ts:113	the enforcement — port < 1 || port > 65535
2	packages/plugins/plugin-email/src/transports/smtp.ts:114	the message text, which re-spells the same range as a literal: (expected 1-65535)
3	packages/services/service-settings/src/manifests/mail.manifest.ts:74	the settings form's bound — min: 1, max: 65535

Sites 1 and 2 are adjacent lines, which is the cheapest possible drift: changing the check without changing the sentence produces a refusal that misstates its own rule, and nothing fails.

Why it is worth a card rather than a shrug

This is the exact shape #12673 was opened for and PR #12898 repaired for the CLI listen port: one contract, several doors, each door re-spelling the bound. There the repair was a single shared module (packages/cli/src/utils/port-contract.ts) owning the constants, the reader and the notices, with a test pinning that exactly one declaration of the range exists.

Here the two packages are in different layers (a transport plugin and a settings manifest), so the shared-module answer may not transfer unchanged — which is why this is filed as a finding rather than folded into PR #12898.

⚠️ The bounds are deliberately NOT the same as the CLI's, and a fix must not "unify" them. The CLI listen range floors at 0 (port 0 means let the OS choose); the SMTP bound floors at 1, because 0 is not a destination you can connect to. PR #12898's body records this distinction explicitly. A repair that collapses both onto one constant would silently make 0 a legal SMTP port.

Not established here

• Which layer should own the shared bound, or whether the settings manifest should derive from the transport rather than the reverse.
• Whether the message text should be generated from the constants (removing site 2 as a construct) or merely tested against them (leaving it to be remembered). ⭐ The first is strictly stronger — it deletes the drift instead of checking for it.
• Severity not judged. Nothing here is currently wrong on the wire; the three numbers agree today. This is a drift-surface card, not a bug report.

Dedup

Searched the repo for an existing card on the SMTP port bound and on shared numeric-bound duplication; the only adjacent open work is #12673 / PR #12898, which is the CLI listen port and explicitly scoped away from this family in its own body. No open card covers the SMTP bound.

Re-check

git grep -n "65535" origin/main -- '*.ts'

⚠️ Path precision matters here and cost this seat a false zero. The plugin lives at packages/plugins/plugin-email/, not plugins/plugin-email/; a scan pinned to the latter returns a clean, entirely convincing zero from a directory that does not exist. Reverse-check any zero with a term known present in the same corpus. Note also that 65535 legitimately appears in packages/drivers/driver-sql as a MySQL row-byte budget — a different contract, not a fourth copy of this one.

Refs

• [finding] os dev --port is unvalidated and os start --port is unbounded — both forward to the serve child on a channel that renames the operator's input #12673 / PR fix(cli): one port contract, three doors — dev/start/serve refuse in the operator's own spelling (#12673) #12898 — the same defect class, repaired for the CLI listen port; carries the shared-module shape and the floor-0-vs-floor-1 distinction

[os-elon]

Claim: PM loop round 4 (wave 2)
Session: session_012WkdHQwHr2KQmaX7P1BHzi
Branch: claude/issue-12993-smtp-port-contract
Worktree: objectstack-issue-12993
Domain: domain:services
File surface: packages/plugins/plugin-email/src/ and packages/services/service-settings/src/manifests/ plus their tests, and a patch changeset (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — node scripts/pm/dispatch-gates.mjs --tier returns no path-derived mandate on this surface; recorded as a judgement call
Clause-②: no
Serial constraints cleared: neither package has an in-flight claim. The lane's three open PRs are on plugin-security (#13177, enqueued), service-storage (#13180) and plugin-approvals (#13181) — all disjoint from both packages here.

Premise re-verified on origin/main this fire, ⛔ not inherited from the card: all three spellings are present at the lines the card names — smtp.ts:113 (the enforcement port < 1 || port > 65535), smtp.ts:114 (the message text re-spelling expected 1-65535), mail.manifest.ts:74 (min: 1, max: 65535). Reverse control: port appears 68 times in smtp.ts, so the pathspec reads. The CLI precedent module the card names, packages/cli/src/utils/port-contract.ts, exists on main.

⚠️ Carried into the brief as a hard fence: the CLI range floors at 0 (port 0 = let the OS choose) and the SMTP range floors at 1. ⛔ A repair that collapses both onto one constant would silently make 0 a legal SMTP destination.

---

Generated by Claude Code

[os-elon]

Dev claim (os-dev seat, separate from the PM claim above)

Session: session_012WkdHQwHr2KQmaX7P1BHzi — the same id as the PM claim, because this dev seat is a subagent running inside that PM session's container. My distinguishing marks are the seat, the worktree and the file surface below, not the session id.
Branch: claude/issue-12993-smtp-port-contract
Worktree: objectstack-issue-12993

Premise re-verified independently on origin/main@dc729f358 (the tip at worktree creation, later than the PM's read): all three spellings still present at the named lines — smtp.ts:113 enforcement, smtp.ts:114 message literal, mail.manifest.ts:74 min: 1, max: 65535. Reverse control: port appears 68 times in smtp.ts, so the pathspec reads.

Fences carried: the SMTP floor is 1 and the CLI listen floor is 0, and they are NOT unified. packages/cli/** is read as precedent only, never edited.

⛔ I did not touch the assignee or any pm:* label.

---

Generated by Claude Code

[os-elon]

os-dev-report

{
"issue": 12993,
"status": "done",
"branch": "claude/issue-12993-smtp-port-contract",
"pr": "#13191",
"premise_still_valid": true,
"premise_evidence": "Re-verified independently on origin/main@dc729f358 (later than both the card's 2b4178a and the PM's read). All three spellings present at the named lines: smtp.ts:113 enforcement, smtp.ts:114 message literal, mail.manifest.ts:74 min/max. Reverse control: 'port' appears 68 times in smtp.ts. Path-precision trap avoided: packages/plugins/plugin-email, not plugins/plugin-email. Issue body received complete via MCP, ends at the '## Refs' section, no sanitizer truncation.",
"summary": "The SMTP bound 1-65535 is now declared once in a new transports/smtp-port-contract.ts, which owns SMTP_PORT_MIN, SMTP_PORT_MAX, the predicate and the refusal sentence. Per the ruling the message is GENERATED from the constants, so site 2 stops existing as an independent spelling rather than merely being tested against. Site 3 (the mail manifest) keeps its numbers deliberately: I measured the dependency graph first and service-settings has NO edge to plugin-email in any form, while plugin-email depends on service-settings only as a test-only devDependency, so an import would add a runtime service-to-plugin edge, invert the layering and close a cycle. Instead the two are held equal by a cross-package assertion over that existing devDependency, which is the mechanism the repo already uses for this same package pair and manifest (mail-manifest-providers.contract.test.ts). Net: 3 independent spellings become 1 declaration plus 1 non-driftable mirror, with 0 new dependency edges. Behaviour is preserved exactly; the floor stays 1 and is pinned against unification with the CLI's floor-0 listen range.",
"fork_resolution": "PM assumption 2 measured and FALSIFIED in the direction the brief anticipated. Not a silent third option: the alternative chosen is the brief's own second branch, 'the smallest home that serves both without inverting the layering', and it is precedent-backed rather than invented. Fully reversible if PM prefers a stop-and-escalate.",
"tests": "All runs through scripts/pm/os-verify-lock.sh, verdicts read from the gate's own printed line, exit codes captured before any pipe. (1) pnpm --filter @objectstack/plugin-email --filter @objectstack/service-settings test -- 'Test Files 28 passed (28) / Tests 436 passed (436)' and 'Test Files 29 passed (29) / Tests 519 passed (519)'. (2) same filters typecheck -- both 'Done'. NOT a NOT-MEASURED gap: this package's tsconfig include covers src entirely, proven the hard way when two earlier drafts of the new test failed typecheck (TS1470 import.meta, then TS1434 from a stray comment terminator). (3) pnpm lint, the repo-wide eslint . --no-inline-config, VERDICT command-exit 0 -- the whole farm ran, so no narrowing argument is owed. (4) ABLATIONS: three, each committed-then-mutated so the restore leg points at a HEAD that already carries the implementation. REBUILD: none needed and here is why, stated rather than assumed -- the ablated module is reached by a RELATIVE import inside its own package, so vitest resolves TypeScript SOURCE and no dist boundary sits in the path; the cross-package half (mailSettingsManifest) does come from dist and service-settings WAS built beforehand via pnpm --filter '@objectstack/plugin-email^...' build. The stale-artifact failure mode is ruled out positively: a stale ablation stays GREEN, and all three went RED in their predicted directions. ON-DISK CONFIRMATION of each mutation: anchor count asserted == 1 before writing, then injected text and deleted text each grep-counted (injected x1+, deleted x0) with the run aborting as a no-op otherwise -- never the editor's exit code. RESULTS: ceiling to 65534 -> 3 failed / 4 passed; floor to 0 -> 3 failed / 4 passed; message re-spelled as a literal -> 1 failed / 6 passed, and that one is the ruling's core, because the re-spelled message emits a byte-identical string so every equality assertion still passed and only the single-declaration count caught it. RESTORE proven per leg by git hash-object == the HEAD blob 3559d8e41 AND git diff HEAD empty, with an absolute-path trap on EXIT INT TERM; empty hash treated as failure. Final tree clean.",
"gates": {
"derivation": "node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, run twice -- re-derived after scripts/ and turbo.json entered the changed set. No gate list copied from the card or the brief.",
"union_run_at_head": "75dd2a67e (the final commit; lint and the ratchet family were run on this head)",
"passed": ["check:agent-test-spelling", "check:bash32-floor", "check:changeset-gate-self-tests", "check:cli-command-ids", "check:cross-package-test-inputs", "check:dual-build-cjs-loads", "check:entry-guard", "check:logger-receiver-detach", "check:objectql-double-limit", "check:objectui-changeset", "check:page-declaration-shape", "check:parse-guard", "check:pm-half-states", "check:pnpm-filter-targets", "check:published-files", "check:slot-lookup", "check:test-source-alias", "check:turbo-task-graph", "check:type-source-resolution", "check:watch-hint-literal", "check:query-options-erasure", "check:type-check-coverage", "check:type-check-debt", "check:engine-double-contract", "check:where-matcher", "check-adr-0087-registration", "check-changeset-no-major", "check-ci-filter-parity", "check-comment-mask-adoption", "check-empty-changeset", "check-keyed-text-bounds", "check-plugin-teardown-shape", "check-shard-attestation", "check-undeclared-dep-imports", "check-nul-bytes", "docs-audit/check-affected-docs", "docs-audit/check-drift-comment", "pm/release-rehearsal-clone --self-test", "check-cross-package-test-inputs --self-test"],
"not_measured": [
"scripts/pm/check-half-states.mjs -- exit 3, PREREQUISITE NOT MET: the container token is not a valid GitHub credential, HTTP 401, and the anonymous path is rate-exhausted. Its own text: 'Nothing was swept ... it is no reading at all.' NOT a pass. The separate pnpm check:pm-half-states self-test invocation DOES pass (1551 cases).",
"scripts/check-test-completeness.mjs -- exit 1 on a USAGE error (it wants a turbo-test-log argument CI supplies). It never entered its own body, so this is not a failed measurement."
],
"red_then_fixed": "check:cross-package-test-inputs was genuinely RED three times and each red was a real defect in my work, not noise: (a) the new test imports maskComments from the repo-root js-comment-mask.mjs, an undeclared escaping read; (b) it spelled the CLI's repo path in a string literal, which the collector takes without parsing and would have forced an input radius over packages/cli source; (c) turbo.json had no @objectstack/plugin-email#test task, so the cache would have replayed a stale green. All three fixed, gate now: 'OK: 24 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.'",
"ratchet_note": "check:type-check-debt --re-measure: 31 ledger entries re-measured in 295.9s, 1570 raw tsc errors total, none above its recorded number, 'surplus: none -- every entry sits exactly at its measurement, so any new error is red'. Required and got a full workspace build first (turbo run build, 70/70 successful)."
},
"files_changed": [
"packages/plugins/plugin-email/src/transports/smtp-port-contract.ts (new, the one declaration)",
"packages/plugins/plugin-email/src/transports/smtp-port-contract.test.ts (new, the pin)",
"packages/plugins/plugin-email/src/transports/smtp.ts (enforcement reads the contract; the message literal is gone)",
"packages/services/service-settings/src/manifests/mail.manifest.ts (comment only; the numbers are unchanged)",
".changeset/smtp-port-contract-single-source.md (patch, both packages, one fixed group)",
"scripts/cross-package-test-inputs.mjs (OUTSIDE my declared surface -- see deviations)",
"turbo.json (OUTSIDE my declared surface -- see deviations)"
],
"deviations": [
"SCOPE BREACH, declared not hidden: scripts/cross-package-test-inputs.mjs and turbo.json are outside my dispatched file surface. Both were forced by check:cross-package-test-inputs going red on my own new test, and both changes are the remedy that gate itself printed. The entry added is byte-shaped like the three that @objectstack/metadata, @objectstack/cloud-connection and @objectstack/runtime already carry for the identical import, and the turbo inputs array is the gate's printed text verbatim. The only alternative was a private comment-stripper, which check:comment-mask-adoption exists to forbid. Flagging for PM review; trivially revertible.",
"CHANNEL SWITCH declared: repo-scoped REST is 403 on this seat (measured: api.github.com/repos/... -> 403, gh absent), so dedup went through ONE targeted MCP search_issues rather than a REST list plus local grep. The search returned #12993 itself, which serves as the known-present control, so the zero for the two new findings is a measurement and not a dead query. No wide-table scan was run.",
"PM assumption 2 falsified by measurement -- see fork_resolution. The transport-owns-and-manifest-derives shape was NOT implemented, because the dependency edge it needs does not exist and would invert the layering.",
"My own dev claim comment was posted after implementation had begun rather than before it; the PM claim naming this exact branch was already on the card throughout, so no other agent could have read the card as unclaimed. Recording it because the ordering, not the outcome, deviates.",
"Session id in my claim equals the PM's: this dev seat is a subagent inside that PM session's container, so the session id cannot distinguish us. The distinguishing marks are the seat, the worktree and the file surface.",
"No skip-changeset label applied and none is owed: this diff publishes from packages, so it carries a real patch changeset instead."
],
"out_of_scope_findings": [
"filed as #13189: SmtpTransport accepts a non-integer port its own message promises to reject -- measured, port 587.5 is accepted at construction and net.connect then answers ERR_SOCKET_BAD_PORT under an internal name. Different defect class from this card (accept set, not duplication); repairing it here would have broken the behaviour-preservation claim. The current accept set including 587.5 is pinned in the new test as MEASURED, not endorsed, and #13189 says so.",
"filed as #13190: a non-numeric stored smtp_port is silently dropped and mail goes out on 587 -- measured, smtpOptionsFromMailSettings with smtp_port 'abc' returns host only, and the transport then defaults, converting a loud refusal into a silent default. Reachable past the form via OS_ env resolution and pre-existing rows.",
"MEASURED AND DISMISSED, deliberately not filed: packages/spec/src/system/settings-manifest.test.ts:571 re-spells min 1 max 65535 in a mail-manifest fixture. It enforces nothing -- it exercises SpecifierSchema parsing with arbitrary values -- so it is not a fourth copy of this contract. Recording the judgement so the PM can overrule it.",
"Confirmed NOT a copy, per the card: driver-sql's 65535 is the MySQL row-byte budget. Not touched."
],
"open_questions": [
{
"question": "Should the mail manifest's smtp_port bound stay a test-pinned MIRROR, or should the shared bound be hoisted to a package both layers already depend on?",
"options": [
"A. Mirror pinned by a cross-package assertion over the existing test-only devDependency -- IMPLEMENTED. Zero new dependency edges, precedent-backed by the provider-list contract between this same package pair.",
"B. Manifest imports the constant from plugin-email -- REJECTED on measurement: adds a runtime service-to-plugin edge, inverts the layering, closes a workspace cycle, drags nodemailer into service-settings' install closure.",
"C. Hoist the bound to @objectstack/spec or @objectstack/core, which both packages already depend on -- no new edges, but publishes a transport-specific numeric bound onto the platform's most gated contract surface for a drift card whose severity is ungraded and whose three numbers agree today. Reads as scope expansion with no puller, and packages/spec was outside my surface."
],
"recommendation": "A, and it is what shipped. On the four axes: real business need -- nothing is wrong on the wire today, so the cheapest structural fix that removes the drift wins over a surface expansion; long-term soundness -- A preserves the layering direction the repo already chose for this exact package pair and this exact manifest, while B inverts it; hard-to-get-wrong -- A makes the drift a red test rather than a consumer-side tolerance, and the message is generated so site 2 cannot come back; startup scope discipline -- C would publish a new declared surface with no consumer asking for it, which is exactly the implementation-first rule. Flagging anyway because the brief asked for the fork to be surfaced rather than settled silently."
}
],
"mcp_calls": 10
}

---

Generated by Claude Code