Unify Signature Workflows — ONE Engine

import (
    "encoding/json"
    "strings"
    "time"
)

// Completion rules for a step with more than one assignee.
const (
    // CompletionAny: the FIRST assignee to act decides the step. This is the legacy
    // default — an absent/empty `completion` key reads as "any", so every jsonb step
    // written before this field existed keeps behaving exactly as it always has.
    CompletionAny = "any"
    // CompletionAll: EVERY assignee must act before the step completes. This is what the
    // "Request signature" preset always meant (it hard-coded the rule in the service
    // instead of in the step); the designer can now ask for it too.
    CompletionAll = "all"
)

// IsValidCompletion reports whether c is a recognised completion rule. The empty string
// is accepted because it is the legacy/default encoding of "any".
func IsValidCompletion(c string) bool {
    switch c {
    case "", CompletionAny, CompletionAll:
        return true
    }
    return false
}

// SignaturePlacement is a PRE-PLACED visible-signature rectangle in PDF points with origin
// BOTTOM-LEFT (the space the page MediaBox lives in); Page is 1-based. It is exactly the
// geometry the signer's own placement modal already produces — captured earlier, by the
// sender at request time or the author at design time — so the signer's ceremony opens on
// the box instead of a blank page. It is a SUGGESTION: the signer can still move it, and the
// PAdES adapter clamps it to the page and silently falls back to its default box when the
// rect is unusable, so a stale placement can never fail a sign.
type SignaturePlacement struct {
    Page        int     `json:"page"`
    LowerLeftX  float64 `json:"llx"`
    LowerLeftY  float64 `json:"lly"`
    UpperRightX float64 `json:"urx"`
    UpperRightY float64 `json:"ury"`
}

// Placement map keys. A step's Placements map is keyed by an assignee REF so one step can
// pre-place a different box per signer. The prefixes keep the namespaces disjoint: a user id
// can never collide with a free-text contact-slot label.
//
// There is deliberately no position ref: you cannot pre-place a box for a holder you cannot
// name, and keying by position would force ResolveActors to run once per position instead of
// once per step. A position step uses PlacementRefDefault instead.
const (
    placementRefUserPrefix    = "user:"
    placementRefContactPrefix = "contact:"
    // PlacementRefDefault is the step-level fallback box, applied to any assignee with no
    // ref of their own. "*" carries no prefix, so it can never collide with a real ref.
    PlacementRefDefault = "*"
)

// PlacementRefUser is the Placements key for an individually named signer.
func PlacementRefUser(userID string) string { return placementRefUserPrefix + userID }

// PlacementRefContact is the Placements key for an external contact slot, keyed by the
// slot's label (the only stable identity a slot has before the requester fills it in).
func PlacementRefContact(slot string) string { return placementRefContactPrefix + slot }

// StepSpec is one step in a no-code workflow definition: a human-readable name plus WHO must
// act. Assignees come from ApproverPositionIDs (whose live holders the Resolver expands at
// fan-out) and/or AssigneeUserIDs (individually named users) — unioned and de-duped, one
// pending task each. Kind decides what the task is: an approval ("approve", the default), a
// signature ("sign"), an e-Meterai affix ("meterai") or an external signature
// ("sign_external", which routes to contact slots instead of people).
//
// EVERY field after SignKind is `omitempty` on purpose: a step written before that field
// existed re-serialises byte-identically and unmarshals to the zero value, which the
// accessors below map back to exactly the legacy behavior. That is the whole back-compat
// contract for the jsonb steps column — do not remove an omitempty.
type StepSpec struct {
    Name                string   `json:"name"`
    ApproverPositionIDs []string `json:"approver_position_ids"`
    // StepKind is "approve" (default), "sign", "meterai" or "sign_external". omitempty
    // keeps the jsonb backward-compatible: an approve step serialises WITHOUT a kind key,
    // so old rows that predate this field unmarshal to StepKind=="" and read as approve.
    StepKind string `json:"kind,omitempty"`
    // ContactSlot is the LEGACY single external-signer slot for a sign_external step (e.g.
    // "Client signatory"); the requester fills the actual contact at start. Superseded by
    // ContactSlots but still read (and still written by nothing) — use Contacts(), which
    // normalises both into one slice. Empty for every other kind.
    ContactSlot string `json:"contact_slot,omitempty"`
    // SignKind is the suggested signature tier ("internal"|"global"|"psre") for a sign or
    // sign_external step — a hint carried onto the ceremony, not a hard constraint. Empty
    // = the provider/adapter default.
    SignKind string `json:"sign_kind,omitempty"`

    // AssigneeUserIDs names INDIVIDUAL users who each receive a task when the step
    // activates, expanded ALONGSIDE ApproverPositionIDs (union, de-duped by user id). A
    // step may name positions, users, or both. Unlike a position holder, a named assignee
    // is NEVER routed through the availability/substitute resolver: naming someone is an
    // identity claim ("Alice must sign"), not a fungible duty, and for a Global signature
    // request the envelope's signer phones must line up with the task assignees.
    AssigneeUserIDs []string `json:"assignee_user_ids,omitempty"`
    // StepCompletion is "any" (the first assignee to act decides the step — the legacy
    // default for every step ever written) or "all" (every assignee must act before the
    // step advances). Read it through Completion(), never directly. See also
    // app.effectiveCompletion, which layers the one legacy exception on top.
    StepCompletion string `json:"completion,omitempty"`
    // ContactSlots are the labelled external-signer slots for a sign_external step — one
    // outside party each, one envelope each, all of which must sign before the step
    // advances. Read it through Contacts(), which folds in the legacy single ContactSlot.
    ContactSlots []string `json:"contact_slots,omitempty"`
    // Placements are OPTIONAL pre-placed signature boxes keyed by assignee ref
    // (PlacementRefUser / PlacementRefContact / PlacementRefDefault). Absent = the signer
    // places their own box, which is what every step did before this field existed. Read it
    // through PlacementFor().
    Placements map[string]SignaturePlacement `json:"placements,omitempty"`
}

