Plan: Worker intake + program independence (SNAP + TANF)

┌─────────────────────── canopy-web ───────────────────────┐
│  GET /applications/{id}/intake/{program}                 │
│   └─ get_intake_application() — NEW handler              │
│       Validates {program} is in the app's                │
│       programs_requested AND in session.primary_programs.│
│       Returns 404 otherwise.                             │
│       └─ Askama: templates/applications/intake.html      │
│           ├─ 9-step stepper (top)                        │
│           └─ Single-program section accordion            │
│              (9 SNAP sections OR 10 TANF — exactly       │
│              ONE program per page render).               │
│                                                          │
│  PUT /applications/{id}/sections/{program}/{section}     │
│   └─ save_intake_section() — proxies to canopy-apps      │
│                                                          │
│  POST /applications/{id}/programs/{program}/complete     │
│   └─ complete_data_collection() — proxies; canopy-apps   │
│      validates all required sections completed.          │
│                                                          │
│  POST /applications/{id}/run-determination?program={p}   │
│   └─ run_determination() — NEW handler. Replaces         │
│      `case_detail.rs:2516` handler entirely (pre-1.0).   │
│      Takes application_id from path AND program from     │
│      query string — per-program scoped. Posts to         │
│      canopy-eligibility with the single program.         │
└──────────────────────────────────────────────────────────┘
                            │
                            ▼ (HTTP via ServiceClients)
┌─────────────────── canopy-applications ───────────────────┐
│  PUT /v1/applications/{id}/sections/{program}/{section}   │
│   └─ upsert_section() — NEW. Integrity guards:            │
│       (i) program is in the app's active                  │
│           application_programs.program set;               │
│       (ii) section_name in SectionName::                  │
│            applicable_programs(program).                  │
│       Returns 422 on either violation.                    │
│  GET /v1/applications/{id}/sections — NEW                 │
│  POST /v1/applications/{id}/programs/{program}/complete   │
│   └─ NEW. Backend GATE: verifies that every section in    │
│      SectionName::applicable_programs(program) has a row  │
│      in application_sections with completed_at IS NOT NULL│
│      for this (application_id, program). Returns 422      │
│      "incomplete sections: [list]" if any are missing.    │
│      On pass: sets application_programs.status=           │
│      'data_collected' AND recomputes applications.status  │
│      ('submitted'→'processing' on first transition;       │
│      'processing'→'closed' if all program rows terminal). │
│      Emits application_section.completed.                 │
│                                                           │
│  Table: application_sections                              │
│   UNIQUE (application_id, program, section_name)          │
│         WHERE active = true                               │
│                                                           │
│  Outbox emit: application_section.updated                 │
│   (PII allowlist INCLUDES household_id — see §7)          │
└───────────────────────────────────────────────────────────┘

GET /cases/{household_id} (existing case-detail composition)
  ▼ dispatched via dispatch_fetch(item, ctx) at sections.rs:166
audit::fetch(clients, household_id, session, program, item)
  ▼ (HTTP)
GET /v1/security/events?household_id={hh}&limit=50
GET /v1/security/verify-chain   ← general audit chain (not FTI)
  ▼
finalize_section_html(html, item, DISPLAY_NAME) → RenderedSection

Login as jane.snap-worker        Login as jane.tanf-worker
  │ Keycloak attr                  │ Keycloak attr
  │ primary_programs=["snap"]      │ primary_programs=["tanf"]
  ▼ oidc-usermodel-attribute-      ▼ oidc-usermodel-attribute-
    mapper → JWT claim               mapper → JWT claim
Claims.primary_programs           Claims.primary_programs
= vec!["snap"]                    = vec!["tanf"]
  │                                │
  ▼                                ▼
SessionData.primary_programs    SessionData.primary_programs
  │                                │
  ▼                                ▼
