> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase08-session05-production-hosted-validation-and-deploy-smoke/spec.md). # Session Specification **Session ID**: `phase08-session05-production-hosted-validation-and-deploy-smoke` **Phase**: 08 - Release Hardening and Legacy Decommission **Status**: Complete **Created**: 2026-05-31 **Completed**: 2026-05-31 **Package**: Cross-cutting **Package Stack**: Node 20 scripts, TypeScript test coverage, Cloudflare Worker/Public Demo deployment docs, release evidence, and Phase 08 PRD artifacts across `scripts`, `tests`, `docs`, `public-demo`, `apps/warroom`, `apps/web`, and `.spec_system/PRD/phase_08` *** ## 1. Session Overview This session creates the Phase 08 production-hosted validation gate. Sessions 01 through 04 closed the release baseline, erasure inventory, local/browser erasure, Worker room-state erasure, and hosted identity no-claim gates. The next unresolved release risk is that local, mocked, same-origin, or documentation-only evidence could be mistaken for deployed app, deployed Worker, public demo, Cloudflare dashboard, or production account validation. The work defines repeatable, sanitized smoke validation for deployed release surfaces: the public demo on Cloudflare Pages, the War Room Worker on its custom domain and workers.dev URL, and any optional deployed app shell if a release host is explicitly configured. If a surface has no production host or credentials are absent, the session records a no-claim unavailable result instead of failing local-first development or implying hosted capability. The session should produce source-controlled scripts, tests, runbook updates, and sanitized evidence. The implementation must not print Cloudflare account ids, zone ids, API tokens, request bodies, room payloads, prompts, local paths, exports, logs, backups, replay buffers, or raw dashboard output. Release docs should clearly distinguish production-hosted smoke evidence from local browser, mocked Worker, and CI-only validation. *** ## 2. Objectives 1. Define production-hosted validation targets and claim states for public demo, War Room Worker, optional app shell, Cloudflare dashboard constraints, and unavailable surfaces. 2. Add a repeatable hosted smoke script that validates configured URLs with sanitized output, strict URL handling, timeout/failure handling, and no credential printing. 3. Add tests that prove hosted validation fails closed when credentials, URLs, or responses are absent, malformed, unsafe, or sensitive. 4. Record sanitized Phase 08 production-hosted evidence and update release, deployment, hosted-service, public-demo, War Room, and web documentation with exact no-overclaim wording. *** ## 3. Prerequisites ### Required Sessions * [x] `phase08-session01-release-requirements-and-risk-baseline` - provides production-hosted routing, release claim vocabulary, risk ownership, and evidence standards. * [x] `phase08-session02-unified-erasure-contract-and-inventory` - provides erasure and unsupported-claim vocabulary that production validation must not overclaim. * [x] `phase08-session03-local-erasure-runtime-and-controls` - provides local/browser erasure evidence that remains separate from production-hosted validation. * [x] `phase08-session04-war-room-and-hosted-identity-release-gate` - provides Worker room-state erasure and hosted identity no-claim gates that deployed smoke must not reinterpret as hosted identity. ### Required Tools/Knowledge * `docs/deployment.md`, `docs/release.md`, `docs/hosted-services.md`, `docs/environments.md`, and `docs/privacy-and-security.md`. * Public demo docs under `public-demo/docs_public-demo/`, especially deployment and validation guidance. * War Room deployment workflow and docs: `.github/workflows/warroom-deploy.yml`, `apps/warroom/README_warroom.md`, and `docs/runbooks/war-room-operations.md`. * Root scripts and tests patterns in `scripts/README_scripts.md`, `tests/publicDemoMedia.test.ts`, and `tests/mediaReleaseGates.test.ts`. * Phase 08 routing and risk artifacts: `.spec_system/PRD/phase_08/phase08_requirement_routing_matrix.md` and `.spec_system/PRD/phase_08/phase08_release_risk_matrix.md`. ### Environment Requirements * Node 20+ and npm workspaces installed. * Network access for optional smoke runs against configured public URLs. * Cloudflare credentials may be present only in safe local or CI environments and must never be required for local default validation. * Default validation must run without Cloudflare, Supabase, Umami, VAPID, hosted account, provider, tunnel, or executor credentials. *** ## 4. Scope ### In Scope (MVP) * Maintainer can run one production-hosted smoke command for configured public demo, War Room Worker custom domain, War Room Worker workers.dev URL, and optional app shell targets. * Public demo production validation checks HTTPS URL shape, page load, expected shell content, service-worker script availability, cache-version discoverability, and no local endpoint or raw repository asset leak in sanitized output. * War Room Worker production validation checks `/health` on custom-domain and workers.dev targets, compact health metadata, service id, deployment type, app-level rate limit posture, timeout behavior, and response redaction. * Optional app-shell validation records an unavailable no-claim result when no production app host is configured, or a bounded load/health result when an explicit URL is supplied. * Smoke output uses labels, statuses, booleans, URL hostnames, docs paths, timing buckets, and issue codes only. * Script and tests reject unsafe URL schemes, query strings, fragments, credential-bearing URLs, localhost production targets unless explicitly marked local compatibility, and outputs containing secret-like or sensitive payload categories. * Stable docs and Phase 08 artifacts record sanitized evidence, unavailable no-claim results, rollback notes, dashboard constraints, and residual-risk wording. ### Out of Scope (Deferred) * Enabling hosted auth, hosted storage, analytics capture, public replay hosting, push delivery, remote access, Cloudflare Tunnel, hosted diagnostic agents, or real executors - *Reason: Phase 08 Session 05 validates deployed surfaces only and does not activate planned hosted capabilities.* * Adding a production app host for `apps/web` or `apps/server` - *Reason: deployment docs currently state no production app host is configured; this session can validate only an explicitly supplied optional host or record no-claim unavailable evidence.* * Printing Cloudflare account ids, zone ids, API tokens, dashboard raw responses, tunnel tokens, room payloads, prompts, commands, local paths, exports, logs, backups, replay buffers, or raw request bodies - *Reason: release evidence must stay sanitized.* * Formal mobile or accessibility certification - *Reason: Session 06 owns certification evidence and no-overclaim wording.* * Media release gate revalidation or legacy evidence decommission - *Reason: Session 07 owns media and decommission gates.* *** ## 5. Technical Approach ### Architecture Add a root Node script for production-hosted smoke validation. The script should define typed target records for public demo, Worker custom domain, Worker workers.dev URL, and optional app shell. Defaults can use documented public URLs, while optional app-shell and credentials-sensitive checks must require explicit environment variables or CLI flags. The script should support a dry summary mode that reports unavailable/no-claim states without making network calls when targets are disabled or absent. Implement URL and output sanitization as first-class helpers. URL validation should require `https:` for production targets, reject usernames, passwords, query strings, fragments, broad local URLs, and non-HTTP schemes, and expose only safe labels and hostnames in reports. Response handling should use `fetch` with `AbortController` timeouts, bounded response reads, JSON parsing for Worker health, text checks for public demo shell, and explicit error mapping for timeout, DNS/fetch failure, non-2xx, malformed JSON, missing metadata, and sensitive output. Add root Vitest coverage for the script helpers and command result builder. Tests should use injected fetch functions and synthetic responses so they do not require network access or credentials. Documentation should point maintainers to the script, the public URLs, the no-claim behavior for absent app hosts, and the distinction between deployed evidence and local/mocked validation. Create a Phase 08 evidence artifact that records the expected command, target set, sanitized result schema, allowed unavailable results, and any manual production run outcome if available. If no safe network smoke is run during implementation, the artifact must record an explicit unavailable/no-claim result rather than leaving ambiguity. ### Design Patterns * Fail-closed validation: unsafe config, malformed responses, missing hosts, or sensitive output produce explicit issue codes and no-claim states. * Sanitized evidence by default: reports expose safe host labels, statuses, booleans, timings, docs paths, and issue codes only. * Dependency injection for tests: script helpers accept synthetic fetchers and target config so tests do not call production hosts. * Optional hosted target handling: absence of app host or credentials is a no-claim result, not a local workflow failure. * Documentation-backed claims: release docs name exactly which deployed targets were validated and which claims remain absent. ### Technology Stack * Node 20 ESM script under `scripts/`. * Vitest root tests under `tests/`. * Existing npm workspace scripts in root `package.json`. * Cloudflare Pages public demo and Cloudflare Workers War Room endpoints documented in stable docs. * Markdown docs and Phase 08 PRD artifacts. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | | `scripts/check-production-hosted-smoke.mjs` | Production-hosted smoke validator with target config, URL validation, fetch timeouts, response checks, redaction, and JSON/text output | \~360 | | `tests/productionHostedSmoke.test.ts` | Unit tests for target config, URL validation, fetch result mapping, response sanitization, unavailable no-claim states, and sensitive-output rejection | \~260 | | `.spec_system/PRD/phase_08/production_hosted_validation_evidence.md` | Sanitized Phase 08 evidence record for public demo, Worker, optional app shell, dashboard constraints, unavailable results, and residual risks | \~180 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `package.json` | Add `release:hosted-smoke` script for the hosted smoke validator | \~2 | | `scripts/README_scripts.md` | Document hosted smoke script behavior, environment variables, output boundaries, and remediation | \~80 | | `docs/deployment.md` | Add Session 05 production-hosted validation command, target matrix, sanitized output rules, and no-claim app-host behavior | \~100 | | `docs/release.md` | Add Session 05 release gate evidence, command usage, residual risks, and local/mocked evidence distinction | \~100 | | `docs/hosted-services.md` | Update hosted boundary to include production-hosted validation results and no activation of hosted auth/storage/analytics/push/remote surfaces | \~70 | | `docs/environments.md` | Document optional smoke environment variables and secret-safe deployment credential boundaries | \~60 | | `docs/privacy-and-security.md` | Update production-hosted validation security/GDPR posture and sensitive-output limits | \~70 | | `docs/runbooks/war-room-operations.md` | Add deployed Worker smoke procedure and sanitized evidence capture notes | \~70 | | `apps/warroom/README_warroom.md` | Document Worker production smoke command, health expectations, rate-limit posture, and no hosted-identity claim | \~60 | | `apps/web/README_web.md` | Document production-hosted web/app-shell no-claim behavior and distinction from local browser evidence | \~50 | | `public-demo/docs_public-demo/deployment.md` | Link the hosted smoke command to Pages deploy verification and rollback readiness | \~60 | | `public-demo/docs_public-demo/validation.md` | Add production URL smoke expectations and service-worker evidence notes | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `npm run release:hosted-smoke` validates configured production targets or emits explicit unavailable/no-claim results without requiring credentials by default. * [ ] Public demo smoke checks verify HTTPS target shape, shell content, service-worker script availability, cache-version evidence, and absence of local endpoint or raw repository asset leak indicators. * [ ] War Room Worker smoke checks verify compact `/health` metadata on custom-domain and workers.dev targets without exposing raw headers, request bodies, tokens, account ids, zone ids, room payloads, or local paths. * [ ] Optional app-shell smoke records no production-hosted app claim when no explicit host is configured. * [ ] Script output is deterministic, sanitized, bounded, and suitable for stable docs or CI logs. * [ ] Docs distinguish production-hosted smoke evidence from local app browser evidence, mocked Worker evidence, CI typecheck/test evidence, and Cloudflare dashboard metadata. ### Testing Requirements * [ ] Unit tests cover URL validation, target config defaults, unavailable target behavior, timeout handling, non-2xx handling, malformed response handling, sensitive output rejection, and sanitized summary output. * [ ] Existing public demo media and battlefield gates remain documented as prerequisites where public demo files change. * [ ] Manual or recorded smoke evidence is added to the Phase 08 evidence artifact, or an explicit unavailable no-claim result is recorded with the exact reason. ### Non-Functional Requirements * [ ] Core local-first workflows still work without Cloudflare credentials, production URLs, hosted auth, hosted storage, analytics, push, remote access, provider keys, tunnels, or real executors. * [ ] No raw Cloudflare account ids, zone ids, API tokens, tunnel tokens, OAuth values, request bodies, room payloads, prompts, commands, local paths, exports, logs, backups, replay buffers, or dashboard raw responses are printed or tracked. * [ ] Production-hosted validation does not imply hosted identity, hosted storage, analytics capture, public replay hosting, Web Push, remote access, trusted erasure, certification, or release-candidate completion. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `npm run release:hosted-smoke -- --no-network` or equivalent local no-network mode passes. * [ ] Focused Vitest tests for the hosted smoke helper pass. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Key Considerations * The repo currently documents a Cloudflare Pages public demo and a deployed War Room Worker, but no production app host for `apps/web` or `apps/server`. * Absence of a production app host is an explicit no-claim result, not a failure of local-first release readiness. * The Worker health response is compact by design. Do not expand it for this session unless a separate release risk requires it. * Cloudflare dashboard constraints can be documented as manual observations or unavailable results, but raw account ids, zone ids, API responses, screenshots with ids, or tokens must not be tracked. * Public demo production validation should complement, not replace, local public-demo media gates and Playwright checks. ### Potential Challenges * Network flakiness can make production smoke noisy: mitigate with bounded timeouts, one retry only for safe idempotent GET checks if implemented, and issue codes that distinguish timeout from response contract failure. * Production URL drift can make docs stale: mitigate by deriving default URLs from one config object and documenting hostnames only. * Sensitive evidence could leak through error messages: mitigate by redacting URLs, headers, response snippets, and thrown errors before reporting. * Cloudflare credentials may be absent: mitigate with no-claim unavailable states and optional credential checks that report presence labels only. * Public demo CDN dependencies may affect first-load behavior: mitigate by checking shell/service-worker availability and documenting browser Playwright production evidence separately if needed. ### Relevant Considerations * \[P07] **Hosted services ship as disabled-default guardrails only**: this session validates deployed surfaces without activating hosted auth, storage, analytics, push, remote access, or hosted diagnostics. * \[P07] **Phase complete is not release complete**: production-hosted smoke is one release gate; Session 08 still owns final release-candidate closeout. * \[P07] **Redaction is boundary-specific**: smoke output must use labels, statuses, booleans, hostnames, docs paths, timings, and issue codes only. * \[P03] **Stable docs are the current contract**: release, deployment, hosted-service, privacy, runbook, and README docs must be updated with the exact evidence boundary. * \[P02] **Do not confuse browser validation with production-hosted validation**: this session must separate local Playwright and mocked Worker checks from deployed target evidence. * \[Security] **P06-S07-HOSTED-VALIDATION**: this session owns closing or explicitly gating the production-hosted validation finding. * \[Security] **P06-S07-HOSTED-IDENTITY**: Worker health and deploy success must not be treated as hosted account identity or production audit proof. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Hosted smoke output could expose credentials, account ids, raw URLs with tokens, response bodies, request bodies, room payloads, local paths, logs, exports, backups, or replay buffers. * Missing production app hosts or credentials could be misreported as release success instead of unavailable/no-claim evidence. * Local, mocked, or CI evidence could be documented as deployed production evidence. * Network timeouts, malformed responses, or rate limits could produce ambiguous failures that maintainers cannot act on. *** ## 9. Testing Strategy ### Unit Tests * Test target defaults for public demo, Worker custom domain, Worker workers.dev, and optional app host. * Test URL validation rejects unsafe schemes, credentials, query strings, fragments, localhost production URLs, and malformed URLs. * Test public demo response checks with valid shell, missing shell marker, service-worker unavailable, local endpoint leak marker, and raw repository URL marker. * Test Worker health checks with valid compact metadata, non-2xx status, malformed JSON, missing service id, missing rate-limit metadata, and sensitive field leakage. * Test sanitized report output for no tokens, no account ids, no raw request bodies, no local paths, and stable issue ordering. ### Integration Tests * Run the script in no-network mode to verify default target resolution and unavailable/no-claim summaries. * Optionally run the script against documented production URLs in a safe environment and record only sanitized results in the Phase 08 evidence artifact. ### Manual Testing * Review Cloudflare Pages and Worker deployment docs against the smoke target list. * Review production-hosted evidence wording in release, deployment, hosted-services, privacy/security, public-demo, War Room, and web docs. * Confirm docs do not convert local browser evidence, mocked Worker evidence, CI test output, or Cloudflare dashboard metadata into production-hosted claims. ### Edge Cases * Credentials absent or intentionally unset. * Public demo host available but service worker script returns a non-2xx status. * Worker custom domain unavailable while workers.dev is available. * Production app URL unset, malformed, or explicitly supplied with credentials/query strings. * Fetch timeout, DNS failure, rate-limited response, malformed JSON, oversized response text, and sensitive string in response or error text. *** ## 10. Dependencies ### External Libraries * None expected beyond Node 20 global `fetch`, `AbortController`, and existing Vitest tooling. ### Other Sessions * **Depends on**: `phase08-session01-release-requirements-and-risk-baseline`, `phase08-session02-unified-erasure-contract-and-inventory`, `phase08-session03-local-erasure-runtime-and-controls`, `phase08-session04-war-room-and-hosted-identity-release-gate`. * **Depended by**: `phase08-session08-release-candidate-validation-and-documentation-closeout`; supports `phase08-session07-legacy-evidence-decommission-and-media-release-gate` when public demo or media deployment evidence is referenced. *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase08-session05-production-hosted-validation-and-deploy-smoke/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.