// Completion returns the step's completion rule, defaulting an empty/legacy value to "any"
// (first-to-act wins — exactly how every step behaved before this field existed).
func (s StepSpec) Completion() string {
    if s.StepCompletion == CompletionAll {
        return CompletionAll
    }
    return CompletionAny
}

// Contacts normalises a sign_external step's slots into one slice: the legacy single
// ContactSlot first (every such step written before ContactSlots existed), then any
// ContactSlots, trimmed, blanks dropped, de-duped, order stable. A legacy step yields
// exactly one slot, so callers that loop over Contacts() reproduce today's behavior.
func (s StepSpec) Contacts() []string {
    out := make([]string, 0, 1+len(s.ContactSlots))
    seen := map[string]bool{}
    add := func(c string) {
        c = strings.TrimSpace(c)
        if c == "" || seen[c] {
            return
        }
        seen[c] = true
        out = append(out, c)
    }
    add(s.ContactSlot)
    for _, c := range s.ContactSlots {
        add(c)
    }
    return out
}

// DeclaresAssignees reports whether the step names anyone at all to route to: positions,
// individual users, or (for an external signature) contact slots. A step that declares
// nobody has nothing to fan out — that is not an error at fan-out time, because the
// envelope-backed signature request whose signers are ALL external legitimately holds zero
// internal tasks. ValidateSteps rejects such a step in every AUTHORING path, so it is only
// ever reachable from that preset.
func (s StepSpec) DeclaresAssignees() bool {
    return len(s.ApproverPositionIDs) > 0 || len(s.AssigneeUserIDs) > 0 || len(s.Contacts()) > 0
}

// PlacementFor returns the pre-placed box for an assignee ref, falling back to the
// step-level default ("*"), and finally reporting ok=false — meaning "nobody pre-placed one;
// the signer places their own box", the behavior of every step before Placements existed.
func (s StepSpec) PlacementFor(ref string) (SignaturePlacement, bool) {
    if len(s.Placements) == 0 {
        return SignaturePlacement{}, false
    }
    if pl, ok := s.Placements[ref]; ok {
        return pl, true
    }
    if pl, ok := s.Placements[PlacementRefDefault]; ok {
        return pl, true
    }
    return SignaturePlacement{}, false
}

// ValidateSteps reports whether a step list is a well-formed definition body. Returns the
// bool/string pair (rather than a *kernel.Error) so the domain stays stdlib-only; the app
// layer maps a failure to kernel.ErrValidation.
//
// Every step must name at least one assignee: an approve/sign/meterai step needs at least one
// approver position OR one named user; a sign_external step needs at least one contact slot
// and must NOT name positions or users (it routes outside the org).
//
// e-Meterai ordering rules: a meterai step must come AFTER at least one sign step (the
// provider refuses to stamp an unsigned document — the affix service enforces signed-first,
// so an earlier placement could never complete), and a definition may carry at most ONE
// meterai step (the ledger enforces one stamp per document).
//
// IMPORTANT: this guards the AUTHORING paths only (DefineWorkflow, ReviseWorkflow,
// StartCustomWorkflow, SaveCustomWorkflow). RequestSignatures does NOT call it — and must
// not: an all-external Global request legitimately builds a step with zero internal
// assignees, whose instance is a 0-task mirror the envelope's roster finalize advances.
func ValidateSteps(steps []StepSpec) (ok bool, reason string) {
    if len(steps) == 0 {
        return false, "definition must have at least one step"
    }
    signSeen := false
    meteraiSeen := false
    for _, st := range steps {
        if !IsValidStepKind(st.StepKind) {
            return false, "step has an unknown kind"
        }
        if !IsValidCompletion(st.StepCompletion) {
            return false, "step has an unknown completion rule"
        }
        // An empty id would resolve to nobody and silently break the fan-out.
        for _, pid := range st.ApproverPositionIDs {
            if pid == "" {
                return false, "step has an empty approver position id"
            }
        }
        for _, uid := range st.AssigneeUserIDs {
            if uid == "" {
                return false, "step has an empty assignee user id"
            }
        }
        if pok, preason := validatePlacements(st); !pok {
            return false, preason
        }
        named := len(st.ApproverPositionIDs) > 0 || len(st.AssigneeUserIDs) > 0
        switch st.Kind() {
        case StepKindSignExternal:
            // External-sign steps route to an outside party, not to the org: they name
            // contact SLOTS (filled at start) and must carry neither positions nor users.
            if len(st.ApproverPositionIDs) != 0 {
                return false, "an external signature step cannot name positions"
            }
            if len(st.AssigneeUserIDs) != 0 {
                return false, "an external signature step cannot name internal users"
            }
            if len(st.Contacts()) == 0 {
                return false, "an external signature step needs a contact slot label"
            }
            signSeen = true
        case StepKindSign:
            if !named {
                return false, "a signature step needs at least one position or named signer"
            }
            signSeen = true
        case StepKindMeterai:
            if !named {
                return false, "step has no approver positions"
            }
            if meteraiSeen {
                return false, "definition may have at most one e-Meterai step"
            }
            if !signSeen {
                return false, "an e-Meterai step must come after a signature step"
            }
            meteraiSeen = true
        default: // approve (including the legacy empty kind)
            if !named {
                return false, "step has no approver positions"
            }
        }
    }
    return true, ""
}

