rcf-lite 0.26.0 → 0.28.0

package/blueprints/application-notifications-in-app/contributions/probes/probe-utils.mjs

@@ -0,0 +1,177 @@
+// Shared helpers for application-notifications-in-app contributions/probes/.
+//
+// The real engine for every probe in this pack is the fixture HTTP
+// server at packages/rcf-lite/test/fixtures/probe-pack-application-notifications-in-app/server.js
+// booted on a scratch port from the family range 47640-47649.
+// The fixture echoes a per-request x-fixture-request-id header on
+// every response; probes record that id and a response body excerpt
+// as positive evidence per rule 7d.
+//
+// No account credentials or network calls: every probe is
+// local-fixture-driven, so no probe carries an account-bound branch
+// or a CI_HAS_* gate. Declared env vars are the fixture's own
+// PORT and (where the fixture reads them) the CAPS/state switches
+// the probes drive via query string.
+
+import { spawn } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const SLUG = 'application-notifications-in-app';
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/probe-pack-application-notifications-in-app');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/application-notifications-in-app');
+export const PORT_RANGE_START = 47640;
+export const PORT_RANGE_END = 47649;
+export const DECLARED_ENV = Object.freeze(['PORT', 'PROBE_BREAK']);
+export const REQUEST_ID_HEADER = 'x-fixture-request-id';
+
+// Pick a free port from the fixture family range. Falls back to
+// asking the OS for an ephemeral port only if the whole range is
+// held by other workers (never expected on a single-machine run).
+export async function pickPort() {
+  for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port += 1) {
+    if (await canBind(port)) return port;
+  }
+  return await bindEphemeral();
+}
+
+function canBind(port) {
+  return new Promise((res) => {
+    const s = createServer();
+    s.once('error', () => res(false));
+    s.listen(port, '127.0.0.1', () => {
+      const bound = s.address();
+      s.close(() => res(!!bound));
+    });
+  });
+}
+
+function bindEphemeral() {
+  return new Promise((res) => {
+    const s = createServer();
+    s.listen(0, '127.0.0.1', () => {
+      const port = s.address().port;
+      s.close(() => res(port));
+    });
+  });
+}
+
+// Spawns the fixture server as a child on `port` with the given
+// env overlay; resolves once the fixture has printed LISTENING and
+// returns { child, url, kill } (kill is synchronous best-effort).
+export async function startFixture({ port, env = {} } = {}) {
+  const boundPort = port ?? await pickPort();
+  const child = spawn(process.execPath, ['server.js'], {
+    cwd: FIXTURE_DIR,
+    env: { ...process.env, PORT: String(boundPort), ...env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  await new Promise((res, rej) => {
+    const timer = setTimeout(() => rej(new Error(`fixture did not print LISTENING within 4s on port ${boundPort}`)), 4000);
+    let stderrBuf = '';
+    child.stderr.on('data', (chunk) => { stderrBuf += String(chunk); });
+    child.on('exit', (code) => rej(new Error(`fixture exited early (code=${code}) stderr=${stderrBuf.slice(0, 400)}`)));
+    child.stdout.on('data', (chunk) => {
+      if (String(chunk).includes(`LISTENING ${boundPort}`)) { clearTimeout(timer); res(); }
+    });
+  });
+  const url = new URL(`http://127.0.0.1:${boundPort}`);
+  return {
+    child,
+    url,
+    port: boundPort,
+    // Await child exit and propagate any error. A teardown failure
+    // must fail the verdict (the teardown-propagation rule);
+    // no swallowed errors here.
+    kill: () => new Promise((res, rej) => {
+      let settled = false;
+      const done = (err) => { if (settled) return; settled = true; err ? rej(err) : res(); };
+      child.once('exit', () => done());
+      child.once('error', (err) => done(err));
+      try { child.kill('SIGTERM'); } catch (err) { return done(err); }
+      setTimeout(() => {
+        if (settled) return;
+        try { child.kill('SIGKILL'); } catch (err) { return done(err); }
+      }, 4000);
+    }),
+  };
+}
+
+// Issue an HTTP request against the fixture and return
+// { status, headers, body, requestId }.
+export async function fixtureFetch(url, pathAndQuery, init = {}) {
+  const target = new URL(pathAndQuery, url);
+  const res = await fetch(target, init);
+  const body = await res.text();
+  const requestId = res.headers.get(REQUEST_ID_HEADER);
+  return { status: res.status, headers: Object.fromEntries(res.headers.entries()), body, requestId };
+}
+
+export function excerpt(body, maxLen = 240) {
+  if (typeof body !== 'string') return '';
+  return body.length <= maxLen ? body : body.slice(0, maxLen) + '…';
+}
+
+export function aggregate(results) {
+  // Positive-evidence rule: no-checks-ran is a fail.
+  if (!Array.isArray(results) || results.length === 0) return 'fail';
+  if (results.some((r) => r.verdict === 'fail')) return 'fail';
+  // Any warn row lifts the aggregate to warn, including honest
+  // notObservableHere de-claims. A probe whose rows are all warn
+  // aggregates to warn, not pass; the shelf reads amber and the tally
+  // accepts a warn aggregate as problems=0 when no fail row is present.
+  if (results.some((r) => r && r.verdict === 'warn')) return 'warn';
+  return 'pass';
+}
+
+export async function writeReport({ probeName, engine, results, extra }) {
+  await mkdir(REPORT_DIR, { recursive: true });
+  const report = {
+    slug: SLUG,
+    probeName,
+    runAt: new Date().toISOString(),
+    engine,
+    results,
+    aggregateVerdict: aggregate(results),
+    ...(extra ?? {}),
+  };
+  const filepath = resolve(REPORT_DIR, `${probeName}.json`);
+  await writeFile(filepath, JSON.stringify(report, null, 2) + '\n', 'utf8');
+  return { report, path: filepath };
+}
+
+export async function runShim(probeName, engine, mainFn) {
+  try {
+    const outcome = (await mainFn()) ?? { results: [] };
+    const { results, extra } = outcome;
+    const { report, path: filepath } = await writeReport({ probeName, engine, results, extra });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stdout.write(`report written to ${filepath}\n`);
+    if (report.aggregateVerdict === 'fail') process.exitCode = 1;
+  } catch (err) {
+    // Positive-evidence rule (exception fallback): exception rows have no
+    // observed AC; anchor null (never a fabricated id like
+    // "unknown"), carry an evidence object with the error excerpt.
+    const message = err && err.message ? err.message : String(err);
+    const stack = err && err.stack ? err.stack : String(err);
+    const results = [{
+      anchorAcId: null,
+      verdict: 'fail',
+      detail: `probe threw: ${message}`,
+      evidence: {
+        errorMessage: message,
+        errorExcerpt: excerpt(stack, 480),
+      },
+    }];
+    const { report, path: filepath } = await writeReport({ probeName, engine, results });
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.stderr.write(`probe error: ${stack}\n`);
+    process.stderr.write(`report written to ${filepath}\n`);
+    process.exitCode = 1;
+  }
+}

package/blueprints/application-notifications-in-app/contributions/probes/run-centre-acknowledge-round-trip.mjs

@@ -0,0 +1,5 @@
+import runProbe from './centre-acknowledge-round-trip.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-notifications-in-app/server.js', healthy: true };
+runShim('centre-acknowledge-round-trip', engine, runProbe);

package/blueprints/application-notifications-in-app/contributions/probes/run-live-region-preseeding.mjs

@@ -0,0 +1,5 @@
+import runProbe from './live-region-preseeding.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-notifications-in-app/server.js', healthy: true };
+runShim('live-region-preseeding', engine, runProbe);

package/blueprints/application-notifications-in-app/contributions/probes/run-toast-contract.mjs

@@ -0,0 +1,5 @@
+import runProbe from './toast-contract.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-notifications-in-app/server.js', healthy: true };
+runShim('toast-contract', engine, runProbe);