MyQueue.fetch_items(_, session) MyQueue.fetch_items(_, session)
  │ filter by primary_programs    │ filter by primary_programs
  │ link → /intake/snap           │ link → /intake/tanf
  ▼                                ▼
Sees ONLY SNAP intake page      Sees ONLY TANF intake page
on the shared application       on the SAME shared application

Same household, same applications row, separate application_programs
rows, separate application_sections rows, separate documents.
Independence is enforced by per-program tables + per-worker URL
scoping, NOT by separate application rows.

// crates/canopy-common/src/id.rs — append next to existing newtypes
define_id!(
    /// Unique identifier for an applicant-uploaded document
    /// (canopy-applications documents store; Plan 3 surface).
    DocumentId
);

// SPDX-License-Identifier: AGPL-3.0-or-later
use serde::{Deserialize, Serialize};
use validator::Validate;
use canopy_common::id::{ApplicationId, HouseholdId, PersonId};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, utoipa::ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum SectionName {
    HouseholdComposition,
    Identity,
    Citizenship,
    Residency,
    IncomeEmployment,
    Resources,                   // SNAP-only
    ExpensesShelter,             // SNAP-only
    WorkRegistration,
    SpecialCircumstances,
    TanfChildSupport,            // TANF-only
    TanfPersonalResponsibility,  // TANF-only
    TanfTimeLimits,              // TANF-only
}

impl SectionName {
    // Return slugs (not `Program` typed) so comparison with
    // applications.programs_requested: TEXT[] is direct.
    pub fn applicable_programs(&self) -> &'static [&'static str] {
        match self {
            Self::Resources | Self::ExpensesShelter => &["snap"],
            Self::TanfChildSupport
            | Self::TanfPersonalResponsibility
            | Self::TanfTimeLimits => &["tanf"],
            _ => &["snap", "tanf"], // 7 shared sections
        }
    }
    pub fn display_name_key(&self) -> &'static str { /* fluent key */ }
    pub fn icon(&self) -> &'static str { /* lucide slug */ }
    /// Documentary advisory only (§13). NOT validated by xtask policy.
    pub fn pamms_citation(&self) -> &'static str { /* e.g. "PAMMS dfcs-snap §2050" */ }
}

/// Wire-side payload — typed-per-section. The handler dispatches the
/// JSON body to the right struct based on the `section_name` URL path
/// segment, NOT a serde-tag discriminator.
pub mod payloads {
    use super::*;