// validatePlacements rejects a step whose Placements map references an assignee the step does
// not declare. A typo'd ref would never apply, which reads to the author as "my pre-placed box
// was silently ignored" — an authoring error deserves an authoring-time failure. The
// step-level default ("*") is always allowed, and each rect must be usable.
func validatePlacements(st StepSpec) (ok bool, reason string) {
    if len(st.Placements) == 0 {
        return true, ""
    }
    valid := map[string]bool{PlacementRefDefault: true}
    for _, uid := range st.AssigneeUserIDs {
        valid[PlacementRefUser(uid)] = true
    }
    for _, c := range st.Contacts() {
        valid[PlacementRefContact(c)] = true
    }
    for ref, pl := range st.Placements {
        if !valid[ref] {
            return false, "step has a placement for an assignee it does not name: " + ref
        }
        if pl.Page < 1 {
            return false, "a placement needs a 1-based page number"
        }
        if pl.UpperRightX <= pl.LowerLeftX || pl.UpperRightY <= pl.LowerLeftY {
            return false, "a placement needs a non-empty rectangle"
        }
    }
    return true, ""
}

func TestCompletionDefaultsToAny(t *testing.T) {
    // A legacy step (no completion key) must read as first-to-act — the behavior of every
    // step ever written before the field existed.
    if got := (StepSpec{}).Completion(); got != CompletionAny {
        t.Fatalf("legacy Completion() = %q, want %q", got, CompletionAny)
    }
    if got := (StepSpec{StepCompletion: CompletionAll}).Completion(); got != CompletionAll {
        t.Fatalf("Completion() = %q, want %q", got, CompletionAll)
    }
    // An unknown value must never read as "all" (fail closed to the legacy rule).
    if got := (StepSpec{StepCompletion: "bogus"}).Completion(); got != CompletionAny {
        t.Fatalf("unknown Completion() = %q, want %q", got, CompletionAny)
    }
}

func TestContactsNormalisesLegacySlot(t *testing.T) {
    cases := []struct {
        name string
        step StepSpec
        want []string
    }{
        {"legacy single", StepSpec{ContactSlot: "Client"}, []string{"Client"}},
        {"new multi", StepSpec{ContactSlots: []string{"Client", "Witness"}}, []string{"Client", "Witness"}},
        {"legacy + new, de-duped", StepSpec{ContactSlot: "Client", ContactSlots: []string{"Client", "Witness"}}, []string{"Client", "Witness"}},
        {"blanks dropped", StepSpec{ContactSlots: []string{" ", "Client", ""}}, []string{"Client"}},
        {"none", StepSpec{}, []string{}},
    }
    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {
            got := c.step.Contacts()
            if len(got) != len(c.want) {
                t.Fatalf("Contacts() = %v, want %v", got, c.want)
            }
            for i := range got {
                if got[i] != c.want[i] {
                    t.Fatalf("Contacts() = %v, want %v", got, c.want)
                }
            }
        })
    }
}

func TestPlacementForFallsBackToDefault(t *testing.T) {
    mine := SignaturePlacement{Page: 2, LowerLeftX: 10, LowerLeftY: 10, UpperRightX: 100, UpperRightY: 50}
    def := SignaturePlacement{Page: 1, LowerLeftX: 36, LowerLeftY: 36, UpperRightX: 276, UpperRightY: 108}
    st := StepSpec{Placements: map[string]SignaturePlacement{
        PlacementRefUser("u1"): mine,
        PlacementRefDefault:    def,
    }}
    if pl, ok := st.PlacementFor(PlacementRefUser("u1")); !ok || pl != mine {
        t.Fatalf("PlacementFor(u1) = %v/%v, want %v/true", pl, ok, mine)
    }
    if pl, ok := st.PlacementFor(PlacementRefUser("u2")); !ok || pl != def {
        t.Fatalf("PlacementFor(u2) = %v/%v, want the default %v/true", pl, ok, def)
    }
    if _, ok := (StepSpec{}).PlacementFor(PlacementRefUser("u1")); ok {
        t.Fatal("PlacementFor on a step with no placements must report ok=false")
    }
}

