"Assign number" as a workflow step — number step kind

    // StepKindNumber routes the ASSIGN-NUMBER duty for a LETTER subject: holders of the
    // step's positions and/or its named users each get a "number" task, and completing it
    // runs the existing gapless AssignNumber path with TASK-HOLDER authorization (holding
    // the pending task IS the authority — no correspondence-creator gate, no org-wide
    // permission). Letter subjects only — enforced at START time by
    // guardLetterWorkflowStart, because definitions are subject-agnostic. Chain shape is
    // enforced by NumberStepOrder: at most one number step, after every approve step,
    // before every seal step (the numbered PDF is the base the chain seals in place).
    StepKindNumber = "number"

    case "", StepKindApprove, StepKindSign, StepKindMeterai, StepKindSignExternal, StepKindStamp, StepKindNumber:

    // SchemeCode optionally PINS the numbering scheme a NUMBER step must use. Empty (the
    // default) = the registrar picks the scheme in the completion modal at task time.
    // Read only on a number step. omitempty keeps every existing jsonb step
    // byte-identical (the back-compat contract of this struct).
    SchemeCode string `json:"scheme_code,omitempty"`

// NumberStepOrder enforces the CHAIN-SHAPE invariants of the assign-number step, shared by
// ValidateSteps (every authoring path) and the letter start guard (defense in depth for a
// definition authored before a rule existed): a definition may carry at most ONE number
// step; every approve step must PRECEDE it; every seal step (sign / sign_external /
// meterai / stamp) must FOLLOW it. A list with no number step always passes. Returns
// ok=false plus a human reason on the first violation.
func NumberStepOrder(steps []StepSpec) (ok bool, reason string) {
    sealSeen := false
    numberSeen := false
    for _, st := range steps {
        switch st.Kind() {
        case StepKindNumber:
            if numberSeen {
                return false, "Definition may have at most one Assign-number step"
            }
            if sealSeen {
                return false, "The Assign-number step must come before any signature, e-Meterai or stamp step"
            }
            numberSeen = true
        case StepKindSign, StepKindSignExternal, StepKindMeterai, StepKindStamp:
            sealSeen = true
        default: // approve (including the legacy empty kind)
            if numberSeen {
                return false, "Approval steps must come before the Assign-number step"
            }
        }
    }
    return true, ""
}

    if ok, reason := NumberStepOrder(steps); !ok {
        return false, reason
    }

        case StepKindNumber:
            // Assignees exactly like an approval: positions and/or named users. The
            // letter-only + not-yet-numbered rules are START-time checks
            // (guardLetterWorkflowStart) — a definition is subject-agnostic; the
            // ordering/count rules ran up front (NumberStepOrder).
            if !named {
                return false, "Step has no approver positions"
            }

    case StepKindNumber:
        // Numbering has no on-page appearance — nothing to pre-place, ever.
        return true

    // ActionNumber is recorded when an ASSIGN-NUMBER step is completed by its task holder
    // numbering the subject letter (the engine-scoped AssignNumber path). Advances like
    // ActionApprove; reads as a numbering in the chain-of-custody. Recorded-only: absent
    // from Next().
    ActionNumber Action = "number"

    case StepKindNumber:
        return "Assign number"

    switch step.Kind() {
    case domain.StepKindSign, domain.StepKindMeterai, domain.StepKindStamp:
    case domain.StepKindNumber:
        // Numbering has no on-page appearance — never a placement.
        return nil
    default:
        return nil
    }

            case "sign", "meterai", "stamp", "number":
                callerHasCeremonyTask = true

// CompleteNumberForSubject advances any definition-driven workflow whose CURRENT step is an
// ASSIGN-NUMBER step over (subjectType, subjectID), on behalf of p who just numbered the
// subject letter through the task endpoint. Mirror of CompleteMeteraiForSubject with ONE
// deliberate difference: numbering carries no org-wide permission of its own — holding a
// pending number task IS the authority — so only a HOLDER advances the step (no
// any-permitted-user override; a non-holder is skipped silently — the endpoint already
// 403'd them, this in-tx re-check is the concurrency backstop). No-op (nil) when nothing is
// waiting, so a retry after a half-completed call (letter numbered, advance lost) converges
// instead of failing.
func (s *Service) CompleteNumberForSubject(ctx context.Context, p kernel.Principal, subjectType, subjectID string) error {
    if subjectType == "" || subjectID == "" {
        return nil
    }
    return s.uow.Do(ctx, func(ctx context.Context) error {
        tasks, err := s.repo.FindPendingTasksForSubjectAction(ctx, subjectType, subjectID, domain.StepKindNumber)
        if err != nil {
            return err
        }
        if len(tasks) == 0 {
            return nil
        }
        now := s.clock.Now()
        seen := map[string]bool{}
        for _, t := range tasks {
            if seen[t.InstanceID] {
                continue
            }
            seen[t.InstanceID] = true

            holder := false
            for _, tk := range tasks {
                if tk.InstanceID == t.InstanceID && tk.AssigneeUserID == string(p.UserID) {
                    holder = true
                    break
                }
            }
            if !holder {
                continue // task-holder only: numbering has no rank/permission override
            }
            inst, err := s.repo.GetInstance(ctx, t.InstanceID)
            if err != nil {
                return err
            }
            if inst.DefinitionVersionID == nil || inst.State != domain.StateSubmitted {
                continue
            }
            ver, err := s.repo.GetDefinitionVersion(ctx, *inst.DefinitionVersionID)
            if err != nil {
                return err
            }
            // Re-check the CURRENT step really is the number step (the pending task
            // implies it, but the instance may have moved between query and lock).
            if inst.CurrentStep < 1 || inst.CurrentStep > len(ver.Steps) || ver.Steps[inst.CurrentStep-1].Kind() != domain.StepKindNumber {
                continue
            }
            if err := s.advanceApprovedInstance(ctx, inst, ver, string(p.UserID), "number assigned", domain.ActionNumber, now); err != nil {
                return err
            }
        }
        return nil
    })
}

// NumberTaskContext loads and validates the caller's pending NUMBER task for the completion
// endpoint: the task must exist, be pending, carry action_required="number" and be assigned
// to p; its instance must be definition-driven, still submitted, and sitting ON the number
// step. Returns the instance (subject routing) and the number step's spec (its optional
// pinned scheme_code). Read-only — completion + advance run in CompleteNumberForSubject
// AFTER the numbering itself succeeded.
func (s *Service) NumberTaskContext(ctx context.Context, p kernel.Principal, taskID string) (domain.Instance, domain.StepSpec, error) {
    var zi domain.Instance
    var zs domain.StepSpec
    if taskID == "" {
        return zi, zs, &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.number.task_required", Message: "task id is required"}
    }
    tk, err := s.repo.GetTask(ctx, taskID)
    if err != nil {
        return zi, zs, err
    }
    if tk.ActionRequired != domain.StepKindNumber {
        return zi, zs, &kernel.Error{Kind: kernel.ErrConflict, Code: "workflow.number.not_number_task", Message: "this task is not an assign-number task"}
    }
    if tk.AssigneeUserID != string(p.UserID) {
        return zi, zs, &kernel.Error{Kind: kernel.ErrPermissionDenied, Code: "workflow.number.not_assignee", Message: "only this task's assignee can assign the number"}
    }
    if tk.State != domain.TaskStatePending {
        return zi, zs, &kernel.Error{Kind: kernel.ErrConflict, Code: "workflow.number.task_done", Message: "this task is already completed"}
    }
    inst, err := s.repo.GetInstance(ctx, tk.InstanceID)
    if err != nil {
        return zi, zs, err
    }
    if inst.DefinitionVersionID == nil || inst.State != domain.StateSubmitted {
        return zi, zs, &kernel.Error{Kind: kernel.ErrConflict, Code: "workflow.number.not_active", Message: "the workflow is not waiting on this step"}
    }
    ver, err := s.repo.GetDefinitionVersion(ctx, *inst.DefinitionVersionID)
    if err != nil {
        return zi, zs, err
    }
    if inst.CurrentStep < 1 || inst.CurrentStep > len(ver.Steps) || ver.Steps[inst.CurrentStep-1].Kind() != domain.StepKindNumber {
        return zi, zs, &kernel.Error{Kind: kernel.ErrConflict, Code: "workflow.number.not_active", Message: "the workflow is not waiting on this step"}
    }
    return inst, ver.Steps[inst.CurrentStep-1], nil
}

