rcf-lite 0.26.0 → 0.28.0

package/blueprints/application-empty-error-states/contributions/probes/probe-utils.mjs

@@ -0,0 +1,177 @@
+// Shared helpers for application-empty-error-states 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-empty-error-states/server.js
+// booted on a scratch port from the family range 47630-47639.
+// 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-empty-error-states';
+export const PROJECT_ROOT = resolve(HERE, '..', '..', '..', '..');
+export const FIXTURE_DIR = resolve(PROJECT_ROOT, 'packages/rcf-lite/test/fixtures/probe-pack-application-empty-error-states');
+export const REPORT_DIR = resolve(PROJECT_ROOT, '.rcf/reports/blueprints/application-empty-error-states');
+export const PORT_RANGE_START = 47630;
+export const PORT_RANGE_END = 47639;
+export const DECLARED_ENV = Object.freeze(['PORT', 'EMPTY_ERROR_STATES_BREAK', '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-empty-error-states/contributions/probes/run-empty-list-and-no-search.mjs

@@ -0,0 +1,5 @@
+import runProbe from './empty-list-and-no-search.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-empty-error-states/server.js', healthy: true };
+runShim('empty-list-and-no-search', engine, runProbe);

package/blueprints/application-empty-error-states/contributions/probes/run-error-boundary-alert.mjs

@@ -0,0 +1,5 @@
+import runProbe from './error-boundary-alert.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-empty-error-states/server.js', healthy: true };
+runShim('error-boundary-alert', engine, runProbe);

package/blueprints/application-empty-error-states/contributions/probes/run-forbidden-and-server-error.mjs

@@ -0,0 +1,5 @@
+import runProbe from './forbidden-and-server-error.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-empty-error-states/server.js', healthy: true };
+runShim('forbidden-and-server-error', engine, runProbe);

package/blueprints/application-empty-error-states/contributions/probes/run-not-found-and-recovery.mjs

@@ -0,0 +1,5 @@
+import runProbe from './not-found-and-recovery.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-empty-error-states/server.js', healthy: true };
+runShim('not-found-and-recovery', engine, runProbe);

package/blueprints/application-empty-error-states/contributions/probes/run-permission-denied-and-offline.mjs

@@ -0,0 +1,5 @@
+import runProbe from './permission-denied-and-offline.mjs';
+import { runShim } from './probe-utils.mjs';
+
+const engine = { kind: 'fixture', image: 'test/fixtures/probe-pack-application-empty-error-states/server.js', healthy: true };
+runShim('permission-denied-and-offline', engine, runProbe);

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-001.json

@@ -3,6 +3,10 @@
   "prdId": "PRD-001",
   "title": "State catalogue: the eight named empty and error states, each with a machine-readable status and a distinct visual",
   "description": "The application realises eight named empty and error states, one contract per state: not-found (HTTP 404 on an unknown resource), forbidden (HTTP 403 on an authenticated principal without scope), server-error (HTTP 5xx on an internal failure), offline (navigator.onLine false), permission-denied (HTTP 403 with a per-resource cause), empty-list (a listing endpoint returned an empty array), no-search-results (a search or filter yielded zero rows), error-boundary (a client-side render exception caught by the SPA boundary). Each state carries a machine-readable status (statusCode for HTTP-triggered states, a well-known token for client-triggered states) and a distinct visual so a screenshot review reader can tell them apart at a glance. Vendor-neutral: the blueprint contributes WHAT surfaces under WHAT condition, not the visual design.",
