@duffcloudservices/site-forms 0.5.0 → 0.7.1

package/src/__tests__/phi-guidance.test.ts

@@ -0,0 +1,239 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import DcsForm from '../DcsForm.vue'
+import {
+  PHI_GUIDANCE_COPY,
+  fetchSiteHandlesPhi,
+  resetSitePhiPostureCache,
+} from '../composables/useSitePhiPosture'
+import type { PortalFormDefinition } from '../types'
+
+// ---------------------------------------------------------------------------
+// C-415 — PHI guidance on HIPAA-mode tenants.
+//
+// The defect: a `hipaaMode: true` clinic whose AI chat told visitors not to
+// share health details while its managed contact form — 6 required fields
+// including a free-text `message` — said nothing at all. Measured 2026-07-31 on
+// the served https://kineticenergypt.com/contact: /HIPAA/i, /protected health/i,
+// /do not include/i and /medical information/i all NOT FOUND.
+//
+// The rule these tests must not let rot: the guidance is a function of the
+// PLATFORM verdict and nothing else. Every test below therefore controls only
+// what the compliance endpoint says, and asserts in BOTH directions — a test
+// that passed while the component ignored the tenant flag would prove nothing,
+// which is what `it('is vacuous if the flag is ignored')` pins explicitly.
+// ---------------------------------------------------------------------------
+
+const GUIDANCE = '[data-form-phi-guidance]'
+
+function makeDef(
+  overrides: Partial<PortalFormDefinition> = {},
+): PortalFormDefinition {
+  return {
+    formId: 'contact',
+    submission: { kind: 'lead' },
+    // The shape measured on KEPT: split name, email, phone, then two required
+    // free-text fields. `message` is the box a patient actually types into.
+    fields: [
+      { id: 'first-name', type: 'text', label: 'First name', required: true, width: 'half' },
+      { id: 'last-name', type: 'text', label: 'Last name', required: true, width: 'half' },
+      { id: 'email', type: 'email', label: 'Your email', required: true, width: 'half' },
+      { id: 'phone', type: 'tel', label: 'Phone number', required: true, width: 'half' },
+      { id: 'subject', type: 'text', label: 'Subject', required: true, phi: true },
+      { id: 'message', type: 'textarea', label: 'Your message', required: true, phi: true },
+    ],
+    ...overrides,
+  }
+}
+
+/** Installs a fetch that answers the compliance endpoint with `siteHandlesPhi`. */
+function stubCompliance(siteHandlesPhi: boolean | undefined, init: Partial<{ ok: boolean }> = {}) {
+  const calls: string[] = []
+  const impl = vi.fn(async (url: unknown) => {
+    calls.push(String(url))
+    return {
+      ok: init.ok ?? true,
+      status: init.ok === false ? 500 : 200,
+      json: async () => ({ siteHandlesPhi }),
+    } as unknown as Response
+  })
+  vi.stubGlobal('fetch', impl)
+  return { calls, impl }
+}
+
+async function mountForm(props: Record<string, unknown> = {}) {
+  const wrapper = mount(DcsForm, {
+    props: {
+      formId: 'contact',
+      siteSlug: 'kept',
+      apiBase: 'https://api.example.test/api/v1',
+      definitionOverride: makeDef(),
+      ...props,
+    },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+beforeEach(() => {
+  resetSitePhiPostureCache()
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+  resetSitePhiPostureCache()
+})
+
+describe('PHI guidance — the two directions', () => {
+  it('RENDERS the guidance when the platform reports the tenant PHI-handling', async () => {
+    stubCompliance(true)
+    const wrapper = await mountForm()
+
+    const note = wrapper.find(GUIDANCE)
+    expect(note.exists()).toBe(true)
+    expect(note.text()).toContain(PHI_GUIDANCE_COPY.lead)
+    expect(note.text()).toContain(PHI_GUIDANCE_COPY.detail)
+    // The copy the chat already ships on these tenants, so the two surfaces read
+    // as one product rather than two teams.
+    expect(note.text().toLowerCase()).toContain('personal health details')
+  })
+
+  it('renders NOTHING on a non-PHI tenant', async () => {
+    stubCompliance(false)
+    const wrapper = await mountForm({ siteSlug: 'mi-handyman' })
+
+    expect(wrapper.find(GUIDANCE).exists()).toBe(false)
+    expect(wrapper.text().toLowerCase()).not.toContain('personal health details')
+  })
+
+  it('is vacuous if the flag is ignored — the same mount must differ on the verdict alone', async () => {
+    // The kill test. Nothing changes between these two mounts except the boolean
+    // the platform returns, so a component that hardcoded either answer fails
+    // one of them. Written as one test on purpose: it is the DIFFERENCE that is
+    // the assertion.
+    stubCompliance(true)
+    const phi = await mountForm()
+    resetSitePhiPostureCache()
+    vi.unstubAllGlobals()
+
+    stubCompliance(false)
+    const nonPhi = await mountForm()
+
+    expect(phi.find(GUIDANCE).exists()).toBe(true)
+    expect(nonPhi.find(GUIDANCE).exists()).toBe(false)
+    expect(phi.find(GUIDANCE).exists()).not.toBe(nonPhi.find(GUIDANCE).exists())
+  })
+})
+
+describe('PHI guidance — placement', () => {
+  it('sits immediately above the free-text field, not at the top of the form', async () => {
+    stubCompliance(true)
+    const wrapper = await mountForm()
+
+    const fields = wrapper.find('.dcs-form__fields').element
+    const children = Array.from(fields.children)
+    const noteIndex = children.findIndex((el) =>
+      el.hasAttribute('data-form-phi-guidance'),
+    )
+    const messageIndex = children.findIndex(
+      (el) => el.getAttribute('data-form-field-key') === 'message',
+    )
+
+    expect(noteIndex).toBeGreaterThan(0) // NOT parked at the top
+    expect(messageIndex).toBe(noteIndex + 1) // directly above the textarea
+  })
+
+  it('falls back to the top when the form/step has no free-text field', async () => {
+    stubCompliance(true)
+    const wrapper = await mountForm({
+      definitionOverride: makeDef({
+        fields: [
+          { id: 'name', type: 'text', label: 'Name', required: true },
+          { id: 'when', type: 'date', label: 'Preferred date' },
+        ],
+      }),
+    })
+
+    const children = Array.from(wrapper.find('.dcs-form__fields').element.children)
+    expect(children[0]?.hasAttribute('data-form-phi-guidance')).toBe(true)
+  })
+
+  it('anchors to a `message`-role field even when it is not a textarea', async () => {
+    stubCompliance(true)
+    const wrapper = await mountForm({
+      definitionOverride: makeDef({
+        fields: [
+          { id: 'name', type: 'text', label: 'Name', required: true },
+          { id: 'note', type: 'text', role: 'message', label: 'How can we help?' },
+        ],
+      }),
+    })
+
+    const children = Array.from(wrapper.find('.dcs-form__fields').element.children)
+    const noteIndex = children.findIndex((el) =>
+      el.hasAttribute('data-form-phi-guidance'),
+    )
+    expect(children[noteIndex + 1]?.getAttribute('data-form-field-key')).toBe('note')
+  })
+})
+
+describe('the posture read itself', () => {
+  it('calls the slug-scoped compliance route', async () => {
+    const { calls } = stubCompliance(true)
+    await mountForm()
+    expect(calls).toContain(
+      'https://api.example.test/api/v1/sites/kept/forms/compliance',
+    )
+  })
+
+  it('falls back to the slug-free route when the build has no baked slug', async () => {
+    const { calls } = stubCompliance(true)
+    await mountForm({ siteSlug: '' })
+    // Never the broken `/sites//forms/...` shape (the kimduffhomes.com 405).
+    expect(calls).toContain('https://api.example.test/api/v1/forms/compliance')
+    expect(calls.some((u) => u.includes('/sites//'))).toBe(false)
+  })
+
+  it('memoizes one verdict per site so N forms on a page cost ONE round trip', async () => {
+    const { impl } = stubCompliance(true)
+    const opts = { apiBase: 'https://api.example.test/api/v1', siteSlug: 'kept' }
+    const [a, b, c] = await Promise.all([
+      fetchSiteHandlesPhi(opts),
+      fetchSiteHandlesPhi(opts),
+      fetchSiteHandlesPhi(opts),
+    ])
+    expect([a, b, c]).toEqual([true, true, true])
+    expect(impl).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports false — and renders nothing — when the endpoint fails', async () => {
+    stubCompliance(true, { ok: false })
+    const wrapper = await mountForm()
+    expect(wrapper.find(GUIDANCE).exists()).toBe(false)
+  })
+
+  it('reports false when the endpoint is unreachable', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        throw new Error('network down')
+      }),
+    )
+    await expect(
+      fetchSiteHandlesPhi({ apiBase: 'https://api.example.test/api/v1', siteSlug: 'kept' }),
+    ).resolves.toBe(false)
+  })
+
+  it('treats a body without a boolean verdict as NO verdict, never as yes', async () => {
+    // A 200 from an SPA shell / proxy interstitial must not be read as "PHI
+    // tenant" — the same class of failure C-301/C-310 hardened the POST against.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({ ok: true, status: 200, json: async () => ({ siteHandlesPhi: 'true' }) }) as unknown as Response),
+    )
+    await expect(
+      fetchSiteHandlesPhi({ apiBase: 'https://api.example.test/api/v1', siteSlug: 'kept' }),
+    ).resolves.toBe(false)
+  })
+})

