summarizer

Overview ¶

Package summarizer is the home of Harbor's production LLM-backed summarisation: the memory-subsystem `memory.Summarizer` and the planner-trajectory `planner.Summariser`.

Two interfaces — do not conflate ¶

The package satisfies TWO unrelated interfaces that happen to share a name root:

• `memory.Summarizer` (Summarizer, `New`) — the memory subsystem's rolling-summary compactor: conversation window (previous summary + evicted turns) in, free-text summary out.
• `planner.Summariser` (TrajectorySummariser, `NewTrajectorySummariser`) — the runtime's trajectory compression producer: a run's Trajectory in, the five-field `planner.TrajectorySummary` out (structured-output JSON-schema mode).; invoked by `planner.CompressionRunner.MaybeCompress` from the steering RunLoop when `Budget.TokenBudget` is exceeded.

Different signatures, different inputs, different consumers — the shared home exists because both are "LLM client + versioned compaction prompt" compositions (the import direction is clean: summarizer → planner/memory → llm; nothing imports back).

The remainder of this doc describes the memory-subsystem Summarizer; see trajectory.go for the TrajectorySummariser.

Before the only `memory.Summarizer` Harbor shipped was `strategy.EchoSummarizer` — a deterministic test stub that concatenated turns into a single string. The runtime's `rolling_summary` strategy required an *injected* Summarizer with no default, so a `harbor dev` boot against `memory.strategy: rolling_summary` would have crashed with `nil Summarizer` (or worse, silently fallen back to a test stub if a future PR wired one).

Harbor closes that seam: `summarizer.New(client)` composes an `llm.LLMClient` with a versioned compaction prompt and returns a `memory.Summarizer` ready to wire into `memory.Open(..., Deps{Summarizer: ...})`. The dev server wires this when an operator configures `memory.strategy: rolling_summary` (the same conditional the spec laid down).

The compaction prompt ¶

The prompt is versioned (`PromptVersion`) so a later prompt-craft improvement bumps the constant and the prior version stays available for golden-test pinning. The template uses an instruction-tuned shape that works against every native provider:

• One system message anchors the summariser persona: "You are a concise meeting-minutes summariser. Compress the conversation turns below into a short, factual rolling summary..."
• One user message stitches the previous summary (if any) + the evicted turns into a single payload. The Summarize implementation uses the request's `PreviousSummary` + `Turns` directly — no reformatting beyond a stable line-prefix scheme so the LLM sees consistent input shape across calls.

Concurrent reuse ¶

`Summarizer` is a compiled artifact: the embedded `llm.LLMClient` and the compaction prompt template are set once at construction (`New`). One Summarizer is safe to share across N concurrent `Summarize` goroutines; the per-call state lives on the function stack and in `ctx`. Concurrent_test.go pins N≥100 under -race.

Identity (CLAUDE.md §6 rule 9) ¶

`Summarize` is identity-mandatory: the request's `identity.Quadruple` is propagated into ctx via `identity.With` before the LLM call so the safety pass sees the same identity the memory subsystem's caller supplied. The LLM-edge audit + governance + retry layers all key on this identity; without it, the safety pass rejects with `ErrIdentityRequired`.

Fail-loud (CLAUDE.md §5) ¶

An LLM call that fails surfaces the wrapped error verbatim — the summariser does NOT silently degrade to an echo or a truncation. Callers handle `Summarize` errors via the `memory.strategy.rolling_summary` health FSM: the strategy transitions from healthy → retry → degraded as failures accumulate.

§13 primitive-with-consumer ¶

the `harbor dev` subcommand is the §13 first consumer of this Summarizer. The dev wiring constructs `summarizer.New(client)` and passes it through `memory.Deps.Summarizer` when the operator configured `memory.strategy: rolling_summary`. Without the summariser would be a dormant primitive; with it is wired end-to-end on the production code path.

trajectory.go — the production LLM-backed planner.Summariser. Distinct from the memory-subsystem Summarizer in summarizer.go: see the package godoc's two-interface disambiguation.