package/blueprints/application-notifications-in-app/contributions/probes/toast-contract.mjs

@@ -0,0 +1,92 @@
+// application-notifications-in-app probe: toast role/priority mapping
+// and the WCAG 2.2.1 timeout floor (AC-20102-1) plus the focus-pause
+// clause (AC-20102-4).
+//
+// AC-20102-1 concerns the client-JS-rendered toast DOM (priority to
+// role/wrapper mapping, one wrapper per body, data-shown-at and
+// data-dismissed-at ISO timestamps, elapsed timeout at or above the
+// six-second floor). All of that is browser-only in this fixture:
+// the toast DOM is created by the client script and the elapsed
+// timing runs off a browser timer. The AC-20102-1 clause is emitted
+// as a notObservableHere row anchored to AC-20102-1 (no focus-pause
+// language - focus-pause is a separate AC, AC-20102-4).
+//
+// AC-20102-4 is the focus-pause clause: a focused toast pauses the
+// timer and dismissal removes the toast. The fixture's current toast
+// factory renders the toast in client JS, sets data-dismissed-at on
+// dismiss but does not remove the toast from the DOM and does not
+// pause the timer on focus. That is a fixture-level gap against the
+// AC. Rather than attributing a positive observation, this probe
+// emits a conformanceOnly row (null anchor, per the null-anchor +
+// limitation contract) naming AC-20102-4 in the limitation so the
+// AC-property gap is honestly recorded.
+//
+// The pack aggregate stays warn (AMBER) via the shared aggregate()
+// rule (both rows carry verdict:'warn'). The fixture is still spun
+// up so the probe exercises the fixture lifecycle
+// (teardown-fails-verdict rule).
+
+import { fixtureFetch, startFixture, excerpt } from './probe-utils.mjs';
+
+export const anchorAcId = 'application-notifications-in-app-AC-20102-1';
+export const accountBound = false;
+
+export default async function runProbe() {
+  const fixture = await startFixture();
+  const results = [];
+  try {
+    // Reachability fetch: the fixture reports the shell root on /
+    // with data-toast-timeout-floor-seconds and the two live-region
+    // wrappers preseeded. Recorded so both conformance rows below
+    // carry a live x-fixture-request-id and a body excerpt from this
+    // run (rule-7d shape + tally: conformance rows require an
+    // evidence object; the shell body proves the fixture answered
+    // and lets a reader see the observable surface even though the
+    // client-JS toast rendering itself is not observable here).
+    const shell = await fixtureFetch(fixture.url, '/');
+    const shellRootMatch = (shell.body.match(/<div[^>]*data-region="shell-root"[^]{0,240}/) || [''])[0];
+    const timeoutFloorMatch = shell.body.match(/data-toast-timeout-floor-seconds="(\d+)"/);
+    const timeoutFloorSeconds = timeoutFloorMatch ? Number(timeoutFloorMatch[1]) : null;
+
+    results.push({
+      anchorAcId,
+      notObservableAcId: anchorAcId,
+      verdict: 'warn',
+      notObservableHere: true,
+      reason: 'AC-20102-1 requires observing client-driven toast emission into [data-live-region="polite"] with role="status" for info and [data-live-region="assertive"] with role="alert" for error, one wrapper per body, data-shown-at and data-dismissed-at ISO timestamps on the toast element, and the elapsed time between them at or above the ADR-2102 six-second floor. Toast DOM is emitted by client JS after load and elapsed timing runs off a browser timer, so a fixture-HTTP-only probe cannot observe them; a Playwright-driven check is required.',
+      detail: `Given a toast triggered by a background event, priority-to-role/wrapper mapping, one-shot announcement per wrapper, and the WCAG 2.2.1 six-second elapsed-timeout floor on data-shown-at/data-dismissed-at are all browser-only in this fixture; the shell root observed at GET / carries data-toast-timeout-floor-seconds=${timeoutFloorSeconds} (server-rendered constant, not the client-JS-driven toast) so the fixture reachability is recorded; needs a Playwright-driven observation for the toast contract itself; x-fixture-request-id=${shell.requestId}.`,
+      evidence: {
+        requestId: shell.requestId,
+        responseStatus: shell.status,
+        bodyExcerpt: excerpt(shellRootMatch),
+        derived: {
+          route: '/',
+          timeoutFloorSecondsServerRendered: timeoutFloorSeconds,
+          shellRootPresent: shellRootMatch.length > 0,
+        },
+      },
+    });
+
+    results.push({
+      anchorAcId: null,
+      conformanceOnly: true,
+      limitation: 'application-notifications-in-app-AC-20102-4: the focus-pause clause (a focused toast pauses the timer and resumes on focus loss) and the toast-dismissal DOM-removal contract require observing a running browser (focus events, timer state and DOM mutation), and additionally the shipped fixture toast factory does not pause the timer on focus and marks dismissal by setting data-dismissed-at rather than removing the toast from the DOM. Deferred to a Playwright-driven check and named here as a fixture gap so the operator sees the property claim without a positive observation.',
+      verdict: 'warn',
+      detail: `Given a toast triggered by a background event and a focused-toast clause per AC-20102-4, the focus-pause + dismissal-removal properties are not observed by this Node HTTP probe and the shipped fixture does not implement them; this row is a null-anchored conformance de-claim so the AC-20102-4 gap is on the record; fixture reachability confirmed via the same shell fetch (x-fixture-request-id=${shell.requestId}).`,
+      evidence: {
+        requestId: shell.requestId,
+        responseStatus: shell.status,
+        bodyExcerpt: excerpt(shellRootMatch),
+        derived: {
+          route: '/',
+          focusPauseObserved: false,
+          dismissalRemovesToast: false,
+          reason: 'browser-only clauses of AC-20102-4; fixture does not implement them either',
+        },
+      },
+    });
+  } finally {
+    await fixture.kill();
+  }
+  return { results };
+}

