This document is the operational security reference for FieldFlow. It describes the implementation delivered in M15.1-M15.5, the controls required for deployment, and the verification needed before a release is approved.

The repository is security-regression ready. The hosted environment must still deploy the M15.5 commit and pass the production checklist before it is treated as release-ready.

FieldFlow uses a React SPA on Vercel and a FastAPI API on Render. These origins are cross-origin and cross-site. The browser sends short-lived access tokens in Authorization headers and sends refresh and CSRF cookies only to the API's /auth path.

flowchart LR
    U[User browser] --> AP[React AuthProvider]
    AP --> HC[HTTP client]
    HC -->|Access JWT in memory| API[FastAPI routes]
    HC -->|Refresh cookie + CSRF| AUTH[Auth routes]
    AUTH --> RS[Refresh-session service]
    RS --> RDB[(Refresh-session digests)]
    API --> JWT[JWT validation + user reload]
    JWT --> UDB[(Users)]
    API --> OWN[Project and nested ownership checks]
    OWN --> DATA[(Project data)]
    OWN --> ATT[Attachment service]
    ATT --> OBJ[(Private object storage)]
    OWN --> PDF[Bounded PDF export]

• Registration normalizes the complete email address, validates password length in UTF-8 bytes, hashes the password with bcrypt, and returns a generic conflict response for an existing identity.
• Login applies a bounded email-and-client-address rate limit. Unknown users receive the same response and password-verification work as wrong passwords.
• A successful login creates a new refresh-session family and a short-lived HS256 access JWT. The access token is returned to the SPA and held only in module memory.
• The opaque refresh token is stored in an HttpOnly API cookie. PostgreSQL stores only a keyed HMAC-SHA256 digest.
• Startup restoration obtains a CSRF token and rotates the refresh token. A normal 401 means signed out; a network failure or timeout produces a retry state instead of an expiration notice.
• Every refresh consumes the current session under a row lock, creates a replacement in the same family, and rotates both refresh and CSRF cookies.
• Reuse of a revoked refresh token revokes all active sessions in that family.
• Logout revokes the presented family and clears both cookies. The SPA clears local authentication first, so an unavailable API cannot leave private UI active.
• Every protected request validates the JWT signature, issuer, audience, expiry, issue time, type, token ID, subject, and user ID, then reloads the user. Deleted users are rejected with the same generic 401.

• get_owned_project loads a project with both project ID and current user ID.
• Project-scoped routers depend on that owned project before listing or mutating nested records.
• Update and delete queries verify that the nested record belongs to the requested project.
• Related task, predecessor, template, attachment-parent, and workflow references are validated within the same project boundary.
• Template lists are filtered by user; applying a template requires both an owned project and a template owned by the same user.
• Attachment list, upload, download, and delete operations resolve the allowlisted parent type under the owned project. Client input never supplies storage keys.
• PDF export depends on the owned project and reads only that project's tasks.
• Missing and foreign nested resources use the established safe 403/404 policy and do not mutate data.

• Pydantic mutation models reject unknown fields, strip surrounding whitespace, bound strings and numbers, and validate business date ordering.
• Positive IDs and collection pagination are bounded before route logic.
• ASGI middleware enforces the request-body ceiling before multipart parsing and while streamed chunks are received.
• Security headers and Cache-Control: no-store are added to API responses.
• CORS permits credentials only for exact configured origins.
• Refresh and logout require a trusted Origin, CSRF cookie, and matching X-CSRF-Token header.
• Task reorder, template application, session rotation, attachment metadata, durable cleanup, and other multi-step mutations use explicit transaction boundaries.
• Opportunistic refresh-session cleanup is bounded and isolated in a savepoint, so cleanup failure does not invalidate a successful login or refresh transaction.
• Authentication logs use fixed event names and exclude credentials, tokens, cookies, headers, request bodies, token digests, and secret configuration.

• User credentials and authenticated sessions
• Project schedules, field records, financial change-order data, and exports
• Attachment metadata and private object content
• Tenant ownership boundaries
• Database and object-storage credentials
• Application signing and refresh-digest secrets
• Service availability and audit-relevant security events