// guardLetterWorkflowStart authorizes and validates starting a workflow over a letter: the caller
// must be permitted to drive the letter (its creator or a correspondence admin) AND the chain
// shape must fit the letter's numbering state. Because a letter is sealed in place, any workflow
// containing a SEAL step (sign / meterai / stamp / sign_external) needs a numbered base PDF:
// either the letter is ALREADY numbered (chains without a number step — the original rule), or
// the chain itself carries an ASSIGN-NUMBER step that will number it first (approve* → number →
// seal*, shape re-checked here via NumberStepOrder as defense in depth over ValidateSteps).
// A chain WITH a number step additionally requires a NOT-yet-numbered, outbound letter — and a
// LETTER subject at all: for any other subject a number step is refused before the early return,
// so the document start paths stay otherwise untouched.
func (s *Server) guardLetterWorkflowStart(ctx context.Context, p kernel.Principal, subjectType, subjectID string, steps []workflowdomain.StepSpec) *kernel.Error {
    // One shape scan drives every rule below.
    hasSeal := false
    hasNumber := false
    for _, st := range steps {
        switch st.Kind() {
        case workflowdomain.StepKindSign, workflowdomain.StepKindMeterai, workflowdomain.StepKindStamp, workflowdomain.StepKindSignExternal:
            hasSeal = true
        case workflowdomain.StepKindNumber:
            hasNumber = true
        }
    }
    if subjectType != "letter" {
        // An assign-number step runs the LETTER numbering ledger — it is meaningless (and
        // would strand the chain) over any other subject. Everything else about non-letter
        // subjects is none of this guard's business.
        if hasNumber {
            return &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.workflow.number_letter_only", Message: "an Assign-number step can only run over a letter"}
        }
        return nil
    }
    letter, err := s.correspondence.GetLetter(ctx, subjectID)
    if err != nil {
        // Coerce a kernel.Error (e.g. not-found) through; wrap anything else.
        var ke *kernel.Error
        if errors.As(err, &ke) {
            return ke
        }
        return &kernel.Error{Kind: kernel.ErrUnknown, Code: "correspondence.workflow.lookup_failed", Message: err.Error()}
    }
    // Access: creator or correspondence admin (mirrors the document editor gate for workflow start).
    if letter.CreatedBy != string(p.UserID) && !s.isCorrespondenceAdmin(ctx, p) {
        return &kernel.Error{Kind: kernel.ErrPermissionDenied, Code: "correspondence.workflow.forbidden", Message: "only the letter's author or a correspondence admin can start a workflow over it"}
    }
    // A dispatched (sent) letter is terminally locked — no workflow (approval OR seal chain)
    // may start over it.
    if gerr := guardLetterNotSent(letter); gerr != nil {
        return gerr
    }
    if hasNumber {
        // Shape defense-in-depth: ValidateSteps enforced this on every AUTHORING path; the
        // re-check catches a definition authored before the rule existed.
        if ok, reason := workflowdomain.NumberStepOrder(steps); !ok {
            return &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.workflow.number_order", Message: reason}
        }
        switch letter.Status {
        case corrdomain.StatusNumbered:
            // Numbers are never re-assigned: run a seal-only chain instead.
            return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.workflow.already_numbered", Message: "the letter already has its official number — remove the Assign-number step or run a seal-only workflow"}
        case corrdomain.StatusRegistered:
            return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.workflow.number_inbound", Message: "an inbound (registered) letter never takes an outbound number"}
        }
        // Seal steps are fine here: the in-chain number step numbers the letter first.
        return nil
    }
    // Number-first (UNCHANGED rule for chains without a number step): any seal-bearing step
    // requires an already-numbered letter (the numbered PDF is the base the chain seals in
    // place).
    if hasSeal && letter.Status != corrdomain.StatusNumbered {
        return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.workflow.number_first", Message: "number the letter before starting a signing / e-Meterai / stamp workflow"}
    }
    return nil
}

    // An approve-bearing chain starting over a draft/rejected letter flips it to in_review
    // (parity with SubmitLetter's definition branch and POST /workflows; MarkInReview
    // no-ops on any other status). Best-effort — the instance already exists.
    if body.SubjectType == "letter" {
        _ = s.correspondence.MarkInReview(r.Context(), body.SubjectID)
    }

func (s *Service) reserveNumber(ctx context.Context, letterID, schemeCode string, fromWorkflow bool) (reservation, error) {

        numberable := res.letter.Status == domain.StatusDraft || res.letter.Status == domain.StatusApproved
        if fromWorkflow && res.letter.Status == domain.StatusInReview {
            // The workflow NUMBER step completes MID-CHAIN: the approve steps flipped the
            // letter to in_review at start and the terminal reflection has not run yet
            // (the instance is still submitted). Only the engine-scoped task path may
            // number an in_review letter — the public endpoint keeps draft|approved.
            numberable = true
        }
        if !numberable {
            return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.assign.not_numberable", Message: "letter is not in a numberable state (draft or approved)"}
        }

// AssignNumberWithLetterhead is AssignNumber with an OPTIONAL letterhead (kop/footer). …
// (existing doc comment stays verbatim)
func (s *Service) AssignNumberWithLetterhead(ctx context.Context, p kernel.Principal, letterID, schemeCode, headerHTML, footerHTML string) (string, error) {
    return s.assignNumberWithLetterhead(ctx, p, letterID, schemeCode, headerHTML, footerHTML, false)
}

// AssignNumberWithLetterheadForTask is the ENGINE-SCOPED twin used by the workflow
// number-step completion: the identical gapless reserve→render→finalize flow, but the
// status gate additionally accepts an in_review letter (the chain's approve steps put it
// there). Authorization happened at the transport — the caller holds the pending number
// task; there is deliberately no creator/corr-admin check here.
func (s *Service) AssignNumberWithLetterheadForTask(ctx context.Context, p kernel.Principal, letterID, schemeCode, headerHTML, footerHTML string) (string, error) {
    return s.assignNumberWithLetterhead(ctx, p, letterID, schemeCode, headerHTML, footerHTML, true)
}

func (s *Service) assignNumberWithLetterhead(ctx context.Context, p kernel.Principal, letterID, schemeCode, headerHTML, footerHTML string, fromWorkflow bool) (string, error) {
    res, err := s.reserveNumber(ctx, letterID, schemeCode, fromWorkflow)
    // … body from today's AssignNumberWithLetterhead (:867–917) VERBATIM from here on …
}

// CompleteNumberTask completes a workflow ASSIGN-NUMBER task: the caller must be the task's
// assignee (holding the pending task IS the authority — the engine-scoped twin of
// AssignLetterNumber, which stays creator/correspondence-admin gated and is UNCHANGED), the
// instance must still be waiting on the number step, and the subject must be a letter. Runs
// the existing gapless AssignNumber path (docx merge-fields or HTML render, with the same
// optional letterhead resolution as the public endpoint), then completes the task and
// advances the chain (CompleteNumberForSubject).
//
// DECISION — an already-numbered letter does NOT fail the task: it AUTO-COMPLETES. Reached
// two ways: a concurrent DIRECT numbering (creator raced the registrar on the public
// endpoint), or a retry after a crash between numbering and advancing. In both, the step's
// postcondition — "the letter is numbered before the seal steps" — already holds; numbers
// are never un-assigned, so a 409 would strand the run on a task that can never complete
// (the dead-end-task class of bug). Only the task's assignee can take this branch, and it
// allocates nothing — the gapless ledger is untouched. Response then carries the EXISTING
// number with already_numbered=true.
func (s *Server) CompleteNumberTask(w http.ResponseWriter, r *http.Request) {
    p, _ := PrincipalFrom(r.Context())
    taskID := chi.URLParam(r, "taskID")
    var body struct {
        SchemeCode   string `json:"scheme_code"`
        LetterheadID string `json:"letterhead_id"`
    }
    if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
        writeProblem(w, &kernel.Error{Kind: kernel.ErrValidation, Code: "request.invalid_json", Message: "invalid request body"})
        return
    }
    inst, step, err := s.workflow.NumberTaskContext(r.Context(), p, taskID)
    if err != nil {
        writeProblem(w, err)
        return
    }
    if inst.SubjectType != "letter" {
        // Unreachable when the start guard did its job (number steps are letter-only);
        // refuse honestly for any instance that predates the guard.
        writeProblem(w, &kernel.Error{Kind: kernel.ErrConflict, Code: "workflow.number.not_letter", Message: "this workflow does not run over a letter"})
        return
    }
    letter, err := s.correspondence.GetLetter(r.Context(), inst.SubjectID)
    if err != nil {
        writeProblem(w, err)
        return
    }
    // Concurrent direct numbering / retry-after-crash: skip allocation, finish the step
    // (see the doc comment). Sent implies numbered and is unreachable mid-run (MarkSent
    // refuses while an instance is submitted) — handled for defense anyway.
    if letter.Status == corrdomain.StatusNumbered || letter.Status == corrdomain.StatusSent {
        if err := s.workflow.CompleteNumberForSubject(r.Context(), p, "letter", inst.SubjectID); err != nil {
            writeProblem(w, err)
            return
        }
        writeJSON(w, http.StatusOK, map[string]any{"number": letter.Number, "already_numbered": true})
        return
    }
    // Scheme: a definition-pinned scheme wins (the author's intent); otherwise the
    // registrar picked one in the completion modal.
    schemeCode := step.SchemeCode
    if schemeCode == "" {
        schemeCode = body.SchemeCode
    }
    if schemeCode == "" {
        writeProblem(w, &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.assign.scheme_required", Message: "scheme code is required"})
        return
    }
    var number string
    if letter.Authoring == corrdomain.AuthoringDocx {
        // The letterhead was fixed at creation for a docx letter (it IS the seed docx) —
        // letterhead_id is ignored on this branch, exactly like AssignLetterNumber.
        number, err = s.correspondence.AssignNumberDocxForTask(r.Context(), p, inst.SubjectID, schemeCode)
    } else {
        var headerHTML, footerHTML string
        if body.LetterheadID != "" {
            lh, lerr := s.letterhead.GetLetterhead(r.Context(), body.LetterheadID)
            if lerr != nil {
                writeProblem(w, lerr)
                return
            }
            headerHTML, footerHTML = lh.HeaderHTML, lh.FooterHTML
        }
        number, err = s.correspondence.AssignNumberWithLetterheadForTask(r.Context(), p, inst.SubjectID, schemeCode, headerHTML, footerHTML)
    }
    if err != nil {
        writeProblem(w, err)
        return
    }
    // Report an advance failure honestly: the letter IS numbered but the task still pends —
    // a retry lands in the already-numbered branch above and converges (idempotent).
    if err := s.workflow.CompleteNumberForSubject(r.Context(), p, "letter", inst.SubjectID); err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusOK, map[string]any{"number": number})
}

            // Complete an ASSIGN-NUMBER workflow task: the registrar (task assignee) picks
            // the scheme and the engine runs the letter's gapless numbering, completes the
            // task and advances the chain. Task-holder authorized — the engine-scoped twin
            // of POST /letters/{id}/number (which stays creator/corr-admin gated). Module-
            // gated like the letters group (letter tasks only exist with correspondence on).
            r.With(s.requireModule("correspondence"), s.requirePerm("workflow.act")).Post("/workflow/tasks/{taskID}/number", s.CompleteNumberTask)

          kind: (s.kind === 'sign'
            ? 'sign'
            : s.kind === 'meterai'
              ? 'meterai'
              : s.kind === 'sign_external'
                ? 'sign_external'
                : s.kind === 'stamp'
                  ? 'stamp'
                  : s.kind === 'number'
                    ? 'number'
                    : 'approve') as StepKind,

          {hasNumber && (
            <span className="wf-graph__legend-item">
              <span className="wf-graph__swatch wf-graph__swatch--number" />
              {t('workflows.graph.number')}
            </span>
          )}