package/blueprints/application-notifications-in-app/contributions/requirements/application-notifications-in-app-req-001.json

@@ -2,14 +2,21 @@
   "reqId": "application-notifications-in-app-REQ-001",
   "prdId": "PRD-001",
   "title": "The application shell preseeds the polite and assertive live-region wrappers on every declared route before any notification fires",
-  "description": "Every route the applying project declares under its navigation model renders with the two live-region wrappers already present in the DOM at page load: a `[aria-live=\"polite\"]` wrapper for informational messages and a `[role=\"alert\"]` wrapper for assertive alerts. Both wrappers exist and are empty before any notification fires; a wrapper inserted lazily after the first event is a defect that produces a screen-reader miss per the Sara Soueidan normative guidance on ARIA live regions. The wrappers carry stable `data-live-region=\"polite\"` and `data-live-region=\"assertive\"` attributes so the pack can enumerate them by data-id (not by role attribute alone, per the T-3 gate discipline).",
+  "description": "Every route the applying project declares under its navigation model renders with the two live-region wrappers already present in the DOM at page load: a `[aria-live=\"polite\"]` wrapper for informational messages and a `[role=\"alert\"]` wrapper for assertive alerts. Both wrappers exist and are empty before any notification fires; a wrapper inserted lazily after the first event is a defect that produces a screen-reader miss per the Sara Soueidan normative guidance on ARIA live regions. The wrappers carry stable `data-live-region=\"polite\"` and `data-live-region=\"assertive\"` attributes so the pack can enumerate them by data-id (not by role attribute alone, per the gate discipline).",
+  "deliveredBy": {
+    "tacId": "TAC-2101-application-notifications-in-app-live-region",
+    "field": "interfaces.renderLiveRegions"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",
   "rationale": "The WAI-ARIA 1.2 live-regions normative contract requires the container to exist in the DOM before content is inserted; a wrapper inserted at the same tick as the content races the screen-reader announcement pass and the message is silently lost. Preseeding the two wrappers on every route is the runtime discipline that turns the WCAG 4.1.3 status-message clause from a design intent into a runtime-observable check the probe pack can drive.",
-  "tags": ["blueprint:application-notifications-in-app", "category:01-live-region-preseeding"],
-  "version": "1.0.0",
+  "tags": [
+    "blueprint:application-notifications-in-app",
+    "category:01-live-region-preseeding"
+  ],
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-04T23:59:00Z",
-  "updatedAt": "2026-09-04T23:59:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-notifications-in-app/contributions/requirements/application-notifications-in-app-req-002.json

@@ -3,11 +3,18 @@
   "prdId": "PRD-001",
   "title": "A transient toast maps its priority to a live-region role, announces exactly once, and dismisses on operator activation or timeout",
   "description": "A notification surfaced as a transient toast writes into one of the two preseeded live regions based on its priority per ADR-2101: an informational priority renders into the polite wrapper and carries `role=\"status\"`, an error priority renders into the assertive wrapper and carries `role=\"alert\"`. The toast body appears in exactly one wrapper text update (the one whose role reflects the priority) and never in both. Every toast is dismissible in two ways: an operator activation on the toast's dismiss control, and a timeout at or above the ADR-2102 floor (six seconds baseline per WCAG 2.2.1 Timing Adjustable, elicited overrides above the floor). The toast records `data-shown-at` and `data-dismissed-at` timestamps on its DOM element so a probe can measure the actual timeout against the floor without sleeping in the pack.",
+  "deliveredBy": {
+    "tacId": "TAC-2102-application-notifications-in-app-centre",
+    "field": "interfaces.renderCentre"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",
   "rationale": "The WCAG 4.1.3 status-message clause and the ARIA APG alert pattern name the priority-to-role mapping as the accessibility discipline that lets a screen reader distinguish a passive confirmation (polite queue) from an assertive interruption (assertive queue). The WCAG 2.2.1 Timing Adjustable clause names six seconds as the floor for a message a reader can dwell on; a timeout below the floor is a comprehension defect. Recording the shown and dismissed timestamps on the DOM element makes both rules observable at runtime without a race-prone sleep in the pack.",
-  "tags": ["blueprint:application-notifications-in-app", "category:02-toast-contract"],
+  "tags": [
+    "blueprint:application-notifications-in-app",
+    "category:02-toast-contract"
+  ],
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-04T23:59:00Z",

package/blueprints/application-notifications-in-app/contributions/requirements/application-notifications-in-app-req-003.json

@@ -2,12 +2,19 @@
   "reqId": "application-notifications-in-app-REQ-003",
   "prdId": "PRD-001",
   "title": "The notification centre inbox lists the last N days of notifications and each acknowledge control round-trips to the server",
-  "description": "The applying project renders a notification-centre route (default `/notifications-centre`, operator-elicited) whose inbox surface lists the notifications delivered in the last N days per the ADR-2103 retention window (default thirty days, elicited). Each notification carries a stable `data-notification-id` attribute the pack enumerates by (never by a role attribute alone, per the T-3 gate discipline), and each carries a keyboard-reachable acknowledge control (`[data-action=\"acknowledge\"]`) plus a mark-read control (`[data-action=\"mark-read\"]`); the surface offers one mark-all-read control (`[data-action=\"mark-all-read\"]`) reachable in reading order. Activating the acknowledge control POSTs an acknowledge request to the applying project's server, the server responds, and the DOM updates in response: the notification's `data-acknowledged` reads `true` after the round-trip. Every item is Tab-reachable from the start of the surface without a mouse.",
+  "description": "The applying project renders a notification-centre route (default `/notifications-centre`, operator-elicited) whose inbox surface lists the notifications delivered in the last N days per the ADR-2103 retention window (default thirty days, elicited). Each notification carries a stable `data-notification-id` attribute the pack enumerates by (never by a role attribute alone, per the gate discipline), and each carries a keyboard-reachable acknowledge control (`[data-action=\"acknowledge\"]`) plus a mark-read control (`[data-action=\"mark-read\"]`); the surface offers one mark-all-read control (`[data-action=\"mark-all-read\"]`) reachable in reading order. Activating the acknowledge control POSTs an acknowledge request to the applying project's server, the server responds, and the DOM updates in response: the notification's `data-acknowledged` reads `true` after the round-trip. Every item is Tab-reachable from the start of the surface without a mouse.",
+  "deliveredBy": {
+    "tacId": "TAC-2102-application-notifications-in-app-centre",
+    "field": "interfaces.acknowledgeRoundTrip"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",
-  "rationale": "A transient toast is not a system of record; the notification centre is. Making the centre the operator's inbox with a retention window and per-item acknowledge round-trip is what turns a fleeting on-screen message into a durable one the operator can return to and confirm. Enumerating items by `data-notification-id` rather than by `role=\"listitem\"` on the container follows the T-3 gate discipline: a role attribute the primary element carries alone does not enumerate multiple children; a per-element data attribute does.",
-  "tags": ["blueprint:application-notifications-in-app", "category:03-centre-inbox"],
+  "rationale": "A transient toast is not a system of record; the notification centre is. Making the centre the operator's inbox with a retention window and per-item acknowledge round-trip is what turns a fleeting on-screen message into a durable one the operator can return to and confirm. Enumerating items by `data-notification-id` rather than by `role=\"listitem\"` on the container follows the gate discipline: a role attribute the primary element carries alone does not enumerate multiple children; a per-element data attribute does.",
+  "tags": [
+    "blueprint:application-notifications-in-app",
+    "category:03-centre-inbox"
+  ],
   "version": "1.0.0",
   "status": "approved",
   "createdAt": "2026-09-04T23:59:00Z",

package/blueprints/application-notifications-in-app/contributions/requirements/application-notifications-in-app-req-004.json

@@ -3,13 +3,20 @@
   "prdId": "PRD-001",
   "title": "The preferences UI exposes per-user category silence and delegates digest opt-in to the sibling channels",
   "description": "The applying project renders a preferences surface (default `/notifications-preferences`, operator-elicited) that carries one section per operator-elicited notification category with a labelled silence toggle (`[data-preference-category=\"<category>\"]` on the toggle's `<input>` or `<button>` control), and one section per sibling channel (`-email`, `-push`, `-webhook`) with a digest opt-in control recording the operator's intent on `data-digest-<channel>`. This blueprint ships no transport: the digest opt-in records the intent on the surface, and the applying project's sibling blueprint (once shipped) reads the intent from the preferences store and drives its own delivery. A preferences surface that promises a digest without a corresponding sibling blueprint applied is a defect the applying project surfaces via a `[data-preference-status]` label reading `\"sibling not applied\"`.",
+  "deliveredBy": {
+    "tacId": "TAC-2103-application-notifications-in-app-preferences",
+    "field": "interfaces.renderPreferences"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",
-  "rationale": "Per-user category silence is the operator's primary knob on notification fatigue: a labelled toggle per category gives the reader an accountable choice without overloading the transport. Delegating digest opt-in to the sibling channel keeps this blueprint at the in-app surface it names (per Baz decision 2026-09-04: 'we might support more types of notifications - be clear in the name what these ones are'); a digest is a transport concern the sibling blueprint owns.",
-  "tags": ["blueprint:application-notifications-in-app", "category:04-preferences"],
-  "version": "1.0.0",
+  "rationale": "Per-user category silence is the operator's primary knob on notification fatigue: a labelled toggle per category gives the reader an accountable choice without overloading the transport. Delegating digest opt-in to the sibling channel keeps this blueprint at the in-app surface it names (per the 2026-09-04 shelf decision to make the transport type explicit in the blueprint name); a digest is a transport concern the sibling blueprint owns.",
+  "tags": [
+    "blueprint:application-notifications-in-app",
+    "category:04-preferences"
+  ],
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-04T23:59:00Z",
-  "updatedAt": "2026-09-04T23:59:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-notifications-in-app/contributions/requirements/application-notifications-in-app-req-005.json

@@ -2,14 +2,21 @@
   "reqId": "application-notifications-in-app-REQ-005",
   "prdId": "PRD-001",
   "title": "The delivery-attempt log records one row per surfaced notification with the operator-readable fields for later inspection",
-  "description": "Every notification the shell surfaces (as a toast, in the notification centre, or both) appends one row to the delivery-attempt log. Each row carries `notificationId`, `category`, `priority`, `deliveredAt` (ISO-8601 timestamp of the surface event), and the optional acknowledgement trail: `dismissedAt` when the operator dismissed the toast, `acknowledgedAt` when the operator activated the centre's acknowledge control. The log is operator-readable via a `GET /api/delivery-log` endpoint the applying project exposes; the endpoint returns JSON in the shape `{ rows: [...] }`. The log is append-only; a row is never rewritten, only augmented (a `dismissedAt` or `acknowledgedAt` may land on a later request). Records write through the applied `logging` companion's factory so the log's persistence and retention layer is the companion's, not this blueprint's.",
+  "description": "Every notification the shell surfaces (as a toast, in the notification centre, or both) appends one row to the delivery-attempt log through `TAC-2102.interfaces.writeDeliveryRow`; every row honours the shape owned by `TAC-2102.interfaces.deliveryRowShape`. The applied `logging` companion persists the rows; the centre reads them back through `TAC-2102.responsibilities.readDeliveryLog` for the current-session read model.",
+  "deliveredBy": {
+    "tacId": "TAC-2102-application-notifications-in-app-centre",
+    "field": "interfaces.writeDeliveryRow"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",
   "rationale": "A delivery-attempt log is the operator's audit trail for what the shell has said and when, alongside a second row per acknowledgement event. Ownership of the row shape lives on this blueprint; ownership of the persistence layer lives on the applied `logging` companion (per REQ-005 factory delegation). Splitting the two lets the applying project pick a log store per its `logging` companion pin without the notifications blueprint dragging in a store of its own.",
-  "tags": ["blueprint:application-notifications-in-app", "category:05-delivery-log"],
-  "version": "1.0.0",
+  "tags": [
+    "blueprint:application-notifications-in-app",
+    "category:05-delivery-log"
+  ],
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-04T23:59:00Z",
-  "updatedAt": "2026-09-04T23:59:00Z"
-}
+  "updatedAt": "2026-09-10T00:00:00Z"
+}

package/blueprints/application-notifications-in-app/contributions/requirements/application-notifications-in-app-req-006.json

@@ -0,0 +1,21 @@
+{
+  "reqId": "application-notifications-in-app-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Apply-time answer families bind the five elicits to the notifications-in-app contract",
+  "description": "When the applying project answers the five apply-time elicits, the shell honours each with a runtime clause per family: `blueprint.json.elicits[id=timeout]` sets the toast timeout floor on ADR-2102 (a value below 6 seconds refuses at apply with TOAST_TIMEOUT_TOO_SHORT); `blueprint.json.elicits[id=retention]` sets the notification-centre retention window in days per ADR-2103; `blueprint.json.elicits[id=categories]` populates the per-category preference sections on TAC-2103; `blueprint.json.elicits[id=route]` sets the preferences route the shell mounts; `blueprint.json.elicits[id=page-size]` sets the notification-centre page size.",
+  "deliveredBy": {
+    "tacId": "TAC-2102-application-notifications-in-app-centre",
+    "field": "responsibilities.applyElicits"
+  },
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The five apply-time answer families named in the guide needed one must REQ per family so a project cannot elicit a value and see it ignored silently.",
+  "tags": [
+    "blueprint:application-notifications-in-app"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z"
+}

package/blueprints/application-notifications-in-app/contributions/tacs/tac-2101-application-notifications-in-app-live-region.json

@@ -28,7 +28,7 @@
     {
       "name": "priorityToRoleContract",
       "kind": "shape",
-      "description": "The ADR-2101 mapping: `info` maps to `{ wrapper: 'polite', role: 'status' }`; `error` maps to `{ wrapper: 'assertive', role: 'alert' }`. A priority outside the ADR-2101 enum is refused at project-side review."
+      "description": "The ADR-2101 mapping: `info` maps to `{ wrapper: 'polite', role: 'status' }`; `error` maps to `{ wrapper: 'assertive', role: 'alert' }`. A priority outside the ADR-2101 enum is refused at project-side check."
     }
   ],
   "dependencies": [
@@ -39,8 +39,8 @@
       "description": "Every toast the live-region factory emits records a delivery-log row through TAC-2102's `writeDeliveryRow`; ownership of the row shape lives here through the delegating call, ownership of the persistence layer lives on TAC-2102 and the applied `logging` companion."
     }
   ],
-  "tradeoffs": "The two-wrapper contract is opinionated: some designs use one wrapper per notification kind (informational, error, warning, success) with four ARIA politeness levels. This TAC insists on two wrappers because the WCAG 4.1.3 status-message clause and the ARIA APG alert pattern jointly draw the line at polite vs assertive; adding wrapper granularity that assistive technologies do not distinguish trades runtime discipline for false precision. The six-second timeout floor is deliberately not a ceiling: an elicited override raises the floor but never lowers it, so a design that shows a toast for two seconds fails at author-side review.",
-  "notes": "Known mechanism-reach gap: the pack asserts the disjoint-content rule (AC-20108-1) at the moment it inspects the wrappers, not continuously across the toast lifetime. A pathological implementation that briefly writes into both wrappers between two microtasks would not be caught by the pack; project-side review carries the residual. A v1.1 minor bump could add a MutationObserver-based check.",
+  "tradeoffs": "The two-wrapper contract is opinionated: some designs use one wrapper per notification kind (informational, error, warning, success) with four ARIA politeness levels. This TAC insists on two wrappers because the WCAG 4.1.3 status-message clause and the ARIA APG alert pattern jointly draw the line at polite vs assertive; adding wrapper granularity that assistive technologies do not distinguish trades runtime discipline for false precision. The six-second timeout floor is deliberately not a ceiling: an elicited override raises the floor but never lowers it, so a design that shows a toast for two seconds fails at the author-side check.",
+  "notes": "Known mechanism-reach gap: the pack asserts the disjoint-content rule (AC-20108-1) at the moment it inspects the wrappers, not continuously across the toast lifetime. A pathological implementation that briefly writes into both wrappers between two microtasks would not be caught by the pack; project-side check carries the residual. A v1.1 minor bump could add a MutationObserver-based check.",
   "createdAt": "2026-09-04T23:59:00Z",
   "updatedAt": "2026-09-04T23:59:00Z"
 }

package/blueprints/application-notifications-in-app/contributions/tacs/tac-2102-application-notifications-in-app-centre.json

@@ -2,17 +2,18 @@
   "tacId": "TAC-2102-application-notifications-in-app-centre",
   "prdId": "PRD-001",
   "tadId": "TAD-001",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "status": "approved",
   "name": "Notification centre inbox, retention window, acknowledge round-trip and delivery-attempt log",
   "purpose": "Owns the shell's persistent notification-centre inbox: the centre route the applying project mounts (default `/notifications-centre`, elicited), the retention window contract per ADR-2103 (default thirty days, elicited), the per-item acknowledge round-trip that POSTs to the applying project's server and updates the DOM on the response, and the delivery-attempt log write path per REQ-005. The centre is the durable inbox the operator returns to; the toast is the transient surface.",
   "responsibilities": [
-    "Render one notification wrapper per delivery-log row within the ADR-2103 retention window. Every wrapper carries `data-notification-id` (per-element attribute the pack enumerates by, never `role=\"listitem\"` on the container alone per the T-3 gate discipline) (AC-20103-1, AC-20103-2).",
+    "Render one notification wrapper per delivery-log row within the ADR-2103 retention window. Every wrapper carries `data-notification-id` (per-element attribute the pack enumerates by, never `role=\"listitem\"` on the container alone per the gate discipline) (AC-20103-1, AC-20103-2).",
     "Render one keyboard-reachable `[data-action=\"acknowledge\"]` control and one `[data-action=\"mark-read\"]` control per item; render exactly one `[data-action=\"mark-all-read\"]` control on the surface, reachable in Tab order after the item list (AC-20103-1).",
     "On acknowledge activation, POST `POST /api/notifications/acknowledge` with the notification id, wait for the server response, and update `data-acknowledged` on the item to `true` on a 2xx response; a failed response surfaces an error toast via the TAC-2101 factory and the item's `data-acknowledged` remains unchanged (AC-20103-1).",
     "On a page load with a backlog, render every backlog item on the surface without writing any body text into the polite or assertive live-region wrapper (AC-20106-1).",
-    "Expose the delivery-log write factory `writeDeliveryRow` the TAC-2101 toast factory and this TAC's centre factory both call; every write goes through the applied `logging` companion's record factory (AC-20105-2).",
-    "Expose the delivery-log read endpoint `GET /api/delivery-log` returning `{ rows: [...] }` where every row carries `notificationId`, `category`, `priority`, `deliveredAt`, optionally `dismissedAt`, optionally `acknowledgedAt`; rows are append-only (AC-20105-1)."
+    "Expose the delivery-log write factory `interfaces.writeDeliveryRow`, called by both the TAC-2101 toast factory and this TAC's centre factory; every write goes through the applied `logging` companion's record factory (AC-20105-2).",
+    "readDeliveryLog: expose the delivery-log read endpoint `GET /api/delivery-log` returning `{ rows: [...] }` where every row conforms to `interfaces.deliveryRowShape`; rows are append-only, per REQ-005 (AC-20105-1).",
+    "applyElicits: at apply time, dispatch each of the five answer families to its owner: `timeout` sets the toast timeout floor on `ADR-2102`; `retention` sets the notification-centre retention window on this TAC per `ADR-2103`; `categories` populates the per-category preference sections on `TAC-2103`; `route` sets the preferences route this TAC mounts; `page-size` sets the notification-centre page size. Per REQ-006."
   ],
   "internalStructure": "One centre-route module reading the delivery-log endpoint filtered to the retention window and rendering one wrapper per row through a shared item factory. One acknowledge-round-trip helper that owns the POST plus the DOM-update code path. One delivery-log write helper (`writeDeliveryRow`) that adapts the shell-side row shape to the applied `logging` companion's record factory.",
   "interfaces": [
@@ -24,12 +25,17 @@
     {
       "name": "writeDeliveryRow",
       "kind": "factory",
-      "description": "writeDeliveryRow({ notificationId, category, priority, deliveredAt, dismissedAt?, acknowledgedAt? }) -> Promise<void>. Writes one row through the applied `logging` companion's record factory. Called from TAC-2101's toast factory on a toast surface event and from this TAC's centre-item activation on an acknowledge event."
+      "description": "writeDeliveryRow(row) -> Promise<void>. Writes one row through the applied `logging` companion's record factory, where `row` conforms to `interfaces.deliveryRowShape`. Called from TAC-2101's toast factory on a toast surface event and from this TAC's centre-item activation on an acknowledge event."
     },
     {
       "name": "acknowledgeRoundTrip",
       "kind": "function",
       "description": "acknowledgeRoundTrip({ notificationId }) -> Promise<{ ok: boolean }>. POSTs `POST /api/notifications/acknowledge` and returns the parsed server response. A 2xx flips `data-acknowledged` on the item; a non-2xx surfaces an error toast through TAC-2101."
+    },
+    {
+      "name": "deliveryRowShape",
+      "kind": "shape",
+      "description": "Delivery-log row schema owned by TAC-2102: { deliveryTs (ISO-8601 timestamp of the surface event), priority (\"info\" | \"error\"), category (string), outcome (\"delivered\" | \"dismissed\" | \"acknowledged\" | \"expired\"), correlationId (string) }. Every row the toast factory and the centre factory write goes through writeDeliveryRow honouring this shape."
     }
   ],
   "dependencies": [
@@ -42,11 +48,11 @@
     {
       "name": "Applied logging companion",
       "kind": "external",
-      "description": "The delivery-attempt log's persistence layer is the applied `logging` companion's; this TAC delegates the write path. A project applying this blueprint without a `logging` companion (neither applied nor registered library nor core shelf) sees the delivery-log endpoint returning an empty rows array, which fails project-side review."
+      "description": "The delivery-attempt log's persistence layer is the applied `logging` companion's; this TAC delegates the write path. A project applying this blueprint without a `logging` companion (neither applied nor registered library nor core shelf) sees the delivery-log endpoint returning an empty rows array, which fails project-side check."
     }
   ],
   "tradeoffs": "The centre reading through the delivery log (rather than a separate inbox store) keeps the shell single-sourced on the applied `logging` companion but couples the surface latency to the log query; a project with a very high notification volume may want to project a materialised inbox view alongside the log. This TAC accepts the coupling because it collapses two writers of the same row into one; a project that needs the materialised view supersedes with a project-authored REQ.",
-  "notes": "Known mechanism-reach gap: the pack asserts one acknowledge round-trip on one item (AC-20103-1); the mark-read control, the mark-all-read control and the retention-window boundary (a row on day 31 must not surface) are runtime-observable ACs the shipped pack does not itself drive. The README names them individually per the T-1 gate discipline; a v1.1 minor bump could add checks for each.",
+  "notes": "Known mechanism-reach gap: the pack asserts one acknowledge round-trip on one item (AC-20103-1); the mark-read control, the mark-all-read control and the retention-window boundary (a row on day 31 must not surface) are runtime-observable ACs the shipped pack does not itself drive. The README names them individually per the gate discipline; a v1.1 minor bump could add checks for each.",
   "createdAt": "2026-09-04T23:59:00Z",
-  "updatedAt": "2026-09-04T23:59:00Z"
-}
+  "updatedAt": "2026-09-10T00:00:00Z"
+}