• An unauthenticated internet client
• An authenticated user attempting horizontal tenant access
• An attacker with script execution in the frontend origin
• An attacker with a stolen access token or refresh cookie
• A malicious uploader or user supplying hostile record text
• An automated brute-force or resource-exhaustion client
• An operator or deployment error that weakens production configuration

• Browser to Vercel static hosting
• Browser to the cross-site Render API
• Render edge to the FastAPI process
• FastAPI to PostgreSQL
• FastAPI to private object storage
• Deployment control plane to application secrets

• Frontend: https://construction-scheduler-eight.vercel.app
• API: https://construction-scheduler-api.onrender.com
• Database: managed PostgreSQL
• Attachments and Documents: private S3-compatible object storage
• Topology: HTTPS, cross-origin, and cross-site
• Preview policy: Vercel previews do not receive credentialed production API access unless their exact origin is deliberately configured.

Use matching hostnames for local frontend and API URLs when testing cookies. For example, use 127.0.0.1 for both origins or localhost for both.

Use backend/.env.example and frontend/.env.example as the canonical inventory. Never copy production values into repository files.

1. Back up PostgreSQL and record the currently deployed application commit.

2. Confirm Render secret values and private object-storage access.

3. Run the full verification commands in this document.

4. Deploy the Render service. Its start command runs:

   alembic upgrade head
   uvicorn app.main:app --host 0.0.0.0 --port $PORT

5. Confirm the Render health check returns exactly {"status":"online"}.

6. Confirm the finite extraction cron uses the API's database/provider values, confirm the preconstruction preparation cron uses the same database and keeps the provider disabled without receiving object-storage credentials, and configure the separate recurring attachment-cleanup command.

7. Deploy Vercel with VITE_API_URL set to the production API.

8. Confirm Vercel serves the committed headers from frontend/vercel.json.

9. Run DOCUMENT_QA.md before announcing release.

Database migrations run before the new API process starts. Do not run concurrent deploys against different migration heads.

• Vercel and Render must redirect HTTP to HTTPS.
• HSTS is expected at the hosting edge; do not add application HSTS until trusted-proxy and HTTPS behavior are verified.
• Preserve the original client address only through the platform's trusted proxy configuration. The application intentionally ignores arbitrary raw forwarding headers.
• Configure the edge request limit at or below the application MAX_REQUEST_BODY_BYTES value.

For a normal deploy: database availability, object storage, Render migration and API, cleanup scheduler, then Vercel. For recovery, restore dependencies before API traffic and verify the API before restoring the frontend release.

1. Stop further deploys and preserve logs, timestamps, and the failing commit.
2. If the schema is backward compatible, redeploy the previous API commit.
3. Roll back Vercel to its prior deployment after the compatible API is healthy.
4. Do not downgrade PostgreSQL unless the specific Alembic downgrade was tested against a backup and no newer data would be lost.
5. Restore object-storage credentials or provider routing independently when the database remains correct.
6. Re-run health, login, refresh, ownership, upload, and export smoke tests.

• The approved commit is deployed to both Render and Vercel.
• PostgreSQL backup and restore procedures have been tested.
• python -m alembic heads reports one head.
• python -m alembic current equals the repository head.
• python -m alembic check reports no pending operations.
• The database user has only required schema and data privileges.
• The private object-storage bucket denies public access.
• Attachment cleanup runs on a bounded external schedule.

• APP_ENV=production and APP_DEBUG=false.
• DATABASE_URL, SECRET_KEY, and REFRESH_TOKEN_SECRET are secret-managed.
• Signing and refresh secrets are independent and meet length rules.
• No example, placeholder, or development secret is deployed.
• VITE_API_URL points to the HTTPS production API.
• Preview deployments cannot use production sessions by wildcard.

• Refresh cookie is HttpOnly, Secure, SameSite=None, and Path=/auth.
• CSRF cookie is readable, Secure, SameSite=None, and Path=/auth.
• Neither cookie has an unnecessary Domain attribute.
• Logout, invalid session, and replay responses clear both cookies.
• The exact Vercel origin is the only production allowed origin.
• Credentialed preflight permits Authorization and X-CSRF-Token.
• Missing or mismatched CSRF and untrusted Origin return safe 403 responses.

