rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-onboarding-tour/probe-packs/application-onboarding-tour.pack.mjs

@@ -0,0 +1,231 @@
+// application-onboarding-tour probe pack (v1.0.0).
+//
+// Four surface-observable checks anchored to the blueprint AC ids:
+//   AC-26101-1 step-container focus lifecycle and Escape (drives the tour open,
+//              asserts the first step renders, walks Tab through the tour
+//              controls, presses Escape, asserts dismissal)
+//   AC-26102-1 tooltip-as-dialog contract (opens a step, reads the DOM, asserts
+//              role="dialog" and aria-labelledby; asserts focus moves to the
+//              tooltip on open; asserts focus is not obscured at breakpoints
+//              1440 and 360 via the browser.resize seam)
+//   AC-26103-1 checklist slot (asserts the checklist renders inside <details open>
+//              on the dashboard-top anchor when application-dashboard is applied
+//              and inside a <details> closed on the settings-page anchor when not)
+//   AC-26104-1 completion-state persistence (completes the tour, reads the
+//              completion-state store per the elicited shape, activates restart
+//              from the settings surface, asserts the tour re-opens)
+//
+// Every check drives the real Playwright browser the T-0 runner injects and
+// reads its per-check applicability from the blueprint applied sidecar
+// (rcf/blueprints/application-onboarding-tour.applied.json) written by the apply
+// verb. T-5 has no requiresAppliedCapabilities, but the checklist-slot check
+// gates its dashboard-vs-settings branch on the applied-blueprint set
+// (application-dashboard present or not), and the persistence check gates its
+// backend on the elicited completion-state-store answer (with the Q4 fallback
+// spa-local-storage when no persistence blueprint is applied).
+//
+// Sample-app fixture: packages/rcf-lite/test/fixtures/probe-pack-application-onboarding-tour/.
+// The fixture ships APPS and STORE env / ?apps= / ?store= query switches
+// mirroring the applied-blueprint set and the elicited completion-state store,
+// plus four break switches (?break=no-role, ?break=focus-escape,
+// ?break=no-collapse, ?break=no-persist) driving the negative runs.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function readAppliedSidecar(projectRoot) {
+  if (!projectRoot) return { appliedCapabilities: [], appliedElicitations: {}, appliedBlueprints: [] };
+  try {
+    const raw = await readFile(join(projectRoot, 'rcf', 'blueprints', 'application-onboarding-tour.applied.json'), 'utf8');
+    const doc = JSON.parse(raw);
+    return {
+      appliedCapabilities: Array.isArray(doc.appliedCapabilities) ? doc.appliedCapabilities.slice() : [],
+      appliedElicitations: typeof doc.appliedElicitations === 'object' && doc.appliedElicitations ? doc.appliedElicitations : {},
+      appliedBlueprints: Array.isArray(doc.appliedBlueprints) ? doc.appliedBlueprints.slice() : [],
+    };
+  } catch {
+    return { appliedCapabilities: [], appliedElicitations: {}, appliedBlueprints: [] };
+  }
+}
+
+function withUrl(runtimeUrl, path) {
+  return new URL(path, runtimeUrl).toString();
+}
+
+function appsQuery(sidecar) {
+  // The sidecar's appliedBlueprints[] is the truth; on a fixture where the
+  // sidecar is absent (a bare test run) the fixture defaults route through
+  // the ?apps= query so the check still runs against the honest branch.
+  return sidecar.appliedBlueprints.join(',');
+}
+
+export default {
+  packName: 'application-onboarding-tour',
+  version: '1.0.0',
+  blueprintSlug: 'application-onboarding-tour',
+  // Applies to any FBS that realises the step-runner TAC or whose navModel
+  // routes match the operator-configured tour-anchor path glob (any /tour,
+  // /welcome, /getting-started, /onboarding path is a legal anchor).
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2701-application-onboarding-tour-step-runner')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /\/(tour|welcome|getting-started|onboarding)(\/|$)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-26101-1',
+      severity: 'block',
+      description: 'Step-container focus lifecycle: the tour opens the first step on a first-run principal, Tab reaches every tour control inside the tooltip in DOM order without escaping to the underlying surface, and Escape dismisses the tour and returns focus to the anchor (WCAG 2.1.1 Keyboard, 2.1.2 No Keyboard Trap, 2.4.3 Focus Order)',
+      appliesTo: async () => true,
+      run: async ({ browser, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const sidecar = await readAppliedSidecar(projectRoot);
+        const apps = appsQuery(sidecar);
+        await browser.goto(withUrl(runtimeUrl, `/tour?first-run=1&apps=${encodeURIComponent(apps)}`));
+        const open = await browser.evaluate(() => {
+          const tip = document.querySelector('[data-role="onboarding-tour-tooltip"]');
+          if (!tip) return { present: false };
+          const role = tip.getAttribute('role');
+          const step = tip.getAttribute('data-step-id');
+          const controls = Array.from(tip.querySelectorAll('[data-tour-control]')).map((c) => c.getAttribute('data-tour-control'));
+          const focusInside = tip.contains(document.activeElement);
+          return { present: true, role, step, controls, focusInside };
+        });
+        if (!open.present) return { verdict: 'fail', detail: 'onboarding tooltip [data-role="onboarding-tour-tooltip"] not rendered on first run' };
+        if (open.role !== 'dialog') return { verdict: 'fail', detail: `tooltip role expected dialog, got ${open.role}` };
+        if (!open.focusInside) return { verdict: 'fail', detail: 'focus did not move into the tooltip on open' };
+        const requiredControls = ['previous', 'next', 'dismiss'];
+        const missingControls = requiredControls.filter((c) => !open.controls.includes(c));
+        if (missingControls.length > 0) return { verdict: 'fail', detail: `tooltip missing tour controls: ${JSON.stringify(missingControls)} present=${JSON.stringify(open.controls)}` };
+        // Walk Tab across every control; refuse if focus escapes the tooltip.
+        for (let i = 0; i < open.controls.length + 1; i += 1) {
+          await browser.press('Tab');
+        }
+        const walk = await browser.evaluate(() => {
+          const tip = document.querySelector('[data-role="onboarding-tour-tooltip"]');
+          return { focusInside: tip ? tip.contains(document.activeElement) : false };
+        });
+        if (!walk.focusInside) return { verdict: 'fail', detail: 'Tab traversal escaped the tooltip (focus trap failed)' };
+        await browser.press('Escape');
+        const closed = await browser.evaluate(() => {
+          const tip = document.querySelector('[data-role="onboarding-tour-tooltip"]');
+          return { present: !!tip };
+        });
+        if (closed.present) return { verdict: 'fail', detail: 'tooltip still present after Escape (dismiss did not fire)' };
+        return { verdict: 'pass', detail: `step=${open.step} controls=${JSON.stringify(open.controls)} focus trapped and Escape dismissed cleanly` };
+      },
+    },
+    {
+      id: 'AC-26102-1',
+      severity: 'block',
+      description: 'Tooltip-as-dialog contract per the ARIA APG dialog-modal pattern: role="dialog", aria-labelledby to the step heading, aria-describedby to the step body, focus moves in on open, focus not obscured at the 1440 wide and 360 narrow breakpoints (WCAG 2.4.11 Focus Not Obscured Minimum)',
+      appliesTo: async () => true,
+      run: async ({ browser, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const sidecar = await readAppliedSidecar(projectRoot);
+        const apps = appsQuery(sidecar);
+        // Wide breakpoint first.
+        await browser.resize(1440, 900);
+        await browser.goto(withUrl(runtimeUrl, `/tour?first-run=1&apps=${encodeURIComponent(apps)}`));
+        const wide = await browser.evaluate(() => {
+          const tip = document.querySelector('[data-role="onboarding-tour-tooltip"]');
+          if (!tip) return { present: false };
+          const headingId = tip.getAttribute('aria-labelledby');
+          const bodyId = tip.getAttribute('aria-describedby');
+          const headingEl = headingId ? document.getElementById(headingId) : null;
+          const bodyEl = bodyId ? document.getElementById(bodyId) : null;
+          const rect = tip.getBoundingClientRect();
+          const inViewport = rect.top >= 0 && rect.left >= 0 && rect.bottom <= window.innerHeight && rect.right <= window.innerWidth;
+          return { present: true, role: tip.getAttribute('role'), headingId, bodyId, headingText: headingEl ? headingEl.textContent : null, bodyText: bodyEl ? bodyEl.textContent : null, inViewport, rect: { top: rect.top, left: rect.left, right: rect.right, bottom: rect.bottom }, viewport: { w: window.innerWidth, h: window.innerHeight } };
+        });
+        if (!wide.present) return { verdict: 'fail', detail: 'tooltip not rendered at 1440x900' };
+        if (wide.role !== 'dialog') return { verdict: 'fail', detail: `tooltip role expected dialog at 1440, got ${wide.role}` };
+        if (!wide.headingId || !wide.headingText) return { verdict: 'fail', detail: `tooltip aria-labelledby ("${wide.headingId}") does not point at a live heading element` };
+        if (!wide.bodyId || !wide.bodyText) return { verdict: 'fail', detail: `tooltip aria-describedby ("${wide.bodyId}") does not point at a live body element` };
+        if (!wide.inViewport) return { verdict: 'fail', detail: `tooltip focus obscured at 1440x900: rect=${JSON.stringify(wide.rect)} viewport=${JSON.stringify(wide.viewport)}` };
+        // Narrow breakpoint.
+        await browser.resize(360, 640);
+        await browser.goto(withUrl(runtimeUrl, `/tour?first-run=1&apps=${encodeURIComponent(apps)}`));
+        const narrow = await browser.evaluate(() => {
+          const tip = document.querySelector('[data-role="onboarding-tour-tooltip"]');
+          if (!tip) return { present: false };
+          const rect = tip.getBoundingClientRect();
+          const inViewport = rect.top >= 0 && rect.left >= 0 && rect.bottom <= window.innerHeight && rect.right <= window.innerWidth;
+          return { present: true, rect: { top: rect.top, left: rect.left, right: rect.right, bottom: rect.bottom }, viewport: { w: window.innerWidth, h: window.innerHeight }, inViewport };
+        });
+        if (!narrow.present) return { verdict: 'fail', detail: 'tooltip not rendered at 360x640' };
+        if (!narrow.inViewport) return { verdict: 'fail', detail: `tooltip focus obscured at 360x640: rect=${JSON.stringify(narrow.rect)} viewport=${JSON.stringify(narrow.viewport)}` };
+        return { verdict: 'pass', detail: `dialog contract clean at 1440 and 360; aria-labelledby="${wide.headingId}" aria-describedby="${wide.bodyId}"` };
+      },
+    },
+    {
+      id: 'AC-26103-1',
+      severity: 'block',
+      description: 'Checklist slot: renders inside <details open> on the dashboard-top anchor when application-dashboard is applied, and inside <details> (closed) on the settings-page anchor when not; both branches carry data-role="onboarding-tour-checklist"',
+      appliesTo: async () => true,
+      run: async ({ browser, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const sidecar = await readAppliedSidecar(projectRoot);
+        const apps = appsQuery(sidecar);
+        const dashboardApplied = sidecar.appliedBlueprints.includes('application-dashboard');
+        const targetPath = dashboardApplied ? '/dashboard' : '/settings';
+        await browser.goto(withUrl(runtimeUrl, `${targetPath}?apps=${encodeURIComponent(apps)}`));
+        const dom = await browser.evaluate((expectedAnchor) => {
+          const checklist = document.querySelector('details[data-role="onboarding-tour-checklist"]');
+          if (!checklist) return { present: false };
+          const isOpen = checklist.hasAttribute('open');
+          const anchor = checklist.getAttribute('data-anchor');
+          const items = Array.from(checklist.querySelectorAll('[data-checklist-item]')).map((el) => el.getAttribute('data-checklist-item'));
+          return { present: true, isOpen, anchor, items, expectedAnchor };
+        }, dashboardApplied ? 'dashboard-top' : 'settings-page');
+        if (!dom.present) return { verdict: 'fail', detail: `details[data-role="onboarding-tour-checklist"] not found at ${targetPath} (apps=${apps})` };
+        if (dashboardApplied && !dom.isOpen) return { verdict: 'fail', detail: `checklist on dashboard-top anchor is not <details open> (anchor="${dom.anchor}")` };
+        if (!dashboardApplied && dom.isOpen) return { verdict: 'fail', detail: `checklist on settings-page anchor rendered <details open> but should default closed (anchor="${dom.anchor}")` };
+        if (dom.anchor !== dom.expectedAnchor) return { verdict: 'fail', detail: `data-anchor expected "${dom.expectedAnchor}", got "${dom.anchor}"` };
+        return { verdict: 'pass', detail: `anchor=${dom.anchor} open=${dom.isOpen} items=${JSON.stringify(dom.items)} (dashboardApplied=${dashboardApplied})` };
+      },
+    },
+    {
+      id: 'AC-26104-1',
+      severity: 'block',
+      description: 'Completion-state persistence: completing the tour writes to the elicited completion-state store (spa-local-storage per the Q4 fallback when no persistence blueprint is applied; spa-session-storage or server-side-per-principal per the elicit); the restart-tour control on the settings surface clears the record and re-opens the tour on the next principal load',
+      appliesTo: async () => true,
+      run: async ({ browser, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const sidecar = await readAppliedSidecar(projectRoot);
+        const apps = appsQuery(sidecar);
+        const store = sidecar.appliedElicitations['completion-state-store'] || 'spa-local-storage';
+        await browser.goto(withUrl(runtimeUrl, `/tour?first-run=1&apps=${encodeURIComponent(apps)}&store=${encodeURIComponent(store)}&complete=1`));
+        const afterComplete = await browser.evaluate((s) => {
+          const marker = document.querySelector('[data-role="onboarding-tour-completion-marker"]');
+          const writtenAttr = marker ? marker.getAttribute('data-written-to') : null;
+          const key = 'onboarding-tour:completion';
+          let readBack = null;
+          try {
+            if (s === 'spa-local-storage') readBack = window.localStorage.getItem(key);
+            else if (s === 'spa-session-storage') readBack = window.sessionStorage.getItem(key);
+          } catch (e) {
+            readBack = `storage-error: ${e.message}`;
+          }
+          return { markerPresent: !!marker, writtenAttr, readBack };
+        }, store);
+        if (!afterComplete.markerPresent) return { verdict: 'fail', detail: `completion marker [data-role="onboarding-tour-completion-marker"] not present after complete flow (store=${store})` };
+        if (afterComplete.writtenAttr !== store) return { verdict: 'fail', detail: `completion marker data-written-to expected "${store}", got "${afterComplete.writtenAttr}"` };
+        if ((store === 'spa-local-storage' || store === 'spa-session-storage') && !afterComplete.readBack) {
+          return { verdict: 'fail', detail: `store "${store}" reports no persisted record under key onboarding-tour:completion` };
+        }
+        // Drive the restart control.
+        await browser.goto(withUrl(runtimeUrl, `/settings?apps=${encodeURIComponent(apps)}&store=${encodeURIComponent(store)}`));
+        const restartBtn = await browser.evaluate(() => !!document.querySelector('button[data-action="restart-tour"]'));
+        if (!restartBtn) return { verdict: 'fail', detail: 'restart-tour control not reachable on settings surface' };
+        await browser.click('button[data-action="restart-tour"]');
+        await browser.goto(withUrl(runtimeUrl, `/tour?apps=${encodeURIComponent(apps)}&store=${encodeURIComponent(store)}`));
+        const reopen = await browser.evaluate(() => !!document.querySelector('[data-role="onboarding-tour-tooltip"]'));
+        if (!reopen) return { verdict: 'fail', detail: 'tour did not re-open on the highest-value surface after restart' };
+        return { verdict: 'pass', detail: `store=${store} completion persisted, restart cleared, tour re-opened` };
+      },
+    },
+  ],
+};

package/blueprints/application-spa/docs/topics.md

@@ -34,7 +34,7 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
 | observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
-| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
 | security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
 | security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
 | security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
@@ -43,6 +43,18 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
 | observability-logging | 15101-15899 | 16xx | shipped v1.0.0 | `logging` |
 | application-error-handling | 16101-16899 | 17xx | shipped v1.0.0 | `errorHandling` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| 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` |
 
 SPA v1.1.0 stays on the LOW end of its band: v1.0.0 occupied US-1101 through US-1128; v1.1.0 adds US-1129 and US-1130, leaving headroom above 1130 for future minor bumps and for project-side stories that mechanically derive to the 11xx numeric range.
 

package/blueprints/delivery-ci-workflows/docs/topics.md

@@ -42,13 +42,25 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
 | observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
-| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
 | security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
 | security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
 | security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
 | deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| 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` |
 
 US 6101-6110 sit at the LOW end of the 6101-6899 band on purpose. A project-side story that mechanically derives from `delivery-ci-workflows-REQ-011` into the number `6111` would collide against delivery-ci-workflows-US-6111 in this package; the band leaves headroom at the HIGH end (US 6181-6899) so a project's own stories anchored to delivery-ci-workflows REQs can allocate without conflict. The watchpost run4 lesson applies here too.
 

package/blueprints/deploy-cloudflare-workers/docs/topics.md

@@ -28,13 +28,25 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
 | observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
-| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
 | security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
 | security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
 | security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
 | deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| 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` |
 
 US 12101-12112 sit at the LOW end of the 12101-12899 band on purpose. A project-side story that mechanically derives from a deploy-cloudflare-workers REQ id into the number `12112` would collide against deploy-cloudflare-workers-US-12112 in this package; the band leaves headroom at the HIGH end (US 12181-12899) so a project's own stories anchored to deploy-cloudflare-workers REQs can allocate without conflict. The watchpost run4 lesson applies here too. Band spacing between the last shipped block (security-secrets-management, 8101-8899, 9xx) and this one (12101-12899, 13xx) leaves the 9xxx-11xxx US bands and the 10xx-12xx suffix blocks open for concurrent-lane authoring so a peer authoring another blueprint in the same PR window does not collide with this one.
 

package/blueprints/email-smtp-resend/docs/topics.md

@@ -24,13 +24,25 @@ This table is maintained shelf-wide across every blueprint's `docs/topics.md`. R
 | persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
 | observability-essentials | 7101-7899 | 8xx | shipped v2.0.0 | `statusPageContract` |
-| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.1 | `secretsSource` |
 | security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
 | security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
 | security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
 | deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
 | persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
 | observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.1.0 | `healthProbes`, `readinessSemantics` |
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| 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` |
 
 US 4101-4106 sit at the LOW end of the 4101-4899 band on purpose. A project-side story that mechanically derives from an email-smtp-resend REQ id into the number `4106` (leading `4` + sequence `106`) would collide against email-smtp-resend-US-4106 in this package; the band leaves headroom at the HIGH end (US 4181-4899) so a project's own stories anchored to email-smtp-resend REQs can allocate without conflict. The watchpost run4 lesson applies here too.
 

package/blueprints/object-storage-s3/CHANGELOG.md

@@ -0,0 +1,13 @@
+# object-storage-s3 changelog
+
+## 1.0.0 - 2026-09-06
+
+Initial release. Contract for S3-shape object storage on any S3-compatible endpoint (Cloudflare R2 first, MinIO for local dev, AWS S3, Backblaze B2, Wasabi, self-hosted). Accessed through a store facade that is the sole reader of the S3 client (`@aws-sdk/client-s3` on Node targets or `aws4fetch` on Workers targets). Landed via the infra round 5 spec (ratified 2026-09-06) as track T-2.
+
+- 21 contributions: 6 REQs on facade sole-reader / put-get-delete-list / presigned URL / multipart / lifecycle events / credential-pair discipline; 8 USs at 28101-28108; 3 TACs (2901 facade, 2902 multipart uploader, 2903 event sink); 4 ADRs (2901 adapter elicited between AWS SDK and aws4fetch, 2902 presigned TTL default 15 minutes floor 1 minute, 2903 multipart threshold default 8 MiB, 2904 objectStorageContract with scope global).
+- Six Node-only probes under `contributions/probes/` proven against a live MinIO container: `facade-round-trip`, `put-get-round-trip`, `presigned-url`, `multipart-upload`, `event-secrecy`, and the accountBound `r2-real-account-smoke`. The R2 smoke records `accountBoundSkipped: true` when `CI_HAS_CLOUDFLARE_ACCOUNT` is unset per spec section 3.5.
+- T-2 slice of the shared sample-app fixture at `packages/rcf-lite/test/fixtures/infra-s3-and-queue/` boots MinIO via docker compose, exposes the facade over `@aws-sdk/client-s3`, ships a security-secrets-management shim realising the `secretRef` opaque-string contract, and hosts four wired induced-failure switches for the negative-run paths (SIMULATE_MINIO_DOWN, SIMULATE_403_ON_GET, SIMULATE_PART_UPLOAD_FAIL, SIMULATE_PRESIGN_MALFORMED).
+- Declares `capabilities: ["objectStorage"]`, `suggestedCompanions: [{role: "logging"}, {role: "errorHandling"}]`, `providesRoles` absent, `requiresAppliedCapabilities` absent.
+- Contributes ADR-2904 as `scope: global` on new topic `objectStorageContract`. Future non-S3-shape siblings (`object-storage-native-gcs`, `object-storage-native-azure`, reserved slugs) conflict here by design.
+- Refuses composition when `security-secrets-management` v1.0.1+ is not applied. Declares `requiresAppliedCapabilities: {capabilities: ["secretsProvider"], allowSkipFlag: "allow-no-secrets-yet", refusalMessageId: "object-storage-s3-no-secrets"}` per the T-5 capability mechanism. `rcf define blueprint add object-storage-s3` on a bare project exits 3 with `[object-storage-s3-no-secrets]` on stderr, names the shipped predecessor, and points at the override. `--allow-no-secrets-yet` records a `notes` line on `rcf/blueprints/object-storage-s3.applied.json` for later reconciliation. Companion runner extensions (added by this PR to keep the mechanism whole): `src/blueprint/capabilities.js` `buildRefusalMessage` gains a bespoke template branch for `object-storage-s3-no-secrets` (echoes the message id as the first-line tag; other refusalMessageId values also gain a `[<id>]` tag on the first line of the generic fallback for dashboards/lint); `src/cli/blueprint.js` accepts the new `--allow-no-secrets-yet` flag; `src/blueprint/apply.js` sidecar `notes` prose derives predecessor family from the `allowSkipFlag` name (auth vs secrets-management) so the note reads sensibly for either predecessor.
+- Every ADR contribution entry on `blueprint.json` carries a `standardsTraceClause` per section 8a.2 (per HQ mid-flight ruling after PR #154 gate).

package/blueprints/object-storage-s3/README.md

@@ -0,0 +1,108 @@
+# object-storage-s3
+
+Object storage on the S3 API, accessed through a store facade that is the sole reader of the S3 client. Cloudflare R2 is the first adapter, MinIO is the local dev target, any S3-compatible remote (AWS S3, Backblaze B2, Wasabi, self-hosted) composes cleanly. Ships put / get / delete / list, presigned GET URLs with a bounded TTL, and multipart-upload above an elicited threshold, plus a lifecycle-event sink with a metadata-only field discipline. Refuses composition without `security-secrets-management` applied (Baz decision 6): the credential pair is a `secretRef`, never a value.
+
+## What this blueprint gives you
+
+- **A store facade** (TAC-2901) that is the sole importer of the S3 client (`@aws-sdk/client-s3` on Node targets or `aws4fetch` on Workers targets per ADR-2901) in your source tree, opens the client on boot, and exposes typed named domain verbs. Emits `facadeReady` on the first successful ready-check.
+- **A multipart uploader** (TAC-2902) that the facade delegates to for payloads above the elicited threshold (default 8 MiB per ADR-2903); initiates, part-uploads, completes; aborts in-flight on any part-upload failure so no orphan multipart uploads remain on the bucket.
+- **An event sink** (TAC-2903) with a metadata-only field discipline: `facadeReady`, `objectPut`, `objectDeleted`, `presignedIssued`; no body bytes, no user id, no PII drawn from the object body.
+- **Six Node-only probes** proving every runtime observable: five against a real MinIO container (facade round-trip, put/get, presigned URL, multipart 10 MiB, event secrecy against a PII fixture) plus one accountBound R2 real-account smoke that skips cleanly without `CI_HAS_CLOUDFLARE_ACCOUNT`.
+
+## The six REQs
+
+| REQ | What it commits |
+|---|---|
+| REQ-001 | Facade module is the sole reader of the S3 client; opens on boot; emits `facadeReady`. |
+| REQ-002 | Put / get / delete / list contract on typed keys with `objectPut` and `objectDeleted` events. |
+| REQ-003 | Presigned GET URL with bounded TTL (floor 1 minute, default 15 minutes per ADR-2902); 200 within TTL, 403 after. |
+| REQ-004 | Multipart-upload above the ADR-2903 threshold (default 8 MiB); abort-on-failure with no orphan in-flight uploads. |
+| REQ-005 | Four lifecycle events with metadata-only fields; event-secrecy probe asserts against a PII fixture. |
+| REQ-006 | Credential-pair discipline via `security-secrets-management`; refuses composition without with stable message id `object-storage-s3-no-secrets`. |
+
+## The three TACs
+
+- **TAC-2901 facade**: the object-storage S3 facade module.
+- **TAC-2902 multipart uploader**: initiate/part-upload/complete with abort-on-failure.
+- **TAC-2903 event sink**: metadata-only lifecycle event contract.
+
+## The four ADRs
+
+- **ADR-2901 adapter**: `@aws-sdk/client-s3` on Node targets, `aws4fetch` on Workers targets; elicited, `recommendedDefault: true`. Standards trace clause: AWS S3 API and R2 S3-compatibility notes.
+- **ADR-2902 presigned URL TTL**: default 15 minutes, floor 1 minute; elicited ceiling. Standards trace clause: generic enterprise practice.
+- **ADR-2903 multipart threshold**: default 8 MiB, elicited. Standards trace clause: generic enterprise practice.
+- **ADR-2904 object storage contract** (scope: global, topic `objectStorageContract`): S3 API as the shipped shape; conflicts by design with future non-S3-shape siblings. Standards trace clause: AWS S3 API and R2 S3-compatibility notes.
+
+## Elicited parameters
+
+Endpoint URL (R2 `https://<account-id>.r2.cloudflarestorage.com`, AWS S3 `https://s3.<region>.amazonaws.com`, MinIO `http://localhost:9000`, any S3-compatible remote); bucket name; credential-pair reference via `security-secrets-management` (never value); adapter (`awsSdk` or `aws4fetch`); presigned-URL default TTL (default 15 minutes); presigned-URL ceiling (elicited, no shipped default, S3 API 7-day outer bound); multipart-upload threshold (default 8 MiB); force path style (`true` for MinIO, `false` for AWS/R2 with virtual-hosted style); server-side encryption default (`sseNone` on R2 per the R2 compatibility notes; `sseS3` on AWS S3 when the operator elicits it).
+
+## Companions
+
+- **logging**: every lifecycle event (facadeReady, objectPut, objectDeleted, presignedIssued) writes through the applied logger; a logging companion supplies the factory.
+- **errorHandling**: a put failure, a get 404, a presigned-URL malformed request constructs an internal error record; an error-handling companion supplies the record factory and the boundary.
+
+## Composition and conflicts
+
+Consumes `security-secrets-management` v1.0.1+ for the credential pair. Declares `requiresAppliedCapabilities: {capabilities: ["secretsProvider"], allowSkipFlag: "allow-no-secrets-yet", refusalMessageId: "object-storage-s3-no-secrets"}` per the T-5 capability mechanism (visual round spec 5.5.1). The apply verb refuses on a project without `secretsProvider` (exit 3, stderr carries `[object-storage-s3-no-secrets]` as the first-line tag and names the required capability, the shipped predecessor, and the override flag). `--allow-no-secrets-yet` overrides for a scaffolding pass and records a `notes` line on `rcf/blueprints/object-storage-s3.applied.json` for later reconciliation. Contributes ADR-2904 as `scope: global` on new topic `objectStorageContract`; future `object-storage-native-gcs` or `object-storage-native-azure` siblings would conflict here by design. `capabilities: ["objectStorage"]`; `providesRoles: []`.
+
+## The six probes
+
+Each probe is a Node module under `contributions/probes/` exporting the round-5 spec section 3.2 verdict envelope, with a matching `run-<probe-name>.mjs` shim that drives the probe against the shared fixture and writes the per-blueprint report at `.rcf/reports/blueprints/object-storage-s3/<probe-name>.json`.
+
+| Probe | Anchor AC | What it proves | accountBound |
+|---|---|---|---|
+| `facade-round-trip` | AC-28101-1 | Facade opens against MinIO; `facadeReady` fires with endpointHost and bucketName. | false |
+| `put-get-round-trip` | AC-28102-1, AC-28102-2, AC-28102-3 | 1 KiB round-trip byte-equal; delete and list round-trip; `objectPut` and `objectDeleted` fire. | false |
+| `presigned-url` | AC-28103-1 | Presign at 60 s TTL returns 200 within TTL, 403 on tampered signature (or full TTL wall-clock with `SIMULATE_PRESIGN_EXPIRE=true`); floor refusal at 30 s. | false |
+| `multipart-upload` | AC-28104-1, AC-28104-2 | 10 MiB payload above the 8 MiB threshold round-trips byte-equal via multipart; no orphan in-flight uploads after complete; abort-on-failure with `SIMULATE_PART_UPLOAD_FAIL=true`. | false |
+| `event-secrecy` | AC-28105-1 | Every event record carries only whitelisted metadata fields; no PII fixture text; no forbidden field name. | false |
+| `r2-real-account-smoke` | AC-28108-1 | Real R2 round-trip when `CI_HAS_CLOUDFLARE_ACCOUNT` is set; records `accountBoundSkipped: true` when it is not. | true |
+
+## How to run the probes locally
+
+```sh
+cd packages/rcf-lite/test/fixtures/infra-s3-and-queue
+docker compose up -d minio
+sleep 4
+npm install --silent
+node src/create-bucket.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-facade-round-trip.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-put-get-round-trip.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-presigned-url.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-multipart-upload.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-event-secrecy.mjs
+node ../../../../blueprints/object-storage-s3/contributions/probes/run-r2-real-account-smoke.mjs
+docker compose down -v
+```
+
+Each shim exits 0 on aggregate pass and 1 otherwise; every per-blueprint report at `.rcf/reports/blueprints/object-storage-s3/<probe-name>.json` carries `aggregateVerdict pass` on the canonical fixture state. The R2 smoke exits 0 with `accountBoundSkipped: true` when `CI_HAS_CLOUDFLARE_ACCOUNT` is unset.
+
+## R2 deviations from full S3
+
+Cloudflare R2 is S3-compatible per https://developers.cloudflare.com/r2/api/s3/api/ but explicitly does not implement:
+
+- **ACLs**: no per-object or per-bucket ACLs; permissions go through Cloudflare account roles and bucket-level API tokens.
+- **Bucket policies**: no S3-style JSON bucket policies.
+- **Object Lock**: no WORM or retention hold surface.
+- **Versioning**: no object versioning; a put replaces the object.
+- **Lifecycle policies**: R2 marks lifecycle-configuration surface as "feature implementation is currently in progress"; do not depend on time-based expiration or class transitions on R2 at v1.0.0.
+
+An operator relying on any of the four either picks a different endpoint (AWS S3 covers all four) or handles the equivalent semantics application-side. The guide's "R2 deviations" section names each and points at the vendor doc.
+
+## The multipart re-upload gotcha
+
+Per the R2 doc: re-uploading to the same part number replaces the previous part with loss-on-fail semantics. If a re-upload fails, the original part is gone. The facade avoids the case in the shipped path (part uploads are single-attempt; abort-on-failure covers the mid-multipart failure), but a project that layers its own retry on top of the facade's `putObject` should retry the whole put, not a partial multipart.
+
+## Known mechanism-reach gaps
+
+- **Adapter choice (ADR-2901)** is elicited at apply time; the facade's public surface is adapter-neutral so a consumer cannot tell at import time which adapter was picked. Mitigation: the checklist row on the applied blueprint records the adapter chosen; the shipped Node fixture uses `@aws-sdk/client-s3` for probe verifiability.
+- **Server-side encryption default (elicited)** is set at apply time; the facade does not enforce a shipped default because R2 differs from AWS S3 here (R2: SSE-C only, no AWS KMS; AWS: sseS3 available). Mitigation: the guide's "Encryption at rest" section names the two per-target defaults and the applied ADR records the operator choice.
+- **Multipart part re-upload loss-on-fail** per the R2 doc: the facade avoids the case internally but a consumer-side retry loop can walk into it. Mitigation: the README calls it out; the guide's "Retry semantics" section names the shipped-path guarantees.
+
+## Standards trace
+
+- Cloudflare R2 S3-compatibility surface: https://developers.cloudflare.com/r2/api/s3/api/ (documents supported ops and the four deviations enumerated above; SSE-C only; auto region only).
+- Cloudflare R2 overview and presigned URLs: https://developers.cloudflare.com/r2/ (S3 API, zero egress fees, presigned URLs).
+- MinIO S3 compatibility for local dev: https://docs.min.io/community/minio-object-store/administration/object-management/object-lifecycle-management.html.
+- GitHub Actions service container shape (for the CI seam): https://docs.github.com/en/actions/using-containerized-services/about-service-containers.

package/blueprints/object-storage-s3/blueprint.json

@@ -0,0 +1,72 @@
+{
+  "slug": "object-storage-s3",
+  "version": "1.0.0",
+  "category": "object-storage",
+  "capabilities": ["objectStorage"],
+  "requiresAppliedCapabilities": {
+    "capabilities": ["secretsProvider"],
+    "allowSkipFlag": "allow-no-secrets-yet",
+    "refusalMessageId": "object-storage-s3-no-secrets"
+  },
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every lifecycle event (facadeReady, objectPut, objectDeleted, presignedIssued) writes through the applied logger; a logging companion supplies the factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A put failure, a get 404, a presigned-URL malformed request constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "contributions": [
+    { "id": "object-storage-s3-REQ-001", "kind": "req", "path": "requirements/object-storage-s3-req-001.json" },
+    { "id": "object-storage-s3-REQ-002", "kind": "req", "path": "requirements/object-storage-s3-req-002.json" },
+    { "id": "object-storage-s3-REQ-003", "kind": "req", "path": "requirements/object-storage-s3-req-003.json" },
+    { "id": "object-storage-s3-REQ-004", "kind": "req", "path": "requirements/object-storage-s3-req-004.json" },
+    { "id": "object-storage-s3-REQ-005", "kind": "req", "path": "requirements/object-storage-s3-req-005.json" },
+    { "id": "object-storage-s3-REQ-006", "kind": "req", "path": "requirements/object-storage-s3-req-006.json" },
+    { "id": "object-storage-s3-US-28101", "kind": "us", "path": "user-stories/object-storage-s3-us-28101.json" },
+    { "id": "object-storage-s3-US-28102", "kind": "us", "path": "user-stories/object-storage-s3-us-28102.json" },
+    { "id": "object-storage-s3-US-28103", "kind": "us", "path": "user-stories/object-storage-s3-us-28103.json" },
+    { "id": "object-storage-s3-US-28104", "kind": "us", "path": "user-stories/object-storage-s3-us-28104.json" },
+    { "id": "object-storage-s3-US-28105", "kind": "us", "path": "user-stories/object-storage-s3-us-28105.json" },
+    { "id": "object-storage-s3-US-28106", "kind": "us", "path": "user-stories/object-storage-s3-us-28106.json" },
+    { "id": "object-storage-s3-US-28107", "kind": "us", "path": "user-stories/object-storage-s3-us-28107.json" },
+    { "id": "object-storage-s3-US-28108", "kind": "us", "path": "user-stories/object-storage-s3-us-28108.json" },
+    { "id": "TAC-2901-object-storage-s3-facade", "kind": "tac", "path": "tacs/tac-2901-object-storage-s3-facade.json" },
+    { "id": "TAC-2902-object-storage-s3-multipart-uploader", "kind": "tac", "path": "tacs/tac-2902-object-storage-s3-multipart-uploader.json" },
+    { "id": "TAC-2903-object-storage-s3-event-sink", "kind": "tac", "path": "tacs/tac-2903-object-storage-s3-event-sink.json" },
+    {
+      "id": "ADR-2901-object-storage-s3-adapter",
+      "kind": "adr",
+      "path": "adrs/adr-2901-object-storage-s3-adapter.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "AWS S3 API and Cloudflare R2 S3-compatibility notes"
+    },
+    {
+      "id": "ADR-2902-object-storage-s3-presigned-ttl-floor",
+      "kind": "adr",
+      "path": "adrs/adr-2902-object-storage-s3-presigned-ttl-floor.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2903-object-storage-s3-multipart-threshold",
+      "kind": "adr",
+      "path": "adrs/adr-2903-object-storage-s3-multipart-threshold.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2904-object-storage-s3-contract",
+      "kind": "adr",
+      "path": "adrs/adr-2904-object-storage-s3-contract.json",
+      "scope": "global",
+      "topic": "objectStorageContract",
+      "standardsTraceClause": "AWS S3 API and Cloudflare R2 S3-compatibility notes"
+    }
+  ]
+}

package/blueprints/object-storage-s3/contributions/adrs/adr-2901-object-storage-s3-adapter.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-2901-object-storage-s3-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "S3 client adapter: @aws-sdk/client-s3 on Node targets; aws4fetch on Workers targets; elicited",
+  "context": "A project deploying object storage on an S3-shape endpoint has two mainstream client choices for the two dominant deploy targets. On Node targets, @aws-sdk/client-s3 (the modular AWS JavaScript SDK v3) is the reference client with a mature multipart transferer, presigned URL helper, and Cloudflare R2 compatibility. On Cloudflare Workers targets, aws4fetch is the lightweight fetch-native client that avoids the AWS SDK's Node polyfills and ships tiny. Both speak the S3 wire protocol; both handle SigV4; both cover the ops the v1.0.0 facade surface needs (PutObject, GetObject, DeleteObject, ListObjectsV2, presigned URL via query-string, CreateMultipartUpload / UploadPart / CompleteMultipartUpload / AbortMultipartUpload). The v1.0.0 facade design has to hold the adapter reference opaque at the facade boundary so the operator picks per deploy target and a future adapter (a GCS shim, an Azure Blob shim under a sibling blueprint) slots in without a facade re-shape.",
+  "decision": "The shipped v1.0.0 default on a Node target is @aws-sdk/client-s3 (AWS SDK v3, modular client-s3 package). The shipped v1.0.0 default on a Workers target is aws4fetch. Both are elicited at apply time under the adapter parameter; the operator picks based on the deploy target. Every S3 request goes through the elicited client; the facade module is the sole importer of either package in the source tree per REQ-001. The adapter reference is OPAQUE at this ADR: the facade imports the elicited adapter at the top of the module and any consumer wanting a different adapter (a GCS shim, an Azure Blob shim inside a sibling blueprint that mints on demand) replaces the import here without touching the outward interface.",
+  "consequences": "The project inherits the elicited adapter's mature request-signing surface, its presigned-URL helper, and its multipart-upload transferer. Standards trace clause: AWS S3 API (the de facto interop standard, no single normative RFC) and the Cloudflare R2 S3-compatibility notes at https://developers.cloudflare.com/r2/api/s3/api/ enumerating the supported ops (PutObject, GetObject, DeleteObject, ListObjectsV2, HeadObject, HeadBucket, CopyObject, multipart upload, ListMultipartUploads) and the deviations (no ACLs, no bucket policies, no Object Lock, no versioning, no lifecycle policies, SSE-C only). Projects deploying to MinIO for local dev pick the AWS SDK adapter transparently; MinIO covers the S3 surface for the shipped ops per the MinIO S3 compatibility posture at https://docs.min.io/community/minio-object-store/administration/object-management/object-lifecycle-management.html. A future GCS or Azure Blob sibling mints on demand under a different global topic on objectStorageContract (ADR-2904); the operator resolution surfaces as a topic conflict per the round-2 pattern.",
+  "alternativesConsidered": [
+    {
+      "name": "aws-sdk v2 as the shipped Node default",
+      "summary": "Ship the monolithic aws-sdk v2 npm package as the Node default.",
+      "reasonNotChosen": "aws-sdk v2 is in maintenance mode as of 2024; the modular v3 package @aws-sdk/client-s3 is the recommended surface for new work and ships smaller. Choosing v2 would drag every consumer to a maintenance-mode dependency at v1.0.0."
+    },
+    {
+      "name": "aws4fetch as the shipped Node default too",
+      "summary": "Ship aws4fetch on both Node and Workers targets to shrink the dependency footprint.",
+      "reasonNotChosen": "aws4fetch is fetch-native and Workers-friendly but lacks the presigned-URL helper and the multipart transferer the v1.0.0 REQ-003 and REQ-004 need out of the box; a Node target picking aws4fetch would need consumer-side glue for both, defeating the value of the shipped facade."
+    },
+    {
+      "name": "Ship a hand-rolled SigV4 signer with fetch",
+      "summary": "Roll our own SigV4 signer as the v1.0.0 default and skip both AWS SDK and aws4fetch.",
+      "reasonNotChosen": "SigV4 is well-specified but the surface area (request signing, presigned URL, multipart) exceeds a shelf blueprint's maintenance envelope. Two mature adapters exist; picking one per target and eliciting is the shelf pattern."
+    }
+  ],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}

package/blueprints/object-storage-s3/contributions/adrs/adr-2902-object-storage-s3-presigned-ttl-floor.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2902-object-storage-s3-presigned-ttl-floor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Presigned-URL default TTL 15 minutes, floor 1 minute, ceiling elicited",
+  "context": "A presigned URL is the S3-shape mechanism for delegating read access to an object without handing out credentials. The URL carries a bounded TTL after which the storage endpoint refuses the request with 403 (S3 AccessDenied; MinIO returns a 403 XML with AccessDenied code; the R2 shape matches). Too-short a TTL and legitimate readers miss the window; too-long a TTL and a leaked URL becomes a persistent breach. The AWS SDK's default expires-in value is 900 seconds (15 minutes) which most enterprises match; the S3 API caps SigV4 presigned URLs at 604800 seconds (7 days) though few callers reach that ceiling. Local dev with MinIO handles the full range identically.",
+  "decision": "The shipped default TTL is 15 minutes (900 seconds). The floor is 1 minute (60 seconds); the facade refuses a presign request below the floor with a value error. The ceiling is elicited at apply time (no shipped default) with the S3 API's own 7-day ceiling as the outer bound; the operator picks a shorter cap when their threat model calls for it. Every presignedIssued event carries the ttl value used so downstream logging can flag long-lived URLs.",
+  "consequences": "The default is the AWS SDK's own default; most consumer code needs no override. Standards trace clause: generic enterprise practice (no single normative RFC for presigned URL TTL; the S3 API's 7-day ceiling is the outer bound). The 1-minute floor is a defensive against copy-paste ADRs that drift TTL toward seconds; a legitimate short-TTL use case (a 30-second CDN-signed URL) is handled by a dedicated CDN blueprint, not by object-storage-s3. Operators who want a longer default author a project-level ADR overriding the elicited ceiling; the shipped default stays at 15 minutes.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship a shorter default (5 minutes)",
+      "summary": "Ship 5 minutes as the default TTL, matching the tightest common threat model.",
+      "reasonNotChosen": "5 minutes trips legitimate browser-side retries and long-form downloads on slow connections; the AWS SDK's own default of 15 minutes has years of production burn-in without visible complaints."
+    },
+    {
+      "name": "Ship no floor",
+      "summary": "Let the operator set any TTL >= 1 second, matching the SDK's own minimum.",
+      "reasonNotChosen": "A 1-second TTL is a footgun for the copy-paste ADR class of failure; the 1-minute floor is a small defensive with no measured cost."
+    }
+  ],
+  "createdAt": "2026-09-06T18:00:00.000Z",
+  "updatedAt": "2026-09-06T18:00:00.000Z"
+}