OnlyOffice-Authored Letters — Implementation Plan (2026-07-24)

-- +goose Up
-- OnlyOffice-authored letters: a letter (and a letterhead template) can now own a
-- docx artifact in the blob store. authoring selects the compose channel — 'html'
-- (plain text → Gotenberg Chromium, the original path; all existing rows) or 'docx'
-- (OnlyOffice-authored). draft_docx_hash addresses the CURRENT editable docx;
-- draft_docx_rev bumps on every OnlyOffice save and feeds the editor cache key
-- (letter_{id}_{rev}) so the doc-server never serves a stale copy. final_docx_hash
-- freezes the merge-field-substituted docx at numbering (cleared again if the
-- convert step fails and the allocation is voided). letterhead_id records the docx
-- template the letter was seeded from (ON DELETE SET NULL: the seed was zero-copied
-- into draft_docx_hash, so deleting the template never breaks the letter).
ALTER TABLE letters
    ADD COLUMN authoring       text NOT NULL DEFAULT 'html',
    ADD COLUMN draft_docx_hash text,
    ADD COLUMN draft_docx_rev  integer NOT NULL DEFAULT 0,
    ADD COLUMN final_docx_hash text,
    ADD COLUMN letterhead_id   uuid REFERENCES letterhead_templates(id) ON DELETE SET NULL;
ALTER TABLE letters
    ADD CONSTRAINT letters_authoring_chk CHECK (authoring IN ('html', 'docx'));

-- Letterhead templates gain an OnlyOffice-edited docx artifact (the kop lives in the
-- native Word header section). docx_rev mirrors draft_docx_rev: editor cache key fuel.
ALTER TABLE letterhead_templates
    ADD COLUMN docx_hash text,
    ADD COLUMN docx_rev  integer NOT NULL DEFAULT 0;

-- +goose Down
ALTER TABLE letterhead_templates DROP COLUMN IF EXISTS docx_rev;
ALTER TABLE letterhead_templates DROP COLUMN IF EXISTS docx_hash;
ALTER TABLE letters DROP CONSTRAINT IF EXISTS letters_authoring_chk;
ALTER TABLE letters DROP COLUMN IF EXISTS letterhead_id;
ALTER TABLE letters DROP COLUMN IF EXISTS final_docx_hash;
ALTER TABLE letters DROP COLUMN IF EXISTS draft_docx_rev;
ALTER TABLE letters DROP COLUMN IF EXISTS draft_docx_hash;
ALTER TABLE letters DROP COLUMN IF EXISTS authoring;

// Authoring channel for an outbound letter's content: 'html' (plain text wrapped to
// HTML, rendered by Gotenberg Chromium — the original path) or 'docx' (an
// OnlyOffice-authored Word document; numbering merge-substitutes the placeholder
// fields and converts the docx to the official PDF).
const (
    AuthoringHTML = "html"
    AuthoringDocx = "docx"
)

    // Docx authoring (OnlyOffice letters). Authoring is 'html' or 'docx'.
    // DraftDocxHash addresses the current editable docx in the BlobStore and
    // DraftDocxRev bumps on every editor save (it feeds the OnlyOffice cache key, so
    // a save always invalidates the doc-server's copy). FinalDocxHash freezes the
    // merge-field-substituted docx at numbering. LetterheadID records the docx
    // template chosen at creation. Blob hashes are internal — not serialized.
    Authoring     string `json:"authoring"`
    DraftDocxHash string `json:"-"`
    DraftDocxRev  int    `json:"-"`
    FinalDocxHash string `json:"-"`
    LetterheadID  string `json:"letterhead_id"`

// indonesianMonths are the Indonesian month names for the {{TANGGAL}} merge field.
// A manual table, not a locale package — the format is fixed by tata naskah, not by
// the runtime's locale data.
var indonesianMonths = [...]string{
    "Januari", "Februari", "Maret", "April", "Mei", "Juni",
    "Juli", "Agustus", "September", "Oktober", "November", "Desember",
}

// IndonesianLongDate renders t as the Indonesian long date used by {{TANGGAL}},
// e.g. "24 Juli 2026". Uses the time value as given (the service clock).
func IndonesianLongDate(t time.Time) string {
    return fmt.Sprintf("%d %s %d", t.Day(), indonesianMonths[int(t.Month())-1], t.Year())
}

// SifatLabel is the {{SIFAT}} merge value: the classification code as stored,
// except the 'none' default (and empty) renders as "-" — a letter with no sifat
// prints a dash, not the internal sentinel.
func SifatLabel(classification string) string {
    if classification == "" || classification == ClassificationNone {
        return "-"
    }
    return classification
}

    // Docx authoring. UpdateLetterDraftDocx lands an OnlyOffice save: it swaps the
    // draft blob hash and bumps draft_docx_rev, but ONLY while the letter is still
    // editable (status draft/rejected) — the SQL guard is the authoritative,
    // TOCTOU-free half of the F11-parity save re-check (0 rows → ErrConflict).
    // SetLetterFinalDocx records (hash != "") or clears (hash == "") the frozen
    // merged docx around the numbering conversion.
    UpdateLetterDraftDocx(ctx context.Context, letterID, hash string, at time.Time) error
    SetLetterFinalDocx(ctx context.Context, letterID, hash string, at time.Time) error