• Frontend and API redirect HTTP to HTTPS.
• HSTS is visible from the production delivery path.
• Frontend and API send X-Content-Type-Options: nosniff.
• Frontend and API deny framing and set referrer and permissions policies.
• Sensitive API responses use Cache-Control: no-store.
• Attachment responses have safe type, disposition, CSP, and CORP headers.

• Registration, login, startup restoration, refresh, and logout pass.
• Expired access token causes one refresh and one retry.
• Refresh rotation replaces both cookies.
• Replayed refresh token revokes its family.
• Deleted-user access and refresh are rejected.
• Two users cannot access each other's projects, templates, records, attachments, or exports.
• Rate limits return 429 and Retry-After.

• Valid synthetic files upload, download, preview, and delete.
• Unsupported, mismatched, foreign-parent, and oversized uploads fail safely.
• Storage failures leave durable cleanup work without exposing keys.
• Owned PDF export succeeds with safe filename and headers.
• Hostile ReportLab text remains inert.
• Foreign and excessive exports fail without leaked data or paths.
• Unknown fields, malformed IDs, invalid dates, and excessive lists fail safely.

• Authentication, replay, 429, 413, 5xx, storage, and export alerts are configured.
• Logs exclude credentials, tokens, cookies, headers, bodies, and secret values.
• Health is public, minimal, fast, and monitored.
• Login, retry, expiration, and logout work by keyboard with visible focus.
• Auth views pass 320, 375, 768, 1024, desktop, and 200% zoom checks.
• Chromium, Firefox, Safari/WebKit, and Edge smoke tests are recorded.
• Incident contacts, secret rotation owners, and rollback authority are assigned.

Verification on August 1, 2026 found:

• Vercel returned 200, HSTS, and the committed nosniff, frame, referrer, and permissions headers. A site-wide CSP remains an explicitly documented residual risk and is not configured by frontend/vercel.json.
• The Render API returned no response bytes within a finite 30-second probe.

Do not approve the M16 production release until the API and M16 commits are deployed and every applicable production item in DOCUMENT_QA.md passes.

Verification completed on July 29, 2026:

Verification completed on August 1, 2026:

Document-specific storage, cleanup, extraction, search, viewer, relationship, migration, purge-preparation, and future-restore procedures are in DOCUMENT_OPERATIONS.md. The runbooks below remain the security and session incident baseline.

Symptoms: refresh_token_reuse warning, refresh 401s, or a user reports being signed out across tabs. Likely causes: duplicated stale cookie, cross-tab race without Web Locks, or stolen token. Immediate response: preserve event time and user context without logging tokens; treat repeated events as possible compromise. Recovery: have the user log in to create a new family; rotate the refresh secret only for systemic compromise. Verification: old family remains revoked and the new session rotates once.

Symptoms: signing secret is exposed or cannot be trusted. Likely causes: secret-manager disclosure, operator error, or repository leakage. Immediate response: restrict access, preserve evidence, and generate a new independent secret. Recovery: update SECRET_KEY and restart all API instances; existing access JWTs become invalid. Verification: old access tokens return 401 and new login tokens succeed.

Symptoms: refresh-digest key is exposed. Likely causes: secret-manager or host compromise. Immediate response: generate a new REFRESH_TOKEN_SECRET and communicate a forced sign-in. Recovery: deploy the new secret; existing cookie digests no longer match. Optionally remove old session rows after evidence is retained. Verification: old refreshes fail and new login/rotation succeeds.

Symptoms: login, refresh, and protected requests return 5xx or time out. Likely causes: provider outage, connection exhaustion, DNS, credentials, or migration failure. Immediate response: stop migrations and repeated restarts; check provider health and connection limits. Recovery: restore database connectivity, then restart the API. Verification: health, login, refresh, ownership lookup, and one write transaction succeed.

Symptoms: elevated 429s or authentication rejection logs. Likely causes: credential stuffing, client retry loops, shared proxy identity, or a campaign. Immediate response: inspect aggregate identity/IP patterns without logging credentials. Recovery: block abusive sources at the edge and correct clients; do not arbitrarily raise limits. Verification: legitimate login works after the window and abusive traffic remains controlled.

