Merge the five small-task branches

2026-07-31 23:11:26 +04:00
parent 7ad3c9a408 b0f5a16ec9
commit 9b8bdf73cc
7 changed files with 737 additions and 0 deletions
@@ -0,0 +1,158 @@
+package main
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/kami/maven/internal/loop"
+	"github.com/kami/maven/internal/store"
+)
+
+// Vikunja #281 — the fourth delivery outcome: a care candidate the restraint
+// gate suppresses (quiet hours / away / calendar-busy) is not necessarily
+// lost. If it's worth resurfacing (loop.DigestEligible), it's durably held
+// (internal/store's digest_entries) and spoken as one bundle once speaking
+// is appropriate again — never while the suppression reason still holds.
+
+func breakTrace(blockedBy string) *loop.TickTrace {
+	return &loop.TickTrace{
+		RuleTraces: []loop.RuleTrace{{
+			RuleName:        "break",
+			Severity:        loop.Sev2,
+			PredicateResult: true,
+			GateResult:      false,
+			GateBlockedBy:   blockedBy,
+		}},
+	}
+}
+
+// TestSuppressedCareDigestsAcrossQuietHours — a Sev2 care candidate blocked
+// by quiet hours is enqueued into the durable digest, and is spoken as a
+// "digest" nudge only once quiet hours actually end — never while still
+// suppressed (that would just be a second way to nag through quiet hours).
+func TestSuppressedCareDigestsAcrossQuietHours(t *testing.T) {
+	st := newTestStore(t)
+	sink := &fakeSink{}
+	tl := newTestTickLoop(t, st, sink, nil)
+	ctx := context.Background()
+	now := refNow()
+
+	quiet := loop.State{Now: now, QuietHours: true, Presence: store.Present}
+	tl.enqueueSuppressedDigest(ctx, breakTrace("quiet_hours"), quiet, now)
+
+	entries, err := st.PendingDigestEntries(ctx, now)
+	if err != nil {
+		t.Fatalf("pending: %v", err)
+	}
+	if len(entries) != 1 || entries[0].Rule != "break" {
+		t.Fatalf("want 1 pending digest entry for break, got %+v", entries)
+	}
+
+	// still quiet hours: draining now must not speak — the same restraint
+	// that suppressed the live nudge must suppress the bundle too.
+	tl.maybeDrainDigest(ctx, quiet, now)
+	if len(sink.sends) != 0 {
+		t.Fatalf("digest must not drain while quiet hours holds, got %+v", sink.sends)
+	}
+
+	// quiet hours end: this is the moment speaking is appropriate again.
+	after := now.Add(time.Hour)
+	clear := loop.State{Now: after, QuietHours: false, Presence: store.Present}
+	tl.maybeDrainDigest(ctx, clear, after)
+
+	if len(sink.sends) != 1 {
+		t.Fatalf("want exactly 1 dispatched digest bundle, got %d: %+v", len(sink.sends), sink.sends)
+	}
+	if sink.sends[0].RuleName != "digest" {
+		t.Fatalf("want RuleName digest, got %q", sink.sends[0].RuleName)
+	}
+
+	remaining, err := st.PendingDigestEntries(ctx, after)
+	if err != nil {
+		t.Fatalf("pending after drain: %v", err)
+	}
+	if len(remaining) != 0 {
+		t.Fatalf("drained entry must no longer be pending, got %+v", remaining)
+	}
+}
+
+// TestSuppressedCareDigestDedupesAcrossTicks — quiet hours holding for
+// several ticks must not enqueue several copies of the same suppressed
+// nudge; he hears it once when the bundle finally drains.
+func TestSuppressedCareDigestDedupesAcrossTicks(t *testing.T) {
+	st := newTestStore(t)
+	sink := &fakeSink{}
+	tl := newTestTickLoop(t, st, sink, nil)
+	ctx := context.Background()
+	now := refNow()
+
+	quiet := loop.State{Now: now, QuietHours: true, Presence: store.Present}
+	for i := 0; i < 3; i++ {
+		tl.enqueueSuppressedDigest(ctx, breakTrace("quiet_hours"), quiet, now.Add(time.Duration(i)*time.Minute))
+	}
+
+	entries, err := st.PendingDigestEntries(ctx, now)
+	if err != nil {
+		t.Fatalf("pending: %v", err)
+	}
+	if len(entries) != 1 {
+		t.Fatalf("3 suppressions of the same nudge must collapse to 1 pending entry, got %d", len(entries))
+	}
+}
+
+// TestSuppressedCareDigestExpiresRatherThanDeliveringLate — an entry that
+// aged out before the suppression cleared is dropped, not spoken late: a
+// two-day-old "you skipped a break" is noise, not news.
+func TestSuppressedCareDigestExpiresRatherThanDeliveringLate(t *testing.T) {
+	st := newTestStore(t)
+	sink := &fakeSink{}
+	tl := newTestTickLoop(t, st, sink, nil)
+	ctx := context.Background()
+	now := refNow()
+
+	quiet := loop.State{Now: now, QuietHours: true, Presence: store.Present}
+	tl.enqueueSuppressedDigest(ctx, breakTrace("quiet_hours"), quiet, now)
+
+	// well past digestExpiry (24h) before the suppression ever clears.
+	stale := now.Add(48 * time.Hour)
+	tl.expireStaleDigest(ctx, stale)
+
+	clear := loop.State{Now: stale, QuietHours: false, Presence: store.Present}
+	tl.maybeDrainDigest(ctx, clear, stale)
+
+	if len(sink.sends) != 0 {
+		t.Fatalf("a stale digest entry must be dropped, not delivered late; got %+v", sink.sends)
+	}
+}
+
+// TestSuppressedCareDigestIgnoresHighSeverity — defense in depth at the
+// wiring layer: even if a RuleTrace somehow showed a high-severity rule
+// blocked by a care-only gate reason, the tick driver must not durably
+// digest it. Alarms bypass the gate and deliver now, unchanged; they must
+// never be silently delayed into a bundle.
+func TestSuppressedCareDigestIgnoresHighSeverity(t *testing.T) {
+	st := newTestStore(t)
+	sink := &fakeSink{}
+	tl := newTestTickLoop(t, st, sink, nil)
+	ctx := context.Background()
+	now := refNow()
+
+	trace := &loop.TickTrace{RuleTraces: []loop.RuleTrace{{
+		RuleName:        "service_down",
+		Severity:        loop.Sev4,
+		PredicateResult: true,
+		GateResult:      false,
+		GateBlockedBy:   "quiet_hours",
+	}}}
+	quiet := loop.State{Now: now, QuietHours: true, Presence: store.Present}
+	tl.enqueueSuppressedDigest(ctx, trace, quiet, now)
+
+	entries, err := st.PendingDigestEntries(ctx, now)
+	if err != nil {
+		t.Fatalf("pending: %v", err)
+	}
+	if len(entries) != 0 {
+		t.Fatalf("high severity must never be digested, got %+v", entries)
+	}
+}
@@ -180,6 +180,17 @@ func (t *tickLoop) tick(ctx context.Context, now time.Time) {
 	// (with dedup) avoids re-queueing the same rule after a flush.
 	t.maybeFlush(ctx, now, state)

+	// gate-suppressed digest (Vikunja #281): rules the restraint gate held
+	// back this tick (quiet hours / away / calendar-busy), not because they
+	// weren't due, but because it wasn't the moment. Some of those are worth
+	// resurfacing later instead of just being lost — loop.DigestEligible
+	// draws that line. This is a SEPARATE mechanism from the in-memory
+	// digestQ above: that one batches candidates the gate already ALLOWED to
+	// fire; this one durably holds candidates the gate BLOCKED.
+	t.enqueueSuppressedDigest(ctx, trace, state, now)
+	t.expireStaleDigest(ctx, now)
+	t.maybeDrainDigest(ctx, state, now)
+
 	// routines: operator-declared scheduled behaviors. fire the ones whose cron
 	// crossed since last fire, delivered through the normal routing (voice when
 	// present, away channels otherwise). bodies are literal operator text — not
@@ -393,6 +404,133 @@ func (t *tickLoop) detectPatterns(ctx context.Context, now time.Time) {
 	}
 }

+// digestExpiry — how long a gate-suppressed care nudge stays worth
+// resurfacing. 24h: these are daily-cadence rules (water/meal/break run on
+// hour-scale cooldowns and re-derive from facts that reset every day), so a
+// digest entry that outlives one full day is describing a day that's already
+// over — "you skipped a break yesterday" said tomorrow evening is noise, not
+// news. Bounding at one day also means a digest can never silently span a
+// weekend of quiet hours into an unbounded backlog.
+const digestExpiry = 24 * time.Hour
+
+// maxDigestSpokenItems — the bundle read-out is capped so "batched, not
+// dropped" cannot regress into "she dumps twelve things on me the moment I
+// walk in" — a digest that nags in bulk is worse than the drops it replaced.
+// Anything beyond the cap is still marked drained (it did get its moment;
+// the cap limits WORDS, not whether it counted) and folded into a trailing
+// count instead of being spoken in full.
+const maxDigestSpokenItems = 3
+
+// enqueueSuppressedDigest scans this tick's trace for care candidates the
+// gate blocked for a genuine restraint reason and durably records the
+// digest-eligible ones (loop.DigestEligible). Phrasing happens once, here,
+// at enqueue time — not re-derived at drain time — the same way queueNudge
+// phrases once and caches, so a rule suppressed for hours isn't re-prompting
+// the LLM every tick it stays blocked (EnqueueDigestEntry's rule+body dedupe
+// makes repeat calls here harmless, but skipping the phrase call entirely
+// when a pending entry already exists avoids the LLM round-trip too).
+func (t *tickLoop) enqueueSuppressedDigest(ctx context.Context, trace *loop.TickTrace, state loop.State, now time.Time) {
+	if trace == nil {
+		return
+	}
+	for _, tr := range trace.RuleTraces {
+		if !tr.PredicateResult || tr.GateResult {
+			continue // didn't want to fire, or wasn't suppressed
+		}
+		if !loop.DigestEligible(tr.Severity, tr.GateBlockedBy) {
+			continue
+		}
+		rule := loop.Rule{Name: tr.RuleName, Severity: tr.Severity}
+		cand := loop.Candidate{Rule: rule, Severity: tr.Severity, State: state}
+		pn, err := t.phraser.PhraseNudge(ctx, cand)
+		if err != nil {
+			log.Printf("tick: phrase digest candidate %s: %v", tr.RuleName, err)
+			continue
+		}
+		expires := now.Add(digestExpiry)
+		if _, deduped, err := t.store.EnqueueDigestEntry(ctx, tr.RuleName, int(tr.Severity), pn.Body, now, expires); err != nil {
+			log.Printf("tick: enqueue digest entry %s: %v", tr.RuleName, err)
+		} else if deduped {
+			// same suppressed nudge already pending — nothing new to say.
+			continue
+		}
+	}
+}
+
+// expireStaleDigest sweeps entries past their expiry once per tick — cheap
+// bookkeeping, mirrors ReconcileStaleDeliveryAttempts's shape.
+func (t *tickLoop) expireStaleDigest(ctx context.Context, now time.Time) {
+	n, err := t.store.ExpireStaleDigestEntries(ctx, now)
+	if err != nil {
+		log.Printf("tick: expire stale digest entries: %v", err)
+		return
+	}
+	if n > 0 {
+		log.Printf("tick: expired %d stale digest entr(y/ies) unspoken", n)
+	}
+}
+
+// maybeDrainDigest speaks the pending digest bundle once the gate's
+// suppression reasons have actually cleared — quiet hours over, back from
+// away, out of the meeting. Draining while still suppressed would just be a
+// second way to nag through quiet hours; the bundle waits for the same "is
+// it allowed right now" condition a live nudge already waits for.
+func (t *tickLoop) maybeDrainDigest(ctx context.Context, state loop.State, now time.Time) {
+	if state.QuietHours || state.CalendarBusy || state.Presence == store.Away {
+		return
+	}
+	entries, err := t.store.PendingDigestEntries(ctx, now)
+	if err != nil {
+		log.Printf("tick: pending digest entries: %v", err)
+		return
+	}
+	if len(entries) == 0 {
+		return
+	}
+
+	spoken := entries
+	extra := 0
+	if len(spoken) > maxDigestSpokenItems {
+		spoken = entries[:maxDigestSpokenItems]
+		extra = len(entries) - maxDigestSpokenItems
+	}
+	var b strings.Builder
+	maxSev := 0
+	for i, e := range spoken {
+		if i > 0 {
+			b.WriteString(" · ")
+		}
+		b.WriteString(e.Body)
+		if e.Severity > maxSev {
+			maxSev = e.Severity
+		}
+	}
+	if extra > 0 {
+		fmt.Fprintf(&b, " · и ещё %d", extra)
+	}
+	body := b.String()
+	summary := fmt.Sprintf("%d отложенных уведомлений", len(entries))
+
+	cand := loop.Candidate{
+		Rule:     loop.Rule{Name: "digest", Severity: loop.Severity(maxSev)},
+		Severity: loop.Severity(maxSev),
+		State:    state,
+	}
+	pn := delivery.PhrasedNudge{Candidate: cand, Body: body, Summary: summary}
+	t.cachePhrase(pn)
+	if _, err := t.dispatcher.DispatchNudge(ctx, pn, now); err != nil {
+		log.Printf("tick: dispatch digest bundle: %v", err)
+		return // leave entries pending; retried next tick
+	}
+	ids := make([]int64, len(entries))
+	for i, e := range entries {
+		ids[i] = e.ID
+	}
+	if err := t.store.DrainDigestEntries(ctx, ids, now); err != nil {
+		log.Printf("tick: drain digest entries: %v", err)
+	}
+}
+
 // routinesFromConfig maps the config's routine blocks to the engine type.
 // Validation (cron parses, name/body present, severity defaulted) already ran
 // in config.Load, so this is a pure field copy.