rcf-lite 0.21.0 → 0.22.0

package/blueprints/application-empty-error-states/probe-packs/application-empty-error-states.pack.mjs

@@ -0,0 +1,284 @@
+// application-empty-error-states probe pack (v1.0.0).
+//
+// Eight surface-observable checks, one per named state, anchored to
+// the blueprint's contributed AC ids:
+//   AC-22101-1 not-found (heading, parent-surface link, search entry, tab title)
+//   AC-22102-1 forbidden (request-access control, no resource-id leak)
+//   AC-22103-1 server-error (retry, no stack trace, no path shape, no env-key shape)
+//   AC-22104-1 permission-denied (class-level cause, no resource id)
+//   AC-22105-1 offline (banner, buffered synthetic write, polite reconnection announcement)
+//   AC-22106-1 empty-list (distinct visual wrapper, creation-affordance recovery)
+//   AC-22107-1 no-search-results (distinct visual wrapper, echoed query, clear-filters recovery)
+//   AC-22108-1 error-boundary (role=alert, retry control, no stack detail)
+//
+// Every check drives the real Playwright browser the T-0 runner
+// injects. URLs are composed by the withUrl(runtimeUrl, path) helper
+// per the round 3 T-3 fix train; no bare string concatenation.
+//
+// Sample-app fixture:
+// packages/rcf-lite/test/fixtures/probe-pack-application-empty-error-states/
+// Fixture ships one route per state under /probe/<state> plus break
+// switches (?break=stack-trace, ?break=leak-id, ?break=no-recovery,
+// ?break=no-live-region) so the negative runs can be driven from a
+// single boot.
+
+function withUrl(runtimeUrl, path) {
+  return new URL(path, runtimeUrl).toString();
+}
+
+// Sensitive-pattern list used by AC-22103-1 (server-error surface)
+// and by AC-22108-1 (error-boundary surface). Words on this list must
+// not appear on the rendered document text in production.
+//
+// Encoded as an array of {name, re} entries so a failure message can
+// cite which pattern matched. Every regexp is anchored on token
+// boundaries to reduce false positives on legitimate copy.
+const SENSITIVE_PATTERNS = [
+  { name: 'backtrace-frame', re: /\bat\s+[A-Za-z_$][\w$.]*\s*\([^)]*:\d+:\d+\)/ },
+  { name: 'source-path-absolute', re: /(?:^|[\s"'>])\/(?:usr|opt|home|var|etc|Users|private)\/[\w\-./]+/ },
+  { name: 'source-path-relative', re: /(?:^|[\s"'>])\.{1,2}\/[\w\-./]+\.(?:js|mjs|cjs|ts|tsx|jsx)/ },
+  { name: 'env-key-assignment', re: /\b[A-Z][A-Z0-9_]{2,}=(?!=)[^\s"']+/ },
+  { name: 'process-env-reference', re: /\bprocess\.env\.[A-Z_][A-Z0-9_]*/ },
+  { name: 'framework-internal-frame', re: /\b(?:node_modules|webpack-internal|nextjs-internal)\b/ },
+];
+
+// Resource-id pattern list for AC-22104-1 (permission-denied cause
+// must be class-level, not per-resource).
+const RESOURCE_ID_PATTERNS = [
+  { name: 'four-plus-digit-run', re: /\b\d{4,}\b/ },
+  { name: 'uuid-shape', re: /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/ },
+  { name: 'resource-slug-hint', re: /\b(?:resource|id|slug|handle)=[A-Za-z0-9._-]+/i },
+];
+
+function firstSensitiveMatch(text, patterns) {
+  if (typeof text !== 'string') return null;
+  for (const { name, re } of patterns) {
+    const m = text.match(re);
+    if (m) return { name, match: m[0] };
+  }
+  return null;
+}
+
+export default {
+  packName: 'application-empty-error-states',
+  version: '1.0.0',
+  blueprintSlug: 'application-empty-error-states',
+  // Applies to any FBS that realises the state-machine TAC or whose
+  // navModel routes name the operator-configured error-shell path.
+  // References BOTH `tacIds` AND `route` per the loader source-scan
+  // rule (T-0 AC-1701-3, cross-check with authoring standard 8c).
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2301-application-empty-error-states-state-machine')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /\/probe\/(?:not-found|forbidden|server-error|permission-denied|offline|empty-list|search|error-boundary)(\/|$|\?)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-22101-1',
+      severity: 'block',
+      description: 'not-found state renders inside a region with a naming heading, a parent-surface recovery link, a search entry, and a browser tab title matching /^Not found - .+/',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/not-found'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="not-found"]');
+          if (!region) return { present: false };
+          const heading = region.querySelector('h1, h2, [role="heading"]');
+          const parent = region.querySelector('[data-recovery="parent-surface"]');
+          const search = region.querySelector('[data-recovery="search"]');
+          return {
+            present: true,
+            headingText: heading ? heading.textContent.trim() : null,
+            hasParent: !!parent,
+            hasSearch: !!search,
+            title: document.title,
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'not-found region [data-surface="not-found"] not found' };
+        if (!dom.headingText) return { verdict: 'fail', detail: 'not-found region missing heading' };
+        if (!dom.hasParent) return { verdict: 'fail', detail: 'not-found region missing [data-recovery="parent-surface"]' };
+        if (!dom.hasSearch) return { verdict: 'fail', detail: 'not-found region missing [data-recovery="search"]' };
+        if (!/^Not found - .+/.test(dom.title)) return { verdict: 'fail', detail: `not-found tab title did not match /^Not found - .+/: ${JSON.stringify(dom.title)}` };
+        return { verdict: 'pass', detail: `heading=${JSON.stringify(dom.headingText)} title=${JSON.stringify(dom.title)}` };
+      },
+    },
+    {
+      id: 'AC-22102-1',
+      severity: 'block',
+      description: 'forbidden state renders inside a region with a request-access control and the rendered surface refuses to include a resource id, resource name or path-shape token',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/forbidden'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="forbidden"]');
+          if (!region) return { present: false };
+          const control = region.querySelector('[data-action="request-access"]');
+          return { present: true, hasControl: !!control, text: document.body.innerText };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'forbidden region [data-surface="forbidden"] not found' };
+        if (!dom.hasControl) return { verdict: 'fail', detail: 'forbidden region missing [data-action="request-access"] control' };
+        // Least-privilege posture: no resource-id shape, no source path leaking through.
+        const leak = firstSensitiveMatch(dom.text, RESOURCE_ID_PATTERNS);
+        if (leak) return { verdict: 'fail', detail: `forbidden surface leaked ${leak.name}: ${leak.match}` };
+        const path = firstSensitiveMatch(dom.text, SENSITIVE_PATTERNS.filter((p) => p.name.startsWith('source-path')));
+        if (path) return { verdict: 'fail', detail: `forbidden surface leaked ${path.name}: ${path.match}` };
+        return { verdict: 'pass', detail: 'forbidden region clean; request-access control present' };
+      },
+    },
+    {
+      id: 'AC-22103-1',
+      severity: 'block',
+      description: 'server-error state renders in production without a stack trace, without a source path, without an env-key shape and without a framework-internal frame prefix',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/server-error'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="server-error"]');
+          if (!region) return { present: false };
+          const retry = region.querySelector('[data-recovery="retry"]');
+          return { present: true, hasRetry: !!retry, text: document.body.innerText };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'server-error region [data-surface="server-error"] not found' };
+        if (!dom.hasRetry) return { verdict: 'fail', detail: 'server-error region missing [data-recovery="retry"] control' };
+        const leak = firstSensitiveMatch(dom.text, SENSITIVE_PATTERNS);
+        if (leak) return { verdict: 'fail', detail: `server-error surface leaked ${leak.name}: ${leak.match}` };
+        return { verdict: 'pass', detail: 'server-error region clean; retry control present' };
+      },
+    },
+    {
+      id: 'AC-22104-1',
+      severity: 'block',
+      description: 'permission-denied state renders a class-level cause string and never a resource id',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/permission-denied'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="permission-denied"]');
+          if (!region) return { present: false };
+          const cause = region.querySelector('[data-cause]');
+          const control = region.querySelector('[data-action="request-access"]');
+          return {
+            present: true,
+            causeText: cause ? cause.textContent.trim() : null,
+            hasControl: !!control,
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'permission-denied region [data-surface="permission-denied"] not found' };
+        if (!dom.causeText) return { verdict: 'fail', detail: 'permission-denied region missing [data-cause] class-level cause' };
+        if (!dom.hasControl) return { verdict: 'fail', detail: 'permission-denied region missing [data-action="request-access"] control' };
+        const leak = firstSensitiveMatch(dom.causeText, RESOURCE_ID_PATTERNS);
+        if (leak) return { verdict: 'fail', detail: `permission-denied cause leaked ${leak.name}: ${leak.match}` };
+        return { verdict: 'pass', detail: `cause=${JSON.stringify(dom.causeText)}` };
+      },
+    },
+    {
+      id: 'AC-22105-1',
+      severity: 'block',
+      description: 'offline state renders with a read-only banner, a synthetic write buffers to window.__offlineBuffer with an idempotency token, and the polite live-region wrapper carries the reconnection announcement',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/offline'));
+        const offline = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="offline"]');
+          if (!region) return { present: false };
+          const banner = region.querySelector('[data-banner="offline"]');
+          // Fixture pre-seeds a synthetic write on page load so the
+          // pack can observe the buffer without driving Playwright
+          // page.setOffline directly.
+          const buf = window.__offlineBuffer;
+          const hasBufferEntry = Array.isArray(buf) && buf.length > 0
+            && typeof buf[0].idempotencyToken === 'string' && buf[0].idempotencyToken.length > 0
+            && typeof buf[0].sequence === 'number';
+          return { present: true, hasBanner: !!banner, hasBufferEntry, bufferSample: buf ? buf.slice(0, 1) : null };
+        });
+        if (!offline.present) return { verdict: 'fail', detail: 'offline region [data-surface="offline"] not found' };
+        if (!offline.hasBanner) return { verdict: 'fail', detail: 'offline region missing [data-banner="offline"]' };
+        if (!offline.hasBufferEntry) return { verdict: 'fail', detail: `window.__offlineBuffer not populated with a token-and-sequence entry: ${JSON.stringify(offline.bufferSample)}` };
+        // Reconnection: drive the fixture's reconnect route, then
+        // read the polite live-region wrapper's text.
+        await browser.goto(withUrl(runtimeUrl, '/probe/offline?reconnect=1'));
+        const reconnect = await browser.evaluate(() => {
+          const live = document.querySelector('[data-live-region="polite"]');
+          return { text: live ? live.textContent.trim() : null };
+        });
+        if (!reconnect.text || reconnect.text.length === 0) {
+          return { verdict: 'fail', detail: 'polite live-region wrapper empty on reconnect; expected a reconnection announcement' };
+        }
+        return { verdict: 'pass', detail: `bufferSample=${JSON.stringify(offline.bufferSample)} reconnect=${JSON.stringify(reconnect.text)}` };
+      },
+    },
+    {
+      id: 'AC-22106-1',
+      severity: 'block',
+      description: 'empty-list state renders with a distinct visual wrapper and a creation-affordance recovery control',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/empty-list'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="empty-list"]');
+          if (!region) return { present: false };
+          const wrapper = region.querySelector('[data-visual="empty-list"]');
+          const create = region.querySelector('[data-recovery="create"]');
+          return { present: true, hasWrapper: !!wrapper, hasCreate: !!create };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'empty-list region [data-surface="empty-list"] not found' };
+        if (!dom.hasWrapper) return { verdict: 'fail', detail: 'empty-list region missing [data-visual="empty-list"] wrapper' };
+        if (!dom.hasCreate) return { verdict: 'fail', detail: 'empty-list region missing [data-recovery="create"] control' };
+        return { verdict: 'pass', detail: 'empty-list wrapper and create control present' };
+      },
+    },
+    {
+      id: 'AC-22107-1',
+      severity: 'block',
+      description: 'no-search-results state renders with a distinct visual wrapper, an echoed query and a clear-filters recovery control',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/search?q=needle'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="no-search-results"]');
+          if (!region) return { present: false };
+          const wrapper = region.querySelector('[data-visual="no-search-results"]');
+          const query = region.querySelector('[data-query]');
+          const clear = region.querySelector('[data-recovery="clear-filters"]');
+          return {
+            present: true,
+            hasWrapper: !!wrapper,
+            queryText: query ? query.textContent.trim() : null,
+            hasClear: !!clear,
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'no-search-results region [data-surface="no-search-results"] not found' };
+        if (!dom.hasWrapper) return { verdict: 'fail', detail: 'no-search-results region missing [data-visual="no-search-results"] wrapper' };
+        if (!dom.hasClear) return { verdict: 'fail', detail: 'no-search-results region missing [data-recovery="clear-filters"] control' };
+        if (!dom.queryText || !dom.queryText.includes('needle')) {
+          return { verdict: 'fail', detail: `no-search-results region did not echo the query verbatim: ${JSON.stringify(dom.queryText)}` };
+        }
+        return { verdict: 'pass', detail: `queryEcho=${JSON.stringify(dom.queryText)}` };
+      },
+    },
+    {
+      id: 'AC-22108-1',
+      severity: 'block',
+      description: 'error-boundary state renders inside role=alert with a retry recovery hook and no stack detail on the rendered surface',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/probe/error-boundary?crash=1'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="error-boundary"]');
+          if (!region) return { present: false };
+          const role = region.getAttribute('role');
+          const retry = region.querySelector('[data-recovery="retry"]');
+          return { present: true, role, hasRetry: !!retry, text: document.body.innerText };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'error-boundary region [data-surface="error-boundary"] not found' };
+        if (dom.role !== 'alert') return { verdict: 'fail', detail: `error-boundary region role expected "alert", got ${JSON.stringify(dom.role)}` };
+        if (!dom.hasRetry) return { verdict: 'fail', detail: 'error-boundary region missing [data-recovery="retry"] control' };
+        const leak = firstSensitiveMatch(dom.text, SENSITIVE_PATTERNS);
+        if (leak) return { verdict: 'fail', detail: `error-boundary surface leaked ${leak.name}: ${leak.match}` };
+        return { verdict: 'pass', detail: 'error-boundary role=alert, retry control present, no stack detail' };
+      },
+    },
+  ],
+};