Symptoms: upload/download 503s or growing attachment cleanup retries. Likely causes: provider outage, expired credentials, bucket policy, DNS, or region mismatch. Immediate response: preserve database metadata and cleanup jobs; do not delete keys manually. Recovery: restore credentials or provider availability and run bounded cleanup. Verification: synthetic upload/download/delete succeeds and pending jobs drain idempotently.

Symptoms: owned exports return a safe server error. Likely causes: bad data edge case, ReportLab failure, resource ceiling, or temporary storage. Immediate response: record project ID and event time, never field contents or generated paths. Recovery: reproduce with synthetic data and restore the previous compatible build if widespread. Verification: hostile, Unicode, long-field, and task-limit exports pass with no temporary files.

Symptoms: expected 413, unexpected connection reset, or proxy/application limit mismatch. Likely causes: file over 25 MiB, multipart overhead, CDN limit, false Content-Length, or client retry. Immediate response: compare edge, request-body, and per-file limits. Recovery: correct mismatched configuration; do not increase limits without product approval. Verification: just-under succeeds, just-over returns safe 413, and no temporary file remains.

Symptoms: health, auth, migration, or core smoke checks fail after deploy. Likely causes: incompatible code/schema, missing environment, or hosting configuration. Immediate response: freeze deploys and record both commits. Recovery: follow the rollback procedure above; prefer application rollback over an untested database downgrade. Verification: previous health and smoke-test baseline is restored.

Symptoms: systemic session compromise or mandatory global revocation. Likely causes: refresh-secret or authentication-host compromise. Immediate response: rotate REFRESH_TOKEN_SECRET; rotate SECRET_KEY too if access tokens are affected. Recovery: restart all API instances and require login. Verification: old access and refresh material fails while new sessions work. There is no user-facing global-logout command.

Symptoms: unauthorized project activity or repeated replay events. Likely causes: stolen credentials, browser compromise, or shared account. Immediate response: preserve logs, delete or otherwise disable the user through controlled database operations, and protect project data. Recovery: because password reset is not implemented, restore access only through an approved operator process. Verification: deleted-user access and refresh return generic 401 and other tenants remain unaffected.

Symptoms: the user receives 401 on protected access and refresh. Likely causes: intentional deletion or incorrect administrative data operation. Immediate response: confirm the deletion audit trail. Recovery: recreate access only through an approved identity process; do not edit token claims or refresh rows. Verification: old JWT and refresh family stay invalid and a newly registered identity owns no old projects.

Symptoms: login succeeds but restoration/logout fails, cookies do not appear, or deletion is ineffective. Likely causes: Secure/SameSite/path mismatch, wrong API URL, clock problems, or stale deployment. Immediate response: inspect Set-Cookie attributes without recording values. Recovery: align environment values and redeploy API and frontend. Verification: both cookies use /auth, rotate, and clear in the supported browser.

Symptoms: production refresh omits cookies despite successful login. Likely causes: third-party cookie restrictions, privacy mode, or missing SameSite=None; Secure. Immediate response: reproduce in the affected browser and inspect cookie blocking reasons. Recovery: correct flags; for policy-based blocking, use a same-site custom API domain in a future release. Verification: refresh works after reload in each supported browser.

Symptoms: failed preflight or safe 403 from refresh/logout. Likely causes: unlisted frontend, scheme/port mismatch, preview deployment, or trailing configuration error. Immediate response: compare the exact browser Origin with ALLOWED_ORIGINS. Recovery: add only an explicitly approved exact HTTPS origin and redeploy. Verification: approved origin passes preflight while deceptive suffix and preview origins remain denied.

Monitoring should use aggregate counts, latency, status, route, and a request-correlation identifier. It must not capture submitted credentials, headers, cookies, token material, or private record content.

Keep alert thresholds environment-specific. Start with visibility and tune after observing legitimate demo and production traffic.

• Fixed authentication outcomes: login succeeded/rejected, refresh succeeded/rejected/replay, logout completed, and rate-limit rejection
• Operational warnings such as deferred session cleanup
• Framework access data configured by the hosting platform
• Safe status, duration, route template, correlation ID, and aggregate counts when operational logging is added

