Stage 1 batch 2 of docs/COMMENTS-REDESIGN-2026.md: the render function no longer queries the comment table itself. It asks the subsystem for one page and assembles markup, which is what lets the later stages change storage and sorting in one place instead of at every call site.

Core changes:

1. Comment list rendering (core/system.php):

2. ashowcom() reads through $com->getList() instead of its own SQL

   • the count query, the page query and the author group join are gone
   • pagination, the visibility scope and the running comment number now come

from the class, so a count can no longer disagree with the page it counts

• the unreachable ADMIN_FILE read branch left with the read it built; the

admin render branches stay until the function itself is removed

• local names follow the naming rules of .rules/global.md

  • the running number $a became $numb, the checkbox flag $b became $mark

Benefits:

• 253 lines down to 186, and no direct comment SQL left in the render path
• one description of what a viewer may see, shared by the count and the page
• a broken comments.num setting falls back to 15 instead of dividing by zero

Technical notes:

• no schema, template or markup change; the rendered output is byte for byte the same

• verified against the pre-move file over 26 URLs in both sort directions: first, middle, last, out-of-range and zero pages, a target with no comments, a target spilling one row onto a second page, one holding exactly the page size, garbage and negative page parameters, and a missing target id

• comment-baseline verify stays OK on all eight modules

• the signed-in and moderator views need a browser session and are not covered by this batch

Stage 1, batch 1 of docs/COMMENTS-REDESIGN-2026.md opens the move of the comment engine out of the 253-line ashowcom() monolith into one class. This batch adds the class and its reads only; nothing calls them yet, so the running system is untouched and every later batch migrates call sites against a surface already proven equal to the queries it replaces.

Core changes:

1. Comment subsystem (core/classes/comment.php):

2. New class owning every read of the comment table

   • getCount() and getList() serve the frontend list with its pagination
   • getAdminList() serves the moderation list across state, module and the five search fields
   • getComment(), getUserList() and getModuleList() serve the admin edit form, the profile activity feed and the module selector
3. CommentStatus and CommentMode enums replace the bare 0/1/2 literals of status and acomm
4. getScope() and getAdminScope() build a visibility scope once and getTotal() counts against that same source, so a list and its count cannot describe different rows
5. getAuthors() resolves the author records of one page in a single round trip, keeping the group-join precedence the current rendering relies on
6. getPager() holds the page arithmetic the frontend and the moderation list currently spell out twice
7. Request wiring (core/system.php):
8. The class loads beside the other services and is constructed after the parser as $com
9. The constructor takes $conf as a third argument because no class in core/classes reaches for a global and the reads need the comments section for their pagination
10. Read parity harness (tests/Support/contract_probe.php, tests/Unit/CommentReadTest.php):
11. New commentread probe mode puts every legacy statement beside the method replacing it, against the live rows of the installation
12. 8 test cases cover the count, the first and last list page, the author record, the activity feed, the module list, a single read, a missing id and all five moderation filters
13. The list case was proven to fail by flipping the sort direction, so the parity claim is measured rather than asserted

Benefits:

• Byte parity of the rendered comment list becomes checkable per batch instead of at the end of a twenty-site diff
• One visibility predicate per list removes the class of defect the hand-built where/count pair of the admin module still carries
• The read surface is settled before any call site moves, so the migration batches change callers only

Technical notes:

• No table, column or index changes; no behaviour change, because nothing calls the class yet
• Public reads select status = 1 rather than status != 0 per the design query rule; the column holds 0 and 1 only across all 7357 rows and the probe proves the results identical
• The author search keeps two placeholders for one term because emulated prepares are off and a native statement refuses a repeated named placeholder
• getUserList() shares its name with the unrelated global function at core/system.php:4792, which no stage removes; a method and a function of one name coexist without ambiguity

Stage 1 batch 5 of docs/MAIL-2026.md gives the three transports a configuration and an administrator a way to prove it works before real mail depends on it. The delivery half of the subsystem is now reachable from the panel rather than from a hand-written file, and the shipped defaults keep every installation delivering through PHP mail() until someone chooses otherwise. The 26 call sites still use addMail(), so nothing an installation sends has changed.

Core changes:

1. Configuration (config/mail.php):

2. Ship every key the plan lists at its documented default, transport php, the site-derived and SMTP credential fields empty

   • keys are written in the order setConfigFile() writes them, since it sorts

before export and a shipped file in reading order would be rewritten by the
first save

• the queue keys ship complete but have no control yet: a row for batch or

keep would govern machinery that arrives in stage 2

1. Mail tab (admin/modules/config.php):

2. getMailPanel() builds the _MAILOPT tab: transport, sender identity, SMTP, the Sendmail path, the test send, then the existing mtemp

   • getMailRow() carries the transport a row belongs to, so the value hook can

hide it for every other one

• the password field renders empty whatever is stored, and an empty

submission keeps the stored value through the setConfigFile() merge

• a missing openssl or a disabled proc_open is reported beside the control it

disables; neither control is removed, because a disabled field posts nothing
and the next save would silently reset it

• save() writes config/mail.php over the stored section, so the queue keys and an unchanged password survive

  • transport and encryption accept only their listed values
  • a sender or Reply-To address that fails validation refuses the whole save

before any file is written, rather than being stored and silently stopping
delivery

• mailtest() is the fourth operation: POST, checkSiteToken(), the recipient defaults to adminmail, and the answer is either success or the transport's own error string

  • the field carrying the password is dropped from the request first, because

Logger records every posted field with a failure entry and the button
submits the shared config form

1. Row visibility (plugins/system/slaed.js):

2. setFieldShows() shows a row only for named values of another control, beside the tab-index hook it complements and in the same style

   • a row is written visible and is only ever hidden, so the settings stay

reachable when the script is not