// InsertLetter persists a draft letter row.
func (s *Store) InsertLetter(ctx context.Context, l domain.Letter) error {
    direction := l.Direction
    if direction == "" {
        direction = domain.DirectionOutbound
    }
    authoring := l.Authoring
    if authoring == "" {
        authoring = domain.AuthoringHTML
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO letters (id, type, classification, subject, body_html, status, direction,
                              sender_type, sender_name, received_date, agenda_no, content_hash,
                              authoring, draft_docx_hash, draft_docx_rev, final_docx_hash, letterhead_id,
                              created_by, created_at, updated_at)
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20)`,
        l.ID, l.Type, l.Classification, l.Subject, l.BodyHTML, l.Status, direction,
        nilStr(l.SenderType), nilStr(l.SenderName), l.ReceivedDate, nilStr(l.AgendaNo), nilStr(string(l.ContentHash)),
        authoring, nilStr(l.DraftDocxHash), l.DraftDocxRev, nilStr(l.FinalDocxHash), nilStr(l.LetterheadID),
        l.CreatedBy, l.CreatedAt, l.UpdatedAt); err != nil {
        return fmt.Errorf("correspondence insert letter: %w", err)
    }
    return nil
}

// GetLetter loads a letter header.
func (s *Store) GetLetter(ctx context.Context, id string) (domain.Letter, error) {
    var l domain.Letter
    var number, hash, senderType, senderName, agendaNo, draftDocx, finalDocx, letterheadID *string
    err := s.db.Exec(ctx).QueryRow(ctx,
        `SELECT id, type, classification, subject, body_html, status, number, content_hash,
                direction, sender_type, sender_name, received_date, agenda_no,
                authoring, draft_docx_hash, draft_docx_rev, final_docx_hash, letterhead_id,
                created_by, created_at, updated_at
           FROM letters WHERE id = $1`, id).
        Scan(&l.ID, &l.Type, &l.Classification, &l.Subject, &l.BodyHTML, &l.Status, &number, &hash,
            &l.Direction, &senderType, &senderName, &l.ReceivedDate, &agendaNo,
            &l.Authoring, &draftDocx, &l.DraftDocxRev, &finalDocx, &letterheadID,
            &l.CreatedBy, &l.CreatedAt, &l.UpdatedAt)
    if errors.Is(err, pgx.ErrNoRows) {
        return domain.Letter{}, &kernel.Error{Kind: kernel.ErrNotFound, Code: "correspondence.letter.not_found", Message: "letter not found"}
    }
    if err != nil {
        return domain.Letter{}, fmt.Errorf("correspondence get letter: %w", err)
    }
    applyLetterNullables(&l, number, hash, senderType, senderName, agendaNo, draftDocx, finalDocx, letterheadID)
    return l, nil
}

// applyLetterNullables copies scanned nullable columns onto a Letter.
func applyLetterNullables(l *domain.Letter, number, hash, senderType, senderName, agendaNo, draftDocx, finalDocx, letterheadID *string) {
    if number != nil {
        l.Number = *number
    }
    if hash != nil {
        l.ContentHash = kernel.ContentHash(*hash)
    }
    if senderType != nil {
        l.SenderType = *senderType
    }
    if senderName != nil {
        l.SenderName = *senderName
    }
    if agendaNo != nil {
        l.AgendaNo = *agendaNo
    }
    if draftDocx != nil {
        l.DraftDocxHash = *draftDocx
    }
    if finalDocx != nil {
        l.FinalDocxHash = *finalDocx
    }
    if letterheadID != nil {
        l.LetterheadID = *letterheadID
    }
}

// ListLetters returns all letter headers, newest first.
func (s *Store) ListLetters(ctx context.Context) ([]domain.Letter, error) {
    rows, err := s.db.Exec(ctx).Query(ctx,
        `SELECT id, type, classification, subject, body_html, status, number, content_hash,
                direction, sender_type, sender_name, received_date, agenda_no,
                authoring, draft_docx_hash, draft_docx_rev, final_docx_hash, letterhead_id,
                created_by, created_at, updated_at
           FROM letters ORDER BY created_at DESC`)
    if err != nil {
        return nil, fmt.Errorf("correspondence list letters: %w", err)
    }
    defer rows.Close()
    var out []domain.Letter
    for rows.Next() {
        var l domain.Letter
        var number, hash, senderType, senderName, agendaNo, draftDocx, finalDocx, letterheadID *string
        if err := rows.Scan(&l.ID, &l.Type, &l.Classification, &l.Subject, &l.BodyHTML, &l.Status, &number, &hash,
            &l.Direction, &senderType, &senderName, &l.ReceivedDate, &agendaNo,
            &l.Authoring, &draftDocx, &l.DraftDocxRev, &finalDocx, &letterheadID,
            &l.CreatedBy, &l.CreatedAt, &l.UpdatedAt); err != nil {
            return nil, fmt.Errorf("correspondence scan letter: %w", err)
        }
        applyLetterNullables(&l, number, hash, senderType, senderName, agendaNo, draftDocx, finalDocx, letterheadID)
        out = append(out, l)
    }
    return out, rows.Err()
}

// UpdateLetterDraftDocx lands an OnlyOffice save on a docx letter: new draft blob,
// rev+1 (invalidates the editor cache key), fresh updated_at. Status-guarded IN SQL:
// only a still-editable letter (draft/rejected, per D4) accepts a save — a letter
// numbered or submitted while an editor was open rejects the late save with a
// conflict instead of silently overwriting official content (F11 parity).
func (s *Store) UpdateLetterDraftDocx(ctx context.Context, letterID, hash string, at time.Time) error {
    tag, err := s.db.Exec(ctx).Exec(ctx,
        `UPDATE letters SET draft_docx_hash = $2, draft_docx_rev = draft_docx_rev + 1, updated_at = $3
           WHERE id = $1 AND status IN ('draft', 'rejected')`,
        letterID, hash, at)
    if err != nil {
        return fmt.Errorf("correspondence update letter draft docx: %w", err)
    }
    if tag.RowsAffected() == 0 {
        return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.letter.not_editable", Message: "the letter can no longer be edited (already submitted or numbered)"}
    }
    return nil
}

// SetLetterFinalDocx records (hash != "") or clears (hash == "") the frozen merged
// docx. Written just before the numbering conversion so the doc-server can fetch it,
// and cleared again when a conversion failure voids the allocation.
func (s *Store) SetLetterFinalDocx(ctx context.Context, letterID, hash string, at time.Time) error {
    tag, err := s.db.Exec(ctx).Exec(ctx,
        `UPDATE letters SET final_docx_hash = $2, updated_at = $3 WHERE id = $1`,
        letterID, nilStr(hash), at)
    if err != nil {
        return fmt.Errorf("correspondence set letter final docx: %w", err)
    }
    if tag.RowsAffected() == 0 {
        return &kernel.Error{Kind: kernel.ErrNotFound, Code: "correspondence.letter.not_found", Message: "letter not found"}
    }
    return nil
}

    // Docx template (OnlyOffice-edited letterhead). DocxHash addresses the .docx in
    // the blob store (empty = not seeded yet); DocxRev bumps on every editor save or
    // upload and feeds the doc-server cache key (letterhead_{id}_{rev}). HasDocx is
    // the derived flag surfaced to clients (the create-letter modal filters on it).
    DocxHash string `json:"-"`
    DocxRev  int    `json:"-"`
    HasDocx  bool   `json:"has_docx"`

// Service is the letterhead context's application service. blobs stores the
// OnlyOffice-edited docx templates (content-addressed, shared with dms/letters).
type Service struct {
    repo  Repository
    blobs kernel.BlobStore
    clock kernel.Clock
}

// NewService constructs the letterhead service.
func NewService(repo Repository, blobs kernel.BlobStore) *Service {
    return &Service{repo: repo, blobs: blobs, clock: kernel.SystemClock()}
}

const letterheadCols = `id, name, header_html, footer_html, docx_hash, docx_rev, created_by, created_at, updated_at`

func scanLetterhead(row scanner) (domain.Template, error) {
    var t domain.Template
    var docxHash *string
    if err := row.Scan(&t.ID, &t.Name, &t.HeaderHTML, &t.FooterHTML, &docxHash, &t.DocxRev, &t.CreatedBy, &t.CreatedAt, &t.UpdatedAt); err != nil {
        return domain.Template{}, err
    }
    if docxHash != nil {
        t.DocxHash = *docxHash
    }
    t.HasDocx = t.DocxHash != ""
    return t, nil
}

// Insert persists a new letterhead row. A duplicate name is surfaced as kernel.ErrConflict.
func (s *Store) Insert(ctx context.Context, t domain.Template) error {
    _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO letterhead_templates (`+letterheadCols+`)
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
        t.ID, t.Name, t.HeaderHTML, t.FooterHTML, nilStr(t.DocxHash), t.DocxRev, t.CreatedBy, t.CreatedAt, t.UpdatedAt)
    if err != nil {
        if c := mapConflict(err); c != nil {
            return c
        }
        return fmt.Errorf("letterhead insert: %w", err)
    }
    return nil
}

// nilStr maps an empty string to a SQL NULL for nullable columns (docx_hash).
func nilStr(s string) *string {
    if s == "" {
        return nil
    }
    return &s
}

// UpdateDocx swaps the docx template blob and bumps docx_rev (invalidating the
// OnlyOffice editor cache key), stamping updated_at = at. NotFound when the id
// matches no row.
func (s *Store) UpdateDocx(ctx context.Context, id, hash string, at time.Time) error {
    tag, err := s.db.Exec(ctx).Exec(ctx,
        `UPDATE letterhead_templates SET docx_hash = $2, docx_rev = docx_rev + 1, updated_at = $3 WHERE id = $1`,
        id, hash, at)
    if err != nil {
        return fmt.Errorf("letterhead update docx: %w", err)
    }
    if tag.RowsAffected() == 0 {
        return &kernel.Error{Kind: kernel.ErrNotFound, Code: "letterhead.not_found", Message: "letterhead not found"}
    }
    return nil
}

    letterheadSvc := letterheadapp.NewService(letterheadadapters.NewStore(database), blobStore)

cd /home/efran/remote-development/obscura && git add go/migrations/00128_letters_docx_authoring.sql go/internal/correspondence/domain/letter.go go/internal/correspondence/app/service.go go/internal/correspondence/adapters/pg.go go/internal/letterhead/domain/template.go go/internal/letterhead/app/service.go go/internal/letterhead/adapters/pg.go go/cmd/obscura-server/wire.go && git commit -m "feat(letters): docx authoring schema (mig 00128) + letterhead docx storage plumbing" -m "Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

// Package docx provides the small OOXML (docx) utilities the OnlyOffice-letters
// feature needs: merge-field replacement across the document/header/footer parts,
// upload validation, and the runtime-assembled starter templates. Pure stdlib, no
// dependency on any bounded context — both the correspondence and letterhead
// services consume it.
package docx

import (
    "archive/zip"
    "bytes"
    "fmt"
    "io"
    "sort"
    "strings"
)

// MIME is the canonical docx content type.
const MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"

// Validate checks that data is a plausible docx: a readable zip that contains
// [Content_Types].xml and word/document.xml. Used on letterhead uploads and on
// editor save-backs; anything deeper (schema validity) is the converter's problem —
// a corrupt part fails the ConvertService/Gotenberg step, which voids cleanly.
func Validate(data []byte) error {
    zr, err := zip.NewReader(bytes.NewReader(data), int64(len(data)))
    if err != nil {
        return fmt.Errorf("not a zip archive")
    }
    var hasTypes, hasDoc bool
    for _, f := range zr.File {
        switch f.Name {
        case "[Content_Types].xml":
            hasTypes = true
        case "word/document.xml":
            hasDoc = true
        }
    }
    if !hasTypes || !hasDoc {
        return fmt.Errorf("missing [Content_Types].xml or word/document.xml")
    }
    return nil
}

// isTargetPart reports whether a zip entry is one of the parts merge fields are
// replaced in: the main document plus every header/footer part.
func isTargetPart(name string) bool {
    if name == "word/document.xml" {
        return true
    }
    return (strings.HasPrefix(name, "word/header") || strings.HasPrefix(name, "word/footer")) && strings.HasSuffix(name, ".xml")
}

// ReplaceFields replaces {{FIELD}} placeholders with XML-escaped values across
// word/document.xml + word/header*.xml + word/footer*.xml, copying every other zip
// entry byte-for-byte. STRING-LEVEL surgery — never an encoding/xml re-serialization
// (which would reorder attributes/namespaces and break OnlyOffice fidelity).
//
// Word splits literal text across arbitrary <w:r> runs (rsid/spellcheck fragments),
// so per part the algorithm is: collect every <w:t> text node with its byte ranges,
// join their texts into one stream, find {{FIELD}} occurrences in the joined stream
// (placeholders contain no XML-escapable characters, so raw matching is safe), then
// splice the escaped replacement into the FIRST affected node's range and empty the
// rest of the span. Unknown fields are left untouched; a docx with no placeholders
// passes through unchanged.
func ReplaceFields(docxZip []byte, fields map[string]string) ([]byte, error) {
    zr, err := zip.NewReader(bytes.NewReader(docxZip), int64(len(docxZip)))
    if err != nil {
        return nil, fmt.Errorf("docx: not a zip archive: %w", err)
    }
    var out bytes.Buffer
    zw := zip.NewWriter(&out)
    for _, f := range zr.File {
        rc, err := f.Open()
        if err != nil {
            return nil, fmt.Errorf("docx: open %s: %w", f.Name, err)
        }
        data, err := io.ReadAll(rc)
        rc.Close()
        if err != nil {
            return nil, fmt.Errorf("docx: read %s: %w", f.Name, err)
        }
        if isTargetPart(f.Name) {
            data = replaceInPart(data, fields)
        }
        w, err := zw.CreateHeader(&zip.FileHeader{Name: f.Name, Method: zip.Deflate, Modified: f.Modified})
        if err != nil {
            return nil, fmt.Errorf("docx: create %s: %w", f.Name, err)
        }
        if _, err := w.Write(data); err != nil {
            return nil, fmt.Errorf("docx: write %s: %w", f.Name, err)
        }
    }
    if err := zw.Close(); err != nil {
        return nil, fmt.Errorf("docx: close: %w", err)
    }
    return out.Bytes(), nil
}

// tNode is one non-self-closing <w:t> text node in a part: the byte range of its
// open tag, the byte range of its content, and where its text starts in the joined
// per-part text stream.
type tNode struct {
    openStart  int // index of '<' of "<w:t"
    openEnd    int // index just after the open tag's '>'
    contentEnd int // index of "</w:t>"
    joinStart  int // offset of this node's text in the joined stream
    text       string
}

// scanTextNodes locates every <w:t> node with content. Exact-tag match: the byte
// after "<w:t" must be '>', ' ' (attributes) or '/' — so <w:tab/>, <w:tc>, <w:tr>
// never match, and w:delText / w:instrText never even reach the check (they do not
// start with "<w:t"). Self-closing <w:t/> carries no text and is skipped: it can
// never contain a placeholder character and emptying it would be a no-op.
func scanTextNodes(xml string) []tNode {
    var nodes []tNode
    join := 0
    for i := 0; ; {
        j := strings.Index(xml[i:], "<w:t")
        if j < 0 {
            break
        }
        start := i + j
        rest := start + 4
        if rest >= len(xml) {
            break
        }
        switch xml[rest] {
        case '>', ' ', '/':
        default: // <w:tab, <w:tc, <w:tbl, ...
            i = rest
            continue
        }
        gt := strings.IndexByte(xml[rest:], '>')
        if gt < 0 {
            break
        }
        openEnd := rest + gt + 1
        if xml[openEnd-2] == '/' { // self-closing <w:t/> (possibly with attributes)
            i = openEnd
            continue
        }
        closeIdx := strings.Index(xml[openEnd:], "</w:t>")
        if closeIdx < 0 {
            break
        }
        contentEnd := openEnd + closeIdx
        text := xml[openEnd:contentEnd]
        nodes = append(nodes, tNode{openStart: start, openEnd: openEnd, contentEnd: contentEnd, joinStart: join, text: text})
        join += len(text)
        i = contentEnd + len("</w:t>")
    }
    return nodes
}

// occurrence is one placeholder hit in a part's joined text stream.
type occurrence struct {
    start, end int    // [start, end) in the joined stream
    value      string // XML-escaped replacement
}

// xmlEscaper escapes replacement values for insertion into XML text content —
// subjects can legally contain &, <, >, quotes.
var xmlEscaper = strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;", "'", "&apos;")

// replaceInPart runs the merge substitution over one XML part.
func replaceInPart(part []byte, fields map[string]string) []byte {
    xml := string(part)
    nodes := scanTextNodes(xml)
    if len(nodes) == 0 {
        return part
    }
    var joinedB strings.Builder
    for _, n := range nodes {
        joinedB.WriteString(n.text)
    }
    joined := joinedB.String()

    // Collect every occurrence of every known field on the ORIGINAL joined stream,
    // then apply edits RIGHT-TO-LEFT so earlier offsets stay valid while node texts
    // mutate. (The fixed field set has no overlapping placeholder shapes; the
    // prevStart guard below skips pathological overlaps defensively.)
    var occs []occurrence
    for field, value := range fields {
        ph := "{{" + field + "}}"
        esc := xmlEscaper.Replace(value)
        for from := 0; ; {
            k := strings.Index(joined[from:], ph)
            if k < 0 {
                break
            }
            s := from + k
            occs = append(occs, occurrence{start: s, end: s + len(ph), value: esc})
            from = s + len(ph)
        }
    }
    if len(occs) == 0 {
        return part
    }
    sort.Slice(occs, func(i, j int) bool { return occs[i].start > occs[j].start })

    texts := make([]string, len(nodes))
    for i, n := range nodes {
        texts[i] = n.text
    }
    // nodeAt maps a joined-stream offset to its node index (offsets are original —
    // right-to-left application keeps every prefix below the current edit intact).
    nodeAt := func(off int) int {
        for i, n := range nodes {
            if off >= n.joinStart && off < n.joinStart+len(n.text) {
                return i
            }
        }
        return -1
    }
    prevStart := len(joined) + 1
    for _, oc := range occs {
        if oc.end > prevStart { // overlap with the previously applied (righter) occurrence
            continue
        }
        prevStart = oc.start
        first := nodeAt(oc.start)
        last := nodeAt(oc.end - 1)
        if first < 0 || last < 0 {
            continue
        }
        if first == last {
            local := oc.start - nodes[first].joinStart
            localEnd := oc.end - nodes[first].joinStart
            texts[first] = texts[first][:local] + oc.value + texts[first][localEnd:]
            continue
        }
        // Placeholder split across runs: replacement lands in the first affected run
        // (keeping that run's formatting), the middle runs empty, the last keeps its tail.
        texts[first] = texts[first][:oc.start-nodes[first].joinStart] + oc.value
        for k := first + 1; k < last; k++ {
            texts[k] = ""
        }
        texts[last] = texts[last][oc.end-nodes[last].joinStart:]
    }

    // Reassemble: original bytes outside the text nodes, mutated text inside. When a
    // node's new text gained a boundary space and its open tag lacks
    // xml:space="preserve", add the attribute (Word/OnlyOffice trim otherwise).
    var out strings.Builder
    prev := 0
    for i, n := range nodes {
        out.WriteString(xml[prev:n.openStart])
        openTag := xml[n.openStart:n.openEnd]
        if needsPreserve(texts[i]) && !strings.Contains(openTag, "xml:space") {
            openTag = openTag[:len(openTag)-1] + ` xml:space="preserve">`
        }
        out.WriteString(openTag)
        out.WriteString(texts[i])
        prev = n.contentEnd
    }
    out.WriteString(xml[prev:])
    return []byte(out.String())
}

// needsPreserve reports whether a text needs xml:space="preserve" (leading or
// trailing space that XML whitespace handling would otherwise eat).
func needsPreserve(t string) bool {
    return t != "" && (t[0] == ' ' || t[len(t)-1] == ' ')
}

package docx

import (
    "archive/zip"
    "bytes"
    "time"
)

// Starter templates are assembled at RUNTIME from OOXML part constants — no binary
// .docx files in the repo. Fixed entry order + a fixed zip timestamp keep the output
// byte-stable within a build, so the content-addressed blob hash of a freshly seeded
// starter is deterministic. (A Go toolchain upgrade may change deflate output and
// thus the hash of NEW seeds — harmless: existing letters/templates keep the blobs
// they already reference.)

const starterContentTypes = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/><Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/><Override PartName="/word/header1.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml"/><Override PartName="/word/footer1.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml"/></Types>`

const starterRootRels = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>`

const starterDocumentRels = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/><Relationship Id="rId10" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/header" Target="header1.xml"/><Relationship Id="rId11" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer" Target="footer1.xml"/></Relationships>`

// Minimal styles: Times New Roman 12pt (w:sz is half-points) with a little
// paragraph spacing — the traditional tata-naskah look, all overridable in the editor.
const starterStyles = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Times New Roman" w:hAnsi="Times New Roman" w:cs="Times New Roman"/><w:sz w:val="24"/><w:szCs w:val="24"/></w:rPr></w:rPrDefault><w:pPrDefault><w:pPr><w:spacing w:after="120"/></w:pPr></w:pPrDefault></w:docDefaults></w:styles>`

// Body: the standard tata-naskah opening block as editable guidance (the author can
// delete it), plus a sectPr wiring header1/footer1 (rIds match starterDocumentRels)
// on an A4 page (11906x16838 twips) with 1-inch margins. The header/footer
// references are what make OnlyOffice's header/footer editing immediately
// discoverable (spec D2).
const starterDocument = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><w:body><w:p><w:r><w:t xml:space="preserve">Nomor: {{NOMOR}}</w:t></w:r></w:p><w:p><w:r><w:t xml:space="preserve">Sifat: {{SIFAT}}</w:t></w:r></w:p><w:p><w:r><w:t xml:space="preserve">Perihal: {{PERIHAL}}</w:t></w:r></w:p><w:p/><w:p><w:pPr><w:jc w:val="right"/></w:pPr><w:r><w:t>{{TANGGAL}}</w:t></w:r></w:p><w:p/><w:sectPr><w:headerReference w:type="default" r:id="rId10"/><w:footerReference w:type="default" r:id="rId11"/><w:pgSz w:w="11906" w:h="16838"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="720" w:footer="720" w:gutter="0"/></w:sectPr></w:body></w:document>`

// Letterhead starter: sample kop in the header, sample text in the footer.
const starterLetterheadHeader = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:hdr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:p><w:pPr><w:jc w:val="center"/></w:pPr><w:r><w:rPr><w:b/><w:sz w:val="28"/></w:rPr><w:t>NAMA INSTANSI / ORGANISASI</w:t></w:r></w:p><w:p><w:pPr><w:jc w:val="center"/></w:pPr><w:r><w:t>Alamat, telepon, surel — sunting kop ini di bagian header</w:t></w:r></w:p></w:hdr>`

const starterLetterheadFooter = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:ftr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:p><w:pPr><w:jc w:val="center"/></w:pPr><w:r><w:rPr><w:sz w:val="18"/></w:rPr><w:t>Contoh footer — sunting di bagian footer</w:t></w:r></w:p></w:ftr>`

// Blank starter: header/footer sections exist (so header/footer editing is
// discoverable) but contain a single empty paragraph.
const starterBlankHeader = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:hdr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:p/></w:hdr>`

const starterBlankFooter = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:ftr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:p/></w:ftr>`

// starterZipTime is the fixed timestamp stamped on every starter zip entry.
var starterZipTime = time.Date(2026, 7, 1, 0, 0, 0, 0, time.UTC)

// assembleStarter zips the OOXML parts into a docx. Inputs are static string
// constants and the writes go to an in-memory buffer, so errors are impossible in
// practice — a panic here means a broken constant, caught by the build-time scratch
// check, never at runtime with user data.
func assembleStarter(headerXML, footerXML string) []byte {
    var buf bytes.Buffer
    zw := zip.NewWriter(&buf)
    parts := []struct{ name, body string }{
        {"[Content_Types].xml", starterContentTypes},
        {"_rels/.rels", starterRootRels},
        {"word/document.xml", starterDocument},
        {"word/_rels/document.xml.rels", starterDocumentRels},
        {"word/styles.xml", starterStyles},
        {"word/header1.xml", headerXML},
        {"word/footer1.xml", footerXML},
    }
    for _, p := range parts {
        w, err := zw.CreateHeader(&zip.FileHeader{Name: p.name, Method: zip.Deflate, Modified: starterZipTime})
        if err != nil {
            panic("docx starter: " + err.Error())
        }
        if _, err := w.Write([]byte(p.body)); err != nil {
            panic("docx starter: " + err.Error())
        }
    }
    if err := zw.Close(); err != nil {
        panic("docx starter: " + err.Error())
    }
    return buf.Bytes()
}

// LetterheadStarter is the seed docx for a letterhead template: sample kop text in
// the native Word header section, sample footer, and the tata-naskah opening block
// in the body as editable guidance.
func LetterheadStarter() []byte { return assembleStarter(starterLetterheadHeader, starterLetterheadFooter) }

// BlankLetterStarter is the seed docx for a letter created without a letterhead:
// A4, empty header/footer sections wired, same opening block in the body.
func BlankLetterStarter() []byte { return assembleStarter(starterBlankHeader, starterBlankFooter) }

mkdir -p /tmp/docxscratch && cd /tmp/docxscratch
cat > go.mod <<'EOF'
module github.com/Virtue-Digital-Indonesia/obscura/scratch

go 1.25.7

require github.com/Virtue-Digital-Indonesia/obscura v0.0.0

replace github.com/Virtue-Digital-Indonesia/obscura => /home/efran/remote-development/obscura/go
EOF
cat > main.go <<'EOF'
package main

import (
    "archive/zip"
    "bytes"
    "fmt"
    "io"
    "os"
    "strings"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/platform/docx"
)

func readPart(zipBytes []byte, name string) string {
    zr, err := zip.NewReader(bytes.NewReader(zipBytes), int64(len(zipBytes)))
    if err != nil {
        panic(err)
    }
    for _, f := range zr.File {
        if f.Name == name {
            rc, _ := f.Open()
            b, _ := io.ReadAll(rc)
            rc.Close()
            return string(b)
        }
    }
    panic("part not found: " + name)
}

func must(cond bool, what string) {
    if !cond {
        fmt.Println("FAIL:", what)
        os.Exit(1)
    }
}

func main() {
    // 1. Both starters validate and are stable.
    lh, blank := docx.LetterheadStarter(), docx.BlankLetterStarter()
    must(docx.Validate(lh) == nil, "letterhead starter validates")
    must(docx.Validate(blank) == nil, "blank starter validates")
    must(bytes.Equal(lh, docx.LetterheadStarter()), "starter assembly deterministic")
    must(docx.Validate([]byte("not a zip")) != nil, "garbage rejected")

    // 2. Merge over the real starter: values land, escaping applied, no {{ left.
    merged, err := docx.ReplaceFields(lh, map[string]string{
        "NOMOR":   "0007/UND/2026",
        "TANGGAL": "24 Juli 2026",
        "PERIHAL": `Undangan R&D <Divisi> "Alpha"`,
        "SIFAT":   "-",
    })
    must(err == nil, "ReplaceFields on starter")
    _ = os.WriteFile("/tmp/docxscratch/merged.docx", merged, 0o644)
    doc := readPart(merged, "word/document.xml")
    for _, want := range []string{
        "Nomor: 0007/UND/2026",
        "Sifat: -",
        "Perihal: Undangan R&amp;D &lt;Divisi&gt; &quot;Alpha&quot;",
        "24 Juli 2026",
    } {
        must(strings.Contains(doc, want), "document.xml contains "+want)
    }
    must(!strings.Contains(doc, "{{"), "no unreplaced placeholder")
    must(readPart(merged, "word/header1.xml") == readPart(lh, "word/header1.xml"), "header without placeholders untouched")

    // 3. Split-run placeholder (Word rsid fragmentation) + unknown field untouched.
    var buf bytes.Buffer
    zw := zip.NewWriter(&buf)
    add := func(name, body string) {
        w, _ := zw.CreateHeader(&zip.FileHeader{Name: name, Method: zip.Deflate})
        _, _ = w.Write([]byte(body))
    }
    add("[Content_Types].xml", `<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="xml" ContentType="application/xml"/></Types>`)
    add("word/document.xml", `<w:document xmlns:w="x"><w:body><w:p><w:r><w:t>Nomor: {{NO</w:t></w:r><w:r><w:t>MOR}}</w:t></w:r><w:r><w:t xml:space="preserve"> tetap {{LAIN}}</w:t></w:r></w:p><w:p><w:r><w:t>{{TANGGAL}} dan {{TANGGAL}}</w:t></w:r></w:p></w:body></w:document>`)
    _ = zw.Close()
    merged2, err := docx.ReplaceFields(buf.Bytes(), map[string]string{"NOMOR": "0001/X/2026", "TANGGAL": "1 Juli 2026"})
    must(err == nil, "ReplaceFields split-run")
    doc2 := readPart(merged2, "word/document.xml")
    must(strings.Contains(doc2, "<w:t>Nomor: 0001/X/2026</w:t>"), "split-run replacement lands in first run")
    must(strings.Contains(doc2, "<w:t></w:t>"), "remainder of split run emptied")
    must(strings.Contains(doc2, "{{LAIN}}"), "unknown field untouched")
    must(strings.Contains(doc2, "1 Juli 2026 dan 1 Juli 2026"), "double occurrence in one run")

    fmt.Println("OK — all docx scratch checks passed")
}
EOF
go mod tidy && go run .

cd /home/efran/remote-development/obscura && git add go/internal/platform/docx/replace.go go/internal/platform/docx/starter.go && git commit -m "feat(letters): platform/docx — merge-field replacer, validator, runtime-assembled starters" -m "Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"

// DocxPDFRenderer converts a docx letter's merged bytes to PDF at numbering time.
// The composition root late-binds the httpapi server here (mirrors esign's
// SetSealMarker): OnlyOffice ConvertService when the office module is live, with a
// Gotenberg LibreOffice fallback — so docx letters stay NUMBERABLE even if the
// office license lapses; only editing needs the module.
type DocxPDFRenderer interface {
    RenderLetterDocx(ctx context.Context, letterID string, docx []byte) ([]byte, error)
}

type Service struct {
    repo         Repository
    renderer     PDFRenderer
    docxRenderer DocxPDFRenderer // nil until the composition root wires it
    blobs        kernel.BlobStore
    uow          kernel.UnitOfWork
    clock        kernel.Clock
}

// SetDocxRenderer late-binds the docx→PDF converter (set by the composition root
// after the HTTP server exists; the server implements the port).
func (s *Service) SetDocxRenderer(r DocxPDFRenderer) { s.docxRenderer = r }

// CreateLetterParams are the CreateLetter inputs. Authoring selects the compose
// channel: "" / html (plain HTML → Gotenberg, the original path) or docx
// (OnlyOffice-authored). For docx letters the TRANSPORT enforces the office module
// and resolves SeedDocxHash — the chosen letterhead's docx template hash
// (content-addressed ⇒ zero-copy seed; the first editor save diverges naturally).
// An empty SeedDocxHash on a docx letter seeds the embedded blank starter.
type CreateLetterParams struct {
    Type           string
    Classification string
    Subject        string
    BodyHTML       string
    Authoring      string
    LetterheadID   string
    SeedDocxHash   string
}

// CreateLetter creates a draft letter and returns its ID. An empty classification
// defaults to 'none'. The letter has no number and no rendered PDF until
// AssignNumber succeeds.
func (s *Service) CreateLetter(ctx context.Context, p kernel.Principal, params CreateLetterParams) (string, error) {
    switch params.Type {
    case domain.TypeSurat, domain.TypeNota, domain.TypeMemo:
    default:
        return "", &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.letter.invalid_type", Message: "letter type must be surat, nota or memo"}
    }
    if params.Subject == "" {
        return "", &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.letter.subject_required", Message: "letter subject is required"}
    }
    if params.Classification == "" {
        params.Classification = domain.ClassificationNone
    }
    switch params.Authoring {
    case "":
        params.Authoring = domain.AuthoringHTML
    case domain.AuthoringHTML, domain.AuthoringDocx:
    default:
        return "", &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.letter.invalid_authoring", Message: "authoring must be html or docx"}
    }
    // Seed the editable docx. A letterhead seed arrives as its template hash
    // (zero-copy — the blob already exists, content-addressed); otherwise store the
    // embedded blank starter. Put-before-insert: an insert failure leaves at worst
    // an unreferenced blob, never a letter pointing at missing bytes.
    draftDocxHash := ""
    if params.Authoring == domain.AuthoringDocx {
        draftDocxHash = params.SeedDocxHash
        if draftDocxHash == "" {
            h, _, err := s.blobs.Put(ctx, bytes.NewReader(docx.BlankLetterStarter()), kernel.PutOpts{ContentType: docx.MIME})
            if err != nil {
                return "", err
            }
            draftDocxHash = string(h)
        }
    }
    now := s.clock.Now()
    id := kernel.NewID()
    l := domain.Letter{
        ID:             id,
        Type:           params.Type,
        Classification: params.Classification,
        Subject:        params.Subject,
        BodyHTML:       params.BodyHTML,
        Status:         domain.StatusDraft,
        Direction:      domain.DirectionOutbound,
        Authoring:      params.Authoring,
        DraftDocxHash:  draftDocxHash,
        LetterheadID:   params.LetterheadID,
        CreatedBy:      string(p.UserID),
        CreatedAt:      now,
        UpdatedAt:      now,
    }
    if err := s.repo.InsertLetter(ctx, l); err != nil {
        return "", err
    }
    return id, nil
}

// OpenDraftDocx streams a docx letter's CURRENT editable docx (the OnlyOffice
// content fetch). Conflict when the letter is not docx-authored.
func (s *Service) OpenDraftDocx(ctx context.Context, letterID string) (io.ReadCloser, domain.Letter, error) {
    l, err := s.repo.GetLetter(ctx, letterID)
    if err != nil {
        return nil, domain.Letter{}, err
    }
    if l.Authoring != domain.AuthoringDocx || l.DraftDocxHash == "" {
        return nil, domain.Letter{}, &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.letter.no_docx", Message: "letter has no docx draft"}
    }
    rc, err := s.blobs.Get(ctx, kernel.ContentHash(l.DraftDocxHash))
    if err != nil {
        return nil, domain.Letter{}, err
    }
    return rc, l, nil
}

// OpenFinalDocx streams the FROZEN merge-substituted docx written at numbering —
// read-only, only ever fetched by the numbering conversion (variant=final tokens).
func (s *Service) OpenFinalDocx(ctx context.Context, letterID string) (io.ReadCloser, domain.Letter, error) {
    l, err := s.repo.GetLetter(ctx, letterID)
    if err != nil {
        return nil, domain.Letter{}, err
    }
    if l.FinalDocxHash == "" {
        return nil, domain.Letter{}, &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.letter.no_final_docx", Message: "letter has no frozen final docx"}
    }
    rc, err := s.blobs.Get(ctx, kernel.ContentHash(l.FinalDocxHash))
    if err != nil {
        return nil, domain.Letter{}, err
    }
    return rc, l, nil
}

// SaveDraftDocx lands an OnlyOffice editor save. The TRANSPORT re-checks the
// saver's identity (creator / correspondence.admin — it holds the authorizer);
// here the letter must be docx-authored and still editable, and the repository
// UPDATE re-guards status IN SQL so a numbering that races an open editor rejects
// the late save (F11 parity). editorUserID names the saver for the guard's error
// context; put-before-update keeps a failed update from stranding anything but an
// unreferenced blob.
func (s *Service) SaveDraftDocx(ctx context.Context, letterID, editorUserID string, docxBytes []byte) error {
    l, err := s.repo.GetLetter(ctx, letterID)
    if err != nil {
        return err
    }
    if l.Authoring != domain.AuthoringDocx {
        return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.letter.no_docx", Message: "letter is not docx-authored"}
    }
    if l.Status != domain.StatusDraft && l.Status != domain.StatusRejected {
        return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.letter.not_editable", Message: "the letter can no longer be edited (already submitted or numbered)"}
    }
    if err := docx.Validate(docxBytes); err != nil {
        return &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.letter.docx_invalid", Message: "the saved file is not a valid docx", Err: err}
    }
    _ = editorUserID // identity re-check lives in the transport (it owns the authorizer)
    hash, _, err := s.blobs.Put(ctx, bytes.NewReader(docxBytes), kernel.PutOpts{ContentType: docx.MIME})
    if err != nil {
        return err
    }
    return s.repo.UpdateLetterDraftDocx(ctx, letterID, string(hash), s.clock.Now())
}

// reservation is the outcome of the numbering flow's Tx A: the letter + scheme
// snapshot and the reserved allocation the caller must resolve to assigned/voided.
type reservation struct {
    scheme    domain.NumberingScheme
    letter    domain.Letter
    allocID   string
    seq       int
    periodKey string
}

// reserveNumber is Tx A of the gapless flow (shared by the HTML and docx paths):
// validate inputs, take the per-scheme advisory lock, read MAX(seq)+1, INSERT a
// 'reserved' allocation. Commit releases the lock immediately — the slow render
// never holds it.
func (s *Service) reserveNumber(ctx context.Context, letterID, schemeCode string) (reservation, error) {
    if letterID == "" {
        return reservation{}, &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.assign.letter_required", Message: "letter id is required"}
    }
    if schemeCode == "" {
        return reservation{}, &kernel.Error{Kind: kernel.ErrValidation, Code: "correspondence.assign.scheme_required", Message: "scheme code is required"}
    }
    var res reservation
    err := s.uow.Do(ctx, func(ctx context.Context) error {
        var err error
        res.letter, err = s.repo.GetLetter(ctx, letterID)
        if err != nil {
            return err
        }
        if res.letter.Status != domain.StatusDraft && res.letter.Status != domain.StatusApproved {
            return &kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.assign.not_numberable", Message: "letter is not in a numberable state (draft or approved)"}
        }
        res.scheme, err = s.repo.GetSchemeByCode(ctx, schemeCode)
        if err != nil {
            return err
        }
        // Serialize concurrent allocators on this scheme so MAX(seq)+1 is monotonic.
        if err := s.repo.AcquireSchemeLock(ctx, res.scheme.Code); err != nil {
            return err
        }
        res.periodKey = s.clock.Now().Format(res.scheme.PeriodFormat)
        res.seq, err = s.repo.NextSeqForPeriod(ctx, res.scheme.ID, res.periodKey)
        if err != nil {
            return err
        }
        res.allocID = kernel.NewID()
        return s.repo.InsertReservedAllocation(ctx, domain.Allocation{
            ID:          res.allocID,
            SchemeID:    res.scheme.ID,
            PeriodKey:   res.periodKey,
            Seq:         res.seq,
            State:       domain.AllocReserved,
            LetterID:    letterID,
            AllocatedAt: s.clock.Now(),
        })
    })
    if err != nil {
        return reservation{}, err
    }
    return res, nil
}

// voidAllocation resolves a reserved seq as consumed-but-void — the auditable
// record of a failed render/convert, never a silent gap.
func (s *Service) voidAllocation(ctx context.Context, allocID string) error {
    return s.uow.Do(ctx, func(ctx context.Context) error {
        return s.repo.MarkAllocationVoided(ctx, allocID, s.clock.Now())
    })
}

// AssignNumberWithLetterhead is AssignNumber with an OPTIONAL letterhead (kop/footer).
// Empty header AND footer render the bare body (identical to AssignNumber). Otherwise the
// renderer gets header + body + footer. The letterhead lives in the CORE letterhead store
// and is resolved by the httpapi layer, which passes its header/footer HTML in here. The
// gapless reserve->render->finalize ordering is UNCHANGED — only the HTML handed to the
// renderer differs. HTML letters only; docx letters number through AssignNumberDocx.
func (s *Service) AssignNumberWithLetterhead(ctx context.Context, p kernel.Principal, letterID, schemeCode, headerHTML, footerHTML string) (string, error) {
    res, err := s.reserveNumber(ctx, letterID, schemeCode)
    if err != nil {
        return "", err
    }

    // The HTML handed to the renderer: wrapped with the letterhead (header + body +
    // footer) when one was chosen, otherwise the bare body (current behavior).
    renderHTML := res.letter.BodyHTML
    if headerHTML != "" || footerHTML != "" {
        renderHTML = headerHTML + res.letter.BodyHTML + footerHTML
    }

    // Out of any tx: render the PDF (slow, network, fallible).
    pdf, renderErr := s.renderer.Render(ctx, renderHTML)
    if renderErr != nil {
        // Render failed: void the reserved seq (auditable, never a silent gap).
        if voidErr := s.voidAllocation(ctx, res.allocID); voidErr != nil {
            return "", voidErr
        }
        return "", renderErr
    }

    // Render OK: store the PDF, then finalize the allocation and the letter. A storage
    // failure here must NOT strand the reservation in 'reserved' forever — void it
    // (auditable), exactly like a render failure, so the gapless invariant holds.
    hash, _, err := s.blobs.Put(ctx, bytes.NewReader(pdf), kernel.PutOpts{ContentType: "application/pdf"})
    if err != nil {
        if voidErr := s.voidAllocation(ctx, res.allocID); voidErr != nil {
            return "", voidErr
        }
        return "", err
    }
    number := domain.FormatNumber(res.scheme.Pattern, res.seq, res.scheme.Code, res.periodKey)
    err = s.uow.Do(ctx, func(ctx context.Context) error {
        now := s.clock.Now()
        if err := s.repo.MarkAllocationAssigned(ctx, res.allocID, letterID, now); err != nil {
            return err
        }
        return s.repo.UpdateLetterNumbered(ctx, letterID, number, string(hash), now)
    })
    if err != nil {
        return "", err
    }
    return number, nil
}

// AssignNumberDocx numbers a DOCX-authored letter: same three-phase gapless flow,
// but phase 2 is merge-replace ({{NOMOR}} {{TANGGAL}} {{PERIHAL}} {{SIFAT}}) across
// document + header/footer parts, freeze the merged docx (final_docx_hash — written
// BEFORE the conversion so the doc-server can fetch it through a variant=final
// content token), then convert docx→PDF through the late-bound DocxPDFRenderer.
// ANY phase-2 failure voids the allocation and clears final_docx_hash.
func (s *Service) AssignNumberDocx(ctx context.Context, p kernel.Principal, letterID, schemeCode string) (string, error) {
    res, err := s.reserveNumber(ctx, letterID, schemeCode)
    if err != nil {
        return "", err
    }
    // fail voids the reservation (and clears the frozen docx when it was already
    // recorded), then surfaces cause. A failed void wins — a dangling reservation
    // would break the gapless invariant.
    fail := func(cause error, clearFinal bool) (string, error) {
        if clearFinal {
            _ = s.repo.SetLetterFinalDocx(ctx, letterID, "", s.clock.Now())
        }
        if voidErr := s.voidAllocation(ctx, res.allocID); voidErr != nil {
            return "", voidErr
        }
        return "", cause
    }
    if res.letter.Authoring != domain.AuthoringDocx || res.letter.DraftDocxHash == "" {
        return fail(&kernel.Error{Kind: kernel.ErrConflict, Code: "correspondence.assign.no_docx", Message: "letter has no docx draft to number"}, false)
    }
    if s.docxRenderer == nil {
        return fail(&kernel.Error{Kind: kernel.ErrProtectionUnavailable, Code: "correspondence.assign.docx_renderer_unavailable", Message: "no docx-to-PDF converter is configured"}, false)
    }

    number := domain.FormatNumber(res.scheme.Pattern, res.seq, res.scheme.Code, res.periodKey)

    rc, err := s.blobs.Get(ctx, kernel.ContentHash(res.letter.DraftDocxHash))
    if err != nil {
        return fail(err, false)
    }
    draft, err := io.ReadAll(rc)
    rc.Close()
    if err != nil {
        return fail(err, false)
    }
    merged, err := docx.ReplaceFields(draft, map[string]string{
        "NOMOR":   number,
        "TANGGAL": domain.IndonesianLongDate(s.clock.Now()),
        "PERIHAL": res.letter.Subject,
        "SIFAT":   domain.SifatLabel(res.letter.Classification),
    })
    if err != nil {
        return fail(err, false)
    }
    finalHash, _, err := s.blobs.Put(ctx, bytes.NewReader(merged), kernel.PutOpts{ContentType: docx.MIME})
    if err != nil {
        return fail(err, false)
    }
    // Persist the frozen docx BEFORE converting — the ConvertService fetches it by
    // letter id through a variant=final content token.
    if err := s.repo.SetLetterFinalDocx(ctx, letterID, string(finalHash), s.clock.Now()); err != nil {
        return fail(err, false)
    }
    pdf, err := s.docxRenderer.RenderLetterDocx(ctx, letterID, merged)
    if err != nil {
        return fail(err, true)
    }
    pdfHash, _, err := s.blobs.Put(ctx, bytes.NewReader(pdf), kernel.PutOpts{ContentType: "application/pdf"})
    if err != nil {
        return fail(err, true)
    }
    err = s.uow.Do(ctx, func(ctx context.Context) error {
        now := s.clock.Now()
        if err := s.repo.MarkAllocationAssigned(ctx, res.allocID, letterID, now); err != nil {
            return err
        }
        return s.repo.UpdateLetterNumbered(ctx, letterID, number, string(pdfHash), now)
    })
    if err != nil {
        return "", err
    }
    return number, nil
}