• Passwords or complete registration/login bodies
• Access tokens, refresh tokens, CSRF values, token digests, or session row IDs
• Authorization or Cookie headers
• Secret keys, database URLs, object-storage credentials, or internal keys
• Attachment bodies, private record text, generated PDF contents, or local filesystem paths

Email addresses and project/user identifiers are PII. Prefer an internal, access-controlled identifier or keyed pseudonym when correlation is required. Grant production-log access by least privilege, encrypt logs in transit and at rest, and choose retention through legal and incident-response policy. A practical starting point is 30 days searchable and 90 days archived, subject to organizational requirements.

Safe examples:

INFO Authentication login succeeded
WARNING Authentication refresh_token_reuse
WARNING Authentication rate limit rejected a request
WARNING Refresh session cleanup deferred

For an incident, record UTC time, environment, release commit, route template, status, safe correlation ID, response action, and operator decisions. Place sensitive evidence in the approved incident system, not application logs.

BroadcastChannel carries only event type, nonce, and timestamp. If unavailable, storage events provide logout/expiration/restoration notification. If storage is blocked, local state still changes but other tabs may not receive the event. Web Locks serialize cross-tab refresh when supported; without them, simultaneous refresh can trigger legitimate replay-family revocation.

Production cross-site cookies require HTTPS, Secure, SameSite=None, credentialed fetches, exact CORS, and browser permission to send the cookie. A same-site custom API domain is the preferred long-term compatibility improvement.

Use synthetic accounts, projects, records, and files. Record method, status, cookie changes, visible result, console result, and headers. Never paste token values into evidence.

The final implementation and documentation agree on these boundaries:

• Authentication uses memory-only access JWTs plus rotating HttpOnly refresh cookies; it no longer stores JWTs in localStorage.
• Authorization remains user-owned and project-scoped; there are no roles, organizations, administrators, or shared projects.
• Validation is strict at schemas and service boundaries; established ISO-string date contracts and workflow rules are preserved.
• Attachments remain private, project-owned, allowlisted by parent type, and backed by local development or private S3-compatible storage.
• Exports remain project-owned, escaped, task-bounded, safely named, and temporary.
• Scheduling, dashboard aggregation, workflow modules, and templates retain their existing architecture and request behavior.
• Sessions use one database migration head and bounded opportunistic cleanup.
• Cookie and CORS settings differ deliberately between local same-site HTTP development and cross-site HTTPS production.
• The frontend retains hash routing, lazy module loading, accessible states, one-retry refresh, and stale-data clearing.

Audience: internal engineering and deployment operators.

• Replaced persistent frontend JWT storage with memory-only access tokens and rotating, revocable refresh sessions.
• Added the refresh_sessions table and identity/template ownership migrations. Deployments must run Alembic before serving new code.
• Added CSRF and exact-Origin enforcement for refresh and logout.
• Added production cookie, CORS, debug, secret, lifetime, rate, and request-limit validation.
• Added database-backed user validation, route-wide tenant enforcement, strict mutation schemas, bounded pagination, and transaction rollback coverage.
• Hardened uploads, attachment delivery, PDF export, security headers, logging, rate limits, and request-body processing.
• Frontend startup now restores from the refresh cookie, retries one expired request, coordinates refresh, propagates session events, and distinguishes network failure from session expiration.

Breaking operational changes: production requires new refresh-session migration and environment values; clients relying on a localStorage token must sign in again. Cross-site production requires COOKIE_SECURE=true, COOKIE_SAMESITE=none, and an exact HTTPS origin.

Known limitations: no password reset, email verification, MFA, OAuth, roles, organizations, access-token denylist, distributed rate limit, antivirus engine, background refresh cleanup worker, full audit log, or verified Safari cross-site-cookie support.