+  "deliveredBy": {
+    "tacId": "TAC-2301-application-empty-error-states-state-machine",
+    "field": "interfaces.renderState"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-002.json

@@ -2,7 +2,11 @@
   "reqId": "application-empty-error-states-REQ-002",
   "prdId": "PRD-001",
   "title": "Recovery-action contract per state: parent-surface link, search entry, request-access flow, retry hook",
-  "description": "Every rendered state carries at least one recovery action. The recovery-action router maps each named state to one of a fixed four action shapes: parent-surface (a link back up the resource hierarchy, used by not-found and empty-list), search (a search entry, used by not-found and no-search-results), request-access (a POST to a well-known request-access endpoint the applied notification centre can surface, used by forbidden and permission-denied), retry (a client-side re-issue of the failed operation, used by server-error and offline). The router refuses to render a state without a recovery action; a state whose applied surface has no legitimate recovery renders an explicit no-recovery notice with the reason.",
+  "description": "Every rendered state carries at least one recovery action. The recovery-action router realises the closed enum owned by `TAC-2302.notes` (`parent-surface`, `search`, `request-access`, `retry`, `create`, `clear-filters`, `no-recovery`): parent-surface anchors a link back up the resource hierarchy (used by not-found and empty-list); search opens a search entry (used by not-found and no-search-results); request-access POSTs to a well-known endpoint the applied notification centre can surface (used by forbidden and permission-denied); retry re-issues the failed operation client-side (used by server-error and offline); create anchors a new-resource affordance (used by empty-list); clear-filters clears the applied filter set (used by no-search-results); no-recovery is an explicit notice the surface authors when no legitimate recovery exists. The router refuses to render a state without a recovery shape from the owned enum.",
+  "deliveredBy": {
+    "tacId": "TAC-2302-application-empty-error-states-recovery-router",
+    "field": "interfaces.renderRecovery"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",
@@ -11,8 +15,8 @@
     "blueprint:application-empty-error-states",
     "category:02-recovery-router"
   ],
-  "version": "1.0.0",
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-003.json

@@ -3,6 +3,10 @@
   "prdId": "PRD-001",
   "title": "Announcement contract: role region per state, aria-live polite for progress and reconnection, screen-reader traversal order",
   "description": "Every rendered state region carries role=\"region\" with an accessible name naming the state (WCAG 2.4.6 Headings and Labels). Progress announcements (retry attempt, reconnection to server) fire through an aria-live=\"polite\" live-region wrapper (WCAG 4.1.3 Status Messages). Screen-reader traversal order is: state heading first, then the recovery action, then any secondary detail; keyboard focus lands on the recovery control on state entry so a keyboard user reaches recovery in one tab. The error-boundary state announces via role=\"alert\" (assertive) rather than polite because the client render failed and the operator has no context.",
+  "deliveredBy": {
+    "tacId": "TAC-2301-application-empty-error-states-state-machine",
+    "field": "responsibilities.announceState"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-004.json

@@ -3,6 +3,10 @@
   "prdId": "PRD-001",
   "title": "Server-error surface: no stack trace in production, no resource-id leak on forbidden per least-privilege posture",
   "description": "The server-error (5xx) state renders in production mode without a stack trace, without a source file path, without any environment-variable key shape (VARNAME=value or process.env.NAME references), and without any framework internal frame prefix. The pack refuses when any word in a bundled sensitive-pattern list matches the rendered surface (path-shape strings, backtrace-frame prefixes, environment-variable key shape). The forbidden (403) and permission-denied (403 with cause) states render without the resource id, without the resource name and without the server-side path so a principal without scope cannot infer resource existence from the error surface. A staging environment override is available via ADR-2302 elicitation.",
+  "deliveredBy": {
+    "tacId": "TAC-2301-application-empty-error-states-state-machine",
+    "field": "responsibilities.redactSensitivePatterns"
+  },
   "category": "security",
   "domain": "application",
   "priority": "must",
@@ -11,8 +15,8 @@
     "blueprint:application-empty-error-states",
     "category:04-least-privilege"
   ],
-  "version": "1.0.0",
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-005.json

@@ -3,6 +3,10 @@
   "prdId": "PRD-001",
   "title": "Offline state: write-buffer contract, navigator.onLine reconnection announcement, per-write reconciliation semantics",
   "description": "When navigator.onLine reports false the offline state renders with a read-only banner naming the offline mode. Queued writes buffer to an applied local buffer (IndexedDB by default, an elicited alternative per ADR-2303) with an idempotency token per write, a serialised payload, and a monotonically increasing sequence. On reconnection (navigator.onLine true) the offline state announces through the polite live-region wrapper the applied notifications-in-app blueprint has preseeded; queued writes flush in sequence, each with the same idempotency token so a server-side dedupe rejects a re-issue. Per-write reconciliation semantics: on flush success the surface clears the buffer entry; on flush failure the entry is retained with a retry counter and the surface renders a per-write error banner.",
+  "deliveredBy": {
+    "tacId": "TAC-2303-application-empty-error-states-offline-buffer",
+    "field": "responsibilities.writeAndFlushReconciliation"
+  },
   "category": "functional",
   "domain": "application",
   "priority": "must",
@@ -11,8 +15,8 @@
     "blueprint:application-empty-error-states",
     "category:05-offline"
   ],