package/blueprints/application-notifications-in-app/contributions/tacs/tac-2103-application-notifications-in-app-preferences.json

@@ -33,8 +33,8 @@
       "description": "A preference update that fails at the server surfaces an error toast through TAC-2101."
     }
   ],
-  "tradeoffs": "Delegating digest opt-in to sibling blueprints keeps this blueprint's contract at the in-app surface (Baz decision 2026-09-04: 'be clear in the name what these ones are'). The trade-off is that on a project without any sibling channel applied the preferences surface renders disabled sibling sections; a first-time reader might expect the preferences UI to be silent about siblings that do not exist. This TAC ships the disabled section on the argument that the reserved family prefix (`application-notifications-`) is discoverable to the operator and the labelled disabled state names the residual honestly.",
-  "notes": "Known mechanism-reach gap: elicitation of the notification categories is a declarative field on the ADR-2101 elicited-parameters block; the runner has no apply-time elicitation phase today (w-2026-09-04-dave-022, built in T-5), so the applying project gathers the categories by hand at the apply pass. The README names this individually.",
+  "tradeoffs": "Delegating digest opt-in to sibling blueprints keeps this blueprint's contract at the in-app surface (per the 2026-09-04 shelf decision to make the transport type explicit in the blueprint name). The trade-off is that on a project without any sibling channel applied the preferences surface renders disabled sibling sections; a first-time reader might expect the preferences UI to be silent about siblings that do not exist. This TAC ships the disabled section on the argument that the reserved family prefix (`application-notifications-`) is discoverable to the operator and the labelled disabled state names the residual honestly.",
+  "notes": "Known mechanism-reach gap: elicitation of the notification categories is a declarative field on the ADR-2101 elicited-parameters block; the runner has no apply-time elicitation phase today (planned for a follow-up minor), so the applying project gathers the categories by hand at the apply pass. The README names this individually.",
   "createdAt": "2026-09-04T23:59:00Z",
   "updatedAt": "2026-09-04T23:59:00Z"
 }