• Login: inspect normalized email, rate-limit status, generic 401, user lookup, bcrypt validation, and Set-Cookie attributes. Never print inputs.
• Refresh: verify /auth/csrf, cookie path, credentials mode, exact Origin, matching header, session digest row, revocation state, and replacement row.
• Cookies: compare host, Secure, SameSite, path, expiry, and browser blocking reason. Do not record cookie values.
• CORS: compare the complete Origin string with ALLOWED_ORIGINS; check preflight method, Authorization, X-CSRF-Token, credentials, and Vary.
• CSRF: confirm the browser sends both the CSRF cookie and matching header to a state-changing /auth endpoint from an allowed Origin.
• 401 loops: ensure the request retries only once, refreshPromise clears, auth generation has not changed, and the unauthorized handler fires once.
• Cross-tab: inspect event types only; verify BroadcastChannel, storage fallback, Web Lock support, and listener cleanup.

Run focused tests first, then complete verification:

cd backend
venv\Scripts\python -m pytest tests/test_auth_sessions.py tests/test_security_hardening.py tests/test_api_hardening.py tests/test_production_hardening.py
venv\Scripts\python -m pytest
venv\Scripts\python -m pip check
venv\Scripts\python -m alembic heads
venv\Scripts\python -m alembic current
venv\Scripts\python -m alembic check

cd ../frontend
npm test
npm run lint
npm run build

Use isolated test settings to reproduce expiration, malformed cookies, database failure, storage failure, rate limits, request limits, and concurrent refresh. Do not weaken committed production defaults for a test.

All schedule settings, task, baseline, look-ahead, resource, health, dashboard, and report routes require authentication and resolve the project through get_owned_project. Nested task, dependency, baseline, plan, company, crew, equipment, assignment, and availability IDs are resolved within that project; strict schemas reject ownership, audit, derived, and unknown fields.

Health accepts only a bounded positive baseline ID and returns approved, bounded fields with no raw ORM objects or task notes. Resource Loading uses typed resource resolution, a 90-day date cap, 200-row pagination, 100-conflict cap, and five-task contribution cap. Look-ahead fields and notes are bounded. The executive PDF escapes user-controlled text, loads no external resource, uses an ASCII-safe server filename, exposes no storage URL, and removes its temporary file on success and failure. M15 session, CSRF, CORS, request-size, header, rate-limit, safe-error, rollback, and log-redaction controls remain unchanged. Live proxy limits, PostgreSQL plans, cross-browser download, and production temporary-directory behavior remain Not Verified.

Do not treat these items as implicit scope for the next milestone. Each requires a separate product and operational decision.

Preconstruction routes authenticate and resolve get_owned_project before review sets, sources, candidates, readiness, or runs. Source resolution is an exact document/drawing_revision allowlist and revalidates the backing Document's project, active state, checksum, and extraction lineage. Strict schemas reject lifecycle, audit, result, and unknown client fields.

Production defaults to a disabled provider and rejects the deterministic fake provider. The provider DTO has no database, storage, ownership, binary, page text, URL, or credential access. Manifests omit content and storage metadata; responses omit manifest JSON, prompts, raw provider output, exceptions, lease tokens, and hidden reasoning. Results are treated as untrusted, strictly validated, and byte-bounded. No document content reaches a provider in M18.1, so malicious-document instructions cannot cross the provider boundary. Future retrieval must preserve that content-as-untrusted-data rule and mandatory human approval. See AI_PRECONSTRUCTION.md and AI_PRECONSTRUCTION_OPERATIONS.md.

Findings are advisory records that cannot mutate any authoritative system. Ownership is enforced through get_owned_project before any comparison plan, run, finding set, finding, assertion link, evidence, or review identifier is resolved, and a two-user matrix covers plan CRUD, archive, readiness, runs, finding listing and detail, review, and manual creation.

Comparison operates only on human-accepted assertions. The comparison manifest pins exact assertion ids and the exact review decision that made each eligible, so a later review change cannot rewrite a historical finding set.

Mutation schemas forbid unknown fields and reject client-supplied project identity, manifest and content hashes, lifecycle status, origin, provider profile and confidence, match scores and reasons, evidence excerpts, reviewer identity, and review timestamps. The server computes all of them.

Provider validation can only keep, reject, or escalate candidates that trusted code already generated. It cannot introduce a candidate, an assertion, or evidence; cannot accept a finding; cannot create project records; and cannot change the manifest. Any structural failure — unknown candidate key, unknown or disallowed finding type, forged assertion or evidence id, repeated candidate, version mismatch, or oversized result — rejects the entire result.

