textmachine/platform/internal/httpapi/reading.go

package httpapi

import (
	"net/http"
	"time"

	"textmachine/platform/internal/ingest"
)

// reading.go: the chapter tree, its pairs, the book's notes and its memory bank.
//
// One rule shapes all four: a collection answers ONE page and the revision that page is a picture
// of, read in the same transaction. The client stamps a multi-page WALK with the lowest revision it
// saw and uses that as the watermark of its next delta read (canon §Revision) — server-side that
// means every page carries its own number and none of them carries a promise about the others.

type wireChapter struct {
	ID     string `json:"id"`
	Number *int   `json:"number"`
	// Heading is the chapter's label as it comes from the DATA of the book, or null. A deployment
	// whose parser does not extract labels answers null and MUST NOT put a rendered ordinal here.
	Heading    *string `json:"heading"`
	UnitsTotal int     `json:"units_total"`
	UnitsDone  int     `json:"units_done"`
	NoteCount  int     `json:"note_count"`
}

type wireChapterPage struct {
	Revision         int64         `json:"revision"`
	NextCursor       *string       `json:"next_cursor"`
	StructureVersion int           `json:"structure_version"`
	Chapters         []wireChapter `json:"chapters"`
}

type wireUnit struct {
	ID     string `json:"id"`
	Source string `json:"source"`
	// Target is non-empty exactly when State is `translated`, the empty string otherwise — never
	// absent, never null.
	Target string     `json:"target"`
	State  string     `json:"state"`
	Notes  []wireNote `json:"notes"`
}

type wireUnitPage struct {
	Revision         int64      `json:"revision"`
	NextCursor       *string    `json:"next_cursor"`
	StructureVersion int        `json:"structure_version"`
	Units            []wireUnit `json:"units"`
}

type wireNote struct {
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
	Severity  string    `json:"severity"`
	Code      string    `json:"code"`
	ChapterID string    `json:"chapter_id"`
	// UnitID is optional and for one reason only: a note is about a pair, or about a whole chapter.
	UnitID *string `json:"unit_id,omitempty"`
}

type wireNotePage struct {
	Revision         int64      `json:"revision"`
	NextCursor       *string    `json:"next_cursor"`
	StructureVersion int        `json:"structure_version"`
	Notes            []wireNote `json:"notes"`
}

type wireTerm struct {
	ID     string  `json:"id"`
	Src    string  `json:"src"`
	Dst    string  `json:"dst"`
	Kind   *string `json:"kind"`
	Status string  `json:"status"`
	Origin string  `json:"origin"`
	Sense  string  `json:"sense"`
	// The window is in chapter NUMBERS, which are not keys: it lives in the coordinates of the
	// current structure_version. null means "no boundary".
	SinceChapter *int `json:"since_chapter"`
	UntilChapter *int `json:"until_chapter"`
}

// wireBankPage carries the whole-bank aggregates on the FIRST page only — any response to a request
// with no cursor, a delta read included. They are `omitempty` for that reason and for no other:
// absence here means "does not apply to this page", one of the two places on this surface where it
// does (canon §BankPage).
//
// ⚠ `pending_decisions` and `complete` are gone WITH the canon (0.5.0, PD-399): they counted for
// the abolished per-term model and had degraded into a live count of `proposed` rows. "How many are
// still undecided" is the engine's answer and rides the correction receipt (`signature`), not a
// read of this table.
type wireBankPage struct {
	Revision         int64      `json:"revision"`
	NextCursor       *string    `json:"next_cursor"`
	StructureVersion int        `json:"structure_version"`
	Total            *int       `json:"total,omitempty"`
	Signed           *int       `json:"signed,omitempty"`
	Terms            []wireTerm `json:"terms"`
}

func (h *v0) listChapters(w http.ResponseWriter, r *http.Request) {
	user, ok := principal(w, r)
	if !ok {
		return
	}
	page, err := h.lib.ListChapters(r.Context(), user, r.PathValue("bookId"), h.pageLimit(r), r.URL.Query().Get("cursor"))
	if err != nil {
		h.fail(w, r, err)
		return
	}
	out := wireChapterPage{
		Revision: page.Revision, StructureVersion: page.StructureVersion,
		Chapters: make([]wireChapter, 0, len(page.Chapters)),
	}
	if page.NextCursor != "" {
		out.NextCursor = &page.NextCursor
	}
	for _, c := range page.Chapters {
		out.Chapters = append(out.Chapters, projectChapter(c))
	}
	h.writeJSON(w, r, http.StatusOK, out)
}

