rcf-lite 0.20.0 → 0.22.0

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"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-file-upload-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Progress contract: per-file percent, aggregate percent, and a polite live-region tick",
+  "description": "Every file in the upload set carries a per-file percent that advances monotonically from 0 to 100. The surface also carries an aggregate percent that reflects the mean weighted by byte size. A polite live-region wrapper (aria-live polite) receives a text tick at least every 10 percent of aggregate progress with the string format \"<uploaded> of <total> files, <PP> percent\". The polite wrapper is preseeded at render time so a screen reader adopts it before the first tick fires.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.2, REQ 2.",
+  "tags": [
+    "blueprint:application-file-upload",
+    "category:02-progress-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-file-upload-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Refusal contract: MIME-type, size-limit and virus-scan refusals with an aria-describedby error binding and focus-to-retry",
+  "description": "The upload surface refuses a file that fails the MIME-type gate, exceeds the per-file size cap, or matches the virus-scan hit. Every refusal renders a per-file error message inside a region bound to the file row via aria-describedby, moves keyboard focus to the row's retry control, and refuses to send the file to the server. The refusal reason is one of the closed strings mime-refused, size-refused, virus-refused so a project's log pipeline can classify without prose parsing.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.2, REQ 3.",
+  "tags": [
+    "blueprint:application-file-upload",
+    "category:03-refusal-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-file-upload-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Transport contract: chunked-and-resumable, multipart POST default, tus.io elicited alternative",
+  "description": "The upload transport is chunked-and-resumable: an interrupted upload resumes from the last acknowledged offset on retry, and the client retries on transient failures without re-sending acknowledged bytes. The recommended default is a multipart POST with the file split into fixed-size chunks the server assembles server-side. The tus.io resumable upload protocol 1.0.0 is the elicited alternative for projects with a tus server or the third-party SDK; when applied it exposes an Upload-Offset header per PATCH request and supports server-side pause and resume. A per-vendor SDK (S3 multipart, Cloudflare R2 client-direct) is the second elicited alternative when the project has committed to a vendor library.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.2, REQ 4.",
+  "tags": [
+    "blueprint:application-file-upload",
+    "category:04-transport-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-file-upload-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Completion contract: assertive-slot success announcement per WCAG 4.1.3 plus per-file remove and retry",
+  "description": "On successful completion of the upload set, the surface renders an assertive-slot announcement in a wrapper carrying role=status or aria-live=assertive with the string \"<N> files uploaded successfully\", per WCAG 4.1.3 Status Messages. Every completed file row carries a keyboard-reachable remove control (returns the row to the pre-upload state and issues a DELETE against the transport where the transport supports removal) and a retry control (visible only after a refusal or a transport error). The completion announcement fires exactly once per set; a retried refusal that then succeeds increments the completed count but does not re-announce.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec section 5.2, REQ 5.",
+  "tags": [
+    "blueprint:application-file-upload",
+    "category:05-completion-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/tacs/tac-2401-application-file-upload-input.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-2401-application-file-upload-input",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Upload input surface",
+  "purpose": "Owns the input-side surface of the file-upload contract: the labelled file input, the drop-zone region, the keyboard-focusable picker-opener, the accessible-name binding, the file-collector aggregating the three input paths into one selection set, and the refusal-render seam. Every AC on REQ-001 and REQ-003 that reads the surface anchors on this TAC.",
+  "responsibilities": [
+    "Render a labelled <input type=\"file\"> with a keyboard-reachable label and an accessible name (AC-23101-1).",
+    "Render a [data-drop-zone] region that accepts dropped files but is never the only input path (WCAG 2.5.7).",
+    "Render a [data-open-picker] button that opens the same picker on Enter or Space (AC-23101-1).",
+    "Aggregate the three input paths into one file-selection set the transport TAC drains (AC-23101-1).",
+    "Render a per-file error region with an aria-describedby binding and a [data-recovery=\"retry\"] control on refusal, and hand refused files to the transport TAC's refusal-render seam so no bytes leave the browser (AC-23103-1)."
+  ],
+  "internalStructure": "One input-surface module the shell mounts on route entry. On file addition the module normalises the three input paths (input change, drop event, picker-opener button) into a File[] selection set, tags each entry with a stable [data-file-row] id, runs the accepted-set gates (MIME per ADR-2402, size per ADR-2402) and the virus-scan hook per ADR-2403 before handing the set to the transport TAC. Refusal renders inside the file row with a [data-error-message] element whose id is referenced by the row's aria-describedby attribute; the closed refusal-reason enum {mime-refused, size-refused, virus-refused} rides [data-refusal-reason].",
+  "interfaces": [
+    {
+      "name": "collectFiles",
+      "kind": "factory",
+      "description": "collectFiles({ inputEvent | dropEvent | pickerClick }) -> FileSelection. Every input path routes through this factory."
+    },
+    {
+      "name": "renderRefusal",
+      "kind": "factory",
+      "description": "renderRefusal({ fileRow, reason }) -> void. Binds the error region to the row via aria-describedby, sets [data-refusal-reason], focuses the [data-recovery=\"retry\"] control."
+    },
+    {
+      "name": "affordancesEnum",
+      "kind": "shape",
+      "description": "The three input affordances (input, drop-zone, keyboard-opener) are the closed enum {file-input, drop-zone, keyboard-opener}. Removing one is a v2.0.0 major bump."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Transport contract",
+      "kind": "tac",
+      "tacId": "TAC-2402-application-file-upload-transport",
+      "description": "The input surface hands accepted files to the transport TAC and honours its refusal-render seam on virus-scan hits."
+    }
+  ],
+  "tradeoffs": "One input-surface module keeps the WCAG 2.5.7 discipline lint-checkable but ties every framework to the collectFiles factory. Projects using a vendor upload widget (Filepond, Uppy) satisfy the surface by adapting the vendor's mount seam to the TAC's factories rather than rewriting the collector. Known mechanism-reach gap: the pack cannot exhaustively probe every drop-target inside a nested drop-zone; the primary drop-zone attribute is asserted.",
+  "notes": "See README Known mechanism-reach gaps for the full list.",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/tacs/tac-2402-application-file-upload-transport.json

@@ -0,0 +1,47 @@
+{
+  "tacId": "TAC-2402-application-file-upload-transport",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Upload transport contract",
+  "purpose": "Owns the wire-level side of the file-upload contract: chunking, resumption, the multipart POST default, the tus.io elicited alternative, the refusal-render seam, and the completion callback. Every AC on REQ-004 that reads the request log anchors on this TAC.",
+  "responsibilities": [
+    "Split each accepted file into fixed-size chunks and upload chunks in bounded parallelism (default 3) (AC-23104-1).",
+    "On the multipart branch, POST the chunk set to the applied endpoint and assemble server-side; expose [data-transport=\"multipart\"] and [data-chunks-uploaded] on the file row (AC-23104-1).",
+    "On the tus branch, PATCH chunks to the tus creation URL with an Upload-Offset header per request; expose [data-transport=\"tus\"] (AC-23104-1).",
+    "On interruption, pause the upload and resume from the last acknowledged offset on reconnect, without re-sending acknowledged bytes (AC-23106-1).",
+    "Refuse to enqueue a refused file (mime, size, virus-scan) and hand control back to TAC-2401's refusal-render seam (AC-23103-1).",
+    "Call the progress-announcer TAC with per-chunk acknowledgements so the per-file and aggregate percent advance (AC-23102-1)."
+  ],
+  "internalStructure": "One transport module the input TAC drains. The module reads the applied ADR-2401 branch (multipart, tus, per-vendor SDK) and instantiates one of three adapter shapes. Each adapter drains the file-selection set through a bounded worker pool (concurrency default 3, elicited cap), tracks per-file [data-chunks-uploaded], and posts an acknowledgement event on every server acknowledgement the progress-announcer TAC reads. Interruption is detected via fetch reject (multipart) or the tus client's onError seam (tus); resumption re-fetches the Upload-Offset (tus) or resumes from the last completed chunk index (multipart). The refusal-render seam is a thin wrapper the input TAC calls, not a separate class, so the input surface stays authoritative.",
+  "interfaces": [
+    {
+      "name": "uploadFile",
+      "kind": "factory",
+      "description": "uploadFile({ file, endpoint, transport }) -> UploadSession. Returns a session the caller reads for per-chunk progress and completion."
+    },
+    {
+      "name": "resumeSession",
+      "kind": "factory",
+      "description": "resumeSession(session) -> UploadSession. Resumes from the last acknowledged offset."
+    },
+    {
+      "name": "transportsEnum",
+      "kind": "shape",
+      "description": "The transport branches are the closed enum {multipart, tus, vendor-sdk}. multipart is the recommended default per ADR-2401."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Progress announcer",
+      "kind": "tac",
+      "tacId": "TAC-2403-application-file-upload-progress-announcer",
+      "description": "The transport calls the announcer's tick on every acknowledged chunk."
+    }
+  ],
+  "tradeoffs": "Three transport branches keep the shelf usable for teams already committed to a vendor SDK, but the per-branch adapter code is real work; a project that never elicits tus or a vendor SDK ships with the multipart adapter only. Bounded parallelism (default 3) is a heuristic; a slow-link project can lower it via the applied endpoint config. Known mechanism-reach gap: the pack cannot probe a network-interruption resume path on the multipart branch without a request-blocking driver; the fixture simulates the pause via a ?interrupt=1 branch and the pack reads the resulting DOM state.",
+  "notes": "See README Known mechanism-reach gaps for the full list.",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/tacs/tac-2403-application-file-upload-progress-announcer.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-2403-application-file-upload-progress-announcer",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Upload progress announcer",
+  "purpose": "Owns the announcement side of the file-upload contract: the polite live-region wrapper the transport ticks, the aggregate-percent calculator, the assertive-slot completion announcement, and the background-tab tick continuity. Every AC on REQ-002 and REQ-005 that reads the aria-live regions anchors on this TAC.",
+  "responsibilities": [
+    "Mount the polite live-region wrapper at render time so a screen reader adopts it before the first tick (AC-23102-1).",
+    "Emit a polite text tick every 10 percent of aggregate progress in the closed format \"<uploaded> of <total> files, <PP> percent\" (AC-23102-1).",
+    "Compute the aggregate percent as the mean weighted by byte size across the active file set (AC-23102-1).",
+    "On completion of the set, mount an assertive-slot announcement (aria-live=\"assertive\" or role=\"status\") with the closed text \"<N> files uploaded successfully\", exactly once per set (AC-23105-1).",
+    "Continue ticking under document visibilitychange to hidden so a backgrounded tab does not stall the announcement (AC-23107-1)."
+  ],
+  "internalStructure": "One announcer module the transport hooks. The module preseeds the polite wrapper (aria-live polite) on mount, reads per-chunk acknowledgements from the transport, updates a per-file percent + aggregate percent record, and pushes a text tick every time the floor(aggregate/10) integer changes. Completion detection is a single flag; the assertive slot is mounted on mount as an empty wrapper and its textContent is set exactly once per set. Background-tab continuity is achieved by using setInterval on the ack polling loop rather than requestAnimationFrame; the interval keeps firing when the tab is hidden. A project that wants to pause on hidden explicitly elicits the alternative.",
+  "interfaces": [
+    {
+      "name": "tick",
+      "kind": "factory",
+      "description": "tick({ fileRowId, bytesAcknowledged, totalBytes }) -> void. Transport calls this on every acknowledgement."
+    },
+    {
+      "name": "complete",
+      "kind": "factory",
+      "description": "complete({ successCount }) -> void. Transport calls this exactly once per set."
+    },
+    {
+      "name": "announcementFormatsEnum",
+      "kind": "shape",
+      "description": "The polite format is fixed: /^\\d+ of \\d+ files, \\d{1,3} percent$/; the assertive format is fixed: /^\\d+ files uploaded successfully$/. Localisation is a v1.1.0 minor bump extending the enum with a lookup table."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Transport contract",
+      "kind": "tac",
+      "tacId": "TAC-2402-application-file-upload-transport",
+      "description": "The announcer reads per-chunk acknowledgements from the transport."
+    }
+  ],
+  "tradeoffs": "One announcer module keeps the aria-live discipline testable but pins the wire format in English at v1.0.0; a localised project elicits the format table in a v1.1.0 minor. Known mechanism-reach gap: the pack asserts the polite wrapper's textContent format but does not additionally probe screen-reader adoption (that requires a real assistive tech in the loop).",
+  "notes": "See README Known mechanism-reach gaps for the full list.",
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/user-stories/application-file-upload-us-23101.json

@@ -0,0 +1,28 @@
+{
+  "usId": "application-file-upload-US-23101",
+  "prdId": "PRD-001",
+  "reqId": "application-file-upload-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The upload surface renders a labelled file input, a drop-zone region and a keyboard-focusable alternative that opens the picker on Enter",
+  "asA": "operator selecting files to upload, whether by pointer, drag-drop or keyboard alone",
+  "iWant": "a labelled native file input, a drop-zone region and a keyboard-focusable button that opens the picker so I can add files from whichever input mode I use",
+  "soThat": "I never have to drag to add a file and my screen reader announces the picker rather than a silent drop-zone",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-23101-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "The upload region carries [data-surface=\"file-upload\"] and inside it: a labelled <input type=\"file\"> with a keyboard-reachable label (an id-referenced <label> or an aria-label), a [data-drop-zone] region, and a keyboard-focusable [data-open-picker] button that opens the same picker on Enter or Space. The pack drives the real browser to /upload, asserts the three affordances are present, focuses the [data-open-picker] control and presses Enter, then reads that the file input received focus."
+    }
+  ],
+  "tacIds": [
+    "TAC-2401-application-file-upload-input"
+  ],
+  "tags": [
+    "blueprint:application-file-upload",
+    "affordance:input-plus-drop-plus-keyboard"
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}

package/blueprints/application-file-upload/contributions/user-stories/application-file-upload-us-23102.json

@@ -0,0 +1,28 @@
+{
+  "usId": "application-file-upload-US-23102",
+  "prdId": "PRD-001",
+  "reqId": "application-file-upload-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The progress announcer emits per-file and aggregate progress through a polite live-region wrapper",
+  "asA": "operator watching an upload progress on a screen reader or a low-vision magnifier",
+  "iWant": "a polite live-region tick every 10 percent of aggregate progress that names how many files have completed out of how many",
+  "soThat": "I know the upload is still working without watching the screen and I can tell when it stalls",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-23102-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "The upload region ships a [data-live-region=\"polite\"] wrapper with aria-live=\"polite\" preseeded at render time. During an upload the wrapper's textContent matches /^\\d+ of \\d+ files, \\d{1,3} percent$/ and the numeric aggregate percent advances monotonically. Per-file rows carry [data-file-row] with a [data-file-progress] element whose text or aria-valuenow reflects the per-file percent. The pack drives /upload?transport=multipart, starts the upload, and reads the wrapper text plus one per-file progress value before completion."
+    }
+  ],
+  "tacIds": [
+    "TAC-2403-application-file-upload-progress-announcer"
+  ],
+  "tags": [
+    "blueprint:application-file-upload",
+    "affordance:polite-progress"
+  ],
+  "createdAt": "2026-09-06T16:55:00Z",
+  "updatedAt": "2026-09-06T16:55:00Z"
+}