Severity proposed by a provider is clamped to one step from the documented default. There is no bulk acceptance, no confidence threshold that accepts a finding, and no one-click RFI or Change Order action. Archived plans and review sets are read-only.

The controlled vocabulary deliberately contains no legal-conclusion terms; tests assert that breach, liability, entitlement, and damages never appear in finding types or review reason codes.

Logs may carry plan, run, and finding-set identifiers, counts, provider profile, safe failure and warning codes, versions, latency, and a manifest hash prefix. They must never carry finding summaries or rationales, assertion text, evidence excerpts, reviewer notes, prompts, or provider response bodies.

M18.7 re-verified every M18 security boundary and recorded the result in AI_PRECONSTRUCTION_RELEASE.md. Automated guards now assert each one on every backend run rather than relying on review:

• all 49 preconstruction routes resolve get_owned_project before any nested identifier, and no route commits or rolls back its own transaction;
• no preconstruction service constructs an RFI, ChangeOrder, Submittal, PunchItem, EntityRelationship, Task, DrawingRevision, or Document, scanned across all six service modules;
• the provider factory contains no dynamic import, class path, eval, exec, or getattr, so no live SDK is reachable;
• .env.example pins the disabled provider, disabled fake provider, and disabled OCR;
• every setting declared in config.py appears in the deployment contract, so the two cannot drift;
• cited evidence, snapshots, pages, and segments are RESTRICT-protected, and the three append-only tables carry no updated_at;
• the migration chain is linear with a single head and no branch.

One production defect was found and fixed during closeout. The preconstruction_analysis_runs type CHECK permitted scope_comparison and scope_comparison_validation, but the display-label map omitted both, so a stored row of either type would have made the run listing and run detail routes fail for the entire review set. The label map is now total with respect to its own CHECK, and a test asserts that property for all eleven controlled vocabularies. Labeling did not make either type creatable: the request literal still refuses both.

Four high-severity npm advisories remain in dev-only transitive packages (brace-expansion, nanoid, postcss, undici). npm audit --omit=dev reports zero vulnerabilities; none of these packages reaches the browser bundle. Remediation requires a dependency bump and is deferred.

Execution metrics are measurement, not analysis. The metrics route is read-only: there is no create, update, or delete endpoint, and a test asserts POST, PUT, and DELETE all return 405. Ownership is enforced through get_owned_project, so a foreign project returns 403 and an anonymous request 401.

Metric payloads carry identifiers, counts, milliseconds, billable units, and cost only. A test asserts assertion text, evidence excerpts, reviewer notes, prompts, and rationales never appear in the serialized response.

Cost is reported as absent when no rate is configured rather than as zero, so an operator is never shown a fabricated figure, and the stored micro-units imply no currency.

The execution_id reference is deliberately untyped, so a metric never restricts or cascades into the record it measures; project deletion still cascades metrics with the rest of the graph. Recording runs inside a SAVEPOINT and swallows failures, so measurement can never roll back the work being measured.

Readiness diagnostics contain no measured duration, preserving the documented determinism of the readiness response; a test asserts two consecutive calls are byte-identical.

A pair-budget breach blocks readiness and refuses the run with 422 rather than silently comparing a truncated population, so a reviewer is never shown a partial comparison presented as complete. Manifest reuse is opt-in, returns an existing set without writing, and declines as soon as a human review changes the pinned manifest.

The evaluation framework is pure and offline: no ORM, session, network, provider, database write, or project data, asserted by a test that records zero SQL statements during a full command run. No evaluation outcome can accept, reject, or escalate anything.

A follow-up is advisory bookkeeping that records human intent and a link. No route in M18.5 creates, approves, or mutates an RFI, Change Order, Submittal, Task, relationship, procurement record, or notification, and a route-inventory test asserts there is no promote, auto-create, or bulk endpoint anywhere. A snapshot test captures eighteen authoritative tables — including entity_relationships, rfis, change_orders, submittals, tasks, and the whole M18.2-M18.4 immutable chain — before and after a full follow-up lifecycle and asserts byte-equality.

Ownership is enforced through get_owned_project before any follow-up, finding, comparison-plan, or review-set identifier is resolved, and a two-user matrix covers all six routes. A follow-up reached through another user's own project returns 404 rather than leaking its existence.