-  "version": "1.0.0",
+  "version": "1.0.1",
   "status": "approved",
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
-}
+  "updatedAt": "2026-09-10T00:00:00Z"
+}

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-006.json

@@ -0,0 +1,21 @@
+{
+  "reqId": "application-empty-error-states-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Stack-trace visibility bound to the stack-trace-visible elicit per option",
+  "description": "The server-error state honours the elicited `blueprint.json.elicits[id=stack-trace-visible]` with a runtime clause per option: when `production-hide` the surface refuses any word matching the sensitive-pattern list (backtrace-frame prefix, source path, environment-variable key shape, framework-internal frame prefix), rendering only a plain summary line and a retry recovery hook; when `staging-show` the surface may include a stack-trace block marked `data-stack-trace=\"staging\"` and the sensitive-pattern refusal narrows to environment-variable keys only; when `local-show` the surface may include full stack traces and source paths under `data-stack-trace=\"local\"` with no pattern refusal. ADR-2302 owns the visibility decision; this REQ binds each option to observable behaviour on the rendered surface.",
+  "deliveredBy": {
+    "tacId": "TAC-2301-application-empty-error-states-state-machine",
+    "field": "responsibilities.stackTraceGate"
+  },
+  "category": "security",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The elicit offers three visibility levels; each option needs a runtime clause the state machine enforces so a project cannot choose staging-show and inherit local-show behaviour silently.",
+  "tags": [
+    "blueprint:application-empty-error-states"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z"
+}

package/blueprints/application-empty-error-states/contributions/requirements/application-empty-error-states-req-007.json

@@ -0,0 +1,21 @@
+{
+  "reqId": "application-empty-error-states-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Offline strategy bound to the offline-strategy elicit per option",
+  "description": "The offline state honours the elicited `blueprint.json.elicits[id=offline-strategy]` with a runtime clause per option: when `write-buffer` the surface renders a read-only banner and queues writes to the offline buffer (per REQ-005 and TAC-2303); when `read-only-banner` the surface renders the banner and disables every write control, and no buffer entry is created; when `refuse-writes` every write attempt fails locally with a clear message referencing `OFFLINE_WRITES_REFUSED`, and no buffer entry is created. ADR-2303 owns the strategy decision; this REQ binds each option to observable behaviour on the rendered surface.",
+  "deliveredBy": {
+    "tacId": "TAC-2301-application-empty-error-states-state-machine",
+    "field": "responsibilities.offlineStrategyGate"
+  },
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "The elicit offers three strategies; each option needs a runtime clause the offline buffer or the surface enforces so a project cannot choose refuse-writes and see writes queue silently.",
+  "tags": [
+    "blueprint:application-empty-error-states"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-10T00:00:00Z",
+  "updatedAt": "2026-09-10T00:00:00Z"
+}

package/blueprints/application-empty-error-states/contributions/tacs/tac-2301-application-empty-error-states-state-machine.json

@@ -2,7 +2,7 @@
   "tacId": "TAC-2301-application-empty-error-states-state-machine",
   "prdId": "PRD-001",
   "tadId": "TAD-001",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "status": "approved",
   "name": "Empty and error state machine",
   "purpose": "Owns the mapping from an FBS surface render (a routed page, a listing surface, a search surface, a client-side render) to the eight named empty and error states and from each state to a recovery-action shape. Reads the runtime signals (HTTP status code, response body shape, navigator.onLine, caught render exception) and dispatches the correct state region plus the correct recovery shape. Every AC in this blueprint anchors on this TAC.",
@@ -10,7 +10,10 @@
     "Map HTTP 404 to not-found, 403 to forbidden or permission-denied (see internalStructure), 5xx to server-error, and empty-array response bodies to empty-list or no-search-results (see internalStructure) (AC-22101-1 through AC-22104-1, AC-22106-1, AC-22107-1).",
     "Map navigator.onLine false to offline and the reconnect signal to the polite reconnection announcement (AC-22105-1).",
     "Map a caught client-side render exception to error-boundary announced through role=\"alert\" (AC-22108-1).",
-    "Delegate every recovery action to the recovery-action router (TAC-2302) and every offline buffer operation to the offline-buffer TAC (TAC-2303)."
+    "Delegate every recovery action to the recovery-action router (TAC-2302) and every offline buffer operation to the offline-buffer TAC (TAC-2303).",
+    "redactSensitivePatterns: refuse to render any word matching the sensitive-pattern list (backtrace-frame prefix, source path, environment-variable key shape, framework-internal frame prefix) on the server-error and error-boundary surfaces in production, and any resource-id shape on the forbidden and permission-denied surfaces per least-privilege posture (REQ-004).",
+    "stackTraceGate: gate stack-trace rendering per the elicited stack-trace-visible option (production-hide, staging-show, local-show) per REQ-006.",
+    "offlineStrategyGate: honour `blueprint.json.elicits[id=offline-strategy]` on the offline surface per REQ-007: `write-buffer` renders a read-only banner and delegates writes to TAC-2303.interfaces.bufferWrite; `read-only-banner` renders the banner, disables every write control and creates no buffer entry; `refuse-writes` refuses every write attempt locally with OFFLINE_WRITES_REFUSED and creates no buffer entry."
   ],
   "internalStructure": "One state-machine module the shell mounts on route entry. On response, the machine reads the HTTP status code plus the response body shape: a 403 with a per-resource cause routes to permission-denied, a bare 403 routes to forbidden; a 200 with an empty array on a search endpoint (route carries a q query parameter) routes to no-search-results, a 200 with an empty array on a listing endpoint routes to empty-list. On navigator.onLine transitions the machine dispatches offline entry and reconnection through the polite live-region wrapper. On a caught render exception (the SPA error boundary) the machine dispatches error-boundary through the assertive alert wrapper. Every dispatch writes the state name into the rendered region as an accessible name and delegates the recovery action to the recovery router. The framework is not prescribed; the machines interfaces are what the project realises against React, Vue, Svelte or vanilla DOM.",
   "interfaces": [
@@ -42,5 +45,5 @@
   "tradeoffs": "One state-machine module keeps the mapping deterministic and lint-checkable but ties every state to a runtime signal the project must expose. Projects that route through a framework's own boundary primitive (React error boundary, Vue errorCaptured) wire the machine into that primitive rather than replacing it. Known mechanism-reach gap: the machine cannot prove keyboard focus lands on the recovery control in every framework's rendering; the pack asserts the control is reachable, project-side smoke tests supplement.",
   "notes": "See README Known mechanism-reach gaps for the full list.",
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
-}
+  "updatedAt": "2026-09-10T00:00:00Z"
+}