package/blueprints/application-notifications-in-app/contributions/user-stories/application-notifications-in-app-us-20101.json

@@ -16,20 +16,44 @@
       "when": "the initial DOM is read",
       "then": "both preseeded wrappers are present, carry their id attribute, and are empty",
       "testable": true,
-      "scope": "runtime"
+      "scope": "runtime",
+      "disposition": "fixed"
     },
     {
       "id": "AC-20101-2",
-      "description": "Given the shell's live-region factory (TAC-2101 `renderLiveRegions`), a call at first render emits exactly two wrapper elements matching the AC-20101-1 shape and never re-creates them on subsequent renders (the wrappers are stable identity across the app lifetime). A factory that recreates the wrappers on a route change fails this AC at project-side review.",
+      "description": "Given the shell's live-region factory (TAC-2101 `renderLiveRegions`), a call at first render emits exactly two wrapper elements matching the AC-20101-1 shape and never re-creates them on subsequent renders (the wrappers are stable identity across the app lifetime). A factory that recreates the wrappers on a route change fails this AC at project-side check.",
       "given": "the shell's live-region factory",
       "when": "the factory is invoked at first render and again on a route change",
       "then": "the same two wrapper elements are returned; identity is stable",
       "testable": true,
-      "scope": "library"
+      "scope": "library",
+      "disposition": "fixed",
+      "ownerRef": {
+        "tacId": "TAC-2101-application-notifications-in-app-live-region",
+        "field": "interfaces.renderLiveRegions"
+      }
+    },
+    {
+      "id": "AC-20101-3",
+      "description": "The two live-region wrappers pre-seed at document render, before any state-driven mount, so that an announcement fired during a first render lands in a live region already present. A break that mounts the wrapper on state entry fails the pack.",
+      "given": "a page load on any route",
+      "when": "the DOM is inspected before any state-driven announcement fires",
+      "then": "both polite (aria-live=polite) and assertive (aria-live=assertive) live-region containers are present in the initial DOM",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "vendorCitation": {
+        "url": "https://www.w3.org/TR/WCAG22/#status-messages",
+        "verifiedOn": "2026-09-10"
+      }
     }
   ],
-  "tacIds": ["TAC-2101-application-notifications-in-app-live-region"],
-  "tags": ["blueprint:application-notifications-in-app"],
+  "tacIds": [
+    "TAC-2101-application-notifications-in-app-live-region"
+  ],
+  "tags": [
+    "blueprint:application-notifications-in-app"
+  ],
   "createdAt": "2026-09-04T23:59:00Z",
-  "updatedAt": "2026-09-04T23:59:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }