Letters through the full workflow chain (approve → sign → e-Meterai → e-Stamp)

type SealSubject interface {
    CurrentPDF(ctx, subjectType, subjectID) (pdf []byte, rev int, err error)
    WriteSealedPDF(ctx, signer, in SealWrite) (rev int, err error)
}

-- +goose Up
-- Letter seal history (letter workflow chain). A letter has no document_versions row -- its PDF
-- is one content-addressed blob at letters.content_hash. When a workflow seals a numbered letter
-- (sign / e-Meterai / digital stamp) the sealed PDF becomes the new content_hash AND appends one
-- row here, so the letter keeps an auditable trail of its sealed revisions. rev 0 (kind 'base') is
-- the pre-chain numbered PDF, captured on the first seal; it is never voided and is the restore
-- floor when a rejected/cancelled run voids the seals it produced (mirrors dms.VoidSealedVersions
-- for documents, which mark-and-keep; letters mark-and-restore because they overwrite in place).
CREATE TABLE letter_seals (
    id           uuid PRIMARY KEY,
    letter_id    uuid NOT NULL REFERENCES letters(id) ON DELETE CASCADE,
    rev          int  NOT NULL,                     -- 0 = base (numbered PDF), 1..N = sealed revisions
    kind         text NOT NULL,                     -- 'base' | 'sign' | 'meterai' | 'stamp'
    content_hash text NOT NULL,                     -- addresses the PDF for this rev in the BlobStore
    created_by   uuid,                              -- signer/affixer (NULL for an attributed-less landing)
    created_at   timestamptz NOT NULL DEFAULT now(),
    voided_at    timestamptz                        -- set when a failed run voids this rev; base stays NULL
);

-- One row per (letter, rev); rev is gapless-monotonic per letter (MAX(rev)+1 under the letter row).
CREATE UNIQUE INDEX letter_seals_letter_rev_uniq ON letter_seals (letter_id, rev);
-- History + restore reads walk newest-first per letter.
CREATE INDEX letter_seals_letter_idx ON letter_seals (letter_id, rev DESC);

-- +goose Down
DROP TABLE letter_seals;

// Seal kinds recorded in letter_seals. 'base' is the pre-chain numbered PDF (rev 0); the rest
// mirror the workflow ceremony that produced the sealed revision.
const (
    SealKindBase    = "base"
    SealKindSign    = "sign"
    SealKindMeterai = "meterai"
    SealKindStamp   = "stamp"
)

// LetterSeal is one revision in a letter's seal history — the letter equivalent of a
// document_versions row for the seal trail. Rev 0 (SealKindBase) is the numbered PDF; VoidedAt is
// set when a rejected/cancelled workflow run voids the revision it produced.
type LetterSeal struct {
    ID          string     `json:"id"`
    LetterID    string     `json:"letter_id"`
    Rev         int        `json:"rev"`
    Kind        string     `json:"kind"`
    ContentHash string     `json:"-"` // internal blob hash, never serialized
    CreatedBy   string     `json:"created_by"`
    CreatedAt   time.Time  `json:"created_at"`
    VoidedAt    *time.Time `json:"voided_at"`
}

    // Letter seal history (letter workflow chain). UpdateLetterContentHash swaps the current
    // PDF WITHOUT touching status (the letter stays 'numbered'). InsertLetterSeal appends a
    // history row; MaxLetterSealRev is MAX(rev) for the letter (-1 when none, so the first
    // real seal is rev 1 after the rev-0 base). VoidLetterSealsSince marks the run's rows voided
    // and restores content_hash to the newest surviving rev (base is the floor).
    UpdateLetterContentHash(ctx context.Context, letterID, contentHash string, at time.Time) error
    InsertLetterSeal(ctx context.Context, ls domain.LetterSeal) error
    ListLetterSeals(ctx context.Context, letterID string) ([]domain.LetterSeal, error)
    MaxLetterSealRev(ctx context.Context, letterID string) (int, error)
    VoidLetterSealsSince(ctx context.Context, letterID string, since time.Time) error

