Merge branch 'main' into jzh

feat(contacts): confirm platform contact upgrades
feat(members): confirm external contact upgrades
2026-07-27 17:56:29 +08:00 · 2026-07-27 17:53:22 +08:00 · 2026-07-27 17:39:44 +08:00 · 2026-07-27 09:36:44 +00:00 · 2026-07-27 09:32:52 +00:00 · 2026-07-27 09:24:58 +00:00
655 changed files with 66012 additions and 7184 deletions
@@ -29,13 +29,13 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: ${{ matrix.python-version }}
@@ -88,13 +88,13 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: ${{ matrix.python-version }}
@@ -139,13 +139,13 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: "3.12"
@@ -20,7 +20,7 @@ jobs:
        run: echo "autofix.ci updates pull request branches, not merge group refs."

      - if: github.event_name != 'merge_group'
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Check Docker Compose inputs
        if: github.event_name != 'merge_group'
@@ -84,12 +84,12 @@ jobs:
            dify-agent/pyproject.toml
            dify-agent/uv.lock
      - if: github.event_name != 'merge_group'
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.11"

      - if: github.event_name != 'merge_group'
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0

      - name: Generate Docker Compose
        if: github.event_name != 'merge_group' && steps.docker-compose-changes.outputs.any_changed == 'true'
@@ -97,7 +97,7 @@ jobs:
          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV

      - name: Login to Docker Hub
-        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
        with:
          username: ${{ env.DOCKERHUB_USER }}
          password: ${{ env.DOCKERHUB_TOKEN }}
@@ -199,7 +199,7 @@ jobs:
          merge-multiple: true

      - name: Login to Docker Hub
-        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
        with:
          username: ${{ env.DOCKERHUB_USER }}
          password: ${{ env.DOCKERHUB_TOKEN }}
@@ -79,7 +79,7 @@ jobs:
      ws2_app_id:                 ${{ steps.out.outputs.DIFY_E2E_WS2_APP_ID }}

    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
        with:
          ref: ${{ inputs.cli_ref || github.ref }}
          persist-credentials: false
@@ -123,7 +123,7 @@ jobs:
        shell: bash

    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
        with:
          ref: ${{ inputs.cli_ref || github.ref }}
          persist-credentials: false
@@ -170,7 +170,7 @@ jobs:
        shell: bash

    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
        with:
          ref: ${{ inputs.cli_ref || github.ref }}
          persist-credentials: false
@@ -233,7 +233,7 @@ jobs:
        shell: bash

    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
        with:
          ref: ${{ inputs.cli_ref || github.ref }}
          persist-credentials: false
@@ -295,7 +295,7 @@ jobs:
        shell: bash

    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
        with:
          ref: ${{ inputs.cli_ref || github.ref }}
          persist-credentials: false
@@ -351,7 +351,7 @@ jobs:
        shell: bash

    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
        with:
          ref: ${{ inputs.cli_ref || github.ref }}
          persist-credentials: false
@@ -23,7 +23,7 @@ jobs:
        working-directory: ./cli
    steps:
      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 0
@@ -35,7 +35,7 @@ jobs:
      dify_tag: ${{ steps.resolve.outputs.dify_tag }}
    steps:
      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -98,7 +98,7 @@ jobs:
      DIFY_TAG: ${{ needs.validate.outputs.dify_tag }}
    steps:
      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 1
@@ -24,7 +24,7 @@ jobs:
        shell: bash
    steps:
      - name: Checkout cli ref
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ inputs.cli_ref || github.ref }}
          persist-credentials: false
@@ -30,7 +30,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -13,13 +13,13 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: "3.12"
@@ -63,13 +63,13 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: "3.12"
@@ -24,7 +24,7 @@ jobs:
    name: Require cherry-pick provenance
    runs-on: depot-ubuntu-24.04
    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

@@ -9,6 +9,6 @@ jobs:
      pull-requests: write
    runs-on: depot-ubuntu-24.04
    steps:
-      - uses: actions/labeler@b8dd2d9be0f68b860e7dae5dae7d772984eacd6d # v6.2.0
+      - uses: actions/labeler@bf12e9b00b37c5c0ca2b87b79b2daf7891dbda13 # v7.0.0
        with:
          sync-labels: true
@@ -47,7 +47,7 @@ jobs:
      migration-changed: ${{ steps.changes.outputs.migration }}
      sandbox-runtime-changed: ${{ steps.changes.outputs.sandbox-runtime }}
    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
        id: changes
        with:
@@ -18,7 +18,7 @@ jobs:
    outputs:
      external-e2e-changed: ${{ steps.changes.outputs.external_e2e }}
    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
        id: changes
        with:
@@ -17,12 +17,12 @@ jobs:
      pull-requests: write
    steps:
      - name: Checkout PR branch
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Setup Python & UV
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true

@@ -21,10 +21,10 @@ jobs:
    if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.pull_requests[0].head.repo.full_name != github.repository }}
    steps:
      - name: Checkout default branch (trusted code)
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Setup Python & UV
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true

@@ -17,12 +17,12 @@ jobs:
      pull-requests: write
    steps:
      - name: Checkout PR branch
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Setup Python & UV
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true

@@ -21,7 +21,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
@@ -45,7 +45,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
@@ -72,7 +72,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
@@ -23,7 +23,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 0
@@ -45,7 +45,7 @@ jobs:

      - name: Setup UV and Python
        if: steps.changed-files.outputs.any_changed == 'true'
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: false
          python-version: "3.12"
@@ -93,7 +93,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -144,7 +144,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -186,7 +186,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
@@ -24,7 +24,7 @@ jobs:
        working-directory: sdks/nodejs-client

    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -40,7 +40,7 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
@@ -158,7 +158,7 @@ jobs:

      - name: Run Claude Code for Translation Sync
        if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@af0559ee4f514d1ef21826982bed13f7edc3c35e # v1.0.178
+        uses: anthropics/claude-code-action@be7b93b1907a4abad570368f3c74b6fe3807510b # v1.0.183
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
@@ -21,7 +21,7 @@ jobs:

    steps:
      - name: Checkout repository
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

@@ -24,7 +24,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -36,7 +36,7 @@ jobs:
          remove_tool_cache: true

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: ${{ matrix.python-version }}
@@ -21,7 +21,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -33,7 +33,7 @@ jobs:
          remove_tool_cache: true

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: ${{ matrix.python-version }}
@@ -26,7 +26,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -34,7 +34,7 @@ jobs:
        uses: ./.github/actions/setup-web

      - name: Setup UV and Python
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          enable-cache: true
          python-version: "3.12"
@@ -29,7 +29,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -62,7 +62,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -100,7 +100,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -132,7 +132,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

@@ -677,6 +677,8 @@ INNER_API_KEY_FOR_PLUGIN=QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y

 # Dify Agent backend
 AGENT_BACKEND_BASE_URL=http://localhost:5050
+# Bearer token sent to the Agent backend /runs API. Must match DIFY_AGENT_API_TOKEN on the server side.
+AGENT_BACKEND_API_TOKEN=dify-agent-run-token-for-dev-only
 AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS=30
 AGENT_BACKEND_STREAM_MAX_RECONNECTS=3
 AGENT_BACKEND_RUN_TIMEOUT_SECONDS=1200
@@ -729,7 +731,6 @@ OTEL_MAX_EXPORT_BATCH_SIZE=512
 OTEL_METRIC_EXPORT_INTERVAL=60000
 OTEL_BATCH_EXPORT_TIMEOUT=10000
 OTEL_METRIC_EXPORT_TIMEOUT=30000
-
 # Prevent Clickjacking
 ALLOW_EMBED=false

@@ -1,10 +1,13 @@
 import logging
 import time
+from collections.abc import Callable
+from typing import NamedTuple

 import socketio
 from flask import request
 from opentelemetry.trace import get_current_span
 from opentelemetry.trace.span import INVALID_SPAN_ID, INVALID_TRACE_ID
+from werkzeug.exceptions import Forbidden, HTTPException, ServiceUnavailable

 from configs import dify_config
 from contexts.wrapper import RecyclableContextVar
@@ -42,6 +45,53 @@ _CONSOLE_EXEMPT_PREFIXES = (
    "/console/api/activate/check",
 )

+_WEBAPP_EXEMPT_PREFIXES = ("/api/system-features",)
+
+_INVALID_LICENSE_STATUSES = (LicenseStatus.INACTIVE, LicenseStatus.EXPIRED, LicenseStatus.LOST)
+
+
+def _session_surface_error(license_status: LicenseStatus | None) -> HTTPException:
+    if license_status is None:
+        return UnauthorizedAndForceLogout("Unable to verify enterprise license. Please contact your administrator.")
+    return UnauthorizedAndForceLogout(f"Enterprise license is {license_status}. Please contact your administrator.")
+
+
+def _bearer_surface_error(license_status: LicenseStatus | None) -> HTTPException:
+    """Token-authed: forcing a logout is meaningless and license state must not leak."""
+    return Forbidden(description="license_required")
+
+
+def _retryable_surface_error(license_status: LicenseStatus | None) -> HTTPException:
+    """Webhook senders retry on 5xx but treat 4xx as permanent, disabling the subscription."""
+    return ServiceUnavailable(description="license_required")
+
+
+class _LicenseGatedSurface(NamedTuple):
+    prefix: str
+    exempt_prefixes: tuple[str, ...]
+    build_error: Callable[[LicenseStatus | None], HTTPException]
+
+
+# /files (plugin-daemon data plane), /inner/api (enterprise control plane) and /health
+# stay ungated: blocking them breaks workflow execution or license recovery itself.
+_LICENSE_GATED_SURFACES = (
+    _LicenseGatedSurface("/console/api/", _CONSOLE_EXEMPT_PREFIXES, _session_surface_error),
+    _LicenseGatedSurface("/api/", _WEBAPP_EXEMPT_PREFIXES, _session_surface_error),
+    _LicenseGatedSurface("/v1", (), _bearer_surface_error),
+    _LicenseGatedSurface("/mcp", (), _bearer_surface_error),
+    _LicenseGatedSurface("/triggers", (), _retryable_surface_error),
+)
+
+
+def _match_license_gated_surface(path: str) -> _LicenseGatedSurface | None:
+    for surface in _LICENSE_GATED_SURFACES:
+        if not path.startswith(surface.prefix):
+            continue
+        if any(path.startswith(exempt) for exempt in surface.exempt_prefixes):
+            return None
+        return surface
+    return None
+

 # ----------------------------
 # Application Factory Function
@@ -62,38 +112,17 @@ def create_flask_app_with_configs() -> DifyApp:
        init_request_context()
        RecyclableContextVar.increment_thread_recycles()

-        # Enterprise license validation for API endpoints (both console and webapp)
-        # When license expires, block all API access except bootstrap endpoints needed
-        # for the frontend to load the license expiration page without infinite reloads.
        if dify_config.ENTERPRISE_ENABLED:
-            is_console_api = request.path.startswith("/console/api/")
-            is_webapp_api = request.path.startswith("/api/")
+            surface = _match_license_gated_surface(request.path)
+            if surface is not None:
+                try:
+                    license_status = EnterpriseService.get_cached_license_status()
+                except Exception:
+                    logger.exception("Failed to check enterprise license status")
+                    license_status = None

-            if is_console_api or is_webapp_api:
-                if is_console_api:
-                    is_exempt = any(request.path.startswith(p) for p in _CONSOLE_EXEMPT_PREFIXES)
-                else:  # webapp API
-                    is_exempt = request.path.startswith("/api/system-features")
-
-                if not is_exempt:
-                    try:
-                        # Check license status (cached — see EnterpriseService for TTL details)
-                        license_status = EnterpriseService.get_cached_license_status()
-                        if license_status in (LicenseStatus.INACTIVE, LicenseStatus.EXPIRED, LicenseStatus.LOST):
-                            raise UnauthorizedAndForceLogout(
-                                f"Enterprise license is {license_status}. Please contact your administrator."
-                            )
-                        if license_status is None:
-                            raise UnauthorizedAndForceLogout(
-                                "Unable to verify enterprise license. Please contact your administrator."
-                            )
-                    except UnauthorizedAndForceLogout:
-                        raise
-                    except Exception:
-                        logger.exception("Failed to check enterprise license status")
-                        raise UnauthorizedAndForceLogout(
-                            "Unable to verify enterprise license. Please contact your administrator."
-                        )
+                if license_status is None or license_status in _INVALID_LICENSE_STATUSES:
+                    raise surface.build_error(license_status)

    # add after request hook for injecting trace headers from OpenTelemetry span context
    # Only adds headers when OTEL is enabled and has valid context
@@ -11,6 +11,7 @@ from clients.agent_backend.fake_client import FakeAgentBackendRunClient, FakeAge
 def create_agent_backend_run_client(
    *,
    base_url: str | None = None,
+    api_token: str | None = None,
    use_fake: bool = False,
    fake_scenario: str | FakeAgentBackendScenario = FakeAgentBackendScenario.SUCCESS,
    stream_read_timeout_seconds: float = 30,
@@ -22,8 +23,11 @@ def create_agent_backend_run_client(
        return FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario(fake_scenario))
    if base_url is None:
        raise ValueError("base_url is required when creating a real Agent backend client")
+    headers: dict[str, str] = {}
+    if api_token:
+        headers["Authorization"] = f"Bearer {api_token}"
    return DifyAgentBackendRunClient(
-        Client(base_url=base_url, stream_timeout=stream_read_timeout_seconds),
+        Client(base_url=base_url, stream_timeout=stream_read_timeout_seconds, headers=headers),
        stream_max_reconnects=stream_max_reconnects,
        stream_timeout_seconds=stream_run_timeout_seconds,
    )
@@ -12,6 +12,11 @@ class AgentBackendConfig(BaseSettings):
        default=None,
    )

+    AGENT_BACKEND_API_TOKEN: str | None = Field(
+        description="Bearer token for authenticating with the Agent backend /runs API.",
+        default=None,
+    )
+
    AGENT_BACKEND_USE_FAKE: bool = Field(
        description="Use the deterministic in-process fake Agent backend client.",
        default=False,
@@ -816,6 +816,41 @@ class UpdateConfig(BaseSettings):
    )


+class CommunityTelemetryConfig(BaseSettings):
+    """
+    Configuration for anonymous self-hosted community telemetry.
+    """
+
+    DISABLE_TELEMETRY: bool = Field(
+        description="Disable anonymous community telemetry",
+        default=False,
+    )
+    DO_NOT_TRACK: bool = Field(
+        description="Respect the standard do-not-track opt-out signal for telemetry",
+        default=False,
+    )
+    TELEMETRY_ENDPOINT: str = Field(
+        description="Endpoint for anonymous community telemetry events",
+        default="https://otel.dify.ai/v1/events",
+    )
+    TELEMETRY_FALLBACK_ENDPOINT: str = Field(
+        description="Fallback endpoint for anonymous community telemetry events",
+        default="https://otel.dify.cn/v1/events",
+    )
+    TELEMETRY_TIMEOUT_SECONDS: PositiveInt = Field(
+        description="HTTP timeout in seconds for anonymous community telemetry requests",
+        default=3,
+    )
+    TELEMETRY_HEARTBEAT_INTERVAL_MINUTES: PositiveInt = Field(
+        description="Celery beat interval in minutes for checking whether heartbeat telemetry is due",
+        default=30,
+    )
+    CI: bool = Field(
+        description="Whether the process is running in CI; telemetry is skipped when true",
+        default=False,
+    )
+
+
 class WorkflowVariableTruncationConfig(BaseSettings):
    WORKFLOW_VARIABLE_TRUNCATION_MAX_SIZE: PositiveInt = Field(
        # 1000 KiB
@@ -1599,6 +1634,7 @@ class FeatureConfig(
    TenantIsolatedTaskQueueConfig,
    ToolConfig,
    UpdateConfig,
+    CommunityTelemetryConfig,
    WorkflowConfig,
    WorkflowNodeExecutionConfig,
    WorkspaceConfig,
@@ -25,6 +25,8 @@ HUMAN_INPUT_FORM_INPUT_EXAMPLE = {


 class HumanInputFormSubmitPayload(BaseModel):
+    """Legacy Human Input v1 submit payload shared by existing runtime surfaces."""
+
    inputs: dict[str, JsonValue] = Field(
        description=(
            "Submitted human input values keyed by output variable name. "
@@ -0,0 +1,984 @@
+"""Shared Human Input v2 transport contracts.
+
+Request DTOs use normal Pydantic coercion and forbid unknown fields. Migration
+input is the sole compatibility exception: it ignores unknown legacy fields,
+defaults a missing version to ``"1"``, rejects any other explicit version, and
+rejects duplicate node IDs. Its transport shape mirrors the frontend migration
+adapter so the generated client can replace the temporary mock without changing
+frontend orchestration.
+Public v2, trusted Service API v2, and legacy v1 submit DTOs stay independent.
+"""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+from typing import Annotated, Literal, Self, Union
+
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, JsonValue, field_validator, model_validator
+
+from core.human_input_v2.entities import (
+    ContactId,
+    EmailProviderType,
+    HumanInputContactType,
+    IMBindingId,
+    IMBindingScope,
+    IMIdentityBindingStatus,
+    IMIdentityId,
+    IMIntegrationStatus,
+    IMProvider,
+    IMSyncRemovalReason,
+    IMSyncResultType,
+    IMSyncRunId,
+    IMSyncRunStatus,
+    OrganizationCandidateId,
+)
+from core.workflow.nodes.human_input.entities import FormInputConfig, UserActionConfig
+from core.workflow.nodes.human_input.entities import HumanInputNodeDataFull as HITLv1NodeData
+from core.workflow.nodes.human_input_v2.entities import Channel
+from core.workflow.nodes.human_input_v2.entities import HumanInputNodeData as HITLv2NodeData
+from fields.base import ResponseModel
+from fields.pagination import PaginationParamsMixin, PaginationResultMixin
+from fields.timestamp import Timestamp
+from libs.helper import EmailStr
+
+
+class _NoExtraModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class _RequestModel(BaseModel):
+    """Base request model that forbids unknown fields while accepting JSON-native values."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class _MigrationInputModel(BaseModel):
+    """Forward-compatible migration input that ignores fields unknown to this backend version."""
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class ContactListQuery(PaginationParamsMixin, _NoExtraModel):
+    """Query params for listing contacts in the workspace directory."""
+
+    group: HumanInputContactType | None = Field(
+        default=None,
+        description="Optional contact type filter. None means all contacts.",
+    )
+    keyword: str | None = Field(default=None, description="Free-text search against contact name or email.")
+
+
+class ContactOptionsQuery(PaginationParamsMixin, _NoExtraModel):
+    """Query params for selecting contacts in workflow editors."""
+
+    keyword: str | None = Field(default=None, description="Free-text search against selectable contact names.")
+
+
+class OrganizationCandidatesQuery(PaginationParamsMixin, _NoExtraModel):
+    """Query params for searching organization member candidates."""
+
+    keyword: str | None = Field(default=None, description="Free-text search against candidate name or email.")
+
+
+ExternalContactName = Annotated[
+    str,
+    Field(
+        min_length=1,
+        max_length=255,
+        description="Display name shown in the contact directory.",
+    ),
+]
+
+ExternalContactEmail = Annotated[
+    EmailStr,
+    Field(
+        description="Primary email used for delivery and identity verification.",
+    ),
+]
+
+ExternalContactAvatar = Annotated[
+    str,
+    Field(
+        description=(
+            "Optional avatar file ID. Upload the avatar image first via "
+            "`POST /console/api/files/upload`, then use the returned file id here."
+            " Set to empty string for resetting to default avatar."
+        ),
+    ),
+]
+
+
+class ExternalContactCreateRequest(_RequestModel):
+    """Request body for creating or updating one external contact."""
+
+    name: ExternalContactName
+    email: ExternalContactEmail
+    avatar: ExternalContactAvatar | None = None
+
+
+class ExternalContactUpdateRequest(_RequestModel):
+    """Request body for creating or updating one external contact."""
+
+    name: ExternalContactName | None = None
+    email: ExternalContactEmail | None = None
+    avatar: ExternalContactAvatar | None = None
+
+
+class IMBinding(BaseModel):
+    id: IMBindingId = Field(description="Unique IM binding identifier.")
+    provider: IMProvider = Field(description="Provider of the IM binding.")
+    scope: IMBindingScope = Field(description="Scope of the IM binding.")
+
+
+class HumanInputContactSummary(BaseModel):
+    """A trimmed version of `HumanInputContact` that only includes the fields needed for workflow orchestration."""
+
+    id: ContactId = Field(description="Unique contact identifier.")
+    name: str = Field(description="Display name shown in the contact directory.")
+    avatar_url: str = Field(default="", description="URL of the contact's avatar.")
+    created_at: Timestamp = Field(description="Timestamp when the contact was created.")
+
+
+class HumanInputContact(BaseModel):
+    """One contact entity returned by contact-related APIs."""
+
+    id: ContactId = Field(description="Unique contact identifier.")
+    type: HumanInputContactType = Field(description="Resolved contact type in the current workspace scope.")
+    name: str = Field(description="Display name shown in the contact directory.")
+    email: str | None = Field(default=None, description="Primary contact email if one exists.")
+    avatar_url: str = Field(default="", description="URL of the contact's avatar.")
+    # the `im_bindings` field is always empty for EXTERNAL contacts
+    im_bindings: list[IMBinding] = Field(
+        default_factory=list[IMBinding],
+        description=(
+            "IM bindings that are bound to this contact. "
+            "Currently, only one IM binding is supported. "
+            "There is at most one IM binding per IM provider."
+        ),
+    )
+
+    created_at: Timestamp = Field(description="Timestamp when the contact was created.")
+
+
+class ContactOption(ResponseModel):
+    """Least-privilege contact projection returned to workflow editors."""
+
+    id: ContactId = Field(description="Unique contact identifier persisted in workflow recipient configuration.")
+    type: HumanInputContactType = Field(description="Resolved contact type in the current workspace scope.")
+    name: str = Field(description="Display name shown in the contact picker.")
+    avatar_url: str | None = Field(default=None, description="Signed avatar URL if one is available.")
+
+
+class ExternalContactCreateResponse(ResponseModel):
+    contact: HumanInputContact = Field(description="The created external contact.")
+
+
+class ExternalContactUpdateResponse(ResponseModel):
+    contact: HumanInputContact = Field(description="The updated external contact. Fields are values after updating.")
+
+
+class OrganizationCandidate(ResponseModel):
+    """One organization member candidate that may become a platform contact."""
+
+    id: OrganizationCandidateId = Field(description="Organization candidate identifier.")
+    name: str = Field(description="Display name shown in the candidate list.")
+    email: str = Field(description="Primary organization email used for matching.")
+    avatar_url: str | None = Field(default=None, description="Signed avatar URL if one is available.")
+
+
+class ListContactsResponse(PaginationResultMixin, ResponseModel):
+    """Paginated response body for contact list APIs."""
+
+    data: list[HumanInputContact] = Field(description="Contacts returned for the current page.")
+
+
+class ListContactOptionsResponse(PaginationResultMixin, ResponseModel):
+    """Paginated editor-safe contact picker response."""
+
+    data: list[ContactOption] = Field(description="Selectable contacts returned for the current page.")
+
+
+class GetContactResponse(ResponseModel):
+    """Response body for one contact resolved in the current workspace scope."""
+
+    contact: HumanInputContact = Field(description="Contact resolved as workspace, platform, or external.")
+
+
+class ListOrganizationCandidatesResponse(PaginationResultMixin, ResponseModel):
+    """Paginated response body for organization candidate search."""
+
+    data: list[OrganizationCandidate] = Field(
+        description="Organization member candidates returned for the current page."
+    )
+
+
+class AddPlatformContactsRequest(_RequestModel):
+    """Request body for adding one or more organization members as platform contacts."""
+
+    candidate_ids: list[OrganizationCandidateId] = Field(
+        ...,
+        min_length=1,
+        description="Organization candidate identifiers to project into the current workspace as platform contacts.",
+    )
+
+
+class AddPlatformContactsResponse(ResponseModel):
+    """Response body for adding platform contacts."""
+
+    data: list[HumanInputContact] = Field(description="Contacts created by the current add operation.")
+
+
+class RemoveContactsRequest(_RequestModel):
+    """Request body for batch-removing platform or external contacts."""
+
+    contact_ids: list[ContactId] = Field(
+        ...,
+        min_length=1,
+        description="Contact identifiers selected for removal from the contact directory surface.",
+    )
+
+
+class RemoveContactsResponse(ResponseModel):
+    """Response body returned after batch-removing contacts."""
+
+    removed_contact_ids: list[ContactId] = Field(description="Contact identifiers removed by the current operation.")
+
+
+class _FeishuLarkIMIntegrationCredentialsBase(_RequestModel):
+    """Shared credential fields for Feishu and Lark integrations."""
+
+    app_id: str = Field(description="Feishu or Lark application identifier.")
+    app_secret: str | PreserveOriginalValue = Field(description="Feishu or Lark application secret.")
+    verification_token: str | PreserveOriginalValue | None = Field(
+        default=None, description="Optional callback verification token."
+    )
+    encrypt_key: str | PreserveOriginalValue | None = Field(default=None, description="Optional callback encrypt key.")
+
+
+class FeishuIMIntegrationCredentials(_FeishuLarkIMIntegrationCredentialsBase):
+    """Feishu integration credentials used by organization-level IM setup."""
+
+    provider: Literal[IMProvider.FEISHU] = Field(description="Discriminator for Feishu integration credentials.")
+
+
+class LarkIMIntegrationCredentials(_FeishuLarkIMIntegrationCredentialsBase):
+    """Lark integration credentials used by organization-level IM setup."""
+
+    provider: Literal[IMProvider.LARK] = Field(description="Discriminator for Lark integration credentials.")
+
+
+class SlackIMIntegrationCredentials(_RequestModel):
+    """Slack integration credentials used by organization-level IM setup."""
+
+    provider: Literal[IMProvider.SLACK] = Field(description="Discriminator for Slack integration credentials.")
+    client_id: str = Field(description="Slack OAuth client identifier.")
+    client_secret: str | PreserveOriginalValue = Field(description="Slack OAuth client secret.")
+    signing_secret: str | PreserveOriginalValue = Field(description="Slack signing secret used to verify callbacks.")
+    bot_token: str | PreserveOriginalValue = Field(
+        description="Slack bot token used for API calls and message delivery."
+    )
+
+
+class DingTalkIMIntegrationCredentials(_RequestModel):
+    """DingTalk integration credentials used by organization-level IM setup."""
+
+    provider: Literal[IMProvider.DING_TALK] = Field(description="Discriminator for DingTalk integration credentials.")
+    client_id: str = Field(description="DingTalk application client identifier.")
+    client_secret: str | PreserveOriginalValue = Field(
+        description="DingTalk application client secret. This field will be masked in response."
+    )
+
+
+class MSTeamsIMIntegrationCredentials(_RequestModel):
+    """Microsoft Teams integration credentials used by organization-level IM setup."""
+
+    provider: Literal[IMProvider.MS_TEAMS] = Field(
+        description="Discriminator for Microsoft Teams integration credentials."
+    )
+    tenant_id: str = Field(description="Microsoft Entra tenant identifier.")
+    client_id: str = Field(description="Microsoft Teams application client identifier.")
+    client_secret: str | PreserveOriginalValue = Field(
+        description="Microsoft Teams application client secret. This field will be masked in response"
+    )
+
+
+class WeComIMIntegrationCredentials(_RequestModel):
+    """WeCom integration credentials used by organization-level IM setup."""
+
+    provider: Literal[IMProvider.WE_COM] = Field(description="Discriminator for WeCom integration credentials.")
+    corp_id: str = Field(description="WeCom corporation identifier.")
+    agent_id: str = Field(description="WeCom agent identifier.")
+    secret: str | PreserveOriginalValue = Field(
+        description="WeCom application secret. This field will be masked in response"
+    )
+
+
+IMIntegrationCredentials = Annotated[
+    FeishuIMIntegrationCredentials
+    | LarkIMIntegrationCredentials
+    | SlackIMIntegrationCredentials
+    | DingTalkIMIntegrationCredentials
+    | MSTeamsIMIntegrationCredentials
+    | WeComIMIntegrationCredentials,
+    Field(discriminator="provider"),
+]
+
+
+class _IMIntegrationRequest(_RequestModel):
+    """Internal shared body for IM integration write/test operations."""
+
+    credentials: IMIntegrationCredentials = Field(description="Provider-specific IM integration credentials.")
+
+
+class UpdateIMIntegrationRequest(_IMIntegrationRequest):
+    """Request body for creating or updating one IM integration."""
+
+    expected_integration_id: str | None = Field(
+        default=None,
+        min_length=1,
+        description="Current integration identifier used with expected_config_version for compare-and-swap.",
+    )
+    expected_config_version: int | None = Field(
+        default=None,
+        ge=1,
+        description="Current integration revision used with expected_integration_id for compare-and-swap.",
+    )
+
+    @model_validator(mode="after")
+    def validate_complete_cas_token(self) -> Self:
+        has_integration_id = self.expected_integration_id is not None
+        has_config_version = self.expected_config_version is not None
+        if has_integration_id != has_config_version:
+            raise ValueError("expected_integration_id and expected_config_version must be provided together")
+        return self
+
+
+class DeleteIMIntegrationQuery(_NoExtraModel):
+    """CAS token required when deleting the current IM integration."""
+
+    expected_integration_id: str = Field(min_length=1, description="Current integration identifier.")
+    expected_config_version: int = Field(ge=1, description="Current integration revision.")
+
+
+class TestIMIntegrationRequest(_IMIntegrationRequest):
+    """Request body for testing one IM integration."""
+
+
+class IMIntegration(ResponseModel):
+    """One organization-level IM integration snapshot."""
+
+    provider: IMProvider | None = Field(
+        default=None,
+        description="Configured IM provider. None is allowed when the integration is not configured.",
+    )
+    status: IMIntegrationStatus = Field(description="Current integration connectivity state.")
+    callback_url: str | None = Field(
+        default=None,
+        description=(
+            "Callback URL expected by the provider. "
+            "None if the current deployment uses persistence connections for receive events."
+        ),
+    )
+    permission_hint: str | None = Field(default=None, description="Operator-facing hint about permission issues.")
+    configured_at: Timestamp | None = Field(
+        default=None, description="Unix timestamp in milliseconds when the integration was created."
+    )
+    updated_at: Timestamp | None = Field(
+        default=None, description="Unix timestamp in milliseconds when the integration was last updated."
+    )
+    integration_id: str | None = Field(
+        default=None,
+        description="Stable integration identifier. None when no integration is configured.",
+    )
+    config_version: int | None = Field(
+        default=None,
+        ge=1,
+        description="Monotonic configuration revision. None when no integration is configured.",
+    )
+
+
+class GetIMIntegrationResponse(ResponseModel):
+    """Response body carrying one IM integration snapshot."""
+
+    integration: IMIntegration = Field(description="Current organization-level IM integration snapshot.")
+
+
+class UpdateIMIntegrationResponse(ResponseModel):
+    """Response body returned after updating one IM integration."""
+
+    integration: IMIntegration = Field(description="Saved organization-level IM integration snapshot.")
+
+
+class TestIMIntegrationResponse(ResponseModel):
+    """Response body returned by IM integration test APIs."""
+
+    status: IMIntegrationStatus = Field(description="Integration status mapped from the test result.")
+    message: str = Field(description="Human-readable explanation of the test result.")
+
+
+class IMSyncRunResultCounts(ResponseModel):
+    """Aggregate result counts for one IM sync run."""
+
+    added: int = Field(description="Number of entries newly matched and bound.")
+    not_matched: int = Field(description="Number of entries that could not be matched.")
+    failed: int = Field(description="Number of entries that failed to reconcile.")
+    removed: int = Field(description="Number of entries whose prior binding was removed.")
+    skipped: int = Field(description="Number of entries intentionally skipped.")
+
+
+class IMSyncRun(ResponseModel):
+    """One IM sync run snapshot.
+
+    The latest-only UI displays ``finished_at`` as the explicit sync time. The
+    transport contract intentionally does not expose a ``started_by`` actor.
+    """
+
+    id: IMSyncRunId = Field(description="Unique sync run identifier.")
+    status: IMSyncRunStatus = Field(description="Current lifecycle state of the sync run.")
+    started_at: Timestamp | None = Field(
+        default=None, description="Unix timestamp in milliseconds when the sync run started."
+    )
+    finished_at: Timestamp | None = Field(
+        default=None,
+        description=(
+            "Unix timestamp in milliseconds when the sync run finished. "
+            "This is the sync time displayed by the latest-only UI and is None while the run is unfinished."
+        ),
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Terminal error message. Present only when the sync run status is `failed`.",
+    )
+    result_counts: IMSyncRunResultCounts = Field(
+        description="Aggregate reconciliation counts for the current run snapshot.",
+    )
+    provider: IMProvider = Field(description="IM provider associated with the sync run.")
+    integration_id: str = Field(description="Integration identifier captured when the sync run was created.")
+    integration_config_version: int = Field(
+        ge=1,
+        description="Integration configuration revision captured when the sync run was created.",
+    )
+
+
+class CreateIMSyncRunResponse(ResponseModel):
+    """Response body returned after creating one sync run."""
+
+    run: IMSyncRun = Field(description="Newly created sync run snapshot.")
+
+
+class IMDirectoryEntry(_RequestModel):
+    """Normalized provider-side account observed during an IM sync run.
+
+    The entry is run-scoped input to identity and binding reconciliation. It does
+    not represent a stable Dify identity and must not be referenced by bindings
+    or runtime authorization. Sync results may retain a snapshot for display,
+    diagnostics, and audit; durable references use IMIdentity or IMBinding IDs.
+    """
+
+    provider_user_id: str
+    display_name: str | None = None
+    email: str | None = None
+
+
+class IMIdentitySnapshot(_RequestModel):
+    """Last known persistent IM identity state retained by a sync result."""
+
+    identity_id: IMIdentityId
+    provider_user_id: str
+    display_name: str | None = None
+    email: str | None = None
+
+
+class IMSyncResultAdded(BaseModel):
+    type: Literal[IMSyncResultType.ADDED] = IMSyncResultType.ADDED
+
+    contact: HumanInputContactSummary = Field(description="The contact that associated with this sync result.")
+    entry: IMDirectoryEntry = Field(description="Provider directory entry observed during the current sync run.")
+
+
+class IMSyncResultRemoved(BaseModel):
+    type: Literal[IMSyncResultType.REMOVED] = IMSyncResultType.REMOVED
+
+    contact: HumanInputContactSummary = Field(description="The contact that associated with this sync result.")
+    last_known_identity: IMIdentitySnapshot = Field(
+        description="Last known persistent IM identity state before its binding was removed."
+    )
+    reason: IMSyncRemovalReason = Field(description="Reason the existing IM binding was removed.")
+
+
+class IMSyncResultFailed(BaseModel):
+    type: Literal[IMSyncResultType.FAILED] = IMSyncResultType.FAILED
+
+    entry: IMDirectoryEntry | None = Field(
+        None, description="Provider directory entry observed before this reconciliation failure, if available."
+    )
+    reason: str = Field(description="Reason the binding failed to sync.")
+
+
+class IMSyncResultSkipped(BaseModel):
+    type: Literal[IMSyncResultType.SKIPPED] = IMSyncResultType.SKIPPED
+
+    entry: IMDirectoryEntry | None = Field(
+        None, description="Provider directory entry observed before reconciliation was skipped, if available."
+    )
+    contact: HumanInputContactSummary = Field(description="The contact that associated with this sync result.")
+
+
+class IMSyncResultNotMatched(BaseModel):
+    type: Literal[IMSyncResultType.NOT_MATCHED] = IMSyncResultType.NOT_MATCHED
+
+    entry: IMDirectoryEntry | None = Field(
+        None, description="Provider directory entry that could not be matched, if available."
+    )
+
+
+IMSyncResult = Annotated[
+    Union[
+        IMSyncResultAdded,
+        IMSyncResultRemoved,
+        IMSyncResultFailed,
+        IMSyncResultNotMatched,
+        IMSyncResultSkipped,
+    ],
+    Discriminator("type"),
+]
+
+
+class IMSyncResultItem(ResponseModel):
+    """One paginated reconciliation result entry for the latest sync run."""
+
+    # The current implementation does not return IM binding status for other IM providers.
+    # According to the design, we should return IM binding status for all configured IM providers.
+    # However, this version allows only one configured IM provider, so this model excludes
+    # the IM binding status for other IM providers.
+
+    id: str = Field(description="Unique synchronization result identifier.")
+    result: IMSyncResult = Field(description="Result bucket this entry belongs to.")
+
+
+class GetLatestIMSyncRunResponse(ResponseModel):
+    """Response body for reading the latest IM sync run summary."""
+
+    run: IMSyncRun = Field(description="Latest sync run summary.")
+
+
+class ListLatestIMSyncRunResultsQuery(PaginationParamsMixin, _NoExtraModel):
+    """Query params for reading paginated latest-run results."""
+
+    result: IMSyncResultType = Field(
+        ...,
+        description=(
+            "Required result bucket to paginate from the latest sync run. "
+            "There is no `all` bucket or unfiltered results mode."
+        ),
+    )
+
+
+class ListLatestIMSyncRunResultsResponse(PaginationResultMixin, ResponseModel):
+    """Page-based latest-run results without cursor state or a repeated run summary."""
+
+    data: list[IMSyncResultItem] = Field(
+        description="Result entries returned with page, limit, and total metadata for the selected bucket."
+    )
+
+
+class ListIMIdentitiesQuery(PaginationParamsMixin, _NoExtraModel):
+    """Query params for searching synced IM identities."""
+
+    keyword: str | None = Field(
+        default=None,
+        description="Free-text search against identity display name, email, or provider user ID.",
+    )
+
+
+class IMIdentity(ResponseModel):
+    """One synced IM identity that may be bound or overridden."""
+
+    id: IMIdentityId = Field(description="Internal IM identity record identifier.")
+    provider: IMProvider = Field(description="IM provider that owns this identity.")
+    provider_user_id: str = Field(description="Provider-side user identifier.")
+    display_name: str | None = Field(default=None, description="Display name returned by the provider.")
+    email: str | None = Field(default=None, description="Email returned by the provider, if any.")
+    binding_status: IMIdentityBindingStatus = Field(
+        description="Whether this IM identity is currently bound to a contact."
+    )
+
+
+class ListIMIdentitiesResponse(PaginationResultMixin, ResponseModel):
+    """Paginated response body for synced IM identity search."""
+
+    data: list[IMIdentity] = Field(description="IM identities returned for the current page.")
+
+
+class SetContactIMOverrideRequest(_RequestModel):
+    """Request body for setting one workspace-scoped IM override."""
+
+    identity_id: IMIdentityId = Field(description="Synced IM identity identifier selected as the workspace override.")
+
+
+class SetContactIMOverrideResponse(ResponseModel):
+    """Response body returned after setting one contact IM override."""
+
+    contact: HumanInputContact = Field(description="Contact snapshot after the override is applied.")
+
+
+class ResetContactIMOverrideResponse(ResponseModel):
+    """Response body returned after resetting one contact IM override."""
+
+    contact: HumanInputContact = Field(description="Contact snapshot after the override is cleared.")
+
+
+class CreateIMBindingRequest(_RequestModel):
+    """Request body for setting one workspace-scoped IM override."""
+
+    identity_id: IMIdentityId = Field(description="Synced IM identity identifier selected as the workspace override.")
+
+
+class CreateIMBindingResponse(ResponseModel):
+    """Response body returned after binding one IM identity to the workspace."""
+
+    contact: HumanInputContact = Field(description="Contact snapshot after the IM identity is bound.")
+
+
+class DeleteIMBindingQuery(_RequestModel):
+    binding_id: IMBindingId = Field(description="IM binding to unbind.")
+
+
+class DeleteIMBindingResponse(ResponseModel):
+    pass
+
+
+class MessageTemplateTestRequest(_RequestModel):
+    """Request body for sending one message-template test notification."""
+
+    channel: Channel = Field(description="Target debug delivery channel used for the test send.")
+    inputs: dict[str, JsonValue] = Field(
+        default_factory=dict,
+        description="Variable values used when rendering the message template preview.",
+    )
+
+
+class MessageTemplateTestResponse(ResponseModel):
+    """Response body returned after one message-template test send."""
+
+
+class FormAccessRequestResponse(ResponseModel):
+    """Response body returned after creating one OTP challenge."""
+
+    expires_in_seconds: int = Field(description="Seconds until the current OTP challenge expires.")
+    resend_after_seconds: int = Field(description="Seconds until another OTP challenge may be requested.")
+    challenge_token: str = Field(description="The token used to complete the OTP challenge.")
+
+
+class FormDefinitionResponse(ResponseModel):
+    """Response body containing a resolved human-input form definition."""
+
+    form_content: str | None = Field(default=None, description="Rendered form body shown to the approver.")
+    inputs: list[FormInputConfig] = Field(default_factory=list, description="Resolved form input definitions.")
+    resolved_default_values: dict[str, str] = Field(
+        default_factory=dict,
+        description="Default values after variable resolution and stringification.",
+    )
+    user_actions: list[UserActionConfig] = Field(
+        default_factory=list,
+        description="Action buttons that can complete the form.",
+    )
+    expiration_time: int = Field(description="Unix timestamp when the current form expires.")
+
+
+class ServiceFormQuery(_NoExtraModel):
+    """Query params for reading one service-api human-input form."""
+
+    user: str = Field(min_length=1, description="End-user identifier used to scope the service API request.")
+
+
+class BatchGetContactsQuery(_NoExtraModel):
+    contact_ids: list[ContactId] = Field(..., description="List of contact IDs to retrieve.")
+
+
+class BatchGetContactsResponse(ResponseModel):
+    data: list[HumanInputContactSummary] = Field(..., description="List of retrieved human input contacts.")
+
+
+class BatchGetContactOptionsQuery(_NoExtraModel):
+    contact_ids: list[ContactId] = Field(..., description="Contact IDs persisted in workflow recipient configuration.")
+
+
+class BatchGetContactOptionsResponse(ResponseModel):
+    data: list[ContactOption] = Field(..., description="Selectable contacts resolved in request order.")
+
+
+class HumanInputV2FormSubmitRequest(_RequestModel):
+    """Public Human Input v2 submit payload, independent from the v1 form contract."""
+
+    inputs: dict[str, JsonValue] = Field(description="Submitted form values keyed by output variable name.")
+    action: str = Field(description="Identifier of the selected Human Input v2 action.")
+    challenge_token: str | None = Field(
+        default=None,
+        description="OTP challenge token returned by the Human Input v2 access-request endpoint.",
+    )
+    otp_code: str | None = Field(
+        default=None,
+        description="OTP code required when the current Human Input v2 approver uses email proof.",
+    )
+
+    @model_validator(mode="after")
+    def validate_complete_email_proof(self) -> Self:
+        has_challenge_token = self.challenge_token is not None
+        has_otp_code = self.otp_code is not None
+        if has_challenge_token != has_otp_code:
+            raise ValueError("challenge_token and otp_code must be provided together")
+        return self
+
+
+class HumanInputV2ServiceFormSubmitRequest(_RequestModel):
+    """Trusted Service API submit payload without public-web OTP proof fields."""
+
+    inputs: dict[str, JsonValue] = Field(description="Submitted form values keyed by output variable name.")
+    action: str = Field(description="Identifier of the selected Human Input v2 action.")
+    user: str = Field(min_length=1, description="End-user identifier scoped to the current app token.")
+
+
+class FormUploadTokenResponse(ResponseModel):
+    """Response body returned when issuing a Human Input v2 upload token."""
+
+    upload_token: str
+    expires_at: int
+
+
+class FormSubmitResponse(ResponseModel):
+    """Empty response body returned after a Human Input v2 form submission."""
+
+
+# =================== Node migration related entities ===================
+
+
+class LegacyHITLv1NodeData(HITLv1NodeData):
+    """Legacy Human Input node data accepted by the v1-to-v2 migration helper.
+
+    Missing versions use the historical v1 default. Any explicit value other
+    than the string ``"1"`` is rejected before migration.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    # Keep the mutable parent field type for static substitutability while
+    # preserving the literal transport schema and runtime validation.
+    version: str = Field(
+        default="1",
+        description=(
+            'Legacy Human Input node version. Missing values default to "1"; '
+            'any explicit value other than the string "1" is rejected.'
+        ),
+        json_schema_extra={"const": "1"},
+    )
+
+    @field_validator("version")
+    @classmethod
+    def validate_version(cls, value: str) -> str:
+        if value != "1":
+            raise ValueError('version must be "1"')
+        return value
+
+
+class NodeDataMigrationInput(_MigrationInputModel):
+    """One legacy node submitted through the frontend migration adapter boundary."""
+
+    node_id: str = Field(
+        ..., description="The identifier of node to migrate. Used to associate between request and response"
+    )
+    node_data: LegacyHITLv1NodeData = Field(..., description="The legacy Human Input node data to migrate.")
+
+
+class NodeDataMigrationPayload(_MigrationInputModel):
+    """Complete legacy-node batch submitted for one migration attempt."""
+
+    nodes: list[NodeDataMigrationInput] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def validate_unique_node_ids(self) -> Self:
+        node_ids = [node.node_id for node in self.nodes]
+        if len(node_ids) != len(set(node_ids)):
+            raise ValueError("node_id must be unique within one migration request")
+        return self
+
+
+class NodeDataMigrationResult(ResponseModel):
+    """One converted node returned with its frontend correlation identifier."""
+
+    node_id: str = Field(description="The identifier of the migrated node.")
+    node_data: HITLv2NodeData = Field(description="The complete converted Human Input v2 node data.")
+
+
+class NodeDataMigrationResponse(ResponseModel):
+    """Successful all-node conversion response."""
+
+    data: list[NodeDataMigrationResult]
+
+
+NodeDataMigrationBlockerCode = Literal[
+    "unsupported-version",
+    "configured-disabled-method",
+    "unsupported-delivery-method",
+    "invalid-email-configuration",
+    "invalid-email",
+    "unresolved-member",
+    "conflicting-email-templates",
+    "missing-recipients",
+]
+
+
+class NodeDataMigrationBlocker(ResponseModel):
+    """Stable node-scoped reason why the backend cannot produce lossless v2 data."""
+
+    node_id: str = Field(description="The identifier of the node that failed migration.")
+    node_title: str = Field(description="The node title used for actionable frontend feedback.")
+    code: NodeDataMigrationBlockerCode = Field(description="Machine-readable migration blocker code.")
+    method_id: str | None = Field(default=None, description="Legacy delivery method related to the blocker.")
+    value: str | None = Field(default=None, description="Safe legacy value related to the blocker.")
+
+
+class NodeDataMigrationFailureResponse(ResponseModel):
+    """Whole-batch failure response without partial converted node data."""
+
+    code: Literal["hitl_node_data_migration_failure"] = "hitl_node_data_migration_failure"
+    message: str = Field(..., description="overall error messages")
+    status: Literal[HTTPStatus.BAD_REQUEST] = HTTPStatus.BAD_REQUEST
+    blockers: list[NodeDataMigrationBlocker] = Field(
+        ..., description="Node-scoped blockers that caused the whole batch to fail."
+    )
+
+
+# =================== EmailProvider related entities ===================
+
+
+class PreserveOriginalValue(_RequestModel):
+    tag: Literal["preserve_original_value"] = "preserve_original_value"
+
+
+class ResendProviderUpdateConfig(_RequestModel):
+    type: Literal[EmailProviderType.RESEND] = EmailProviderType.RESEND
+
+    api_key: str | PreserveOriginalValue = Field(
+        ...,
+        description=(
+            "Resend API key. "
+            "Setting this to `PreserveOriginalValue` while updating will preserve the previously set credential."
+        ),
+    )
+    sender_email: str = Field(
+        ..., description="The email address shown as the sender. Its domain must be verified in Resend."
+    )
+
+    sender_name: str = Field("", description="The sender's name displayed in the recipient's inbox.")
+
+
+class ResendProviderConfigResponse(ResponseModel):
+    type: Literal[EmailProviderType.RESEND] = EmailProviderType.RESEND
+    api_key_configured: bool = Field(description="Whether a Resend API key has been configured.")
+    sender_email: str = Field(description="The email address shown as the sender.")
+    sender_name: str = Field("", description="The sender's name displayed in the recipient's inbox.")
+
+
+EmailProviderUpdateConfig = ResendProviderUpdateConfig
+EmailProviderConfigResponse = ResendProviderConfigResponse
+
+
+class GetEmailProviderResponse(ResponseModel):
+    provider_config: EmailProviderConfigResponse | None = Field(
+        ...,
+        description="The current email provider configuration. `None` if not set.",
+    )
+
+
+class SetEmailProviderRequest(_RequestModel):
+    provider_config: EmailProviderUpdateConfig = Field(..., description="Email provider configuration update.")
+
+
+class SetEmailProviderResponse(ResponseModel):
+    pass
+
+
+class TestEmailProviderConfigRequest(_RequestModel):
+    pass
+
+
+class TestEmailProviderConfigResponse(ResponseModel):
+    pass
+
+
+__all__ = [
+    "AddPlatformContactsRequest",
+    "AddPlatformContactsResponse",
+    "BatchGetContactOptionsQuery",
+    "BatchGetContactOptionsResponse",
+    "ContactListQuery",
+    "ContactOption",
+    "ContactOptionsQuery",
+    "CreateIMSyncRunResponse",
+    "DeleteIMIntegrationQuery",
+    "DingTalkIMIntegrationCredentials",
+    "EmailProviderConfigResponse",
+    "EmailProviderType",
+    "EmailProviderUpdateConfig",
+    "ExternalContactCreateRequest",
+    "ExternalContactUpdateRequest",
+    "FeishuIMIntegrationCredentials",
+    "FormAccessRequestResponse",
+    "FormDefinitionResponse",
+    "FormSubmitResponse",
+    "FormUploadTokenResponse",
+    "GetContactResponse",
+    "GetEmailProviderResponse",
+    "GetIMIntegrationResponse",
+    "GetLatestIMSyncRunResponse",
+    "HumanInputContact",
+    "HumanInputContactType",
+    "HumanInputV2FormSubmitRequest",
+    "HumanInputV2ServiceFormSubmitRequest",
+    "IMIdentity",
+    "IMIdentityBindingStatus",
+    "IMIntegration",
+    "IMIntegrationCredentials",
+    "IMIntegrationStatus",
+    "IMProvider",
+    "IMSyncRemovalReason",
+    "IMSyncResultItem",
+    "IMSyncResultType",
+    "IMSyncRun",
+    "IMSyncRunResultCounts",
+    "IMSyncRunStatus",
+    "LarkIMIntegrationCredentials",
+    "ListContactOptionsResponse",
+    "ListContactsResponse",
+    "ListIMIdentitiesQuery",
+    "ListIMIdentitiesResponse",
+    "ListLatestIMSyncRunResultsQuery",
+    "ListLatestIMSyncRunResultsResponse",
+    "ListOrganizationCandidatesResponse",
+    "MSTeamsIMIntegrationCredentials",
+    "MessageTemplateTestRequest",
+    "MessageTemplateTestResponse",
+    "NodeDataMigrationFailureResponse",
+    "NodeDataMigrationPayload",
+    "NodeDataMigrationResponse",
+    "OrganizationCandidate",
+    "OrganizationCandidatesQuery",
+    "PreserveOriginalValue",
+    "RemoveContactsRequest",
+    "RemoveContactsResponse",
+    "ResendProviderConfigResponse",
+    "ResendProviderUpdateConfig",
+    "ResetContactIMOverrideResponse",
+    "ServiceFormQuery",
+    "SetContactIMOverrideRequest",
+    "SetContactIMOverrideResponse",
+    "SetEmailProviderRequest",
+    "SetEmailProviderResponse",
+    "SlackIMIntegrationCredentials",
+    "TestIMIntegrationRequest",
+    "TestIMIntegrationResponse",
+    "UpdateIMIntegrationRequest",
+    "UpdateIMIntegrationResponse",
+    "WeComIMIntegrationCredentials",
+]
@@ -76,6 +76,7 @@ from .app import (
    workflow_app_log,
    workflow_comment,
    workflow_draft_variable,
+    workflow_human_input_v2,
    workflow_node_output_inspector,
    workflow_run,
    workflow_statistic,
@@ -138,6 +139,7 @@ from .workspace import (
    account,
    agent_providers,
    endpoint,
+    human_input,
    load_balancing_config,
    members,
    model_providers,
@@ -194,6 +196,7 @@ __all__ = [
    "forgot_password",
    "generator",
    "hit_testing",
+    "human_input",
    "human_input_form",
    "init_validate",
    "installed_app",
@@ -241,6 +244,7 @@ __all__ = [
    "workflow_app_log",
    "workflow_comment",
    "workflow_draft_variable",
+    "workflow_human_input_v2",
    "workflow_node_output_inspector",
    "workflow_run",
    "workflow_run_archive",
@@ -257,7 +257,6 @@ class AgentAppDetailWithSite(GenericAppDetailWithSite):
    debug_conversation_has_messages: bool = False
    debug_conversation_message_count: int = 0
    role: str | None = None
-    active_config_is_published: bool = False


 class AgentDebugConversationRefreshResponse(BaseModel):
@@ -410,10 +409,6 @@ def _serialize_agent_app_detail(
    payload["debug_conversation_has_messages"] = message_count > 0
    payload["debug_conversation_message_count"] = message_count
    payload["role"] = agent.role or ""
-    payload["active_config_is_published"] = roster_service.active_config_is_published(
-        tenant_id=app_model.tenant_id,
-        agent=agent,
-    )
    return payload


@@ -58,6 +58,7 @@ from services.app_service import (
    AppResponseView,
    AppService,
    CreateAppParams,
+    RecentAppMode,
    StarredAppListParams,
 )
 from services.enterprise import rbac_service as enterprise_rbac_service
@@ -139,6 +140,10 @@ class AppListBaseQuery(BaseModel):
            raise ValueError("Invalid UUID format in creator_ids.") from exc


+class RecentAppListQuery(BaseModel):
+    limit: int = Field(default=8, ge=1, le=8, description="Number of recently modified apps to return (1-8)")
+
+
 class AppListQuery(AppListBaseQuery):
    pass

@@ -411,6 +416,33 @@ class AppPartial(AppResponseModel):
        return to_timestamp(value)


+class RecentAppResponse(ResponseModel):
+    id: str
+    name: str
+    icon_type: IconType | None = None
+    icon: str | None = None
+    icon_background: str | None = None
+    mode: RecentAppMode
+    author_name: str | None = None
+    updated_at: int
+    permission_keys: list[str] = Field(default_factory=list)
+    maintainer: str | None = None
+
+    @computed_field(return_type=str | None)  # type: ignore[prop-decorator]
+    @property
+    def icon_url(self) -> str | None:
+        return build_icon_url(self.icon_type, self.icon)
+
+    @field_validator("updated_at", mode="before")
+    @classmethod
+    def _normalize_timestamp(cls, value: datetime | int) -> int:
+        return to_timestamp(value)
+
+
+class RecentAppListResponse(ResponseModel):
+    data: list[RecentAppResponse]
+
+
 class AppDetail(AppResponseModel):
    id: str
    name: str
@@ -575,6 +607,8 @@ register_schema_models(
 register_response_schema_models(
    console_ns,
    AppPartial,
+    RecentAppResponse,
+    RecentAppListResponse,
    AppDetailWithSite,
    AppPagination,
 )
@@ -699,6 +733,49 @@ class AppListApi(Resource):
        return app_detail.model_dump(mode="json"), 201


+@console_ns.route("/apps/recent")
+class RecentAppListApi(Resource):
+    @console_ns.doc("list_recent_apps")
+    @console_ns.doc(description="Get recently modified apps for the home Continue Work section")
+    @console_ns.doc(params=query_params_from_model(RecentAppListQuery))
+    @console_ns.response(200, "Success", console_ns.models[RecentAppListResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @enterprise_license_required
+    @with_session(write=False)
+    @with_current_user_id
+    @with_current_tenant_id
+    def get(self, current_tenant_id: str, current_user_id: str, session: Session):
+        """Return the lightweight app cards needed by the Explore home page."""
+        args = query_params_from_request(RecentAppListQuery)
+        params = AppListParams(limit=args.limit)
+
+        permissions = enterprise_rbac_service.RBACService.MyPermissions.get(
+            current_tenant_id,
+            current_user_id,
+            session=session,
+        )
+        if dify_config.RBAC_ENABLED:
+            access_filter = resolve_app_access_filter(
+                current_tenant_id,
+                current_user_id,
+                session=session,
+                permissions=permissions,
+            )
+            access_filter.apply_to_params(params)
+
+        recent_apps = AppService().get_recent_apps(current_user_id, current_tenant_id, params, session)
+        permission_keys_map = permissions.app.permission_keys_by_resource_ids([app.id for app in recent_apps])
+        response_items = [
+            RecentAppResponse.model_validate(app, from_attributes=True).model_copy(
+                update={"permission_keys": permission_keys_map.get(app.id, [])}
+            )
+            for app in recent_apps
+        ]
+        return dump_response(RecentAppListResponse, {"data": response_items}), 200
+
+
@console_ns.route("/apps/starred")
 class StarredAppListApi(Resource):
    @console_ns.doc("list_starred_apps")
@@ -0,0 +1,70 @@
+"""Draft Human Input v2 workflow controller stubs."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+
+from flask import abort
+from flask_restx import Resource
+
+from controllers.common.human_input_v2_contracts import (
+    MessageTemplateTestRequest,
+    MessageTemplateTestResponse,
+)
+from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.console import console_ns
+from controllers.console.wraps import (
+    RBACPermission,
+    RBACResourceScope,
+    account_initialization_required,
+    edit_permission_required,
+    rbac_permission_required,
+    setup_required,
+    with_current_user,
+)
+from libs.login import login_required
+from models import Account
+from models.model import AppMode
+
+from .wraps import get_app_model
+
+register_schema_models(console_ns, MessageTemplateTestRequest)
+register_response_schema_models(console_ns, MessageTemplateTestResponse)
+
+
+def _raise_stub_not_implemented() -> None:
+    abort(HTTPStatus.NOT_IMPLEMENTED, "Human Input v2 draft stub endpoint is not implemented yet.")
+
+
+@console_ns.route("/apps/<uuid:app_id>/workflows/draft/human-input/nodes/<string:node_id>/message-template/test")
+class WorkflowDraftMessageTemplateTestApi(Resource):
+    @console_ns.expect(console_ns.models[MessageTemplateTestRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[MessageTemplateTestResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @get_app_model(mode=[AppMode.WORKFLOW])
+    @with_current_user
+    @edit_permission_required
+    def post(self, current_user: Account, app_model, node_id: str):
+        MessageTemplateTestRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@console_ns.route(
+    "/apps/<uuid:app_id>/advanced-chat/workflows/draft/human-input/nodes/<string:node_id>/message-template/test"
+)
+class AdvancedChatDraftMessageTemplateTestApi(Resource):
+    @console_ns.expect(console_ns.models[MessageTemplateTestRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[MessageTemplateTestResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_TEST_AND_RUN)
+    @get_app_model(mode=[AppMode.ADVANCED_CHAT])
+    @with_current_user
+    @edit_permission_required
+    def post(self, current_user: Account, app_model, node_id: str):
+        MessageTemplateTestRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
@@ -0,0 +1,541 @@
+"""Workspace-level Human Input v2 controller stubs."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+
+from flask import abort, request
+from flask_restx import Resource
+
+from controllers.common.human_input_v2_contracts import (
+    AddPlatformContactsRequest,
+    AddPlatformContactsResponse,
+    BatchGetContactOptionsQuery,
+    BatchGetContactOptionsResponse,
+    BatchGetContactsQuery,
+    BatchGetContactsResponse,
+    ContactListQuery,
+    ContactOption,
+    ContactOptionsQuery,
+    CreateIMBindingRequest,
+    CreateIMBindingResponse,
+    CreateIMSyncRunResponse,
+    DeleteIMBindingQuery,
+    DeleteIMBindingResponse,
+    DeleteIMIntegrationQuery,
+    ExternalContactCreateRequest,
+    ExternalContactCreateResponse,
+    ExternalContactUpdateRequest,
+    ExternalContactUpdateResponse,
+    GetContactResponse,
+    GetEmailProviderResponse,
+    GetIMIntegrationResponse,
+    GetLatestIMSyncRunResponse,
+    HumanInputContact,
+    HumanInputContactType,
+    IMIntegrationStatus,
+    IMProvider,
+    IMSyncResultType,
+    IMSyncRunStatus,
+    ListContactOptionsResponse,
+    ListContactsResponse,
+    ListIMIdentitiesQuery,
+    ListIMIdentitiesResponse,
+    ListLatestIMSyncRunResultsQuery,
+    ListLatestIMSyncRunResultsResponse,
+    ListOrganizationCandidatesResponse,
+    NodeDataMigrationFailureResponse,
+    NodeDataMigrationPayload,
+    NodeDataMigrationResponse,
+    OrganizationCandidatesQuery,
+    RemoveContactsRequest,
+    RemoveContactsResponse,
+    ResetContactIMOverrideResponse,
+    SetContactIMOverrideRequest,
+    SetContactIMOverrideResponse,
+    SetEmailProviderRequest,
+    SetEmailProviderResponse,
+    TestIMIntegrationRequest,
+    TestIMIntegrationResponse,
+    UpdateIMIntegrationRequest,
+    UpdateIMIntegrationResponse,
+)
+from controllers.common.schema import (
+    query_params_from_model,
+    query_params_from_request,
+    register_enum_models,
+    register_response_schema_models,
+    register_schema_models,
+)
+from controllers.console import console_ns
+from controllers.console.wraps import (
+    account_initialization_required,
+    edit_permission_required,
+    is_admin_or_owner_required,
+    setup_required,
+    with_current_tenant_id,
+)
+from libs.login import login_required
+
+register_enum_models(
+    console_ns,
+    HumanInputContactType,
+    IMIntegrationStatus,
+    IMSyncRunStatus,
+    IMSyncResultType,
+    IMProvider,
+)
+register_schema_models(
+    console_ns,
+    ContactListQuery,
+    ContactOptionsQuery,
+    BatchGetContactOptionsQuery,
+    OrganizationCandidatesQuery,
+    AddPlatformContactsRequest,
+    ExternalContactCreateRequest,
+    ExternalContactUpdateRequest,
+    RemoveContactsRequest,
+    UpdateIMIntegrationRequest,
+    DeleteIMIntegrationQuery,
+    TestIMIntegrationRequest,
+    ListIMIdentitiesQuery,
+    ListLatestIMSyncRunResultsQuery,
+    SetContactIMOverrideRequest,
+    CreateIMBindingRequest,
+    NodeDataMigrationPayload,
+    SetEmailProviderRequest,
+)
+register_response_schema_models(
+    console_ns,
+    HumanInputContact,
+    ContactOption,
+    GetContactResponse,
+    ExternalContactCreateResponse,
+    ExternalContactUpdateResponse,
+    AddPlatformContactsResponse,
+    ListContactsResponse,
+    ListContactOptionsResponse,
+    BatchGetContactOptionsResponse,
+    RemoveContactsResponse,
+    ListIMIdentitiesResponse,
+    GetIMIntegrationResponse,
+    UpdateIMIntegrationResponse,
+    TestIMIntegrationResponse,
+    CreateIMSyncRunResponse,
+    GetLatestIMSyncRunResponse,
+    ListLatestIMSyncRunResultsResponse,
+    ListOrganizationCandidatesResponse,
+    ResetContactIMOverrideResponse,
+    SetContactIMOverrideResponse,
+    CreateIMBindingResponse,
+    DeleteIMBindingResponse,
+    BatchGetContactsResponse,
+    NodeDataMigrationResponse,
+    NodeDataMigrationFailureResponse,
+    GetEmailProviderResponse,
+    SetEmailProviderResponse,
+)
+
+
+def _raise_stub_not_implemented() -> None:
+    abort(HTTPStatus.NOT_IMPLEMENTED, "Human Input v2 stub endpoint is not implemented yet.")
+
+
+@console_ns.route("/workspaces/current/human-input/contacts")
+class WorkspaceContactsApi(Resource):
+    @console_ns.doc(params=query_params_from_model(ContactListQuery))
+    @console_ns.response(200, "Success", console_ns.models[ListContactsResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        ContactListQuery.model_validate(request.args.to_dict(flat=True))
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/<uuid:contact_id>")
+class WorkspaceContactApi(Resource):
+    """Read one contact only when it resolves in the current workspace scope."""
+
+    @console_ns.response(200, "Success", console_ns.models[GetContactResponse.__name__])
+    @console_ns.response(404, "Contact not found or absent in the current workspace")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str, contact_id: str):
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contact-options")
+class WorkspaceContactOptionsApi(Resource):
+    """Search the current workspace's selectable Contact projection for workflow editors."""
+
+    @console_ns.doc(
+        params=query_params_from_model(ContactOptionsQuery),
+        description=(
+            "List editor-safe Contact options for static recipient selection. "
+            "The projection omits email, IM bindings, and management metadata; contacts that resolve as ABSENT "
+            "or are otherwise unavailable in the current workspace are omitted."
+        ),
+    )
+    @console_ns.response(200, "Success", console_ns.models[ListContactOptionsResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        ContactOptionsQuery.model_validate(request.args.to_dict(flat=True))
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/organization-candidates")
+class WorkspaceOrganizationCandidatesApi(Resource):
+    @console_ns.doc(params=query_params_from_model(OrganizationCandidatesQuery))
+    @console_ns.response(200, "Success", console_ns.models[ListOrganizationCandidatesResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        OrganizationCandidatesQuery.model_validate(request.args.to_dict(flat=True))
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/platform")
+class WorkspacePlatformContactsApi(Resource):
+    @console_ns.expect(console_ns.models[AddPlatformContactsRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[AddPlatformContactsResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
+        AddPlatformContactsRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/external")
+class WorkspaceExternalContactsApi(Resource):
+    @console_ns.expect(console_ns.models[ExternalContactCreateRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ExternalContactCreateResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
+        ExternalContactCreateRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/external/<uuid:contact_id>")
+class WorkspaceExternalContactApi(Resource):
+    @console_ns.expect(console_ns.models[ExternalContactUpdateRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[ExternalContactUpdateResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def patch(self, tenant_id: str, contact_id: str):
+        ExternalContactUpdateRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/remove")
+class WorkspaceContactsRemoveApi(Resource):
+    @console_ns.expect(console_ns.models[RemoveContactsRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[RemoveContactsResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
+        RemoveContactsRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/im-integration")
+class WorkspaceIMIntegrationApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[GetIMIntegrationResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        _raise_stub_not_implemented()
+
+    @console_ns.expect(console_ns.models[UpdateIMIntegrationRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[UpdateIMIntegrationResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def put(self, tenant_id: str):
+        UpdateIMIntegrationRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+    @console_ns.doc(params=query_params_from_model(DeleteIMIntegrationQuery))
+    @console_ns.response(204, "IM integration deleted successfully")
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def delete(self, tenant_id: str):
+        query_params_from_request(DeleteIMIntegrationQuery)
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/im-integration/test")
+class WorkspaceIMIntegrationTestApi(Resource):
+    @console_ns.expect(console_ns.models[TestIMIntegrationRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[TestIMIntegrationResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
+        TestIMIntegrationRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/im-sync-runs")
+class WorkspaceIMSyncRunsApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[CreateIMSyncRunResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/im-sync-runs/latest")
+class WorkspaceLatestIMSyncRunApi(Resource):
+    @console_ns.doc(
+        description=(
+            "Return the latest IM sync run summary. The UI uses finished_at as the explicit sync time; "
+            "the response does not include started_by."
+        )
+    )
+    @console_ns.response(200, "Success", console_ns.models[GetLatestIMSyncRunResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/im-sync-runs/latest/results")
+class WorkspaceLatestIMSyncRunResultsApi(Resource):
+    @console_ns.doc(
+        params=query_params_from_model(ListLatestIMSyncRunResultsQuery),
+        description=(
+            "Return one required result bucket from the latest IM sync run using page and limit pagination. "
+            "There is no all filter; the response contains page, limit, and total metadata without a run summary."
+        ),
+    )
+    @console_ns.response(200, "Success", console_ns.models[ListLatestIMSyncRunResultsResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        ListLatestIMSyncRunResultsQuery.model_validate(request.args.to_dict(flat=True))
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/im-identities")
+class WorkspaceIMIdentitiesApi(Resource):
+    @console_ns.doc(params=query_params_from_model(ListIMIdentitiesQuery))
+    @console_ns.response(200, "Success", console_ns.models[ListIMIdentitiesResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        ListIMIdentitiesQuery.model_validate(request.args.to_dict(flat=True))
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/<uuid:contact_id>/im-override")
+class WorkspaceContactIMOverrideApi(Resource):
+    @console_ns.doc(
+        description=(
+            "Set or reset the IM override for a contact. "
+            "This endpoint is used to override the IM identity for a contact in the workspace."
+        ),
+    )
+    @console_ns.expect(console_ns.models[SetContactIMOverrideRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SetContactIMOverrideResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def put(self, tenant_id: str, contact_id: str):
+        # This API only works in EE.
+        SetContactIMOverrideRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+    @console_ns.doc(
+        description=(
+            "Reset the IM override for a contact. "
+            "This endpoint is used to clear the IM identity override for a contact in the workspace."
+        ),
+    )
+    @console_ns.response(200, "Success", console_ns.models[ResetContactIMOverrideResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, contact_id: str):
+        # This API only works in EE.
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/<uuid:contact_id>/im-bindings")
+class WorkspaceContactIMBindingsApi(Resource):
+    @console_ns.doc(
+        description=(
+            "Set an IM binding for a contact. Used for binding an IM identity to a contact. "
+            "This endpoint is not used for creating workspace IM override. "
+            "For that purpose, use WorkspaceContactIMOverrideApi.put instead."
+        ),
+    )
+    @console_ns.expect(console_ns.models[CreateIMBindingRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[CreateIMBindingResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def put(self, tenant_id: str, contact_id: str):
+        CreateIMBindingRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+    @console_ns.response(200, "Success", console_ns.models[DeleteIMBindingResponse.__name__])
+    @console_ns.doc(
+        params=query_params_from_model(DeleteIMBindingQuery),
+        description=(
+            "Delete an IM binding for a contact. Used for removing contact IM binding information. "
+            "This endpoint is not used for resetting workspace IM override. For that purpose, use "
+            "WorkspaceContactIMOverrideApi.delete instead."
+        ),
+    )
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def delete(self, tenant_id: str, contact_id: str):
+        query_params_from_request(DeleteIMBindingQuery)
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contacts/batch")
+class BatchGetContactsAPI(Resource):
+    @console_ns.doc(
+        params=query_params_from_model(BatchGetContactsQuery),
+        description=(
+            "Admin-only batch lookup for Contact management clients. "
+            "Workflow editors must use the editor-safe contact-options/batch projection."
+        ),
+    )
+    @console_ns.response(200, "Success", console_ns.models[BatchGetContactsResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        query_params_from_request(BatchGetContactsQuery, list_fields=("contact_ids",))
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/contact-options/batch")
+class BatchGetContactOptionsAPI(Resource):
+    """Resolve persisted Contact IDs through the same editor-safe selection projection."""
+
+    @console_ns.doc(
+        params=query_params_from_model(BatchGetContactOptionsQuery),
+        description=(
+            "Resolve Contact IDs persisted in workflow recipient configuration. "
+            "Contacts that resolve as ABSENT or are otherwise unavailable in the current workspace are omitted."
+        ),
+    )
+    @console_ns.response(200, "Success", console_ns.models[BatchGetContactOptionsResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        query_params_from_request(BatchGetContactOptionsQuery, list_fields=("contact_ids",))
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/node-data-migration")
+class NodeDataMigrationAPI(Resource):
+    @console_ns.doc(
+        description=(
+            "Migrate node data from HITLv1 to HITLv2. "
+            'A missing legacy version defaults to "1"; any other explicit version is rejected. '
+            "This endpoint only returns the migrated Human Input v2 node data to the client. "
+            "It does not update the workflow DSL."
+        ),
+    )
+    @console_ns.expect(console_ns.models[NodeDataMigrationPayload.__name__])
+    @console_ns.response(200, "Success", console_ns.models[NodeDataMigrationResponse.__name__])
+    @console_ns.response(400, "Migration failed", console_ns.models[NodeDataMigrationFailureResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @edit_permission_required
+    @with_current_tenant_id
+    def post(self, tenant_id: str):
+        NodeDataMigrationPayload.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@console_ns.route("/workspaces/current/human-input/email-provider")
+class HumanInputEmailProviderAPI(Resource):
+    @console_ns.doc(description="Retrieve the current email provider settings for human input")
+    @console_ns.response(200, "Success", console_ns.models[GetEmailProviderResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def get(self, tenant_id: str):
+        _raise_stub_not_implemented()
+
+    @console_ns.doc(description="update the current email provider settings for human input")
+    @console_ns.expect(console_ns.models[SetEmailProviderRequest.__name__])
+    @console_ns.response(200, "Success", console_ns.models[SetEmailProviderResponse.__name__])
+    @setup_required
+    @login_required
+    @account_initialization_required
+    @is_admin_or_owner_required
+    @with_current_tenant_id
+    def put(self, tenant_id: str):
+        SetEmailProviderRequest.model_validate(console_ns.payload or {})
+        _raise_stub_not_implemented()
@@ -23,6 +23,7 @@ from .knowledge import retrieval as _knowledge_retrieval
 from .plugin import agent_config as _agent_config
 from .plugin import agent_drive as _agent_drive
 from .plugin import plugin as _plugin
+from .workspace import plugin_model_providers as _plugin_model_providers
 from .workspace import workspace as _workspace

 api.add_namespace(inner_api_ns)
@@ -35,6 +36,7 @@ __all__ = [
    "_knowledge_retrieval",
    "_mail",
    "_plugin",
+    "_plugin_model_providers",
    "_runtime_credentials",
    "_workspace",
    "api",
@@ -0,0 +1,39 @@
+from flask_restx import Resource
+from pydantic import BaseModel, ConfigDict, Field
+
+from controllers.common.schema import register_schema_model
+from controllers.console.wraps import setup_required
+from controllers.inner_api import inner_api_ns
+from controllers.inner_api.wraps import enterprise_inner_api_only
+from core.plugin.plugin_service import PluginService
+
+
+class InvalidatePluginModelProvidersCachePayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    tenant_ids: list[str] = Field(default_factory=list, description="Workspace ids whose cache should be invalidated")
+
+
+register_schema_model(inner_api_ns, InvalidatePluginModelProvidersCachePayload)
+
+
+@inner_api_ns.route("/enterprise/workspace/plugin-model-providers/invalidate")
+class EnterprisePluginModelProvidersCacheInvalidate(Resource):
+    @setup_required
+    @enterprise_inner_api_only
+    @inner_api_ns.doc(
+        "enterprise_invalidate_plugin_model_providers_cache",
+        responses={
+            200: "Cache invalidated",
+            400: "Invalid request",
+            401: "Unauthorized - invalid API key",
+        },
+    )
+    @inner_api_ns.expect(inner_api_ns.models[InvalidatePluginModelProvidersCachePayload.__name__])
+    def post(self):
+        args = InvalidatePluginModelProvidersCachePayload.model_validate(inner_api_ns.payload or {})
+
+        for tenant_id in args.tenant_ids:
+            PluginService.invalidate_plugin_model_providers_cache(tenant_id)
+
+        return {"result": "success"}, 200
@@ -8,14 +8,18 @@ paused human input forms in workflow/chatflow runs.
 import json
 import logging
 from collections.abc import Sequence
+from http import HTTPStatus
 from typing import Any

-from flask import Response
+from flask import Response, abort, request
 from flask_restx import Resource
 from pydantic import ConfigDict, Field
 from werkzeug.exceptions import BadRequest, NotFound

 from controllers.common.human_input import HumanInputFormSubmitPayload, stringify_form_default_values
+from controllers.common.human_input_v2_contracts import FormDefinitionResponse as HumanInputV2FormDefinitionResponse
+from controllers.common.human_input_v2_contracts import FormSubmitResponse as HumanInputV2FormSubmitResponse
+from controllers.common.human_input_v2_contracts import HumanInputV2ServiceFormSubmitRequest, ServiceFormQuery
 from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.service_api import service_api_ns
 from controllers.service_api.schema import expect_with_user
@@ -43,8 +47,19 @@ class HumanInputFormSubmitResponse(ResponseModel):
    model_config = ConfigDict(extra="forbid")


-register_schema_models(service_api_ns, HumanInputFormSubmitPayload)
-register_response_schema_models(service_api_ns, HumanInputFormDefinitionResponse, HumanInputFormSubmitResponse)
+register_schema_models(
+    service_api_ns,
+    HumanInputFormSubmitPayload,
+    HumanInputV2ServiceFormSubmitRequest,
+    ServiceFormQuery,
+)
+register_response_schema_models(
+    service_api_ns,
+    HumanInputFormDefinitionResponse,
+    HumanInputFormSubmitResponse,
+    HumanInputV2FormDefinitionResponse,
+    HumanInputV2FormSubmitResponse,
+)


 def _jsonify_form_definition(form: Form, *, inputs: Sequence[FormInputConfig] = ()) -> Response:
@@ -188,3 +203,33 @@ class WorkflowHumanInputFormApi(Resource):
            raise NotFound("Form not found")

        return {}, 200
+
+
+@service_api_ns.route("/form/human-input/<string:form_token>")
+class WorkflowHumanInputV2FormApi(Resource):
+    """Trusted Service API stub for Human Input v2 forms.
+
+    This route does not alias the v1 handler. The implementation must resolve a
+    v2 form and reject v1 form tokens before reading or submitting it.
+    """
+
+    @service_api_ns.response(
+        200,
+        "Form retrieved successfully",
+        service_api_ns.models[HumanInputV2FormDefinitionResponse.__name__],
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY, required=True))
+    def get(self, app_model: App, end_user: EndUser, form_token: str):
+        ServiceFormQuery.model_validate(request.args.to_dict(flat=True))
+        abort(HTTPStatus.NOT_IMPLEMENTED, "Human Input v2 Service API stub endpoint is not implemented yet.")
+
+    @service_api_ns.expect(service_api_ns.models[HumanInputV2ServiceFormSubmitRequest.__name__])
+    @service_api_ns.response(
+        200,
+        "Form submitted successfully",
+        service_api_ns.models[HumanInputV2FormSubmitResponse.__name__],
+    )
+    @validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
+    def post(self, app_model: App, end_user: EndUser, form_token: str):
+        HumanInputV2ServiceFormSubmitRequest.model_validate(service_api_ns.payload or {})
+        abort(HTTPStatus.NOT_IMPLEMENTED, "Human Input v2 Service API stub endpoint is not implemented yet.")
@@ -25,6 +25,7 @@ from . import (
    forgot_password,
    human_input_file_upload,
    human_input_form,
+    human_input_form_access_request,
    login,
    message,
    passport,
@@ -49,6 +50,7 @@ __all__ = [
    "forgot_password",
    "human_input_file_upload",
    "human_input_form",
+    "human_input_form_access_request",
    "login",
    "message",
    "passport",
@@ -24,7 +24,7 @@ from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import RateLimiter, dump_response, extract_remote_ip, to_timestamp
 from models.account import TenantStatus
-from models.model import App, Site
+from models.model import App, AppMode, Site
 from repositories.factory import DifyAPIRepositoryFactory
 from services.feature_service import FeatureService
 from services.human_input_file_upload_service import HumanInputFileUploadService
@@ -207,6 +207,7 @@ class HumanInputFormApi(Resource):
                site=WebAppSiteResponse.from_app_site(
                    tenant=tenant,
                    app_model=app_model,
+                    mode=AppMode.value_of(app_model.mode),
                    site=site,
                    end_user_id=None,
                    features=features,
@@ -0,0 +1,67 @@
+"""Public web Human Input v2 form stubs.
+
+The hyphenated v2 routes are intentionally separate from the legacy underscored
+Human Input form routes. Each runtime path must reject tokens owned by the other
+version when the service implementation is added.
+"""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+
+from flask import abort
+from flask_restx import Resource
+
+from controllers.common.human_input_v2_contracts import (
+    FormAccessRequestResponse,
+    FormDefinitionResponse,
+    FormSubmitResponse,
+    FormUploadTokenResponse,
+    HumanInputV2FormSubmitRequest,
+)
+from controllers.common.schema import register_response_schema_models, register_schema_models
+from controllers.web import web_ns
+
+register_schema_models(web_ns, HumanInputV2FormSubmitRequest)
+register_response_schema_models(
+    web_ns,
+    FormAccessRequestResponse,
+    FormDefinitionResponse,
+    FormSubmitResponse,
+    FormUploadTokenResponse,
+)
+
+
+def _raise_stub_not_implemented() -> None:
+    abort(HTTPStatus.NOT_IMPLEMENTED, "Human Input v2 form stub endpoint is not implemented yet.")
+
+
+@web_ns.route("/form/human-input/<string:form_token>")
+class HumanInputV2FormApi(Resource):
+    """Read or submit a Human Input v2 form without sharing v1 submission logic."""
+
+    @web_ns.response(200, "Success", web_ns.models[FormDefinitionResponse.__name__])
+    def get(self, form_token: str):
+        _raise_stub_not_implemented()
+
+    @web_ns.expect(web_ns.models[HumanInputV2FormSubmitRequest.__name__])
+    @web_ns.response(200, "Success", web_ns.models[FormSubmitResponse.__name__])
+    def post(self, form_token: str):
+        HumanInputV2FormSubmitRequest.model_validate(web_ns.payload or {})
+        _raise_stub_not_implemented()
+
+
+@web_ns.route("/form/human-input/<string:form_token>/upload-token")
+class HumanInputV2FormUploadTokenApi(Resource):
+    """Issue an upload token for an active Human Input v2 form."""
+
+    @web_ns.response(200, "Success", web_ns.models[FormUploadTokenResponse.__name__])
+    def post(self, form_token: str):
+        _raise_stub_not_implemented()
+
+
+@web_ns.route("/form/human-input/<string:form_token>/access-request")
+class FormAccessRequestApi(Resource):
+    @web_ns.response(200, "Success", web_ns.models[FormAccessRequestResponse.__name__])
+    def post(self, form_token: str):
+        _raise_stub_not_implemented()
@@ -14,7 +14,7 @@ from extensions.storage.storage_type import StorageType
 from fields.base import ResponseModel
 from libs.helper import build_icon_url
 from models.account import Tenant, TenantStatus
-from models.model import App, EndUser, IconType, Site
+from models.model import App, AppMode, EndUser, IconType, Site
 from services.feature_service import FeatureModel, FeatureService
 from services.file_service import FileService

@@ -67,6 +67,7 @@ class WebAppCustomConfigResponse(ResponseModel):

 class WebAppSiteResponse(ResponseModel):
    app_id: str
+    mode: AppMode
    end_user_id: str | None = None
    enable_site: bool
    site: WebSiteResponse
@@ -83,6 +84,7 @@ class WebAppSiteResponse(ResponseModel):
        *,
        tenant: Tenant,
        app_model: App,
+        mode: AppMode,
        site: Site,
        end_user_id: str | None,
        features: FeatureModel,
@@ -109,6 +111,7 @@ class WebAppSiteResponse(ResponseModel):

        return cls(
            app_id=app_model.id,
+            mode=mode,
            end_user_id=end_user_id,
            enable_site=app_model.enable_site,
            site=site_response,
@@ -167,6 +170,7 @@ class AppSiteApi(WebApiResource):
        return WebAppSiteResponse.from_app_site(
            tenant=tenant,
            app_model=app_model,
+            mode=AppMode.value_of(app_model.mode_compatible_with_agent_with_session(session=db.session())),
            site=site,
            end_user_id=end_user.id,
            features=features,
@@ -616,23 +616,34 @@ class AdvancedChatAppGenerator(MessageBasedAppGenerator):
            message_snapshot = MessageSnapshot.from_message(message)
            session.close()

-            # return response or stream generator
-            response = self._handle_advanced_chat_response(
-                application_generate_entity=application_generate_entity,
-                workflow=workflow_snapshot,
-                queue_manager=queue_manager,
-                conversation=conversation_snapshot,
-                message=message_snapshot,
-                user=user,
-                stream=stream,
-                draft_var_saver_factory=self._get_draft_var_saver_factory(
-                    invoke_from,
-                    account=user,
-                    tenant_id=application_generate_entity.app_config.tenant_id,
-                ),
-            )
+            try:
+                response = self._handle_advanced_chat_response(
+                    application_generate_entity=application_generate_entity,
+                    workflow=workflow_snapshot,
+                    queue_manager=queue_manager,
+                    conversation=conversation_snapshot,
+                    message=message_snapshot,
+                    user=user,
+                    stream=stream,
+                    draft_var_saver_factory=self._get_draft_var_saver_factory(
+                        invoke_from,
+                        account=user,
+                        tenant_id=application_generate_entity.app_config.tenant_id,
+                    ),
+                )
+                converted_response = AdvancedChatAppGenerateResponseConverter.convert(
+                    response=response,
+                    invoke_from=invoke_from,
+                )
+            except BaseException:
+                self._join_worker_thread(worker_thread)
+                raise

-            return AdvancedChatAppGenerateResponseConverter.convert(response=response, invoke_from=invoke_from)
+            if isinstance(converted_response, Generator):
+                return self._wrap_stream_with_worker_thread_join(converted_response, worker_thread)
+
+            self._join_worker_thread(worker_thread)
+            return converted_response

    def _generate_worker(
        self,
@@ -538,6 +538,7 @@ class AgentAppGenerator(MessageBasedAppGenerator):
            request_builder=AgentAppRuntimeRequestBuilder(credentials_provider=credentials_provider),
            agent_backend_client=create_agent_backend_run_client(
                base_url=dify_config.AGENT_BACKEND_BASE_URL,
+                api_token=dify_config.AGENT_BACKEND_API_TOKEN,
                use_fake=dify_config.AGENT_BACKEND_USE_FAKE,
                fake_scenario=dify_config.AGENT_BACKEND_FAKE_SCENARIO,
                stream_read_timeout_seconds=dify_config.AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS,
@@ -1,3 +1,5 @@
+import logging
+import threading
 from collections.abc import Generator, Mapping, Sequence
 from contextlib import AbstractContextManager, nullcontext
 from typing import TYPE_CHECKING, Any, Union, final
@@ -23,6 +25,10 @@ from services.workflow_draft_variable_service import DraftVariableSaver as Draft
 if TYPE_CHECKING:
    from graphon.variables.input_entities import VariableEntity

+logger = logging.getLogger(__name__)
+
+_WORKER_THREAD_JOIN_TIMEOUT_SECONDS = 300
+

@final
 class _DebuggerDraftVariableSaver:
@@ -64,6 +70,29 @@ class _DebuggerDraftVariableSaver:
 class BaseAppGenerator:
    _file_access_controller: DatabaseFileAccessController = DatabaseFileAccessController()

+    @staticmethod
+    def _join_worker_thread(worker_thread: threading.Thread) -> None:
+        # Bound the wait so a leaked app worker cannot occupy an execution slot indefinitely.
+        worker_thread.join(timeout=_WORKER_THREAD_JOIN_TIMEOUT_SECONDS)
+        if worker_thread.is_alive():
+            logger.warning(
+                "Possible app worker thread leak: thread_name=%s timeout_seconds=%s; "
+                "continuing without waiting further to avoid occupying an execution slot indefinitely",
+                worker_thread.name,
+                _WORKER_THREAD_JOIN_TIMEOUT_SECONDS,
+            )
+
+    @staticmethod
+    def _wrap_stream_with_worker_thread_join[ResponseT](
+        response_stream: Generator[ResponseT, None, None],
+        worker_thread: threading.Thread,
+    ) -> Generator[ResponseT, None, None]:
+        """Keep the producer owned by the response stream until both finish."""
+        try:
+            yield from response_stream
+        finally:
+            BaseAppGenerator._join_worker_thread(worker_thread)
+
    @staticmethod
    def _bind_file_access_scope(
        *,
@@ -351,17 +351,28 @@ class PipelineGenerator(BaseAppGenerator):
                user,
                tenant_id=pipeline.tenant_id,
            )
-            # return response or stream generator
-            response = self._handle_response(
-                application_generate_entity=application_generate_entity,
-                workflow=workflow,
-                queue_manager=queue_manager,
-                user=user,
-                stream=streaming,
-                draft_var_saver_factory=draft_var_saver_factory,
-            )
+            try:
+                response = self._handle_response(
+                    application_generate_entity=application_generate_entity,
+                    workflow=workflow,
+                    queue_manager=queue_manager,
+                    user=user,
+                    stream=streaming,
+                    draft_var_saver_factory=draft_var_saver_factory,
+                )
+                converted_response = WorkflowAppGenerateResponseConverter.convert(
+                    response=response,
+                    invoke_from=invoke_from,
+                )
+            except BaseException:
+                self._join_worker_thread(worker_thread)
+                raise

-            return WorkflowAppGenerateResponseConverter.convert(response=response, invoke_from=invoke_from)
+            if isinstance(converted_response, Generator):
+                return self._wrap_stream_with_worker_thread_join(converted_response, worker_thread)
+
+            self._join_worker_thread(worker_thread)
+            return converted_response

    def single_iteration_generate(
        self,
@@ -405,17 +405,28 @@ class WorkflowAppGenerator(BaseAppGenerator):
                tenant_id=app_model.tenant_id,
            )

-            # return response or stream generator
-            response = self._handle_response(
-                application_generate_entity=application_generate_entity,
-                workflow=workflow,
-                queue_manager=queue_manager,
-                user=user,
-                draft_var_saver_factory=draft_var_saver_factory,
-                stream=streaming,
-            )
+            try:
+                response = self._handle_response(
+                    application_generate_entity=application_generate_entity,
+                    workflow=workflow,
+                    queue_manager=queue_manager,
+                    user=user,
+                    draft_var_saver_factory=draft_var_saver_factory,
+                    stream=streaming,
+                )
+                converted_response = WorkflowAppGenerateResponseConverter.convert(
+                    response=response,
+                    invoke_from=invoke_from,
+                )
+            except BaseException:
+                self._join_worker_thread(worker_thread)
+                raise

-            return WorkflowAppGenerateResponseConverter.convert(response=response, invoke_from=invoke_from)
+            if isinstance(converted_response, Generator):
+                return self._wrap_stream_with_worker_thread_join(converted_response, worker_thread)
+
+            self._join_worker_thread(worker_thread)
+            return converted_response

    def single_iteration_generate(
        self,
@@ -88,7 +88,7 @@ from graphon.graph_events import (
 from graphon.runtime import GraphRuntimeState, VariablePool
 from graphon.variable_loader import DUMMY_VARIABLE_LOADER, VariableLoader, load_into_variable_pool
 from models.workflow import Workflow
-from tasks.mail_human_input_delivery_task import dispatch_human_input_email_task
+from tasks.mail_human_input_delivery_task import dispatch_human_input_form_delivery_task

 logger = logging.getLogger(__name__)

@@ -715,12 +715,12 @@ class WorkflowBasedAppRunner:
            if not reason.form_id:
                continue
            try:
-                dispatch_human_input_email_task.apply_async(
+                dispatch_human_input_form_delivery_task.apply_async(
                    kwargs={"form_id": reason.form_id, "node_title": reason.node_title},
                    queue="mail",
                )
            except Exception:  # pragma: no cover - defensive logging
-                logger.exception("Failed to enqueue human input email task for form %s", reason.form_id)
+                logger.exception("Failed to enqueue human input form delivery task for form %s", reason.form_id)

    def _publish_event(self, event: AppQueueEvent):
        self._queue_manager.publish(event, PublishFrom.APPLICATION_MANAGER)
@@ -39,15 +39,16 @@ class Jinja2TemplateTransformer(TemplateTransformer):
    @override
    def get_runner_script(cls) -> str:
        runner_script = dedent(f"""
-            import jinja2
            import json
            from base64 import b64decode
+            from jinja2.sandbox import SandboxedEnvironment

            # declare main function
            def main(**inputs):
                # Decode base64-encoded template to handle special characters safely
                template_code = b64decode('{cls._template_b64_placeholder}').decode('utf-8')
-                template = jinja2.Template(template_code)
+                env = SandboxedEnvironment()
+                template = env.from_string(template_code)
                return template.render(**inputs)

            # decode and prepare input dict
@@ -67,12 +68,13 @@ class Jinja2TemplateTransformer(TemplateTransformer):
    @override
    def get_preload_script(cls) -> str:
        preload_script = dedent("""
-            import jinja2
+            from jinja2.sandbox import SandboxedEnvironment
            from base64 import b64decode

            def _jinja2_preload_():
-                # prepare jinja2 environment, load template and render before to avoid sandbox issue
-                template = jinja2.Template('{{s}}')
+                # prepare jinja2 sandboxed environment, load template and render
+                env = SandboxedEnvironment()
+                template = env.from_string('{{s}}')
                template.render(s='a')

            if __name__ == '__main__':
@@ -0,0 +1,236 @@
+"""Human Input v2 recipient planning, Form, and OTP aggregate boundaries.
+
+The package owns separate Form and OTP aggregate boundaries plus grant,
+delivery, and upload facts. It exposes domain and persistence ports without
+importing transport, provider, database-session, or ORM concerns.
+"""
+
+from .delivery import (
+    ConsoleEndpointConfiguration,
+    DeliveryAttempt,
+    DeliveryEndpoint,
+    DeliveryEndpointConfiguration,
+    EmailEndpointConfiguration,
+    EmailProviderConfiguration,
+    EndpointAccessCapability,
+    IMEndpointConfiguration,
+    UploadCapability,
+    UploadCapabilityRef,
+    UploadFileAssociation,
+    WebEndpointConfiguration,
+)
+from .form import (
+    FormCreation,
+    FormInactiveReason,
+    FormSnapshotIdentifierFactory,
+    FormState,
+    FrozenFormAction,
+    FrozenFormDefinition,
+    HumanInputForm,
+    InactiveFormState,
+    InvalidApproverGrantError,
+    InvalidSelectedActionError,
+    SubmissionTransitionDecision,
+    WaitingFormState,
+)
+from .frozen_values import FrozenJSONArray, FrozenJSONObject, JSONPrimitive
+from .grants import ApproverGrant, ApproverGrantRef, DeliveryEndpointRef, FormRef, OTPChallengeRef
+from .otp import (
+    Clock,
+    ContactOTPSubject,
+    CurrentEmailOTPIdentity,
+    EmailAddressOTPSubject,
+    EmailOTPProofAuthorizationDecision,
+    EmailOTPSubject,
+    OTPChallenge,
+    OTPChallengePublicPrimitive,
+    OTPChallengeRejectionReason,
+    OTPChallengeRepository,
+    OTPChallengeState,
+    OTPCodeHash,
+    OTPCodeHasher,
+    OTPReplacementDecision,
+    OTPVerificationDecision,
+    VerifiedEmailOTPProof,
+    VerifiedEmailOTPProofPrimitive,
+    authorize_email_otp_proof,
+)
+from .ports import FormDefinitionProjection, FormDeliveryProjection, FormRepository
+from .recipient_resolution import (
+    ApprovalSubject,
+    CanonicalSubjectKey,
+    ConsoleEndpointPlan,
+    ContactApprovalSubject,
+    ContactInitiatorSnapshot,
+    DebugRecipientReplacement,
+    DeliveryCapabilitySnapshot,
+    DeliveryEndpointPlan,
+    EmailAddressApprovalSubject,
+    EmailEndpointPlan,
+    EndUserApprovalSubject,
+    EndUserInitiatorSnapshot,
+    IMEndpointPlan,
+    MatchedRecipientSource,
+    RecipientRejectionReason,
+    RecipientResolutionFailureReason,
+    RecipientResolver,
+    RecipientSourceKind,
+    RejectedRecipient,
+    ResolvedApprovalPlan,
+    ResolvedApprover,
+    SubjectSnapshot,
+    WebEndpointPlan,
+)
+from .recipient_specifications import (
+    ContactRecipientSpecification,
+    CurrentInitiatorRecipientSpecification,
+    DynamicEmailRecipientSpecification,
+    DynamicRecipientValue,
+    OneTimeEmailRecipientSpecification,
+    RecipientSpecification,
+    RecipientSpecificationKind,
+    UnsupportedDynamicRecipientValue,
+    WorkflowRecipientSpecificationAdapter,
+)
+from .submission_authorization import (
+    AccountSubmissionActor,
+    AuthorizationContext,
+    AuthorizedSubmission,
+    CurrentContactAuthorizationFacts,
+    CurrentEndUserAuthorizationFacts,
+    CurrentIMAuthorizationFacts,
+    EmailAddressSubmissionActor,
+    EndUserSubmissionActor,
+    SubmissionActor,
+    SubmissionAuthorizationDecision,
+    SubmissionAuthorizationRejection,
+    SubmissionAuthorizer,
+    VerifiedAccountSessionProof,
+    VerifiedIMIdentityProof,
+    VerifiedSubmissionProof,
+    VerifiedTrustedEndUserProof,
+)
+from .submission_ports import (
+    AuthorizedSubmissionCommit,
+    RetryableSubmissionPersistenceError,
+    SubmissionAttemptScope,
+    SubmissionCommitResult,
+    SubmissionCommitStatus,
+    SubmissionRepository,
+    SubmissionTransaction,
+)
+from .submission_records import FormAuthorizationAuditEvent, FormAuthorizationAuditEventType, FormSubmission
+
+__all__ = [
+    "AccountSubmissionActor",
+    "ApprovalSubject",
+    "ApproverGrant",
+    "ApproverGrantRef",
+    "AuthorizationContext",
+    "AuthorizedSubmission",
+    "AuthorizedSubmissionCommit",
+    "CanonicalSubjectKey",
+    "Clock",
+    "ConsoleEndpointConfiguration",
+    "ConsoleEndpointPlan",
+    "ContactApprovalSubject",
+    "ContactInitiatorSnapshot",
+    "ContactOTPSubject",
+    "ContactRecipientSpecification",
+    "CurrentContactAuthorizationFacts",
+    "CurrentEmailOTPIdentity",
+    "CurrentEndUserAuthorizationFacts",
+    "CurrentIMAuthorizationFacts",
+    "CurrentInitiatorRecipientSpecification",
+    "DebugRecipientReplacement",
+    "DeliveryAttempt",
+    "DeliveryCapabilitySnapshot",
+    "DeliveryEndpoint",
+    "DeliveryEndpointConfiguration",
+    "DeliveryEndpointPlan",
+    "DeliveryEndpointRef",
+    "DynamicEmailRecipientSpecification",
+    "DynamicRecipientValue",
+    "EmailAddressApprovalSubject",
+    "EmailAddressOTPSubject",
+    "EmailAddressSubmissionActor",
+    "EmailEndpointConfiguration",
+    "EmailEndpointPlan",
+    "EmailOTPProofAuthorizationDecision",
+    "EmailOTPSubject",
+    "EmailProviderConfiguration",
+    "EndUserApprovalSubject",
+    "EndUserInitiatorSnapshot",
+    "EndUserSubmissionActor",
+    "EndpointAccessCapability",
+    "FormAuthorizationAuditEvent",
+    "FormAuthorizationAuditEventType",
+    "FormCreation",
+    "FormDefinitionProjection",
+    "FormDeliveryProjection",
+    "FormInactiveReason",
+    "FormRef",
+    "FormRepository",
+    "FormSnapshotIdentifierFactory",
+    "FormState",
+    "FormSubmission",
+    "FrozenFormAction",
+    "FrozenFormDefinition",
+    "FrozenJSONArray",
+    "FrozenJSONObject",
+    "HumanInputForm",
+    "IMEndpointConfiguration",
+    "IMEndpointPlan",
+    "InactiveFormState",
+    "InvalidApproverGrantError",
+    "InvalidSelectedActionError",
+    "JSONPrimitive",
+    "MatchedRecipientSource",
+    "OTPChallenge",
+    "OTPChallengePublicPrimitive",
+    "OTPChallengeRef",
+    "OTPChallengeRejectionReason",
+    "OTPChallengeRepository",
+    "OTPChallengeState",
+    "OTPCodeHash",
+    "OTPCodeHasher",
+    "OTPReplacementDecision",
+    "OTPVerificationDecision",
+    "OneTimeEmailRecipientSpecification",
+    "RecipientRejectionReason",
+    "RecipientResolutionFailureReason",
+    "RecipientResolver",
+    "RecipientSourceKind",
+    "RecipientSpecification",
+    "RecipientSpecificationKind",
+    "RejectedRecipient",
+    "ResolvedApprovalPlan",
+    "ResolvedApprover",
+    "RetryableSubmissionPersistenceError",
+    "SubjectSnapshot",
+    "SubmissionActor",
+    "SubmissionAttemptScope",
+    "SubmissionAuthorizationDecision",
+    "SubmissionAuthorizationRejection",
+    "SubmissionAuthorizer",
+    "SubmissionCommitResult",
+    "SubmissionCommitStatus",
+    "SubmissionRepository",
+    "SubmissionTransaction",
+    "SubmissionTransitionDecision",
+    "UnsupportedDynamicRecipientValue",
+    "UploadCapability",
+    "UploadCapabilityRef",
+    "UploadFileAssociation",
+    "VerifiedAccountSessionProof",
+    "VerifiedEmailOTPProof",
+    "VerifiedEmailOTPProofPrimitive",
+    "VerifiedIMIdentityProof",
+    "VerifiedSubmissionProof",
+    "VerifiedTrustedEndUserProof",
+    "WaitingFormState",
+    "WebEndpointConfiguration",
+    "WebEndpointPlan",
+    "WorkflowRecipientSpecificationAdapter",
+    "authorize_email_otp_proof",
+]
@@ -0,0 +1,287 @@
+"""Frozen delivery, provider, endpoint-token, and upload facts.
+
+Endpoints describe where a form can be delivered or interacted with. Their
+tokens are scoped capabilities only; this module deliberately exposes no actor
+or verified-proof conversion. Delivery attempts are append-only diagnostics and
+cannot mutate :class:`HumanInputForm` lifecycle state.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import assert_never
+
+from core.human_input_v2.entities import (
+    EmailProviderType,
+    HumanInputDeliveryAttemptStatus,
+    HumanInputDeliveryChannel,
+    IMProvider,
+)
+from core.human_input_v2.shared import (
+    AccountId,
+    AppId,
+    DeliveryAttemptId,
+    DeliveryEndpointId,
+    EmailProviderId,
+    IMBindingId,
+    IMIdentityId,
+    IntegrationId,
+    NormalizedEmail,
+    UploadCapabilityId,
+    UploadFileAssociationId,
+    UtcTimestamp,
+    WorkspaceId,
+)
+
+from .frozen_values import FrozenJSONObject
+from .grants import ApproverGrantRef, DeliveryEndpointRef
+from .recipient_resolution import (
+    ConsoleEndpointPlan,
+    DeliveryEndpointPlan,
+    EmailEndpointPlan,
+    IMEndpointPlan,
+    WebEndpointPlan,
+)
+
+
+def _validate_sha256(value: str, *, label: str) -> None:
+    if len(value) != 64 or any(character not in "0123456789abcdef" for character in value):
+        raise ValueError(f"{label} must be a lower-case SHA-256 digest")
+
+
+@dataclass(frozen=True, slots=True)
+class EndpointAccessCapability:
+    """Hashed endpoint interaction capability that carries no identity proof."""
+
+    endpoint_ref: DeliveryEndpointRef
+    token_hash: str
+
+    def __post_init__(self) -> None:
+        _validate_sha256(self.token_hash, label="endpoint access token hash")
+
+
+@dataclass(frozen=True, slots=True)
+class EmailEndpointConfiguration:
+    """Frozen Email delivery address."""
+
+    email_address: NormalizedEmail
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.EMAIL
+
+
+@dataclass(frozen=True, slots=True)
+class IMEndpointConfiguration:
+    """Credential-free IM interaction snapshot owned by one integration."""
+
+    integration_id: IntegrationId
+    provider: IMProvider
+    provider_tenant_id: str
+    identity_id: IMIdentityId
+    binding_id: IMBindingId | None
+    provider_user_id: str
+
+    def __post_init__(self) -> None:
+        if not self.provider_tenant_id or not self.provider_user_id:
+            raise ValueError("IM endpoint provider identities must not be blank")
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.IM
+
+
+@dataclass(frozen=True, slots=True)
+class WebEndpointConfiguration:
+    """Public or trusted-app web interaction surface."""
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.WEB
+
+
+@dataclass(frozen=True, slots=True)
+class ConsoleEndpointConfiguration:
+    """Authenticated console interaction surface."""
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.CONSOLE
+
+
+type DeliveryEndpointConfiguration = (
+    EmailEndpointConfiguration | IMEndpointConfiguration | WebEndpointConfiguration | ConsoleEndpointConfiguration
+)
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryEndpoint:
+    """Historical endpoint snapshot distinct from its approver grant."""
+
+    ref: DeliveryEndpointRef
+    configuration: DeliveryEndpointConfiguration
+    address_hash: str
+    access_capability: EndpointAccessCapability | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        _validate_sha256(self.address_hash, label="endpoint address hash")
+        if self.access_capability is not None and self.access_capability.endpoint_ref != self.ref:
+            raise ValueError("endpoint access capability owner does not match the endpoint")
+
+    @property
+    def id(self) -> DeliveryEndpointId:
+        return self.ref.endpoint_id
+
+    @property
+    def grant_ref(self) -> ApproverGrantRef:
+        return self.ref.grant_ref
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return self.configuration.channel
+
+    @classmethod
+    def from_plan(
+        cls,
+        *,
+        endpoint_id: DeliveryEndpointId,
+        grant_ref: ApproverGrantRef,
+        endpoint_plan: DeliveryEndpointPlan,
+        access_capability: EndpointAccessCapability | None,
+        now: UtcTimestamp,
+    ) -> DeliveryEndpoint:
+        endpoint_ref = grant_ref.endpoint(endpoint_id)
+        configuration: DeliveryEndpointConfiguration
+        canonical_address: str
+        match endpoint_plan:
+            case EmailEndpointPlan(email_address=email_address):
+                configuration = EmailEndpointConfiguration(email_address)
+                canonical_address = f"email:{email_address}"
+            case IMEndpointPlan(
+                integration_id=integration_id,
+                provider=provider,
+                provider_tenant_id=provider_tenant_id,
+                identity_id=identity_id,
+                binding_id=binding_id,
+                provider_user_id=provider_user_id,
+            ):
+                configuration = IMEndpointConfiguration(
+                    integration_id=integration_id,
+                    provider=provider,
+                    provider_tenant_id=provider_tenant_id,
+                    identity_id=identity_id,
+                    binding_id=binding_id,
+                    provider_user_id=provider_user_id,
+                )
+                canonical_address = f"im:{integration_id}:{provider.value}:{provider_user_id}"
+            case WebEndpointPlan():
+                configuration = WebEndpointConfiguration()
+                canonical_address = "web"
+            case ConsoleEndpointPlan():
+                configuration = ConsoleEndpointConfiguration()
+                canonical_address = "console"
+            case _:
+                assert_never(endpoint_plan)
+        return cls(
+            ref=endpoint_ref,
+            configuration=configuration,
+            address_hash=sha256(canonical_address.encode()).hexdigest(),
+            access_capability=access_capability,
+            created_at=now,
+            updated_at=now,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryAttempt:
+    """Append-only provider delivery outcome scoped to one endpoint."""
+
+    id: DeliveryAttemptId
+    endpoint_ref: DeliveryEndpointRef
+    attempt_number: int
+    status: HumanInputDeliveryAttemptStatus
+    scheduled_at: UtcTimestamp
+    started_at: UtcTimestamp | None
+    finished_at: UtcTimestamp | None
+    provider_message_id: str | None
+    failure_code: str | None
+    failure_reason: str | None
+    provider_response: FrozenJSONObject | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if self.attempt_number < 1:
+            raise ValueError("delivery attempt number must be positive")
+        if self.status is HumanInputDeliveryAttemptStatus.FAILED:
+            if self.finished_at is None:
+                raise ValueError("failed delivery attempt requires finished_at")
+            has_failure_code = self.failure_code is not None and bool(self.failure_code.strip())
+            has_failure_reason = self.failure_reason is not None and bool(self.failure_reason.strip())
+            if not has_failure_code and not has_failure_reason and self.provider_response is None:
+                raise ValueError("failed delivery attempt requires a failure diagnostic")
+        if self.status is not HumanInputDeliveryAttemptStatus.FAILED and (
+            self.failure_code is not None or self.failure_reason is not None
+        ):
+            raise ValueError("only failed delivery attempts may contain failure diagnostics")
+
+
+@dataclass(frozen=True, slots=True)
+class EmailProviderConfiguration:
+    """Workspace provider configuration kept outside the form domain lifecycle."""
+
+    id: EmailProviderId
+    workspace_id: WorkspaceId
+    provider: EmailProviderType
+    sender_email: NormalizedEmail
+    sender_name: str
+    encrypted_credentials: FrozenJSONObject
+    configured_by_account_id: AccountId | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+
+@dataclass(frozen=True, slots=True)
+class UploadCapabilityRef:
+    """Upload capability reference carrying the complete endpoint owner chain."""
+
+    endpoint_ref: DeliveryEndpointRef
+    capability_id: UploadCapabilityId
+    app_id: AppId
+
+
+@dataclass(frozen=True, slots=True)
+class UploadCapability:
+    """Hashed upload capability scoped to exactly one form endpoint."""
+
+    id: UploadCapabilityId
+    endpoint_ref: DeliveryEndpointRef
+    app_id: AppId
+    token_hash: str
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        _validate_sha256(self.token_hash, label="upload token hash")
+
+    @property
+    def ref(self) -> UploadCapabilityRef:
+        return UploadCapabilityRef(self.endpoint_ref, self.id, self.app_id)
+
+
+@dataclass(frozen=True, slots=True)
+class UploadFileAssociation:
+    """Durable file fact whose scope is inherited from its upload capability."""
+
+    id: UploadFileAssociationId
+    capability_ref: UploadCapabilityRef
+    upload_file_id: str
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if not self.upload_file_id.strip():
+            raise ValueError("upload file id must not be blank")
@@ -0,0 +1,261 @@
+"""Rich Human Input v2 form aggregate and plan-to-snapshot creation.
+
+``HumanInputForm`` directly owns every local lifecycle decision: persisted
+status, node/global expiry, grant membership, and selected actions. It returns a
+transition decision only; committing the first successful submission belongs to
+the later submission transaction boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+from core.human_input_v2.entities import HumanInputV2FormKind, HumanInputV2FormStatus
+from core.human_input_v2.shared import (
+    AppId,
+    ApproverGrantId,
+    DeliveryEndpointId,
+    UtcTimestamp,
+)
+
+from .delivery import DeliveryEndpoint
+from .frozen_values import FrozenJSONObject
+from .grants import ApproverGrant, FormRef
+from .recipient_resolution import ResolvedApprovalPlan
+
+
+class InvalidApproverGrantError(ValueError):
+    """The selected grant does not belong to this form snapshot."""
+
+
+class InvalidSelectedActionError(ValueError):
+    """The selected action is absent from the frozen definition."""
+
+
+@dataclass(frozen=True, slots=True)
+class FrozenFormAction:
+    """Immutable action values required for display and transition validation."""
+
+    id: str
+    title: str
+    button_style: str
+
+    def __post_init__(self) -> None:
+        if not self.id or not self.title or not self.button_style:
+            raise ValueError("frozen form action values must not be blank")
+
+
+@dataclass(frozen=True, slots=True)
+class FrozenFormDefinition:
+    """Immutable render and validation definition captured at form creation."""
+
+    form_content: str
+    inputs: tuple[FrozenJSONObject, ...]
+    actions: tuple[FrozenFormAction, ...]
+    default_values: FrozenJSONObject
+    node_title: str | None
+    display_in_ui: bool | None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.inputs, tuple) or not isinstance(self.actions, tuple):
+            raise TypeError("frozen form definition collections must be immutable tuples")
+        action_ids = [action.id for action in self.actions]
+        if len(action_ids) != len(set(action_ids)):
+            raise ValueError("frozen form action identifiers must be unique")
+
+    def accepts_action(self, selected_action_id: str) -> bool:
+        return any(action.id == selected_action_id for action in self.actions)
+
+
+class FormInactiveReason(StrEnum):
+    """Transport-neutral reason why a form cannot accept a transition."""
+
+    SUBMITTED = "submitted"
+    TIMED_OUT = "timed_out"
+    STATUS_EXPIRED = "status_expired"
+    GLOBALLY_EXPIRED = "globally_expired"
+
+
+@dataclass(frozen=True, slots=True)
+class WaitingFormState:
+    """Stable active-state result for a waiting form."""
+
+    is_waiting: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class InactiveFormState:
+    """Stable inactive-state result independent from HTTP status codes."""
+
+    reason: FormInactiveReason
+    is_waiting: bool = False
+
+
+type FormState = WaitingFormState | InactiveFormState
+
+
+@dataclass(frozen=True, slots=True)
+class SubmissionTransitionDecision:
+    """Validated intent that does not claim persistence has committed."""
+
+    form_ref: FormRef
+    grant_id: ApproverGrantId
+    selected_action_id: str
+    decided_at: UtcTimestamp
+
+
+class FormSnapshotIdentifierFactory(Protocol):
+    """Provide child identifiers without coupling the domain to persistence."""
+
+    def new_grant_id(self) -> ApproverGrantId: ...
+
+    def new_endpoint_id(self) -> DeliveryEndpointId: ...
+
+
+@dataclass(frozen=True, slots=True)
+class FormCreation:
+    """Complete form/grant/endpoint snapshot persisted by one transaction."""
+
+    form: HumanInputForm
+    endpoints: tuple[DeliveryEndpoint, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.endpoints, tuple):
+            raise TypeError("form creation endpoints must be an immutable tuple")
+        grant_refs = {grant.ref for grant in self.form.grants}
+        if any(endpoint.grant_ref not in grant_refs for endpoint in self.endpoints):
+            raise ValueError("form creation contains an endpoint outside its grants")
+
+
+@dataclass(frozen=True, slots=True)
+class HumanInputForm:
+    """Form root owning local lifecycle and submission transition invariants."""
+
+    ref: FormRef
+    app_id: AppId
+    definition: FrozenFormDefinition
+    rendered_content: str
+    node_timeout_at: UtcTimestamp
+    global_expires_at: UtcTimestamp
+    kind: HumanInputV2FormKind
+    status: HumanInputV2FormStatus
+    workflow_pause_id: str | None
+    node_execution_id: str | None
+    grants: tuple[ApproverGrant, ...]
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.grants, tuple):
+            raise TypeError("form grants must be an immutable tuple")
+        if self.kind is HumanInputV2FormKind.RUNTIME and (
+            self.workflow_pause_id is None or self.node_execution_id is None
+        ):
+            raise ValueError("runtime form requires workflow pause and node execution owners")
+        if any(grant.ref.form_ref != self.ref for grant in self.grants):
+            raise ValueError("form contains a grant from another owner")
+        grant_ids = [grant.id for grant in self.grants]
+        subject_keys = [grant.subject_key for grant in self.grants]
+        if len(grant_ids) != len(set(grant_ids)) or len(subject_keys) != len(set(subject_keys)):
+            raise ValueError("form grants must have unique identifiers and canonical subjects")
+
+    def state_at(self, now: UtcTimestamp) -> FormState:
+        """Return a stable status/expiry decision without changing persisted state."""
+
+        match self.status:
+            case HumanInputV2FormStatus.SUBMITTED:
+                return InactiveFormState(FormInactiveReason.SUBMITTED)
+            case HumanInputV2FormStatus.TIMEOUT:
+                return InactiveFormState(FormInactiveReason.TIMED_OUT)
+            case HumanInputV2FormStatus.EXPIRED:
+                return InactiveFormState(FormInactiveReason.STATUS_EXPIRED)
+            case HumanInputV2FormStatus.WAITING:
+                if now.value >= self.global_expires_at.value:
+                    return InactiveFormState(FormInactiveReason.GLOBALLY_EXPIRED)
+                if now.value >= self.node_timeout_at.value:
+                    return InactiveFormState(FormInactiveReason.TIMED_OUT)
+                return WaitingFormState()
+        raise AssertionError(f"unsupported Human Input form status: {self.status}")
+
+    def decide_submission(
+        self,
+        *,
+        grant_id: ApproverGrantId,
+        selected_action_id: str,
+        now: UtcTimestamp,
+    ) -> SubmissionTransitionDecision | InactiveFormState:
+        """Validate one local transition without mutating or persisting the form."""
+
+        state = self.state_at(now)
+        if isinstance(state, InactiveFormState):
+            return state
+        if not any(grant.id == grant_id for grant in self.grants):
+            raise InvalidApproverGrantError(str(grant_id))
+        if not self.definition.accepts_action(selected_action_id):
+            raise InvalidSelectedActionError(selected_action_id)
+        return SubmissionTransitionDecision(
+            form_ref=self.ref,
+            grant_id=grant_id,
+            selected_action_id=selected_action_id,
+            decided_at=now,
+        )
+
+    @classmethod
+    def create_from_plan(
+        cls,
+        *,
+        ref: FormRef,
+        app_id: AppId,
+        definition: FrozenFormDefinition,
+        rendered_content: str,
+        node_timeout_at: UtcTimestamp,
+        global_expires_at: UtcTimestamp,
+        kind: HumanInputV2FormKind,
+        workflow_pause_id: str | None,
+        node_execution_id: str | None,
+        plan: ResolvedApprovalPlan,
+        identifier_factory: FormSnapshotIdentifierFactory,
+        now: UtcTimestamp,
+    ) -> FormCreation:
+        """Map one deterministic resolved plan into a complete frozen snapshot."""
+
+        if not plan.approvers:
+            raise ValueError("form creation requires resolved approvers")
+        grants: list[ApproverGrant] = []
+        endpoints: list[DeliveryEndpoint] = []
+        for approver in plan.approvers:
+            grant = ApproverGrant.from_resolved_approver(
+                grant_id=identifier_factory.new_grant_id(),
+                form_ref=ref,
+                approver=approver,
+                now=now,
+            )
+            grants.append(grant)
+            for endpoint_plan in approver.endpoints:
+                endpoints.append(
+                    DeliveryEndpoint.from_plan(
+                        endpoint_id=identifier_factory.new_endpoint_id(),
+                        grant_ref=grant.ref,
+                        endpoint_plan=endpoint_plan,
+                        access_capability=None,
+                        now=now,
+                    )
+                )
+        form = cls(
+            ref=ref,
+            app_id=app_id,
+            definition=definition,
+            rendered_content=rendered_content,
+            node_timeout_at=node_timeout_at,
+            global_expires_at=global_expires_at,
+            kind=kind,
+            status=HumanInputV2FormStatus.WAITING,
+            workflow_pause_id=workflow_pause_id,
+            node_execution_id=node_execution_id,
+            grants=tuple(grants),
+            created_at=now,
+            updated_at=now,
+        )
+        return FormCreation(form=form, endpoints=tuple(endpoints))
@@ -0,0 +1,100 @@
+"""Recursively immutable JSON values used by frozen form snapshots.
+
+Domain code never receives mutable dictionaries from persistence or provider
+boundaries. Explicit conversion methods create fresh primitive containers only
+when a caller crosses such a boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from math import isfinite
+
+type JSONScalar = str | int | float | bool | None
+type JSONPrimitive = JSONScalar | list[JSONPrimitive] | dict[str, JSONPrimitive]
+type FrozenJSONValue = JSONScalar | FrozenJSONArray | FrozenJSONObject
+
+
+def _validate_frozen_json(value: object) -> None:
+    if value is None or isinstance(value, (str, bool, int)):
+        return
+    if isinstance(value, float):
+        if not isfinite(value):
+            raise ValueError("JSON numbers must be finite")
+        return
+    if isinstance(value, (FrozenJSONArray, FrozenJSONObject)):
+        return
+    raise TypeError(f"frozen JSON values cannot contain {type(value).__name__}")
+
+
+def _freeze_json(value: object) -> FrozenJSONValue:
+    if value is None or isinstance(value, (str, bool, int)):
+        return value
+    if isinstance(value, float):
+        if not isfinite(value):
+            raise ValueError("JSON numbers must be finite")
+        return value
+    if isinstance(value, Mapping):
+        return FrozenJSONObject.from_mapping(value)
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return FrozenJSONArray(tuple(_freeze_json(item) for item in value))
+    raise TypeError(f"unsupported JSON value type: {type(value).__name__}")
+
+
+def _thaw_json(value: FrozenJSONValue) -> JSONPrimitive:
+    if isinstance(value, FrozenJSONObject):
+        return value.to_mapping()
+    if isinstance(value, FrozenJSONArray):
+        return value.to_list()
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class FrozenJSONArray:
+    """Immutable JSON array with an explicit primitive conversion boundary."""
+
+    values: tuple[FrozenJSONValue, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.values, tuple):
+            raise TypeError("frozen JSON array values must be an immutable tuple")
+        for value in self.values:
+            _validate_frozen_json(value)
+
+    def to_list(self) -> list[JSONPrimitive]:
+        return [_thaw_json(value) for value in self.values]
+
+
+@dataclass(frozen=True, slots=True)
+class FrozenJSONObject:
+    """Immutable ordered JSON object independent from Pydantic and ORM types."""
+
+    entries: tuple[tuple[str, FrozenJSONValue], ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.entries, tuple):
+            raise TypeError("frozen JSON object entries must be an immutable tuple")
+        seen_keys: set[str] = set()
+        for entry in self.entries:
+            if not isinstance(entry, tuple) or len(entry) != 2:
+                raise TypeError("frozen JSON object entries must be key-value tuples")
+            key, value = entry
+            if not isinstance(key, str):
+                raise TypeError("JSON objects require string keys")
+            if key in seen_keys:
+                raise ValueError(f"duplicate JSON object key: {key}")
+            seen_keys.add(key)
+            _validate_frozen_json(value)
+
+    @classmethod
+    def from_mapping(cls, values: Mapping[str, object]) -> FrozenJSONObject:
+        entries: list[tuple[str, FrozenJSONValue]] = []
+        for key in sorted(values, key=lambda candidate: str(candidate)):
+            if not isinstance(key, str):
+                raise TypeError("JSON objects require string keys")
+            entries.append((key, _freeze_json(values[key])))
+        return cls(tuple(entries))
+
+    def to_mapping(self) -> dict[str, JSONPrimitive]:
+        return {key: _thaw_json(value) for key, value in self.entries}
@@ -0,0 +1,134 @@
+"""Historical approver grants and form-scoped logical references.
+
+Grants capture candidate authority at form creation. They are intentionally not
+current authorization proofs: later submission code must revalidate the current
+identity behind the frozen subject.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import assert_never
+
+from core.human_input_v2.shared import (
+    ApproverGrantId,
+    DeliveryEndpointId,
+    FormId,
+    OTPChallengeId,
+    UtcTimestamp,
+    WorkspaceId,
+)
+
+from .recipient_resolution import (
+    ApprovalSubject,
+    CanonicalSubjectKey,
+    ContactApprovalSubject,
+    EmailAddressApprovalSubject,
+    EndUserApprovalSubject,
+    MatchedRecipientSource,
+    ResolvedApprover,
+    SubjectSnapshot,
+)
+
+
+def _subject_key(subject: ApprovalSubject) -> CanonicalSubjectKey:
+    match subject:
+        case ContactApprovalSubject(contact_id=contact_id):
+            return CanonicalSubjectKey.for_contact(contact_id)
+        case EndUserApprovalSubject(end_user_id=end_user_id):
+            return CanonicalSubjectKey.for_end_user(end_user_id)
+        case EmailAddressApprovalSubject(normalized_email=normalized_email):
+            return CanonicalSubjectKey.for_email(normalized_email)
+        case _:
+            assert_never(subject)
+
+
+@dataclass(frozen=True, slots=True)
+class FormRef:
+    """Workspace-owned root reference; authorization still requires scoped queries."""
+
+    workspace_id: WorkspaceId
+    form_id: FormId
+
+    def grant(self, grant_id: ApproverGrantId) -> ApproverGrantRef:
+        return ApproverGrantRef(self, grant_id)
+
+
+@dataclass(frozen=True, slots=True)
+class ApproverGrantRef:
+    """Grant reference carrying its complete form owner chain."""
+
+    form_ref: FormRef
+    grant_id: ApproverGrantId
+
+    def endpoint(self, endpoint_id: DeliveryEndpointId) -> DeliveryEndpointRef:
+        return DeliveryEndpointRef(self, endpoint_id)
+
+    def challenge(self, challenge_id: OTPChallengeId) -> OTPChallengeRef:
+        return OTPChallengeRef(self, challenge_id)
+
+
+@dataclass(frozen=True, slots=True)
+class OTPChallengeRef:
+    """OTP proof-session reference carrying its complete grant owner chain."""
+
+    grant_ref: ApproverGrantRef
+    challenge_id: OTPChallengeId
+
+    @property
+    def form_ref(self) -> FormRef:
+        return self.grant_ref.form_ref
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryEndpointRef:
+    """Endpoint reference carrying grant, form, and workspace ownership."""
+
+    grant_ref: ApproverGrantRef
+    endpoint_id: DeliveryEndpointId
+
+    @property
+    def form_ref(self) -> FormRef:
+        return self.grant_ref.form_ref
+
+
+@dataclass(frozen=True, slots=True)
+class ApproverGrant:
+    """Frozen candidate approver with historical matched-source facts."""
+
+    ref: ApproverGrantRef
+    subject: ApprovalSubject
+    subject_key: CanonicalSubjectKey
+    matched_sources: tuple[MatchedRecipientSource, ...]
+    subject_snapshot: SubjectSnapshot
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.matched_sources, tuple):
+            raise TypeError("matched sources must be an immutable tuple")
+        if self.subject_key != _subject_key(self.subject):
+            raise ValueError("approver grant subject key does not match its subject")
+
+    @property
+    def id(self) -> ApproverGrantId:
+        return self.ref.grant_id
+
+    @classmethod
+    def from_resolved_approver(
+        cls,
+        *,
+        grant_id: ApproverGrantId,
+        form_ref: FormRef,
+        approver: ResolvedApprover,
+        now: UtcTimestamp,
+    ) -> ApproverGrant:
+        return cls(
+            ref=form_ref.grant(grant_id),
+            subject=approver.subject,
+            subject_key=approver.subject_key,
+            matched_sources=approver.matched_sources,
+            subject_snapshot=approver.subject_snapshot,
+            created_at=now,
+            updated_at=now,
+        )
@@ -0,0 +1,460 @@
+"""Independent Email OTP proof-session lifecycle and limited proof boundary.
+
+The aggregate owns only challenge expiry, cooldown, counters, verification, and
+invalidation. It never reads or mutates :class:`HumanInputForm`; submission code
+must separately compare a verified proof with coherent current identity facts.
+Plaintext codes are transient method inputs and are never retained or serialized.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from datetime import timedelta
+from enum import StrEnum
+from typing import Protocol, TypedDict
+
+from core.human_input_v2.entities import HumanInputAuthorizationProofType, HumanInputOTPChallengeStatus
+from core.human_input_v2.shared import ContactId, NormalizedEmail, OTPChallengeId, UtcTimestamp
+
+from .grants import ApproverGrantRef, OTPChallengeRef
+
+OTP_EXPIRY = timedelta(minutes=10)
+OTP_RESEND_COOLDOWN = timedelta(seconds=60)
+OTP_MAX_SEND_COUNT = 5
+OTP_MAX_ATTEMPT_COUNT = 5
+
+
+def _validate_sha256(value: str, *, label: str) -> None:
+    if len(value) != 64 or any(character not in "0123456789abcdef" for character in value):
+        raise ValueError(f"{label} must be a lower-case SHA-256 digest")
+
+
+class Clock(Protocol):
+    """Narrow clock port used to make all lifecycle boundaries deterministic."""
+
+    def now(self) -> UtcTimestamp: ...
+
+
+@dataclass(frozen=True, slots=True)
+class OTPCodeHash:
+    """Opaque encoded code digest plus the verifier algorithm discriminator."""
+
+    encoded_value: str
+    algorithm: str
+
+    def __post_init__(self) -> None:
+        if not self.encoded_value or not self.algorithm.strip():
+            raise ValueError("OTP code hash values must not be blank")
+
+
+class OTPCodeHasher(Protocol):
+    """Hash and verify transient plaintext without exposing implementation policy."""
+
+    def hash_code(self, plaintext_code: str) -> OTPCodeHash: ...
+
+    def verify_code(self, plaintext_code: str, code_hash: OTPCodeHash) -> bool: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ContactOTPSubject:
+    """Contact incarnation captured when an OTP challenge is issued."""
+
+    contact_id: ContactId
+
+
+@dataclass(frozen=True, slots=True)
+class EmailAddressOTPSubject:
+    """Standalone normalized Email subject captured from a one-time grant."""
+
+    normalized_email: NormalizedEmail
+
+
+type EmailOTPSubject = ContactOTPSubject | EmailAddressOTPSubject
+
+
+class OTPChallengeRejectionReason(StrEnum):
+    """Transport-neutral reason for a rejected OTP or proof operation."""
+
+    EXPIRED = "expired"
+    RESEND_COOLDOWN = "resend_cooldown"
+    SEND_LIMIT_REACHED = "send_limit_reached"
+    ATTEMPT_LIMIT_REACHED = "attempt_limit_reached"
+    ALREADY_VERIFIED = "already_verified"
+    INVALIDATED = "invalidated"
+    INVALID_CODE = "invalid_code"
+    RAW_CODE_NOT_VERIFIED = "raw_code_not_verified"
+    GRANT_MISMATCH = "grant_mismatch"
+    STALE_IDENTITY = "stale_identity"
+
+
+class OTPChallengePublicPrimitive(TypedDict):
+    """Secret-free diagnostic form of challenge state."""
+
+    otp_challenge_id: str
+    form_id: str
+    approver_grant_id: str
+    status: str
+    email: str
+    send_count: int
+    attempt_count: int
+    expires_at: str
+    resend_after: str
+    verified_at: str | None
+    invalidated_at: str | None
+
+
+class VerifiedEmailOTPProofPrimitive(TypedDict):
+    """Primitive proof shape safe for authorization and audit boundaries."""
+
+    type: str
+    otp_challenge_id: str
+    form_id: str
+    approver_grant_id: str
+    subject_type: str
+    contact_id: str | None
+    verified_email: str
+    verified_at: str
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedEmailOTPProof:
+    """Immutable Email verification fact that carries no submission authority."""
+
+    challenge_ref: OTPChallengeRef
+    subject: EmailOTPSubject
+    normalized_email: NormalizedEmail
+    verified_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if isinstance(self.subject, EmailAddressOTPSubject) and self.subject.normalized_email != self.normalized_email:
+            raise ValueError("OTP proof subject email must match the verified email")
+
+    def to_primitive(self) -> VerifiedEmailOTPProofPrimitive:
+        contact_id: str | None = None
+        subject_type = "email_address"
+        if isinstance(self.subject, ContactOTPSubject):
+            subject_type = "contact"
+            contact_id = str(self.subject.contact_id)
+        return {
+            "type": HumanInputAuthorizationProofType.EMAIL_OTP.value,
+            "otp_challenge_id": str(self.challenge_ref.challenge_id),
+            "form_id": str(self.challenge_ref.form_ref.form_id),
+            "approver_grant_id": str(self.challenge_ref.grant_ref.grant_id),
+            "subject_type": subject_type,
+            "contact_id": contact_id,
+            "verified_email": str(self.normalized_email),
+            "verified_at": self.verified_at.to_primitive(),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class OTPChallengeState:
+    """Stable current usability result independent from transport status codes."""
+
+    status: HumanInputOTPChallengeStatus
+    rejection: OTPChallengeRejectionReason | None
+
+    @property
+    def is_usable(self) -> bool:
+        return self.rejection is None
+
+
+@dataclass(frozen=True, slots=True)
+class OTPReplacementDecision:
+    """Immutable replacement result; persistence commits both states atomically."""
+
+    previous: OTPChallenge
+    replacement: OTPChallenge | None
+    rejection: OTPChallengeRejectionReason | None
+
+
+@dataclass(frozen=True, slots=True)
+class OTPVerificationDecision:
+    """Verification result containing either one limited proof or one rejection."""
+
+    challenge: OTPChallenge
+    proof: VerifiedEmailOTPProof | None
+    rejection: OTPChallengeRejectionReason | None
+
+
+@dataclass(frozen=True, slots=True)
+class OTPChallenge:
+    """Grant-scoped proof session whose counters never touch Form lifecycle state.
+
+    Persisted sessions reconstruct only when cooldown and expiry are the exact
+    durations derived from ``created_at``; stored timestamps are not policy input.
+    """
+
+    ref: OTPChallengeRef
+    subject: EmailOTPSubject
+    normalized_email: NormalizedEmail
+    challenge_token_hash: str = field(repr=False)
+    code_hash: OTPCodeHash = field(repr=False)
+    status: HumanInputOTPChallengeStatus
+    expires_at: UtcTimestamp
+    resend_after: UtcTimestamp
+    send_count: int
+    attempt_count: int
+    verified_at: UtcTimestamp | None
+    invalidated_at: UtcTimestamp | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        _validate_sha256(self.challenge_token_hash, label="challenge token hash")
+        if isinstance(self.subject, EmailAddressOTPSubject) and self.subject.normalized_email != self.normalized_email:
+            raise ValueError("OTP challenge subject email must match the destination email")
+        if not 1 <= self.send_count <= OTP_MAX_SEND_COUNT:
+            raise ValueError("OTP send count is outside the supported range")
+        if not 0 <= self.attempt_count <= OTP_MAX_ATTEMPT_COUNT:
+            raise ValueError("OTP attempt count is outside the supported range")
+        if self.resend_after.value != self.created_at.value + OTP_RESEND_COOLDOWN:
+            raise ValueError("OTP resend_after must equal created_at plus the resend cooldown")
+        if self.expires_at.value != self.created_at.value + OTP_EXPIRY:
+            raise ValueError("OTP expires_at must equal created_at plus the expiry duration")
+        if self.updated_at.value < self.created_at.value:
+            raise ValueError("OTP updated_at must not precede created_at")
+        if self.status is HumanInputOTPChallengeStatus.VERIFIED:
+            if self.verified_at is None or self.invalidated_at is not None:
+                raise ValueError("verified OTP challenge requires only verified_at")
+        elif self.status is HumanInputOTPChallengeStatus.INVALIDATED:
+            if self.invalidated_at is None or self.verified_at is not None:
+                raise ValueError("invalidated OTP challenge requires only invalidated_at")
+        elif self.verified_at is not None or self.invalidated_at is not None:
+            raise ValueError("pending and expired OTP challenges cannot have terminal timestamps")
+
+    @classmethod
+    def issue(
+        cls,
+        *,
+        challenge_ref: OTPChallengeRef,
+        subject: EmailOTPSubject,
+        normalized_email: NormalizedEmail,
+        challenge_token_hash: str,
+        plaintext_code: str,
+        send_count: int,
+        clock: Clock,
+        code_hasher: OTPCodeHasher,
+    ) -> OTPChallenge:
+        """Hash a transient code and create one pending proof session."""
+
+        now = clock.now()
+        return cls(
+            ref=challenge_ref,
+            subject=subject,
+            normalized_email=normalized_email,
+            challenge_token_hash=challenge_token_hash,
+            code_hash=code_hasher.hash_code(plaintext_code),
+            status=HumanInputOTPChallengeStatus.PENDING,
+            expires_at=UtcTimestamp(now.value + OTP_EXPIRY),
+            resend_after=UtcTimestamp(now.value + OTP_RESEND_COOLDOWN),
+            send_count=send_count,
+            attempt_count=0,
+            verified_at=None,
+            invalidated_at=None,
+            created_at=now,
+            updated_at=now,
+        )
+
+    def state_at(self, now: UtcTimestamp) -> OTPChallengeState:
+        match self.status:
+            case HumanInputOTPChallengeStatus.VERIFIED:
+                return OTPChallengeState(self.status, OTPChallengeRejectionReason.ALREADY_VERIFIED)
+            case HumanInputOTPChallengeStatus.INVALIDATED:
+                return OTPChallengeState(self.status, OTPChallengeRejectionReason.INVALIDATED)
+            case HumanInputOTPChallengeStatus.EXPIRED:
+                return OTPChallengeState(self.status, OTPChallengeRejectionReason.EXPIRED)
+            case HumanInputOTPChallengeStatus.PENDING:
+                if now.value >= self.expires_at.value:
+                    return OTPChallengeState(HumanInputOTPChallengeStatus.EXPIRED, OTPChallengeRejectionReason.EXPIRED)
+                return OTPChallengeState(self.status, None)
+        raise AssertionError(f"unsupported OTP challenge status: {self.status}")
+
+    def replace(
+        self,
+        *,
+        challenge_ref: OTPChallengeRef,
+        challenge_token_hash: str,
+        plaintext_code: str,
+        clock: Clock,
+        code_hasher: OTPCodeHasher,
+    ) -> OTPReplacementDecision:
+        """Prepare an eligible replacement without persisting either state."""
+
+        now = clock.now()
+        state = self.state_at(now)
+        if (
+            state.rejection is OTPChallengeRejectionReason.EXPIRED
+            and self.status is HumanInputOTPChallengeStatus.PENDING
+        ):
+            expired = replace(
+                self,
+                status=HumanInputOTPChallengeStatus.EXPIRED,
+                updated_at=now,
+            )
+            return OTPReplacementDecision(expired, None, OTPChallengeRejectionReason.EXPIRED)
+        if state.rejection is not None:
+            return OTPReplacementDecision(self, None, state.rejection)
+        if self.send_count >= OTP_MAX_SEND_COUNT:
+            return OTPReplacementDecision(self, None, OTPChallengeRejectionReason.SEND_LIMIT_REACHED)
+        if now.value < self.resend_after.value:
+            return OTPReplacementDecision(self, None, OTPChallengeRejectionReason.RESEND_COOLDOWN)
+        replacement_challenge = self.issue(
+            challenge_ref=challenge_ref,
+            subject=self.subject,
+            normalized_email=self.normalized_email,
+            challenge_token_hash=challenge_token_hash,
+            plaintext_code=plaintext_code,
+            send_count=self.send_count + 1,
+            clock=clock,
+            code_hasher=code_hasher,
+        )
+        invalidated = replace(
+            self,
+            status=HumanInputOTPChallengeStatus.INVALIDATED,
+            invalidated_at=now,
+            updated_at=now,
+        )
+        return OTPReplacementDecision(invalidated, replacement_challenge, None)
+
+    def verify(
+        self,
+        *,
+        plaintext_code: str,
+        clock: Clock,
+        code_hasher: OTPCodeHasher,
+    ) -> OTPVerificationDecision:
+        """Verify one transient code while preserving exact attempt boundaries."""
+
+        now = clock.now()
+        state = self.state_at(now)
+        if (
+            state.rejection is OTPChallengeRejectionReason.EXPIRED
+            and self.status is HumanInputOTPChallengeStatus.PENDING
+        ):
+            expired = replace(
+                self,
+                status=HumanInputOTPChallengeStatus.EXPIRED,
+                updated_at=now,
+            )
+            return OTPVerificationDecision(expired, None, OTPChallengeRejectionReason.EXPIRED)
+        if state.rejection is not None:
+            return OTPVerificationDecision(self, None, state.rejection)
+        if self.attempt_count >= OTP_MAX_ATTEMPT_COUNT:
+            return OTPVerificationDecision(self, None, OTPChallengeRejectionReason.ATTEMPT_LIMIT_REACHED)
+        attempt_count = self.attempt_count + 1
+        if not code_hasher.verify_code(plaintext_code, self.code_hash):
+            attempted = replace(self, attempt_count=attempt_count, updated_at=now)
+            return OTPVerificationDecision(attempted, None, OTPChallengeRejectionReason.INVALID_CODE)
+        verified = replace(
+            self,
+            status=HumanInputOTPChallengeStatus.VERIFIED,
+            attempt_count=attempt_count,
+            verified_at=now,
+            updated_at=now,
+        )
+        proof = VerifiedEmailOTPProof(
+            challenge_ref=self.ref,
+            subject=self.subject,
+            normalized_email=self.normalized_email,
+            verified_at=now,
+        )
+        return OTPVerificationDecision(verified, proof, None)
+
+    def invalidate(self, *, clock: Clock) -> OTPChallenge:
+        """Make a pending proof session unusable without changing its counters."""
+
+        if self.status is not HumanInputOTPChallengeStatus.PENDING:
+            return self
+        now = clock.now()
+        return replace(
+            self,
+            status=HumanInputOTPChallengeStatus.INVALIDATED,
+            invalidated_at=now,
+            updated_at=now,
+        )
+
+    def to_public_primitive(self) -> OTPChallengePublicPrimitive:
+        """Return state diagnostics while deliberately excluding all hashes."""
+
+        return {
+            "otp_challenge_id": str(self.ref.challenge_id),
+            "form_id": str(self.ref.form_ref.form_id),
+            "approver_grant_id": str(self.ref.grant_ref.grant_id),
+            "status": self.status.value,
+            "email": str(self.normalized_email),
+            "send_count": self.send_count,
+            "attempt_count": self.attempt_count,
+            "expires_at": self.expires_at.to_primitive(),
+            "resend_after": self.resend_after.to_primitive(),
+            "verified_at": self.verified_at.to_primitive() if self.verified_at is not None else None,
+            "invalidated_at": self.invalidated_at.to_primitive() if self.invalidated_at is not None else None,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentEmailOTPIdentity:
+    """Coherent current grant subject and Email facts loaded by submission persistence."""
+
+    grant_ref: ApproverGrantRef
+    subject: EmailOTPSubject | None
+    normalized_email: NormalizedEmail | None
+
+
+@dataclass(frozen=True, slots=True)
+class EmailOTPProofAuthorizationDecision:
+    """OTP-specific proof decision consumed by the later Submission authorizer."""
+
+    proof: VerifiedEmailOTPProof | None
+    rejection: OTPChallengeRejectionReason | None
+
+
+class OTPChallengeRepository(Protocol):
+    """Grant-scoped atomic persistence operations for OTP proof sessions."""
+
+    def issue_initial(
+        self,
+        grant_ref: ApproverGrantRef,
+        *,
+        challenge_id: OTPChallengeId,
+        audit_event_id: str,
+        challenge_token_hash: str,
+        plaintext_code: str,
+    ) -> OTPChallenge: ...
+
+    def replace_current(
+        self,
+        grant_ref: ApproverGrantRef,
+        *,
+        challenge_id: OTPChallengeId,
+        audit_event_id: str,
+        challenge_token_hash: str,
+        plaintext_code: str,
+    ) -> OTPReplacementDecision: ...
+
+    def verify(self, challenge_ref: OTPChallengeRef, *, plaintext_code: str) -> OTPVerificationDecision: ...
+
+    def invalidate_current(self, grant_ref: ApproverGrantRef) -> OTPChallenge | None: ...
+
+    def load(self, challenge_ref: OTPChallengeRef) -> OTPChallenge | None: ...
+
+
+def authorize_email_otp_proof(
+    candidate: object,
+    *,
+    current_identity: CurrentEmailOTPIdentity,
+) -> EmailOTPProofAuthorizationDecision:
+    """Reject raw codes and stale identity incarnations without authorizing submission."""
+
+    if not isinstance(candidate, VerifiedEmailOTPProof):
+        return EmailOTPProofAuthorizationDecision(None, OTPChallengeRejectionReason.RAW_CODE_NOT_VERIFIED)
+    if candidate.challenge_ref.grant_ref != current_identity.grant_ref:
+        return EmailOTPProofAuthorizationDecision(None, OTPChallengeRejectionReason.GRANT_MISMATCH)
+    if (
+        current_identity.subject is None
+        or current_identity.normalized_email is None
+        or candidate.subject != current_identity.subject
+        or candidate.normalized_email != current_identity.normalized_email
+    ):
+        return EmailOTPProofAuthorizationDecision(None, OTPChallengeRejectionReason.STALE_IDENTITY)
+    return EmailOTPProofAuthorizationDecision(candidate, None)
@@ -0,0 +1,81 @@
+"""Operation-oriented persistence ports for the Human Input v2 form boundary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from core.human_input_v2.entities import HumanInputV2FormStatus
+from core.human_input_v2.shared import UtcTimestamp, WorkspaceId
+
+from .delivery import DeliveryAttempt, DeliveryEndpoint, UploadCapability, UploadFileAssociation
+from .form import FormCreation, FrozenFormDefinition, HumanInputForm
+from .grants import ApproverGrant, DeliveryEndpointRef, FormRef
+
+
+@dataclass(frozen=True, slots=True)
+class FormDefinitionProjection:
+    """Read model for rendering a form through one endpoint capability."""
+
+    form_ref: FormRef
+    endpoint_ref: DeliveryEndpointRef
+    definition: FrozenFormDefinition
+    rendered_content: str
+    status: HumanInputV2FormStatus
+    node_timeout_at: UtcTimestamp
+    global_expires_at: UtcTimestamp
+
+
+@dataclass(frozen=True, slots=True)
+class FormDeliveryProjection:
+    """Read model containing only data needed to deliver one endpoint."""
+
+    form_ref: FormRef
+    grant: ApproverGrant
+    endpoint: DeliveryEndpoint
+    definition: FrozenFormDefinition
+    rendered_content: str
+
+
+class FormRepository(Protocol):
+    """Deep adapter contract whose operations own their query and transaction shape."""
+
+    def create_form(self, creation: FormCreation) -> HumanInputForm:
+        """Persist form, grants, and endpoints atomically."""
+
+        ...
+
+    def load_for_lifecycle(self, form_ref: FormRef) -> HumanInputForm | None:
+        """Load the form and grants required for local transition decisions."""
+
+        ...
+
+    def load_delivery_projection(self, endpoint_ref: DeliveryEndpointRef) -> FormDeliveryProjection | None:
+        """Load exactly one endpoint with its grant and form delivery values."""
+
+        ...
+
+    def load_definition_by_endpoint_token(
+        self,
+        *,
+        workspace_id: WorkspaceId,
+        token_hash: str,
+    ) -> FormDefinitionProjection | None:
+        """Resolve a scoped interaction capability without creating authority."""
+
+        ...
+
+    def append_delivery_attempt(self, attempt: DeliveryAttempt) -> DeliveryAttempt:
+        """Append one delivery fact without changing form lifecycle status."""
+
+        ...
+
+    def create_upload_capability(self, capability: UploadCapability) -> UploadCapability:
+        """Persist one endpoint-scoped upload capability."""
+
+        ...
+
+    def associate_upload_file(self, association: UploadFileAssociation) -> UploadFileAssociation:
+        """Associate a file only after validating the full capability owner chain."""
+
+        ...
@@ -0,0 +1,775 @@
+"""Canonical approval plan values and single-entry recipient resolution.
+
+``RecipientResolver.resolve`` is the only public operation that converts saved
+recipient specifications into approvers. Validation, Contact upgrade, subject
+deduplication, matched-source aggregation, debug replacement, and endpoint
+planning stay behind that interface so callers cannot apply them inconsistently.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from hashlib import sha256
+from typing import assert_never
+
+from core.human_input_v2.contact_directory import (
+    Contact,
+    ContactDirectoryError,
+    ContactDirectoryPolicy,
+    ContactDirectorySnapshot,
+    ContactResolution,
+)
+from core.human_input_v2.entities import HumanInputApproverGrantSubjectType, HumanInputDeliveryChannel, IMProvider
+from core.human_input_v2.im_integration import EffectiveIMBindingSnapshot
+from core.human_input_v2.shared import (
+    ContactId,
+    EndUserId,
+    IMBindingId,
+    IMIdentityId,
+    IntegrationId,
+    NormalizedEmail,
+)
+
+from .recipient_specifications import (
+    ContactRecipientSpecification,
+    CurrentInitiatorRecipientSpecification,
+    DynamicEmailRecipientSpecification,
+    DynamicRecipientValue,
+    OneTimeEmailRecipientSpecification,
+    RecipientSpecification,
+    UnsupportedDynamicRecipientValue,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CanonicalSubjectKey:
+    """Portable form-scoped deduplication key, not an authorization identity."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        namespace, separator, identity = self.value.partition(":")
+        valid_named_identity = namespace in {"contact", "end_user"} and bool(identity)
+        valid_email_digest = (
+            namespace == "email_address"
+            and len(identity) == 64
+            and all(character in "0123456789abcdef" for character in identity)
+        )
+        if not separator or not (valid_named_identity or valid_email_digest):
+            raise ValueError("canonical subject key has an invalid portable format")
+
+    @classmethod
+    def for_contact(cls, contact_id: ContactId) -> CanonicalSubjectKey:
+        return cls(f"contact:{contact_id}")
+
+    @classmethod
+    def for_end_user(cls, end_user_id: EndUserId) -> CanonicalSubjectKey:
+        return cls(f"end_user:{end_user_id}")
+
+    @classmethod
+    def for_email(cls, normalized_email: NormalizedEmail) -> CanonicalSubjectKey:
+        digest = sha256(normalized_email.value.encode()).hexdigest()
+        return cls(f"email_address:{digest}")
+
+
+@dataclass(frozen=True, slots=True)
+class ContactApprovalSubject:
+    """Approval authority backed by one canonical Contact."""
+
+    contact_id: ContactId
+
+    @property
+    def subject_type(self) -> HumanInputApproverGrantSubjectType:
+        return HumanInputApproverGrantSubjectType.CONTACT
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"type": self.subject_type.value, "contact_id": self.contact_id.to_primitive()}
+
+
+@dataclass(frozen=True, slots=True)
+class EndUserApprovalSubject:
+    """Approval authority backed by one app-scoped EndUser."""
+
+    end_user_id: EndUserId
+
+    @property
+    def subject_type(self) -> HumanInputApproverGrantSubjectType:
+        return HumanInputApproverGrantSubjectType.END_USER
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"type": self.subject_type.value, "end_user_id": self.end_user_id.to_primitive()}
+
+
+@dataclass(frozen=True, slots=True)
+class EmailAddressApprovalSubject:
+    """Task-scoped approval authority backed by one normalized Email address."""
+
+    normalized_email: NormalizedEmail
+
+    @property
+    def subject_type(self) -> HumanInputApproverGrantSubjectType:
+        return HumanInputApproverGrantSubjectType.EMAIL_ADDRESS
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"type": self.subject_type.value, "normalized_email": self.normalized_email.to_primitive()}
+
+
+type ApprovalSubject = ContactApprovalSubject | EndUserApprovalSubject | EmailAddressApprovalSubject
+
+
+class RecipientSourceKind(StrEnum):
+    """Stable source discriminator retained after canonicalization."""
+
+    STATIC_CONTACT = "static_contact"
+    ONE_TIME_EMAIL = "one_time_email"
+    DYNAMIC_EMAIL = "dynamic_email"
+    CURRENT_INITIATOR = "current_initiator"
+    DEBUG_REPLACEMENT = "debug_replacement"
+
+
+@dataclass(frozen=True, slots=True)
+class MatchedRecipientSource:
+    """One ordered configured or request-scoped source of an approver."""
+
+    kind: RecipientSourceKind
+    position: int
+    reference: str | None
+
+    def __post_init__(self) -> None:
+        if self.position < 0:
+            raise ValueError("recipient source position must not be negative")
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"kind": self.kind.value, "position": self.position, "reference": self.reference}
+
+
+@dataclass(frozen=True, slots=True)
+class SubjectSnapshot:
+    """Display-only identity facts captured by resolution."""
+
+    display_name: str | None
+    email: str | None
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"display_name": self.display_name, "email": self.email}
+
+
+@dataclass(frozen=True, slots=True)
+class EmailEndpointPlan:
+    """Email delivery destination for one canonical approver."""
+
+    email_address: NormalizedEmail
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.EMAIL
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"channel": self.channel.value, "email_address": self.email_address.to_primitive()}
+
+
+@dataclass(frozen=True, slots=True)
+class IMEndpointPlan:
+    """Credential-free IM delivery destination frozen from an effective binding."""
+
+    integration_id: IntegrationId
+    provider: IMProvider
+    provider_tenant_id: str
+    identity_id: IMIdentityId
+    binding_id: IMBindingId | None
+    provider_user_id: str
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.IM
+
+    def to_primitive(self) -> dict[str, object]:
+        return {
+            "channel": self.channel.value,
+            "integration_id": self.integration_id.to_primitive(),
+            "provider": self.provider.value,
+            "provider_tenant_id": self.provider_tenant_id,
+            "identity_id": self.identity_id.to_primitive(),
+            "binding_id": self.binding_id.to_primitive() if self.binding_id is not None else None,
+            "provider_user_id": self.provider_user_id,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class WebEndpointPlan:
+    """Public or trusted-app web interaction surface without a saved token."""
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.WEB
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"channel": self.channel.value}
+
+
+@dataclass(frozen=True, slots=True)
+class ConsoleEndpointPlan:
+    """Authenticated console interaction surface without a notification address."""
+
+    @property
+    def channel(self) -> HumanInputDeliveryChannel:
+        return HumanInputDeliveryChannel.CONSOLE
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"channel": self.channel.value}
+
+
+type DeliveryEndpointPlan = EmailEndpointPlan | IMEndpointPlan | WebEndpointPlan | ConsoleEndpointPlan
+
+
+class RecipientRejectionReason(StrEnum):
+    """Transport-neutral reason for rejecting one recipient source."""
+
+    INVALID_CONTACT_ID = "invalid_contact_id"
+    CONTACT_UNAVAILABLE = "contact_unavailable"
+    INVALID_DYNAMIC_SELECTOR = "invalid_dynamic_selector"
+    DYNAMIC_VALUE_UNAVAILABLE = "dynamic_value_unavailable"
+    UNSUPPORTED_DYNAMIC_TYPE = "unsupported_dynamic_type"
+    INVALID_EMAIL = "invalid_email"
+    INITIATOR_UNAVAILABLE = "initiator_unavailable"
+    NO_USABLE_ENDPOINT = "no_usable_endpoint"
+
+
+@dataclass(frozen=True, slots=True)
+class RejectedRecipient:
+    """Machine-readable source failure retained alongside valid approvers."""
+
+    source: MatchedRecipientSource
+    reason: RecipientRejectionReason
+    rejected_value: str | None
+
+    def to_primitive(self) -> dict[str, object]:
+        return {
+            "source": self.source.to_primitive(),
+            "reason": self.reason.value,
+            "rejected_value": self.rejected_value,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedApprover:
+    """One canonical subject with all matched sources and usable endpoints."""
+
+    subject: ApprovalSubject
+    subject_key: CanonicalSubjectKey
+    matched_sources: tuple[MatchedRecipientSource, ...]
+    subject_snapshot: SubjectSnapshot
+    endpoints: tuple[DeliveryEndpointPlan, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.matched_sources, tuple) or not isinstance(self.endpoints, tuple):
+            raise TypeError("resolved approver collections must be immutable tuples")
+        if self.subject_key != _canonical_key_for_subject(self.subject):
+            raise ValueError("resolved approver subject key does not match its subject")
+
+    def to_primitive(self) -> dict[str, object]:
+        return {
+            "subject": self.subject.to_primitive(),
+            "subject_key": self.subject_key.value,
+            "matched_sources": [source.to_primitive() for source in self.matched_sources],
+            "subject_snapshot": self.subject_snapshot.to_primitive(),
+            "endpoints": [endpoint.to_primitive() for endpoint in self.endpoints],
+        }
+
+
+class RecipientResolutionFailureReason(StrEnum):
+    """Stable whole-plan failure independent from HTTP or provider semantics."""
+
+    NO_VALID_RECIPIENTS = "no_valid_recipients"
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedApprovalPlan:
+    """Immutable complete output of one recipient resolution request."""
+
+    approvers: tuple[ResolvedApprover, ...]
+    rejected_recipients: tuple[RejectedRecipient, ...]
+    failure_reason: RecipientResolutionFailureReason | None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.approvers, tuple) or not isinstance(self.rejected_recipients, tuple):
+            raise TypeError("approval plan collections must be immutable tuples")
+        if self.approvers and self.failure_reason is not None:
+            raise ValueError("a plan with approvers cannot have a failure reason")
+        if not self.approvers and self.failure_reason is None:
+            raise ValueError("a plan without approvers must have a failure reason")
+
+    def to_primitive(self) -> dict[str, object]:
+        return {
+            "approvers": [approver.to_primitive() for approver in self.approvers],
+            "rejected_recipients": [rejection.to_primitive() for rejection in self.rejected_recipients],
+            "failure_reason": self.failure_reason.value if self.failure_reason is not None else None,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ContactInitiatorSnapshot:
+    """Current request initiator resolved to a canonical Contact reference."""
+
+    contact_id: ContactId
+
+
+@dataclass(frozen=True, slots=True)
+class EndUserInitiatorSnapshot:
+    """Current request initiator resolved to one app-scoped EndUser."""
+
+    end_user_id: EndUserId
+    display_name: str | None
+    email: str | None
+
+
+type InitiatorSnapshot = ContactInitiatorSnapshot | EndUserInitiatorSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class DebugRecipientReplacement:
+    """Valid debug actor that replaces saved recipients for one request only."""
+
+    subject: InitiatorSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryCapabilitySnapshot:
+    """Request-scoped effective delivery and interaction capabilities.
+
+    IM values are already resolved by the IM control plane; this domain never
+    sees credentials, raw provider clients, or invalid binding candidates.
+    Explicit Web/Console sets prevent recipient resolution from inventing
+    interaction surfaces that the current runtime cannot actually expose.
+    """
+
+    im_bindings: tuple[EffectiveIMBindingSnapshot, ...] = ()
+    contact_web_ids: frozenset[ContactId] = frozenset()
+    contact_console_ids: frozenset[ContactId] = frozenset()
+    end_user_web_ids: frozenset[EndUserId] = frozenset()
+    email_address_web_available: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.im_bindings, tuple):
+            raise TypeError("effective IM bindings must be an immutable tuple")
+        if not all(
+            isinstance(values, frozenset)
+            for values in (self.contact_web_ids, self.contact_console_ids, self.end_user_web_ids)
+        ):
+            raise TypeError("interaction capability identifiers must be immutable frozensets")
+
+
+@dataclass(slots=True)
+class _PendingApprover:
+    """Private mutable accumulator hidden behind the immutable resolver result."""
+
+    subject: ApprovalSubject
+    subject_key: CanonicalSubjectKey
+    subject_snapshot: SubjectSnapshot
+    first_source_position: int
+    matched_sources: list[MatchedRecipientSource] = field(default_factory=list)
+    endpoints: list[DeliveryEndpointPlan] = field(default_factory=list)
+
+
+class RecipientResolver:
+    """Resolve all recipient semantics through one deterministic domain entry."""
+
+    @staticmethod
+    def resolve(
+        *,
+        specifications: tuple[RecipientSpecification, ...],
+        directory: ContactDirectorySnapshot,
+        dynamic_values: tuple[DynamicRecipientValue, ...],
+        initiator: InitiatorSnapshot | None,
+        capabilities: DeliveryCapabilitySnapshot,
+        debug_replacement: DebugRecipientReplacement | None = None,
+    ) -> ResolvedApprovalPlan:
+        """Resolve immutable request inputs into one complete approval plan.
+
+        Invalid or unavailable sources are returned as typed rejection facts;
+        the method raises only when a caller violates an immutable input shape.
+        No database, provider, transport, or mutation side effects occur.
+        """
+        if not isinstance(specifications, tuple) or not isinstance(dynamic_values, tuple):
+            raise TypeError("recipient resolution inputs must be immutable tuples")
+
+        pending_approvers: dict[CanonicalSubjectKey, _PendingApprover] = {}
+        rejected_recipients: list[RejectedRecipient] = []
+        dynamic_values_by_selector: dict[tuple[str, ...], DynamicRecipientValue] = {}
+        for dynamic_value in dynamic_values:
+            dynamic_values_by_selector.setdefault(dynamic_value.selector, dynamic_value)
+
+        if debug_replacement is not None:
+            source = MatchedRecipientSource(RecipientSourceKind.DEBUG_REPLACEMENT, 0, None)
+            RecipientResolver._resolve_initiator(
+                debug_replacement.subject,
+                source,
+                directory,
+                capabilities,
+                pending_approvers,
+                rejected_recipients,
+            )
+        else:
+            for position, specification in enumerate(specifications):
+                RecipientResolver._resolve_specification(
+                    specification,
+                    position,
+                    directory,
+                    dynamic_values_by_selector,
+                    initiator,
+                    capabilities,
+                    pending_approvers,
+                    rejected_recipients,
+                )
+
+        approvers: list[ResolvedApprover] = []
+        for pending in sorted(
+            pending_approvers.values(),
+            key=lambda candidate: (candidate.first_source_position, candidate.subject_key.value),
+        ):
+            matched_sources = tuple(sorted(pending.matched_sources, key=_source_sort_key))
+            endpoints = tuple(sorted(pending.endpoints, key=_endpoint_sort_key))
+            if not endpoints:
+                rejected_recipients.extend(
+                    RejectedRecipient(
+                        source=source,
+                        reason=RecipientRejectionReason.NO_USABLE_ENDPOINT,
+                        rejected_value=pending.subject_key.value,
+                    )
+                    for source in matched_sources
+                )
+                continue
+            approvers.append(
+                ResolvedApprover(
+                    subject=pending.subject,
+                    subject_key=pending.subject_key,
+                    matched_sources=matched_sources,
+                    subject_snapshot=pending.subject_snapshot,
+                    endpoints=endpoints,
+                )
+            )
+
+        ordered_rejections = tuple(sorted(rejected_recipients, key=_rejection_sort_key))
+        failure_reason = None if approvers else RecipientResolutionFailureReason.NO_VALID_RECIPIENTS
+        return ResolvedApprovalPlan(tuple(approvers), ordered_rejections, failure_reason)
+
+    @staticmethod
+    def _resolve_specification(
+        specification: RecipientSpecification,
+        position: int,
+        directory: ContactDirectorySnapshot,
+        dynamic_values_by_selector: dict[tuple[str, ...], DynamicRecipientValue],
+        initiator: InitiatorSnapshot | None,
+        capabilities: DeliveryCapabilitySnapshot,
+        pending_approvers: dict[CanonicalSubjectKey, _PendingApprover],
+        rejected_recipients: list[RejectedRecipient],
+    ) -> None:
+        if isinstance(specification, ContactRecipientSpecification):
+            source = MatchedRecipientSource(
+                RecipientSourceKind.STATIC_CONTACT,
+                position,
+                specification.contact_id,
+            )
+            try:
+                contact_id = ContactId(specification.contact_id)
+            except ValueError:
+                rejected_recipients.append(
+                    RejectedRecipient(source, RecipientRejectionReason.INVALID_CONTACT_ID, specification.contact_id)
+                )
+                return
+            RecipientResolver._resolve_contact(
+                contact_id,
+                source,
+                directory,
+                capabilities,
+                pending_approvers,
+                rejected_recipients,
+            )
+            return
+
+        if isinstance(specification, OneTimeEmailRecipientSpecification):
+            source = MatchedRecipientSource(
+                RecipientSourceKind.ONE_TIME_EMAIL,
+                position,
+                specification.email,
+            )
+            RecipientResolver._resolve_email(
+                specification.email,
+                source,
+                directory,
+                capabilities,
+                pending_approvers,
+                rejected_recipients,
+            )
+            return
+
+        if isinstance(specification, DynamicEmailRecipientSpecification):
+            selector_reference = ".".join(specification.selector)
+            source = MatchedRecipientSource(
+                RecipientSourceKind.DYNAMIC_EMAIL,
+                position,
+                selector_reference,
+            )
+            if not specification.selector or any(not component.strip() for component in specification.selector):
+                rejected_recipients.append(
+                    RejectedRecipient(source, RecipientRejectionReason.INVALID_DYNAMIC_SELECTOR, selector_reference)
+                )
+                return
+            dynamic_value = dynamic_values_by_selector.get(specification.selector)
+            if dynamic_value is None:
+                rejected_recipients.append(
+                    RejectedRecipient(source, RecipientRejectionReason.DYNAMIC_VALUE_UNAVAILABLE, selector_reference)
+                )
+                return
+            if isinstance(dynamic_value.value, UnsupportedDynamicRecipientValue):
+                rejected_recipients.append(
+                    RejectedRecipient(
+                        source,
+                        RecipientRejectionReason.UNSUPPORTED_DYNAMIC_TYPE,
+                        dynamic_value.value.value_type,
+                    )
+                )
+                return
+            RecipientResolver._resolve_email(
+                dynamic_value.value,
+                source,
+                directory,
+                capabilities,
+                pending_approvers,
+                rejected_recipients,
+            )
+            return
+
+        if isinstance(specification, CurrentInitiatorRecipientSpecification):
+            source = MatchedRecipientSource(RecipientSourceKind.CURRENT_INITIATOR, position, None)
+            if initiator is None:
+                rejected_recipients.append(
+                    RejectedRecipient(source, RecipientRejectionReason.INITIATOR_UNAVAILABLE, None)
+                )
+                return
+            RecipientResolver._resolve_initiator(
+                initiator,
+                source,
+                directory,
+                capabilities,
+                pending_approvers,
+                rejected_recipients,
+            )
+            return
+
+        assert_never(specification)
+
+    @staticmethod
+    def _resolve_initiator(
+        initiator: InitiatorSnapshot,
+        source: MatchedRecipientSource,
+        directory: ContactDirectorySnapshot,
+        capabilities: DeliveryCapabilitySnapshot,
+        pending_approvers: dict[CanonicalSubjectKey, _PendingApprover],
+        rejected_recipients: list[RejectedRecipient],
+    ) -> None:
+        if isinstance(initiator, ContactInitiatorSnapshot):
+            RecipientResolver._resolve_contact(
+                initiator.contact_id,
+                source,
+                directory,
+                capabilities,
+                pending_approvers,
+                rejected_recipients,
+            )
+            return
+
+        normalized_email: NormalizedEmail | None = None
+        if initiator.email is not None:
+            try:
+                normalized_email = NormalizedEmail(initiator.email)
+            except ValueError:
+                normalized_email = None
+        subject = EndUserApprovalSubject(initiator.end_user_id)
+        endpoints: list[DeliveryEndpointPlan] = []
+        if normalized_email is not None:
+            endpoints.append(EmailEndpointPlan(normalized_email))
+        if initiator.end_user_id in capabilities.end_user_web_ids:
+            endpoints.append(WebEndpointPlan())
+        RecipientResolver._add_approver(
+            subject,
+            source,
+            SubjectSnapshot(initiator.display_name, normalized_email.value if normalized_email is not None else None),
+            endpoints,
+            pending_approvers,
+        )
+
+    @staticmethod
+    def _resolve_contact(
+        contact_id: ContactId,
+        source: MatchedRecipientSource,
+        directory: ContactDirectorySnapshot,
+        capabilities: DeliveryCapabilitySnapshot,
+        pending_approvers: dict[CanonicalSubjectKey, _PendingApprover],
+        rejected_recipients: list[RejectedRecipient],
+    ) -> None:
+        try:
+            resolution = ContactDirectoryPolicy.resolve_for_workspace(directory, contact_id)
+        except ContactDirectoryError:
+            resolution = ContactResolution.ABSENT
+        contact = directory.find(contact_id)
+        if resolution is ContactResolution.ABSENT or contact is None:
+            rejected_recipients.append(
+                RejectedRecipient(source, RecipientRejectionReason.CONTACT_UNAVAILABLE, contact_id.value)
+            )
+            return
+        RecipientResolver._add_contact_approver(contact, source, capabilities, pending_approvers)
+
+    @staticmethod
+    def _resolve_email(
+        email: str,
+        source: MatchedRecipientSource,
+        directory: ContactDirectorySnapshot,
+        capabilities: DeliveryCapabilitySnapshot,
+        pending_approvers: dict[CanonicalSubjectKey, _PendingApprover],
+        rejected_recipients: list[RejectedRecipient],
+    ) -> None:
+        """Resolve Email input without bypassing an existing Contact's policy.
+
+        EmailAddress authority is valid only when the directory contains no
+        matching Contact. A matching but unavailable Contact fails closed so
+        callers cannot bypass Account availability or workspace visibility.
+        """
+        try:
+            normalized_email = NormalizedEmail(email)
+        except ValueError:
+            rejected_recipients.append(RejectedRecipient(source, RecipientRejectionReason.INVALID_EMAIL, email))
+            return
+
+        matching_contacts = sorted(
+            (contact for contact in directory.contacts if contact.normalized_email == normalized_email),
+            key=lambda contact: contact.id.value,
+        )
+        for contact in matching_contacts:
+            try:
+                resolution = ContactDirectoryPolicy.resolve_for_workspace(directory, contact.id)
+            except ContactDirectoryError:
+                continue
+            if resolution is not ContactResolution.ABSENT:
+                RecipientResolver._add_contact_approver(contact, source, capabilities, pending_approvers)
+                return
+
+        if matching_contacts:
+            rejected_recipients.append(
+                RejectedRecipient(
+                    source,
+                    RecipientRejectionReason.CONTACT_UNAVAILABLE,
+                    normalized_email.value,
+                )
+            )
+            return
+
+        subject = EmailAddressApprovalSubject(normalized_email)
+        endpoints: list[DeliveryEndpointPlan] = [EmailEndpointPlan(normalized_email)]
+        if capabilities.email_address_web_available:
+            endpoints.append(WebEndpointPlan())
+        RecipientResolver._add_approver(
+            subject,
+            source,
+            SubjectSnapshot(None, normalized_email.value),
+            endpoints,
+            pending_approvers,
+        )
+
+    @staticmethod
+    def _add_contact_approver(
+        contact: Contact,
+        source: MatchedRecipientSource,
+        capabilities: DeliveryCapabilitySnapshot,
+        pending_approvers: dict[CanonicalSubjectKey, _PendingApprover],
+    ) -> None:
+        endpoints: list[DeliveryEndpointPlan] = []
+        if contact.normalized_email is not None:
+            endpoints.append(EmailEndpointPlan(contact.normalized_email))
+        endpoints.extend(
+            IMEndpointPlan(
+                integration_id=binding.integration_id,
+                provider=binding.provider,
+                provider_tenant_id=binding.provider_tenant_id,
+                identity_id=binding.identity_id,
+                binding_id=binding.binding_id,
+                provider_user_id=binding.provider_user_id,
+            )
+            for binding in capabilities.im_bindings
+            if binding.contact_id == contact.id
+        )
+        if contact.id in capabilities.contact_web_ids:
+            endpoints.append(WebEndpointPlan())
+        if contact.id in capabilities.contact_console_ids:
+            endpoints.append(ConsoleEndpointPlan())
+        RecipientResolver._add_approver(
+            ContactApprovalSubject(contact.id),
+            source,
+            SubjectSnapshot(contact.name, contact.email),
+            endpoints,
+            pending_approvers,
+        )
+
+    @staticmethod
+    def _add_approver(
+        subject: ApprovalSubject,
+        source: MatchedRecipientSource,
+        subject_snapshot: SubjectSnapshot,
+        endpoints: list[DeliveryEndpointPlan],
+        pending_approvers: dict[CanonicalSubjectKey, _PendingApprover],
+    ) -> None:
+        subject_key = _canonical_key_for_subject(subject)
+        pending = pending_approvers.get(subject_key)
+        if pending is None:
+            pending = _PendingApprover(
+                subject=subject,
+                subject_key=subject_key,
+                subject_snapshot=subject_snapshot,
+                first_source_position=source.position,
+            )
+            pending_approvers[subject_key] = pending
+        if source not in pending.matched_sources:
+            pending.matched_sources.append(source)
+        for endpoint in endpoints:
+            if endpoint not in pending.endpoints:
+                pending.endpoints.append(endpoint)
+
+
+def _canonical_key_for_subject(subject: ApprovalSubject) -> CanonicalSubjectKey:
+    if isinstance(subject, ContactApprovalSubject):
+        return CanonicalSubjectKey.for_contact(subject.contact_id)
+    if isinstance(subject, EndUserApprovalSubject):
+        return CanonicalSubjectKey.for_end_user(subject.end_user_id)
+    return CanonicalSubjectKey.for_email(subject.normalized_email)
+
+
+_CHANNEL_ORDER = {
+    HumanInputDeliveryChannel.EMAIL: 0,
+    HumanInputDeliveryChannel.IM: 1,
+    HumanInputDeliveryChannel.WEB: 2,
+    HumanInputDeliveryChannel.CONSOLE: 3,
+}
+
+
+def _source_sort_key(source: MatchedRecipientSource) -> tuple[int, str, str]:
+    return source.position, source.kind.value, source.reference or ""
+
+
+def _endpoint_sort_key(endpoint: DeliveryEndpointPlan) -> tuple[int, str, str, str]:
+    channel_order = _CHANNEL_ORDER[endpoint.channel]
+    if isinstance(endpoint, EmailEndpointPlan):
+        return channel_order, endpoint.email_address.value, "", ""
+    if isinstance(endpoint, IMEndpointPlan):
+        return (
+            channel_order,
+            endpoint.integration_id.value,
+            endpoint.provider.value,
+            endpoint.identity_id.value,
+        )
+    return channel_order, "", "", ""
+
+
+def _rejection_sort_key(rejection: RejectedRecipient) -> tuple[int, str, str, str]:
+    source_key = _source_sort_key(rejection.source)
+    return source_key[0], source_key[1], rejection.reason.value, rejection.rejected_value or ""
@@ -0,0 +1,145 @@
+"""Immutable recipient specifications at the workflow-to-approval boundary.
+
+Saved node configuration intentionally retains unvalidated Email text. Runtime
+validation belongs to :class:`RecipientResolver`, which can retain a typed
+rejection without making workflow configuration parsing fail early.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import assert_never
+
+from core.workflow.nodes.human_input_v2.entities import (
+    Contact as WorkflowContactRecipient,
+)
+from core.workflow.nodes.human_input_v2.entities import (
+    DynamicEmail as WorkflowDynamicEmailRecipient,
+)
+from core.workflow.nodes.human_input_v2.entities import (
+    HumanInputNodeData,
+)
+from core.workflow.nodes.human_input_v2.entities import (
+    Initiator as WorkflowInitiatorRecipient,
+)
+from core.workflow.nodes.human_input_v2.entities import (
+    OnetimeEmail as WorkflowOneTimeEmailRecipient,
+)
+
+
+class RecipientSpecificationKind(StrEnum):
+    """Stable workflow recipient discriminator."""
+
+    CONTACT = "contact"
+    DYNAMIC_EMAIL = "dynamic_email"
+    ONETIME_EMAIL = "onetime_email"
+    INITIATOR = "initiator"
+
+
+@dataclass(frozen=True, slots=True)
+class ContactRecipientSpecification:
+    """Saved reference to one Contact; current availability is resolved later."""
+
+    contact_id: str
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"type": RecipientSpecificationKind.CONTACT.value, "contact_id": self.contact_id}
+
+
+@dataclass(frozen=True, slots=True)
+class OneTimeEmailRecipientSpecification:
+    """Saved one-time Email text whose validity is decided per resolution."""
+
+    email: str
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"type": RecipientSpecificationKind.ONETIME_EMAIL.value, "email": self.email}
+
+
+@dataclass(frozen=True, slots=True)
+class DynamicEmailRecipientSpecification:
+    """Saved workflow selector whose current value is supplied separately."""
+
+    selector: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.selector, tuple):
+            raise TypeError("dynamic email selector must be an immutable tuple")
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"type": RecipientSpecificationKind.DYNAMIC_EMAIL.value, "selector": list(self.selector)}
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentInitiatorRecipientSpecification:
+    """Request-scoped current initiator recipient marker."""
+
+    def to_primitive(self) -> dict[str, object]:
+        return {"type": RecipientSpecificationKind.INITIATOR.value}
+
+
+type RecipientSpecification = (
+    ContactRecipientSpecification
+    | OneTimeEmailRecipientSpecification
+    | DynamicEmailRecipientSpecification
+    | CurrentInitiatorRecipientSpecification
+)
+
+
+@dataclass(frozen=True, slots=True)
+class UnsupportedDynamicRecipientValue:
+    """Safe snapshot of a non-string workflow value without retaining its graph."""
+
+    value_type: str
+
+    def __post_init__(self) -> None:
+        if not self.value_type:
+            raise ValueError("unsupported dynamic recipient value type must not be blank")
+
+
+@dataclass(frozen=True, slots=True)
+class DynamicRecipientValue:
+    """One evaluated selector value captured for a single resolution request."""
+
+    selector: tuple[str, ...]
+    value: str | UnsupportedDynamicRecipientValue
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.selector, tuple):
+            raise TypeError("dynamic recipient value selector must be an immutable tuple")
+
+    @classmethod
+    def from_runtime(cls, selector: tuple[str, ...], value: object) -> DynamicRecipientValue:
+        """Capture a runtime value without retaining mutable unsupported data."""
+
+        captured_value: str | UnsupportedDynamicRecipientValue
+        if isinstance(value, str):
+            captured_value = value
+        else:
+            captured_value = UnsupportedDynamicRecipientValue(type(value).__name__)
+        return cls(selector=selector, value=captured_value)
+
+
+class WorkflowRecipientSpecificationAdapter:
+    """Convert versioned workflow node values into approval-domain inputs."""
+
+    @staticmethod
+    def from_node_data(node_data: HumanInputNodeData) -> tuple[RecipientSpecification, ...]:
+        """Copy ordered v2 node recipients into immutable domain values."""
+
+        specifications: list[RecipientSpecification] = []
+        for configured_recipient in node_data.recipients_spec:
+            specification: RecipientSpecification
+            if isinstance(configured_recipient, WorkflowContactRecipient):
+                specification = ContactRecipientSpecification(contact_id=configured_recipient.contact_id)
+            elif isinstance(configured_recipient, WorkflowOneTimeEmailRecipient):
+                specification = OneTimeEmailRecipientSpecification(email=configured_recipient.email)
+            elif isinstance(configured_recipient, WorkflowDynamicEmailRecipient):
+                specification = DynamicEmailRecipientSpecification(selector=tuple(configured_recipient.selector))
+            elif isinstance(configured_recipient, WorkflowInitiatorRecipient):
+                specification = CurrentInitiatorRecipientSpecification()
+            else:
+                assert_never(configured_recipient)
+            specifications.append(specification)
+        return tuple(specifications)
@@ -0,0 +1,405 @@
+"""Pure current-state authorization for Human Input v2 submissions.
+
+The module owns the cross-snapshot decision only. Callers must verify transport
+credentials before constructing a proof and must load one coherent
+``AuthorizationContext`` through persistence. The authorizer performs no I/O,
+does not retain raw credentials, and never reloads Contact or IM binding facts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import assert_never
+
+from core.human_input_v2.entities import IMProvider
+from core.human_input_v2.shared import (
+    AccountId,
+    AppId,
+    ContactId,
+    EndUserId,
+    IMBindingId,
+    IMIdentityId,
+    IntegrationId,
+    NormalizedEmail,
+    UtcTimestamp,
+)
+
+from .delivery import DeliveryEndpoint
+from .form import (
+    FormInactiveReason,
+    HumanInputForm,
+    InactiveFormState,
+    InvalidApproverGrantError,
+    InvalidSelectedActionError,
+    SubmissionTransitionDecision,
+)
+from .grants import ApproverGrant, DeliveryEndpointRef
+from .otp import ContactOTPSubject, EmailAddressOTPSubject, VerifiedEmailOTPProof
+from .recipient_resolution import ContactApprovalSubject, EmailAddressApprovalSubject, EndUserApprovalSubject
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedAccountSessionProof:
+    """Current Account identity produced by a trusted session verifier."""
+
+    account_id: AccountId
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedTrustedEndUserProof:
+    """Current EndUser identity produced by a trusted app-token boundary."""
+
+    end_user_id: EndUserId
+    app_id: AppId
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedIMIdentityProof:
+    """Current provider identity evidence without callback credentials or payloads."""
+
+    integration_id: IntegrationId
+    identity_id: IMIdentityId
+    binding_id: IMBindingId | None
+    provider: IMProvider
+    provider_tenant_id: str
+    provider_user_id: str
+
+    def __post_init__(self) -> None:
+        if not self.provider_tenant_id.strip() or not self.provider_user_id.strip():
+            raise ValueError("verified IM provider identities must not be blank")
+
+
+type VerifiedSubmissionProof = (
+    VerifiedAccountSessionProof | VerifiedTrustedEndUserProof | VerifiedEmailOTPProof | VerifiedIMIdentityProof
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AccountSubmissionActor:
+    """Current Dify Account that completed a submission."""
+
+    account_id: AccountId
+
+
+@dataclass(frozen=True, slots=True)
+class EndUserSubmissionActor:
+    """Current app-scoped EndUser that completed a submission."""
+
+    end_user_id: EndUserId
+
+
+@dataclass(frozen=True, slots=True)
+class EmailAddressSubmissionActor:
+    """Verified normalized Email identity that completed a submission."""
+
+    normalized_email: NormalizedEmail
+
+
+type SubmissionActor = AccountSubmissionActor | EndUserSubmissionActor | EmailAddressSubmissionActor
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentContactAuthorizationFacts:
+    """Current Contact incarnation, Email, Account, and workspace availability."""
+
+    contact_id: ContactId
+    account_id: AccountId | None
+    normalized_email: NormalizedEmail | None
+    account_active: bool
+    workspace_available: bool
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentEndUserAuthorizationFacts:
+    """Current tenant/app ownership facts for one EndUser identity."""
+
+    end_user_id: EndUserId
+    app_id: AppId
+    workspace_available: bool
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentIMAuthorizationFacts:
+    """Credential-free effective IM binding observed in the authorization snapshot."""
+
+    integration_id: IntegrationId
+    provider: IMProvider
+    provider_tenant_id: str
+    contact_id: ContactId
+    account_id: AccountId | None
+    identity_id: IMIdentityId
+    binding_id: IMBindingId | None
+    provider_user_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizationContext:
+    """One immutable tenant-scoped view used without later identity reloads."""
+
+    form: HumanInputForm
+    grant: ApproverGrant
+    endpoint: DeliveryEndpoint | None
+    current_contact: CurrentContactAuthorizationFacts | None
+    current_end_user: CurrentEndUserAuthorizationFacts | None
+    current_im_binding: CurrentIMAuthorizationFacts | None
+
+    def __post_init__(self) -> None:
+        if self.grant.ref.form_ref != self.form.ref or self.grant not in self.form.grants:
+            raise ValueError("authorization grant does not belong to the form snapshot")
+        if self.endpoint is not None and self.endpoint.grant_ref != self.grant.ref:
+            raise ValueError("authorization endpoint does not belong to the target grant")
+
+
+class SubmissionAuthorizationRejection(StrEnum):
+    """Stable transport-neutral reasons for denied submission authority."""
+
+    RAW_CREDENTIAL_NOT_VERIFIED = "raw_credential_not_verified"
+    FORM_ALREADY_SUBMITTED = "form_already_submitted"
+    FORM_TIMED_OUT = "form_timed_out"
+    FORM_STATUS_EXPIRED = "form_status_expired"
+    FORM_GLOBALLY_EXPIRED = "form_globally_expired"
+    GRANT_NOT_MATCHED = "grant_not_matched"
+    INVALID_SELECTED_ACTION = "invalid_selected_action"
+    STALE_IDENTITY = "stale_identity"
+    ACCOUNT_DISABLED = "account_disabled"
+    WORKSPACE_UNAVAILABLE = "workspace_unavailable"
+    END_USER_UNAVAILABLE = "end_user_unavailable"
+    IM_BINDING_CHANGED = "im_binding_changed"
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizedSubmission:
+    """Current authority and local form transition prepared for atomic persistence."""
+
+    transition: SubmissionTransitionDecision
+    proof: VerifiedSubmissionProof
+    actor: SubmissionActor
+    endpoint_ref: DeliveryEndpointRef | None
+
+
+@dataclass(frozen=True, slots=True)
+class SubmissionAuthorizationDecision:
+    """Exactly one authorized value or stable rejection."""
+
+    authorized: AuthorizedSubmission | None
+    rejection: SubmissionAuthorizationRejection | None
+
+    def __post_init__(self) -> None:
+        if (self.authorized is None) == (self.rejection is None):
+            raise ValueError("authorization decision requires exactly one outcome")
+
+    @classmethod
+    def accept(cls, authorized: AuthorizedSubmission) -> SubmissionAuthorizationDecision:
+        return cls(authorized, None)
+
+    @classmethod
+    def reject(cls, reason: SubmissionAuthorizationRejection) -> SubmissionAuthorizationDecision:
+        return cls(None, reason)
+
+
+class SubmissionAuthorizer:
+    """Stateless cross-snapshot policy that resolves one current business actor."""
+
+    @classmethod
+    def authorize(
+        cls,
+        *,
+        context: AuthorizationContext,
+        proof: object,
+        selected_action_id: str,
+        now: UtcTimestamp,
+    ) -> SubmissionAuthorizationDecision:
+        """Authorize verified proof against one already-loaded coherent context."""
+
+        if not isinstance(
+            proof,
+            VerifiedAccountSessionProof | VerifiedTrustedEndUserProof | VerifiedEmailOTPProof | VerifiedIMIdentityProof,
+        ):
+            return SubmissionAuthorizationDecision.reject(SubmissionAuthorizationRejection.RAW_CREDENTIAL_NOT_VERIFIED)
+
+        state = context.form.state_at(now)
+        if isinstance(state, InactiveFormState):
+            return SubmissionAuthorizationDecision.reject(cls._inactive_rejection(state.reason))
+        try:
+            transition = context.form.decide_submission(
+                grant_id=context.grant.id,
+                selected_action_id=selected_action_id,
+                now=now,
+            )
+        except InvalidApproverGrantError:
+            return SubmissionAuthorizationDecision.reject(SubmissionAuthorizationRejection.GRANT_NOT_MATCHED)
+        except InvalidSelectedActionError:
+            return SubmissionAuthorizationDecision.reject(SubmissionAuthorizationRejection.INVALID_SELECTED_ACTION)
+        if isinstance(transition, InactiveFormState):
+            return SubmissionAuthorizationDecision.reject(cls._inactive_rejection(transition.reason))
+
+        actor_or_rejection = cls._resolve_actor(context, proof)
+        if isinstance(actor_or_rejection, SubmissionAuthorizationRejection):
+            return SubmissionAuthorizationDecision.reject(actor_or_rejection)
+        return SubmissionAuthorizationDecision.accept(
+            AuthorizedSubmission(
+                transition=transition,
+                proof=proof,
+                actor=actor_or_rejection,
+                endpoint_ref=context.endpoint.ref if context.endpoint is not None else None,
+            )
+        )
+
+    @staticmethod
+    def _inactive_rejection(reason: FormInactiveReason) -> SubmissionAuthorizationRejection:
+        match reason:
+            case FormInactiveReason.SUBMITTED:
+                return SubmissionAuthorizationRejection.FORM_ALREADY_SUBMITTED
+            case FormInactiveReason.TIMED_OUT:
+                return SubmissionAuthorizationRejection.FORM_TIMED_OUT
+            case FormInactiveReason.STATUS_EXPIRED:
+                return SubmissionAuthorizationRejection.FORM_STATUS_EXPIRED
+            case FormInactiveReason.GLOBALLY_EXPIRED:
+                return SubmissionAuthorizationRejection.FORM_GLOBALLY_EXPIRED
+        assert_never(reason)
+
+    @classmethod
+    def _resolve_actor(
+        cls,
+        context: AuthorizationContext,
+        proof: VerifiedSubmissionProof,
+    ) -> SubmissionActor | SubmissionAuthorizationRejection:
+        match proof:
+            case VerifiedAccountSessionProof():
+                return cls._authorize_account(context, proof)
+            case VerifiedTrustedEndUserProof():
+                return cls._authorize_end_user(context, proof)
+            case VerifiedEmailOTPProof():
+                return cls._authorize_email(context, proof)
+            case VerifiedIMIdentityProof():
+                return cls._authorize_im(context, proof)
+        assert_never(proof)
+
+    @classmethod
+    def _authorize_account(
+        cls,
+        context: AuthorizationContext,
+        proof: VerifiedAccountSessionProof,
+    ) -> SubmissionActor | SubmissionAuthorizationRejection:
+        if not isinstance(context.grant.subject, ContactApprovalSubject):
+            return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+        current = cls._validate_current_contact(context, context.grant.subject.contact_id)
+        if isinstance(current, SubmissionAuthorizationRejection):
+            return current
+        if current.account_id != proof.account_id:
+            return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+        return AccountSubmissionActor(proof.account_id)
+
+    @staticmethod
+    def _authorize_end_user(
+        context: AuthorizationContext,
+        proof: VerifiedTrustedEndUserProof,
+    ) -> SubmissionActor | SubmissionAuthorizationRejection:
+        if not isinstance(context.grant.subject, EndUserApprovalSubject):
+            return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+        current = context.current_end_user
+        if (
+            current is None
+            or current.end_user_id != context.grant.subject.end_user_id
+            or current.end_user_id != proof.end_user_id
+            or current.app_id != context.form.app_id
+            or current.app_id != proof.app_id
+        ):
+            return SubmissionAuthorizationRejection.END_USER_UNAVAILABLE
+        if not current.workspace_available:
+            return SubmissionAuthorizationRejection.WORKSPACE_UNAVAILABLE
+        return EndUserSubmissionActor(current.end_user_id)
+
+    @classmethod
+    def _authorize_email(
+        cls,
+        context: AuthorizationContext,
+        proof: VerifiedEmailOTPProof,
+    ) -> SubmissionActor | SubmissionAuthorizationRejection:
+        if proof.challenge_ref.grant_ref != context.grant.ref:
+            return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+        subject = context.grant.subject
+        if isinstance(subject, EmailAddressApprovalSubject):
+            if (
+                not isinstance(proof.subject, EmailAddressOTPSubject)
+                or proof.subject.normalized_email != subject.normalized_email
+                or proof.normalized_email != subject.normalized_email
+            ):
+                return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+            return EmailAddressSubmissionActor(subject.normalized_email)
+        if not isinstance(subject, ContactApprovalSubject) or not isinstance(proof.subject, ContactOTPSubject):
+            return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+        if proof.subject.contact_id != subject.contact_id:
+            return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+        current = cls._validate_current_contact(context, subject.contact_id)
+        if isinstance(current, SubmissionAuthorizationRejection):
+            return current
+        if current.normalized_email is None or current.normalized_email != proof.normalized_email:
+            return SubmissionAuthorizationRejection.STALE_IDENTITY
+        if current.account_id is not None:
+            return AccountSubmissionActor(current.account_id)
+        return EmailAddressSubmissionActor(proof.normalized_email)
+
+    @classmethod
+    def _authorize_im(
+        cls,
+        context: AuthorizationContext,
+        proof: VerifiedIMIdentityProof,
+    ) -> SubmissionActor | SubmissionAuthorizationRejection:
+        if not isinstance(context.grant.subject, ContactApprovalSubject):
+            return SubmissionAuthorizationRejection.GRANT_NOT_MATCHED
+        current_contact = cls._validate_current_contact(context, context.grant.subject.contact_id)
+        if isinstance(current_contact, SubmissionAuthorizationRejection):
+            return current_contact
+        if current_contact.account_id is None:
+            return SubmissionAuthorizationRejection.STALE_IDENTITY
+        current_im = context.current_im_binding
+        if current_im is None:
+            return SubmissionAuthorizationRejection.IM_BINDING_CHANGED
+        if (
+            current_im.contact_id != context.grant.subject.contact_id
+            or current_im.account_id != current_contact.account_id
+            or current_im.integration_id != proof.integration_id
+            or current_im.identity_id != proof.identity_id
+            or current_im.binding_id != proof.binding_id
+            or current_im.provider is not proof.provider
+            or current_im.provider_tenant_id != proof.provider_tenant_id
+            or current_im.provider_user_id != proof.provider_user_id
+        ):
+            return SubmissionAuthorizationRejection.IM_BINDING_CHANGED
+        return AccountSubmissionActor(current_contact.account_id)
+
+    @staticmethod
+    def _validate_current_contact(
+        context: AuthorizationContext,
+        contact_id: ContactId,
+    ) -> CurrentContactAuthorizationFacts | SubmissionAuthorizationRejection:
+        current = context.current_contact
+        if current is None or current.contact_id != contact_id:
+            return SubmissionAuthorizationRejection.STALE_IDENTITY
+        if current.account_id is not None and not current.account_active:
+            return SubmissionAuthorizationRejection.ACCOUNT_DISABLED
+        if not current.workspace_available:
+            return SubmissionAuthorizationRejection.WORKSPACE_UNAVAILABLE
+        return current
+
+
+__all__ = [
+    "AccountSubmissionActor",
+    "AuthorizationContext",
+    "AuthorizedSubmission",
+    "CurrentContactAuthorizationFacts",
+    "CurrentEndUserAuthorizationFacts",
+    "CurrentIMAuthorizationFacts",
+    "EmailAddressSubmissionActor",
+    "EndUserSubmissionActor",
+    "SubmissionActor",
+    "SubmissionAuthorizationDecision",
+    "SubmissionAuthorizationRejection",
+    "SubmissionAuthorizer",
+    "VerifiedAccountSessionProof",
+    "VerifiedIMIdentityProof",
+    "VerifiedSubmissionProof",
+    "VerifiedTrustedEndUserProof",
+]
@@ -0,0 +1,117 @@
+"""Transaction-oriented ports for current authorization and first-success commit.
+
+The transaction object keeps one coherent authorization context alive through
+the winning write set. Generic CRUD is intentionally absent; persistence owns
+the Form lock, rejection audit append, and atomic authorized commit shape.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+from core.human_input_v2.shared import (
+    ApproverGrantId,
+    AuditEventId,
+    DeliveryEndpointId,
+    SubmissionId,
+    UtcTimestamp,
+)
+
+from .frozen_values import FrozenJSONObject
+from .grants import FormRef
+from .submission_authorization import AuthorizationContext, AuthorizedSubmission
+from .submission_records import FormAuthorizationAuditEvent, FormSubmission
+
+
+class RetryableSubmissionPersistenceError(RuntimeError):
+    """A complete submission transaction must be retried with a fresh snapshot."""
+
+
+@dataclass(frozen=True, slots=True)
+class SubmissionAttemptScope:
+    """Complete logical owner chain selected before the transaction begins."""
+
+    form_ref: FormRef
+    approver_grant_id: ApproverGrantId
+    endpoint_id: DeliveryEndpointId | None
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizedSubmissionCommit:
+    """Caller-owned identities and structured values for one authorized write set."""
+
+    submission_id: SubmissionId
+    authorization_audit_event_id: AuditEventId
+    authorized: AuthorizedSubmission
+    input_snapshot: FrozenJSONObject
+    canonical_values: FrozenJSONObject
+
+    def to_submission(
+        self,
+        *,
+        form_ref: FormRef,
+        approver_grant_id: ApproverGrantId,
+        endpoint_id: DeliveryEndpointId | None,
+        submitted_at: UtcTimestamp,
+    ) -> FormSubmission:
+        """Build the immutable record value after owner-scope validation."""
+
+        return FormSubmission(
+            id=self.submission_id,
+            form_ref=form_ref,
+            approver_grant_id=approver_grant_id,
+            endpoint_id=endpoint_id,
+            authorization_audit_event_id=self.authorization_audit_event_id,
+            actor=self.authorized.actor,
+            selected_action_id=self.authorized.transition.selected_action_id,
+            input_snapshot=self.input_snapshot,
+            canonical_values=self.canonical_values,
+            submitted_at=submitted_at,
+            created_at=submitted_at,
+            updated_at=submitted_at,
+        )
+
+
+class SubmissionCommitStatus(StrEnum):
+    """Stable first-success persistence outcome."""
+
+    COMMITTED = "committed"
+    ALREADY_COMPLETED = "already_completed"
+
+
+@dataclass(frozen=True, slots=True)
+class SubmissionCommitResult:
+    """Committed winning submission or stable loser result."""
+
+    status: SubmissionCommitStatus
+    submission: FormSubmission | None
+
+
+class SubmissionTransaction(Protocol):
+    """One session-bound authorization and commit transaction."""
+
+    def load_authorization_context(self, *, proof: object) -> AuthorizationContext: ...
+
+    def append_rejection_audit(self, event: FormAuthorizationAuditEvent) -> None: ...
+
+    def commit_authorized_submission_once(self, commit: AuthorizedSubmissionCommit) -> SubmissionCommitResult: ...
+
+
+class SubmissionRepository(Protocol):
+    """Factory for one short transaction owning the complete submission use case."""
+
+    def transaction(self, scope: SubmissionAttemptScope) -> AbstractContextManager[SubmissionTransaction]: ...
+
+
+__all__ = [
+    "AuthorizedSubmissionCommit",
+    "RetryableSubmissionPersistenceError",
+    "SubmissionAttemptScope",
+    "SubmissionCommitResult",
+    "SubmissionCommitStatus",
+    "SubmissionRepository",
+    "SubmissionTransaction",
+]
@@ -0,0 +1,102 @@
+"""Immutable submission and shared authorization-audit persistence values.
+
+These values preserve business identity and structured snapshots without
+exposing ORM records. Persistence mappers alone translate them to storage
+columns and Pydantic JSON values.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from core.human_input_v2.entities import HumanInputDeliveryChannel
+from core.human_input_v2.shared import (
+    ApproverGrantId,
+    AuditEventId,
+    DeliveryEndpointId,
+    SubmissionId,
+    UtcTimestamp,
+)
+
+from .frozen_values import FrozenJSONObject
+from .grants import FormRef
+from .submission_authorization import SubmissionActor, VerifiedEmailOTPProof, VerifiedSubmissionProof
+
+
+class FormAuthorizationAuditEventType(StrEnum):
+    """Stable append-only event names owned by the shared audit table."""
+
+    OTP_CHALLENGE_ISSUED = "otp_challenge_issued"
+    SUBMISSION_AUTHORIZED = "submission_authorized"
+    SUBMISSION_REJECTED = "submission_rejected"
+
+
+@dataclass(frozen=True, slots=True)
+class FormAuthorizationAuditEvent:
+    """Secret-free authorized, rejected, or OTP issuance audit fact."""
+
+    id: AuditEventId
+    event_type: FormAuthorizationAuditEventType
+    form_ref: FormRef
+    approver_grant_id: ApproverGrantId | None
+    endpoint_id: DeliveryEndpointId | None
+    channel: HumanInputDeliveryChannel | None
+    reason_code: str | None
+    reason_message: str | None
+    authorization_proof: VerifiedSubmissionProof | None
+    payload: FrozenJSONObject | None
+    occurred_at: UtcTimestamp
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if self.event_type is FormAuthorizationAuditEventType.SUBMISSION_AUTHORIZED:
+            if self.approver_grant_id is None or self.authorization_proof is None:
+                raise ValueError("authorized audit event requires a grant and verified proof")
+            if self.reason_code is not None:
+                raise ValueError("authorized audit event cannot contain a rejection reason")
+            self.validate_authorization_proof_owner()
+        if self.event_type is FormAuthorizationAuditEventType.SUBMISSION_REJECTED and not self.reason_code:
+            raise ValueError("rejected audit event requires a stable reason code")
+
+    def validate_authorization_proof_owner(self) -> None:
+        """Reject authorized Email evidence captured for another form or grant."""
+
+        proof = self.authorization_proof
+        if not isinstance(proof, VerifiedEmailOTPProof):
+            return
+        if (
+            proof.challenge_ref.form_ref != self.form_ref
+            or proof.challenge_ref.grant_ref.grant_id != self.approver_grant_id
+        ):
+            raise ValueError("authorized Email proof owner does not match the audit event")
+
+
+@dataclass(frozen=True, slots=True)
+class FormSubmission:
+    """Immutable winning submission mapped independently from ORM lifetime."""
+
+    id: SubmissionId
+    form_ref: FormRef
+    approver_grant_id: ApproverGrantId
+    endpoint_id: DeliveryEndpointId | None
+    authorization_audit_event_id: AuditEventId
+    actor: SubmissionActor
+    selected_action_id: str
+    input_snapshot: FrozenJSONObject
+    canonical_values: FrozenJSONObject
+    submitted_at: UtcTimestamp
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if not self.selected_action_id.strip():
+            raise ValueError("submission selected action must not be blank")
+
+
+__all__ = [
+    "FormAuthorizationAuditEvent",
+    "FormAuthorizationAuditEventType",
+    "FormSubmission",
+]
@@ -0,0 +1,37 @@
+"""Infrastructure-free Contact Directory domain boundary.
+
+Transport and persistence layers may depend on this package. This package must
+not import controllers, Flask, SQLAlchemy, sessions, or ORM records.
+"""
+
+from .entities import (
+    Contact,
+    ContactIdentitySource,
+    ContactOwner,
+    ContactSnapshot,
+    ExternalContactOwner,
+    OrganizationAccountOwner,
+    PlatformWorkspaceEntry,
+    WorkspaceMemberOwner,
+)
+from .errors import ContactDirectoryError, ContactRejection, ContactRejectionCode
+from .policy import ContactDirectoryPolicy, ContactDirectorySnapshot, ContactResolution
+from .ports import ContactDirectoryRepository
+
+__all__ = [
+    "Contact",
+    "ContactDirectoryError",
+    "ContactDirectoryPolicy",
+    "ContactDirectoryRepository",
+    "ContactDirectorySnapshot",
+    "ContactIdentitySource",
+    "ContactOwner",
+    "ContactRejection",
+    "ContactRejectionCode",
+    "ContactResolution",
+    "ContactSnapshot",
+    "ExternalContactOwner",
+    "OrganizationAccountOwner",
+    "PlatformWorkspaceEntry",
+    "WorkspaceMemberOwner",
+]
@@ -0,0 +1,229 @@
+"""Canonical Contact identity independent of workspace-relative resolution.
+
+Contacts own identity invariants and current profile facts. Membership,
+allow-list state, database I/O, and transport serialization remain outside the
+entity so its immutable lifecycle source cannot be confused with a query result.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from core.human_input_v2.shared import (
+    AccountId,
+    ContactId,
+    DeploymentScope,
+    DirectoryScope,
+    NormalizedEmail,
+    PlatformEntryId,
+    UtcTimestamp,
+    WorkspaceId,
+    WorkspaceScope,
+)
+
+from .errors import ContactRejectionCode, reject
+
+
+class ContactIdentitySource(StrEnum):
+    """Immutable lifecycle source of a canonical Contact."""
+
+    ORGANIZATION_ACCOUNT = "organization_account"
+    WORKSPACE_MEMBER = "workspace_member"
+    EXTERNAL = "external"
+
+
+@dataclass(frozen=True, slots=True)
+class OrganizationAccountOwner:
+    """Deployment-wide EE owner reference backed by one Account."""
+
+    account_id: AccountId
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceMemberOwner:
+    """Workspace owner reference backed by one current or historical Account."""
+
+    workspace_id: WorkspaceId
+    account_id: AccountId
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalContactOwner:
+    """Workspace owner reference for an address managed by administrators."""
+
+    workspace_id: WorkspaceId
+
+
+type ContactOwner = OrganizationAccountOwner | WorkspaceMemberOwner | ExternalContactOwner
+
+
+@dataclass(frozen=True, slots=True)
+class Contact:
+    """Canonical identity whose source and owner remain immutable.
+
+    Use the named factories for normal construction. ``create`` exists for
+    persistence mapping and validates the same source/owner invariant.
+    """
+
+    id: ContactId
+    identity_source: ContactIdentitySource
+    owner: ContactOwner
+    name: str
+    normalized_name: str
+    email: str | None
+    normalized_email: NormalizedEmail | None
+    avatar_file_id: str | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        expected_owner_type = {
+            ContactIdentitySource.ORGANIZATION_ACCOUNT: OrganizationAccountOwner,
+            ContactIdentitySource.WORKSPACE_MEMBER: WorkspaceMemberOwner,
+            ContactIdentitySource.EXTERNAL: ExternalContactOwner,
+        }[self.identity_source]
+        if not isinstance(self.owner, expected_owner_type):
+            raise reject(ContactRejectionCode.INVALID_OWNER)
+        if not self.name.strip():
+            raise reject(ContactRejectionCode.INVALID_NAME)
+        if self.identity_source is ContactIdentitySource.EXTERNAL and self.normalized_email is None:
+            raise reject(ContactRejectionCode.INVALID_EMAIL)
+        if self.email is None and self.normalized_email is not None:
+            raise reject(ContactRejectionCode.INVALID_EMAIL)
+        if self.email is not None:
+            try:
+                normalized_email = NormalizedEmail(self.email)
+            except ValueError as error:
+                raise reject(ContactRejectionCode.INVALID_EMAIL) from error
+            if self.normalized_email != normalized_email:
+                raise reject(ContactRejectionCode.INVALID_EMAIL)
+            object.__setattr__(self, "email", self.email.strip())
+        normalized_name = self.name.strip().casefold()
+        if self.normalized_name != normalized_name:
+            object.__setattr__(self, "normalized_name", normalized_name)
+        object.__setattr__(self, "name", self.name.strip())
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        contact_id: ContactId,
+        identity_source: ContactIdentitySource,
+        owner: ContactOwner,
+        name: str,
+        email: str | None,
+        now: UtcTimestamp,
+        avatar_file_id: str | None = None,
+        created_at: UtcTimestamp | None = None,
+    ) -> Contact:
+        normalized_email: NormalizedEmail | None = None
+        if email is not None:
+            try:
+                normalized_email = NormalizedEmail(email)
+            except ValueError as error:
+                raise reject(ContactRejectionCode.INVALID_EMAIL) from error
+        return cls(
+            id=contact_id,
+            identity_source=identity_source,
+            owner=owner,
+            name=name,
+            normalized_name=name.strip().casefold(),
+            email=email,
+            normalized_email=normalized_email,
+            avatar_file_id=avatar_file_id,
+            created_at=created_at or now,
+            updated_at=now,
+        )
+
+    @classmethod
+    def organization_account(
+        cls,
+        *,
+        contact_id: ContactId,
+        account_id: AccountId,
+        name: str,
+        email: str | None,
+        now: UtcTimestamp,
+    ) -> Contact:
+        return cls.create(
+            contact_id=contact_id,
+            identity_source=ContactIdentitySource.ORGANIZATION_ACCOUNT,
+            owner=OrganizationAccountOwner(account_id),
+            name=name,
+            email=email,
+            now=now,
+        )
+
+    @classmethod
+    def workspace_member(
+        cls,
+        *,
+        contact_id: ContactId,
+        workspace_id: WorkspaceId,
+        account_id: AccountId,
+        name: str,
+        email: str | None,
+        now: UtcTimestamp,
+    ) -> Contact:
+        return cls.create(
+            contact_id=contact_id,
+            identity_source=ContactIdentitySource.WORKSPACE_MEMBER,
+            owner=WorkspaceMemberOwner(workspace_id, account_id),
+            name=name,
+            email=email,
+            now=now,
+        )
+
+    @classmethod
+    def external(
+        cls,
+        *,
+        contact_id: ContactId,
+        workspace_id: WorkspaceId,
+        name: str,
+        email: str,
+        now: UtcTimestamp,
+        avatar_file_id: str | None = None,
+    ) -> Contact:
+        return cls.create(
+            contact_id=contact_id,
+            identity_source=ContactIdentitySource.EXTERNAL,
+            owner=ExternalContactOwner(workspace_id),
+            name=name,
+            email=email,
+            now=now,
+            avatar_file_id=avatar_file_id,
+        )
+
+    @property
+    def account_id(self) -> AccountId | None:
+        if isinstance(self.owner, OrganizationAccountOwner | WorkspaceMemberOwner):
+            return self.owner.account_id
+        return None
+
+    @property
+    def directory_scope(self) -> DirectoryScope:
+        if isinstance(self.owner, OrganizationAccountOwner):
+            return DeploymentScope()
+        return WorkspaceScope(self.owner.workspace_id)
+
+
+@dataclass(frozen=True, slots=True)
+class ContactSnapshot:
+    """Immutable Contact plus current Account availability for one operation."""
+
+    contact: Contact
+    account_available: bool
+
+
+@dataclass(frozen=True, slots=True)
+class PlatformWorkspaceEntry:
+    """One workspace allow-list fact for an Organization Account Contact."""
+
+    id: PlatformEntryId
+    workspace_id: WorkspaceId
+    contact_id: ContactId
+    added_by_account_id: AccountId
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
@@ -0,0 +1,48 @@
+"""Transport-neutral Contact Directory rejection contracts."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class ContactRejectionCode(StrEnum):
+    """Stable machine-readable reasons returned by Contact Directory operations."""
+
+    INVALID_OWNER = "invalid_owner"
+    INVALID_EMAIL = "invalid_email"
+    INVALID_NAME = "invalid_name"
+    CONFLICTING_IDENTITY = "conflicting_identity"
+    CROSS_ORGANIZATION = "cross_organization"
+    ACCOUNT_UNAVAILABLE = "account_unavailable"
+    CONTACT_NOT_FOUND = "contact_not_found"
+    SETUP_ROW_MISSING = "setup_row_missing"
+    PERSISTENCE_FAILURE = "persistence_failure"
+
+
+@dataclass(frozen=True, slots=True)
+class ContactRejection:
+    """Serializable domain rejection without HTTP or RPC semantics."""
+
+    reason: ContactRejectionCode
+
+    def to_primitive(self) -> dict[str, str]:
+        return {"reason": self.reason.value}
+
+
+class ContactDirectoryError(Exception):
+    """Exception carrier for one transport-neutral Contact rejection."""
+
+    rejection: ContactRejection
+
+    def __init__(self, rejection: ContactRejection) -> None:
+        self.rejection = rejection
+        super().__init__(rejection.reason.value)
+
+    @property
+    def code(self) -> ContactRejectionCode:
+        return self.rejection.reason
+
+
+def reject(reason: ContactRejectionCode) -> ContactDirectoryError:
+    """Build a domain exception while keeping reason construction consistent."""
+
+    return ContactDirectoryError(ContactRejection(reason))
@@ -0,0 +1,101 @@
+"""Pure Contact Directory resolution and lifecycle policies.
+
+The immutable snapshot supplies all operation-scoped facts. Policies never load
+membership, Account, allow-list, or Contact records themselves.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from core.human_input_v2.shared import AccountId, ContactId, NormalizedEmail, UtcTimestamp, WorkspaceId
+
+from .entities import Contact, ExternalContactOwner, OrganizationAccountOwner, WorkspaceMemberOwner
+from .errors import ContactRejectionCode, reject
+
+
+class ContactResolution(StrEnum):
+    """Workspace-relative availability of one canonical Contact."""
+
+    WORKSPACE = "workspace"
+    PLATFORM = "platform"
+    EXTERNAL = "external"
+    ABSENT = "absent"
+
+
+@dataclass(frozen=True, slots=True)
+class ContactDirectorySnapshot:
+    """Coherent, request-scoped Contact facts for one workspace.
+
+    The snapshot is deliberately not a cache. Authorization callers that need
+    current facts must load a new snapshot in their own operation.
+    """
+
+    workspace_id: WorkspaceId
+    contacts: tuple[Contact, ...] = ()
+    member_account_ids: frozenset[AccountId] = frozenset()
+    platform_contact_ids: frozenset[ContactId] = frozenset()
+    unavailable_account_ids: frozenset[AccountId] = frozenset()
+
+    def find(self, contact_id: ContactId) -> Contact | None:
+        return next((contact for contact in self.contacts if contact.id == contact_id), None)
+
+
+class ContactDirectoryPolicy:
+    """Stateless policy for workspace resolution and External lifecycle rules."""
+
+    @staticmethod
+    def resolve_for_workspace(snapshot: ContactDirectorySnapshot, contact_id: ContactId) -> ContactResolution:
+        contact = snapshot.find(contact_id)
+        if contact is None:
+            return ContactResolution.ABSENT
+
+        owner = contact.owner
+        if isinstance(owner, ExternalContactOwner):
+            if owner.workspace_id != snapshot.workspace_id:
+                raise reject(ContactRejectionCode.CROSS_ORGANIZATION)
+            return ContactResolution.EXTERNAL
+        if isinstance(owner, WorkspaceMemberOwner) and owner.workspace_id != snapshot.workspace_id:
+            raise reject(ContactRejectionCode.CROSS_ORGANIZATION)
+
+        account_id = contact.account_id
+        if account_id is None or account_id in snapshot.unavailable_account_ids:
+            return ContactResolution.ABSENT
+        if account_id in snapshot.member_account_ids:
+            return ContactResolution.WORKSPACE
+        if isinstance(owner, OrganizationAccountOwner) and contact.id in snapshot.platform_contact_ids:
+            return ContactResolution.PLATFORM
+        return ContactResolution.ABSENT
+
+    @staticmethod
+    def admit_external(
+        snapshot: ContactDirectorySnapshot,
+        *,
+        contact_id: ContactId,
+        name: str,
+        email: str,
+        now: UtcTimestamp,
+        avatar_file_id: str | None = None,
+    ) -> Contact:
+        try:
+            normalized_email = NormalizedEmail(email)
+        except ValueError as error:
+            raise reject(ContactRejectionCode.INVALID_EMAIL) from error
+        if any(contact.normalized_email == normalized_email for contact in snapshot.contacts):
+            raise reject(ContactRejectionCode.CONFLICTING_IDENTITY)
+        return Contact.external(
+            contact_id=contact_id,
+            workspace_id=snapshot.workspace_id,
+            name=name,
+            email=email,
+            now=now,
+            avatar_file_id=avatar_file_id,
+        )
+
+    @staticmethod
+    def ensure_external_deletable(contact: Contact, workspace_id: WorkspaceId) -> None:
+        if not isinstance(contact.owner, ExternalContactOwner):
+            raise reject(ContactRejectionCode.INVALID_OWNER)
+        if contact.owner.workspace_id != workspace_id:
+            raise reject(ContactRejectionCode.CROSS_ORGANIZATION)
@@ -0,0 +1,47 @@
+"""Aggregate-oriented persistence ports for Contact Directory operations.
+
+Implementations own transactions, owner predicates, locking, mapping, and
+rollback. Callers receive domain values and never persistence records.
+"""
+
+from typing import Protocol
+
+from core.human_input_v2.shared import AccountId, ContactId, WorkspaceId
+
+from .entities import Contact
+from .policy import ContactDirectorySnapshot
+
+
+class ContactDirectoryRepository(Protocol):
+    """Persistence contract centered on coherent directory invariants."""
+
+    def load_snapshot(self, workspace_id: WorkspaceId) -> ContactDirectorySnapshot:
+        """Load one immutable workspace-scoped directory view."""
+        ...
+
+    def save_organization_contact(self, contact: Contact) -> Contact:
+        """Create or update one deployment-owned Organization Contact with a serialized Email claim."""
+        ...
+
+    def save_workspace_member_contact(self, contact: Contact) -> Contact:
+        """Create or update one Contact backed by current workspace membership."""
+        ...
+
+    def admit_external(self, workspace_id: WorkspaceId, *, name: str, email: str) -> Contact:
+        """Atomically admit one External Contact against tenant and configured Organization identities."""
+        ...
+
+    def set_platform_availability(
+        self,
+        workspace_id: WorkspaceId,
+        contact_id: ContactId,
+        *,
+        added_by_account_id: AccountId,
+        enabled: bool,
+    ) -> None:
+        """Atomically add or remove one EE Platform allow-list fact."""
+        ...
+
+    def hard_delete_external(self, workspace_id: WorkspaceId, contact_id: ContactId) -> None:
+        """Delete an External Contact without retaining an identity tombstone."""
+        ...
@@ -0,0 +1,197 @@
+from enum import StrEnum
+from typing import NewType
+
+from core.human_input_v2.shared import AccountId, NormalizedEmail, UtcTimestamp, WorkspaceId
+
+
+class HumanInputContactType(StrEnum):
+    """Concrete contact classification resolved in one workspace."""
+
+    WORKSPACE = "workspace"
+    PLATFORM = "platform"
+    EXTERNAL = "external"
+
+
+class HumanInputApproverGrantSubjectType(StrEnum):
+    """Business subject receiving approval authority for one Human Input form."""
+
+    CONTACT = "contact"
+    END_USER = "end_user"
+    EMAIL_ADDRESS = "email_address"
+
+
+class HumanInputSubmissionActorType(StrEnum):
+    """Business identity that completed one Human Input form submission."""
+
+    ACCOUNT = "account"
+    END_USER = "end_user"
+    EMAIL_ADDRESS = "email_address"
+
+
+class HumanInputV2FormKind(StrEnum):
+    """Persistence kind for an independently stored Human Input v2 form."""
+
+    RUNTIME = "runtime"
+    DELIVERY_TEST = "delivery_test"
+
+
+class HumanInputV2FormStatus(StrEnum):
+    """Lifecycle state of an independently stored Human Input v2 form."""
+
+    WAITING = "waiting"
+    EXPIRED = "expired"
+    SUBMITTED = "submitted"
+    TIMEOUT = "timeout"
+
+
+class HumanInputAuthorizationProofType(StrEnum):
+    """Verified evidence type retained for a Human Input authorization audit event."""
+
+    ACCOUNT_SESSION = "account_session"
+    EMAIL_OTP = "email_otp"
+    IM_IDENTITY = "im_identity"
+    TRUSTED_END_USER = "trusted_end_user"
+
+
+class HumanInputDeliveryChannel(StrEnum):
+    """Notification or interaction channel frozen for one form endpoint."""
+
+    EMAIL = "email"
+    IM = "im"
+    WEB = "web"
+    CONSOLE = "console"
+
+
+class HumanInputDeliveryAttemptStatus(StrEnum):
+    """Delivery lifecycle kept separate from the form state machine."""
+
+    QUEUED = "queued"
+    SENDING = "sending"
+    SENT = "sent"
+    FAILED = "failed"
+
+
+class HumanInputOTPChallengeStatus(StrEnum):
+    """Current usability of an email proof challenge."""
+
+    PENDING = "pending"
+    VERIFIED = "verified"
+    INVALIDATED = "invalidated"
+    EXPIRED = "expired"
+
+
+class IMProvider(StrEnum):
+    """IM provider supported by Human Input contact and delivery flows."""
+
+    FEISHU = "feishu"
+    SLACK = "slack"
+    DING_TALK = "ding_talk"
+    MS_TEAMS = "ms_teams"
+    WE_COM = "we_com"
+    LARK = "lark"
+
+
+class IMBindingScope(StrEnum):
+    """Resolution scope of a contact-to-IM-identity binding."""
+
+    WORKSPACE = "workspace"
+    ORGANIZATION = "organization"
+
+
+class IMIntegrationStatus(StrEnum):
+    """Connectivity state of an organization-level IM integration."""
+
+    NOT_CONFIGURED = "not_configured"
+    CONFIGURED = "configured"
+    CONNECTED = "connected"
+    PERMISSION_ISSUE = "permission_issue"
+    CALLBACK_ERROR = "callback_error"
+    CONNECTION_ERROR = "connection_error"
+
+
+class IMIdentityBindingStatus(StrEnum):
+    """Whether a synchronized IM identity is currently bound."""
+
+    UNBOUND = "unbound"
+    BOUND = "bound"
+
+
+class IMSyncRunStatus(StrEnum):
+    """Lifecycle state of a manual IM directory synchronization."""
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+class IMSyncResultType(StrEnum):
+    """Stable reconciliation bucket for one synchronized directory entry."""
+
+    ADDED = "added"
+    NOT_MATCHED = "not_matched"
+    FAILED = "failed"
+    REMOVED = "removed"
+    SKIPPED = "skipped"
+
+
+class IMSyncRemovalReason(StrEnum):
+    """Stable reason for removing or replacing a current IM binding."""
+
+    NOT_PRESENT_IN_DIRECTORY = "not_present_in_directory"
+    BINDING_INVALIDATED = "binding_invalidated"
+    BINDING_REPLACED = "binding_replaced"
+
+
+class EmailProviderType(StrEnum):
+    """Email provider supported by organization-level Human Input delivery."""
+
+    RESEND = "resend"
+
+
+# Identifiers for organization candidates and contacts.
+OrganizationCandidateId = NewType("OrganizationCandidateId", str)
+
+# Legacy transport identifier. Contact Directory code uses the richer value
+# object from ``core.human_input_v2.shared`` at its domain boundary.
+ContactId = NewType("ContactId", str)
+
+# Identifiers for synced IM identiies. This is not the same as user_id or account_id
+# on the IM provier side. It is the identifier for the synced IM user record in Dify.
+IMIdentityId = NewType("IMIdentityId", str)
+
+# Identifiers for a full IM user synchorization.
+IMSyncRunId = NewType("IMSyncRunId", str)
+
+# Identifier for an IM binding, an association between an IM identity and a Dify contact.
+IMBindingId = NewType("IMBindingId", str)
+
+
+__all__ = [
+    "AccountId",
+    "ContactId",
+    "EmailProviderType",
+    "HumanInputApproverGrantSubjectType",
+    "HumanInputAuthorizationProofType",
+    "HumanInputContactType",
+    "HumanInputDeliveryAttemptStatus",
+    "HumanInputDeliveryChannel",
+    "HumanInputOTPChallengeStatus",
+    "HumanInputSubmissionActorType",
+    "HumanInputV2FormKind",
+    "HumanInputV2FormStatus",
+    "IMBindingId",
+    "IMBindingScope",
+    "IMIdentityBindingStatus",
+    "IMIdentityId",
+    "IMIntegrationStatus",
+    "IMProvider",
+    "IMSyncRemovalReason",
+    "IMSyncResultType",
+    "IMSyncRunId",
+    "IMSyncRunStatus",
+    "NormalizedEmail",
+    "OrganizationCandidateId",
+    "UtcTimestamp",
+    "WorkspaceId",
+]
@@ -0,0 +1,82 @@
+"""Infrastructure-free IM configuration, synchronization, and binding boundary.
+
+This package depends on canonical Contact Directory facts and shared primitive
+values. Provider clients, controllers, SQLAlchemy sessions, ORM records, and
+provider transport payload types belong outside this boundary. The public API
+hides configuration CAS, sync matching, and effective-binding priority behind
+domain decisions and transaction-oriented ports.
+"""
+
+from .binding_resolution import (
+    BindingResolutionKind,
+    BindingResolutionResult,
+    EffectiveBindingResolver,
+    EffectiveIMBindingSnapshot,
+)
+from .integration import (
+    ConfigurationTransition,
+    ConfigurationTransitionKind,
+    CurrentStateInvalidation,
+    EncryptedCredentials,
+    IMIntegration,
+    IntegrationDeletion,
+    IntegrationRevisionToken,
+    ProviderTenantIdentity,
+    StaleRevision,
+)
+from .ports import (
+    ActiveRunDecision,
+    ActiveRunDecisionKind,
+    ApplyReconciliationResult,
+    ApplyReconciliationStatus,
+    IMControlPlaneRepository,
+)
+from .records import IMBinding, IMIdentity, OpaqueProviderPayload
+from .state import IMIntegrationState
+from .sync_reconciliation import (
+    IMSyncRun,
+    MatchKind,
+    ProviderDirectoryEntry,
+    ReconciliationAction,
+    ReconciliationPlan,
+    ReconciliationSnapshot,
+    SyncContactSnapshot,
+    SyncIdentitySnapshot,
+    SyncReconciler,
+    SyncResultFact,
+)
+
+__all__ = [
+    "ActiveRunDecision",
+    "ActiveRunDecisionKind",
+    "ApplyReconciliationResult",
+    "ApplyReconciliationStatus",
+    "BindingResolutionKind",
+    "BindingResolutionResult",
+    "ConfigurationTransition",
+    "ConfigurationTransitionKind",
+    "CurrentStateInvalidation",
+    "EffectiveBindingResolver",
+    "EffectiveIMBindingSnapshot",
+    "EncryptedCredentials",
+    "IMBinding",
+    "IMControlPlaneRepository",
+    "IMIdentity",
+    "IMIntegration",
+    "IMIntegrationState",
+    "IMSyncRun",
+    "IntegrationDeletion",
+    "IntegrationRevisionToken",
+    "MatchKind",
+    "OpaqueProviderPayload",
+    "ProviderDirectoryEntry",
+    "ProviderTenantIdentity",
+    "ReconciliationAction",
+    "ReconciliationPlan",
+    "ReconciliationSnapshot",
+    "StaleRevision",
+    "SyncContactSnapshot",
+    "SyncIdentitySnapshot",
+    "SyncReconciler",
+    "SyncResultFact",
+]
@@ -0,0 +1,178 @@
+"""Effective binding priority and credential-free consumer snapshots."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from core.human_input_v2.contact_directory import ContactSnapshot
+from core.human_input_v2.entities import IMBindingScope, IMProvider
+from core.human_input_v2.shared import (
+    AccountId,
+    ContactId,
+    IMBindingId,
+    IMIdentityId,
+    IntegrationId,
+    WorkspaceId,
+)
+
+from .integration import IntegrationRevisionToken, ProviderTenantIdentity
+from .records import IMBinding, IMIdentity
+
+
+class BindingResolutionKind(StrEnum):
+    """Stable priority result returned to control-plane consumers."""
+
+    WORKSPACE_OVERRIDE = "workspace_override"
+    ORGANIZATION_BINDING = "organization_binding"
+    EMAIL_FALLBACK = "email_fallback"
+    NOT_AVAILABLE = "not_available"
+    INVALID_BINDING = "invalid_binding"
+
+
+@dataclass(frozen=True, slots=True)
+class EffectiveIMBindingSnapshot:
+    """Consumer-safe effective channel facts without credentials or raw payloads."""
+
+    integration_id: IntegrationId
+    integration_config_version: int
+    provider: IMProvider
+    provider_tenant_id: str
+    contact_id: ContactId
+    account_id: AccountId | None
+    identity_id: IMIdentityId
+    binding_id: IMBindingId | None
+    provider_user_id: str
+    display_name: str | None
+    email: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class BindingResolutionResult:
+    """Effective binding or stable rejection without leaking invalid records."""
+
+    kind: BindingResolutionKind
+    binding: EffectiveIMBindingSnapshot | None
+
+
+class EffectiveBindingResolver:
+    """Resolve workspace override, organization binding, then Email fallback."""
+
+    @staticmethod
+    def resolve(
+        *,
+        integration_revision: IntegrationRevisionToken,
+        provider_tenant: ProviderTenantIdentity,
+        workspace_id: WorkspaceId,
+        contact: ContactSnapshot,
+        identities: tuple[IMIdentity, ...],
+        bindings: tuple[IMBinding, ...],
+    ) -> BindingResolutionResult:
+        identities_by_id = {identity.id: identity for identity in identities}
+        candidates = [binding for binding in bindings if binding.contact_id == contact.contact.id]
+        workspace_binding = next(
+            (
+                binding
+                for binding in candidates
+                if binding.scope is IMBindingScope.WORKSPACE and binding.scope_id == str(workspace_id)
+            ),
+            None,
+        )
+        organization_binding = next(
+            (
+                binding
+                for binding in candidates
+                if binding.scope is IMBindingScope.ORGANIZATION
+                and binding.scope_id == str(integration_revision.integration_id)
+            ),
+            None,
+        )
+
+        selected = workspace_binding or organization_binding
+        if selected is not None:
+            identity = identities_by_id.get(selected.identity_id)
+            if not EffectiveBindingResolver._matches_integration(
+                selected,
+                identity,
+                integration_revision,
+                provider_tenant,
+            ):
+                return BindingResolutionResult(BindingResolutionKind.INVALID_BINDING, None)
+            assert identity is not None
+            kind = (
+                BindingResolutionKind.WORKSPACE_OVERRIDE
+                if selected is workspace_binding
+                else BindingResolutionKind.ORGANIZATION_BINDING
+            )
+            return BindingResolutionResult(
+                kind,
+                EffectiveBindingResolver._snapshot(
+                    integration_revision,
+                    provider_tenant,
+                    contact,
+                    identity,
+                    selected.id,
+                ),
+            )
+
+        normalized_email = contact.contact.normalized_email
+        if normalized_email is not None:
+            identity = next(
+                (
+                    candidate
+                    for candidate in identities
+                    if candidate.integration_id == integration_revision.integration_id
+                    and candidate.provider is provider_tenant.provider
+                    and candidate.normalized_email == normalized_email
+                ),
+                None,
+            )
+            if identity is not None:
+                return BindingResolutionResult(
+                    BindingResolutionKind.EMAIL_FALLBACK,
+                    EffectiveBindingResolver._snapshot(
+                        integration_revision,
+                        provider_tenant,
+                        contact,
+                        identity,
+                        None,
+                    ),
+                )
+        return BindingResolutionResult(BindingResolutionKind.NOT_AVAILABLE, None)
+
+    @staticmethod
+    def _matches_integration(
+        binding: IMBinding,
+        identity: IMIdentity | None,
+        integration_revision: IntegrationRevisionToken,
+        provider_tenant: ProviderTenantIdentity,
+    ) -> bool:
+        return (
+            identity is not None
+            and binding.integration_id == integration_revision.integration_id
+            and identity.integration_id == integration_revision.integration_id
+            and binding.provider is provider_tenant.provider
+            and identity.provider is provider_tenant.provider
+        )
+
+    @staticmethod
+    def _snapshot(
+        revision: IntegrationRevisionToken,
+        provider_tenant: ProviderTenantIdentity,
+        contact: ContactSnapshot,
+        identity: IMIdentity,
+        binding_id: IMBindingId | None,
+    ) -> EffectiveIMBindingSnapshot:
+        return EffectiveIMBindingSnapshot(
+            integration_id=revision.integration_id,
+            integration_config_version=revision.config_version,
+            provider=provider_tenant.provider,
+            provider_tenant_id=provider_tenant.provider_tenant_id,
+            contact_id=contact.contact.id,
+            account_id=contact.contact.account_id,
+            identity_id=identity.id,
+            binding_id=binding_id,
+            provider_user_id=identity.provider_user_id,
+            display_name=identity.display_name,
+            email=identity.email,
+        )
@@ -0,0 +1,236 @@
+"""IM Integration aggregate and complete compare-and-swap revision values."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from enum import StrEnum
+
+from pydantic import JsonValue
+
+from core.human_input_v2.entities import IMIntegrationStatus, IMProvider
+from core.human_input_v2.shared import AccountId, IntegrationId, UtcTimestamp, WorkspaceId
+
+
+@dataclass(frozen=True, slots=True)
+class EncryptedCredentials:
+    """Immutable opaque encrypted configuration passed through the domain boundary."""
+
+    _serialized: str
+
+    @classmethod
+    def from_mapping(cls, values: Mapping[str, JsonValue]) -> EncryptedCredentials:
+        if not values:
+            raise ValueError("encrypted credentials must not be empty")
+        return cls(json.dumps(dict(values), sort_keys=True, separators=(",", ":")))
+
+    def to_mapping(self) -> dict[str, JsonValue]:
+        value = json.loads(self._serialized)
+        if not isinstance(value, dict):
+            raise ValueError("encrypted credentials must be a JSON object")
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderTenantIdentity:
+    """Provider plus its confirmed organization or workspace identity."""
+
+    provider: IMProvider
+    provider_tenant_id: str
+
+    def __post_init__(self) -> None:
+        if not self.provider_tenant_id.strip():
+            raise ValueError("provider tenant id must not be blank")
+        object.__setattr__(self, "provider_tenant_id", self.provider_tenant_id.strip())
+
+
+@dataclass(frozen=True, slots=True)
+class IntegrationRevisionToken:
+    """Complete CAS token that prevents identity-replacement ABA."""
+
+    integration_id: IntegrationId
+    config_version: int
+
+    def __post_init__(self) -> None:
+        if self.config_version < 1:
+            raise ValueError("config version must be positive")
+
+
+@dataclass(frozen=True, slots=True)
+class StaleRevision:
+    """Stable rejection for a token that no longer names current configuration."""
+
+    expected: IntegrationRevisionToken
+    actual: IntegrationRevisionToken | None
+
+
+class ConfigurationTransitionKind(StrEnum):
+    """Current-state effect selected by one confirmed configuration write."""
+
+    CREDENTIAL_ROTATION = "credential_rotation"
+    PROVIDER_REPLACEMENT = "provider_replacement"
+
+
+@dataclass(frozen=True, slots=True)
+class CurrentStateInvalidation:
+    """Current identity and binding cleanup owned by the configuration transaction."""
+
+    invalidate_identities: bool
+    invalidate_bindings: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigurationTransition:
+    """Atomic configuration write plus its current-state cleanup decision."""
+
+    expected_revision: IntegrationRevisionToken
+    kind: ConfigurationTransitionKind
+    integration: IMIntegration
+    invalidation: CurrentStateInvalidation
+
+
+@dataclass(frozen=True, slots=True)
+class IntegrationDeletion:
+    """CAS-authorized deletion and current-state invalidation decision."""
+
+    expected_revision: IntegrationRevisionToken
+    invalidation: CurrentStateInvalidation = CurrentStateInvalidation(True, True)
+
+
+@dataclass(frozen=True, slots=True)
+class IMIntegration:
+    """Organization IM configuration aggregate.
+
+    Provider reads and credential encryption happen before construction.
+    Configuration transitions return decisions; persistence adapters alone make
+    them atomic and decide whether the expected revision is still current.
+    Connectivity diagnostics are non-configuration state and retain the token.
+    """
+
+    id: IntegrationId
+    workspace_id: WorkspaceId | None
+    provider_tenant: ProviderTenantIdentity
+    encrypted_credentials: EncryptedCredentials
+    configured_by_account_id: AccountId | None
+    callback_url: str | None
+    config_version: int
+    status: IMIntegrationStatus
+    safe_status_reason: str | None
+    last_checked_at: UtcTimestamp | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if self.config_version < 1:
+            raise ValueError("config version must be positive")
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        integration_id: IntegrationId,
+        workspace_id: WorkspaceId | None,
+        provider_tenant: ProviderTenantIdentity,
+        encrypted_credentials: EncryptedCredentials,
+        configured_by_account_id: AccountId | None,
+        callback_url: str | None,
+        now: UtcTimestamp,
+    ) -> IMIntegration:
+        return cls(
+            id=integration_id,
+            workspace_id=workspace_id,
+            provider_tenant=provider_tenant,
+            encrypted_credentials=encrypted_credentials,
+            configured_by_account_id=configured_by_account_id,
+            callback_url=callback_url,
+            config_version=1,
+            status=IMIntegrationStatus.CONFIGURED,
+            safe_status_reason=None,
+            last_checked_at=None,
+            created_at=now,
+            updated_at=now,
+        )
+
+    @property
+    def revision(self) -> IntegrationRevisionToken:
+        return IntegrationRevisionToken(self.id, self.config_version)
+
+    def reconfigure(
+        self,
+        *,
+        expected_revision: IntegrationRevisionToken,
+        provider_tenant: ProviderTenantIdentity,
+        encrypted_credentials: EncryptedCredentials,
+        configured_by_account_id: AccountId | None,
+        callback_url: str | None,
+        now: UtcTimestamp,
+        replacement_integration_id: IntegrationId | None = None,
+    ) -> ConfigurationTransition | StaleRevision:
+        """Plan a confirmed rotation or replacement without performing I/O."""
+
+        if expected_revision != self.revision:
+            return StaleRevision(expected_revision, self.revision)
+
+        if provider_tenant == self.provider_tenant:
+            if replacement_integration_id not in (None, self.id):
+                raise ValueError("credential rotation must preserve integration identity")
+            updated = replace(
+                self,
+                encrypted_credentials=encrypted_credentials,
+                configured_by_account_id=configured_by_account_id,
+                callback_url=callback_url,
+                config_version=self.config_version + 1,
+                status=IMIntegrationStatus.CONFIGURED,
+                safe_status_reason=None,
+                last_checked_at=None,
+                updated_at=now,
+            )
+            return ConfigurationTransition(
+                expected_revision=expected_revision,
+                kind=ConfigurationTransitionKind.CREDENTIAL_ROTATION,
+                integration=updated,
+                invalidation=CurrentStateInvalidation(False, False),
+            )
+
+        if replacement_integration_id is None or replacement_integration_id == self.id:
+            raise ValueError("provider replacement requires a new integration identity")
+        replacement = IMIntegration.create(
+            integration_id=replacement_integration_id,
+            workspace_id=self.workspace_id,
+            provider_tenant=provider_tenant,
+            encrypted_credentials=encrypted_credentials,
+            configured_by_account_id=configured_by_account_id,
+            callback_url=callback_url,
+            now=now,
+        )
+        return ConfigurationTransition(
+            expected_revision=expected_revision,
+            kind=ConfigurationTransitionKind.PROVIDER_REPLACEMENT,
+            integration=replacement,
+            invalidation=CurrentStateInvalidation(True, True),
+        )
+
+    def plan_deletion(self, expected_revision: IntegrationRevisionToken) -> IntegrationDeletion | StaleRevision:
+        """Return deletion cleanup only when the complete token is current."""
+
+        if expected_revision != self.revision:
+            return StaleRevision(expected_revision, self.revision)
+        return IntegrationDeletion(expected_revision)
+
+    def record_diagnostics(
+        self,
+        *,
+        status: IMIntegrationStatus,
+        safe_status_reason: str | None,
+        checked_at: UtcTimestamp,
+    ) -> IMIntegration:
+        """Update connection diagnostics without advancing configuration."""
+
+        return replace(
+            self,
+            status=status,
+            safe_status_reason=safe_status_reason,
+            last_checked_at=checked_at,
+            updated_at=checked_at,
+        )
@@ -0,0 +1,123 @@
+"""Transaction-oriented persistence ports for IM Control Plane invariants.
+
+Implementations own CAS predicates, Integration row locks, eager loading,
+revision-guarded apply, rollback, and append-only result persistence. Generic
+table CRUD is intentionally absent.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+from core.human_input_v2.entities import IMProvider
+from core.human_input_v2.shared import (
+    AccountId,
+    ContactId,
+    IMSyncRunId,
+    IntegrationId,
+    UtcTimestamp,
+    WorkspaceId,
+)
+
+from .binding_resolution import BindingResolutionResult
+from .integration import (
+    ConfigurationTransition,
+    IMIntegration,
+    IntegrationDeletion,
+    IntegrationRevisionToken,
+    StaleRevision,
+)
+from .sync_reconciliation import IMSyncRun, ReconciliationPlan, ReconciliationSnapshot, SyncResultFact
+
+
+class ActiveRunDecisionKind(StrEnum):
+    """Outcome of Integration-locked sync run creation."""
+
+    CREATED = "created"
+    EXISTING_ACTIVE = "existing_active"
+    STALE_REVISION = "stale_revision"
+
+
+@dataclass(frozen=True, slots=True)
+class ActiveRunDecision:
+    """New or existing active run, or a stable stale-revision rejection."""
+
+    kind: ActiveRunDecisionKind
+    run: IMSyncRun | None
+    stale_revision: StaleRevision | None = None
+
+
+class ApplyReconciliationStatus(StrEnum):
+    """Stable outcome of one idempotent revision-guarded apply."""
+
+    APPLIED = "applied"
+    ALREADY_APPLIED = "already_applied"
+    STALE_REVISION = "stale_revision"
+
+
+@dataclass(frozen=True, slots=True)
+class ApplyReconciliationResult:
+    """Run and append-only facts returned after reconciliation apply."""
+
+    status: ApplyReconciliationStatus
+    run: IMSyncRun
+    results: tuple[SyncResultFact, ...]
+
+
+class IMControlPlaneRepository(Protocol):
+    """Atomic persistence capabilities required by the IM domain."""
+
+    def create_integration(self, integration: IMIntegration) -> IMIntegration:
+        """Create the first integration configuration for its owner scope."""
+        ...
+
+    def compare_and_swap_configuration(self, transition: ConfigurationTransition) -> IMIntegration | StaleRevision:
+        """Atomically apply rotation or replacement and its invalidation plan."""
+        ...
+
+    def compare_and_swap_delete(self, deletion: IntegrationDeletion) -> None | StaleRevision:
+        """Delete current configuration and current children under complete CAS."""
+        ...
+
+    def create_or_get_active_run(
+        self,
+        integration_revision: IntegrationRevisionToken,
+        *,
+        sync_run_id: IMSyncRunId,
+        started_by_account_id: AccountId | None,
+        now: UtcTimestamp,
+    ) -> ActiveRunDecision:
+        """Lock Integration and return at most one active run."""
+        ...
+
+    def load_reconciliation_snapshot(self, sync_run_id: IMSyncRunId) -> ReconciliationSnapshot:
+        """Load current identities, bindings, and eligible Contact facts."""
+        ...
+
+    def apply_reconciliation(self, plan: ReconciliationPlan, *, now: UtcTimestamp) -> ApplyReconciliationResult:
+        """Apply one plan using its persisted sync run capture as CAS authority."""
+        ...
+
+    def resolve_effective_binding(
+        self,
+        *,
+        integration_id: IntegrationId,
+        provider: IMProvider,
+        workspace_id: WorkspaceId,
+        contact_id: ContactId,
+    ) -> BindingResolutionResult:
+        """Load and resolve one credential-free effective binding snapshot."""
+        ...
+
+    def append_sync_results(self, results: tuple[SyncResultFact, ...]) -> None:
+        """Append diagnostic result facts without changing current state."""
+        ...
+
+
+__all__ = [
+    "ActiveRunDecision",
+    "ActiveRunDecisionKind",
+    "ApplyReconciliationResult",
+    "ApplyReconciliationStatus",
+    "IMControlPlaneRepository",
+]
@@ -0,0 +1,145 @@
+"""Current IM identity and binding values shared by sync and resolution."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from pydantic import JsonValue
+
+from core.human_input_v2.entities import IMBindingScope, IMProvider
+from core.human_input_v2.shared import (
+    AccountId,
+    ContactId,
+    IMBindingId,
+    IMIdentityId,
+    IMSyncRunId,
+    IntegrationId,
+    NormalizedEmail,
+    UtcTimestamp,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class OpaqueProviderPayload:
+    """Immutable provider JSON retained only for persistence diagnostics."""
+
+    _serialized: str
+
+    @classmethod
+    def from_mapping(cls, values: Mapping[str, JsonValue]) -> OpaqueProviderPayload:
+        return cls(json.dumps(dict(values), sort_keys=True, separators=(",", ":")))
+
+    def to_mapping(self) -> dict[str, JsonValue]:
+        value = json.loads(self._serialized)
+        if not isinstance(value, dict):
+            raise ValueError("provider payload must be a JSON object")
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class IMIdentity:
+    """Current provider identity independent from ORM lifetime and raw clients."""
+
+    id: IMIdentityId
+    integration_id: IntegrationId
+    provider: IMProvider
+    provider_user_id: str
+    display_name: str | None
+    normalized_name: str | None
+    email: str | None
+    normalized_email: NormalizedEmail | None
+    raw_payload: OpaqueProviderPayload
+    last_seen_sync_run_id: IMSyncRunId | None
+    last_seen_at: UtcTimestamp | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if not self.provider_user_id.strip():
+            raise ValueError("provider user id must not be blank")
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        identity_id: IMIdentityId,
+        integration_id: IntegrationId,
+        provider: IMProvider,
+        provider_user_id: str,
+        display_name: str | None,
+        email: str | None,
+        raw_payload: Mapping[str, JsonValue],
+        last_seen_sync_run_id: IMSyncRunId | None,
+        last_seen_at: UtcTimestamp | None,
+        now: UtcTimestamp,
+        created_at: UtcTimestamp | None = None,
+    ) -> IMIdentity:
+        clean_name = display_name.strip() if display_name is not None else None
+        clean_email = email.strip() if email is not None else None
+        return cls(
+            id=identity_id,
+            integration_id=integration_id,
+            provider=provider,
+            provider_user_id=provider_user_id.strip(),
+            display_name=clean_name,
+            normalized_name=clean_name.casefold() if clean_name else None,
+            email=clean_email,
+            normalized_email=NormalizedEmail(clean_email) if clean_email else None,
+            raw_payload=OpaqueProviderPayload.from_mapping(raw_payload),
+            last_seen_sync_run_id=last_seen_sync_run_id,
+            last_seen_at=last_seen_at,
+            created_at=created_at or now,
+            updated_at=now,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class IMBinding:
+    """Current Contact-to-provider identity association in one resolution scope."""
+
+    id: IMBindingId
+    integration_id: IntegrationId
+    scope: IMBindingScope
+    scope_id: str
+    contact_id: ContactId
+    identity_id: IMIdentityId
+    provider: IMProvider
+    bound_by_account_id: AccountId | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    def __post_init__(self) -> None:
+        if not self.scope_id.strip():
+            raise ValueError("binding scope id must not be blank")
+        if self.scope is IMBindingScope.ORGANIZATION and self.scope_id != str(self.integration_id):
+            raise ValueError("organization binding scope must be its integration")
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        binding_id: IMBindingId,
+        integration_id: IntegrationId,
+        scope: IMBindingScope,
+        scope_id: str,
+        contact_id: ContactId,
+        identity_id: IMIdentityId,
+        provider: IMProvider,
+        bound_by_account_id: AccountId | None,
+        now: UtcTimestamp,
+        created_at: UtcTimestamp | None = None,
+    ) -> IMBinding:
+        return cls(
+            id=binding_id,
+            integration_id=integration_id,
+            scope=scope,
+            scope_id=scope_id,
+            contact_id=contact_id,
+            identity_id=identity_id,
+            provider=provider,
+            bound_by_account_id=bound_by_account_id,
+            created_at=created_at or now,
+            updated_at=now,
+        )
@@ -0,0 +1,18 @@
+"""Explicit aggregate-load snapshot spanning IM persistence records."""
+
+from dataclasses import dataclass
+
+from .integration import IMIntegration
+from .records import IMBinding, IMIdentity
+from .sync_reconciliation import IMSyncRun, SyncResultFact
+
+
+@dataclass(frozen=True, slots=True)
+class IMIntegrationState:
+    """Eagerly loaded Integration with mapped current and historical children."""
+
+    integration: IMIntegration
+    identities: tuple[IMIdentity, ...]
+    bindings: tuple[IMBinding, ...]
+    sync_runs: tuple[IMSyncRun, ...]
+    sync_results: tuple[SyncResultFact, ...]
@@ -0,0 +1,276 @@
+"""Pure provider directory matching and immutable reconciliation plans."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from enum import StrEnum
+
+from pydantic import JsonValue
+
+from core.human_input_v2.contact_directory import ContactIdentitySource, ContactSnapshot
+from core.human_input_v2.entities import IMProvider, IMSyncRemovalReason, IMSyncResultType, IMSyncRunStatus
+from core.human_input_v2.shared import (
+    AccountId,
+    ContactId,
+    IMBindingId,
+    IMIdentityId,
+    IMSyncResultId,
+    IMSyncRunId,
+    IntegrationId,
+    NormalizedEmail,
+    UtcTimestamp,
+)
+
+from .integration import IntegrationRevisionToken
+from .records import IMBinding, IMIdentity, OpaqueProviderPayload
+
+
+class MatchKind(StrEnum):
+    """Stable explanation for how one provider entry was classified."""
+
+    PROVIDER_USER_ID = "provider_user_id"
+    NORMALIZED_EMAIL = "normalized_email"
+    UNMATCHED = "unmatched"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDirectoryEntry:
+    """Provider-neutral directory values consumed by the pure reconciler."""
+
+    provider_user_id: str
+    display_name: str | None
+    email: str | None
+    normalized_email: NormalizedEmail | None
+    raw_payload: OpaqueProviderPayload
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        provider_user_id: str,
+        display_name: str | None,
+        email: str | None,
+        raw_payload: dict[str, JsonValue],
+    ) -> ProviderDirectoryEntry:
+        clean_email = email.strip() if email is not None else None
+        return cls(
+            provider_user_id=provider_user_id.strip(),
+            display_name=display_name.strip() if display_name is not None else None,
+            email=clean_email,
+            normalized_email=NormalizedEmail(clean_email) if clean_email else None,
+            raw_payload=OpaqueProviderPayload.from_mapping(raw_payload),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ReconciliationSnapshot:
+    """Coherent current facts loaded before provider entries are matched."""
+
+    identities: tuple[IMIdentity, ...] = ()
+    bindings: tuple[IMBinding, ...] = ()
+    contacts: tuple[ContactSnapshot, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ReconciliationAction:
+    """One provider entry match without persistence side effects."""
+
+    entry: ProviderDirectoryEntry
+    match_kind: MatchKind
+    identity_id: IMIdentityId | None
+    binding_id: IMBindingId | None
+    contact_id: ContactId | None
+
+
+@dataclass(frozen=True, slots=True)
+class ReconciliationPlan:
+    """Immutable plan whose captured revision must be checked again at apply."""
+
+    sync_run_id: IMSyncRunId
+    integration_revision: IntegrationRevisionToken
+    provider: IMProvider
+    actions: tuple[ReconciliationAction, ...]
+    removed_identity_ids: tuple[IMIdentityId, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SyncResultFact:
+    """Append-only outcome for one action, removed binding, or diagnostic.
+
+    Removing an identity emits one fact per removed binding so every scope
+    override remains auditable. An identity without bindings emits one fact
+    whose binding and Contact fields are absent.
+    """
+
+    id: IMSyncResultId
+    integration_id: IntegrationId
+    sync_run_id: IMSyncRunId
+    result_type: IMSyncResultType
+    provider_user_id: str | None
+    display_name: str | None
+    email: str | None
+    normalized_email: NormalizedEmail | None
+    contact_id: ContactId | None
+    identity_id: IMIdentityId | None
+    binding_id: IMBindingId | None
+    removal_reason: IMSyncRemovalReason | None
+    reason_code: str | None
+    reason_message: str | None
+    directory_entry_payload: OpaqueProviderPayload | None
+    contact_snapshot: SyncContactSnapshot | None
+    identity_snapshot: SyncIdentitySnapshot | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+
+@dataclass(frozen=True, slots=True)
+class SyncContactSnapshot:
+    """Immutable Contact display values retained by a historical result."""
+
+    contact_id: ContactId
+    name: str
+    email: str | None
+    avatar_file_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class SyncIdentitySnapshot:
+    """Immutable last-known provider identity retained after current deletion."""
+
+    identity_id: IMIdentityId
+    provider: IMProvider
+    provider_user_id: str
+    display_name: str | None
+    email: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class IMSyncRun:
+    """Independent sync aggregate that captures one complete Integration token."""
+
+    id: IMSyncRunId
+    integration_revision: IntegrationRevisionToken
+    provider: IMProvider
+    status: IMSyncRunStatus
+    added_count: int
+    not_matched_count: int
+    failed_count: int
+    removed_count: int
+    skipped_count: int
+    started_by_account_id: AccountId | None
+    started_at: UtcTimestamp | None
+    finished_at: UtcTimestamp | None
+    error_code: str | None
+    error_message: str | None
+    created_at: UtcTimestamp
+    updated_at: UtcTimestamp
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        sync_run_id: IMSyncRunId,
+        integration_revision: IntegrationRevisionToken,
+        provider: IMProvider,
+        started_by_account_id: AccountId | None,
+        now: UtcTimestamp,
+    ) -> IMSyncRun:
+        return cls(
+            id=sync_run_id,
+            integration_revision=integration_revision,
+            provider=provider,
+            status=IMSyncRunStatus.QUEUED,
+            added_count=0,
+            not_matched_count=0,
+            failed_count=0,
+            removed_count=0,
+            skipped_count=0,
+            started_by_account_id=started_by_account_id,
+            started_at=None,
+            finished_at=None,
+            error_code=None,
+            error_message=None,
+            created_at=now,
+            updated_at=now,
+        )
+
+    @property
+    def is_active(self) -> bool:
+        return self.status in (IMSyncRunStatus.QUEUED, IMSyncRunStatus.RUNNING)
+
+    def start(self, now: UtcTimestamp) -> IMSyncRun:
+        if self.status is not IMSyncRunStatus.QUEUED:
+            return self
+        return replace(self, status=IMSyncRunStatus.RUNNING, started_at=now, updated_at=now)
+
+
+class SyncReconciler:
+    """Stateless matching policy with no provider or persistence dependencies.
+
+    Email fallback accepts available account-backed Contacts: EE Organization
+    Accounts and CE/SaaS workspace members. External Contacts never participate.
+    """
+
+    @staticmethod
+    def reconcile(
+        *,
+        sync_run_id: IMSyncRunId,
+        integration_revision: IntegrationRevisionToken,
+        provider: IMProvider,
+        entries: tuple[ProviderDirectoryEntry, ...],
+        snapshot: ReconciliationSnapshot,
+    ) -> ReconciliationPlan:
+        identities = {
+            identity.provider_user_id: identity
+            for identity in snapshot.identities
+            if identity.integration_id == integration_revision.integration_id and identity.provider is provider
+        }
+        bindings_by_identity: dict[IMIdentityId, IMBinding] = {}
+        for binding in sorted(snapshot.bindings, key=lambda item: item.scope.value, reverse=True):
+            bindings_by_identity.setdefault(binding.identity_id, binding)
+        contacts_by_email = {
+            item.contact.normalized_email: item.contact
+            for item in snapshot.contacts
+            if item.account_available
+            and item.contact.identity_source
+            in (ContactIdentitySource.ORGANIZATION_ACCOUNT, ContactIdentitySource.WORKSPACE_MEMBER)
+            and item.contact.normalized_email is not None
+        }
+
+        actions: list[ReconciliationAction] = []
+        seen_provider_user_ids: set[str] = set()
+        for entry in entries:
+            seen_provider_user_ids.add(entry.provider_user_id)
+            identity = identities.get(entry.provider_user_id)
+            if identity is not None:
+                matched_binding = bindings_by_identity.get(identity.id)
+                actions.append(
+                    ReconciliationAction(
+                        entry=entry,
+                        match_kind=MatchKind.PROVIDER_USER_ID,
+                        identity_id=identity.id,
+                        binding_id=matched_binding.id if matched_binding is not None else None,
+                        contact_id=matched_binding.contact_id if matched_binding is not None else None,
+                    )
+                )
+                continue
+
+            contact = contacts_by_email.get(entry.normalized_email) if entry.normalized_email is not None else None
+            actions.append(
+                ReconciliationAction(
+                    entry=entry,
+                    match_kind=MatchKind.NORMALIZED_EMAIL if contact is not None else MatchKind.UNMATCHED,
+                    identity_id=None,
+                    binding_id=None,
+                    contact_id=contact.id if contact is not None else None,
+                )
+            )
+
+        removed = tuple(
+            identity.id
+            for identity in snapshot.identities
+            if identity.integration_id == integration_revision.integration_id
+            and identity.provider is provider
+            and identity.provider_user_id not in seen_provider_user_ids
+        )
+        return ReconciliationPlan(sync_run_id, integration_revision, provider, tuple(actions), removed)
@@ -0,0 +1,63 @@
+"""Stable Human Input v2 values shared across domain contexts.
+
+This package contains infrastructure-free values only. Feature-specific ownership
+and lifecycle rules belong to their bounded context rather than this package.
+"""
+
+from .values import (
+    AccountId,
+    AppId,
+    ApproverGrantId,
+    AuditEventId,
+    ContactId,
+    DeliveryAttemptId,
+    DeliveryEndpointId,
+    DeploymentScope,
+    DirectoryScope,
+    EmailProviderId,
+    EndUserId,
+    FormId,
+    IMBindingId,
+    IMIdentityId,
+    IMSyncResultId,
+    IMSyncRunId,
+    IntegrationId,
+    NormalizedEmail,
+    OTPChallengeId,
+    PlatformEntryId,
+    SubmissionId,
+    UploadCapabilityId,
+    UploadFileAssociationId,
+    UtcTimestamp,
+    WorkspaceId,
+    WorkspaceScope,
+)
+
+__all__ = [
+    "AccountId",
+    "AppId",
+    "ApproverGrantId",
+    "AuditEventId",
+    "ContactId",
+    "DeliveryAttemptId",
+    "DeliveryEndpointId",
+    "DeploymentScope",
+    "DirectoryScope",
+    "EmailProviderId",
+    "EndUserId",
+    "FormId",
+    "IMBindingId",
+    "IMIdentityId",
+    "IMSyncResultId",
+    "IMSyncRunId",
+    "IntegrationId",
+    "NormalizedEmail",
+    "OTPChallengeId",
+    "PlatformEntryId",
+    "SubmissionId",
+    "UploadCapabilityId",
+    "UploadFileAssociationId",
+    "UtcTimestamp",
+    "WorkspaceId",
+    "WorkspaceScope",
+]
@@ -0,0 +1,173 @@
+"""Primitive-independent identifiers, scopes, email, and time values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import override
+
+
+@dataclass(frozen=True, slots=True)
+class _Identifier:
+    """Non-empty string identifier with explicit primitive serialization."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.value, str) or not self.value.strip():
+            raise ValueError(f"{type(self).__name__} must not be blank")
+        object.__setattr__(self, "value", self.value.strip())
+
+    @override
+    def __str__(self) -> str:
+        return self.value
+
+    def to_primitive(self) -> str:
+        return self.value
+
+
+class AccountId(_Identifier):
+    """Identifier of an Account record."""
+
+
+class ContactId(_Identifier):
+    """Identifier of a canonical Contact."""
+
+
+class EndUserId(_Identifier):
+    """Identifier of one app-scoped EndUser identity."""
+
+
+class PlatformEntryId(_Identifier):
+    """Identifier of one Platform allow-list entry."""
+
+
+class WorkspaceId(_Identifier):
+    """Identifier of the workspace that owns or resolves a Contact."""
+
+
+class AppId(_Identifier):
+    """Identifier of the application that owns a Human Input form."""
+
+
+class FormId(_Identifier):
+    """Identifier of one Human Input v2 form root."""
+
+
+class ApproverGrantId(_Identifier):
+    """Identifier of one form-scoped approver grant."""
+
+
+class OTPChallengeId(_Identifier):
+    """Identifier of one grant-scoped OTP proof session."""
+
+
+class DeliveryEndpointId(_Identifier):
+    """Identifier of one frozen form delivery endpoint."""
+
+
+class DeliveryAttemptId(_Identifier):
+    """Identifier of one append-only delivery attempt."""
+
+
+class SubmissionId(_Identifier):
+    """Identifier of one immutable winning form submission."""
+
+
+class AuditEventId(_Identifier):
+    """Identifier of one append-only Human Input audit event."""
+
+
+class EmailProviderId(_Identifier):
+    """Identifier of one workspace email provider configuration."""
+
+
+class UploadCapabilityId(_Identifier):
+    """Identifier of one endpoint-scoped upload capability."""
+
+
+class UploadFileAssociationId(_Identifier):
+    """Identifier of one durable uploaded-file association."""
+
+
+class IntegrationId(_Identifier):
+    """Identifier of one IM Integration configuration identity."""
+
+
+class IMIdentityId(_Identifier):
+    """Identifier of one current synchronized provider identity."""
+
+
+class IMBindingId(_Identifier):
+    """Identifier of one current Contact-to-IM-identity binding."""
+
+
+class IMSyncRunId(_Identifier):
+    """Identifier of one IM directory synchronization run."""
+
+
+class IMSyncResultId(_Identifier):
+    """Identifier of one append-only synchronization result fact."""
+
+
+@dataclass(frozen=True, slots=True)
+class NormalizedEmail:
+    """Case-insensitive canonical email used for identity comparisons."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.value, str):
+            raise ValueError("value must be a valid email")
+        normalized = self.value.strip().casefold()
+        local, separator, domain = normalized.partition("@")
+        if not separator or not local or not domain or " " in normalized or "@" in domain:
+            raise ValueError("value must be a valid email")
+        object.__setattr__(self, "value", normalized)
+
+    @override
+    def __str__(self) -> str:
+        return self.value
+
+    def to_primitive(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class DeploymentScope:
+    """Deployment-wide owner scope used by EE Organization contacts."""
+
+    def to_primitive(self) -> dict[str, str]:
+        return {"kind": "deployment"}
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceScope:
+    """Owner scope for workspace-owned contacts and directory operations."""
+
+    workspace_id: WorkspaceId
+
+    def to_primitive(self) -> dict[str, str]:
+        return {"kind": "workspace", "workspace_id": self.workspace_id.to_primitive()}
+
+
+type DirectoryScope = DeploymentScope | WorkspaceScope
+
+
+@dataclass(frozen=True, slots=True)
+class UtcTimestamp:
+    """Timezone-aware timestamp normalized to UTC at construction."""
+
+    value: datetime
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.value, datetime) or self.value.tzinfo is None or self.value.utcoffset() is None:
+            raise ValueError("value must be a timezone-aware datetime")
+        object.__setattr__(self, "value", self.value.astimezone(UTC))
+
+    @classmethod
+    def now(cls) -> UtcTimestamp:
+        return cls(datetime.now(UTC))
+
+    def to_primitive(self) -> str:
+        return self.value.isoformat().replace("+00:00", "Z")
@@ -519,7 +519,7 @@ class IndexingRunner:
    def filter_string(text):
        text = re.sub(r"<\|", "<", text)
        text = re.sub(r"\|>", ">", text)
-        text = re.sub(r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\xEF\xBF\xBE]", "", text)
+        text = re.sub(r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]", "", text)
        # Unicode  U+FFFE
        text = re.sub("\ufffe", "", text)
        return text
@@ -9,7 +9,7 @@ class CleanProcessor:
        # remove invalid symbol
        text = re.sub(r"<\|", "<", text)
        text = re.sub(r"\|>", ">", text)
-        text = re.sub(r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\xEF\xBF\xBE]", "", text)
+        text = re.sub(r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]", "", text)
        # Unicode  U+FFFE
        text = re.sub("\ufffe", "", text)

@@ -2023,6 +2023,8 @@ class DatasetRetrieval:
            redis_client.zremrangebyscore(key, 0, current_time - 60000)
            request_count = redis_client.zcard(key)
            if request_count > knowledge_rate_limit.limit:
+                # The rate-limit exception is raised after this block, so commit the audit row
+                # explicitly instead of relying on the Session context, which only closes it.
                with session_factory.create_session() as session:
                    rate_limit_log = RateLimitLog(
                        tenant_id=tenant_id,
@@ -2030,6 +2032,7 @@ class DatasetRetrieval:
                        operation="knowledge",
                    )
                    session.add(rate_limit_log)
+                    session.commit()
                raise exc.RateLimitExceededError(
                    "you have reached the knowledge base request rate limit of your subscription."
                )
@@ -91,8 +91,8 @@ class FixedRecursiveCharacterTextSplitter(EnhanceRecursiveCharacterTextSplitter)
                splits = re.split(r" +", text)
            else:
                splits = text.split(separator)
-                if self._keep_separator:
-                    splits = [s + separator for s in splits[:-1]] + splits[-1:]
+            if self._keep_separator:
+                splits = [s + separator for s in splits[:-1]] + splits[-1:]
        else:
            splits = list(text)
        if separator == "\n":
@@ -14,6 +14,10 @@ from core.workflow.human_input_adapter import (
    EmailDeliveryMethod,
    EmailRecipients,
    ExternalRecipient,
+    InstantMessageChannelRecipient,
+    InstantMessageDeliveryConfig,
+    InstantMessageDeliveryMethod,
+    InstantMessageUserRecipient,
    InteractiveSurfaceDeliveryMethod,
    is_human_input_webapp_enabled,
 )
@@ -32,6 +36,7 @@ from models.human_input import (
    HumanInputDelivery,
    HumanInputForm,
    HumanInputFormRecipient,
+    InstantMessageRecipientPayload,
    RecipientType,
    StandaloneWebAppRecipientPayload,
 )
@@ -323,9 +328,48 @@ class HumanInputFormRepositoryImpl:
                        recipients_config=email_recipients_config,
                    )
                )
+            case InstantMessageDeliveryMethod():
+                recipients.extend(
+                    self._build_instant_message_recipients(
+                        form_id=form_id,
+                        delivery_id=delivery_id,
+                        config=delivery_method.config,
+                    )
+                )

        return _DeliveryAndRecipients(delivery=delivery_model, recipients=recipients)

+    @staticmethod
+    def _build_instant_message_recipients(
+        *,
+        form_id: str,
+        delivery_id: str,
+        config: InstantMessageDeliveryConfig,
+    ) -> list[HumanInputFormRecipient]:
+        recipient_models: list[HumanInputFormRecipient] = []
+        for recipient in config.recipients.items:
+            match recipient:
+                case InstantMessageChannelRecipient():
+                    payload = InstantMessageRecipientPayload(
+                        provider=config.provider,
+                        recipient_kind=recipient.type,
+                        channel_id=recipient.channel_id,
+                    )
+                case InstantMessageUserRecipient():
+                    payload = InstantMessageRecipientPayload(
+                        provider=config.provider,
+                        recipient_kind=recipient.type,
+                        user_id=recipient.user_id,
+                    )
+            recipient_models.append(
+                HumanInputFormRecipient.new(
+                    form_id=form_id,
+                    delivery_id=delivery_id,
+                    payload=payload,
+                )
+            )
+        return recipient_models
+
    def _build_email_recipients(
        self,
        session: Session,
@@ -5,6 +5,8 @@ Dify-owned field spellings and value shapes. Adapt them here before handing the
 payload to Graphon so Graphon-owned models only see current contracts.
 """

+# TODO(QuantumGhost): This should be migrated back to human_input.HumanInputNodeData.
+
 from __future__ import annotations

 import enum
@@ -26,6 +28,7 @@ from graphon.variables.consts import SELECTORS_LENGTH
 class DeliveryMethodType(enum.StrEnum):
    WEBAPP = enum.auto()
    EMAIL = enum.auto()
+    IM = enum.auto()


 class EmailRecipientType(enum.StrEnum):
@@ -34,6 +37,17 @@ class EmailRecipientType(enum.StrEnum):
    EXTERNAL = "external"


+class InstantMessageProvider(enum.StrEnum):
+    SLACK = "slack"
+    TEAMS = "teams"
+    DISCORD = "discord"
+
+
+class InstantMessageRecipientType(enum.StrEnum):
+    CHANNEL = "channel"
+    USER = "user"
+
+
 class _InteractiveSurfaceDeliveryConfig(BaseModel):
    pass

@@ -56,6 +70,25 @@ MemberRecipient = BoundRecipient
 EmailRecipient = Annotated[BoundRecipient | ExternalRecipient, Field(discriminator="type")]


+class InstantMessageChannelRecipient(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal[InstantMessageRecipientType.CHANNEL] = InstantMessageRecipientType.CHANNEL
+    channel_id: str
+
+
+class InstantMessageUserRecipient(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal[InstantMessageRecipientType.USER] = InstantMessageRecipientType.USER
+    user_id: str
+
+
+InstantMessageRecipient = Annotated[
+    InstantMessageChannelRecipient | InstantMessageUserRecipient, Field(discriminator="type")
+]
+
+
 class EmailRecipients(BaseModel):
    model_config = ConfigDict(extra="forbid")

@@ -66,6 +99,12 @@ class EmailRecipients(BaseModel):
    items: list[EmailRecipient] = Field(default_factory=list)


+class InstantMessageRecipients(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    items: list[InstantMessageRecipient] = Field(default_factory=list)
+
+
 class EmailDeliveryConfig(BaseModel):
    URL_PLACEHOLDER: ClassVar[str] = "{{#url#}}"
    _ALLOWED_HTML_TAGS: ClassVar[list[str]] = [
@@ -141,6 +180,14 @@ class EmailDeliveryConfig(BaseModel):
        return " ".join(sanitized.split())


+class InstantMessageDeliveryConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    provider: InstantMessageProvider
+    recipients: InstantMessageRecipients = Field(default_factory=InstantMessageRecipients)
+    message: str | None = None
+
+
 class _DeliveryMethodBase(BaseModel):
    enabled: bool = True
    id: uuid.UUID = Field(default_factory=uuid.uuid4)
@@ -170,10 +217,31 @@ class EmailDeliveryMethod(_DeliveryMethodBase):
        return selectors


+class InstantMessageDeliveryMethod(_DeliveryMethodBase):
+    type: Literal[DeliveryMethodType.IM] = DeliveryMethodType.IM
+    config: InstantMessageDeliveryConfig
+
+    @override
+    def extract_variable_selectors(self) -> Sequence[Sequence[str]]:
+        if not self.config.message:
+            return ()
+        variable_template_parser = VariableTemplateParser(template=self.config.message)
+        selectors: list[Sequence[str]] = []
+        for variable_selector in variable_template_parser.extract_variable_selectors():
+            value_selector = list(variable_selector.value_selector)
+            if len(value_selector) < SELECTORS_LENGTH:
+                continue
+            selectors.append(value_selector[:SELECTORS_LENGTH])
+        return selectors
+
+
 WebAppDeliveryMethod = InteractiveSurfaceDeliveryMethod
 _WebAppDeliveryConfig = _InteractiveSurfaceDeliveryConfig

-DeliveryChannelConfig = Annotated[InteractiveSurfaceDeliveryMethod | EmailDeliveryMethod, Field(discriminator="type")]
+DeliveryChannelConfig = Annotated[
+    InteractiveSurfaceDeliveryMethod | EmailDeliveryMethod | InstantMessageDeliveryMethod,
+    Field(discriminator="type"),
+]

 _DELIVERY_METHODS_ADAPTER = TypeAdapter(list[DeliveryChannelConfig])

@@ -204,9 +272,10 @@ def adapt_human_input_node_data_for_graph(node_data: Mapping[str, Any] | BaseMod

        config_mapping = _copy_mapping(method_mapping.get("config"))
        if config_mapping is not None:
-            recipients_mapping = _copy_mapping(config_mapping.get("recipients"))
-            if recipients_mapping is not None:
-                config_mapping["recipients"] = _normalize_email_recipients(recipients_mapping)
+            if method_mapping.get("type") == DeliveryMethodType.EMAIL:
+                recipients_mapping = _copy_mapping(config_mapping.get("recipients"))
+                if recipients_mapping is not None:
+                    config_mapping["recipients"] = _normalize_email_recipients(recipients_mapping)
            method_mapping["config"] = config_mapping

        normalized_methods.append(method_mapping)
@@ -377,6 +446,13 @@ __all__ = [
    "EmailRecipientType",
    "EmailRecipients",
    "ExternalRecipient",
+    "InstantMessageChannelRecipient",
+    "InstantMessageDeliveryConfig",
+    "InstantMessageDeliveryMethod",
+    "InstantMessageProvider",
+    "InstantMessageRecipientType",
+    "InstantMessageRecipients",
+    "InstantMessageUserRecipient",
    "MemberRecipient",
    "WebAppDeliveryMethod",
    "_WebAppDeliveryConfig",
@@ -497,6 +497,7 @@ class DifyNodeFactory(NodeFactory):
                ),
                "agent_backend_client": create_agent_backend_run_client(
                    base_url=dify_config.AGENT_BACKEND_BASE_URL,
+                    api_token=dify_config.AGENT_BACKEND_API_TOKEN,
                    use_fake=dify_config.AGENT_BACKEND_USE_FAKE,
                    fake_scenario=dify_config.AGENT_BACKEND_FAKE_SCENARIO,
                    stream_read_timeout_seconds=dify_config.AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS,
@@ -13,6 +13,7 @@ from typing import Annotated, Any, Literal, Self, assert_never, override

 from pydantic import BaseModel, Field, NonNegativeInt, field_validator, model_validator

+from core.workflow.human_input_adapter import DeliveryChannelConfig
 from graphon.entities.base_node_data import BaseNodeData
 from graphon.enums import BuiltinNodeTypes, NodeType
 from graphon.file.enums import FileTransferMethod, FileType
@@ -372,3 +373,10 @@ def validate_human_input_submission(
        missing_list = ", ".join(missing_inputs)
        msg = f"Missing required inputs: {missing_list}"
        raise HumanInputSubmissionValidationError(msg)
+
+
+class HumanInputNodeDataFull(HumanInputNodeData):
+    # This model is the full definition of HumanInputNodeData.
+    #
+    # The model above lacks some fields due to migration between Graphon and Dify. This model add them back.
+    delivery_methods: list[DeliveryChannelConfig] = Field(default_factory=list[DeliveryChannelConfig])
@@ -0,0 +1,91 @@
+import enum
+from collections.abc import Sequence
+from typing import Annotated, Final, Literal
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Discriminator, Field
+
+from core.human_input_v2.entities import IMProvider
+from core.workflow.nodes.human_input.entities import FormInputConfig, TimeoutUnit, UserActionConfig
+from graphon.entities.base_node_data import BaseNodeData
+from graphon.enums import BuiltinNodeTypes, NodeType
+
+
+class RecipientType(enum.StrEnum):
+    CONTACT = enum.auto()
+    DYNAMIC_EMAIL = enum.auto()
+    ONETIME_EMAIL = enum.auto()
+    INITIATOR = enum.auto()
+
+
+class Contact(BaseModel):
+    type: Literal[RecipientType.CONTACT] = RecipientType.CONTACT
+
+    contact_id: str
+
+
+class DynamicEmail(BaseModel):
+    type: Literal[RecipientType.DYNAMIC_EMAIL] = RecipientType.DYNAMIC_EMAIL
+
+    selector: Sequence[str]
+
+
+class OnetimeEmail(BaseModel):
+    type: Literal[RecipientType.ONETIME_EMAIL] = RecipientType.ONETIME_EMAIL
+
+    email: str
+
+
+class Initiator(BaseModel):
+    type: Literal[RecipientType.INITIATOR] = RecipientType.INITIATOR
+
+
+RecipientConfig = Annotated[Contact | DynamicEmail | OnetimeEmail | Initiator, Discriminator("type")]
+
+
+class MessageTemplateConfig(BaseModel):
+    subject: str
+    body: str
+
+
+class Channel(enum.StrEnum):
+    EMAIL = enum.auto()
+    FEISHU = IMProvider.FEISHU.value
+    SLACK = IMProvider.SLACK.value
+    DING_TALK = IMProvider.DING_TALK.value
+    MS_TEAMS = IMProvider.MS_TEAMS.value
+    WE_COM = IMProvider.WE_COM.value
+    LARK = IMProvider.LARK.value
+
+
+class DebugModeConfig(BaseModel):
+    enabled: bool = False
+    channels: Sequence[Channel]
+
+
+HUMAN_INPUT_V2_VERSION: Final = "2"
+
+
+def _version_validator(version: str) -> str:
+    if version != HUMAN_INPUT_V2_VERSION:
+        raise ValueError(f"Human Input v2 requires version='{HUMAN_INPUT_V2_VERSION}'")
+    return version
+
+
+class HumanInputNodeData(BaseNodeData):
+    """Human Input node data."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True, validate_default=True)
+
+    type: NodeType = BuiltinNodeTypes.HUMAN_INPUT
+    version: Annotated[str, AfterValidator(_version_validator)] = HUMAN_INPUT_V2_VERSION
+
+    recipients_spec: list[RecipientConfig]
+
+    message_template: MessageTemplateConfig
+    debug_mode: DebugModeConfig
+
+    form_content: str = ""
+    inputs: list[FormInputConfig] = Field(default_factory=list[FormInputConfig])
+    user_actions: list[UserActionConfig] = Field(default_factory=list[UserActionConfig])
+    timeout: int = 36
+    timeout_unit: TimeoutUnit = TimeoutUnit.HOUR
@@ -5,6 +5,7 @@ from typing import Any
 import pytz  # type: ignore[import-untyped]
 from celery import Celery, Task
 from celery.schedules import crontab
+from celery.signals import beat_init
 from typing_extensions import TypedDict

 from configs import dify_config
@@ -36,6 +37,19 @@ class CeleryBeatScheduleEntry(TypedDict):
    schedule: crontab | timedelta


+def _enqueue_initial_community_telemetry_heartbeat(sender: Any, **_: Any) -> None:
+    task_name = "community_telemetry.send_heartbeat"
+    if "community_telemetry_heartbeat" not in sender.app.conf.beat_schedule:
+        return
+
+    task = sender.app.tasks.get(task_name)
+    if task is not None:
+        task.apply_async()
+
+
+beat_init.connect(_enqueue_initial_community_telemetry_heartbeat, weak=False)
+
+
 def get_celery_ssl_options() -> CelerySSLOptionsDict | None:
    """Get SSL configuration for Celery broker/backend connections."""
    # Only apply SSL if we're using Redis as broker/backend
@@ -260,6 +274,19 @@ def init_app(app: DifyApp) -> Celery:
            "schedule": timedelta(minutes=dify_config.API_TOKEN_LAST_USED_UPDATE_INTERVAL),
        }

+    if (
+        dify_config.EDITION == "SELF_HOSTED"
+        and not dify_config.ENTERPRISE_ENABLED
+        and not dify_config.DISABLE_TELEMETRY
+        and not dify_config.DO_NOT_TRACK
+        and not dify_config.CI
+    ):
+        imports.append("tasks.community_telemetry_task")
+        beat_schedule["community_telemetry_heartbeat"] = {
+            "task": "community_telemetry.send_heartbeat",
+            "schedule": timedelta(minutes=dify_config.TELEMETRY_HEARTBEAT_INTERVAL_MINUTES),
+        }
+
    if dify_config.ENTERPRISE_ENABLED and dify_config.ENTERPRISE_TELEMETRY_ENABLED:
        imports.append("tasks.enterprise_telemetry_task")
    celery_app.conf.update(beat_schedule=beat_schedule, imports=imports)
@@ -383,6 +383,7 @@ class AgentAppComposerResponse(ResponseModel):
    variant: Literal[ComposerVariant.AGENT_APP]
    agent: AgentComposerAgentResponse
    active_config_snapshot: AgentConfigSnapshotSummaryResponse | None = None
+    active_config_is_published: bool
    draft: AgentConfigDraftSummaryResponse | None = None
    agent_soul: AgentSoulConfig
    save_options: list[ComposerSaveStrategy]
@@ -0,0 +1,12 @@
+from pydantic import Field, PositiveInt
+
+
+class PaginationParamsMixin:
+    page: PositiveInt = Field(1, description="1-based page number.")
+    limit: PositiveInt = Field(default=20, le=100, description="Maximum number of records returned per page.")
+
+
+class PaginationResultMixin:
+    limit: int = Field(description="Page size used for the current query.")
+    total: int = Field(description="Total number of candidates matching the current query.")
+    page: int = Field(description="Current 1-based page number.")
@@ -0,0 +1,5 @@
+from typing import Annotated
+
+from pydantic import Field
+
+Timestamp = Annotated[int, Field(..., description="Unix timestamp in milliseconds")]
@@ -0,0 +1,30 @@
+"""add telemetry fields to dify_setups
+
+Revision ID: 6f5a9c2d8e1b
+Revises: d2825e7b9c10
+Create Date: 2026-07-23 12:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "6f5a9c2d8e1b"
+down_revision = "d2825e7b9c10"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    with op.batch_alter_table("dify_setups", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("instance_id", sa.String(length=255), nullable=True))
+        batch_op.add_column(sa.Column("install_reported_at", sa.DateTime(), nullable=True))
+        batch_op.add_column(sa.Column("last_heartbeat_at", sa.DateTime(), nullable=True))
+
+
+def downgrade():
+    with op.batch_alter_table("dify_setups", schema=None) as batch_op:
+        batch_op.drop_column("last_heartbeat_at")
+        batch_op.drop_column("install_reported_at")
+        batch_op.drop_column("instance_id")
@@ -0,0 +1,141 @@
+"""add human input v2 contact directory
+
+Revision ID: 5c8f1a2b3d4e
+Revises: d2825e7b9c10
+Create Date: 2026-07-25 10:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+import models
+
+# revision identifiers, used by Alembic.
+revision = "5c8f1a2b3d4e"
+down_revision = "d2825e7b9c10"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "human_input_contacts",
+        sa.Column("name", sa.String(length=255), nullable=False, comment="Display name shown in contact surfaces."),
+        sa.Column(
+            "normalized_name",
+            sa.String(length=255),
+            nullable=False,
+            comment="Lower-cased search value maintained by the application.",
+        ),
+        sa.Column(
+            "identity_source",
+            sa.String(length=20),
+            nullable=False,
+            comment="Immutable identity source that determines the Contact lifecycle owner.",
+        ),
+        sa.Column(
+            "tenant_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment=(
+                "Ownership boundary: null only for EE Organization contacts; otherwise the owning tenants.id for "
+                "workspace-owned contacts. CE and SaaS must never persist a null value."
+            ),
+        ),
+        sa.Column(
+            "account_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to accounts.id for an account-backed contact.",
+        ),
+        sa.Column(
+            "email",
+            sa.String(length=320),
+            nullable=True,
+            comment="Current deliverable email address, when available.",
+        ),
+        sa.Column(
+            "normalized_email",
+            sa.String(length=320),
+            nullable=True,
+            comment="Full lower-cased email used for equality matching.",
+        ),
+        sa.Column(
+            "avatar_file_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to upload_files.id for an external contact avatar.",
+        ),
+        sa.Column("id", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name="human_input_contacts_pkey"),
+        sa.UniqueConstraint("tenant_id", "account_id", name="human_input_contacts_tenant_account_uq"),
+        sa.UniqueConstraint("tenant_id", "normalized_email", name="human_input_contacts_tenant_email_uq"),
+        sa.CheckConstraint(
+            "(identity_source = 'organization_account' AND tenant_id IS NULL AND account_id IS NOT NULL) OR "
+            "(identity_source = 'workspace_member' AND tenant_id IS NOT NULL AND account_id IS NOT NULL) OR "
+            "(identity_source = 'external' AND tenant_id IS NOT NULL AND account_id IS NULL)",
+            name="identity_owner",
+        ),
+        sa.CheckConstraint(
+            "identity_source <> 'external' OR (email IS NOT NULL AND normalized_email IS NOT NULL)",
+            name="external_email",
+        ),
+        sa.CheckConstraint(
+            "(email IS NULL AND normalized_email IS NULL) OR (email IS NOT NULL AND normalized_email IS NOT NULL)",
+            name="email_normalization_pair",
+        ),
+        comment=(
+            "Canonical Human Input contact identities. EE Organization Account contacts have tenant_id IS NULL; "
+            "workspace-owned contacts have tenant_id = tenants.id; CE and SaaS must not create contacts with "
+            "tenant_id IS NULL."
+        ),
+    )
+    op.create_index(
+        "human_input_contacts_tenant_normalized_name_idx",
+        "human_input_contacts",
+        ["tenant_id", "normalized_name"],
+    )
+
+    op.create_table(
+        "human_input_platform_contact_workspace_entries",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column(
+            "contact_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to human_input_contacts.id.",
+        ),
+        sa.Column(
+            "added_by_account_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to accounts.id for the administrator who added this directory entry.",
+        ),
+        sa.Column("id", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name="human_input_platform_contact_workspace_entries_pkey"),
+        sa.UniqueConstraint("tenant_id", "contact_id", name="hipcwe_tenant_contact_uq"),
+        comment=(
+            "EE-only workspace allow-list for Organization Account contacts. Workspace membership and External "
+            "contact ownership must not create rows in this table."
+        ),
+    )
+    op.create_index(
+        "hipcwe_tenant_created_at_id_idx",
+        "human_input_platform_contact_workspace_entries",
+        ["tenant_id", "created_at", "id"],
+    )
+    op.create_index(
+        "hipcwe_contact_id_idx",
+        "human_input_platform_contact_workspace_entries",
+        ["contact_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("human_input_platform_contact_workspace_entries")
+    op.drop_table("human_input_contacts")
@@ -0,0 +1,320 @@
+"""add human input v2 im control plane
+
+Revision ID: 6d9f2b4c5e7a
+Revises: 5c8f1a2b3d4e
+Create Date: 2026-07-25 11:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+import models
+
+# revision identifiers, used by Alembic.
+revision = "6d9f2b4c5e7a"
+down_revision = "5c8f1a2b3d4e"
+branch_labels = None
+depends_on = None
+
+
+def _default_fields(table_name: str) -> tuple[sa.Column, sa.Column, sa.Column, sa.PrimaryKeyConstraint]:
+    return (
+        sa.Column("id", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=f"{table_name}_pkey"),
+    )
+
+
+def upgrade() -> None:
+    op.create_table(
+        "human_input_im_integrations",
+        sa.Column("provider", sa.String(length=20), nullable=False, comment="Configured IM provider discriminator."),
+        sa.Column(
+            "encrypted_credentials",
+            models.types.LongText(),
+            nullable=False,
+            comment="Provider-specific encrypted credential model serialized as JSON text.",
+        ),
+        sa.Column(
+            "tenant_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical tenants.id owner in CE/SaaS; null for an EE deployment-wide integration.",
+        ),
+        sa.Column(
+            "provider_tenant_id",
+            sa.String(length=255),
+            nullable=False,
+            comment="Confirmed provider-side organization or workspace identity.",
+        ),
+        sa.Column("status", sa.String(length=20), nullable=False, comment="Last connectivity diagnostic status."),
+        sa.Column(
+            "config_version",
+            sa.Integer(),
+            nullable=False,
+            comment="Monotonic configuration revision used with the integration ID for CAS.",
+        ),
+        sa.Column(
+            "configured_by_account_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical accounts.id for the latest configuration writer.",
+        ),
+        sa.Column("callback_url", sa.String(length=1024), nullable=True, comment="Configured callback URL."),
+        sa.Column(
+            "safe_status_reason",
+            models.types.LongText(),
+            nullable=True,
+            comment="Operator-safe connection diagnostic.",
+        ),
+        sa.Column("last_checked_at", sa.DateTime(), nullable=True, comment="Latest connectivity check timestamp."),
+        *_default_fields("human_input_im_integrations"),
+        sa.UniqueConstraint("tenant_id", name="human_input_im_integrations_tenant_uq"),
+        sa.CheckConstraint("config_version > 0", name="config_version_positive"),
+        comment="Organization-level Human Input IM integration configuration.",
+    )
+
+    op.create_table(
+        "human_input_im_identities",
+        sa.Column(
+            "integration_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_im_integrations.id owner.",
+        ),
+        sa.Column("provider", sa.String(length=20), nullable=False, comment="Provider identity discriminator."),
+        sa.Column(
+            "provider_user_id", sa.String(length=255), nullable=False, comment="Provider user matching identity."
+        ),
+        sa.Column("display_name", sa.String(length=255), nullable=True, comment="Latest provider display name."),
+        sa.Column("normalized_name", sa.String(length=255), nullable=True, comment="Case-folded provider name."),
+        sa.Column("email", sa.String(length=320), nullable=True, comment="Latest provider email."),
+        sa.Column(
+            "normalized_email", sa.String(length=320), nullable=True, comment="Case-folded fallback matching email."
+        ),
+        sa.Column(
+            "raw_payload",
+            models.types.LongText(),
+            nullable=False,
+            comment="Opaque provider payload serialized as JSON text for diagnostics.",
+        ),
+        sa.Column(
+            "last_seen_sync_run_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical human_input_im_sync_runs.id that last observed this identity.",
+        ),
+        sa.Column("last_seen_at", sa.DateTime(), nullable=True, comment="Timestamp last observed."),
+        *_default_fields("human_input_im_identities"),
+        sa.UniqueConstraint(
+            "integration_id",
+            "provider",
+            "provider_user_id",
+            name="human_input_im_identities_integration_provider_user_uq",
+        ),
+        sa.CheckConstraint(
+            "(email IS NULL AND normalized_email IS NULL) OR (email IS NOT NULL AND normalized_email IS NOT NULL)",
+            name="email_normalization_pair",
+        ),
+        comment="Current synchronized IM directory identities.",
+    )
+    op.create_index(
+        "hiimi_integration_provider_email_idx",
+        "human_input_im_identities",
+        ["integration_id", "provider", "normalized_email"],
+    )
+    op.create_index(
+        "hiimi_integration_provider_name_idx",
+        "human_input_im_identities",
+        ["integration_id", "provider", "normalized_name"],
+    )
+    op.create_index(
+        "hiimi_integration_last_seen_run_idx",
+        "human_input_im_identities",
+        ["integration_id", "last_seen_sync_run_id"],
+    )
+
+    op.create_table(
+        "human_input_im_bindings",
+        sa.Column(
+            "integration_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_im_integrations.id owner.",
+        ),
+        sa.Column("scope", sa.String(length=20), nullable=False, comment="Organization or workspace scope."),
+        sa.Column("scope_id", models.types.StringUUID(), nullable=False, comment="Scope owner identity."),
+        sa.Column("contact_id", models.types.StringUUID(), nullable=False, comment="Logical human_input_contacts.id."),
+        sa.Column(
+            "im_identity_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_im_identities.id.",
+        ),
+        sa.Column("provider", sa.String(length=20), nullable=False, comment="Denormalized provider discriminator."),
+        sa.Column(
+            "bound_by_account_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical accounts.id for an administrative override.",
+        ),
+        *_default_fields("human_input_im_bindings"),
+        sa.UniqueConstraint(
+            "scope",
+            "scope_id",
+            "contact_id",
+            "provider",
+            name="human_input_im_bindings_scope_contact_provider_uq",
+        ),
+        sa.UniqueConstraint("scope", "scope_id", "im_identity_id", name="human_input_im_bindings_scope_identity_uq"),
+        sa.CheckConstraint(
+            "scope <> 'organization' OR scope_id = integration_id",
+            name="organization_scope_owner",
+        ),
+        comment="Current organization binding or workspace override.",
+    )
+    op.create_index(
+        "hiimb_integration_contact_provider_scope_idx",
+        "human_input_im_bindings",
+        ["integration_id", "contact_id", "provider", "scope", "scope_id"],
+    )
+    op.create_index(
+        "hiimb_identity_scope_idx",
+        "human_input_im_bindings",
+        ["im_identity_id", "scope", "scope_id"],
+    )
+
+    op.create_table(
+        "human_input_im_sync_runs",
+        sa.Column(
+            "integration_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_im_integrations.id owner.",
+        ),
+        sa.Column(
+            "integration_config_version",
+            sa.Integer(),
+            nullable=False,
+            comment="Captured integration configuration revision.",
+        ),
+        sa.Column("provider", sa.String(length=20), nullable=False, comment="Captured provider discriminator."),
+        sa.Column("status", sa.String(length=20), nullable=False, comment="Synchronization lifecycle state."),
+        sa.Column("added_count", sa.Integer(), nullable=False, comment="Newly matched and bound entries."),
+        sa.Column("not_matched_count", sa.Integer(), nullable=False, comment="Unmatched entries."),
+        sa.Column("failed_count", sa.Integer(), nullable=False, comment="Failed entries."),
+        sa.Column(
+            "removed_count",
+            sa.Integer(),
+            nullable=False,
+            comment="Removed binding facts, including one unbound-identity fact when applicable.",
+        ),
+        sa.Column("skipped_count", sa.Integer(), nullable=False, comment="Intentionally skipped entries."),
+        sa.Column(
+            "started_by_account_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical accounts.id for the trigger actor.",
+        ),
+        sa.Column("started_at", sa.DateTime(), nullable=True, comment="Worker start timestamp."),
+        sa.Column("finished_at", sa.DateTime(), nullable=True, comment="Terminal timestamp."),
+        sa.Column("error_code", sa.String(length=100), nullable=True, comment="Machine-readable terminal error."),
+        sa.Column("error_message", models.types.LongText(), nullable=True, comment="Operator-safe terminal error."),
+        *_default_fields("human_input_im_sync_runs"),
+        sa.CheckConstraint("integration_config_version > 0", name="captured_version_positive"),
+        sa.CheckConstraint(
+            "added_count >= 0 AND not_matched_count >= 0 AND failed_count >= 0 AND removed_count >= 0 "
+            "AND skipped_count >= 0",
+            name="result_counts_nonnegative",
+        ),
+        comment="Manual IM directory synchronization lifecycle and counts.",
+    )
+    op.create_index(
+        "hiimsr_integration_created_idx",
+        "human_input_im_sync_runs",
+        ["integration_id", "created_at", "id"],
+    )
+    op.create_index(
+        "hiimsr_integration_status_created_idx",
+        "human_input_im_sync_runs",
+        ["integration_id", "status", "created_at"],
+    )
+
+    op.create_table(
+        "human_input_im_sync_results",
+        sa.Column(
+            "integration_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Denormalized logical human_input_im_integrations.id.",
+        ),
+        sa.Column(
+            "sync_run_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_im_sync_runs.id.",
+        ),
+        sa.Column("result_type", sa.String(length=20), nullable=False, comment="Stable result bucket."),
+        sa.Column("provider_user_id", sa.String(length=255), nullable=True, comment="Observed provider user ID."),
+        sa.Column("display_name", sa.String(length=255), nullable=True, comment="Observed provider display name."),
+        sa.Column("email", sa.String(length=320), nullable=True, comment="Observed provider email."),
+        sa.Column("normalized_email", sa.String(length=320), nullable=True, comment="Normalized matching email."),
+        sa.Column(
+            "contact_id", models.types.StringUUID(), nullable=True, comment="Historical logical Contact identity."
+        ),
+        sa.Column(
+            "im_identity_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Historical logical IM identity.",
+        ),
+        sa.Column("im_binding_id", models.types.StringUUID(), nullable=True, comment="Historical logical IM binding."),
+        sa.Column("removal_reason", sa.String(length=32), nullable=True, comment="Stable removal reason."),
+        sa.Column("reason_code", sa.String(length=100), nullable=True, comment="Machine-readable diagnostic reason."),
+        sa.Column("reason_message", models.types.LongText(), nullable=True, comment="Operator-safe diagnostic."),
+        sa.Column(
+            "directory_entry_payload",
+            models.types.LongText(),
+            nullable=True,
+            comment="Immutable provider entry JSON observed by this run.",
+        ),
+        sa.Column(
+            "contact_snapshot",
+            models.types.LongText(),
+            nullable=True,
+            comment="Immutable Contact display snapshot JSON.",
+        ),
+        sa.Column(
+            "identity_snapshot",
+            models.types.LongText(),
+            nullable=True,
+            comment="Immutable removed identity snapshot JSON.",
+        ),
+        *_default_fields("human_input_im_sync_results"),
+        comment="Append-only per-entry, removed-binding, and diagnostic IM synchronization outcomes.",
+    )
+    op.create_index(
+        "hiimsres_run_type_created_idx",
+        "human_input_im_sync_results",
+        ["sync_run_id", "result_type", "created_at", "id"],
+    )
+    op.create_index(
+        "hiimsres_integration_contact_created_idx",
+        "human_input_im_sync_results",
+        ["integration_id", "contact_id", "created_at"],
+    )
+    op.create_index(
+        "hiimsres_integration_identity_created_idx",
+        "human_input_im_sync_results",
+        ["integration_id", "im_identity_id", "created_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("human_input_im_sync_results")
+    op.drop_table("human_input_im_sync_runs")
+    op.drop_table("human_input_im_bindings")
+    op.drop_table("human_input_im_identities")
+    op.drop_table("human_input_im_integrations")
@@ -0,0 +1,290 @@
+"""add human input v2 form core
+
+Revision ID: 8a1c4e7f9b2d
+Revises: 6d9f2b4c5e7a
+Create Date: 2026-07-25 12:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+import models
+
+# revision identifiers, used by Alembic.
+revision = "8a1c4e7f9b2d"
+down_revision = "6d9f2b4c5e7a"
+branch_labels = None
+depends_on = None
+
+
+def _default_fields(table_name: str) -> tuple[sa.Column, sa.Column, sa.Column, sa.PrimaryKeyConstraint]:
+    return (
+        sa.Column("id", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=f"{table_name}_pkey"),
+    )
+
+
+def upgrade() -> None:
+    op.create_table(
+        "human_input_email_providers",
+        sa.Column("provider", sa.String(length=20), nullable=False, comment="Configured email provider discriminator."),
+        sa.Column("sender_email", sa.String(length=320), nullable=False, comment="Configured sender email address."),
+        sa.Column(
+            "encrypted_credentials",
+            models.types.LongText(),
+            nullable=False,
+            comment="Encrypted Resend credential Pydantic model serialized as JSON text.",
+        ),
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column("sender_name", sa.String(length=255), nullable=False, comment="Optional sender display name."),
+        sa.Column(
+            "configured_by_account_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to accounts.id for the latest configuration write.",
+        ),
+        *_default_fields("human_input_email_providers"),
+        sa.UniqueConstraint("tenant_id", name="human_input_email_providers_tenant_uq"),
+        comment="Workspace-level Human Input email delivery configuration.",
+    )
+
+    op.create_table(
+        "human_input_v2_forms",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column("app_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to apps.id."),
+        sa.Column(
+            "form_definition",
+            models.types.LongText(),
+            nullable=False,
+            comment="Frozen Human Input v2 form definition serialized as JSON text.",
+        ),
+        sa.Column("rendered_content", models.types.LongText(), nullable=False, comment="Frozen rendered content."),
+        sa.Column("node_timeout_at", sa.DateTime(), nullable=False, comment="Frozen node-level timeout timestamp."),
+        sa.Column("global_expires_at", sa.DateTime(), nullable=False, comment="Frozen global expiration timestamp."),
+        sa.Column("form_kind", sa.String(length=20), nullable=False, comment="Human Input v2 form ownership kind."),
+        sa.Column("status", sa.String(length=20), nullable=False, comment="Current form lifecycle state."),
+        sa.Column(
+            "workflow_pause_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to workflow_pauses.id.",
+        ),
+        sa.Column(
+            "node_execution_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to workflow_node_executions.id.",
+        ),
+        *_default_fields("human_input_v2_forms"),
+        sa.UniqueConstraint("workflow_pause_id", name="hiv2_forms_workflow_pause_uq"),
+        sa.UniqueConstraint("node_execution_id", name="hiv2_forms_node_execution_uq"),
+        sa.CheckConstraint(
+            "form_kind <> 'runtime' OR (workflow_pause_id IS NOT NULL AND node_execution_id IS NOT NULL)",
+            name="runtime_owner",
+        ),
+        comment="Independent Human Input v2 form roots bound only to shared workflow pause infrastructure.",
+    )
+    op.create_index(
+        "hiv2_forms_tenant_status_node_timeout_idx",
+        "human_input_v2_forms",
+        ["tenant_id", "status", "node_timeout_at"],
+    )
+    op.create_index(
+        "hiv2_forms_tenant_status_global_expiry_idx",
+        "human_input_v2_forms",
+        ["tenant_id", "status", "global_expires_at"],
+    )
+
+    op.create_table(
+        "human_input_v2_form_approver_grants",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column(
+            "form_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to human_input_v2_forms.id.",
+        ),
+        sa.Column("subject_type", sa.String(length=20), nullable=False, comment="Approval subject discriminator."),
+        sa.Column("subject_key", sa.String(length=255), nullable=False, comment="Portable subject deduplication key."),
+        sa.Column(
+            "matched_sources",
+            models.types.LongText(),
+            nullable=False,
+            comment="Immutable ordered recipient source snapshots serialized as JSON text.",
+        ),
+        sa.Column(
+            "subject_snapshot",
+            models.types.LongText(),
+            nullable=False,
+            comment="Immutable display-only subject snapshot serialized as JSON text.",
+        ),
+        sa.Column("contact_id", models.types.StringUUID(), nullable=True, comment="Logical human_input_contacts.id."),
+        sa.Column("end_user_id", models.types.StringUUID(), nullable=True, comment="Logical end_users.id."),
+        sa.Column("normalized_email", sa.String(length=320), nullable=True, comment="Normalized Email subject."),
+        *_default_fields("human_input_v2_form_approver_grants"),
+        sa.UniqueConstraint("form_id", "subject_key", name="hiv2_form_grants_form_subject_uq"),
+        sa.CheckConstraint(
+            "(subject_type = 'contact' AND contact_id IS NOT NULL AND end_user_id IS NULL "
+            "AND normalized_email IS NULL) OR "
+            "(subject_type = 'end_user' AND contact_id IS NULL AND end_user_id IS NOT NULL "
+            "AND normalized_email IS NULL) OR "
+            "(subject_type = 'email_address' AND contact_id IS NULL AND end_user_id IS NULL "
+            "AND normalized_email IS NOT NULL)",
+            name="subject_identity",
+        ),
+        comment="Frozen Human Input v2 form approval grants resolved from runtime recipients.",
+    )
+    op.create_index(
+        "hiv2_form_grants_form_contact_idx",
+        "human_input_v2_form_approver_grants",
+        ["form_id", "contact_id"],
+    )
+    op.create_index(
+        "hiv2_form_grants_form_end_user_idx",
+        "human_input_v2_form_approver_grants",
+        ["form_id", "end_user_id"],
+    )
+    op.create_index(
+        "hiv2_form_grants_form_email_idx",
+        "human_input_v2_form_approver_grants",
+        ["form_id", "normalized_email"],
+    )
+
+    op.create_table(
+        "human_input_v2_form_delivery_endpoints",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column("form_id", models.types.StringUUID(), nullable=False, comment="Logical human_input_v2_forms.id."),
+        sa.Column(
+            "approver_grant_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_v2_form_approver_grants.id.",
+        ),
+        sa.Column("channel", sa.String(length=20), nullable=False, comment="Delivery or interaction channel."),
+        sa.Column("address_hash", sa.String(length=64), nullable=False, comment="Canonical endpoint SHA-256."),
+        sa.Column("email_address", sa.String(length=320), nullable=True, comment="Frozen Email endpoint address."),
+        sa.Column("integration_id", models.types.StringUUID(), nullable=True, comment="Logical IM integration id."),
+        sa.Column("provider", sa.String(length=20), nullable=True, comment="Frozen IM provider."),
+        sa.Column("provider_user_id", sa.String(length=255), nullable=True, comment="Frozen provider user id."),
+        sa.Column("provider_tenant_id", sa.String(length=255), nullable=True, comment="Frozen provider tenant id."),
+        sa.Column("im_identity_id", models.types.StringUUID(), nullable=True, comment="Historical IM identity id."),
+        sa.Column("im_binding_id", models.types.StringUUID(), nullable=True, comment="Historical IM binding id."),
+        sa.Column("access_token_hash", sa.String(length=64), nullable=True, comment="Hashed endpoint capability."),
+        *_default_fields("human_input_v2_form_delivery_endpoints"),
+        sa.UniqueConstraint(
+            "form_id",
+            "approver_grant_id",
+            "channel",
+            "address_hash",
+            name="hiv2_form_endpoints_grant_channel_address_uq",
+        ),
+        sa.UniqueConstraint("access_token_hash", name="hiv2_form_endpoints_token_uq"),
+        comment="Immutable notification and interaction endpoints for Human Input v2 approver grants.",
+    )
+    op.create_index(
+        "hiv2_form_endpoints_identity_form_idx",
+        "human_input_v2_form_delivery_endpoints",
+        ["im_identity_id", "form_id"],
+    )
+
+    op.create_table(
+        "human_input_v2_form_delivery_attempts",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column("form_id", models.types.StringUUID(), nullable=False, comment="Logical human_input_v2_forms.id."),
+        sa.Column(
+            "endpoint_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_v2_form_delivery_endpoints.id.",
+        ),
+        sa.Column("attempt_number", sa.Integer(), nullable=False, comment="One-based endpoint retry sequence."),
+        sa.Column("status", sa.String(length=20), nullable=False, comment="Delivery attempt lifecycle."),
+        sa.Column("scheduled_at", sa.DateTime(), nullable=False, comment="Eligibility timestamp."),
+        sa.Column("started_at", sa.DateTime(), nullable=True, comment="Provider delivery start timestamp."),
+        sa.Column("finished_at", sa.DateTime(), nullable=True, comment="Terminal timestamp."),
+        sa.Column("provider_message_id", sa.String(length=255), nullable=True, comment="Provider message id."),
+        sa.Column("failure_code", sa.String(length=100), nullable=True, comment="Failure code."),
+        sa.Column("failure_reason", models.types.LongText(), nullable=True, comment="Failure diagnostic."),
+        sa.Column("provider_response", models.types.LongText(), nullable=True, comment="Provider response JSON."),
+        *_default_fields("human_input_v2_form_delivery_attempts"),
+        sa.UniqueConstraint("endpoint_id", "attempt_number", name="hiv2_form_attempts_endpoint_number_uq"),
+        comment="Append-oriented delivery attempts for Human Input v2 form endpoints.",
+    )
+    op.create_index(
+        "hiv2_form_attempts_form_status_created_idx",
+        "human_input_v2_form_delivery_attempts",
+        ["form_id", "status", "created_at", "id"],
+    )
+    op.create_index(
+        "hiv2_form_attempts_status_scheduled_idx",
+        "human_input_v2_form_delivery_attempts",
+        ["status", "scheduled_at", "id"],
+    )
+
+    op.create_table(
+        "human_input_v2_form_upload_tokens",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column("app_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to apps.id."),
+        sa.Column("form_id", models.types.StringUUID(), nullable=False, comment="Logical human_input_v2_forms.id."),
+        sa.Column(
+            "endpoint_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_v2_form_delivery_endpoints.id.",
+        ),
+        sa.Column("upload_token_hash", sa.String(length=64), nullable=False, comment="Hashed upload capability."),
+        *_default_fields("human_input_v2_form_upload_tokens"),
+        sa.UniqueConstraint("upload_token_hash", name="hiv2_form_upload_tokens_hash_uq"),
+        comment="Hashed endpoint-scoped upload capabilities for Human Input v2 forms.",
+    )
+    op.create_index(
+        "hiv2_form_upload_tokens_form_endpoint_idx",
+        "human_input_v2_form_upload_tokens",
+        ["form_id", "endpoint_id"],
+    )
+
+    op.create_table(
+        "human_input_v2_form_upload_files",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column("app_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to apps.id."),
+        sa.Column("form_id", models.types.StringUUID(), nullable=False, comment="Logical human_input_v2_forms.id."),
+        sa.Column(
+            "endpoint_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_v2_form_delivery_endpoints.id.",
+        ),
+        sa.Column("upload_file_id", models.types.StringUUID(), nullable=False, comment="Logical upload_files.id."),
+        sa.Column(
+            "upload_token_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical human_input_v2_form_upload_tokens.id.",
+        ),
+        *_default_fields("human_input_v2_form_upload_files"),
+        sa.UniqueConstraint("upload_file_id", name="hiv2_form_upload_files_file_uq"),
+        comment="Durable Human Input v2 form, endpoint, upload-token, and file associations.",
+    )
+    op.create_index(
+        "hiv2_form_upload_files_form_endpoint_idx",
+        "human_input_v2_form_upload_files",
+        ["form_id", "endpoint_id"],
+    )
+    op.create_index(
+        "hiv2_form_upload_files_token_idx",
+        "human_input_v2_form_upload_files",
+        ["upload_token_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("human_input_v2_form_upload_files")
+    op.drop_table("human_input_v2_form_upload_tokens")
+    op.drop_table("human_input_v2_form_delivery_attempts")
+    op.drop_table("human_input_v2_form_delivery_endpoints")
+    op.drop_table("human_input_v2_form_approver_grants")
+    op.drop_table("human_input_v2_forms")
+    op.drop_table("human_input_email_providers")
@@ -0,0 +1,105 @@
+"""add human input v2 otp proof session
+
+Revision ID: 9c2e5f7a1b3d
+Revises: 8a1c4e7f9b2d
+Create Date: 2026-07-25 13:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+import models
+
+# revision identifiers, used by Alembic.
+revision = "9c2e5f7a1b3d"
+down_revision = "8a1c4e7f9b2d"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "human_input_v2_form_otp_challenges",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column(
+            "form_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to human_input_v2_forms.id.",
+        ),
+        sa.Column(
+            "approver_grant_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to human_input_v2_form_approver_grants.id.",
+        ),
+        sa.Column("subject_type", sa.String(length=20), nullable=False, comment="OTP proof subject discriminator."),
+        sa.Column(
+            "challenge_token_hash",
+            sa.String(length=64),
+            nullable=False,
+            comment="SHA-256 hash of the ephemeral challenge token.",
+        ),
+        sa.Column(
+            "code_hash",
+            sa.String(length=255),
+            nullable=False,
+            comment="Slow password hash of the one-time verification code.",
+        ),
+        sa.Column(
+            "code_hash_algorithm",
+            sa.String(length=50),
+            nullable=False,
+            comment="Verifier algorithm discriminator for code_hash.",
+        ),
+        sa.Column("email_hash", sa.String(length=64), nullable=False, comment="SHA-256 of the normalized Email."),
+        sa.Column("email", sa.String(length=320), nullable=False, comment="Normalized destination Email."),
+        sa.Column("status", sa.String(length=20), nullable=False, comment="Current proof-session usability."),
+        sa.Column("expires_at", sa.DateTime(), nullable=False, comment="Challenge expiration timestamp."),
+        sa.Column("resend_after", sa.DateTime(), nullable=False, comment="Earliest replacement timestamp."),
+        sa.Column(
+            "contact_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical human_input_contacts.id captured for a Contact incarnation.",
+        ),
+        sa.Column("send_count", sa.Integer(), nullable=False, comment="One-based send count for the grant scope."),
+        sa.Column("attempt_count", sa.Integer(), nullable=False, comment="Consumed verification attempts."),
+        sa.Column("verified_at", sa.DateTime(), nullable=True, comment="Successful verification timestamp."),
+        sa.Column("invalidated_at", sa.DateTime(), nullable=True, comment="Replacement or stale-identity timestamp."),
+        sa.Column("id", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name="human_input_v2_form_otp_challenges_pkey"),
+        sa.UniqueConstraint("challenge_token_hash", name="hiv2_form_otp_challenges_token_uq"),
+        sa.CheckConstraint(
+            "(subject_type = 'contact' AND contact_id IS NOT NULL) OR "
+            "(subject_type = 'email_address' AND contact_id IS NULL)",
+            name="hiv2_form_otp_challenges_subject_identity_ck",
+        ),
+        sa.CheckConstraint(
+            "send_count >= 1 AND send_count <= 5",
+            name="hiv2_form_otp_challenges_send_count_ck",
+        ),
+        sa.CheckConstraint(
+            "attempt_count >= 0 AND attempt_count <= 5",
+            name="hiv2_form_otp_challenges_attempt_count_ck",
+        ),
+        sa.CheckConstraint(
+            "(status = 'verified' AND verified_at IS NOT NULL AND invalidated_at IS NULL) OR "
+            "(status = 'invalidated' AND verified_at IS NULL AND invalidated_at IS NOT NULL) OR "
+            "(status IN ('pending', 'expired') AND verified_at IS NULL AND invalidated_at IS NULL)",
+            name="hiv2_form_otp_challenges_terminal_timestamps_ck",
+        ),
+        comment="Hashed OTP proof sessions for Email-based Human Input v2 approval.",
+    )
+    op.create_index(
+        "hiv2_form_otp_scope_created_idx",
+        "human_input_v2_form_otp_challenges",
+        ["tenant_id", "form_id", "approver_grant_id", "created_at", "id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("human_input_v2_form_otp_challenges")
@@ -0,0 +1,183 @@
+"""add human input v2 submission runtime
+
+Revision ID: ad4f6b8c2e1d
+Revises: 9c2e5f7a1b3d
+Create Date: 2026-07-25 14:00:00.000000
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+import models
+
+# revision identifiers, used by Alembic.
+revision = "ad4f6b8c2e1d"
+down_revision = "9c2e5f7a1b3d"
+branch_labels = None
+depends_on = None
+
+
+def _default_fields(table_name: str) -> tuple[sa.Column, sa.Column, sa.Column, sa.PrimaryKeyConstraint]:
+    return (
+        sa.Column("id", models.types.StringUUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.func.current_timestamp(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=f"{table_name}_pkey"),
+    )
+
+
+def upgrade() -> None:
+    op.create_table(
+        "human_input_v2_form_audit_events",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column(
+            "form_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to human_input_v2_forms.id.",
+        ),
+        sa.Column("event_type", sa.String(length=64), nullable=False, comment="Stable append-only event name."),
+        sa.Column("occurred_at", sa.DateTime(), nullable=False, comment="Business timestamp for the audited fact."),
+        sa.Column(
+            "approver_grant_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to human_input_v2_form_approver_grants.id.",
+        ),
+        sa.Column(
+            "endpoint_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to human_input_v2_form_delivery_endpoints.id.",
+        ),
+        sa.Column("channel", sa.String(length=20), nullable=True, comment="Originating interaction channel."),
+        sa.Column("reason_code", sa.String(length=100), nullable=True, comment="Stable rejection reason code."),
+        sa.Column("reason_message", models.types.LongText(), nullable=True, comment="Operator-safe diagnostic detail."),
+        sa.Column(
+            "authorization_proof",
+            models.types.LongText(),
+            nullable=True,
+            comment="Secret-free verified proof serialized as structured JSON text.",
+        ),
+        sa.Column(
+            "event_payload",
+            models.types.LongText(),
+            nullable=True,
+            comment="Immutable event-specific structured JSON text.",
+        ),
+        *_default_fields("human_input_v2_form_audit_events"),
+        sa.CheckConstraint(
+            "event_type <> 'submission_authorized' OR "
+            "(approver_grant_id IS NOT NULL AND authorization_proof IS NOT NULL)",
+            name="hiv2_form_audit_authorized_proof_ck",
+        ),
+        sa.CheckConstraint(
+            "event_type <> 'submission_rejected' OR reason_code IS NOT NULL",
+            name="hiv2_form_audit_rejection_reason_ck",
+        ),
+        comment="Append-only Human Input v2 audit facts for proof sessions and submission authorization.",
+    )
+    op.create_index(
+        "hiv2_form_audit_form_occurred_idx",
+        "human_input_v2_form_audit_events",
+        ["form_id", "occurred_at", "id"],
+    )
+    op.create_index(
+        "hiv2_form_audit_tenant_occurred_idx",
+        "human_input_v2_form_audit_events",
+        ["tenant_id", "occurred_at", "id"],
+    )
+
+    op.create_table(
+        "human_input_v2_form_submissions",
+        sa.Column("tenant_id", models.types.StringUUID(), nullable=False, comment="Logical foreign key to tenants.id."),
+        sa.Column(
+            "form_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to human_input_v2_forms.id.",
+        ),
+        sa.Column(
+            "approver_grant_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to human_input_v2_form_approver_grants.id.",
+        ),
+        sa.Column("actor_type", sa.String(length=20), nullable=False, comment="Submission actor discriminator."),
+        sa.Column(
+            "authorization_audit_event_id",
+            models.types.StringUUID(),
+            nullable=False,
+            comment="Logical foreign key to the authorized human_input_v2_form_audit_events.id.",
+        ),
+        sa.Column(
+            "selected_action_id",
+            sa.String(length=200),
+            nullable=False,
+            comment="Selected action from the frozen form definition.",
+        ),
+        sa.Column(
+            "input_snapshot",
+            models.types.LongText(),
+            nullable=False,
+            comment="Unvalidated request.inputs object serialized as structured JSON text.",
+        ),
+        sa.Column(
+            "canonical_values",
+            models.types.LongText(),
+            nullable=False,
+            comment="Validated runtime values serialized as structured JSON text.",
+        ),
+        sa.Column("submitted_at", sa.DateTime(), nullable=False, comment="Winning commit business timestamp."),
+        sa.Column(
+            "actor_account_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical accounts.id for an Account actor.",
+        ),
+        sa.Column(
+            "actor_end_user_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical end_users.id for an EndUser actor.",
+        ),
+        sa.Column(
+            "actor_normalized_email",
+            sa.String(length=320),
+            nullable=True,
+            comment="Normalized EmailAddress actor identity.",
+        ),
+        sa.Column(
+            "endpoint_id",
+            models.types.StringUUID(),
+            nullable=True,
+            comment="Logical foreign key to human_input_v2_form_delivery_endpoints.id.",
+        ),
+        *_default_fields("human_input_v2_form_submissions"),
+        sa.UniqueConstraint("form_id", name="hiv2_form_submissions_form_uq"),
+        sa.UniqueConstraint(
+            "authorization_audit_event_id",
+            name="hiv2_submission_authorization_audit_event_uq",
+        ),
+        sa.CheckConstraint(
+            "(actor_type = 'account' AND actor_account_id IS NOT NULL AND actor_end_user_id IS NULL "
+            "AND actor_normalized_email IS NULL) OR "
+            "(actor_type = 'end_user' AND actor_account_id IS NULL AND actor_end_user_id IS NOT NULL "
+            "AND actor_normalized_email IS NULL) OR "
+            "(actor_type = 'email_address' AND actor_account_id IS NULL AND actor_end_user_id IS NULL "
+            "AND actor_normalized_email IS NOT NULL)",
+            name="hiv2_form_submissions_actor_identity_ck",
+        ),
+        comment="Immutable first successful Human Input v2 submission and business actor.",
+    )
+    op.create_index(
+        "hiv2_form_submissions_tenant_submitted_idx",
+        "human_input_v2_form_submissions",
+        ["tenant_id", "submitted_at", "id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("human_input_v2_form_submissions")
+    op.drop_table("human_input_v2_form_audit_events")
@@ -66,6 +66,50 @@ from .enums import (
 )
 from .execution_extra_content import ExecutionExtraContent, HumanInputContent
 from .human_input import HumanInputForm, HumanInputFormUploadFile, HumanInputFormUploadToken
+from .human_input_v2 import (
+    AccountSessionAuthorizationProof,
+    DingTalkIMIntegrationEncryptedCredentials,
+    EmailOTPAuthorizationProof,
+    FeishuIMIntegrationEncryptedCredentials,
+    FormApproverGrantMatchedSources,
+    FormApproverGrantSubjectSnapshot,
+    FormAuditEventPayload,
+    FormAuthorizationProof,
+    FormCanonicalValues,
+    FormDeliveryProviderResponse,
+    FormInputSnapshot,
+    HumanInputContact,
+    HumanInputContactIdentitySource,
+    HumanInputEmailProvider,
+    HumanInputIMBinding,
+    HumanInputIMIdentity,
+    HumanInputIMIntegration,
+    HumanInputIMSyncResult,
+    HumanInputIMSyncRun,
+    HumanInputPlatformContactWorkspaceEntry,
+    HumanInputV2Form,
+    HumanInputV2FormApproverGrant,
+    HumanInputV2FormAuditEvent,
+    HumanInputV2FormDefinition,
+    HumanInputV2FormDeliveryAttempt,
+    HumanInputV2FormDeliveryEndpoint,
+    HumanInputV2FormOTPChallenge,
+    HumanInputV2FormSubmission,
+    HumanInputV2FormUploadFile,
+    HumanInputV2FormUploadToken,
+    IMIdentityAuthorizationProof,
+    IMIdentityRawPayload,
+    IMIntegrationEncryptedCredentials,
+    IMSyncContactSnapshot,
+    IMSyncDirectoryEntryPayload,
+    IMSyncIdentitySnapshot,
+    LarkIMIntegrationEncryptedCredentials,
+    MSTeamsIMIntegrationEncryptedCredentials,
+    ResendEmailProviderEncryptedCredentials,
+    SlackIMIntegrationEncryptedCredentials,
+    TrustedEndUserAuthorizationProof,
+    WeComIMIntegrationEncryptedCredentials,
+)
 from .model import (
    AccountTrialAppRecord,
    ApiRequest,
@@ -155,6 +199,7 @@ __all__ = [
    "APIBasedExtensionPoint",
    "Account",
    "AccountIntegrate",
+    "AccountSessionAuthorizationProof",
    "AccountStatus",
    "AccountStepByStepTourState",
    "AccountTrialAppRecord",
@@ -211,22 +256,59 @@ __all__ = [
    "DatasourceOauthParamConfig",
    "DatasourceProvider",
    "DifySetup",
+    "DingTalkIMIntegrationEncryptedCredentials",
    "Document",
    "DocumentSegment",
+    "EmailOTPAuthorizationProof",
    "Embedding",
    "EndUser",
    "ExecutionExtraContent",
    "ExporleBanner",
    "ExternalKnowledgeApis",
    "ExternalKnowledgeBindings",
+    "FeishuIMIntegrationEncryptedCredentials",
+    "FormApproverGrantMatchedSources",
+    "FormApproverGrantSubjectSnapshot",
+    "FormAuditEventPayload",
+    "FormAuthorizationProof",
+    "FormCanonicalValues",
+    "FormDeliveryProviderResponse",
+    "FormInputSnapshot",
+    "HumanInputContact",
+    "HumanInputContactIdentitySource",
    "HumanInputContent",
+    "HumanInputEmailProvider",
    "HumanInputForm",
    "HumanInputFormUploadFile",
    "HumanInputFormUploadToken",
+    "HumanInputIMBinding",
+    "HumanInputIMIdentity",
+    "HumanInputIMIntegration",
+    "HumanInputIMSyncResult",
+    "HumanInputIMSyncRun",
+    "HumanInputPlatformContactWorkspaceEntry",
+    "HumanInputV2Form",
+    "HumanInputV2FormApproverGrant",
+    "HumanInputV2FormAuditEvent",
+    "HumanInputV2FormDefinition",
+    "HumanInputV2FormDeliveryAttempt",
+    "HumanInputV2FormDeliveryEndpoint",
+    "HumanInputV2FormOTPChallenge",
+    "HumanInputV2FormSubmission",
+    "HumanInputV2FormUploadFile",
+    "HumanInputV2FormUploadToken",
+    "IMIdentityAuthorizationProof",
+    "IMIdentityRawPayload",
+    "IMIntegrationEncryptedCredentials",
+    "IMSyncContactSnapshot",
+    "IMSyncDirectoryEntryPayload",
+    "IMSyncIdentitySnapshot",
    "IconType",
    "InstalledApp",
    "InvitationCode",
+    "LarkIMIntegrationEncryptedCredentials",
    "LoadBalancingModelConfig",
+    "MSTeamsIMIntegrationEncryptedCredentials",
    "Message",
    "MessageAgentThought",
    "MessageAnnotation",
@@ -244,8 +326,10 @@ __all__ = [
    "ProviderQuotaType",
    "ProviderType",
    "RecommendedApp",
+    "ResendEmailProviderEncryptedCredentials",
    "SavedMessage",
    "Site",
+    "SlackIMIntegrationEncryptedCredentials",
    "SnippetType",
    "Tag",
    "TagBinding",
@@ -266,7 +350,9 @@ __all__ = [
    "TriggerOAuthSystemClient",
    "TriggerOAuthTenantClient",
    "TriggerSubscription",
+    "TrustedEndUserAuthorizationProof",
    "UploadFile",
+    "WeComIMIntegrationEncryptedCredentials",
    "Whitelist",
    "Workflow",
    "WorkflowAgentBindingType",
@@ -2,7 +2,7 @@ from flask_sqlalchemy import SQLAlchemy
 from sqlalchemy import MetaData

 POSTGRES_INDEXES_NAMING_CONVENTION = {
-    "ix": "%(column_0_label)s_idx",
+    "ix": "%(table_name)s_%(column_0_N_name)s_idx",
    "uq": "%(table_name)s_%(column_0_name)s_key",
    "ck": "%(table_name)s_%(constraint_name)s_check",
    "fk": "%(table_name)s_%(column_0_name)s_fkey",
--- a/Show More
+++ b/Show More