package/blueprints/application-error-handling/docs/topics.md

@@ -25,5 +25,12 @@
 | application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
 | application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
 | application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
 
 The shelf-wide band registry lives in `packages/rcf-lite/docs/blueprint-authoring.md` section 5.

package/blueprints/application-file-upload/CHANGELOG.md

@@ -0,0 +1,9 @@
+# application-file-upload CHANGELOG
+
+## 1.0.0 (visual round T-2, spec 2026-09-06)
+
+- First ratified version of the shelf's file-upload blueprint. Five REQs (input contract with a labelled file input plus drop-zone plus keyboard alternative per WCAG 2.5.7, progress contract with per-file percent and aggregate percent and polite live-region tick, refusal contract with MIME and size and virus-scan gates and aria-describedby error binding and focus-to-retry, transport contract chunked-and-resumable with multipart POST default and tus.io elicited alternative, completion contract with assertive-slot success announcement per WCAG 4.1.3 and per-file remove and retry), seven USs 23101-23107 binding one runtime-observable AC per REQ plus two cross-cutting cases (network-interruption resumption AC-23106-1, background-tab progress AC-23107-1), three TACs 2401-2403 (upload input surface, upload transport contract, upload progress announcer), three ADRs 2401-2403 (transport branch with multipart recommendedDefault true and tus and vendor-sdk elicited, accepted MIME set and per-file size cap elicited, virus-scan integration via a capability-plus-elicit). No new global topics.
+- Ships `probe-packs/application-file-upload.pack.mjs`: four surface-observable browser-verify checks anchored one per contract (`AC-23101-1` input surface, `AC-23102-1` progress announcer, `AC-23103-1` refusal contract, `AC-23104-1` chunked transport). Every URL is composed by the `withUrl(runtimeUrl, path)` helper per the round 3 T-3 fix train; no bare string concatenation. The pack-level `appliesTo` predicate references BOTH `tacIds` (TAC-2401) AND `route` (the operator-configured upload path glob).
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-file-upload/` with a Node HTTP server realising both transport branches honestly (`?transport=multipart` default, `?transport=tus` elicited alternative) and break switches (`?break=no-input`, `?break=no-live-region`, `?break=send-refused`, `?break=no-chunks`) driving the negative runs from a single boot. The fixture ships its own README naming PORT, every `?transport=`, every `?seed=`, every `?break=`, the manual boot line and the two-line gate-reviewer boot.
+- Declares `suggestedCompanions` `logging` (every refused upload writes one request-scoped log line with the closed refusal reason and the correlation identifier) and `errorHandling` (refusals and transport-layer failures construct an internal error record through the applied error-handling factory). Does NOT declare `providesRoles` (leaf blueprint per spec; loader refuses an empty `providesRoles` array when set, so the leaf-blueprint intent is expressed by omitting the field). Does NOT declare `capabilities` and does NOT declare `requiresAppliedCapabilities` (no auth required).
+- Seventh shipped consumer of T-0's probe-pack runner extension.

package/blueprints/application-file-upload/README.md

@@ -0,0 +1,85 @@
+# File upload blueprint (v1.0.0)
+
+Vendor-neutral file-upload contract for an rcf-lite application. Ships one upload surface with three input affordances (a labelled `<input type="file">`, a `[data-drop-zone]` region and a keyboard-focusable `[data-open-picker]` button per WCAG 2.5.7), a chunked-and-resumable transport with a multipart POST default and a tus.io elicited alternative, a refusal contract (MIME, size cap, virus-scan) that binds errors via `aria-describedby` and refuses to send refused bytes to the server, a progress announcer that emits a polite live-region tick in the closed format `"<uploaded> of <total> files, <PP> percent"` and an assertive-slot completion announcement per WCAG 4.1.3, and per-file remove and retry controls. Ships a Playwright probe pack under `probe-packs/application-file-upload.pack.mjs` whose four checks each anchor one contract and refuse on the corresponding break switch on the shipped sample-app fixture.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-file-upload
+```
+
+Applies 18 contributions (5 REQs, 7 USs, 3 TACs, 3 ADRs) cleanly on any fresh init project. No `requiresAppliedCapabilities`, no auth prerequisite. The three ADR elicits (`ADR-2401` transport branch, `ADR-2402` accepted MIME set and per-file size cap, `ADR-2403` virus-scan verifier) carry the multipart default with `recommendedDefault: true` on the transport branch; the other two elicits (accepted set and virus-scan) have no shelf default (see the elicits below).
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `suggestedCompanions: [logging, errorHandling]`, 18 contributions in the 24xx / 23xxx band |
+| Doc set | `contributions/` | 5 REQs, 7 USs (7 runtime-observable ACs), 3 TACs, 3 ADRs |
+| Probe pack | `probe-packs/application-file-upload.pack.mjs` | Four surface-observable browser-verify checks, one per contract |
+| Guide | `guide/application-file-upload.md` | Operator-facing: when to reach, when not, mechanism-reach gaps |
+| Coordination vocabulary | `docs/topics.md` | Shelf id band registry update; no new global topics claimed |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-file-upload/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## The four contracts
+
+| Contract | REQ | AC on the pack | Region wrapper | Announcement |
+|---|---|---|---|---|
+| Input surface | REQ-001 | `AC-23101-1` | `[data-surface="file-upload"]` | (n/a; keyboard reach + accessible name) |
+| Progress announcer | REQ-002 | `AC-23102-1` | `[data-live-region="polite"]` inside the region | polite `aria-live="polite"` |
+| Refusal contract | REQ-003 | `AC-23103-1` | `[data-file-row][data-refused="true"]` | `aria-describedby` error binding |
+| Chunked transport | REQ-004 | `AC-23104-1` | `[data-transport]` on the region; `[data-chunks-uploaded]` on each row | (n/a; observed on the wire) |
+| Completion | REQ-005 | asserted by AC-23105-1 (see below) | `[data-assertive-slot]` | `aria-live="assertive"` |
+
+The pack ships four checks (`AC-23101-1`, `AC-23102-1`, `AC-23103-1`, `AC-23104-1`) which is the minimum honest set per spec section 5.2; the completion contract (`AC-23105-1`) and the cross-cutting cases (`AC-23106-1` network interruption resumption, `AC-23107-1` background-tab progress) are runtime-observable ACs bound only through the fixture and the anatomy test. Every gap is enumerated below and is a candidate for a v1.1.0 minor bump extending the pack.
+
+## The four fixture states
+
+Every file row on the fixture cycles through the closed state set `idle` -> `uploading` -> `complete` (honest branch) or `idle` -> `refused` (refusal branch). The state slug rides `[data-file-state]` on the row. The four slugs appear identically across the fixture README, this README, the guide, the pack `checks[]` descriptions and `docs/topics.md`.
+
+## The two transport slugs
+
+`multipart` is the recommended default per ADR-2401; `tus` is the elicited alternative (tus.io 1.0.0). The two slugs appear identically across the fixture README, this README, the guide, the pack `checks[]` descriptions and `docs/topics.md`. The third elicited alternative (`vendor-sdk` for S3, R2, Cloudinary) is documented in ADR-2401 but is not exercised by the shipped fixture; a project on a vendor SDK adapts the pack to run against a fixture that mocks the vendor's completion callback.
+
+## Elicited parameters
+
+- **Transport branch (ADR-2401).** Default: `multipart` (recommendedDefault true). Elicited alternatives: `tus`, `vendor-sdk`.
+- **Accepted MIME set (ADR-2402).** No default. Every project elicits its own list of IANA media types. The input TAC refuses every file until this is elicited (the safe floor).
+- **Per-file size cap in bytes (ADR-2402).** No default. Every project elicits its own cap. The input TAC refuses every file until this is elicited.
+- **Concurrency cap** for the transport worker pool. Recommended default: 3. Projects with a slow-link posture elicit a lower cap.
+- **Announcer polling interval in milliseconds.** Recommended default: 250. Backgrounded tabs continue to tick at the same interval per REQ-002 and AC-23107-1.
+- **Virus-scan verifier (ADR-2403).** Capability-plus-elicit. Every project elicits the verifier or the explicit noop; there is no shelf default.
+
+## The one runtime gate
+
+`probe-packs/application-file-upload.pack.mjs` ships four checks the `rcf verify browser` runner invokes on any FBS whose surface binds `TAC-2401-application-file-upload-input` or whose nav model routes name an operator-configured upload path. Each check drives the real Playwright browser the runner provisions, reads the accessibility tree and the DOM (and the request log for the refusal check and the tus branch), and returns a verdict. URLs are composed by the `withUrl(runtimeUrl, path)` helper per the round 3 T-3 fix train; no bare string concatenation.
+
+## Quality bar
+
+WCAG 2.2 AA on every upload surface: 2.5.7 Dragging Movements (the drop-zone is never the only input path; the keyboard opener satisfies the alternative), 4.1.3 Status Messages (the polite live-region tick and the assertive-slot completion announcement fire through preseeded wrappers), 3.3.1 Error Identification (every refusal names the closed reason from `mime-refused`, `size-refused`, `virus-refused`), 1.3.1 Info and Relationships (every refusal binds the error message to its file row via `aria-describedby`), 3.3.3 Error Suggestion (every refused row exposes a keyboard-reachable retry control and the guide names the correction). ARIA APG button pattern on the retry control; ARIA APG status pattern on the polite tick. `standardsTrace` on the blueprint is empty (this is a general-enterprise-practice blueprint); each ADR contribution carries `standardsTraceClause` naming the clause or vendor spec it implements.
+
+The refusal contract is a real refusal: the pack asserts the refused filename never appears on `window.__uploadRequestLog`, and the `?break=send-refused` fixture switch is the only path that lets refused bytes reach the server.
+
+## Known mechanism-reach gaps
+
+Runtime-observable ACs the pack does NOT bind directly (checklist section 6.g), listed individually per AC id:
+
+- **AC-23101-1 drop-zone drop event round-trip.** The pack asserts the `[data-drop-zone]` region exists and that the keyboard opener focuses the file input on Enter; it does NOT additionally synthesise a drag event and drop a File onto the drop-zone (Playwright's DataTransfer synthesis is fragile across browsers). A v1.1.0 minor bump can drive a drop via `page.evaluate` and read that the file-list picked up the drop.
+- **AC-23102-1 screen-reader adoption of the polite region.** The pack asserts the polite wrapper's textContent matches the closed format and advances monotonically; it does NOT additionally probe screen-reader adoption (that requires a real assistive tech in the loop). A v1.1.0 minor bump can attach an accessibility-tree observer via the browser's a11y snapshot.
+- **AC-23103-1 aria-describedby resolves to a non-empty error message.** The pack asserts `aria-describedby` resolves and that the refused row exposes the closed `data-refusal-reason`; the error-text content check is a substring assertion (present and non-empty), not a full-message copy check. A v1.1.0 minor bump can pin the error message content per refusal reason.
+- **AC-23104-1 network-interruption resume on the multipart branch.** The pack asserts `[data-chunks-uploaded]` exceeds one on both branches and that the tus branch records numeric `Upload-Offset` values on `window.__tusPatchOffsets`; it does NOT additionally probe a mid-upload interruption on the multipart branch (that requires a request-blocking driver). A v1.1.0 minor bump can drive the `?interrupt=1` + `?resume=1` seams the fixture already exposes via AC-23106-1.
+- **AC-23105-1 assertive-slot exclusive fire.** The pack does NOT bind this AC directly; the anatomy test drives the fixture and reads the assertive slot's textContent. A v1.1.0 minor bump can promote the check into the pack, driving an upload set to completion and reading the assertive wrapper.
+- **AC-23106-1 network interruption resumption.** The pack does NOT bind this AC directly. The fixture exposes `?interrupt=1` and `?resume=1` and the anatomy test walks the resume path; a v1.1.0 minor bump promotes the check.
+- **AC-23107-1 background-tab tick continuity.** The pack does NOT bind this AC directly. The fixture exposes `?background=1` and the anatomy test synthesises a `visibilitychange` event; a v1.1.0 minor bump promotes the check.
+
+## Companions
+
+`suggestedCompanions` declares `logging` (every refused upload writes one request-scoped log line with the closed refusal reason and the correlation identifier the applied logger factory returns) and `errorHandling` (refusals and transport-layer failures construct an internal error record through the applied error-handling factory so the aria-describedby error message renders a consistent internal representation). Neither is required to apply the blueprint; a project without a logging companion still ships the refusal contract, it just does not emit a per-refusal log line.
+
+## Consumers
+
+The round-4 spec's CSV-import candidate would consume this blueprint's transport and refusal contracts; that candidate is not in this round. A downstream `application-forms-wizard` may wire a per-step file-upload field to this blueprint's input TAC.
+
+## Composition with application-spa
+
+`application-spa` REQ-006 ships upload, progress and error components as part of its component library. This blueprint composes with SPA; the topic-ownership boundary lives in `docs/topics.md`. SPA owns the visual tokens for the upload region; this sibling owns the input affordances, the transport contract, the refusal contract and the runtime enforcement pack.

package/blueprints/application-file-upload/blueprint.json

@@ -0,0 +1,114 @@
+{
+  "slug": "application-file-upload",
+  "version": "1.0.0",
+  "category": "application",
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every refused upload writes one request-scoped log line with the refusal reason (mime, size, virus-scan) and the correlation identifier the applied logger factory returns."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "Refusals and transport-layer failures construct an internal error record through the applied error-handling factory so the aria-describedby error binding renders a consistent message."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "application-file-upload-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-file-upload-req-001.json"
+    },
+    {
+      "id": "application-file-upload-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-file-upload-req-002.json"
+    },
+    {
+      "id": "application-file-upload-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-file-upload-req-003.json"
+    },
+    {
+      "id": "application-file-upload-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-file-upload-req-004.json"
+    },
+    {
+      "id": "application-file-upload-REQ-005",
+      "kind": "req",
+      "path": "requirements/application-file-upload-req-005.json"
+    },
+    {
+      "id": "application-file-upload-US-23101",
+      "kind": "us",
+      "path": "user-stories/application-file-upload-us-23101.json"
+    },
+    {
+      "id": "application-file-upload-US-23102",
+      "kind": "us",
+      "path": "user-stories/application-file-upload-us-23102.json"
+    },
+    {
+      "id": "application-file-upload-US-23103",
+      "kind": "us",
+      "path": "user-stories/application-file-upload-us-23103.json"
+    },
+    {
+      "id": "application-file-upload-US-23104",
+      "kind": "us",
+      "path": "user-stories/application-file-upload-us-23104.json"
+    },
+    {
+      "id": "application-file-upload-US-23105",
+      "kind": "us",
+      "path": "user-stories/application-file-upload-us-23105.json"
+    },
+    {
+      "id": "application-file-upload-US-23106",
+      "kind": "us",
+      "path": "user-stories/application-file-upload-us-23106.json"
+    },
+    {
+      "id": "application-file-upload-US-23107",
+      "kind": "us",
+      "path": "user-stories/application-file-upload-us-23107.json"
+    },
+    {
+      "id": "TAC-2401-application-file-upload-input",
+      "kind": "tac",
+      "path": "tacs/tac-2401-application-file-upload-input.json"
+    },
+    {
+      "id": "TAC-2402-application-file-upload-transport",
+      "kind": "tac",
+      "path": "tacs/tac-2402-application-file-upload-transport.json"
+    },
+    {
+      "id": "TAC-2403-application-file-upload-progress-announcer",
+      "kind": "tac",
+      "path": "tacs/tac-2403-application-file-upload-progress-announcer.json"
+    },
+    {
+      "id": "ADR-2401-application-file-upload-transport",
+      "kind": "adr",
+      "path": "adrs/adr-2401-application-file-upload-transport.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "WHATWG Fetch multipart/form-data; tus.io resumable upload protocol 1.0.0"
+    },
+    {
+      "id": "ADR-2402-application-file-upload-accepted-set",
+      "kind": "adr",
+      "path": "adrs/adr-2402-application-file-upload-accepted-set.json",
+      "elicited": true,
+      "standardsTraceClause": "IANA media types; generic enterprise practice"
+    },
+    {
+      "id": "ADR-2403-application-file-upload-virus-scan",
+      "kind": "adr",
+      "path": "adrs/adr-2403-application-file-upload-virus-scan.json",
+      "elicited": true,
+      "standardsTraceClause": "OWASP ASVS V12 file uploads"
+    }
+  ]
+}

