@jrpool/kilotest 47.0.1 → 48.0.0

package/api/requestRetest.test.ts

@@ -46,22 +46,30 @@ after(() => {
 
 test('requestRetest rejects a nonexistent report', async () => {
   const body = await response(['999999T9999', 'xyz', 'A reason that is long enough.']);
-  assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('does not exist'));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
 });
 
 test('requestRetest rejects a superseded report', async () => {
+  // 260101T0000-mix is an earlier report of "Mixed Outcomes Page" than 260202T0000-new,
+  // so it is superseded and processTestRequest returns 'superseded', reported via the
+  // disposition rather than details.error.
   const body = await response(['260101T0000', 'mix', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
-  assert.ok(details.error.includes('later report'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(
+    disposition['what happens next'].includes('a later report about a page with the same description is available.')
+  );
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
 });
 
 test('requestRetest rejects a reason shorter than 20 characters', async () => {
   const body = await response(['260101T0001', 'ct', 'short']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
 });
 
 test('requestRetest rejects a reason longer than 100 characters', async () => {
@@ -69,7 +77,58 @@ test('requestRetest rejects a reason longer than 100 characters', async () => {
   const body = await response(['260101T0001', 'ct', longReason]);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+});
+
+test('requestRetest rejects a report matching a claimed job by description', async () => {
+  // 260101T0001-ct is the "All CantTell Page" report.
+  const claimedPath = path.join(fixtureDBDir, 'jobs', 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, JSON.stringify({
+    target: {what: 'All CantTell Page', url: 'https://example.com/unrelated'}
+  }));
+  try {
+    const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same description is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('requestRetest rejects a report matching a queued job by URL', async () => {
+  // 260101T0001-ct's URL is https://example.com/canttell.
+  const queuedPath = path.join(fixtureDBDir, 'jobs', 'queue', 'que.json');
+  await fs.writeFile(queuedPath, JSON.stringify({
+    target: {what: 'Some Other Page', url: 'https://example.com/canttell'}
+  }));
+  try {
+    const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same URL is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('requestRetest rejects a duplicate request', async () => {
+  await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+  const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('an identical request is already awaiting approval.'));
 });
 
 test('requestRetest accepts a valid retest request for the latest report of a page', async () => {
@@ -78,7 +137,7 @@ test('requestRetest accepts a valid retest request for the latest report of a pa
   assert.equal(details.error, undefined);
   assert.equal(details['page to be retested'].description, 'Mixed Outcomes Page');
   assert.ok(logged.some(line =>
-    line.startsWith('WARNING (Kilotest: new retest request in the API)')
+    line.startsWith('WARNING (Kilotest: new retest request awaits approval)')
     && line.includes('Mixed Outcomes Page')
     && line.includes('https://example.com/mixed')
   ));

package/api/requestRetest.ts

@@ -6,8 +6,8 @@
 // IMPORTS
 
 import {z} from 'zod';
-import {getResponseMetadata, getThisHost, getToolsFacts, processTestRequest} from './util.ts';
-import {getReportExtracts, getReportExtract} from '../util.ts';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {processTestRequest} from '../util.ts';
 import {requestRetestResponseSchema} from './schemas.ts';
 
 // TYPES
@@ -22,51 +22,67 @@ export const response = async (args: string[]) => {
   const [timeStamp = '', jobID = '', reason = ''] = args;
   const thisHost = getThisHost();
   const reasonLength = reason.length;
-  // Get data on the report.
-  const reportExtract = await getReportExtract(timeStamp, jobID);
   // Initialize the response-content properties.
   let requestDetails: ResponseContent['details about your request'];
   let requestDisposition: ResponseContent['disposition of your request'] = null;
-  // If this failed:
-  if ('error' in reportExtract) {
-    requestDetails = {
-      error: 'request invalid: the specified existing report is not an available report'
-    };
-  }
-  // Otherwise, if the report has been superseded:
-  else if (
-    (await getReportExtracts(true))
-    .every(extract => extract.timeStamp !== timeStamp || extract.jobID !== jobID)
-  ) {
-    requestDetails = {
-      error: 'request invalid: a later report about the page exists'
-    };
-  }
-  // Otherwise, if the encoded reason is too short or too long:
-  else if (reasonLength < 20 || reasonLength > 100) {
+  // If the encoded reason is too short or too long:
+  if (reasonLength < 20 || reasonLength > 100) {
     requestDetails = {
       error: 'request invalid: your reason is not between 20 and 100 characters long'
     }
   }
-  // Otherwise, i.e. if getting the report succeeded and the request is valid:
+  // Otherwise, i.e. if the request is facially valid:
   else {
-    // Process the request.
-    await processTestRequest('retest', reportExtract.description, reportExtract.url, reason);
-    // Add details about the request.
-    requestDetails = {
-      'date and time received': new Date().toISOString(),
-      'page to be retested': {
-        'description': reportExtract.description,
-        'URL': reportExtract.url
-      },
-      'reason why the page should be retested': reason
-    };
-    // Add information about the disposition of the request.
-    requestDisposition = {
-      'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
-      'how you can check for completion': 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
-      'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been retested and a new report is available.`
-    };
+    // Process the request. This resolves the cited report's description and URL itself.
+    const processResult = await processTestRequest(reason, {timeStamp, jobID});
+    // If the cited report does not exist:
+    if (processResult.result === 'nonreport') {
+      requestDetails = {
+        error: 'request invalid: the specified report does not exist'
+      };
+    }
+    // Otherwise, i.e. if the cited report was found:
+    else {
+      const {result: requestResult, description, url} = processResult;
+      // Add details about the request.
+      requestDetails = {
+        'date and time received': new Date().toISOString(),
+        'page to be retested': {
+          'description': description,
+          'URL': url
+        },
+        'reason why the page should be retested': reason
+      };
+      // Add information about the disposition of the request.
+      if (requestResult === 'ok') {
+        requestDisposition = {
+          'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
+          'how you can check for completion': 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
+          'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been retested and a new report is available.`
+        };
+      }
+      else {
+        const failureFact = 'Your request will not be processed, because ';
+        let failureReason: string;
+        if (requestResult === 'description') {
+          failureReason = 'a request to test a page with the same description is already approved.'
+        }
+        else if (requestResult === 'url') {
+          failureReason = 'a request to test a page with the same URL is already approved.'
+        }
+        else if (requestResult === 'superseded') {
+          failureReason = 'a later report about a page with the same description is available.'
+        }
+        else {
+          failureReason = 'an identical request is already awaiting approval.'
+        }
+        requestDisposition = {
+          'what happens next': `${failureFact}${failureReason}`,
+          'how you can check for completion': 'Not applicable.',
+          'how a web user can check for completion': 'Not applicable.'
+        }
+      }
+    }
   }
   // Create the response content.
   const responseContent: ResponseContent = {

package/api/requestTest.test.ts

@@ -47,34 +47,90 @@ after(() => {
 test('requestTest rejects an empty description', async () => {
   const body = await response(['', 'https://example.com/test', 'A reason that is long enough.']);
   assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects a description longer than 100 characters', async () => {
   const longWhat = 'x'.repeat(101);
   const body = await response([longWhat, 'https://example.com/test', 'A reason that is long enough.']);
   assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects a URL shorter than 12 characters', async () => {
   const body = await response(['Test Page', 'short', 'A reason that is long enough.']);
   assert.ok((body['response content']['details about your request'] as any).error);
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects a syntactically invalid URL with the correct length', async () => {
   const body = await response(['Test Page', 'not-a-valid-url', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('invalid URL'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
 });
 
 test('requestTest rejects an already-tested page', async () => {
   const body = await response(['Mixed Outcomes Page', 'https://example.com/mixed', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
-  assert.ok(details.error.includes('already been tested'));
-  assert.ok(!logged.some(line => line.includes('request in the API')));
+  // A report for this description and URL already exists, so processTestRequest
+  // returns 'retest' and the failure is reported via the disposition, not details.error.
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(
+    disposition['what happens next']
+    .includes('a report about a page with the same description and URL is available.')
+  );
+  assert.ok(!logged.some(line => line.includes('new test request awaits approval')));
+});
+
+test('requestTest rejects a page matching a claimed job by description', async () => {
+  const claimedPath = path.join(fixtureDBDir, 'jobs', 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, JSON.stringify({
+    target: {what: 'Claimed Test Page', url: 'https://example.com/claimed-job'}
+  }));
+  try {
+    const body = await response(['Claimed Test Page', 'https://example.com/other-url', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same description is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('requestTest rejects a page matching a queued job by URL', async () => {
+  const queuedPath = path.join(fixtureDBDir, 'jobs', 'queue', 'que.json');
+  await fs.writeFile(queuedPath, JSON.stringify({
+    target: {what: 'Some Other Page', url: 'https://example.com/queued-url'}
+  }));
+  try {
+    const body = await response(['A Different Page', 'https://example.com/queued-url', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same URL is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('requestTest rejects a duplicate request', async () => {
+  await response(['Duplicate API Page', 'https://example.com/dup-api', 'A reason that is long enough.']);
+  const body = await response(['Duplicate API Page', 'https://example.com/dup-api', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('an identical request is already awaiting approval.'));
 });
 
 test('requestTest accepts a valid new page request', async () => {
@@ -83,7 +139,7 @@ test('requestTest accepts a valid new page request', async () => {
   assert.equal(details.error, undefined);
   assert.equal(details['page to be tested'].description, 'Brand New Page');
   assert.ok(logged.some(line =>
-    line.startsWith('WARNING (Kilotest: new test request in the API)')
+    line.startsWith('WARNING (Kilotest: new test request awaits approval)')
     && line.includes('Brand New Page')
     && line.includes('https://example.com/brandnew')
   ));

package/api/requestTest.ts

@@ -6,8 +6,8 @@
 // IMPORTS
 
 import {z} from 'zod';
-import {getResponseMetadata, getThisHost, getToolsFacts, processTestRequest} from './util.ts';
-import {getReportExtracts, isURL} from '../util.ts';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {isURL, processTestRequest} from '../util.ts';
 import {requestTestResponseSchema} from './schemas.ts';
 
 // TYPES
@@ -45,36 +45,46 @@ export const response = async (args: string[]) => {
   }
   // Otherwise, i.e. if the description and URL are valid:
   else {
-    // Get an extract of the available reports.
-    const reportExtracts = await getReportExtracts();
-    // If any report is on a page with the specified description and URL:
-    if (
-      reportExtracts.some(extract => extract.description === description && extract.url === url)
-    ) {
-      requestDetails = {
-        error: 'request invalid: the page has already been tested and its report is available'
-      };
-    }
-    // Otherwise, i.e. if none is on the page:
-    else {
-      // Process the request.
-      await processTestRequest('test', description, url, reason);
-      // Add details about the request.
-      requestDetails = {
-        'date and time received': new Date().toISOString(),
-        'page to be tested': {
-          description,
-          URL: url
-        },
-        'reason why the page should be tested': reason
-      };
-      // Add information about the disposition of the request.
+    // Process the request.
+    const {result: requestResult} = await processTestRequest(reason, {description, url});
+    // Add details about the request.
+    requestDetails = {
+      'date and time received': new Date().toISOString(),
+      'page to be tested': {
+        description,
+        URL: url
+      },
+      'reason why the page should be tested': reason
+    };
+    // Add information about the disposition of the request.
+    if (requestResult === 'ok') {
       requestDisposition = {
         'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
         'how you can check for completion': 'You can call the listReports tool to learn whether the page has been tested and a report is available.',
         'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been tested and a report is available.`
       };
     }
+    else {
+      const failureFact = 'Your request will not be processed, because ';
+      let failureReason: string;
+      if (requestResult === 'description') {
+        failureReason = 'a request to test a page with the same description is already approved.'
+      }
+      else if (requestResult === 'url') {
+        failureReason = 'a request to test a page with the same URL is already approved.'
+      }
+      else if (requestResult === 'retest') {
+        failureReason = 'a report about a page with the same description and URL is available.'
+      }
+      else {
+        failureReason = 'an identical request is already awaiting approval.'
+      }
+      requestDisposition = {
+        'what happens next': `${failureFact}${failureReason}`,
+        'how you can check for completion': 'Not applicable.',
+        'how a web user can check for completion': 'Not applicable.'
+      }
+    }
   }
   // Create the response content.
   const responseContent: ResponseContent = {

package/api/util.test.ts

@@ -7,7 +7,8 @@
 
 import {test} from 'node:test';
 import assert from 'node:assert/strict';
-import {getReportBasics, getResponseMetadata, getRuleEngineFacts, getRuleEnginesFacts, getIssueSpec, getToolsFacts, processTestRequest} from './util.ts';
+import {getReportBasics, getResponseMetadata, getRuleEngineFacts, getRuleEnginesFacts, getIssueSpec, getToolsFacts} from './util.ts';
+import {processTestRequest} from '../util.ts';
 
 // SETUP
 
@@ -98,10 +99,10 @@ test('getReportBasics returns an error for a report whose extract cannot be read
 test('processTestRequest returns an error for a duplicate request', async () => {
   process.env.DB_DIR = (await import('../test/dbFixture.ts')).fixtureDBDir;
   // Submit the same request twice; the second should be a duplicate.
-  await processTestRequest('test', 'Dup Page', 'https://example.com/dup', 'A reason that is long enough.');
-  const result: any = await processTestRequest('test', 'Dup Page', 'https://example.com/dup', 'A reason that is long enough.');
-  assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Duplicate request');
+  const target = {description: 'Dup Page', url: 'https://example.com/dup'};
+  await processTestRequest('A reason that is long enough.', target);
+  const {result} = await processTestRequest('A reason that is long enough.', target);
+  assert.equal(result, 'duplicate');
   if (savedDBDir !== undefined) {
     process.env.DB_DIR = savedDBDir;
   }

package/api/util.ts

@@ -5,18 +5,15 @@
 
 // IMPORTS
 
-import {sendAlert} from '../alerts.ts';
 import {
   getAgoDays,
   getReportExtracts,
   getNowStamp,
-  getPlainText,
   getRandomString,
   getReportExtract,
   getReportStats,
   objectSort,
-  ruleEngines,
-  addTestRequest
+  ruleEngines
 } from '../util.ts';
 import type {ReportExtract} from '../util.ts';
 import {issues as issueSpecs} from 'testaro-issues';
@@ -83,6 +80,7 @@ export const getRuleEnginesFacts = (ruleEngineIDSet: Iterable<string>) => {
 // getReportExtracts, it carries a superseded flag; otherwise the flag is computed.
 // With an extract provided, failure is impossible, so the return type narrows
 // to ReportBasics; without one, an error object may be returned.
+// XXX Why are these overloads necessary? Can't we just have one function?
 export function getReportBasics(
   timeStamp: string, jobID: string, extract: ReportExtract
 ): Promise<ReportBasics>;
@@ -151,23 +149,3 @@ export const getIssueSpec = (issueID: string) => {
   // Otherwise, i.e. if it does not exist, return this.
   return null;
 };
-// Processes a test or retest request from the API.
-export const processTestRequest = async (testType: string, description: string, url: string, why: string): Promise<{status: string; message: string} | undefined> => {
-  // Get an email-safe version of the reason.
-  const plainWhy = getPlainText(why);
-  // Add the test request as a transaction.
-  const updateResult = await addTestRequest(description, url, plainWhy);
-  // If the request was a duplicate:
-  if (updateResult.error === 'duplicate') {
-    // Return this.
-    return {
-      status: 'error',
-      message: 'Duplicate request'
-    };
-  }
-  // Otherwise, i.e. if it was not a duplicate, alert a manager about it.
-  await sendAlert(
-    `Kilotest: new ${testType} request in the API`,
-    `Target: ${description}\nURL: ${url}\nReason: ${plainWhy}`
-  );
-};

package/docs/BACKLOG.md

@@ -4,14 +4,6 @@ Engineering tasks and risks that are not yet scheduled.
 
 Items marked completed are preserved for about 2 weeks in case of production bugs.
 
-## Document alerting
-
-Document when and how Kilotest sends alerts to its maintainer, including the subscription to Resend and the DNS configuration for Resend authentication.
-
-## Decide whether to tighten the DMARC policy and add SPF alignment for Resend
-
-Live DNS for `kilotest.com`, checked 2026-09-16, shows a DMARC record of `v=DMARC1; p=none;` (monitoring only, no `rua=` reporting address) and an SPF record (`v=spf1 include:_spf.porkbun.com ~all`) that does not include `resend.com`. Mail sent via Resend is currently authenticated only by the DKIM record at `resend._domainkey.kilotest.com`. This may be an intentional, working minimal configuration, or an oversight from Resend's onboarding; it has not been confirmed against the Resend dashboard's domain-verification status. Consider confirming, in the Resend dashboard, whether SPF alignment is recommended or required for this domain's deliverability, and once alert deliverability has been stable for a period, whether to tighten DMARC from `p=none` to `p=quarantine` and add an `rua=` address so DMARC aggregate reports reach the maintainer.
-
 ## Widen test-request duplicate detection
 
 The duplicate check in `addTestRequest` (`util.ts`), reached by all four test/retest request paths (UI `/requestTest.html` and `/requestRetest.html`; API `requestTest` and `requestRetest` operations), compares an incoming request only against other requests currently pending in `db/jobs/testRequests.json`, i.e., submitted but not yet manually approved by the maintainer into a job. Once a pending request is approved into a job (`web/enqueue/index.ts`), all pending requests for that URL are cleared from `testRequests.json`, so this shared check cannot recognize a duplicate against a request that has already been approved, is currently running, or has already completed. An identical request submitted after approval triggers a fresh alert rather than being filtered.
@@ -205,6 +197,18 @@ Create this file in your project root as `scripts/generate-manifest.js`. It pull
 
 Record per-endpoint request counts, latencies, and error rates so that Kilotest managers can observe which API operations are most used and identify performance regressions.
 
+## Tighten the DMARC policy after adding aggregate reporting (revised and completed)
+
+Resend mail is already fully authenticated and passes DMARC; what remains undecided is reporting and enforcement, not SPF alignment. Confirmed on 2026-09-17 by querying DNS live and by inspecting the full headers of a received alert: SPF passes against a Resend-configured MAIL FROM on `send.kilotest.com` (MX `feedback-smtp.us-east-1.amazonses.com` and TXT `v=spf1 include:amazonses.com ~all`, the pair created by Resend’s “Enable SPF” option), which aligns with the `kilotest.com` From domain under relaxed alignment, and DKIM passes with an aligned `d=kilotest.com` signature (`s=resend`, key published at `resend._domainkey.kilotest.com`). The captured message showed `dmarc=pass` at both the Porkbun forwarding hop and the final Zoho mailbox; Porkbun’s SRS rewrite makes post-forward SPF unaligned, so DKIM is what carries DMARC across the forward. `ALERT_FROM` is `info@kilotest.com`, matching the DMARC domain, and `MANAGER_EMAIL` is the same Porkbun-forwarded address, which terminates at `pool@jpdev.pro` on Zoho.
+
+The maintainer sends no mail as `@kilotest.com` (human mail is sent from `pool@jpdev.pro`), so Resend alerts are currently the domain’s only legitimate sending stream, and tightening DMARC risks no known sender. If transactional mail is added later it will also use `info@kilotest.com`; any provider other than Resend would need its own SPF and DKIM alignment configured before deployment under an enforced policy. The root-domain SPF record has no Resend mechanism and needs none: SPF is evaluated against the MAIL FROM domain, which for Resend is `send.kilotest.com`, not the root domain.
+
+Consider: (1) adding `rua=mailto:info@kilotest.com` to the `_dmarc.kilotest.com` record while still at `p=none` (aggregate reports are zipped XML and reach Zoho through the existing forward); (2) after a few weeks of reports confirm that no unexpected stream is failing, moving to `p=quarantine`, optionally with a `pct=` ramp, and later to `p=reject`; (3) reflecting any DNS change in `docs/SERVICE.md` and its DNS CSV.
+
+## Document alerting (completed)
+
+Document when and how Kilotest sends alerts to its maintainer, including the subscription to Resend and the DNS configuration for Resend authentication.
+
 ## Serve explanation page for human MCP requests (completed)
 
 When the `/mcp` path is requested without a `text/event-stream` accept header, serve an HTML page explaining that the endpoint is for AI agents and providing a link to the AI tutorial.

package/docs/SERVICE.md

@@ -145,6 +145,26 @@ The DNS records for `kilotest.com` are configured as follows. In each case, `TTL
    - **Host**: _acme-challenge.kilotest.com
    - **Answers**: validation tokens provided by Porkbun ACME client
 
+6. **TXT** (SPF for Porkbun-handled mail)
+   - **Host**: kilotest.com
+   - **Answer**: `v=spf1 include:_spf.porkbun.com ~all`
+
+7. **MX and TXT** (Resend MAIL FROM domain; provides SPF alignment for Resend mail)
+   - **Host**: send.kilotest.com
+   - **Answers**: MX `feedback-smtp.us-east-1.amazonses.com` (priority 10); TXT `v=spf1 include:amazonses.com ~all`
+
+8. **TXT** (Resend DKIM public key)
+   - **Host**: resend._domainkey.kilotest.com
+   - **Answer**: an RSA public key in `p=...` form, issued by Resend
+
+9. **TXT** (DMARC policy)
+   - **Host**: _dmarc.kilotest.com
+   - **Answer**: `v=DMARC1; p=none;`
+
+10. **TXT** (site verification)
+    - **Host**: kilotest.com
+    - **Answers**: `google-site-verification=...` and `smithery-verification=...` tokens issued by Google and Smithery
+
 The DNS configuration as CSV:
 
 ```csv
@@ -153,7 +173,13 @@ kilotest.com,kilotest.com,A,149.28.208.106,3600,0
 kilotest.com,www.kilotest.com,CNAME,kilotest.com,3600,0
 kilotest.com,kilotest.com,MX,fwd1.porkbun.com,3600,10
 kilotest.com,kilotest.com,MX,fwd2.porkbun.com,3600,20
+kilotest.com,send.kilotest.com,MX,feedback-smtp.us-east-1.amazonses.com,3600,10
 kilotest.com,kilotest.com,TXT,"v=spf1 include:_spf.porkbun.com ~all",3600,0
+kilotest.com,send.kilotest.com,TXT,"v=spf1 include:amazonses.com ~all",3600,0
+kilotest.com,resend._domainkey.kilotest.com,TXT,"p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDWjPkYLQ+xYcmMRODdXoXl7QTXK5TkhNQXjl5HcPvk1D5A5eqtjuw17lgZOQy1wiUq8BGId+Iq3BWO32kYTJo+lWMQJ8/Me4M0xQ0qaYPmtTJ9cQ8oyrFUuheu7T0MqTYEwYRbHwE74WkQSQTHnCx0Uy98pcXqOaucA3n1v3YkjQIDAQAB",3600,0
+kilotest.com,_dmarc.kilotest.com,TXT,"v=DMARC1; p=none;",3600,0
+kilotest.com,kilotest.com,TXT,google-site-verification=EnNe2chUyUaV645ENd3c6pHs1PZ_Zb3u5516HSirvrA,3600,0
+kilotest.com,kilotest.com,TXT,smithery-verification=6a3a2327c26bc478be748041f340e14fa50c4386eea3b2692eeffda703b8b3f9,3600,0
 kilotest.com,_acme-challenge.kilotest.com,TXT,GIzAHOFW416fHp7cuTkg4gvJDsyuPZvsPlSsnyViFLQ,3600,0
 kilotest.com,_acme-challenge.kilotest.com,TXT,qQdIIiUSC76PvYuku-AxPsRPY-fJV7T7i3b8fimlFjU,3600,0
 ```
@@ -356,7 +382,7 @@ Kilotest uses [Resend](https://resend.com/) as its transactional email delivery
 
 ### DNS configuration for Resend
 
-Resend authenticates outgoing mail using DKIM, and mail receivers additionally consult SPF and DMARC records for the sending domain. The `kilotest.com` DNS zone (managed at [porkbun.com](https://porkbun.com/); see the DNS Configuration section above for the full record set) currently contains the following records relevant to Resend, confirmed live on 2026-09-16 by querying DNS directly:
+Resend authenticates outgoing mail using DKIM, and mail receivers additionally consult SPF and DMARC records for the sending domain. The `kilotest.com` DNS zone (managed at [porkbun.com](https://porkbun.com/); see the DNS Configuration section above for the full record set) currently contains the following records relevant to Resend, confirmed live on 2026-09-17 by querying DNS directly and by inspecting the full headers of a delivered alert message:
 
 1. **DKIM (DomainKeys Identified Mail)**
    - **Record type**: TXT (not a CNAME)
@@ -364,10 +390,10 @@ Resend authenticates outgoing mail using DKIM, and mail receivers additionally c
    - **Value**: an RSA public key in `p=...` form, issued by Resend for this domain.
 
 2. **SPF (Sender Policy Framework)**
-   - **Record type**: TXT
-   - **Host**: `kilotest.com` (the root domain)
-   - **Value**: `v=spf1 include:_spf.porkbun.com ~all`
-   - This record does **not** include `include:resend.com` or any other Resend-related mechanism. Whether Resend's deliverability for this domain depends on that inclusion, or relies on DKIM alignment alone under the current relaxed DMARC policy (see below), has not been confirmed; this is worth confirming against the Resend dashboard's domain-verification status rather than assuming either way.
+   - **Record types**: MX and TXT
+   - **Host**: `send.kilotest.com` (a dedicated MAIL FROM subdomain, not the root domain)
+   - **Values**: MX `feedback-smtp.us-east-1.amazonses.com` (priority 10) and TXT `v=spf1 include:amazonses.com ~all`
+   - This pair is what Resend’s “Enable SPF” option creates. It makes Resend send with a MAIL FROM on `send.kilotest.com`, which aligns with the `kilotest.com` From domain under relaxed DMARC alignment. Because Resend sends through Amazon SES, the include target is `amazonses.com`, not `resend.com`. The separate root-domain TXT record `v=spf1 include:_spf.porkbun.com ~all` authorizes Porkbun’s servers for mail sent as `@kilotest.com` through Porkbun; SPF is evaluated against the MAIL FROM domain, so the root record plays no role in Resend authentication and needs no Resend mechanism.
 
 3. **DMARC (Domain-based Message Authentication, Reporting and Conformance)**
    - **Record type**: TXT
@@ -375,7 +401,7 @@ Resend authenticates outgoing mail using DKIM, and mail receivers additionally c
    - **Value**: `v=DMARC1; p=none;`
    - The `p=none` policy is monitoring-only: it asks receivers to take no special action on mail that fails alignment, rather than quarantining or rejecting it. No `rua=` reporting address is configured, so no aggregate DMARC reports are being sent anywhere.
 
-These records, along with the MX records already documented above, are the complete set of email-related DNS configuration for `kilotest.com` as of the date given above. Any future change to Resend's configuration (for example, rotating the DKIM key, or tightening the DMARC policy from `p=none` to `p=quarantine` once deliverability is confirmed stable) should be reflected here and in the DNS Configuration section's CSV.
+A delivered alert message inspected on 2026-09-17 confirms this configuration end to end: `spf=pass` with `smtp.mailfrom` on `send.kilotest.com`, `dkim=pass` with `d=kilotest.com` (`s=resend`), and `dmarc=pass` at both the Porkbun forwarding hop and the final mailbox. Any future change to Resend’s configuration (for example, rotating the DKIM key, adding a `rua=` reporting address to the DMARC record, or tightening the DMARC policy from `p=none` to `p=quarantine`) should be reflected here and in the DNS Configuration section’s CSV.
 
 ### Setting environment variables in production