A follow-up may only be raised from a finding whose current status is accepted. intentional_exclusion is refused because that status is the recorded decision not to act. Archived plans and review sets are read-only.

Link targets are resolved through the existing resolve_relationship_entity(..., require_selectable=True), the same code that guards the relationship graph, so a foreign, missing, or unavailable record can never be linked and target_type must match the action's declared record type. The reference is deliberately untyped, so a follow-up never restricts or cascades into an authoritative workflow table.

Mutation schemas forbid unknown fields and reject client-supplied project identity, finding identity, lifecycle status, the pinned acceptance review, target identity at creation, draft template version, actor identity, and every lifecycle timestamp. The server computes all of them.

Drafts are assembled server-side from stored finding data, cite evidence by reference rather than copying it, and are plain text with no Markdown, HTML, or links. Import-time validation rejects the vocabulary module if breach, liability, entitlement, damages, negligence, default, termination, or warranty-claim language appears in any label, template, or notice, and tests assert the same over generated drafts.

A partial unique index on (finding_id, action_type) restricted to active statuses means a double submission cannot produce two RFIs for one finding. Reversing a finding's acceptance never rewrites an existing follow-up; the reversal is surfaced as a derived flag and new follow-ups are refused.

Logs may carry follow-up, finding, plan, and target identifiers, action type, status, and counts. They must never carry draft titles or bodies, closure notes, reviewer notes, assertion text, or evidence excerpts.

Scope assertions are advisory records that cannot mutate any authoritative system. Ownership is enforced through get_owned_project before any assertion, assertion-set, evidence, or review identifier is resolved, and a two-user matrix covers taxonomy reads, listings, detail, manual creation, review, and supersession.

Mutation schemas forbid unknown fields and reject client-supplied project identity, origin, lifecycle status, confidence, provider assertion keys, taxonomy versions, content hashes, evidence excerpts, reviewer identity, and review timestamps. The server computes all of them. Reviewer identity always comes from the session.

Provider output is untrusted and strictly revalidated: sources must belong to the pinned manifest, concepts must be active in the pinned taxonomy, and every evidence coordinate must match a segment that was actually supplied in the request with a matching text hash. Excerpts are always derived server-side from stored segment text. A provider cannot set review state, accept an assertion, reference foreign content, or introduce taxonomy entries. Any structural or evidence-identity failure rejects the entire result.

There is no bulk acceptance and no confidence threshold that can accept an assertion. Archived review sets are read-only.

Logs may carry identifiers, counts, provider profile, safe failure codes, versions, latency, and a manifest hash prefix. They must never carry requirement text, evidence excerpts, segment content, prompts, provider response bodies, or reviewer notes.

Hostile-content fixtures (instruction override, forged system messages, fabricated taxonomy codes, forged source and segment identifiers, HTML/script, SQL, shell commands, URL fetch requests, and auto-approval instructions) are covered by tests asserting the content stays inert or fails validation. This reduces risk; it does not claim prompt injection is solved.

Preparation routes still resolve get_owned_project before nested Review Set, Review Source, run, snapshot, page, or segment IDs. Server code computes every checksum, lineage fingerprint, count, hash, status, warning, timestamp, and citation coordinate; optional request bodies and query parameters cannot mass-assign lifecycle or text fields. Inspection is source-scoped, paginated, character-bounded, and returned with Cache-Control: no-store.

Extracted text is untrusted. NFKC normalization removes null and unsafe control characters, while React renders the result only as plain text. No HTML, Markdown, formula, shell, SQL, forged JSON, or URL is interpreted or fetched. Content-dependent provider DTOs keep a fixed instruction separate from typed untrusted_text and expose no tools, ORM objects, database session, storage, credentials, or arbitrary URLs. This is defense in depth, not a claim that prompt injection is solved.

Snapshot creation is atomic and immutable after completion. Failed work rolls back all content rows and retains only a safe preparation-run outcome. Lease tokens are stored as digests; logs and responses omit document text, internal leases, storage metadata, signed URLs, raw exceptions, and provider secrets. Production OCR and live AI remain disabled. See AI_CONTENT_PREPARATION.md.