package/blueprints/application-empty-error-states/contributions/tacs/tac-2303-application-empty-error-states-offline-buffer.json

@@ -10,7 +10,8 @@
     "Persist every buffered write to the applied local buffer (IndexedDB by default per ADR-2303, an elicited alternative for projects that need it) with an idempotency token, serialised payload and sequence (AC-22105-1).",
     "Expose window.__offlineBuffer as a read-only enumeration for the pack and for project-side smoke tests (AC-22105-1).",
     "Announce buffered-write count changes through the polite live-region wrapper on entry and on reconnection (AC-22105-1 via TAC-2301).",
-    "On reconnection, flush the buffer in sequence, retain the entry on flush failure with a retry counter, and clear the entry on flush success."
+    "On reconnection, flush the buffer in sequence, retain the entry on flush failure with a retry counter, and clear the entry on flush success.",
+    "writeAndFlushReconciliation: on write, persist through bufferWrite with idempotency token, serialised payload and monotonic sequence; on reconnection, iterate through flushBuffer, retain entries on flush failure with a retry counter and clear on success, per REQ-005."
   ],
   "internalStructure": "One buffer module the state machine invokes on offline entry and exit. The buffer wraps the applied storage engine (default IndexedDB via a small adapter interface, elicited alternatives per ADR-2303) with a serialise/deserialise pair and a monotonic counter. The reconciliation loop is idempotent: replaying the flush against the same buffer produces the same server-side effect.",
   "interfaces": [
@@ -37,4 +38,4 @@
   "notes": "The buffer is a runtime-observable contract; the pack drives an offline probe with a synthetic write and asserts window.__offlineBuffer is populated.",
   "createdAt": "2026-09-06T15:40:00Z",
   "updatedAt": "2026-09-06T15:40:00Z"
-}
+}

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22101.json