package/blueprints/application-file-upload/contributions/adrs/adr-2401-application-file-upload-transport.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2401-application-file-upload-transport",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Transport branch: multipart POST is the recommended default; tus.io 1.0.0 and per-vendor SDK are the elicited alternatives",
+  "context": "There are three plausible upload transports for a shelf blueprint whose consumers range from a hobby SPA hitting a Node server to an enterprise SPA hitting Cloudflare R2. Native multipart POST is the least-surprising choice: every server toolkit and every fetch client can send it, the client side of the code is a Blob split into fixed-size chunks, and the server assembles the chunks server-side. The tus.io resumable upload protocol 1.0.0 (RFC-shaped spec) is the strongest choice for large files over spotty connections because it standardises Upload-Offset and Upload-Length headers and a PATCH-per-chunk shape that lets the client resume by re-reading the offset from the server; it needs a tus-server or the third-party tus client library. A per-vendor SDK (S3 multipart, Cloudflare R2 client-direct upload, Cloudinary widget, Uppy with a specific backend) buys the vendor's operational benefits (signed URLs, resumable multipart, CDN write-through) at the price of pinning the client to the vendor and the vendor's SDK release cycle.",
+  "decision": "Adopt multipart POST as the recommended default. Every applied blueprint gets multipart out of the box with no configuration. Projects with tus servers or the tus client library elicit the tus branch through this ADR and the transport TAC instantiates the tus adapter. Projects committed to a vendor (S3, R2, Cloudinary) elicit the vendor-sdk branch and supply the SDK client through the applied endpoint config; the transport TAC delegates chunking to the SDK. recommendedDefault is true; elicited is true because the branch is a per-project answer.",
+  "consequences": "Projects on the default get a working chunked-and-resumable upload against a plain server with no extra dependency. Projects that need tus wire it in via a small adapter and gain the protocol's cross-vendor portability. Projects on vendor SDKs delegate the wire-level details to the vendor and accept the vendor lock-in as an explicit choice. The pack fires on both the multipart branch and the tus branch of the sample fixture; a vendor-sdk project runs the pack against a fixture that mocks the vendor's completion callback.",
+  "alternativesConsidered": [
+    {
+      "name": "tus-only as the shelf default",
+      "summary": "Ship tus.io as the sole transport, on the theory that resumable-by-default is the correct posture.",
+      "reasonNotChosen": "Every applied blueprint would need a tus server, which is a hard prerequisite for a shelf blueprint; a hobby SPA hitting a Node server would refuse to apply without stand-up work. The default has to be reachable by every consumer."
+    },
+    {
+      "name": "Vendor-SDK-only",
+      "summary": "Ship an SDK-agnostic vendor adapter as the only transport, on the theory that most enterprise uploads eventually pin a vendor.",
+      "reasonNotChosen": "A vendor-first shelf pins the shelf to a vendor's SDK release cycle and breaks the vendor-neutral posture of every other application blueprint on the shelf."
+    }
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/adrs/adr-2402-application-file-upload-accepted-set.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2402-application-file-upload-accepted-set",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Accepted MIME set and per-file size cap are elicited per project; no shelf default beyond \"nothing accepted\"",
+  "context": "A shelf blueprint cannot know what a downstream project's upload endpoint accepts. A photo-gallery product accepts a narrow image set (jpeg, png, webp) with a 20 MB per-file cap; a document workspace accepts pdf, docx, txt with a 100 MB cap; a code-review product accepts a broad set with a 5 MB cap. Picking a default that fits all projects picks one that fits none. Shipping without any elicited values leaves the input TAC in a state where every file is refused (the safe default), which is the correct floor: a project that forgets to elicit the accepted set discovers this immediately on the first upload.",
+  "decision": "The accepted MIME set and the per-file size cap are elicited per project through this ADR. The blueprint contributes the two parameters as elicits on apply; the input TAC's MIME gate refuses every file until both are elicited. The elicited MIME set is a list of IANA media types; wildcards (image/*, application/*) are permitted for projects that want them but discouraged in the guide. The per-file size cap is a positive integer in bytes. A concurrency cap and the polling interval for the announcer are secondary elicits with recommended defaults (concurrency 3, interval 250 ms).",
+  "consequences": "Projects that apply the blueprint without elicitizing discover the refusal on the first upload attempt and go through the elicit flow to unblock it; the refusal is legible (\"MIME gate has no accepted set\") rather than silently accepting everything. Projects with a mature accepted-set list paste it in once and never revisit. The pack asserts the input TAC refuses an obvious wrong-MIME file (a text/plain payload with a jpeg extension) and refuses a payload exceeding the size cap.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship a broad default set (image/*, application/pdf, text/plain)",
+      "summary": "Adopt a shelf default that covers the most common cases so most projects can apply without elicitizing.",
+      "reasonNotChosen": "Any default that is broad enough to be useful is broad enough to be wrong for a project whose backend cannot accept the same set; the discovery cost of a mismatched accepted set at the server is higher than the discovery cost of the refuse-all floor at the client."
+    },
+    {
+      "name": "Ship no accepted-set gate at all",
+      "summary": "Rely on the server to refuse a wrong-MIME upload and skip the client-side gate.",
+      "reasonNotChosen": "The server refusal happens after the bytes are on the wire; a client that never gates wastes the operator's upload budget on payloads the server will refuse and loses the aria-describedby error binding the input TAC ships."
+    }
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/adrs/adr-2403-application-file-upload-virus-scan.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2403-application-file-upload-virus-scan",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Virus scan integration is a capability-plus-elicit; the operator supplies a verifier or the transport refuses the branch",
+  "context": "A file-upload surface that skips virus scanning ships a well-known attack path: a workspace with unmoderated attachments hands a payload from one user to any other user that opens the file. The right answer is server-side scanning against a vendor (ClamAV, VirusTotal, S3 GuardDuty malware protection) plus a client-side hook that refuses to hand a scan-hit file to the user for retry. But the vendor and the wire shape are project decisions: a healthcare product with a HIPAA data path uses a different scanner than a games product with an S3 bucket. The shelf cannot choose one.",
+  "decision": "Virus scan integration is a capability-plus-elicit: the blueprint contributes a virusScan capability the input TAC calls (an async predicate over a File that resolves to {clean: true} or {clean: false, reason: <string>}), and the applied capability is elicited per project. Projects with a virus scanner supply the verifier. Projects that explicitly opt out of virus scanning elicit the noop verifier and accept the risk (the guide names the risk in plain language). The pack asserts the input TAC's refusal path fires on a virus-scan hit and that the refused file never leaves the browser.",
+  "consequences": "Projects with a scanner apply the blueprint and paste in the verifier. Projects without one see the elicit and either wire in ClamAV/VirusTotal or accept the noop with the guide's warning in hand. The shelf posture is opinionated on the mechanism (a virus-scan hook exists and is called) but neutral on the vendor. A project that ignores the elicit and never supplies a verifier hits an apply-time refusal.",
+  "alternativesConsidered": [
+    {
+      "name": "Skip virus scanning at the shelf layer entirely",
+      "summary": "Leave scanning to the server and ship no client-side hook.",
+      "reasonNotChosen": "The server-side scanner cannot refuse the client's retry loop on a hit without an aria-describedby error binding; the client-side hook is what surfaces the refusal legibly."
+    },
+    {
+      "name": "Bundle ClamAV as the shelf default",
+      "summary": "Ship the ClamAV client bindings as the sole verifier.",
+      "reasonNotChosen": "Adds a vendor dependency to every applied project and pins the shelf to a scanner that many projects will not use; capability-plus-elicit keeps the shelf vendor-neutral."
+    }
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/requirements/application-file-upload-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-file-upload-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Input contract: a labelled file input plus a drop-zone plus a keyboard alternative per WCAG 2.5.7",
+  "description": "The upload surface renders a labelled native file input, a labelled drop-zone region for pointer users, and a keyboard-focusable alternative control that opens the picker on Enter or Space. Every input carries an accessible name via label association or aria-label. The three affordances share the same underlying file collector so a keyboard-only user, a pointer user with drag-drop and a screen-reader user reach the same state. Per WCAG 2.5.7 Dragging Movements, the drop-zone is never the only way to add a file; a click and keyboard path both satisfy the same acceptance criterion.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.2, REQ 1.",
+  "tags": [
+    "blueprint:application-file-upload",
+    "category:01-input-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}