    /// Workflow-record payload — captures the worker's verification
    /// ACTION on the named person, not the underlying identity facts.
    /// Per ADR-001 + ADR-002: SSN / DOB / legal name are owned by
    /// canopy-persons (system of record, encrypted at rest). The intake
    /// page surfaces canopy-persons CRUD via a separate "Edit person
    /// record" affordance; that flow PUTs to canopy-persons directly
    /// and never traverses canopy-applications.
    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema, Validate)]
    pub struct IdentityPayload {
        pub person_id: PersonId,
        pub verification_method: IdentityVerificationMethod,
        pub document_evidence_id: Option<canopy_common::id::DocumentId>,
        pub verified_at: chrono::DateTime<chrono::Utc>,
        #[validate(length(max = 500))]
        pub worker_notes: Option<String>,
    }

    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
    #[serde(rename_all = "snake_case")]
    pub enum IdentityVerificationMethod {
        DriversLicense, StateId, Passport, BirthCertificate,
        TribalId, CollateralContact, ApplicantStatement,
    }

    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema, Validate)]
    pub struct HouseholdCompositionPayload {
        #[validate(length(min = 1))]
        pub members: Vec<HouseholdMemberRef>,
        pub head_of_household_person_id: PersonId,
        pub relationships_confirmed: bool,
    }

    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
    pub struct HouseholdMemberRef {
        pub person_id: PersonId,
        pub relationship_to_head: String,
        pub purchases_and_prepares_meals_with_head: Option<bool>,
    }

    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema, Validate)]
    pub struct CitizenshipPayload {
        pub person_id: PersonId,
        pub verification_method: CitizenshipVerificationMethod,
        pub save_case_number: Option<String>,
        pub document_evidence_id: Option<canopy_common::id::DocumentId>,
        pub verified_at: chrono::DateTime<chrono::Utc>,
        #[validate(length(max = 500))]
        pub worker_notes: Option<String>,
    }

    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
    #[serde(rename_all = "snake_case")]
    pub enum CitizenshipVerificationMethod {
        BirthCertificate, Passport, Naturalization,
        SaveQuery, CollateralContact, ApplicantStatement,
    }

    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema, Validate)]
    pub struct ResidencyPayload {
        pub address_person_id: PersonId,
        pub verification_method: ResidencyVerificationMethod,
        pub same_as_application_address: bool,
    }

    #[derive(Debug, Clone, Serialize, Deserialize, utoipa::ToSchema)]
    #[serde(rename_all = "snake_case")]
    pub enum ResidencyVerificationMethod {
        UtilityBill, RentalAgreement, MortgageStatement, MailFromGovAgency,
        CollateralContact, ApplicantStatement,
    }

    // Remaining 8 payload structs (IncomeEmployment, Resources,
    // ExpensesShelter, WorkRegistration, SpecialCircumstances,
    // TanfChildSupport, TanfPersonalResponsibility, TanfTimeLimits)
    // follow the same architectural principle:
    //   - Reference (PersonId | HouseholdId | IncomeRecordId | ...) into
    //     canopy-persons / canopy-applications-owned data;
    //   - Record only WORKFLOW metadata (verification method, document
    //     references, worker notes, timestamps);
    //   - Never duplicate the underlying facts.
    // MR1 spells each out (~30-40 LOC per struct). Total contracts
    // module ~700 LOC.
}

pub mod paths {
    pub const PUT_SECTION: &str =
        "/v1/applications/{id}/sections/{program}/{section}";
    pub const LIST_SECTIONS: &str = "/v1/applications/{id}/sections";
    pub const COMPLETE_DATA_COLLECTION: &str =
        "/v1/applications/{id}/programs/{program}/complete-data-collection";
}

-- SPDX-License-Identifier: AGPL-3.0-or-later
-- Plan 1 MR2 — per-program intake-section storage.

CREATE TABLE application_sections (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    application_id UUID NOT NULL REFERENCES applications(id),
    program TEXT NOT NULL,
    section_name TEXT NOT NULL,
    payload JSONB NOT NULL,
    completed_at TIMESTAMPTZ,
    last_edited_by UUID NOT NULL,  -- Keycloak `sub`; not FK'd (workers aren't in canopy-persons)
    active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX application_sections_unique
    ON application_sections (application_id, program, section_name)
    WHERE active = true;

CREATE INDEX application_sections_app_program_idx
    ON application_sections (application_id, program)
    WHERE active = true;

CREATE INDEX application_sections_last_edited_by_idx
    ON application_sections (last_edited_by) WHERE active = true;

-- SPDX-License-Identifier: AGPL-3.0-or-later
-- Plan 1 MR2 — formalize status vocabulary.

-- Advisory lock so a concurrent INSERT cannot slip a rogue status
-- value between the UPDATE backfill and the ALTER ADD CONSTRAINT.
-- Lock ID 0xCA40 = 51776 (CA = Canopy, 40 = applications-status migration).
SELECT pg_advisory_xact_lock(51776);

-- applications.status: existing 'pending' rows (~9 PendingVerification
-- personas per generate.rs:401-413) normalize to 'submitted'.
UPDATE applications SET status = 'submitted'
WHERE status NOT IN (
    'submitted','processing','data_collected','determined',
    'withdrawn','denied','approved'
);

-- application_programs.status: include 'processing' defensively even
-- though no current writer exists for that value (verified via grep).
UPDATE application_programs SET status = 'pending'
WHERE status NOT IN (
    'pending','processing','data_collected','determined','approved','denied','withdrawn'
);

ALTER TABLE applications ADD CONSTRAINT applications_status_check
    CHECK (status IN (
        'submitted','processing','data_collected','determined',
        'withdrawn','denied','approved'
    ));

ALTER TABLE application_programs ADD CONSTRAINT application_programs_status_check
    CHECK (status IN (
        'pending','processing','data_collected','determined','approved','denied','withdrawn'
    ));

ApplicationSectionUpdatedEvent {
    application_id: ApplicationId,
    household_id: HouseholdId,    // INCLUDED — case identifier
    program: Program,
    section_name: SectionName,
    completed: bool,
    last_edited_by: WorkerId,
    occurred_at: DateTime<Utc>,
    // NO payload, NO diff, NO field values, NO SSN, NO DOB
}

0:00  Log in as jane.snap-worker.
0:20  MyQueue filtered to apps containing SNAP. Open Maria Lopez's app →
       link target /applications/{app_id}/intake/snap (per-program URL
       — the SNAP worker lands ONLY on the SNAP-scoped page).
0:40  Walk 3 SNAP sections (Identity, Household, Income). htmx
       auto-save badge confirms each.
1:30  Click "Complete Data Collection". Backend gates: every SNAP-
       applicable section has completed_at IS NOT NULL → 200; sets
       application_programs.status='data_collected' for SNAP; recomputes
       applications.status='processing' (TANF row still 'pending').
1:45  Click "Run Determination". Per-application verification gate
       (GET /v1/verifications?application_id=&status=pending&limit=1)
       returns empty → POST /applications/{app_id}/run-determination?
       program=snap triggers eligibility; verdict populates.
2:15  Click Audit tab on case detail. Hash-chain-verified events for
       THIS household via /v1/security/verify-chain (typed
       ChainVerificationResponse); chain badge "Verified".
2:45  Log out. Log in as jane.tanf-worker.
3:00  MyQueue shows the SAME application (programs_requested contains
       TANF, applications.status='processing'). Click → lands on
       /applications/{app_id}/intake/tanf (per-program URL — TANF
       worker never sees SNAP's data). Notice: SNAP's completed
       sections do NOT appear; the TANF tab's sections are
       independently 'not started'.
3:45  Walk 2 TANF sections (Identity, ChildSupport).
4:15  Audit tab now shows a SEPARATE causal trail entry for the TANF
       work — both chains valid; neither leaks.
4:30  Cut. (Plan 1 partial demo: ~4.5 min; Plans 2+3 contribute the
       remaining 5.5 min via applicant submission + ELE flag.)

cargo xtask dev refresh
cargo xtask seed --profile demo --reset

# DB sanity — MR6 seeds 2 sections per (application, program) pair across
# the 3 extended archetypes × 2 programs each = at minimum 12 rows.
psql -c "SELECT COUNT(*) FROM application_sections WHERE active = true;"
# Expect: ≥ 12 rows

# API surface
TOKEN=$(./scripts/get-token.sh jane.snap-worker)
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8083/v1/applications/{id}/sections
curl -H "Authorization: Bearer $TOKEN" -X PUT \
  http://localhost:8083/v1/applications/{id}/sections/snap/identity \
  -d '{...}'
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8084/v1/security/events?household_id={hh}&limit=5"
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8084/v1/security/verify-chain"

# Test gates
cargo nextest run -p canopy-applications -p canopy-web -p canopy-security -p canopy-auth -p canopy-verification -p canopy-renewals
cargo xtask e2e -- intake.spec.ts

# Project gates
cargo xtask validate
cargo xtask policy audit            # ADR-011 (existing thresholds)
cargo xtask policy audit-literals
cargo xtask policy audit-unwraps
cargo xtask demo verify             # ADR-025 cross-service ref validator