func TestValidateStepsNewFields(t *testing.T) {
    pos := []string{"p1"}
    cases := []struct {
        name string
        step StepSpec
        ok   bool
    }{
        {"sign by named user only", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"}}, true},
        {"sign by position only", StepSpec{Name: "S", StepKind: StepKindSign, ApproverPositionIDs: pos}, true},
        {"sign by both", StepSpec{Name: "S", StepKind: StepKindSign, ApproverPositionIDs: pos, AssigneeUserIDs: []string{"u1"}}, true},
        {"sign by nobody", StepSpec{Name: "S", StepKind: StepKindSign}, false},
        {"approve by named user only", StepSpec{Name: "A", AssigneeUserIDs: []string{"u1"}}, true},
        {"empty assignee id", StepSpec{Name: "A", AssigneeUserIDs: []string{""}}, false},
        {"completion all", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"}, StepCompletion: CompletionAll}, true},
        {"completion any", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"}, StepCompletion: CompletionAny}, true},
        {"completion bogus", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"}, StepCompletion: "sometimes"}, false},
        {"external multi-slot", StepSpec{Name: "E", StepKind: StepKindSignExternal, ContactSlots: []string{"Client", "Witness"}}, true},
        {"external with users", StepSpec{Name: "E", StepKind: StepKindSignExternal, ContactSlots: []string{"Client"}, AssigneeUserIDs: []string{"u1"}}, false},
        {"placement for a named user", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"},
            Placements: map[string]SignaturePlacement{PlacementRefUser("u1"): {Page: 1, UpperRightX: 10, UpperRightY: 10}}}, true},
        {"placement default ref", StepSpec{Name: "S", StepKind: StepKindSign, ApproverPositionIDs: pos,
            Placements: map[string]SignaturePlacement{PlacementRefDefault: {Page: 1, UpperRightX: 10, UpperRightY: 10}}}, true},
        {"placement for an unknown user", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"},
            Placements: map[string]SignaturePlacement{PlacementRefUser("nobody"): {Page: 1, UpperRightX: 10, UpperRightY: 10}}}, false},
        {"placement page 0", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"},
            Placements: map[string]SignaturePlacement{PlacementRefUser("u1"): {Page: 0, UpperRightX: 10, UpperRightY: 10}}}, false},
        {"placement empty rect", StepSpec{Name: "S", StepKind: StepKindSign, AssigneeUserIDs: []string{"u1"},
            Placements: map[string]SignaturePlacement{PlacementRefUser("u1"): {Page: 1}}}, false},
    }
    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {
            ok, reason := ValidateSteps([]StepSpec{c.step})
            if ok != c.ok {
                t.Fatalf("ValidateSteps ok = %v (reason %q), want %v", ok, reason, c.ok)
            }
            if !ok && reason == "" {
                t.Fatal("ValidateSteps returned !ok with an empty reason")
            }
        })
    }
}

func TestStepSpecJSONBackCompat(t *testing.T) {
    // The whole jsonb contract: a step with no new fields set must serialise WITHOUT any new
    // key, so existing rows round-trip byte-identically.
    b, err := MarshalSteps([]StepSpec{{Name: "Review", ApproverPositionIDs: []string{"p1"}}})
    if err != nil {
        t.Fatal(err)
    }
    const want = `[{"name":"Review","approver_position_ids":["p1"]}]`
    if string(b) != want {
        t.Fatalf("MarshalSteps = %s, want %s", b, want)
    }
    // And a legacy row unmarshals to exactly the legacy behavior.
    steps, err := UnmarshalSteps([]byte(`[{"name":"Signature","kind":"sign"}]`))
    if err != nil {
        t.Fatal(err)
    }
    if len(steps) != 1 || steps[0].Kind() != StepKindSign || steps[0].Completion() != CompletionAny ||
        steps[0].DeclaresAssignees() || len(steps[0].Contacts()) != 0 {
        t.Fatalf("legacy step read as %+v", steps[0])
    }
}

-- +goose Up
-- Pre-placed signature boxes + multi-slot external signing, for the unified signature engine.
--
-- workflow_tasks.placement is the box a sender (Request signature) or a workflow author (a
-- sign step in the designer) placed AHEAD of the ceremony. The box itself lives in the step's
-- jsonb spec (no migration needed there — StepSpec.Placements is omitempty), and fan-out seeds
-- it onto each task so the signer's placement modal opens on it. NULL = nobody pre-placed one
-- and the signer places their own, which is exactly what every existing row means.
--
-- Shape: {"page":1,"llx":36,"lly":36,"urx":276,"ury":108} — PDF points, origin BOTTOM-LEFT,
-- page 1-based: the same geometry the signer's modal emits and the PAdES adapter clamps.
ALTER TABLE workflow_tasks ADD COLUMN placement jsonb;

-- The envelope roster's per-signer box: where an external / Global signer's signature lands,
-- captured by the sender at request time. NULL = the adapter's default box, which is what
-- every existing row means (signerPlacement() returned nil for every roster signer).
ALTER TABLE esign_envelope_signers ADD COLUMN placement jsonb;

-- workflow_instances.external_slots_done marks which of a sign_external step's contact SLOTS
-- have had their envelope completed, keyed "<stepIndex>#<slotIndex>" (both 0-based slot,
-- 1-based step). The step advances only once every slot is done. NULL/absent = none done,
-- which is correct for every existing row: a legacy step has exactly one slot, so it advances
-- on that slot's completion exactly as it does today.
ALTER TABLE workflow_instances ADD COLUMN external_slots_done jsonb;

-- esign_sign_envelopes.step_slot is the 0-based contact slot within step_index that this
-- envelope fulfils, so its completion marks exactly that slot. Existing envelopes default to
-- slot 0 — the only slot a legacy single-slot step has. (Mirrors how step_index was added in
-- 00095_workflow_external_sign.sql.)
ALTER TABLE esign_sign_envelopes ADD COLUMN step_slot int NOT NULL DEFAULT 0;

-- +goose Down
ALTER TABLE esign_sign_envelopes DROP COLUMN step_slot;
ALTER TABLE workflow_instances DROP COLUMN external_slots_done;
ALTER TABLE esign_envelope_signers DROP COLUMN placement;
ALTER TABLE workflow_tasks DROP COLUMN placement;

    // Placement is the OPTIONAL pre-placed visible-signature box, seeded from the step at
    // fan-out because the sender/author placed it. nil = the signer places their own box in
    // their ceremony — the behavior of every task created before this field existed. Only
    // ever set on a sign task (an approval or affix has no signature appearance).
    Placement *SignaturePlacement