// listUnits answers the pairs of ONE chapter.
//
// Per chapter and only per chapter: a book-wide pairs endpoint is never introduced, and the client's
// whole memory model stands on that (canon §listUnits). A chapter that existed and no longer does is
// `410`, so a client re-reads the tree rather than checking the address.
func (h *v0) listUnits(w http.ResponseWriter, r *http.Request) {
	user, ok := principal(w, r)
	if !ok {
		return
	}
	page, err := h.lib.ListUnits(r.Context(), user, r.PathValue("bookId"), r.PathValue("chapterId"),
		h.pageLimit(r), r.URL.Query().Get("cursor"))
	if err != nil {
		h.fail(w, r, err)
		return
	}
	out := wireUnitPage{
		Revision: page.Revision, StructureVersion: page.StructureVersion,
		Units: make([]wireUnit, 0, len(page.Units)),
	}
	if page.NextCursor != "" {
		out.NextCursor = &page.NextCursor
	}
	for _, u := range page.Units {
		out.Units = append(out.Units, projectUnit(u))
	}
	h.writeJSON(w, r, http.StatusOK, out)
}

func (h *v0) listNotes(w http.ResponseWriter, r *http.Request) {
	user, ok := principal(w, r)
	if !ok {
		return
	}
	after, ok := h.afterVersion(w, r)
	if !ok {
		return
	}
	page, err := h.lib.ListNotes(r.Context(), user, r.PathValue("bookId"), h.pageLimit(r),
		r.URL.Query().Get("cursor"), after)
	if err != nil {
		h.fail(w, r, err)
		return
	}
	out := wireNotePage{
		Revision: page.Revision, StructureVersion: page.StructureVersion,
		Notes: make([]wireNote, 0, len(page.Notes)),
	}
	if page.NextCursor != "" {
		out.NextCursor = &page.NextCursor
	}
	unnamed := 0
	for _, n := range page.Notes {
		note := projectNote(n)
		if note.Code == ingest.NoteCodeUnspecified {
			unnamed++
		}
		out.Notes = append(out.Notes, note)
	}
	if unnamed > 0 {
		// A flag reason the contract's map does not name. Loud, because the answer is a line in that
		// map rather than a change here — and silent, it would look like a note the engine produced
		// without a reason.
		h.log.ErrorContext(r.Context(), "notes carry a flag reason this build cannot name; the contract's map needs a line",
			"notes", unnamed)
	}
	h.writeJSON(w, r, http.StatusOK, out)
}

// listBank answers the memory bank, and it is also the STATE of a signing stop — informationally,
// never as a gate. Signing is ONE act over the whole bank: `resume` lifts the stop with the
// decisions as they stand, and no counter here decides whether continuing may be offered (D39.144).
func (h *v0) listBank(w http.ResponseWriter, r *http.Request) {
	user, ok := principal(w, r)
	if !ok {
		return
	}
	after, ok := h.afterVersion(w, r)
	if !ok {
		return
	}
	page, err := h.lib.ListBank(r.Context(), user, r.PathValue("bookId"), h.pageLimit(r),
		r.URL.Query().Get("cursor"), after)
	if err != nil {
		h.fail(w, r, err)
		return
	}
	out := wireBankPage{
		Revision: page.Revision, StructureVersion: page.StructureVersion,
		Terms: make([]wireTerm, 0, len(page.Terms)),
	}
	if page.NextCursor != "" {
		out.NextCursor = &page.NextCursor
	}
	if page.First {
		c := page.Counts
		out.Total, out.Signed = &c.Total, &c.Signed
	}
	for _, t := range page.Terms {
		out.Terms = append(out.Terms, projectTerm(t))
	}
	h.writeJSON(w, r, http.StatusOK, out)
}

// The write half of the bank lives at `POST /books/{bookId}/bank/corrections` (bank.go): the
// per-term act is a CORRECTION applied by the engine's own verb, never a signature — signing stayed
// ONE act over the whole bank, `resume` (D39.144, D39.156). What stood here before it — the
// abolished per-term decisions route — went on the owner's word of 22.08; the `bank_decisions`
// table it fed is dead and nothing here reads it.