/* Assign-number step: cyan — the registrar issues the official letter number. */
.wf-graph__node--number rect {
  fill: var(--cds-tag-background-cyan, #bae6ff);
  stroke: var(--cds-tag-color-cyan, #00539a);
}
.wf-graph__node--number text {
  fill: var(--cds-tag-color-cyan, #00539a);
}
.wf-graph__node--number .wf-graph__glyph circle {
  fill: var(--cds-tag-color-cyan, #00539a);
}

.wf-graph__swatch--number {
  background: var(--cds-tag-background-cyan, #bae6ff);
  border-color: var(--cds-tag-color-cyan, #00539a);
}

.wf-builder__steps .wf-builder__step--number {
  border-left: 3px solid var(--cds-tag-color-cyan, #00539a);
}

export function StartWorkflowOnDocModal({ open, docId, onClose, subjectType = 'document', onPreset }: { open: boolean; docId: string; onClose: () => void; subjectType?: string; onPreset?: () => void }) {

    const preset: WorkflowPick[] =
      !isDoc && onPreset && me?.customWorkflowsEnabled
        ? [{ id: PRESET_FULL_CORRESPONDENCE, name: t('workflows.picker.presetFullCorr'), kind: 'preset' as const, ownerName: '', mine: false }]
        : []
    // Preset first, then standards, then customs; group headings via firstOfGroup as before.
    return [...preset, ...standard, ...custom].map((it, i, all) => ({ ...it, firstOfGroup: i === 0 || all[i - 1].kind !== it.kind }))

    if (!picked || start.isPending) return
    if (picked.kind === 'preset') {
      // Hand off to the letter page, which opens the custom builder prefilled with
      // Approve → Assign number → Sign over this letter.
      onPreset?.()
      onClose()
      return
    }

              {(status === 'draft' || status === 'rejected' || status === 'approved' || numbered) && canManage && me?.customWorkflowsEnabled && (

// The "Full correspondence flow" preset: Approve → Assign number → Sign. Assignees are
// picked in the builder; names stay empty so steps auto-label by kind in both locales.
const FULL_CORRESPONDENCE_STEPS: StepInput[] = [
  { name: '', approver_position_ids: [], kind: 'approve' },
  { name: '', approver_position_ids: [], kind: 'number' },
  { name: '', approver_position_ids: [], kind: 'sign' },
]

      {startingWf && (
        <StartWorkflowOnDocModal
          open
          docId={letter.id}
          subjectType="letter"
          onClose={() => setStartingWf(false)}
          onPreset={() => {
            setStartingWf(false)
            setPresetWf(true)
          }}
        />
      )}
      {/* The preset opens the EXISTING run-once builder prefilled over THIS letter: the
          user only picks WHO approves / numbers / signs. No scheme input anywhere at start
          — the registrar picks the scheme when completing the number task. */}
      {presetWf && (
        <CustomWorkflowModal
          open
          onClose={() => setPresetWf(false)}
          fixedSubject={{ id: letter.id, label: letter.subject }}
          fixedSubjectType="letter"
          initialName={t('correspondence.chain.presetName')}
          initialSteps={FULL_CORRESPONDENCE_STEPS}
          onStarted={() => {
            qc.invalidateQueries({ queryKey: ['letter', letter.id] })
            qc.invalidateQueries({ queryKey: ['letter-tasks', letter.id] })
            qc.invalidateQueries({ queryKey: ['workflow-instances'] })
            qc.invalidateQueries({ queryKey: ['correspondence'] })
          }}
        />
      )}

          action: t.ActionRequired === 'sign' ? 'sign' : t.ActionRequired === 'meterai' ? 'meterai' : t.ActionRequired === 'stamp' ? 'stamp' : t.ActionRequired === 'number' ? 'number' : 'approve',

              action:
                t.ActionRequired === 'sign' ? 'sign' : t.ActionRequired === 'meterai' ? 'meterai' : t.ActionRequired === 'stamp' ? 'stamp' : t.ActionRequired === 'number' ? 'number' : 'approve',

// Complete an ASSIGN-NUMBER workflow task (the registrar's engine-scoped numbering):
// POST /workflow/tasks/{taskID}/number with the picked scheme (+ optional letterhead for an
// HTML letter; ignored for docx, whose letterhead is its seed document). The backend runs
// the gapless AssignNumber path with task-holder authorization, completes the task and
// advances the chain — so every task/letter/register surface refreshes.
export function useCompleteNumberTask(letterId: string) {
  const qc = useQueryClient()
  return useMutation({
    mutationFn: ({ taskId, schemeCode, letterheadId }: { taskId: string; schemeCode: string; letterheadId: string }) =>
      req(`/workflow/tasks/${taskId}/number`, {
        method: 'POST',
        body: JSON.stringify({ scheme_code: schemeCode, letterhead_id: letterheadId }),
      }),
    onSuccess: () => {
      qc.invalidateQueries({ queryKey: ['letter', letterId] })
      qc.invalidateQueries({ queryKey: ['letter-tasks', letterId] })
      qc.invalidateQueries({ queryKey: ['letter-seals', letterId] })
      qc.invalidateQueries({ queryKey: ['correspondence'] })
      qc.invalidateQueries({ queryKey: ['approvals'] })
      qc.invalidateQueries({ queryKey: ['workflow-instances'] })
    },
  })
}

// AssignNumberModal — scheme picker + live next-number preview + (HTML letters) optional
// letterhead. Extracted from LetterDetailView so BOTH numbering surfaces share one modal:
//  - direct numbering (creator/corr-admin): POST /letters/{id}/number (useAssignNumber)
//  - workflow NUMBER task (taskId set): POST /workflow/tasks/{taskId}/number — task-holder
//    authorized; completing it advances the chain.
import { useState } from 'react'
import { useTranslation } from 'react-i18next'
import { Dropdown, InlineNotification, Modal } from '@carbon/react'
import {
  useAssignNumber,
  useCompleteNumberTask,
  useNumberingSchemes,
  useSchemeNumberPreview,
} from '@/api/correspondence'
import { useLetterheads } from '@/api/letterhead'

const NO_TEMPLATE = '__none__'

export function AssignNumberModal({
  letterId,
  authoring,
  taskId,
  onClose,
}: {
  letterId: string
  authoring: string
  // When set, submitting completes THIS workflow task instead of the direct endpoint.
  taskId?: string
  onClose: () => void
}) {
  const { t } = useTranslation()
  const assign = useAssignNumber()
  const completeTask = useCompleteNumberTask(letterId)
  const { data: schemes = [] } = useNumberingSchemes()
  const { data: letterheads = [] } = useLetterheads()
  const [schemeCode, setSchemeCode] = useState('')
  const [letterheadId, setLetterheadId] = useState(NO_TEMPLATE)
  const [error, setError] = useState<string | null>(null)
  const { data: previewNumber } = useSchemeNumberPreview(schemeCode)

  const schemeItems = schemes.map((s) => ({ id: s.code, label: `${s.code} — ${s.pattern}` }))
  const schemeItem = schemeItems.find((s) => s.id === schemeCode) ?? null
  const letterheadItems = [{ id: NO_TEMPLATE, label: t('correspondence.assign.noTemplate') }, ...letterheads.map((l) => ({ id: l.id, label: l.name }))]
  const letterheadItem = letterheadItems.find((l) => l.id === letterheadId) ?? letterheadItems[0]
  const valid = schemeCode !== ''
  const busy = assign.isPending || completeTask.isPending

  const submit = () => {
    if (!valid || busy) return
    setError(null)
    const lh = authoring === 'docx' || letterheadId === NO_TEMPLATE ? '' : letterheadId
    const opts = { onSuccess: onClose, onError: (e: unknown) => setError((e as Error).message) }
    if (taskId) completeTask.mutate({ taskId, schemeCode, letterheadId: lh }, opts)
    else assign.mutate({ id: letterId, schemeCode, letterheadId: lh }, opts)
  }

  return (
    <Modal
      open
      size="sm"
      modalHeading={t('correspondence.assign.title')}
      primaryButtonText={t('correspondence.assign.confirm')}
      secondaryButtonText={t('detail.cancel')}
      primaryButtonDisabled={!valid || busy}
      onRequestClose={onClose}
      onRequestSubmit={submit}
    >
      <p className="page__lead muted">{t(taskId ? 'correspondence.assign.taskLead' : 'correspondence.assign.lead')}</p>
      {/* Numbering freezes the content — say so BEFORE the irreversible click, in the
          repo's quiet low-contrast warning style. */}
      <InlineNotification
        kind="warning"
        lowContrast
        hideCloseButton
        className="assign-lock-note"
        title={t('correspondence.assign.lockWarning')}
      />
      {/* autoAlign floats the menu (floating-ui, position:fixed) so it escapes the modal's
          overflow clip instead of rendering under the footer buttons — the same fix the
          workflow/MCP/EditFolder modal pickers use (commit 15d05ac). */}
      <Dropdown
        id="assign-scheme"
        autoAlign
        titleText={t('correspondence.assign.scheme')}
        label={schemeItem?.label ?? t('correspondence.assign.schemePlaceholder')}
        items={schemeItems}
        selectedItem={schemeItem}
        itemToString={(i) => i?.label ?? ''}
        onChange={({ selectedItem }) => setSchemeCode(selectedItem?.id ?? '')}
      />
      {schemeCode !== '' && previewNumber && (
        <p className="assign-preview">
          {t('correspondence.assign.nextNumber')} <span className="mono assign-preview__num">{previewNumber}</span>
          <span className="muted assign-preview__note"> {t('correspondence.assign.nextNumberNote')}</span>
        </p>
      )}
      {authoring !== 'docx' && (
        <div className="newdoc__field">
          <Dropdown
            id="assign-template"
            autoAlign
            titleText={t('correspondence.assign.template')}
            label={letterheadItem?.label ?? ''}
            items={letterheadItems}
            selectedItem={letterheadItem}
            itemToString={(i) => i?.label ?? ''}
            onChange={({ selectedItem }) => selectedItem && setLetterheadId(selectedItem.id)}
          />
        </div>
      )}
      {error && <InlineNotification kind="error" lowContrast hideCloseButton title={error} />}
    </Modal>
  )
}

            {task.action === 'number' && (
              <Button size="sm" kind="primary" renderIcon={NumberIcon} onClick={() => setNumberTask(task)}>
                {t('correspondence.detail.assign')}
              </Button>
            )}

      {/* The NUMBER task's ceremony: the shared scheme-picker modal, submitting to the
          engine-scoped task endpoint (completes the task + advances the chain). */}
      {numberTask && (
        <AssignNumberModal letterId={letter.id} authoring={letter.authoring} taskId={numberTask.id} onClose={() => setNumberTask(null)} />
      )}

# 0) sanity: schemes exist (STD)
curl -sf -H "$AUTH" "$API/numbering-schemes" | jq -r '.schemes[].code'   # expect STD

# 1) fresh draft letter (docx if the office fixture is handy, else HTML — both paths are wired)
LETTER=$(curl -sf -H "$AUTH" -H 'Content-Type: application/json' -d '{"subject":"e2e number step","body_html":"<p>halo</p>","classification":"Internal"}' "$API/letters" | jq -r .id)

# 2) start the Full correspondence flow (approve → number → sign), director on every step
INST=$(curl -sf -H "$AUTH" -H 'Content-Type: application/json' -d "{\"name\":\"Full correspondence flow\",\"subject_type\":\"letter\",\"subject_id\":\"$LETTER\",\"steps\":[
  {\"name\":\"\",\"approver_position_ids\":[],\"kind\":\"approve\",\"assignee_user_ids\":[\"$DIR\"]},
  {\"name\":\"\",\"approver_position_ids\":[],\"kind\":\"number\",\"assignee_user_ids\":[\"$DIR\"]},
  {\"name\":\"\",\"approver_position_ids\":[],\"kind\":\"sign\",\"assignee_user_ids\":[\"$DIR\"]}]}" \
  "$API/workflow/custom" | jq -r .instance_id)
curl -sf -H "$AUTH" "$API/letters/$LETTER" | jq -r .status          # in_review  (T2b flip)

# 3) approve step
curl -sf -H "$AUTH" "$API/workflows/inbox" | jq '.[] | select(.State=="pending") | {ID,ActionRequired}'
curl -sf -X POST -H "$AUTH" -H 'Content-Type: application/json' -d '{"action":"approve","note":""}' "$API/workflow/instances/$INST/act-definition" -o /dev/null -w '%{http_code}\n'   # 204; letter stays in_review

# 4) number task (scheme STD at completion — no scheme was pinned)
TASK=$(curl -sf -H "$AUTH" "$API/workflows/inbox" | jq -r '.[] | select(.State=="pending" and .ActionRequired=="number") | .ID')
curl -sf -X POST -H "$AUTH" -H 'Content-Type: application/json' -d '{"scheme_code":"STD"}' "$API/workflow/tasks/$TASK/number" | jq .   # {"number":"…"}
curl -sf -H "$AUTH" "$API/letters/$LETTER" | jq '{status,number}'   # numbered + number set

# 5) sign task → letter seal ceremony (per the letter-chain memory recipe; internal sig or
#    OTP resume via GET /letters/$LETTER/pending-seal as shipped) → seal_rev 1
curl -sf -X POST -H "$AUTH" -H 'Content-Type: application/json' -d "$SIGN_BODY" "$API/letters/$LETTER/sign" | jq .
curl -sf -H "$AUTH" "$API/letters/$LETTER/seals" | jq '.[0]'        # rev 1; instance now approved

# 6) terminal act stays manual
curl -sf -X POST -H "$AUTH" "$API/letters/$LETTER/sent" -o /dev/null -w '%{http_code}\n'   # 204

# NEGATIVES (each must fail with the exact code):
# a) definition-save order: sign before number → 400 workflow.custom.invalid_steps
curl -s -X POST -H "$AUTH" -H 'Content-Type: application/json' -d "{\"name\":\"bad\",\"visibility\":\"private\",\"steps\":[{\"name\":\"\",\"approver_position_ids\":[\"$POS\"],\"kind\":\"sign\"},{\"name\":\"\",\"approver_position_ids\":[\"$POS\"],\"kind\":\"number\"}]}" "$API/workflow/custom/save" | jq -r .detail
#    → "The Assign-number step must come before any signature, e-Meterai or stamp step"
# b) number chain over the NOW-NUMBERED letter → 409 correspondence.workflow.already_numbered
#    (repeat step 2 against $LETTER … but it is sent now — create a second letter, number it
#     directly via POST /letters/{id}/number, THEN repeat step 2 → 409)
# c) non-assignee completion → 403 workflow.number.not_assignee (second user session, repeat
#    step 4's POST on a fresh chain's number task)
# d) number step over a DOCUMENT subject → 4xx correspondence.workflow.number_letter_only
#    (step 2 body with subject_type document + any doc id)
# e) regression: DOCUMENT approve→sign chain unchanged (start one over a test doc, sign,
#    confirm advance — the document path must be byte-identical)