// CurrentLetterPDF reads a numbered letter's current PDF bytes + its seal rev (0 when no seal has
// landed yet). It is the letter arm of the esign SealSubject.CurrentPDF port: the ceremony reads
// "the current sealable PDF" here instead of a document version. A letter with no content (draft)
// yields ErrConflict, exactly like OpenLetterContent.
func (s *Service) CurrentLetterPDF(ctx context.Context, letterID string) ([]byte, int, error) {
    l, err := s.repo.GetLetter(ctx, letterID)
    if err != nil {
        return nil, 0, err
    }
    if l.ContentHash == "" {
        return nil, 0, &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.letter.no_content", Message: "letter has no stored document yet"}
    }
    rc, err := s.blobs.Get(ctx, l.ContentHash)
    if err != nil {
        return nil, 0, err
    }
    defer rc.Close()
    b, err := io.ReadAll(rc)
    if err != nil {
        return nil, 0, err
    }
    rev, err := s.repo.MaxLetterSealRev(ctx, letterID)
    if err != nil {
        return nil, 0, err
    }
    if rev < 0 {
        rev = 0
    }
    return b, rev, nil
}

// WriteLetterSeal lands a freshly-sealed PDF as the letter's new content, appending a letter_seals
// history row — the letter arm of esign SealSubject.WriteSealedPDF. On the FIRST seal it also
// captures the pre-chain numbered PDF as rev 0 (SealKindBase) so a later void can restore it. All
// in one tx: capture-base → store sealed blob → append rev → swap content_hash (status untouched;
// the letter stays 'numbered'). signerUserID is the acting user ("" tolerated -> stored NULL).
// Returns the new rev.
func (s *Service) WriteLetterSeal(ctx context.Context, signerUserID, letterID, kind string, pdf []byte) (int, error) {
    l, err := s.repo.GetLetter(ctx, letterID)
    if err != nil {
        return 0, err
    }
    if l.ContentHash == "" {
        return 0, &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.letter.no_content", Message: "letter has no stored document to seal yet"}
    }
    hash, _, err := s.blobs.Put(ctx, bytes.NewReader(pdf), kernel.PutOpts{ContentType: "application/pdf"})
    if err != nil {
        return 0, err
    }
    var newRev int
    err = s.uow.Do(ctx, func(ctx context.Context) error {
        now := s.clock.Now()
        maxRev, err := s.repo.MaxLetterSealRev(ctx, letterID)
        if err != nil {
            return err
        }
        if maxRev < 0 {
            // First seal: freeze the current numbered PDF as the rev-0 base (the void restore floor).
            if err := s.repo.InsertLetterSeal(ctx, domain.LetterSeal{
                ID: kernel.NewID(), LetterID: letterID, Rev: 0, Kind: domain.SealKindBase,
                ContentHash: string(l.ContentHash), CreatedBy: signerUserID, CreatedAt: now,
            }); err != nil {
                return err
            }
            maxRev = 0
        }
        newRev = maxRev + 1
        if err := s.repo.InsertLetterSeal(ctx, domain.LetterSeal{
            ID: kernel.NewID(), LetterID: letterID, Rev: newRev, Kind: kind,
            ContentHash: string(hash), CreatedBy: signerUserID, CreatedAt: now,
        }); err != nil {
            return err
        }
        return s.repo.UpdateLetterContentHash(ctx, letterID, string(hash), now)
    })
    if err != nil {
        return 0, err
    }
    return newRev, nil
}

// ListLetterSeals returns a letter's seal history, newest first (base last).
func (s *Service) ListLetterSeals(ctx context.Context, letterID string) ([]domain.LetterSeal, error) {
    return s.repo.ListLetterSeals(ctx, letterID)
}

// VoidLetterSealsSince void-marks the seal revisions a failed (rejected/cancelled) run produced and
// restores content_hash to the newest surviving revision (rev 0 base is the floor, never voided).
// The letter arm of the workflow SealVoider; idempotent. The esign meterai/stamp LEDGER void is
// done separately by esign.VoidSealsSince (the composition root calls both).
func (s *Service) VoidLetterSealsSince(ctx context.Context, letterID string, since time.Time) error {
    return s.repo.VoidLetterSealsSince(ctx, letterID, since)
}

// UpdateLetterContentHash swaps the letter's current PDF blob WITHOUT changing status (a seal
// keeps the letter 'numbered'). Distinct from UpdateLetterNumbered, which also sets status+number.
func (s *Store) UpdateLetterContentHash(ctx context.Context, letterID, contentHash string, at time.Time) error {
    _, err := s.db.Exec(ctx).Exec(ctx,
        `UPDATE letters SET content_hash = $2, updated_at = $3 WHERE id = $1`, letterID, contentHash, at)
    if err != nil {
        return fmt.Errorf("correspondence update letter content hash: %w", err)
    }
    return nil
}