package/src/__tests__/receipt-validation.test.ts

@@ -0,0 +1,425 @@
+/**
+ * C-310 — a 2xx with valid JSON is NOT proof of storage. Only the endpoint's own
+ * receipt is.
+ *
+ * The gap this closes (Codex cross-model review §c, 2026-07-26): C-301/C-302
+ * hardened TRANSPORT parsing — an HTML shell, an empty body, or an unreadable
+ * stream all became visible failures. Anything that parsed as JSON still passed,
+ * so `{}`, `[]`, `"ok"` and `{"hello":"world"}` were all reported to the visitor
+ * as a stored lead. And `204` was exempt from the body check entirely, even
+ * though no guarded endpoint contracts `204`.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import DcsForm from '../DcsForm.vue'
+import { submitFormValues } from '../composables/useFormSubmission'
+import {
+  isBookingCancellationReceipt,
+  isEstimateReceipt,
+  isManagedFormReceipt,
+  isPasswordlessVerifyReceipt,
+  isSiteContactReceipt,
+  readExpectedJson,
+} from '../composables/readExpectedJson'
+import type { DcsFormSubmitError, PortalFormDefinition } from '../types'
+
+const def: PortalFormDefinition = {
+  formId: 'contact',
+  submission: { kind: 'lead' },
+  fields: [
+    { id: 'name', type: 'text', label: 'Name', required: true },
+    { id: 'email', type: 'email', label: 'Email', required: true },
+  ],
+}
+
+/** `202` + `PublicSiteFormSubmissionResponse` — public_site_forms.go:509-524. */
+const MANAGED_FORM_RECEIPT = {
+  id: '07438812886145977836-dd5a5baf3835082c',
+  status: 'accepted',
+  submittedAt: '2026-07-26T14:52:30Z',
+  message: 'Thanks — your form has been received.',
+  notificationQueued: true,
+}
+
+/** `201` + `ContactFormResponse` — contact_form.go:814-823. */
+const SITE_CONTACT_RECEIPT = {
+  id: '3f2504e0-4f89-11d3-9a0c-0305e82c3301',
+  status: 'submitted',
+  submittedAt: '2026-07-26T14:52:30Z',
+  message: 'Thank you for reaching out! A member of the team will respond soon.',
+}
+
+/** `201` + `mapSiteVisitorEstimateResponse` — revenue_estimate_visitor.go:1419. */
+const ESTIMATE_RECEIPT = {
+  id: '01J8Z9QKX2P7B3M4N5R6S7T8U9',
+  siteId: 'iron-oak-contractors',
+  customerEmail: 'jane@example.com',
+  status: 'pending_ai_review',
+}
+
+let consoleError: ReturnType<typeof vi.spyOn>
+beforeEach(() => {
+  consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+})
+afterEach(() => {
+  consoleError.mockRestore()
+})
+
+/**
+ * A fetch stub that answers with a FRESH Response per call.
+ *
+ * It used to `mockResolvedValue` one Response instance, which was only safe
+ * while `<DcsForm>` made exactly one request per mount. C-415 added a
+ * mount-time GET of the form-compliance posture, so a shared instance had its
+ * body consumed by the GET and the submission then failed with "body already
+ * read" — a harness artifact, not a product defect. A real transport hands out
+ * a new Response per request; so does this now.
+ */
+function respond(body: BodyInit | null, init: ResponseInit): typeof fetch {
+  return vi.fn().mockImplementation(async () => new Response(body, init)) as unknown as typeof fetch
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Transport layer: the removed 204 exemption
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('C-310: the 204 exemption is gone', () => {
+  // KILL-TEST. On pre-C-310 code `readOkBody` returned `null` for a bodyless 204
+  // and `submitFormValues` resolved, so this expectation FAILS on the old tree —
+  // which is the whole point of asserting it.
+  it('a bodyless 204 is a FAILURE, not a quiet success', async () => {
+    const fetchImpl = respond(null, { status: 204 })
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ status: 204, nonJsonResponse: true })
+    expect(fetchImpl).toHaveBeenCalledTimes(1)
+  })
+
+  it('the diagnostic explains WHY 204 is no longer trusted', async () => {
+    const response = new Response(null, { status: 204 })
+    await expect(readExpectedJson(response, isManagedFormReceipt)).rejects.toThrow(
+      'We could not confirm your message was received',
+    )
+    const logged = String(consoleError.mock.calls[0][0])
+    expect(logged).toContain('empty body')
+    expect(logged).toContain('204')
+  })
+
+  it('a 204 that DOES carry a JSON receipt is still accepted', async () => {
+    // Belt and braces: the removal is about the EMPTY-body exemption, not about
+    // banning the status. If some hop ever answers 204 with a real receipt, the
+    // receipt is what decides.
+    const response = new Response(JSON.stringify(MANAGED_FORM_RECEIPT), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+    await expect(readExpectedJson(response, isManagedFormReceipt)).resolves.toEqual(
+      MANAGED_FORM_RECEIPT,
+    )
+  })
+})
+
+// ───────────────────────────────────────────────────────────────────────────
+// Receipt layer: valid JSON that proves nothing
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('C-310: valid JSON without a receipt is a FAILURE', () => {
+  const notReceipts: Array<[string, unknown]> = [
+    ['an empty object', {}],
+    ['an empty array', []],
+    ['a bare JSON string', 'ok'],
+    ['a bare JSON number', 1],
+    ['JSON null', null],
+    ['an unrelated object', { hello: 'world' }],
+    ['a receipt missing its id', { status: 'accepted', submittedAt: '2026-07-26T14:52:30Z' }],
+    ['a receipt with a blank id', { id: '   ', status: 'accepted', submittedAt: '2026-07-26T14:52:30Z' }],
+    ['a receipt with an unknown status', { id: 'S-1', status: 'maybe', submittedAt: '2026-07-26T14:52:30Z' }],
+    ['a receipt missing submittedAt', { id: 'S-1', status: 'accepted' }],
+    ['a receipt with an unparseable submittedAt', { id: 'S-1', status: 'accepted', submittedAt: 'soon' }],
+    // The exact shape the pre-C-310 test suite asserted as a success. It is not
+    // a shape the server can produce; testing against it is how a client drifts
+    // away from its own API with every test still green.
+    ['the invented pre-C-310 test shape', { status: 'accepted', submissionId: 'S-1' }],
+  ]
+
+  for (const [label, body] of notReceipts) {
+    it(`rejects ${label}`, async () => {
+      const fetchImpl = respond(JSON.stringify(body), {
+        status: 202,
+        headers: { 'content-type': 'application/json' },
+      })
+      await expect(
+        submitFormValues({
+          apiBase: 'https://api.example.com/api/v1',
+          siteSlug: 'kept',
+          fetchImpl,
+          payload: { formId: 'contact', values: { name: 'Jane' } },
+        }),
+      ).rejects.toMatchObject({ status: 202, unconfirmedReceipt: true, nonJsonResponse: false })
+      // TERMINAL: an unconfirmable submission must never be retried, or a lead
+      // that WAS stored gets stored twice.
+      expect(fetchImpl).toHaveBeenCalledTimes(1)
+    })
+  }
+
+  it('accepts the real managed-form receipt', async () => {
+    const result = await submitFormValues({
+      apiBase: 'https://api.example.com/api/v1',
+      siteSlug: 'kept',
+      fetchImpl: respond(JSON.stringify(MANAGED_FORM_RECEIPT), {
+        status: 202,
+        headers: { 'content-type': 'application/json' },
+      }),
+      payload: { formId: 'contact', values: { name: 'Jane' } },
+    })
+    expect(result.response).toEqual(MANAGED_FORM_RECEIPT)
+    expect(consoleError).not.toHaveBeenCalled()
+  })
+
+  it('separates a receipt failure from a transport failure on the error object', async () => {
+    // The two have different remedies: `nonJsonResponse` means "check routing",
+    // `unconfirmedReceipt` means "check the endpoint contract".
+    const html = respond('<!doctype html><html></html>', {
+      status: 200,
+      headers: { 'content-type': 'text/html' },
+    })
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl: html,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ nonJsonResponse: true, unconfirmedReceipt: false })
+  })
+})
+
+// ───────────────────────────────────────────────────────────────────────────
+// C-319: the spam-quarantine shapes are the GENUINE receipts
+// ───────────────────────────────────────────────────────────────────────────
+
+describe("C-319: a quarantine response is the route's genuine receipt", () => {
+  // C-310 pinned a deliberate WIDENING here: `isLegacySpamOkReceipt` accepted a
+  // bare `{"status":"ok"}` because two of the five spam-quarantine paths
+  // answered that instead of their endpoint's real receipt, and rejecting it
+  // would have shown a visible failure to every quarantined submitter —
+  // including an AI false-positive victim whose message really was stored.
+  //
+  // C-319 removed the cause, so the widening is gone with it. All five
+  // quarantine paths now answer the route's genuine success receipt, built by
+  // the same writer the success path uses (server spam_receipts.go) from the
+  // row C-307 stores. These tests are the inverse of the ones they replace: the
+  // legacy shape must now FAIL, and the real quarantine receipts must PASS.
+
+  it('managed forms: the legacy 202 {"status":"ok"} is no longer a receipt', async () => {
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl: respond(JSON.stringify({ status: 'ok' }), {
+          status: 202,
+          headers: { 'content-type': 'application/json' },
+        }),
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toThrow()
+  })
+
+  it('managed forms: a quarantined submission still resolves as success', async () => {
+    // What the server now answers a spam-classified managed-form submission
+    // with — indistinguishable from a genuine 202, because it IS one.
+    const result = await submitFormValues({
+      apiBase: 'https://api.example.com/api/v1',
+      siteSlug: 'kept',
+      fetchImpl: respond(JSON.stringify(MANAGED_FORM_RECEIPT), {
+        status: 202,
+        headers: { 'content-type': 'application/json' },
+      }),
+      payload: { formId: 'contact', values: { name: 'Buy cheap SEO' } },
+    })
+    expect(result.response).toEqual(MANAGED_FORM_RECEIPT)
+    expect(consoleError).not.toHaveBeenCalled()
+  })
+
+  it('managed forms: the DcsForm UI shows the success state for a quarantined spammer', async () => {
+    const originalFetch = globalThis.fetch
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = respond(
+      JSON.stringify(MANAGED_FORM_RECEIPT),
+      { status: 202, headers: { 'content-type': 'application/json' } },
+    )
+
+    const wrapper = mount(DcsForm, {
+      props: { formId: 'contact', siteSlug: 'kept', definitionOverride: def, apiBase: '' },
+    })
+    await wrapper.find('[data-form-field-key="name"] input').setValue('Buy cheap SEO')
+    await wrapper.find('[data-form-field-key="email"] input').setValue('spam@example.com')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(wrapper.emitted('submit-error')).toBeUndefined()
+    expect(wrapper.emitted('submit-success')?.length).toBe(1)
+
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = originalFetch
+  })
+
+  it('site contact: the legacy {"status":"ok"} no longer satisfies the predicate', () => {
+    expect(isSiteContactReceipt({ status: 'ok' })).toBe(false)
+    expect(isManagedFormReceipt({ status: 'ok' })).toBe(false)
+  })
+
+  it('site contact: a quarantined submission answers the genuine 201 receipt', async () => {
+    await expect(
+      readExpectedJson(jsonResponse(SITE_CONTACT_RECEIPT, 201), isSiteContactReceipt),
+    ).resolves.toEqual(SITE_CONTACT_RECEIPT)
+  })
+
+  it('the estimate honeypot decoy stays indistinguishable from a genuine estimate', () => {
+    // The honeypot answers a 201 built by the same writer and row constructor a
+    // genuine estimate uses, so `id` is a real ULID and the predicate passes.
+    // If it did not, a bot could detect the honeypot from the client's behaviour.
+    expect(isEstimateReceipt({ ...ESTIMATE_RECEIPT, id: '01J8ZDECOY0000000000000000' })).toBe(true)
+  })
+})
+
+// ───────────────────────────────────────────────────────────────────────────
+// Per-endpoint predicates (exported for the site backports)
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('C-310: per-endpoint receipt predicates', () => {
+  it('site contact requires an id and a contract status', async () => {
+    await expect(
+      readExpectedJson(jsonResponse(SITE_CONTACT_RECEIPT, 201), isSiteContactReceipt),
+    ).resolves.toEqual(SITE_CONTACT_RECEIPT)
+    expect(isSiteContactReceipt({ id: 'c-1', status: 'processing' })).toBe(true)
+    expect(isSiteContactReceipt({ id: 'c-1', status: 'accepted' })).toBe(false)
+    expect(isSiteContactReceipt({ status: 'submitted' })).toBe(false)
+  })
+
+  it('estimate requires the returned estimate id', async () => {
+    await expect(
+      readExpectedJson(jsonResponse(ESTIMATE_RECEIPT, 201), isEstimateReceipt),
+    ).resolves.toEqual(ESTIMATE_RECEIPT)
+    expect(isEstimateReceipt({ siteId: 'iron-oak-contractors' })).toBe(false)
+    expect(isEstimateReceipt({ id: '' })).toBe(false)
+  })
+
+  it('passwordless verification requires success === true', async () => {
+    await expect(
+      readExpectedJson(
+        jsonResponse({ success: true, redirectTo: 'https://example.com/account' }),
+        isPasswordlessVerifyReceipt,
+      ),
+    ).resolves.toMatchObject({ success: true })
+    expect(isPasswordlessVerifyReceipt({ success: false })).toBe(false)
+    expect(isPasswordlessVerifyReceipt({ success: 'true' })).toBe(false)
+    expect(isPasswordlessVerifyReceipt({ redirectTo: '/account' })).toBe(false)
+  })
+
+  it('booking cancellation requires success === true', async () => {
+    await expect(
+      readExpectedJson(
+        jsonResponse({ success: true, message: 'Booking cancelled successfully' }),
+        isBookingCancellationReceipt,
+      ),
+    ).resolves.toMatchObject({ success: true })
+    expect(isBookingCancellationReceipt({ success: false })).toBe(false)
+    expect(isBookingCancellationReceipt({ message: 'Booking cancelled successfully' })).toBe(false)
+  })
+})
+
+// ───────────────────────────────────────────────────────────────────────────
+// A submission POST must never follow a redirect
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('C-310: submission POSTs never follow redirects', () => {
+  it("sets redirect:'error' on the JSON POST", async () => {
+    const fetchImpl = respond(JSON.stringify(MANAGED_FORM_RECEIPT), {
+      status: 202,
+      headers: { 'content-type': 'application/json' },
+    })
+    await submitFormValues({
+      apiBase: 'https://api.example.com/api/v1',
+      siteSlug: 'kept',
+      fetchImpl,
+      payload: { formId: 'contact', values: { name: 'Jane' } },
+    })
+    const [, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect((init as RequestInit).redirect).toBe('error')
+  })
+
+  it("sets redirect:'error' on the multipart POST", async () => {
+    const fetchImpl = respond(JSON.stringify(MANAGED_FORM_RECEIPT), {
+      status: 202,
+      headers: { 'content-type': 'application/json' },
+    })
+    await submitFormValues({
+      apiBase: 'https://api.example.com/api/v1',
+      siteSlug: 'kept',
+      fetchImpl,
+      payload: {
+        formId: 'contact',
+        values: { photo: new File(['x'], 'x.png', { type: 'image/png' }) },
+      },
+    })
+    const [, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect((init as RequestInit).redirect).toBe('error')
+  })
+
+  it('surfaces a rejected redirect as a visible failure', async () => {
+    // A 301/302 also rewrites the POST into a GET, so following one silently
+    // drops the submission body. `redirect:'error'` makes fetch reject instead.
+    const fetchImpl = vi
+      .fn()
+      .mockRejectedValue(new TypeError('Failed to fetch')) as unknown as typeof fetch
+    await expect(
+      submitFormValues({
+        apiBase: 'https://api.example.com/api/v1',
+        siteSlug: 'kept',
+        fetchImpl,
+        retries: 0,
+        payload: { formId: 'contact', values: { name: 'Jane' } },
+      }),
+    ).rejects.toMatchObject({ payload: { formId: 'contact' } })
+  })
+})
+
+// ───────────────────────────────────────────────────────────────────────────
+// UI level
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('C-310: the DcsForm UI never shows success without a receipt', () => {
+  it('a 202 {} is a visible failure, not a success state', async () => {
+    const originalFetch = globalThis.fetch
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = respond('{}', {
+      status: 202,
+      headers: { 'content-type': 'application/json' },
+    })
+
+    const wrapper = mount(DcsForm, {
+      props: { formId: 'contact', siteSlug: 'kept', definitionOverride: def, apiBase: '' },
+    })
+    await wrapper.find('[data-form-field-key="name"] input').setValue('Jane')
+    await wrapper.find('[data-form-field-key="email"] input').setValue('jane@example.com')
+    await wrapper.find('form').trigger('submit')
+    await flushPromises()
+
+    expect(wrapper.emitted('submit-success')).toBeUndefined()
+    const emitted = wrapper.emitted('submit-error')?.[0]?.[0] as DcsFormSubmitError
+    expect(emitted.unconfirmedReceipt).toBe(true)
+    expect(wrapper.text()).toContain('We could not confirm your message was received')
+
+    ;(globalThis as unknown as { fetch: typeof fetch }).fetch = originalFetch
+  })
+})