@@ -13,7 +13,22 @@
       "id": "AC-22101-1",
       "testable": true,
       "scope": "runtime",
-      "description": "Given a 404 response on a route the SPA declares, the not-found state renders inside a role=\"region\" with an accessible name naming the missing resource kind, a keyboard-reachable recovery link to the parent surface with data-recovery=\"parent-surface\", a search entry with data-recovery=\"search\", and the browser tab title matches /^Not found - .+/. The pack drives the real browser to /probe/not-found and reads all four surface tokens."
+      "description": "Given a 404 response on a route the SPA declares, the not-found state renders inside a role=\"region\" with an accessible name naming the missing resource kind, a keyboard-reachable recovery link to the parent surface with data-recovery=\"parent-surface\", a search entry with data-recovery=\"search\", and the browser tab title matches /^Not found - .+/. The pack drives the real browser to /probe/not-found and reads all four surface tokens.",
+      "disposition": "fixed",
+      "vendorCitation": {
+        "url": "https://www.rfc-editor.org/rfc/rfc9110#status.404",
+        "verifiedOn": "2026-09-10"
+      }
+    },
+    {
+      "id": "AC-22101-2",
+      "description": "The not-found state distinguishes gone from never-existed only when the applied data blueprint supplies the removal record; otherwise the state renders as not-found with no gone-vs-never inference.",
+      "given": "a not-found state on a resource id",
+      "when": "the surface renders",
+      "then": "when the applied data blueprint supplies a removal record the surface renders the gone variant, otherwise the not-found variant",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [
@@ -25,5 +40,5 @@
     "state:not-found"
   ],
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22102.json

@@ -13,7 +13,36 @@
       "id": "AC-22102-1",
       "testable": true,
       "scope": "runtime",
-      "description": "Given a 403 response, the forbidden state renders inside role=\"region\" with a keyboard-reachable [data-action=\"request-access\"] control that POSTs to /api/request-access. The rendered surface does NOT contain any word matching the sensitive-pattern list (resource id shape, resource name shape, path-shape strings starting with /). The pack drives /probe/forbidden and reads the region, the control, and the full document text for pattern hits."
+      "description": "Given a 403 response, the forbidden state renders inside role=\"region\" with a keyboard-reachable [data-action=\"request-access\"] control that POSTs to /api/request-access. The rendered surface does NOT contain any word matching the sensitive-pattern list (resource id shape, resource name shape, path-shape strings starting with /). The pack drives /probe/forbidden and reads the region, the control, and the full document text for pattern hits.",
+      "disposition": "fixed",
+      "vendorCitation": {
+        "url": "https://www.rfc-editor.org/rfc/rfc9110#status.403",
+        "verifiedOn": "2026-09-10"
+      }
+    },
+    {
+      "id": "AC-22102-2",
+      "description": "When the request-access POST returns a non-2xx or times out, the surface announces the failure via the polite live region, keeps the request-access control keyboard-reachable in a retry-able state (data-state=idle) and never shows a submitted-success state.",
+      "given": "the forbidden state rendered and the request-access endpoint returns a non-2xx or times out",
+      "when": "the principal activates request-access",
+      "then": "the polite live region announces the failure, data-state=idle is restored on the control and no data-state=submitted transition fires",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed",
+      "vendorCitation": {
+        "url": "https://www.w3.org/TR/WCAG22/#status-messages",
+        "verifiedOn": "2026-09-10"
+      }
+    },
+    {
+      "id": "AC-22102-3",
+      "description": "The forbidden state never renders the resource identifier or any per-resource detail; the heading names the class (\"You do not have access to this resource\") and the explanation names the missing capability class only.",
+      "given": "a forbidden state on any resource id",
+      "when": "the surface renders",
+      "then": "no resource identifier is present in the DOM, only the class name of the resource type and the missing capability class",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [
@@ -25,5 +54,5 @@
     "state:forbidden"
   ],
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22103.json

@@ -13,7 +13,32 @@
       "id": "AC-22103-1",
       "testable": true,
       "scope": "runtime",
-      "description": "Given a mocked 500 response, the server-error state renders inside role=\"region\" with a keyboard-reachable [data-recovery=\"retry\"] control; the rendered surface does NOT contain any word matching the sensitive-pattern list (backtrace-frame prefix like \"at \" plus function name plus file colon line, a source path starting with / or ./ or ../, an environment-variable key shape NAME= or process.env.NAME, or a framework-internal frame prefix). The pack drives /probe/server-error and greps the document text against the pattern list."
+      "description": "Given a mocked 500 response, the server-error state renders inside role=\"region\" with a keyboard-reachable [data-recovery=\"retry\"] control; the rendered surface does NOT contain any word matching the sensitive-pattern list (backtrace-frame prefix like \"at \" plus function name plus file colon line, a source path starting with / or ./ or ../, an environment-variable key shape NAME= or process.env.NAME, or a framework-internal frame prefix). The pack drives /probe/server-error and greps the document text against the pattern list.",
+      "disposition": "fixed",
+      "vendorCitation": {
+        "url": "https://www.rfc-editor.org/rfc/rfc9110#status.500",
+        "verifiedOn": "2026-09-10"
+      }
+    },
+    {
+      "id": "AC-22103-2",
+      "description": "When the retry-recovery action fires and the underlying request fails again, the surface remains on the server-error state, the polite live region announces the retry failure and a further retry stays keyboard-reachable; no success state is transitioned to.",
+      "given": "a server-error state and a retry that returns a non-2xx or times out",
+      "when": "the principal activates retry",
+      "then": "the surface stays on server-error, the polite live region announces retry-failed and the retry control remains keyboard-reachable",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-22103-3",
+      "description": "The server-error surface never renders a stack trace, a source path, an environment variable name, or any framework internal frame in the production build (ADR-2302); a break in the fixture that leaks any of the above fails the pack.",
+      "given": "the production build renders the server-error surface",
+      "when": "the DOM is inspected",
+      "then": "no stack trace, source path, environment variable name or backtrace frame is present",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [
@@ -25,5 +50,5 @@
     "state:server-error"
   ],
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22104.json

@@ -13,7 +13,18 @@
       "id": "AC-22104-1",
       "testable": true,
       "scope": "runtime",
-      "description": "Given a mocked 403 response with a per-resource cause, the permission-denied state renders inside role=\"region\" with a class-level cause string (matches /^[A-Za-z][A-Za-z0-9 ]+$/ with no digits-run of four or more) and a [data-action=\"request-access\"] control. The pack drives /probe/permission-denied, reads the cause string, and refuses when the string contains a resource-id shape (four or more consecutive digits, or a UUID pattern, or a slug-shape id preceded by resource identifiers like \"resource=\" or \"id=\")."
+      "description": "Given a mocked 403 response with a per-resource cause, the permission-denied state renders inside role=\"region\" with a class-level cause string (matches /^[A-Za-z][A-Za-z0-9 ]+$/ with no digits-run of four or more) and a [data-action=\"request-access\"] control. The pack drives /probe/permission-denied, reads the cause string, and refuses when the string contains a resource-id shape (four or more consecutive digits, or a UUID pattern, or a slug-shape id preceded by resource identifiers like \"resource=\" or \"id=\").",
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-22104-2",
+      "description": "The permission-denied state names the missing scope class (\"You need the admin role\") and never renders the underlying resource identifier; a scope name is a WHOLE role class, never a per-resource permission.",
+      "given": "a permission-denied state on a specific resource",
+      "when": "the surface renders",
+      "then": "the missing scope name is a role class and no resource identifier appears in the DOM",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [
@@ -25,5 +36,5 @@
     "state:permission-denied"
   ],
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }

package/blueprints/application-empty-error-states/contributions/user-stories/application-empty-error-states-us-22105.json

@@ -13,7 +13,38 @@
       "id": "AC-22105-1",
       "testable": true,
       "scope": "runtime",
-      "description": "Given navigator.onLine simulated false via the runtime seam (page.setOffline(true) on the project route, an offline endpoint on the sample-app route the pack uses instead), the offline state renders inside role=\"region\" with a read-only banner naming offline mode. A synthetic write buffers to window.__offlineBuffer with an idempotency token and a monotonic sequence. On the reconnect signal (navigator.onLine true or the sample-app /probe/offline?reconnect route) the polite live-region wrapper with data-live-region=\"polite\" carries a reconnection announcement. The pack drives /probe/offline, reads the banner, the buffer entry and the polite wrapper text."
+      "description": "Given navigator.onLine simulated false via the runtime seam (page.setOffline(true) on the project route, an offline endpoint on the sample-app route the pack uses instead), the offline state renders inside role=\"region\" with a read-only banner naming offline mode. A synthetic write buffers to window.__offlineBuffer with an idempotency token and a monotonic sequence. On the reconnect signal (navigator.onLine true or the sample-app /probe/offline?reconnect route) the polite live-region wrapper with data-live-region=\"polite\" carries a reconnection announcement. The pack drives /probe/offline, reads the banner, the buffer entry and the polite wrapper text.",
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-22105-2",
+      "description": "On reconnection, the offline buffer flushes in the order of enqueue: each buffered write is replayed with the stable token it was buffered under, and a successful write removes the entry from the buffer.",
+      "given": "a buffer with two writes enqueued while offline",
+      "when": "navigator.onLine transitions to true and the buffer flushes",
+      "then": "the two writes are replayed in the order they were enqueued, each keyed by its stable token, and each success removes the entry",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-22105-3",
+      "description": "When a buffered write returns a non-2xx or times out on replay, the entry stays in the buffer, its retry-count increments, a banner announces the failure via the polite live region, and no downstream surface renders as if the write had succeeded.",
+      "given": "a buffer with one write enqueued and the flush replay returns a non-2xx or times out",
+      "when": "the flush runs",
+      "then": "the entry remains in the buffer with retryCount incremented, the polite live region announces the failure and no downstream surface reflects the write",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
+    },
+    {
+      "id": "AC-22105-4",
+      "description": "The buffer refuses to enqueue two writes with the same stable token (idempotency of a retried operation): the second enqueue is a no-op and the buffer size remains 1.",
+      "given": "a buffer that already contains a write with token T",
+      "when": "the client attempts to enqueue a second write with the same token T",
+      "then": "the second enqueue is a no-op, the buffer size stays at 1 and no duplicate replay fires on flush",
+      "testable": true,
+      "scope": "runtime",
+      "disposition": "fixed"
     }
   ],
   "tacIds": [
@@ -25,5 +56,5 @@
     "state:offline"
   ],
   "createdAt": "2026-09-06T15:40:00Z",
-  "updatedAt": "2026-09-06T15:40:00Z"
+  "updatedAt": "2026-09-10T00:00:00Z"
 }