// InsertLetterSeal appends a seal-history row.
func (s *Store) InsertLetterSeal(ctx context.Context, ls domain.LetterSeal) error {
    var createdBy any
    if ls.CreatedBy != "" {
        createdBy = ls.CreatedBy
    }
    _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO letter_seals (id, letter_id, rev, kind, content_hash, created_by, created_at)
         VALUES ($1, $2, $3, $4, $5, $6, $7)`,
        ls.ID, ls.LetterID, ls.Rev, ls.Kind, ls.ContentHash, createdBy, ls.CreatedAt)
    if err != nil {
        return fmt.Errorf("correspondence insert letter seal: %w", err)
    }
    return nil
}

// ListLetterSeals returns a letter's seal history newest-first.
func (s *Store) ListLetterSeals(ctx context.Context, letterID string) ([]domain.LetterSeal, error) {
    rows, err := s.db.Exec(ctx).Query(ctx,
        `SELECT id, letter_id, rev, kind, content_hash, COALESCE(created_by::text, ''), created_at, voided_at
           FROM letter_seals WHERE letter_id = $1 ORDER BY rev DESC`, letterID)
    if err != nil {
        return nil, fmt.Errorf("correspondence list letter seals: %w", err)
    }
    defer rows.Close()
    var out []domain.LetterSeal
    for rows.Next() {
        var ls domain.LetterSeal
        if err := rows.Scan(&ls.ID, &ls.LetterID, &ls.Rev, &ls.Kind, &ls.ContentHash, &ls.CreatedBy, &ls.CreatedAt, &ls.VoidedAt); err != nil {
            return nil, fmt.Errorf("correspondence scan letter seal: %w", err)
        }
        out = append(out, ls)
    }
    return out, rows.Err()
}

// MaxLetterSealRev returns MAX(rev) for the letter, or -1 when there are no seal rows yet (so the
// service captures the rev-0 base on the first seal and the first sealed rev is 1).
func (s *Store) MaxLetterSealRev(ctx context.Context, letterID string) (int, error) {
    var rev *int
    if err := s.db.Exec(ctx).QueryRow(ctx,
        `SELECT MAX(rev) FROM letter_seals WHERE letter_id = $1`, letterID).Scan(&rev); err != nil {
        return 0, fmt.Errorf("correspondence max letter seal rev: %w", err)
    }
    if rev == nil {
        return -1, nil
    }
    return *rev, nil
}

// VoidLetterSealsSince void-marks the non-base rows created at/after `since` and restores
// content_hash to the newest surviving (non-voided) revision — rev 0 (base) is never voided, so a
// row always survives. Idempotent (already-void rows are skipped by the status guard).
func (s *Store) VoidLetterSealsSince(ctx context.Context, letterID string, since time.Time) error {
    ex := s.db.Exec(ctx)
    if _, err := ex.Exec(ctx,
        `UPDATE letter_seals SET voided_at = $3
           WHERE letter_id = $1 AND rev > 0 AND voided_at IS NULL AND created_at >= $2`,
        letterID, since, since); err != nil {
        return fmt.Errorf("correspondence void letter seals: %w", err)
    }
    // Restore the current PDF to the newest surviving revision (base survives as the floor).
    if _, err := ex.Exec(ctx,
        `UPDATE letters SET content_hash = sub.content_hash, updated_at = $2
           FROM (SELECT content_hash FROM letter_seals
                  WHERE letter_id = $1 AND voided_at IS NULL ORDER BY rev DESC LIMIT 1) sub
          WHERE letters.id = $1`, letterID, since); err != nil {
        return fmt.Errorf("correspondence restore letter content hash: %w", err)
    }
    return nil
}

// SealSubject is the subject-generic seal I/O port: it reads "the current sealable PDF" of a
// subject and writes a freshly-sealed PDF back as the subject's new revision. Two impls dispatch
// on subjectType at the composition root: "document" (DMS document_versions, byte-identical to the
// prior VersionReader/VersionWriter) and "letter" (letters.content_hash + a letter_seals row).
// Wired post-construction via SetSealSubject; nil on the synchronous mock path.
type SealSubject interface {
    // CurrentPDF reads the subject's current sealable PDF + its revision (a document's current
    // version; a letter's seal rev, 0 when unsealed).
    CurrentPDF(ctx context.Context, subjectType, subjectID string) (pdf []byte, rev int, err error)
    // WriteSealedPDF lands the sealed PDF as the subject's new revision and returns it.
    WriteSealedPDF(ctx context.Context, signer kernel.Principal, in SealWrite) (rev int, err error)
}

// SealWrite is the sealed-PDF landing request. SubjectType/SubjectID + PDF + Kind are universal;
// SourceRev and Note are DOCUMENT-only bookkeeping the letter impl ignores. SourceRev > 0 makes the
// document impl derive the new version's ROLE from that source version (the synchronous sign/meterai
// path); SourceRev == 0 writes with NO role (the async writeback + the synchronous STAMP path) —
// exactly reproducing today's two behaviors. Note is the version-status note ("" -> the impl uses
// its kind-default, matching the async twin).
type SealWrite struct {
    SubjectType string
    SubjectID   string
    SourceRev   int
    PDF         []byte
    Kind        string // "sign" | "meterai" | "stamp"
    Note        string
}

    // sealSubject is the subject-generic seal I/O port (async completion + in-house local sign).
    // Replaces the former versionWriter/versionReader; nil until SetSealSubject.
    sealSubject SealSubject

// SetSealSubject wires the subject-generic seal I/O port (composition root). Replaces
// SetVersionWriter/SetVersionReader.
func (s *Service) SetSealSubject(ss SealSubject) { s.sealSubject = ss }

        if s.sealSubject == nil {
            return false, &kernel.Error{Kind: kernel.ErrConflict, Code: "esign.async.no_writer", Message: "async completion is not wired (no seal subject)"}
        }
        // ... ClaimPendingSeal unchanged ...
        signer := kernel.Principal{UserID: kernel.UserID(ps.SignerUserID), Subject: ps.SignerSubject}
        newVersion, err := s.sealSubject.WriteSealedPDF(ctx, signer, SealWrite{
            SubjectType: ps.SubjectType, SubjectID: ps.SubjectID, PDF: sealedPDF, Kind: ps.Kind,
            // SourceRev 0 + Note "" -> async: no role, kind-default note (byte-identical to the old writer).
        })

        if s.sealSubject == nil {
            return false, 0, &kernel.Error{Kind: kernel.ErrConflict, Code: "esign.local.unwired", Message: "local signing is not fully configured"}
        }
        // ... ClaimSignerForSubmit unchanged ...
        curPDF, curVer, rerr := s.sealSubject.CurrentPDF(ctx, env.SubjectType, env.SubjectID)
        // ... preSealMarkEmail(env.SubjectType, env.SubjectID, curVer, curPDF, ...) unchanged (it no-ops for non-document) ...
        newVersion, aerr := s.sealSubject.WriteSealedPDF(ctx, kernel.Principal{}, SealWrite{
            SubjectType: env.SubjectType, SubjectID: env.SubjectID, PDF: signedPDF, Kind: "sign",
        })

        if s.sealSubject == nil {
            return false, 0, &kernel.Error{Kind: kernel.ErrConflict, Code: "esign.async.no_writer", Message: "async completion is not wired (no seal subject)"}
        }
        // ... ClaimSignEnvelope + author selection unchanged ...
        newVersion, err := s.sealSubject.WriteSealedPDF(ctx, author, SealWrite{
            SubjectType: env.SubjectType, SubjectID: env.SubjectID, PDF: sealedPDF, Kind: "sign",
        })

        if s.sealSubject == nil {
            return "", fmt.Errorf("esign: seal subject not wired for external sign step")
        }
        pdf, version, err := s.sealSubject.CurrentPDF(ctx, in.SubjectType, in.SubjectID)

// sealSubjectRouter implements the esign SealSubject port over BOTH the DMS (document subjects) and
// the correspondence service (letter subjects), dispatching on subjectType. The document branch is
// byte-identical to the former dmsVersionReader/dmsSignedVersionWriter — it IS that code behind the
// new interface. The letter branch reads/writes letters.content_hash + a letter_seals row.
type sealSubjectRouter struct {
    dms  *dmsapp.Service
    corr *correspondenceapp.Service
}

func (r sealSubjectRouter) CurrentPDF(ctx context.Context, subjectType, subjectID string) ([]byte, int, error) {
    switch subjectType {
    case "letter":
        return r.corr.CurrentLetterPDF(ctx, subjectID)
    default: // "document" (and any legacy subject that used the DMS reader)
        doc, err := r.dms.GetDocument(ctx, subjectID)
        if err != nil {
            return nil, 0, err
        }
        rc, err := r.dms.OpenVersionContent(ctx, subjectID, doc.CurrentVersion)
        if err != nil {
            return nil, 0, err
        }
        defer rc.Close()
        b, err := io.ReadAll(rc)
        if err != nil {
            return nil, 0, err
        }
        return b, doc.CurrentVersion, nil
    }
}

func (r sealSubjectRouter) WriteSealedPDF(ctx context.Context, signer kernel.Principal, in esignapp.SealWrite) (int, error) {
    if in.SubjectType == "letter" {
        return r.corr.WriteLetterSeal(ctx, string(signer.UserID), in.SubjectID, in.Kind, in.PDF)
    }
    return r.writeDocument(ctx, signer, in)
}

// writeDocument is the former dmsSignedVersionWriter.AddSignedVersion, byte-identical, extended only
// to derive the new version's role from in.SourceRev when SourceRev>0 (the synchronous sign/meterai
// write did WithVersionRole(derivedRole); SourceRev==0 keeps the async + sync-stamp no-role write).
func (r sealSubjectRouter) writeDocument(ctx context.Context, signer kernel.Principal, in esignapp.SealWrite) (int, error) {
    docID := in.SubjectID
    // Empty signer (all-external envelope): attribute the version to the document owner.
    if signer.UserID == "" {
        if doc, derr := r.dms.GetDocument(ctx, docID); derr == nil && doc.OwnerID != "" {
            signer = kernel.Principal{UserID: kernel.UserID(doc.OwnerID)}
        }
    }
    // Idempotent land: reuse the current version if it is already this exact sealed content.
    sum := sha256.Sum256(in.PDF)
    hash := hex.EncodeToString(sum[:])
    v := 0
    if doc, derr := r.dms.GetDocument(ctx, docID); derr == nil && doc.CurrentVersion > 0 {
        if cur, verr := r.dms.GetVersion(ctx, docID, doc.CurrentVersion); verr == nil && string(cur.ContentHash) == hash {
            v = doc.CurrentVersion
        }
    }
    if v == 0 {
        opts := []dmsapp.VersionOpt{}
        if in.SourceRev > 0 {
            opts = append(opts, dmsapp.WithVersionRole(r.derivedRole(ctx, docID, in.SourceRev)))
        }
        nv, err := r.dms.AddVersion(ctx, signer, docID, bytes.NewReader(in.PDF), "application/pdf", opts...)
        if err != nil {
            var pgErr *pgconn.PgError
            if errors.As(err, &pgErr) && pgErr.Code == "23505" {
                return 0, &kernel.Error{Kind: kernel.ErrConflict, Code: "esign.version.concurrent_update", Message: "another signature just landed on this document — please try again"}
            }
            return 0, err
        }
        v = nv
    }
    status, note := r.docStatusNote(in.Kind, in.Note)
    _ = r.dms.SetVersionStatus(ctx, signer, docID, v, status, note)
    _ = r.dms.SetDocumentStatus(ctx, docID, dmsdomain.StatusDraft)
    return v, nil
}

// derivedRole mirrors httpapi.derivedRole: a sealed PDF inherits its source version's role.
func (r sealSubjectRouter) derivedRole(ctx context.Context, docID string, version int) string {
    if v, err := r.dms.GetVersion(ctx, docID, version); err == nil && v.Role != "" {
        return v.Role
    }
    return dmsdomain.RoleSource
}

// docStatusNote maps a seal kind to the version status enum + a note. An explicit note (the sync
// handlers pass their exact one) wins; "" falls back to the kind-default that the async writeback
// used — byte-identical to dmsSignedVersionWriter's old status/note.
func (r sealSubjectRouter) docStatusNote(kind, note string) (string, string) {
    switch kind {
    case "meterai":
        if note == "" {
            note = "e-Meterai affixed (external provider)"
        }
        return "meteraied", note
    case "stamp":
        if note == "" {
            note = "Digital stamp affixed (external provider)"
        }
        return "stamped", note
    default: // "sign"
        if note == "" {
            note = "Signed (external provider)"
        }
        return "signed", note
    }
}

type workflowSealVoider struct {
    dms   *dmsapp.Service
    esign *esignapp.Service
    corr  *correspondenceapp.Service
}

func (v workflowSealVoider) VoidSeals(ctx context.Context, subjectType, subjectID string, since time.Time, reason string) error {
    switch subjectType {
    case "letter":
        // Void the letter's sealed revisions (restore content_hash to the base) + the esign
        // meterai/stamp ledger rows for the letter (already subject-generic).
        if err := v.corr.VoidLetterSealsSince(ctx, subjectID, since); err != nil {
            return err
        }
        return v.esign.VoidSealsSince(ctx, subjectType, subjectID, since)
    case "document":
        if _, err := v.dms.VoidSealedVersionsSince(ctx, subjectID, since, reason); err != nil {
            return err
        }
        return v.esign.VoidSealsSince(ctx, subjectType, subjectID, since)
    default:
        return nil
    }
}

    sealRouter := sealSubjectRouter{dms: dmsSvc, corr: correspondenceSvc}
    esignSvc.SetSealSubject(sealRouter)
    esignSvc.SetWorkflowAdvancer(workflowSvc)
    // ... (unchanged lines) ...
    workflowSvc.SetSealVoider(workflowSealVoider{dms: dmsSvc, esign: esignSvc, corr: correspondenceSvc})

// in the Server struct:
    sealSubject esignapp.SealSubject

// in wire.go where the httpapi Server is built, pass sealRouter into that field
// (or add `func (s *Server) SetSealSubject(ss esignapp.SealSubject){ s.sealSubject = ss }` and call it).

// sealAndLand lands an already-sealed PDF for a subject and advances any waiting workflow ceremony
// step. It is the subject-generic tail extracted from the document sign/meterai/stamp handlers: the
// caller sealed `sealed` via s.esign.* (with the real subjectType/subjectID) and here we write it as
// the subject's new revision through the SealSubject port and fire the matching Complete*ForSubject
// hook. sourceRev>0 makes the DOCUMENT write derive a version role (sign/meterai); pass 0 to write
// with no role (STAMP, and every letter write). note is the version-status note (documents only).
// Returns the new revision.
func (s *Server) sealAndLand(ctx context.Context, p kernel.Principal, subjectType, subjectID, kind string, sealed []byte, sourceRev int, note string) (int, error) {
    rev, err := s.sealSubject.WriteSealedPDF(ctx, p, esignapp.SealWrite{
        SubjectType: subjectType, SubjectID: subjectID, SourceRev: sourceRev, PDF: sealed, Kind: kind, Note: note,
    })
    if err != nil {
        return 0, err
    }
    switch kind {
    case "meterai":
        _ = s.workflow.CompleteMeteraiForSubject(ctx, p, subjectType, subjectID)
    case "stamp":
        _ = s.workflow.CompleteStampForSubject(ctx, p, subjectType, subjectID)
    default:
        _ = s.workflow.CompleteSignatureForSubject(ctx, p, subjectType, subjectID)
    }
    return rev, nil
}

    // signed = res.Signed / SignPDF result — unchanged above.
    newVersion, err := s.sealAndLand(r.Context(), p, "document", docID, "sign", signed, version, "Signed by "+signerName)
    if err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusCreated, map[string]any{"signed_version": newVersion})

    newVersion, err := s.sealAndLand(r.Context(), p, "document", docID, "meterai", sealed, version, "e-Meterai affixed ("+rec.Serial+")")
    if err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusCreated, map[string]any{"meterai_version": newVersion, "serial": rec.Serial, "cost_idr": rec.CostIDR})

    newVersion, err := s.sealAndLand(r.Context(), p, "document", docID, "stamp", sealed, 0, "Digital stamp affixed")
    if err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusCreated, map[string]any{"stamp_version": newVersion, "order_ref": rec.OrderRef})

func (s *Server) guardActiveWorkflow(r *http.Request, subjectType, subjectID string) *kernel.Error {
    ctx := r.Context()
    p, _ := PrincipalFrom(ctx)
    insts, err := s.workflow.InstancesForSubject(ctx, subjectType, subjectID)
    // ... body unchanged, but every `docID`→`subjectID`, `"document"`→`subjectType` ...
}

// SignLetter signs a numbered letter's current PDF (internal or official tier) as the next seal
// revision. Mirrors SignDocumentVersion but over letters.content_hash (no version param, no
// interactive placement — letters use the default footer appearance). Requires the letter be
// numbered and the caller be permitted to seal it.
func (s *Server) SignLetter(w http.ResponseWriter, r *http.Request) {
    p, _ := PrincipalFrom(r.Context())
    letterID := chi.URLParam(r, "letterID")
    letter, err := s.correspondence.GetLetter(r.Context(), letterID)
    if err != nil {
        writeProblem(w, err)
        return
    }
    if ok, err := s.mayReadLetter(r.Context(), p, letter); err != nil {
        writeProblem(w, err)
        return
    } else if !ok {
        writeProblem(w, forbidLetterRead())
        return
    }
    if gerr := s.guardActiveWorkflow(r, "letter", letterID); gerr != nil {
        writeProblem(w, gerr)
        return
    }
    pdf, _, err := s.sealSubject.CurrentPDF(r.Context(), "letter", letterID)
    if err != nil {
        writeProblem(w, err)
        return
    }
    var body struct {
        SignatureID string `json:"signature_id"`
        Assurance   string `json:"assurance"`
        SignKind    string `json:"sign_kind"`
        SignerPhone string `json:"signer_phone"`
    }
    if r.Body != nil {
        _ = json.NewDecoder(r.Body).Decode(&body)
    }
    signerName := p.Subject
    if signerName == "" {
        signerName = string(p.UserID)
    }
    if body.SignatureID == "" && !(body.Assurance == string(esigndomain.AssuranceOfficial) && body.SignKind == "psre") {
        writeProblem(w, &kernel.Error{Kind: kernel.ErrValidation, Code: "esign.signature_required", Message: "add a signature in your profile and choose it to sign with"})
        return
    }
    var signed []byte
    if body.Assurance == string(esigndomain.AssuranceOfficial) {
        if !s.esign.ExternalAvailable() {
            writeProblem(w, &kernel.Error{Kind: kernel.ErrConflict, Code: "esign.external.not_configured", Message: "no external signature provider is configured"})
            return
        }
        if !s.canOfficialSign(r.Context(), p) {
            writeProblem(w, &kernel.Error{Kind: kernel.ErrPermissionDenied, Code: "esign.official.forbidden", Message: "you are not permitted to request an official signature"})
            return
        }
        res, serr := s.esign.SignOfficial(r.Context(), p, "letter", letterID, 0, signerName, pdf, body.SignatureID, nil, body.SignKind, body.SignerPhone)
        if serr != nil {
            writeProblem(w, serr)
            return
        }
        if res.OTPRequired {
            writeJSON(w, http.StatusAccepted, map[string]any{"status": "otp_required", "job_id": res.JobID, "otp_channel": res.OTPChannel})
            return
        }
        if res.Pending {
            writeJSON(w, http.StatusAccepted, map[string]any{"status": "pending", "signing_url": res.SigningURL, "job_id": res.JobID})
            return
        }
        signed = res.Signed
    } else {
        signed, err = s.esign.SignPDF(r.Context(), p, "letter", letterID, signerName, pdf, body.SignatureID, nil)
        if err != nil {
            writeProblem(w, err)
            return
        }
    }
    rev, err := s.sealAndLand(r.Context(), p, "letter", letterID, "sign", signed, 0, "")
    if err != nil {
        writeProblem(w, err)
        return
    }
    writeJSON(w, http.StatusCreated, map[string]any{"seal_rev": rev})
}

// AffixLetterMeterai / AffixLetterStamp mirror AffixDocumentMeterai / AffixDocumentStamp over a
// numbered letter (nil placement -> provider default square; async OTP/redirect handled identically
// -> the seal lands via the completion path, which routes through the letter arm of the port).
func (s *Server) AffixLetterMeterai(w http.ResponseWriter, r *http.Request) {
    p, _ := PrincipalFrom(r.Context())
    letterID := chi.URLParam(r, "letterID")
    letter, err := s.correspondence.GetLetter(r.Context(), letterID)
    if err != nil { writeProblem(w, err); return }
    if ok, err := s.mayReadLetter(r.Context(), p, letter); err != nil { writeProblem(w, err); return } else if !ok { writeProblem(w, forbidLetterRead()); return }
    if gerr := s.guardActiveWorkflow(r, "letter", letterID); gerr != nil { writeProblem(w, gerr); return }
    if !s.esign.MeteraiAvailable() { writeProblem(w, &kernel.Error{Kind: kernel.ErrConflict, Code: "esign.external.not_configured", Message: "no e-Meterai provider is configured"}); return }
    if !s.canAffixMeterai(r.Context(), p) { writeProblem(w, &kernel.Error{Kind: kernel.ErrPermissionDenied, Code: "esign.meterai.forbidden", Message: "you are not permitted to affix an e-Meterai"}); return }
    pdf, _, err := s.sealSubject.CurrentPDF(r.Context(), "letter", letterID)
    if err != nil { writeProblem(w, err); return }
    res, err := s.esign.AffixMeterai(r.Context(), p, "letter", letterID, 0, pdf, nil)
    if err != nil { writeProblem(w, err); return }
    if res.Pending { writeJSON(w, http.StatusAccepted, map[string]any{"status": "pending", "job_id": res.JobID}); return }
    rev, err := s.sealAndLand(r.Context(), p, "letter", letterID, "meterai", res.Sealed, 0, "")
    if err != nil { writeProblem(w, err); return }
    writeJSON(w, http.StatusCreated, map[string]any{"seal_rev": rev, "serial": res.Record.Serial, "cost_idr": res.Record.CostIDR})
}

func (s *Server) AffixLetterStamp(w http.ResponseWriter, r *http.Request) {
    p, _ := PrincipalFrom(r.Context())
    letterID := chi.URLParam(r, "letterID")
    letter, err := s.correspondence.GetLetter(r.Context(), letterID)
    if err != nil { writeProblem(w, err); return }
    if ok, err := s.mayReadLetter(r.Context(), p, letter); err != nil { writeProblem(w, err); return } else if !ok { writeProblem(w, forbidLetterRead()); return }
    if gerr := s.guardActiveWorkflow(r, "letter", letterID); gerr != nil { writeProblem(w, gerr); return }
    if !s.esign.StampAvailable() { writeProblem(w, &kernel.Error{Kind: kernel.ErrConflict, Code: "esign.external.not_configured", Message: "no digital-stamp provider is configured"}); return }
    if !s.canAffixStamp(r.Context(), p) { writeProblem(w, &kernel.Error{Kind: kernel.ErrPermissionDenied, Code: "esign.stamp.forbidden", Message: "you are not permitted to affix a digital stamp"}); return }
    pdf, _, err := s.sealSubject.CurrentPDF(r.Context(), "letter", letterID)
    if err != nil { writeProblem(w, err); return }
    fileName := letter.Number
    if fileName == "" { fileName = "letter" }
    res, err := s.esign.AffixStamp(r.Context(), p, "letter", letterID, 0, pdf, fileName, nil)
    if err != nil { writeProblem(w, err); return }
    if res.OTPRequired { writeJSON(w, http.StatusAccepted, map[string]any{"status": "otp_required", "job_id": res.JobID, "otp_channel": res.OTPChannel}); return }
    if res.Pending { writeJSON(w, http.StatusAccepted, map[string]any{"status": "pending", "job_id": res.JobID}); return }
    rev, err := s.sealAndLand(r.Context(), p, "letter", letterID, "stamp", res.Sealed, 0, "")
    if err != nil { writeProblem(w, err); return }
    writeJSON(w, http.StatusCreated, map[string]any{"seal_rev": rev, "order_ref": res.Record.OrderRef})
}

    r.With(s.requireModule("esign")).Group(func(r chi.Router) {
        r.With(s.requirePerm("esign.sign")).Post("/letters/{letterID}/sign", s.SignLetter)
        r.With(s.requirePerm("meterai.affix")).Post("/letters/{letterID}/meterai", s.AffixLetterMeterai)
        r.With(s.requirePerm("stamp.affix")).Post("/letters/{letterID}/stamp", s.AffixLetterStamp)
    })

// 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 — because a
// letter is sealed in place — any workflow that contains a SEAL step (sign/meterai/stamp) requires
// the letter to be NUMBERED first (decision: number-then-seal). Approve-only chains may run from a
// draft/rejected letter. Returns nil (no guard) for non-letter subjects.
func (s *Server) guardLetterWorkflowStart(ctx context.Context, p kernel.Principal, subjectType, subjectID string, steps []workflowdomain.StepSpec) *kernel.Error {
    if subjectType != "letter" {
        return nil
    }
    letter, err := s.correspondence.GetLetter(ctx, subjectID)
    if err != nil {
        return toProblem(err) // helper that coerces a kernel.Error / not-found to *kernel.Error
    }
    // Access: creator or correspondence admin (mirrors the document editor gate).
    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"}
    }
    hasSeal := false
    for _, st := range steps {
        switch st.Kind() {
        case workflowdomain.StepKindSign, workflowdomain.StepKindMeterai, workflowdomain.StepKindStamp, workflowdomain.StepKindSignExternal:
            hasSeal = true
        }
    }
    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
}