// taskColumns is the workflow_tasks column list, in the order scanTask reads them.
// taskColumnsT is the same list qualified for a query that JOINs workflow_instances.
const taskColumns = `id, instance_id, assignee_user_id, action_required, state, instruction, ` +
    `sla_deadline, escalated, created_at, completed_at, recommended, placement`

const taskColumnsT = `t.id, t.instance_id, t.assignee_user_id, t.action_required, t.state, t.instruction, ` +
    `t.sla_deadline, t.escalated, t.created_at, t.completed_at, t.recommended, t.placement`

// InsertTask persists a pending inbox task. instruction carries a disposition's routing note
// (empty for ordinary approval/forward tasks); placement carries the pre-placed signature box
// the step seeded (NULL when nobody pre-placed one).
func (s *Store) InsertTask(ctx context.Context, tk domain.Task) error {
    var placement any
    if tk.Placement != nil {
        b, err := json.Marshal(tk.Placement)
        if err != nil {
            return fmt.Errorf("workflow marshal task placement: %w", err)
        }
        placement = b
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO workflow_tasks (`+taskColumns+`)
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)`,
        tk.ID, tk.InstanceID, tk.AssigneeUserID, tk.ActionRequired, tk.State, tk.Instruction,
        tk.SLADeadline, tk.Escalated, tk.CreatedAt, tk.CompletedAt, tk.Recommended, placement); err != nil {
        return fmt.Errorf("workflow insert task: %w", err)
    }
    return nil
}

    rows, err := s.db.Exec(ctx).Query(ctx,
        `SELECT `+taskColumns+`
           FROM workflow_tasks WHERE instance_id = $1 AND state = $2 ORDER BY created_at`,
        instanceID, domain.TaskStatePending)

    rows, err := s.db.Exec(ctx).Query(ctx,
        `SELECT `+taskColumnsT+`
           FROM workflow_tasks t
           JOIN workflow_instances i ON i.id = t.instance_id
          WHERE t.assignee_user_id = $1
            AND t.state = $2
            AND t.action_required = $3
            AND i.subject_type = $4
            AND i.subject_id = $5
            AND i.definition_version_id IS NOT NULL
            AND i.state = $6
          ORDER BY t.created_at`,
        userID, domain.TaskStatePending, domain.StepKindSign, subjectType, subjectID, string(domain.StateSubmitted))

    query := `SELECT ` + taskColumns + `
           FROM workflow_tasks
          WHERE state = $1 AND NOT escalated AND sla_deadline IS NOT NULL AND sla_deadline < $2
          ORDER BY sla_deadline`

func scanTask(row scanner) (domain.Task, error) {
    var tk domain.Task
    var placement []byte
    if err := row.Scan(&tk.ID, &tk.InstanceID, &tk.AssigneeUserID, &tk.ActionRequired, &tk.State,
        &tk.Instruction, &tk.SLADeadline, &tk.Escalated, &tk.CreatedAt, &tk.CompletedAt,
        &tk.Recommended, &placement); err != nil {
        return domain.Task{}, err
    }
    // A corrupt placement is never fatal: the signer just places their own box (the same
    // degradation the PAdES adapter applies to an unusable rect).
    if len(placement) > 0 {
        var pl domain.SignaturePlacement
        if err := json.Unmarshal(placement, &pl); err == nil {
            tk.Placement = &pl
        }
    }
    return tk, nil
}

// stepAssignee is one resolved actor for a step plus their provenance: a position's live
// holder (substitutable — the duty belongs to the position, not the person) or an
// individually named user (verbatim — the author named THEM).
type stepAssignee struct {
    userID       string
    fromPosition bool
}

// stepAssignees expands a step's assignees: the live holders of its approver positions UNION
// its individually named users, de-duped by user id, positions first then named users (stable
// order). A user who is both a holder and named keeps their position provenance (first entry
// wins), so they route through availability like their peers on that position.
//
// The position set is resolved in ONE bulk ResolveActors call, exactly as before — placements
// are never keyed by position, so there is no reason to resolve them one at a time.
// Read-only; runs inside the caller's UnitOfWork.
func (s *Service) stepAssignees(ctx context.Context, step domain.StepSpec, now time.Time) ([]stepAssignee, error) {
    out := make([]stepAssignee, 0, len(step.ApproverPositionIDs)+len(step.AssigneeUserIDs))
    seen := map[string]bool{}
    if len(step.ApproverPositionIDs) > 0 {
        holders, err := s.resolver.ResolveActors(ctx, step.ApproverPositionIDs, now)
        if err != nil {
            return nil, err
        }
        for _, uid := range holders {
            if uid == "" || seen[uid] {
                continue
            }
            seen[uid] = true
            out = append(out, stepAssignee{userID: uid, fromPosition: true})
        }
    }
    for _, uid := range step.AssigneeUserIDs {
        if uid == "" || seen[uid] {
            continue
        }
        seen[uid] = true
        out = append(out, stepAssignee{userID: uid})
    }
    return out, nil
}

// taskPlacement is the pre-placed signature box a fanned-out assignee's task carries: their
// own ref's box, else the step-level default, else nil (they place their own). Only a SIGN
// task carries one — an approval or an e-Meterai affix has no signature appearance (the
// affix ceremony positions its own square stamp).
func taskPlacement(step domain.StepSpec, a stepAssignee) *domain.SignaturePlacement {
    if step.Kind() != domain.StepKindSign {
        return nil
    }
    pl, ok := step.PlacementFor(domain.PlacementRefUser(a.userID))
    if !ok {
        return nil
    }
    return &pl
}

// fanOutStep expands a step's assignees — the live holders of its approver positions PLUS any
// individually named users, unioned and de-duped — and inserts one pending task each, seeded
// with the step's pre-placed signature box when it has one, emitting workflow.task_assigned so
// every assignee is actually notified.
//
// This is the ONLY path that creates a STEP's tasks: the admin designer, the ad-hoc custom
// builder AND the "Request signature" preset all land here, so they can never diverge and all
// notify identically. (Dispose/Forward/escalation create tasks too, but they are not steps.)
//
// A step that DECLARES assignees (positions and/or users) but resolves to nobody is a
// kernel.ErrValidation — there is nobody to act on it. A step that declares NOBODY fans out to
// zero tasks and is NOT an error: that is the envelope-backed signature request whose signers
// are all external (no Obscura account → no task), whose instance is a 0-task mirror the
// envelope's roster finalize (FinalizeInstance) advances. ValidateSteps rejects a no-assignee
// step in every authoring path, so this case is reachable only from that preset.
//
// Named users are assigned VERBATIM: the availability/substitute resolver runs only on
// position-resolved holders. Naming someone is an identity claim ("Alice must sign"), not a
// fungible duty — and for a Global request the envelope's signer phones must line up with the
// task assignees. Runs inside the caller's UnitOfWork.
func (s *Service) fanOutStep(ctx context.Context, instanceID, subjectType, subjectID string, step domain.StepSpec, stepIndex int, recommendedUserID, initiator string, contacts map[string]domain.ExternalContact, now time.Time) error {
    // A sign_external step has no position to resolve — it mints one envelope per contact
    // slot for the outside parties instead of tasks.
    if step.Kind() == domain.StepKindSignExternal {
        return s.fanOutExternalSign(ctx, instanceID, stepIndex, subjectType, subjectID, step, initiator, contacts)
    }
    assignees, err := s.stepAssignees(ctx, step, now)
    if err != nil {
        return err
    }
    if len(assignees) == 0 {
        if !step.DeclaresAssignees() {
            return nil // envelope-backed mirror: no internal signer holds a task
        }
        return &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.step.no_approvers", Message: "no approvers resolved for step '" + step.Name + "'"}
    }
    // An e-Meterai step is only completable by a meterai.affix holder, so fail the fan-out
    // LOUDLY when the named position resolved to zero permitted users — the requester picked
    // the wrong position; better an immediate error than a workflow stuck on a task nobody
    // may complete.
    if step.Kind() == domain.StepKindMeterai && s.affixPermChecker != nil {
        permitted := false
        for _, a := range assignees {
            if s.affixPermChecker(ctx, a.userID, step.ApproverPositionIDs) {
                permitted = true
                break
            }
        }
        if !permitted {
            return &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.step.no_affixers",
                Message: "no holder of the positions on step '" + step.Name + "' is permitted to affix an e-Meterai"}
        }
    }
    for _, a := range assignees {
        assignee := a.userID
        if a.fromPosition {
            // Position-resolved holders route through availability/delegation; a NAMED
            // assignee never does (see the doc comment).
            eff, aerr := s.effectiveAssignee(ctx, a.userID)
            if aerr != nil {
                return aerr
            }
            assignee = eff
        }
        tk := domain.Task{
            ID:             kernel.NewID(),
            InstanceID:     instanceID,
            AssigneeUserID: assignee,
            ActionRequired: step.Kind(), // "approve", "sign" or "meterai"
            State:          domain.TaskStatePending,
            CreatedAt:      now,
            // Flag the recommended holder (compared pre-substitution) so their inbox
            // highlights it; any holder can still act.
            Recommended: recommendedUserID != "" && a.userID == recommendedUserID,
            Placement:   taskPlacement(step, a),
        }
        if err := s.repo.InsertTask(ctx, tk); err != nil {
            return err
        }
        if s.events != nil {
            payload, _ := json.Marshal(map[string]any{
                "user_id":         assignee,
                "instance_id":     instanceID,
                "subject_type":    subjectType,
                "subject_id":      subjectID,
                "action_required": step.Kind(),
            })
            if err := s.events.Publish(ctx, kernel.DomainEvent{
                Aggregate:   "workflow",
                AggregateID: instanceID,
                Type:        "workflow.task_assigned",
                Payload:     payload,
            }); err != nil {
                return err
            }
        }
    }
    return nil
}

// fanOutExternalSign mints the sign_external step's one-signer envelope via the wired
// ExternalSignRequester (esign-backed). No task is created — the step is "active" via
// current_step, and the envelope's completion advances it (AdvanceExternalSignStep).
// Fails the fan-out LOUDLY when the contact is missing or external signing isn't wired,
// so a misconfigured step can never silently stall.
func (s *Service) fanOutExternalSign(ctx context.Context, instanceID string, stepIndex int, subjectType, subjectID string, step domain.StepSpec, initiator string, contacts map[string]domain.ExternalContact) error {
    contact := contactForStep(contacts, stepIndex)
    if contact == nil || contact.Email == "" {
        return &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.step.no_contact",
            Message: "external signature step '" + step.Name + "' has no signer contact"}
    }
    if s.externalSignRequester == nil {
        return &kernel.Error{Kind: kernel.ErrConflict, Code: "workflow.external_sign.unsupported",
            Message: "external signing is not configured on this deployment"}
    }
    return s.externalSignRequester.RequestExternalSign(ctx, ExternalSignRequest{
        InstanceID:      instanceID,
        StepIndex:       stepIndex,
        SubjectType:     subjectType,
        SubjectID:       subjectID,
        InitiatorUserID: initiator,
        Contact:         *contact,
        SignKind:        step.SignKind,
    })
}

// effectiveCompletion resolves the completion rule that governs a step, carrying the ONE
// legacy exception the jsonb demands.
//
// A step whose spec predates the `completion` field reads as StepCompletion=="" →
// Completion()=="any" (first-to-act wins). That is right for every legacy step EXCEPT those
// inside a signature_request definition: those were minted by the old RequestSignatures
// preset, which hard-coded ALL-must-sign in the SERVICE (a `def.Kind == signature_request`
// branch) instead of in the step, so their stored step carries no completion key at all. An
// unset completion inside a signature_request therefore means "all".
//
// New presets write completion:"all" explicitly and take the same branch, so this fallback is
// needed only for instances already in flight — but they pin their version forever, so it can
// never be removed.
func effectiveCompletion(step domain.StepSpec, defKind string) string {
    if step.StepCompletion == "" && defKind == domain.DefinitionKindSignatureRequest {
        return domain.CompletionAll
    }
    return step.Completion()
}

            if inst.CurrentStep < 1 || inst.CurrentStep > len(ver.Steps) {
                continue
            }
            step := ver.Steps[inst.CurrentStep-1]
            if effectiveCompletion(step, def.Kind) == domain.CompletionAll {
                // ALL-must-sign: complete ONLY this signer's own task; the step finishes only
                // once every assignee's task is done. (Multi-party signature requests, and any
                // designer step that asks for every named signer.)
                if err := s.repo.CompleteTask(ctx, t.ID, now); err != nil {
                    return err
                }
                remaining, err := s.repo.ListPendingTasksForInstance(ctx, inst.ID)
                if err != nil {
                    return err
                }
                if len(remaining) > 0 {
                    // Partial: record this signature; the step stays open until the rest sign.
                    if err := s.repo.InsertTransition(ctx, domain.Transition{
                        ID:         kernel.NewID(),
                        InstanceID: inst.ID,
                        FromState:  inst.State,
                        ToState:    domain.StateSubmitted,
                        Action:     domain.ActionSign,
                        Actor:      string(p.UserID),
                        Note:       "signed",
                        CreatedAt:  now,
                    }); err != nil {
                        return err
                    }
                    continue
                }
                // Everyone has signed. Advance like any other completed step — to the NEXT
                // step, or to approved on the last one. For a one-step signature request this
                // emits exactly the transition the old hard-coded branch emitted
                // (submitted→approved, action=sign, note="signed"); for a multi-step
                // definition it correctly runs the rest of the workflow instead of jumping to
                // approved.
                if err := s.advanceApprovedInstance(ctx, inst, ver, string(p.UserID), "signed", domain.ActionSign, now); err != nil {
                    return err
                }
                continue
            }
            // Single-completes (the legacy default): the first signer decides the step.
            if err := s.advanceApprovedInstance(ctx, inst, ver, string(p.UserID), "signed", domain.ActionSign, now); err != nil {
                return err
            }

// CompleteSignatureForSubject advances any definition-driven workflow waiting on a SIGN step
// for (subjectType, subjectID), on behalf of p who just signed the subject. How the step
// completes is the STEP's business: an "all" step finishes only once every assignee has
// signed, an "any" step (the legacy default) is decided by the first signer. Either way the
// step then advances exactly like the approve path: to the next step or, on the last step, to
// Approved. It is a no-op (nil) when p holds no pending sign-task on a matching instance — the
// common case for ordinary (non-workflow) signing and for re-signs — so the best-effort esign
// hook never fails a successful sign.

        if def.Kind == domain.DefinitionKindSignatureRequest {
            continue
        }

        // An ALL-must-sign step names an exact roster — a superior may NOT sign in their
        // stead; that is precisely what "everyone named must sign" means. (This subsumes the
        // old signature_request exemption: those steps all resolve to "all".) Single-completes
        // steps stay rank-overrideable, exactly as before.
        if effectiveCompletion(step, def.Kind) == domain.CompletionAll {
            continue
        }
        // Note: a step that routes only to NAMED users has no positions to out-rank, so
        // CanOverride is asked about an empty position list and answers false — rank-override
        // simply does not apply to identity-routed steps.

// RequestSignatures creates a multi-party signature request. It is now a thin PRESET over the
// ordinary workflow engine: it mints a one-off definition whose single step is a REAL sign step
// naming the chosen users, asking for all-must-sign, carrying the tier and any boxes the sender
// pre-placed — and then fans that step out through the SAME fanOutStep every designer workflow
// uses. That is what makes each signer's task emit workflow.task_assigned, i.e. actually notify
// them (the old direct task insert did not, so nobody was ever prompted or nudged).
//
// signKind is the request's signature tier (internal|global|psre), signingOrder is
// "parallel"|"sequential", deadlineAt is the mandatory by-when, and placements optionally maps
// a signer's USER ID to the box the sender placed for them. Tasks are assigned to the exact
// users chosen (fanOutStep never substitutes a NAMED assignee) so the Global Mekari envelope's
// signer phones line up with the assignees. Sequential ENFORCEMENT (gating later signers) is
// added in a later phase; here all tasks are created pending. Returns the new instance id; the
// caller (HTTP handler) builds the Global envelope and links it.
//
// The definition keeps Kind=signature_request: it marks the definition as a ONE-OFF so it stays
// out of the designer's template list, and effectiveCompletion still reads it to keep instances
// created before the `completion` field existed all-must-sign.
func (s *Service) RequestSignatures(ctx context.Context, p kernel.Principal, subjectType, subjectID string, signerUserIDs []string, signKind, signingOrder string, deadlineAt time.Time, placements map[string]domain.SignaturePlacement) (string, error) {
    if subjectType == "" || subjectID == "" {
        return "", &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.request_sign.subject_required", Message: "subject type and id are required"}
    }
    // Zero internal signer ids is allowed: an envelope-backed (Global) request may have ONLY external
    // signers (no Obscura account → no workflow task). The instance is then a 0-task mirror that the
    // envelope's roster finalize advances (FinalizeInstance) — fanOutStep tolerates a step that
    // declares nobody for exactly this reason. The HTTP handler enforces ≥1 TOTAL signer.
    switch signKind {
    case "internal", "global", "psre":
    default:
        return "", &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.request_sign.bad_sign_kind", Message: "signature type must be internal, global or psre"}
    }
    sequential := false
    switch signingOrder {
    case "parallel":
    case "sequential":
        sequential = true
    default:
        return "", &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.request_sign.bad_order", Message: "signing order must be parallel or sequential"}
    }
    now := s.clock.Now()
    if !deadlineAt.After(now) || deadlineAt.After(now.Add(32*24*time.Hour)) {
        return "", &kernel.Error{Kind: kernel.ErrValidation, Code: "workflow.request_sign.bad_deadline", Message: "deadline must be in the future and within 31 days"}
    }
    // De-dupe signer ids while preserving order.
    seen := map[string]bool{}
    signers := make([]string, 0, len(signerUserIDs))
    for _, u := range signerUserIDs {
        if u == "" || seen[u] {
            continue
        }
        seen[u] = true
        signers = append(signers, u)
    }
    // The preset's step, expressed in exactly the vocabulary the designer uses.
    step := domain.StepSpec{
        Name:            "Signature",
        StepKind:        domain.StepKindSign,
        AssigneeUserIDs: signers,
        StepCompletion:  domain.CompletionAll,
        SignKind:        signKind,
    }
    // Only keep boxes for signers we actually kept (a placement for a dropped duplicate or an
    // unknown id would fail ValidateSteps in the designer; here it would just never apply).
    if len(placements) > 0 {
        pls := make(map[string]domain.SignaturePlacement, len(placements))
        for uid, pl := range placements {
            if !seen[uid] {
                continue
            }
            pls[domain.PlacementRefUser(uid)] = pl
        }
        if len(pls) > 0 {
            step.Placements = pls
        }
    }
    steps := []domain.StepSpec{step}
    definitionID := kernel.NewID()
    versionID := kernel.NewID()
    instanceID := kernel.NewID()
    deadline := deadlineAt
    err := s.uow.Do(ctx, func(ctx context.Context) error {
        if err := s.repo.InsertDefinition(ctx, domain.Definition{
            ID:        definitionID,
            Name:      "Signature request",
            CreatedBy: string(p.UserID),
            Kind:      domain.DefinitionKindSignatureRequest,
            CreatedAt: now,
        }); err != nil {
            return err
        }
        if err := s.repo.InsertDefinitionVersion(ctx, domain.DefinitionVersion{
            ID:           versionID,
            DefinitionID: definitionID,
            Version:      1,
            Steps:        steps,
            CreatedAt:    now,
        }); err != nil {
            return err
        }
        versionRef := versionID
        recommended := map[string]string{domain.RecommendedSignKindKey: signKind}
        if err := s.repo.InsertInstance(ctx, domain.Instance{
            ID:                  instanceID,
            SubjectType:         subjectType,
            SubjectID:           subjectID,
            State:               domain.StateSubmitted,
            Initiator:           string(p.UserID),
            DefinitionVersionID: &versionRef,
            CurrentStep:         1,
            Recommended:         recommended,
            SigningOrder:        sequential,
            DeadlineAt:          &deadline,
            CreatedAt:           now,
            UpdatedAt:           now,
        }); err != nil {
            return err
        }
        // The unification: ONE task per signer through the ordinary fan-out, which seeds each
        // task's pre-placed box and publishes workflow.task_assigned (in-app + email). Zero
        // signers (all-external Global) fans out to zero tasks and is not an error.
        if err := s.fanOutStep(ctx, instanceID, subjectType, subjectID, steps[0], 1, "", string(p.UserID), nil, now); err != nil {
            return err
        }
        return s.repo.InsertTransition(ctx, domain.Transition{
            ID:         kernel.NewID(),
            InstanceID: instanceID,
            FromState:  domain.StateDraft,
            ToState:    domain.StateSubmitted,
            Action:     domain.ActionSubmit,
            Actor:      string(p.UserID),
            CreatedAt:  now,
        })
    })
    if err != nil {
        return "", err
    }
    return instanceID, nil
}

    workflowdomain "github.com/Virtue-Digital-Indonesia/obscura/internal/workflow/domain"

        Signers []struct {
            UserID    string `json:"user_id"`
            Name      string `json:"name"`
            Email     string `json:"email"`
            Phone     string `json:"phone"`
            Placement *struct {
                Page int     `json:"page"`
                LLX  float64 `json:"llx"`
                LLY  float64 `json:"lly"`
                URX  float64 `json:"urx"`
                URY  float64 `json:"ury"`
            } `json:"placement"`
        } `json:"signers"`