1. Locales (admin/lang/*.php):

2. Twenty-one constants in all six languages, reusing _USER, _PASSWORD, _NONE, _SEND and _ERROR rather than adding scoped duplicates

3. Tests and plan (tests/Unit/MailConfigTest.php, docs/MAIL-2026.md):

4. Five cases hold the shipped file to its key set, its defaults, its key order and its string types, so a fresh install and an upgrade cannot diverge

5. Record the batch in Progress with its decisions, the defect found and fixed inside it and the blockers left open

Benefits:

• Delivery can be pointed at a relay, a binary or PHP mail() from the panel, and the choice is proved by a one-click test send instead of by the next password reset that fails

• Configuration and its writability notice live where every other config section already lives, with no new module, no new tab and no new token mechanism

• The value-driven hook is general: any row can now depend on the value of another field, which the tab-index hook could not express

Technical notes:

• The test send reads the stored configuration, so settings are saved and then tested; the row says so

• An empty password field cannot clear a stored password, which is what makes it safe to render the field empty

• Header-bound values are stored as typed and sanitised where they reach a header, since the input text filter would corrupt a sender name inside MIME

• Without JavaScript the config module shows its first tab only, which is how every tab on that screen already behaved

Stage 1 batch 3 of docs/MAIL-2026.md adds the second transport and the dispatch that chooses one. The binary is reached through proc_open() with an argument array, so no shell is involved and mail.sendmail stays a path rather than a command. Nothing selects it yet, since config/mail.php arrives in batch 5, so every installation keeps delivering through PHP mail().

Core changes:

1. Sendmail transport (core/classes/mail.php):

2. addSendMail() pipes the message into the configured binary and reads the exit status that popen() would hide

   • the command is an argument array: the path is validated as an existing

executable file and every argument (-t, -i, -f) is supplied by the class,
so panel access cannot become shell execution

• -t takes the recipient from the To header, so no address is ever passed as

a command argument

• proc_open() is probed rather than assumed, since shared hosting routinely

lists it in disable_functions

• a short write is a failure of its own: a binary that died before reading

can still exit zero, which an unchecked fwrite() would report as accepted

• the write uses the same warning handler as PHP mail(), because a closed

pipe raises one that would otherwise leak into the response body

1. Transport dispatch (core/classes/mail.php):

2. setDelivery() became the match on mail.transport that batch 2 promised

   • the default arm is PHP mail(), so an unset or unknown value keeps behaving

exactly as the installation does today

1. Message composition (core/classes/mail.php):

2. getHeaders() gained the subject, emitted only when the transport does not supply it, which is the rule the block already applied to To

3. setError() bounds the recorded text at 255 characters, counted in characters so a multibyte transport response is not cut mid-character

4. Tests (tests/Unit/MailTransportTest.php, tests/Unit/MailHeaderTest.php):

5. Five cases over the two sendmail guards, the transport selection and the error bound, none of which start a process

6. Both guards were confirmed to fail their tests when removed

7. The eleven batch 1 getHeaders() calls carry the added argument, with no assertion changed

8. Plan (docs/MAIL-2026.md):

9. Record the batch in Progress with its decisions, the defects found and fixed inside it and the blockers left open

Benefits:

• An installation whose host has no usable mail() gains a second way out
• A failed delivery now carries the binary's own exit status and stderr
• Message assembly stays in one place for the SMTP transport in batch 4

Technical notes:

• Nothing writes mail.transport or mail.sendmail yet, so no installation behaviour changes

• The pipe itself is unexercised here: this box has no sendmail binary, and the stage verification list covers it on a host that can deliver

• No new package: composer.json is untouched and the class uses PHP core only

Stage 1 batch 1 of docs/MAIL-2026.md adds the Mail service that will own every outgoing message. Only the composition half lands here: pure functions over one message with no transport behind them, so the RFC work is reviewable on its own before PHP mail, Sendmail and SMTP arrive. Nothing calls it yet, addMail() is untouched, and delivery behaviour is unchanged.

Core changes:

1. Mail service (core/classes/mail.php):

2. Resolve sender identity per the plan's table: mail.frommail and mail.fromname win, the caller's address and the site name are the fallbacks

3. Assemble the MIME header block without a self-written Return-Path, which the receiving MTA owns

   • To is emitted only when the transport does not write its own, as PHP mail()

does and as Sendmail started with -t cannot

• Reply-To drops the display name that only repeated the address

• Encode subject and display name through mb_encode_mimeheader with B encoding and correct folding, replacing a hand-built encoded word that never folded

  • an encoded word is no longer wrapped in quotes, which RFC 2047 forbids
  • a plain ASCII display name becomes a proper quoted string instead

• Wrap the base64 body at 76 characters, so a 5 KB message stops going out as a single 6720-octet line

• Validate addresses with FILTER_VALIDATE_EMAIL and refuse control characters before whitespace is trimmed, so a trailing CRLF cannot be trimmed into a valid address

• Strip control characters from header text bytewise; a UTF-8 aware pattern returns null on a malformed byte and would drop the whole value

• Bootstrap (core/system.php):

• Require the class between the config and core/security.php, and create $mailer once the database connection exists

• Tests (tests/Unit/MailHeaderTest.php):

• 23 cases over identity resolution, encoded-word folding limits, base64 line length, CRLF endings, encoding round trips and every address injection path

• Plan (docs/MAIL-2026.md):

• Record the batch in Progress with its decisions, its deviations and the defect found and fixed inside it

• Re-measure the core/system.php line references that the new require shifted

Benefits:

• Header and encoding conformance is reviewable before any transport depends on it
• One place composes a message, so the three transports cannot each grow their own
• Header injection is closed at a single sanitiser rather than per transport

Technical notes:

• filterText() is no longer applied to subjects and addresses: it is an input filter that HTML-escapes a MIME subject, corrupts a local part containing &, and depends on request state the stage 2 drain will not have

• Subject bytes therefore change for & < > " ' and %xx sequences; the plan states that byte parity is not the criterion for this stage

• No new package: composer.json is untouched and the class uses PHP core only

• No behaviour change yet: addMail() still delivers every one of the 26 call sites, which migrate in batch 6