From 78ed1dd2813dbc1093542ef5cd0c7915eb560640 Mon Sep 17 00:00:00 2001 From: prosolis <5590409+prosolis@users.noreply.github.com> Date: Sun, 19 Jul 2026 11:45:08 -0700 Subject: [PATCH] Writing passport: evidence of process instead of an AI score MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit She's submitting work that gets run through an AI detector and wants to pre-check she won't be wrongly flagged. Petal should not answer that with a detector of its own: they misfire badly on non-native English (Stanford 2023 found >50% of TOEFL essays flagged as AI vs. near-zero for native writers), so a percentage aimed at an ESL writer is worse than nothing — it either scares her off her own voice or gives false comfort. So the artifact is provenance, not a verdict. Petal already snapshots every ~3 minutes; this turns that history into a standalone printable report: session breakdown, word-count growth, span, active time. No score is emitted anywhere. Two schema additions back it. preserve_history opts a document out of the 40-snapshot prune cap — right for recovery, wrong for provenance, where you want the whole span including the oldest rows. content_hash/prev_hash chain each snapshot to the one before it, so a history edited or thinned after the fact fails verification. Pruning legitimately severs links, so a link break reports as "gaps" unless preserve_history is on; only a hash that fails against its own contents is unconditionally "broken". The chart's x axis is snapshot order, not wall-clock, and that is the load -bearing decision. On a linear time axis an essay written in three sittings across three days renders as three vertical cliffs separated by empty space — visually identical to text pasted in three chunks, i.e. the report would have argued the opposite of the truth. Breaks are compressed into explicitly labelled gutters instead. TestChartGivesWidthToWriting pins it. The report volunteers its largest single word-count jump and states its own limits: it cannot show who was at the keyboard, or whether typed text was composed or copied in. Overclaiming would be self-defeating — a reader who catches it overstating discounts all of it. HTML rather than server-rendered PDF, as with the other exports: a CJK-safe PDF needs an embedded Unicode font or a headless browser. Print styles are there so the browser's Save as PDF is the handoff path. Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd --- internal/db/db.go | 25 ++ internal/db/models.go | 11 + internal/docs/handlers.go | 13 +- internal/docs/passport.go | 281 ++++++++++++++ internal/docs/passport_render.go | 387 ++++++++++++++++++++ internal/docs/passport_test.go | 376 +++++++++++++++++++ internal/docs/versions.go | 66 +++- web/src/api/client.ts | 9 + web/src/components/History/HistoryPanel.tsx | 66 ++++ 9 files changed, 1225 insertions(+), 9 deletions(-) create mode 100644 internal/docs/passport.go create mode 100644 internal/docs/passport_render.go create mode 100644 internal/docs/passport_test.go diff --git a/internal/db/db.go b/internal/db/db.go index d52dbee..c3a1e5b 100644 --- a/internal/db/db.go +++ b/internal/db/db.go @@ -365,6 +365,31 @@ SELECT id, doc_id, from_pos, to_pos, original, replacement, explanation, type, s DROP TABLE suggestions; ALTER TABLE suggestions_new RENAME TO suggestions; CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id); +`, + }, + { + // Writing passport: evidence that a document was written, not pasted. + // + // `preserve_history` opts a document out of auto-snapshot pruning. The + // 40-snapshot cap is right for recovery (you want recent states) but + // wrong for provenance (you want the *whole* span, oldest included), so + // a writer who may need to defend authorship flags the doc and keeps + // every snapshot. + // + // `content_hash`/`prev_hash` chain each snapshot to the one before it: + // hash = sha256(prev_hash | doc_id | created_at | word_count | text). + // This proves the local history is internally consistent — no snapshot + // was edited, reordered, or removed after the fact without breaking + // every link downstream. It is NOT third-party attestation: anyone with + // the DB and the algorithm could forge a fresh chain. It raises the cost + // of a doctored history from "edit one row" to "rebuild all of them". + // Pre-existing snapshots keep empty hashes and are reported as + // unverifiable rather than as failures. + name: "0009_writing_passport", + stmt: ` +ALTER TABLE documents ADD COLUMN preserve_history INTEGER NOT NULL DEFAULT 0; +ALTER TABLE document_versions ADD COLUMN content_hash TEXT NOT NULL DEFAULT ''; +ALTER TABLE document_versions ADD COLUMN prev_hash TEXT NOT NULL DEFAULT ''; `, }, } diff --git a/internal/db/models.go b/internal/db/models.go index 635d7cb..63cd3b1 100644 --- a/internal/db/models.go +++ b/internal/db/models.go @@ -25,6 +25,10 @@ type Document struct { WordCount int `json:"word_count"` CreatedAt time.Time `json:"created_at"` UpdatedAt time.Time `json:"updated_at"` + + // PreserveHistory opts this document out of auto-snapshot pruning so its + // full writing trail survives as authorship evidence (see the passport). + PreserveHistory bool `json:"preserve_history"` } // DocumentVersion is a point-in-time snapshot of a document's body, captured so @@ -42,6 +46,13 @@ type DocumentVersion struct { WordCount int `json:"word_count"` Kind string `json:"kind"` // auto | manual | pre_restore CreatedAt time.Time `json:"created_at"` + + // ContentHash chains this snapshot to the previous one (PrevHash), so a + // history that was edited or thinned after the fact fails verification. + // Both are empty for snapshots taken before the chain existed. Omitted from + // list responses; the passport loads them explicitly. + ContentHash string `json:"content_hash,omitempty"` + PrevHash string `json:"prev_hash,omitempty"` } // Document version kinds, mirrored from the schema CHECK constraint. diff --git a/internal/docs/handlers.go b/internal/docs/handlers.go index a946460..b528837 100644 --- a/internal/docs/handlers.go +++ b/internal/docs/handlers.go @@ -139,6 +139,10 @@ type updateRequest struct { ContentText *string `json:"content_text"` Tone *string `json:"tone"` WordCount *int `json:"word_count"` + + // PreserveHistory toggles the passport's keep-everything mode. Sent alone + // by the History panel's toggle, never by the auto-save path. + PreserveHistory *bool `json:"preserve_history"` } // update applies the provided fields to a document and returns the saved row. @@ -159,9 +163,11 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) { content_text = COALESCE(?, content_text), tone = COALESCE(?, tone), word_count = COALESCE(?, word_count), + preserve_history = COALESCE(?, preserve_history), updated_at = CURRENT_TIMESTAMP WHERE id = ? AND user_id = ?`, - req.Title, req.Content, req.ContentText, req.Tone, req.WordCount, id, db.LocalUserID, + req.Title, req.Content, req.ContentText, req.Tone, req.WordCount, + req.PreserveHistory, id, db.LocalUserID, ) if err != nil { httputil.ServerError(w, err) @@ -211,13 +217,14 @@ func (h *Handler) delete(w http.ResponseWriter, r *http.Request) { func (h *Handler) fetch(id string) (db.Document, error) { var doc db.Document err := h.DB.QueryRow( - `SELECT id, user_id, title, content, content_text, tone, word_count, created_at, updated_at + `SELECT id, user_id, title, content, content_text, tone, word_count, + created_at, updated_at, preserve_history FROM documents WHERE id = ? AND user_id = ?`, id, db.LocalUserID, ).Scan( &doc.ID, &doc.UserID, &doc.Title, &doc.Content, &doc.ContentText, - &doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt, + &doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt, &doc.PreserveHistory, ) return doc, err } diff --git a/internal/docs/passport.go b/internal/docs/passport.go new file mode 100644 index 0000000..8490a23 --- /dev/null +++ b/internal/docs/passport.go @@ -0,0 +1,281 @@ +package docs + +// Writing passport: a standalone, printable report showing *how* a document was +// written — when each snapshot landed, how the word count grew, how the work +// broke into sessions. It exists because automated "AI detector" verdicts are +// unreliable and skew against non-native English writers, so the useful thing to +// hand someone who doubts your authorship is not a score but a record. +// +// The report is deliberately modest about what it proves (see passportLimits): +// it evidences a plausible writing process, it does not certify one. + +import ( + "crypto/sha256" + "database/sql" + "encoding/hex" + "errors" + "fmt" + "net/http" + "time" + + "github.com/go-chi/chi/v5" + + "gitea.parodia.dev/drwily/petal/internal/db" + "gitea.parodia.dev/drwily/petal/internal/httputil" +) + +// Passport tuning. +const ( + // sessionGap is the idle time that separates one writing session from the + // next. Auto-snapshots fire at most every 3 minutes while typing, so any + // gap far above that means the writer stepped away. 45 minutes keeps a + // coffee break inside one session but splits morning from evening work. + sessionGap = 45 * time.Minute + + // jumpNoteThreshold is the share of the final word count a single + // snapshot-to-snapshot increase must exceed before the report calls it out. + // A large jump is the first thing a skeptical reader will ask about, so the + // report raises it rather than leaving it to be discovered. + jumpNoteThreshold = 0.25 +) + +// chainHash links a snapshot to its predecessor. Covering prev_hash makes each +// hash depend on the entire history before it, so altering any earlier snapshot +// invalidates every later one; covering created_at means a row cannot be +// silently backdated. +// +// This detects tampering with the local database. It is not third-party +// attestation — someone with the database and this function could regenerate a +// consistent chain from scratch. +func chainHash(prevHash, docID string, createdAt time.Time, wordCount int, text string) string { + h := sha256.New() + fmt.Fprintf(h, "%s\x00%s\x00%d\x00%d\x00%s", + prevHash, docID, createdAt.UTC().UnixNano(), wordCount, text) + return hex.EncodeToString(h.Sum(nil)) +} + +// --- report model ----------------------------------------------------------- + +// passportSession is one continuous stretch of work — snapshots with no +// sessionGap-sized pause between them. +type passportSession struct { + Start, End time.Time + Snapshots int + WordsAdded int // net change across the session; negative when trimming +} + +// Duration is the observed length of the session: first snapshot to last. A +// single-snapshot session reports zero, which is why total active time is +// described as a lower bound. +func (s passportSession) Duration() time.Duration { return s.End.Sub(s.Start) } + +// chain verification outcomes, in the order the report prefers to report them. +const ( + chainVerified = "verified" // every hash recomputes and every link holds + chainGaps = "gaps" // hashes valid, links broken — consistent with pruning + chainPartial = "partial" // some snapshots predate the hash chain + chainUnverifiable = "unverifiable" // no snapshot carries a hash + chainBroken = "broken" // a hash does not match its own contents +) + +// passportData is everything the template renders. +type passportData struct { + Doc db.Document + Versions []db.DocumentVersion // ascending by time + + Sessions []passportSession + FirstAt time.Time + LastAt time.Time + Span time.Duration // wall-clock first snapshot → last + ActiveTime time.Duration // summed session durations; a lower bound + + LargestJump int // biggest single snapshot-to-snapshot word increase + LargestJumpAt time.Time + LargestJumpIdx int // index into Versions, so the chart can mark it + NoteJump bool // jump is large enough to be worth pre-empting + + ChainStatus string + UnhashedCount int + GeneratedAt time.Time +} + +// buildPassport derives the report from a document and its snapshots, which must +// be ordered oldest-first. It assumes nothing about snapshot spacing. +func buildPassport(doc db.Document, versions []db.DocumentVersion) passportData { + d := passportData{ + Doc: doc, + Versions: versions, + GeneratedAt: time.Now(), + } + if len(versions) == 0 { + d.ChainStatus = chainUnverifiable + return d + } + + d.FirstAt = versions[0].CreatedAt + d.LastAt = versions[len(versions)-1].CreatedAt + d.Span = d.LastAt.Sub(d.FirstAt) + + cur := passportSession{Start: versions[0].CreatedAt, End: versions[0].CreatedAt, Snapshots: 1} + + // Baseline for the running session's net-words figure. Later sessions + // measure from the *previous* session's final count, not from their own + // first snapshot, because that first snapshot already contains the few + // minutes of typing that preceded it — measuring from it would drop that + // work. The first session is the exception: it measures from its own first + // snapshot rather than from zero, so a history whose early snapshots were + // pruned understates session one instead of reporting the words it never + // saw as a sudden addition. + startWords := versions[0].WordCount + + for i := 1; i < len(versions); i++ { + v, prev := versions[i], versions[i-1] + + if delta := v.WordCount - prev.WordCount; delta > d.LargestJump { + d.LargestJump, d.LargestJumpAt, d.LargestJumpIdx = delta, v.CreatedAt, i + } + + if v.CreatedAt.Sub(prev.CreatedAt) > sessionGap { + cur.WordsAdded = prev.WordCount - startWords + d.Sessions = append(d.Sessions, cur) + cur = passportSession{Start: v.CreatedAt, End: v.CreatedAt, Snapshots: 1} + startWords = prev.WordCount + continue + } + cur.End = v.CreatedAt + cur.Snapshots++ + } + cur.WordsAdded = versions[len(versions)-1].WordCount - startWords + d.Sessions = append(d.Sessions, cur) + + for _, s := range d.Sessions { + d.ActiveTime += s.Duration() + } + + final := versions[len(versions)-1].WordCount + d.NoteJump = final > 0 && float64(d.LargestJump)/float64(final) > jumpNoteThreshold + + d.ChainStatus, d.UnhashedCount = verifyChain(doc, versions) + return d +} + +// verifyChain recomputes every snapshot's hash and checks that each links to the +// one before it. Returns the outcome and how many snapshots predate the chain. +// +// Broken *links* are not evidence of tampering on their own: auto-snapshot +// pruning legitimately removes rows from the middle of the history, which severs +// the links across the hole. So a link break is reported as a gap unless the +// document is in preserve-history mode, where nothing should ever be removed. A +// hash that fails to match its *own* contents is unambiguous, and always broken. +func verifyChain(doc db.Document, versions []db.DocumentVersion) (status string, unhashed int) { + var ( + hashed int + linkBreak bool + prevHash string + havePrev bool + ) + + for _, v := range versions { + if v.ContentHash == "" { + unhashed++ + havePrev = false // can't vouch for what follows an unhashed row + continue + } + hashed++ + + want := chainHash(v.PrevHash, v.DocID, v.CreatedAt, v.WordCount, v.ContentText) + if want != v.ContentHash { + return chainBroken, unhashed + } + if havePrev && v.PrevHash != prevHash { + linkBreak = true + } + prevHash, havePrev = v.ContentHash, true + } + + switch { + case hashed == 0: + return chainUnverifiable, unhashed + case linkBreak && doc.PreserveHistory: + // Nothing should have been removed from a preserved history. + return chainBroken, unhashed + case linkBreak: + return chainGaps, unhashed + case unhashed > 0: + return chainPartial, unhashed + default: + return chainVerified, unhashed + } +} + +// --- HTTP ------------------------------------------------------------------- + +// passport renders the report for one document as a standalone HTML download. +// HTML rather than PDF for the same reason as the other exports: a CJK-safe PDF +// needs an embedded Unicode font or a headless browser. The page is styled for +// printing, so "Save as PDF" in the browser produces the handoff artifact. +func (h *Handler) passport(w http.ResponseWriter, r *http.Request) { + docID := chi.URLParam(r, "id") + + doc, err := h.fetch(docID) + if errors.Is(err, sql.ErrNoRows) { + notFound(w) + return + } + if err != nil { + httputil.ServerError(w, err) + return + } + + versions, err := h.passportVersions(docID) + if err != nil { + httputil.ServerError(w, err) + return + } + + body := renderPassport(buildPassport(doc, versions)) + + filename := sanitizeFilename(doc.Title) + if filename == "" { + filename = "untitled" + } + filename += " - writing passport.html" + + w.Header().Set("Content-Type", "text/html; charset=utf-8") + w.Header().Set("Content-Disposition", + fmt.Sprintf("attachment; filename*=UTF-8''%s", urlEscapeFilename(filename))) + w.Header().Set("Content-Length", fmt.Sprintf("%d", len(body))) + _, _ = w.Write(body) +} + +// passportVersions loads every snapshot oldest-first with the fields the report +// and the chain check need — including content_text, which the list endpoint +// omits as too heavy but verification cannot do without. +func (h *Handler) passportVersions(docID string) ([]db.DocumentVersion, error) { + rows, err := h.DB.Query( + `SELECT v.id, v.doc_id, v.title, v.content_text, v.word_count, v.kind, + v.created_at, v.content_hash, v.prev_hash + FROM document_versions v + JOIN documents d ON d.id = v.doc_id + WHERE v.doc_id = ? AND d.user_id = ? + ORDER BY v.created_at ASC, v.rowid ASC`, + docID, db.LocalUserID, + ) + if err != nil { + return nil, err + } + defer rows.Close() + + var out []db.DocumentVersion + for rows.Next() { + var v db.DocumentVersion + if err := rows.Scan( + &v.ID, &v.DocID, &v.Title, &v.ContentText, &v.WordCount, &v.Kind, + &v.CreatedAt, &v.ContentHash, &v.PrevHash, + ); err != nil { + return nil, err + } + out = append(out, v) + } + return out, rows.Err() +} diff --git a/internal/docs/passport_render.go b/internal/docs/passport_render.go new file mode 100644 index 0000000..501d0b6 --- /dev/null +++ b/internal/docs/passport_render.go @@ -0,0 +1,387 @@ +package docs + +// HTML rendering for the writing passport. Self-contained (no external assets) +// and styled for print, so the browser's "Save as PDF" turns it into the file a +// writer actually hands over. + +import ( + "fmt" + "math" + "strings" + "time" +) + +// Chart geometry. The plot is wide and short on purpose: the report's question +// is "what shape did this document grow in", and a wide aspect makes a steady +// climb read as steady rather than dramatic. +const ( + chartW, chartH = 760, 260 + padL, padR, padT, padB = 52, 20, 18, 34 + plotW, plotH = chartW - padL - padR, chartH - padT - padB + minBandW = 2.0 // so a single-snapshot session still shows + + // gutterSlots is the space between sessions, in snapshot-slot widths. Wide + // enough to read as a break and to seat its duration label. + gutterSlots = 2.5 +) + +// Palette — the export stylesheet's tokens, reused so a passport looks like it +// came from the same application as the document it describes. +const ( + rose = "#b04a6a" + roseLight = "#f6d6e0" + roseWash = "#fdeef3" + surface = "#fffafb" +) + +func renderPassport(d passportData) []byte { + var b strings.Builder + + fmt.Fprintf(&b, passportHead, htmlEscape(d.Doc.Title)) + + fmt.Fprintf(&b, `
+

Writing passport

+

%s

+

Generated %s

+
+`, htmlEscape(d.Doc.Title), htmlEscape(formatWhen(d.GeneratedAt))) + + if len(d.Versions) == 0 { + b.WriteString(`

This document has no saved history yet, so there is +nothing to report. History builds up automatically as you write.

+`) + return []byte(b.String()) + } + + b.WriteString(renderStats(d)) + b.WriteString(renderChart(d)) + b.WriteString(renderSessions(d)) + b.WriteString(renderIntegrity(d)) + b.WriteString(passportLimits) + b.WriteString("\n") + + return []byte(b.String()) +} + +// renderStats is the headline row — the numbers a reader wants before deciding +// whether to study the chart. +func renderStats(d passportData) string { + final := d.Versions[len(d.Versions)-1].WordCount + + tiles := []struct{ value, label string }{ + {fmt.Sprintf("%d", len(d.Versions)), "snapshots saved"}, + {humanDuration(d.Span), "from first to last edit"}, + {fmt.Sprintf("%d", len(d.Sessions)), pluralize(len(d.Sessions), "writing session", "writing sessions")}, + {humanDuration(d.ActiveTime), "spent actively editing"}, + {fmt.Sprintf("%d", final), "words in the final draft"}, + } + + var b strings.Builder + b.WriteString(`
`) + for _, t := range tiles { + fmt.Fprintf(&b, `
%s%s
`, + htmlEscape(t.value), htmlEscape(t.label)) + } + b.WriteString("
\n") + return b.String() +} + +// renderChart draws word count as a step line — the count is only known at +// snapshot moments, and a step says that honestly where a smooth curve would +// invent values in between. Shaded bands mark writing sessions. +// +// The x axis is snapshot order, not wall-clock time, and this is deliberate. On +// a linear time axis an essay written in three half-hour sittings across three +// days renders as three vertical cliffs separated by empty space: all the actual +// writing is crushed into one percent of the width, and the result looks exactly +// like text pasted in three chunks — the opposite of what happened. Because +// auto-snapshots are throttled to roughly one per few minutes of *active* +// editing, snapshot order is already close to proportional to time spent +// writing. So the plot gives its width to the writing and compresses the breaks, +// which are drawn as explicit labelled gaps rather than silently removed. +// +// One series, so no legend: the heading names it. +func renderChart(d passportData) string { + maxW := 0 + for _, v := range d.Versions { + if v.WordCount > maxW { + maxW = v.WordCount + } + } + yTop := niceCeil(maxW) + + y := func(words int) float64 { + if yTop <= 0 { + return padT + plotH + } + return padT + plotH - float64(words)/float64(yTop)*plotH + } + + // Lay snapshots out in slots: one per snapshot, plus a gutter between + // sessions for the break marker. + slots := float64(len(d.Versions)) + gutterSlots*float64(len(d.Sessions)-1) + sw := plotW / slots + + xs := make([]float64, len(d.Versions)) + bandStart := make([]float64, len(d.Sessions)) + bandEnd := make([]float64, len(d.Sessions)) + + cursor, vi := 0.0, 0 + for si, s := range d.Sessions { + if si > 0 { + cursor += gutterSlots + } + bandStart[si] = padL + cursor*sw + for k := 0; k < s.Snapshots; k++ { + xs[vi] = padL + (cursor+0.5)*sw + cursor++ + vi++ + } + bandEnd[si] = padL + cursor*sw + } + + var b strings.Builder + fmt.Fprintf(&b, `
+

How the draft grew

+ +`, chartW, chartH) + + // Session bands sit behind everything; each carries a native tooltip. + for i, s := range d.Sessions { + w := bandEnd[i] - bandStart[i] + if w < minBandW { + w = minBandW + } + fmt.Fprintf(&b, `Session %d: %s, %s, %d snapshots +`, bandStart[i], padT, w, plotH, roseWash, i+1, + htmlEscape(formatWhen(s.Start)), htmlEscape(humanDuration(s.Duration())), s.Snapshots) + } + + // Recessive gridlines with y labels at 0 / half / top. + for _, gv := range []int{0, yTop / 2, yTop} { + gy := y(gv) + fmt.Fprintf(&b, ` +%d +`, padL, gy, chartW-padR, gy, roseLight, padL-8, gy+4, gv) + } + + // Break markers in the gutters, so compressed time is stated, not hidden. + for i := 1; i < len(d.Sessions); i++ { + mid := (bandEnd[i-1] + bandStart[i]) / 2 + gap := d.Sessions[i].Start.Sub(d.Sessions[i-1].End) + fmt.Fprintf(&b, ` +%s +`, mid, padT, mid, padT+plotH, roseLight, mid, padT+plotH+13, htmlEscape(humanDuration(gap)+" away")) + } + + // Step path: hold the previous value until the next snapshot lands. + var path strings.Builder + fmt.Fprintf(&path, "M %.1f %.1f", xs[0], y(d.Versions[0].WordCount)) + for i := 1; i < len(d.Versions); i++ { + fmt.Fprintf(&path, " L %.1f %.1f L %.1f %.1f", + xs[i], y(d.Versions[i-1].WordCount), xs[i], y(d.Versions[i].WordCount)) + } + fmt.Fprintf(&b, ` +`, path.String(), rose) + + // Pre-empt the obvious question: label the largest single jump when it is a + // big share of the finished draft, rather than letting a reader find it. + if d.NoteJump && d.LargestJumpIdx < len(xs) { + jx, jy := xs[d.LargestJumpIdx], y(d.Versions[d.LargestJumpIdx].WordCount) + + // Flip the label inboard near the right edge so it can't overflow, and + // push it below the point when the point sits near the top. + anchor, dx := "start", 9.0 + if jx > float64(chartW)*0.6 { + anchor, dx = "end", -9.0 + } + ly := jy - 10 + if ly < padT+12 { + ly = jy + 18 + } + + fmt.Fprintf(&b, ` +largest single addition: +%d words +`, jx, jy, rose, surface, jx+dx, ly, anchor, d.LargestJump) + } + + fmt.Fprintf(&b, ` +

Each shaded band is one writing session, %s to %s. Width follows +snapshots saved, so time spent writing gets the space and breaks are compressed to +the labelled gaps.

+
+`, htmlEscape(formatDay(d.FirstAt)), htmlEscape(formatDay(d.LastAt))) + + return b.String() +} + +func renderSessions(d passportData) string { + var b strings.Builder + b.WriteString(`
+

Writing sessions

+ + + +`) + for i, s := range d.Sessions { + fmt.Fprintf(&b, ` +`, i+1, htmlEscape(formatWhen(s.Start)), htmlEscape(humanDuration(s.Duration())), + s.Snapshots, s.WordsAdded) + } + b.WriteString("
#StartedLengthSnapshotsNet words
%d%s%s%d%+d
\n
\n") + return b.String() +} + +// renderIntegrity explains the hash chain in plain language, including when it +// cannot vouch for something. +func renderIntegrity(d passportData) string { + var headline, detail string + + switch d.ChainStatus { + case chainVerified: + headline = "History intact" + detail = "Every snapshot matches its own contents and links correctly to the one before it. Nothing in this history has been altered or removed since it was recorded." + case chainGaps: + headline = "History intact, with gaps" + detail = "Every snapshot matches its own contents, but some older automatic snapshots have been cleared to save space, so the record is not continuous. Turn on “keep full history” for this document to stop that happening." + case chainPartial: + headline = "Partly verifiable" + detail = fmt.Sprintf("%d snapshot(s) were recorded before this document started tracking integrity, so they cannot be checked. Everything recorded since then matches.", d.UnhashedCount) + case chainUnverifiable: + headline = "Not verifiable" + detail = "These snapshots were recorded before integrity tracking existed. The timeline above is still the record that was saved as you wrote; it simply cannot be checked for later alteration." + case chainBroken: + headline = "Integrity check failed" + detail = "At least one snapshot does not match what was recorded for it. This can mean the history was edited after the fact, or that the database was restored from a backup or copied between machines." + } + + return fmt.Sprintf(`
+

%s

+

%s

+
+`, htmlEscape(d.ChainStatus), htmlEscape(headline), htmlEscape(detail)) +} + +// passportLimits states plainly what the report does and does not establish. +// Overclaiming would be worse than useless: a reader who catches the report +// overstating its case discounts the whole thing. +const passportLimits = `
+

How to read this

+

A document written over time leaves a trail: many snapshots, uneven growth, +words added and cut and added again across separate sittings. A document that was +pasted in from elsewhere tends to arrive nearly whole, in one or two snapshots, +with little revision after.

+

What this report shows is the record Petal saved automatically while the +document was open, roughly every few minutes of active editing.

+

What it does not show. It cannot prove who was at the +keyboard, and it cannot tell whether text typed into the editor was composed +there or copied from another window. It is evidence of a writing process, not a +certificate of authorship. It is most useful read alongside the drafts +themselves.

+
+` + +// --- formatting helpers ----------------------------------------------------- + +func formatWhen(t time.Time) string { return t.Local().Format("2 Jan 2006, 3:04 PM") } +func formatDay(t time.Time) string { return t.Local().Format("2 Jan 2006") } + +// humanDuration renders a span at the coarsest useful precision — a reader cares +// that a session ran "2h 40m", never that it ran 2h40m12s. +func humanDuration(d time.Duration) string { + if d < time.Minute { + return "under a minute" + } + days := int(d.Hours()) / 24 + hours := int(d.Hours()) % 24 + mins := int(d.Minutes()) % 60 + + switch { + case days > 0 && hours > 0: + return fmt.Sprintf("%dd %dh", days, hours) + case days > 0: + return fmt.Sprintf("%dd", days) + case hours > 0 && mins > 0: + return fmt.Sprintf("%dh %dm", hours, mins) + case hours > 0: + return fmt.Sprintf("%dh", hours) + default: + return fmt.Sprintf("%dm", mins) + } +} + +func pluralize(n int, one, many string) string { + if n == 1 { + return one + } + return many +} + +// niceCeil rounds a maximum up to a round number so gridlines land on values a +// reader can hold in their head. +func niceCeil(n int) int { + if n <= 0 { + return 0 + } + mag := math.Pow(10, math.Floor(math.Log10(float64(n)))) + return int(math.Ceil(float64(n)/(mag/2)) * (mag / 2)) +} + +// passportHead is the page shell: one %s for the title. Print rules keep the +// chart and the caveats on the page rather than letting them break across sheets. +const passportHead = ` + + + + +Writing passport — %s + + + +` diff --git a/internal/docs/passport_test.go b/internal/docs/passport_test.go new file mode 100644 index 0000000..edada25 --- /dev/null +++ b/internal/docs/passport_test.go @@ -0,0 +1,376 @@ +package docs + +import ( + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "regexp" + "strconv" + "strings" + "testing" + "time" + + "gitea.parodia.dev/drwily/petal/internal/db" +) + +// chained builds a valid hash-chained snapshot run from (minutes-offset, words) +// pairs, so tests can describe a writing history in terms a reader recognises +// and get correct hashes for free. +func chained(docID string, base time.Time, points ...[2]int) []db.DocumentVersion { + var ( + out []db.DocumentVersion + prev string + ) + for i, p := range points { + at := base.Add(time.Duration(p[0]) * time.Minute) + text := strings.Repeat("word ", p[1]) + v := db.DocumentVersion{ + ID: fmt.Sprintf("v%d", i), + DocID: docID, + ContentText: text, + WordCount: p[1], + Kind: db.VersionKindAuto, + CreatedAt: at, + PrevHash: prev, + } + v.ContentHash = chainHash(prev, docID, at, p[1], text) + prev = v.ContentHash + out = append(out, v) + } + return out +} + +func TestBuildPassportSessions(t *testing.T) { + base := time.Date(2026, 3, 2, 9, 0, 0, 0, time.UTC) + doc := db.Document{ID: "d1", Title: "Essay"} + + // Two sittings: 09:00–09:30, then a three-hour break, then 12:30–13:00. + vs := chained("d1", base, + [2]int{0, 40}, [2]int{15, 120}, [2]int{30, 210}, + [2]int{210, 260}, [2]int{240, 330}, + ) + + d := buildPassport(doc, vs) + + if len(d.Sessions) != 2 { + t.Fatalf("sessions = %d, want 2", len(d.Sessions)) + } + if got := d.Sessions[0].Duration(); got != 30*time.Minute { + t.Errorf("session 1 duration = %v, want 30m", got) + } + if got := d.Sessions[1].Snapshots; got != 2 { + t.Errorf("session 2 snapshots = %d, want 2", got) + } + if got := d.Span; got != 4*time.Hour { + t.Errorf("span = %v, want 4h", got) + } + // Active time counts only time inside sessions, never the break. + if got := d.ActiveTime; got != 60*time.Minute { + t.Errorf("active time = %v, want 60m", got) + } + // Session 2 measures from session 1's final count (210 → 330). + if got := d.Sessions[1].WordsAdded; got != 120 { + t.Errorf("session 2 words = %d, want 120", got) + } + if d.ChainStatus != chainVerified { + t.Errorf("chain = %q, want %q", d.ChainStatus, chainVerified) + } +} + +func TestBuildPassportFlagsLargeJump(t *testing.T) { + base := time.Date(2026, 3, 2, 9, 0, 0, 0, time.UTC) + doc := db.Document{ID: "d1"} + + t.Run("steady growth is not flagged", func(t *testing.T) { + vs := chained("d1", base, [2]int{0, 100}, [2]int{5, 200}, [2]int{10, 300}, [2]int{15, 400}) + if d := buildPassport(doc, vs); d.NoteJump { + t.Errorf("even growth flagged a jump of %d", d.LargestJump) + } + }) + + t.Run("a paste-shaped jump is flagged", func(t *testing.T) { + vs := chained("d1", base, [2]int{0, 20}, [2]int{5, 40}, [2]int{10, 900}) + d := buildPassport(doc, vs) + if !d.NoteJump { + t.Fatal("large jump not flagged") + } + if d.LargestJump != 860 { + t.Errorf("largest jump = %d, want 860", d.LargestJump) + } + if !d.LargestJumpAt.Equal(base.Add(10 * time.Minute)) { + t.Errorf("jump at %v, want +10m", d.LargestJumpAt) + } + }) +} + +func TestVerifyChain(t *testing.T) { + base := time.Date(2026, 3, 2, 9, 0, 0, 0, time.UTC) + good := func() []db.DocumentVersion { + return chained("d1", base, [2]int{0, 50}, [2]int{5, 90}, [2]int{10, 160}) + } + + t.Run("intact chain verifies", func(t *testing.T) { + got, _ := verifyChain(db.Document{ID: "d1"}, good()) + if got != chainVerified { + t.Errorf("got %q, want %q", got, chainVerified) + } + }) + + t.Run("edited content breaks it", func(t *testing.T) { + vs := good() + vs[1].ContentText = "something else entirely" + if got, _ := verifyChain(db.Document{ID: "d1"}, vs); got != chainBroken { + t.Errorf("got %q, want %q", got, chainBroken) + } + }) + + t.Run("backdating breaks it", func(t *testing.T) { + vs := good() + vs[2].CreatedAt = base.Add(-time.Hour) + if got, _ := verifyChain(db.Document{ID: "d1"}, vs); got != chainBroken { + t.Errorf("got %q, want %q", got, chainBroken) + } + }) + + t.Run("a removed snapshot reads as a gap when pruning is allowed", func(t *testing.T) { + vs := good() + pruned := []db.DocumentVersion{vs[0], vs[2]} // middle snapshot gone + got, _ := verifyChain(db.Document{ID: "d1"}, pruned) + if got != chainGaps { + t.Errorf("got %q, want %q", got, chainGaps) + } + }) + + t.Run("a removed snapshot is tampering when history is preserved", func(t *testing.T) { + vs := good() + pruned := []db.DocumentVersion{vs[0], vs[2]} + got, _ := verifyChain(db.Document{ID: "d1", PreserveHistory: true}, pruned) + if got != chainBroken { + t.Errorf("got %q, want %q", got, chainBroken) + } + }) + + t.Run("pre-chain snapshots are partial, not failures", func(t *testing.T) { + vs := good() + vs[0].ContentHash, vs[0].PrevHash = "", "" + got, unhashed := verifyChain(db.Document{ID: "d1"}, vs) + if got != chainPartial { + t.Errorf("got %q, want %q", got, chainPartial) + } + if unhashed != 1 { + t.Errorf("unhashed = %d, want 1", unhashed) + } + }) + + t.Run("no hashes at all is unverifiable", func(t *testing.T) { + vs := good() + for i := range vs { + vs[i].ContentHash, vs[i].PrevHash = "", "" + } + if got, _ := verifyChain(db.Document{ID: "d1"}, vs); got != chainUnverifiable { + t.Errorf("got %q, want %q", got, chainUnverifiable) + } + }) +} + +// The report must survive the degenerate histories — one snapshot, an empty +// document — rather than dividing by a zero span or a zero maximum. +func TestRenderPassportEdgeCases(t *testing.T) { + base := time.Date(2026, 3, 2, 9, 0, 0, 0, time.UTC) + + t.Run("no history", func(t *testing.T) { + out := string(renderPassport(buildPassport(db.Document{Title: "Empty"}, nil))) + if !strings.Contains(out, "no saved history") { + t.Errorf("missing empty-state copy:\n%s", out) + } + }) + + t.Run("single snapshot", func(t *testing.T) { + vs := chained("d1", base, [2]int{0, 12}) + out := string(renderPassport(buildPassport(db.Document{ID: "d1", Title: "One"}, vs))) + if strings.Contains(out, "NaN") || strings.Contains(out, "+Inf") { + t.Errorf("degenerate geometry leaked into output:\n%s", out) + } + }) + + t.Run("empty document", func(t *testing.T) { + vs := chained("d1", base, [2]int{0, 0}, [2]int{5, 0}) + out := string(renderPassport(buildPassport(db.Document{ID: "d1"}, vs))) + if strings.Contains(out, "NaN") { + t.Errorf("zero word count produced NaN:\n%s", out) + } + }) + + t.Run("title is escaped", func(t *testing.T) { + doc := db.Document{ID: "d1", Title: ``} + out := string(renderPassport(buildPassport(doc, chained("d1", base, [2]int{0, 5})))) + if strings.Contains(out, "