@hydraharness/harness-compaction 0.1.1-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @hydraharness/harness-compaction
+
+The **`CompactionEngine`** (`ctx.compaction`) defines WHAT compaction does — decide when history is too large and summarize an older range into a single surface node — without saying HOW.
+
+This package owns the Service Definition role of the compaction capability, split so each role evolves (and swaps) independently:
+
+| Package | Role |
+|---|---|
+| `@hydraharness/harness-compaction` (this) | Service Definition: abstract service + `compaction/*` events + `CompactionResult` + correlated checkpoint-source constructor + tool-pairing boundary helpers |
+| `@hydraharness/harness-compaction-basic` | Service Provider: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
+| `@hydraharness/harness-command-compact` | Consumer: the human `/compact` command over `ctx.compaction.compactNow()` |
+
+Unlike the bash seam, this Service Definition depends on `@hydraharness/harness-session` and `@hydraharness/harness-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "Service Definition depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+
+## Service API (`ctx.compaction`)
+
+All three operations are **abstract** — the backend owns trigger policy, retention, event sequencing, and summarization. Reusable request measurement is a separate service, [`ctx.tokenMeter`](../../llm/token-meter/README.md), rather than part of this Service Definition.
+
+| Member | Semantics |
+|---|---|
+| `compactIfNeeded(agent, trigger, signal)` | Consider automatic compaction for `trigger: 'pressure' \| 'context-overflow'`. A pressure trigger may apply the backend's threshold and retained-tail policy; a confirmed overflow may force a useful balanced reduction. Returns the `CompactionResult`, or `null` when no safe range exists. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
+| `compactNow(agent, signal)` | Explicitly compact one useful balanced older span even below automatic pressure. It synchronously reserves idle turn admission before yielding, writes nothing when no useful span exists, records a standalone `compaction/* { turn: null }` attempt before summarization, and awaits its durability checkpoint before release. Expected operational failures use `ManualCompactionError`; cancellation rethrows the exact abort reason. |
+| `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node whose source comes from `compactCheckpointSource(compactionId)`. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
+
+`CompactionResult` keeps the raw summary and bookkeeping-event seqs available to callers alongside the shadowed range and token accounting; its drift-checked shape lives in the [compaction data-structure reference](../../../docs/subsystems/compaction.md#compactionresult).
+
+`compactIfNeeded` and `compactNow` take a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization. Automatic and explicit-region brackets recover their numeric owner from the currently open turn. Manual brackets require no open turn and stamp `turn: null`.
+
+`ManualCompactionError.code` is the closed set `busy | changed | summary | commit | persistence`. `changed` and `summary` mean the selected conversation surface was not replaced, but their failed attempt is still recorded in the session log. `commit` is deliberately neutral about partial mutation, and `persistence` means the in-memory bracket closed but its explicit flush failed.
+
+## Tool-pairing boundaries
+
+The Service Definition exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order.
+
+The private per-session cache is keyed by `session.surface.replaceGeneration` and the processed surface-entry count. An unchanged generation extends the fold with unseen tail entries only; a log-only append with no new surface entry does no event reads, while a replacement generation rebuilds current membership and balances. Missing event seqs and a `tool/result` without a preceding open call reject as corrupt surface state.
+
+## Surface contract
+
+`SurfaceEventType` is a closed union — only `user/message`, `assistant/message`, and `tool/result` may carry `surfaceOp`. A `compaction/*` event therefore **cannot** appear on the surface. A successful compaction instead:
+
+1. appends `compaction/start` (log-only) — acquires the lock,
+2. summarizes the range,
+3. appends `compaction/summary` (log-only) with the summary, range, shadowed seqs, token count, and provider/model call envelope,
+4. appends a single `user/message` with `source: compactCheckpointSource(compactionId, sourceCommandId?)` and `surfaceOp: { op: 'replace', start, end }` carrying the summary — **the only surface mutation in this operation**,
+5. appends `compaction/end` (log-only) — releases the lock.
+
+The surface mutation (step 4) sits **inside** the lock bracket: `compaction/end` is the last event, so the lock is never released before the mutation lands. A crash between `compaction/start` and `compaction/end` therefore leaves a detectable orphaned lock (a `compaction/start` with no matching `compaction/end`) rather than a `compaction/end` that falsely claims compaction finished while the surface was never shadowed.
+
+The marker pair names lock acquisition and release, not an exclusive event container. An idle `inject()` may append unrelated context between a manual start and end while summarization is pending. Manual stability therefore revalidates the selected span rather than demanding whole-surface equality; the positional replacement leaves that injected context visible after the checkpoint. Automatic compaction keeps whole-surface equality inside its active turn.
+
+`deriveMessages()` then renders the summary as a user-role message followed by the retained nodes. The shadowed events remain in the raw log, so replay is deterministic.
+
+## Blocking
+
+Compaction is serialized by one log-recorded lock shared by all entry points. Tail inspection independently finds the latest unmatched `compaction/start` and the newest `session/end-seed`. An unmatched start after that boundary is live and reports `busy`; an older unmatched start is stale evidence from a prior process lifecycle and does not block. The same end-seed transition clears the invariant companion's replay trace. A live bracket cannot cross a `turn/start` or `turn/end`; during adoption, repair boundaries in the inherited prefix remain replayable when the later end-seed proves their open bracket stale.
+
+The lock is the durable bracket, not a `WeakSet`, wrapper mutex, or client-side anchor. `compaction/start` is appended synchronously before summarization yields. Every later failure makes exactly one `compaction/end { error }` attempt; if that close append itself fails, the unmatched start remains the intentional busy signal and no flush is attempted. A successfully closed manual attempt is flushed even when it reports `changed` or `summary`, preserving the recorded attempt before turn admission is released.
+
+## Events
+
+The `compaction/*` events extend `SessionEventMap` (merge-extensible) via declaration merging — they are session events, not cordis `Events`, and all three are log-only (no `surfaceOp`). Per-event payloads and semantics are in the generated [persistence log event catalog](../../../docs/persistence-catalog.md).
+
+## Implementing a backend
+
+Subclass `CompactionEngine`, implement `compactIfNeeded`, `compactNow`, and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compaction`. Every successful backend creates its replacement user message source with `compactCheckpointSource(compactionId, sourceCommandId?)`; the required `compactionId` correlates the checkpoint with its `compaction/*` transaction, while `isCompactCheckpointSource()` recognizes the marker after persistence or cloning without depending on backend identity. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter.
+
+## Recognizing a checkpoint outside the host program (`./checkpoint`)
+
+`compactCheckpointSource()`, `CompactionCheckpointSource`, and `isCompactCheckpointSource()` are declared on the `@hydraharness/harness-compaction/checkpoint` subpath and re-exported from the root, so host-side consumers keep reading them from the root. The constructor requires the owning `CompactionId`, preventing backends from writing an uncorrelated marker that the package invariant must reject. The leaf imports no cordis and declares no module augmentation (the [`hydra-commands/brand`](../../interaction/commands/README.md) shape), which is what lets a client or wire program name the checkpoint source: the package **root** cannot enter such a program at all, because it reaches `@hydraharness/harness-session`'s root and that `Context` merge declares the host `sessions` service against the client's own (`TS2717` — one program per side, per [development.md](../../../docs/development.md#typescript-project-layout)). The web client's transcript adapter pins its plugin literal to the leaf's source type, so renaming the plugin id there is a compile error here.
+
+## Model Experience
+
+### Conversation history, when a backend is invoked
+
+#### What the model sees
+
+A successful implementation replaces an older surface range with one user-role summary checkpoint — a `user/message` carrying `surfaceOp: { op: 'replace', start, end }`; the raw events stay logged but stop appearing in derived model messages. The seam itself performs no rewrite.
+
+#### Token effect
+
+Zero direct tokens from this Service Definition. A backend trades many retained history tokens for one summary and leaves the recent tail unchanged.
+
+#### KV Cache effect
+
+A successful backend replacement invalidates reuse from the first shadowed history token; the seam itself does not alter a request.
+
+## Known Limitations and Deferred Work
+
+- **Human command, not a model tool** — `@hydraharness/harness-command-compact` exposes argument-free `/compact` through `ctx.commands`; no model-facing compaction tool is registered.
+- **Some single-unit overflow is out of contract** — balanced summary compaction cannot split one indivisible unit. The optional pruning companion can still repair a closed tool pair when text-bearing tool-result bulk is removable; a large non-tool node or a tool unit whose non-prunable remainder is oversized cannot be compacted.
+- **An envelope that alone approaches the window is not surface-compaction work** — compaction shrinks derived history, never the system prompt, tools, or session prefix.

package/lib/index.js

@@ -0,0 +1,183 @@
+import { Service } from "@hydraharness/cordis";
+//#region lib/types/brand.js
+/**
+* Brand an implementation-minted compaction identity.
+* @param id - opaque transaction identity.
+* @returns the same string, branded; no validation is performed.
+*/
+function CompactionId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/tool-pairing.js
+/**
+* Tool-pairing balance over a session surface. Compaction changes surface
+* positions, so safe cuts are derived from tool-call/result content in current
+* surface order rather than step markers.
+* @module @hydraharness/harness-compaction/tool-pairing
+*/
+const balanceCacheBySession = /* @__PURE__ */ new WeakMap();
+/** Return how one surface event changes the in-progress tool-call count. */
+function eventDelta(event) {
+	switch (event.type) {
+		case "assistant/message": return event.data.message.content.filter((block) => block.type === "tool-call").length;
+		case "tool/result": return -1;
+		default: return 0;
+	}
+}
+/** Read and validate the event named by a surface sequence. */
+function eventForSeq(events, seq) {
+	const event = events[seq];
+	if (event === void 0 || event.seq !== seq) throw new Error(`tool-pairing balance: surface seq ${seq} has no matching session event (corrupt surface)`);
+	return event;
+}
+/** Fold surface sequences not yet in the cache into its balance state. */
+function extendCache(session, cache, seqs) {
+	const processed = cache.cutBalanced.length - 1;
+	const tail = seqs.slice(processed);
+	const events = session.events;
+	const pendingCuts = [];
+	let inProgressToolCalls = cache.inProgressToolCalls;
+	for (const seq of tail) {
+		inProgressToolCalls += eventDelta(eventForSeq(events, seq));
+		if (inProgressToolCalls < 0) throw new Error(`tool-pairing balance: tool/result at surface seq ${seq} has no matching tool-call (corrupt surface)`);
+		pendingCuts.push(inProgressToolCalls === 0);
+	}
+	tail.forEach((seq, offset) => cache.indexBySeq.set(seq, processed + offset));
+	cache.cutBalanced = cache.cutBalanced.concat(pendingCuts);
+	cache.inProgressToolCalls = inProgressToolCalls;
+	return cache;
+}
+/** Return balance state synchronized with the current session surface. */
+function balanceCache(session) {
+	const surface = session.surface;
+	const seqs = surface.nodes;
+	const generation = surface.replaceGeneration;
+	const cached = balanceCacheBySession.get(session);
+	if (cached === void 0 || cached.generation !== generation || cached.cutBalanced.length - 1 > seqs.length) {
+		const rebuilt = extendCache(session, {
+			generation,
+			cutBalanced: [true],
+			indexBySeq: /* @__PURE__ */ new Map(),
+			inProgressToolCalls: 0
+		}, seqs);
+		balanceCacheBySession.set(session, rebuilt);
+		return rebuilt;
+	}
+	if (cached.cutBalanced.length - 1 < seqs.length) return extendCache(session, cached, seqs);
+	return cached;
+}
+/** Balance of the cut at a sequence's position plus offset, rejecting seqs outside current membership. */
+function cutBalance(cache, seq, offset) {
+	const index = cache.indexBySeq.get(seq);
+	const balanced = index === void 0 ? void 0 : cache.cutBalanced[index + offset];
+	if (balanced === void 0) throw new Error(`tool-pairing balance: surface seq ${seq} not found`);
+	return balanced;
+}
+/**
+* Whether the cut immediately before a current surface sequence is tool-pairing balanced.
+* @param session - session whose surface is checked.
+* @param seq - event sequence whose leading cut is checked.
+* @returns true when no unanswered tool call crosses the cut.
+* @throws when the seq is absent from the current surface, a surface sequence has no
+* matching log event, or a tool result has no preceding open call.
+*/
+function toolPairingBalancedBefore(session, seq) {
+	return cutBalance(balanceCache(session), seq, 0);
+}
+/**
+* Whether the cut immediately after a current surface sequence is tool-pairing balanced.
+* @param session - session whose surface is checked.
+* @param seq - event sequence whose trailing cut is checked.
+* @returns true when no unanswered tool call crosses the cut.
+* @throws when the seq is absent from the current surface, a surface sequence has no
+* matching log event, or a tool result has no preceding open call.
+*/
+function toolPairingBalancedAfter(session, seq) {
+	return cutBalance(balanceCache(session), seq, 1);
+}
+//#endregion
+//#region lib/types/checkpoint.js
+/**
+* Compaction checkpoint provenance: the correlated source constructor and type
+* every backend uses for its replacement user message, plus the predicate that
+* recognizes persisted checkpoints.
+*
+* The seam itself lives in `@hydraharness/harness-compaction`, which re-exports these
+* contracts; this module is a pure type/value/predicate outlet (no cordis
+* imports, no module augmentation) so client and wire programs can name the
+* checkpoint source without loading the host plugin's Context merges — the
+* `hydra-commands/brand` shape.
+*
+* @module @hydraharness/harness-compaction/checkpoint
+*/
+const COMPACT_CHECKPOINT_MARKER = Object.freeze({
+	kind: "plugin",
+	plugin: "compact"
+});
+/**
+* Create checkpoint provenance correlated with one compaction transaction.
+* @param compactionId - owning compaction identity.
+* @param sourceCommandId - initiating manual command, when present.
+* @returns immutable checkpoint source.
+*/
+function compactCheckpointSource(compactionId, sourceCommandId) {
+	return Object.freeze({
+		...COMPACT_CHECKPOINT_MARKER,
+		compactionId,
+		...sourceCommandId === void 0 ? {} : { sourceCommandId }
+	});
+}
+/**
+* Test whether a persisted message source identifies a compaction checkpoint.
+* @param source - source restored from a surface user message.
+* @returns whether the source carries the backend-independent checkpoint marker.
+*/
+function isCompactCheckpointSource(source) {
+	return source.kind === "plugin" && source.plugin === COMPACT_CHECKPOINT_MARKER.plugin;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Compaction Service Definition (`ctx.compaction`): providers decide when to
+* compact and replace a history range with one summary node by subclassing
+* {@link CompactionEngine}. This interface necessarily depends on session and LLM
+* vocabulary; the rationale is in the
+* [compaction Agent Note](../../../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md).
+* @module @hydraharness/harness-compaction
+*/
+/**
+* Expected manual-compaction failure suitable for a direct human-command result.
+* Shared durable-lock entry assertions may also throw the `busy` subtype from
+* automatic compaction paths.
+*/
+var ManualCompactionError = class extends Error {
+	code;
+	name = "ManualCompactionError";
+	/**
+	* Create one classified compaction failure.
+	* @param code - stable failure class; `busy` may originate from any compaction entry path.
+	* @param message - backend diagnostic retained as the Error message.
+	* @param options - optional original failure.
+	*/
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+	}
+};
+/**
+* Abstract compaction service. Implementations own trigger policy, retention,
+* and summarization, and may consume a separate measurement service. A
+* successful run replaces the selected surface span with one summary node and
+* prevents concurrent compaction of the same session. The replacement user
+* message uses {@link compactCheckpointSource} with the transaction identity
+* so consumers recognize and correlate it independently of the backend. Load
+* one implementation per context as `ctx.compaction`.
+*/
+var CompactionEngine = class extends Service {
+	constructor(ctx) {
+		super(ctx, "compaction");
+	}
+};
+//#endregion
+export { CompactionEngine, CompactionEngine as default, CompactionId, ManualCompactionError, compactCheckpointSource, isCompactCheckpointSource, toolPairingBalancedAfter, toolPairingBalancedBefore };

package/lib/invariant.js

@@ -0,0 +1,217 @@
+import { isReplacementSurfaceEvent } from "@hydraharness/harness-session";
+//#region lib/types/checkpoint.js
+/**
+* Compaction checkpoint provenance: the correlated source constructor and type
+* every backend uses for its replacement user message, plus the predicate that
+* recognizes persisted checkpoints.
+*
+* The seam itself lives in `@hydraharness/harness-compaction`, which re-exports these
+* contracts; this module is a pure type/value/predicate outlet (no cordis
+* imports, no module augmentation) so client and wire programs can name the
+* checkpoint source without loading the host plugin's Context merges — the
+* `hydra-commands/brand` shape.
+*
+* @module @hydraharness/harness-compaction/checkpoint
+*/
+const COMPACT_CHECKPOINT_MARKER = Object.freeze({
+	kind: "plugin",
+	plugin: "compact"
+});
+/**
+* Test whether a persisted message source identifies a compaction checkpoint.
+* @param source - source restored from a surface user message.
+* @returns whether the source carries the backend-independent checkpoint marker.
+*/
+function isCompactCheckpointSource(source) {
+	return source.kind === "plugin" && source.plugin === COMPACT_CHECKPOINT_MARKER.plugin;
+}
+//#endregion
+//#region lib/types/invariant.js
+/** Package-owned compaction log-stream invariants. @module @hydraharness/harness-compaction/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-compaction";
+/** Cordis companion plugin name. */
+const name = "compaction-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Require a durable opaque identity to be a non-empty string. */
+function validateId(value, label, fail) {
+	if (typeof value !== "string" || value.length === 0) fail(`${label} must be a non-empty string`);
+}
+/** Keep the optional initiating command identity stable across one transaction. */
+function validateSourceCommandId(eventType, value, expected, fail) {
+	if (value !== void 0) validateId(value, `${eventType} sourceCommandId`, fail);
+	if (value !== expected) fail(`${eventType} sourceCommandId ${String(value)} does not match compaction/start sourceCommandId ${String(expected)}`);
+}
+/** Validate one replacement checkpoint against its open compaction transaction. */
+function validateCheckpoint(trace, event, fail) {
+	const source = event.data.source;
+	validateId(source.compactionId, "compaction checkpoint compactionId", fail);
+	if (source.sourceCommandId !== void 0) validateId(source.sourceCommandId, "compaction checkpoint sourceCommandId", fail);
+	const open = trace.compaction;
+	if (open === void 0) fail("compaction checkpoint has no matching compaction/start");
+	if (source.compactionId !== open.compactionId) fail(`compaction checkpoint id ${source.compactionId} does not match compaction/start id ${open.compactionId}`);
+	validateSourceCommandId("compaction checkpoint", source.sourceCommandId, open.sourceCommandId, fail);
+}
+/** Compaction starts still unmatched when a later seed boundary made them stale. */
+function inheritedOrphanStartSeqs(events) {
+	const stale = /* @__PURE__ */ new Set();
+	let openStartSeq;
+	for (const event of events) if (event.type === "compaction/start") openStartSeq = event.seq;
+	else if (event.type === "compaction/end") openStartSeq = void 0;
+	else if (event.type === "session/end-seed") {
+		if (openStartSeq !== void 0) stale.add(openStartSeq);
+		openStartSeq = void 0;
+	}
+	return stale;
+}
+/** Keep every live compaction bracket on one side of each turn boundary. */
+function validateTurnBoundary(trace, event, fail) {
+	if (event.type !== "turn/start" && event.type !== "turn/end" || trace.compaction === void 0) return;
+	const owner = trace.compaction.turn === null ? "standalone compaction" : `compaction for turn ${trace.compaction.turn}`;
+	fail(`${event.type} cannot cross an open ${owner}`);
+}
+/** Advance the committed turn cursor after its boundary has been accepted. */
+function applyTurnBoundary(trace, event) {
+	if (event.type === "turn/start") {
+		trace.openTurn = event.data.turn;
+		return true;
+	}
+	if (event.type === "turn/end") {
+		trace.openTurn = null;
+		return true;
+	}
+	return false;
+}
+/** Require a numbered bracket inside its exact turn, or a standalone bracket between turns. */
+function validateOwner(owner, openTurn, eventType, fail) {
+	if (owner === null) {
+		if (openTurn !== null) fail(`${eventType} is standalone but turn ${openTurn} is open`);
+		return;
+	}
+	if (openTurn === null) fail(`${eventType} for turn ${owner} appended outside any open turn`);
+	if (owner !== openTurn) fail(`${eventType} names turn ${owner} but open turn is ${openTurn}`);
+}
+/** Validate one compaction event without advancing committed trace state. */
+function validateCompactionEvent(trace, event, fail) {
+	if (event.type === "session/end-seed") return { kind: "end-seed" };
+	if (event.type === "user/message" && isReplacementSurfaceEvent(event) && isCompactCheckpointSource(event.data.source)) {
+		validateCheckpoint(trace, event, fail);
+		return;
+	}
+	if (event.type !== "compaction/start" && event.type !== "compaction/summary" && event.type !== "compaction/end") return;
+	const open = trace.compaction;
+	if (event.type === "compaction/start") {
+		validateId(event.data.compactionId, "compaction/start compactionId", fail);
+		if (event.data.sourceCommandId !== void 0) validateId(event.data.sourceCommandId, "compaction/start sourceCommandId", fail);
+		if (open !== void 0) fail(`compaction/start while ${open.turn === null ? "standalone compaction" : `turn ${open.turn}`} is still compacting`);
+		validateOwner(event.data.turn, trace.openTurn, event.type, fail);
+		return {
+			kind: "start",
+			compactionId: event.data.compactionId,
+			sourceCommandId: event.data.sourceCommandId,
+			startSeq: event.seq,
+			turn: event.data.turn
+		};
+	}
+	if (event.type === "compaction/summary") {
+		validateId(event.data.compactionId, "compaction/summary compactionId", fail);
+		if (event.data.sourceCommandId !== void 0) validateId(event.data.sourceCommandId, "compaction/summary sourceCommandId", fail);
+		if (open === void 0) fail("compaction/summary has no matching compaction/start");
+		if (event.data.compactionId !== open.compactionId) fail(`compaction/summary id ${event.data.compactionId} does not match compaction/start id ${open.compactionId}`);
+		validateSourceCommandId("compaction/summary", event.data.sourceCommandId, open.sourceCommandId, fail);
+		validateOwner(open.turn, trace.openTurn, event.type, fail);
+		if (open.summarized) fail("compaction/summary repeated within one compaction");
+		const seqs = event.data.shadowedSeqs;
+		if (seqs.length === 0) fail("compaction/summary shadowedSeqs must be non-empty");
+		if (seqs[0] !== event.data.shadowedRange.start || seqs.at(-1) !== event.data.shadowedRange.end) fail("compaction/summary shadowedRange must match the first and last shadowedSeqs");
+		if (!Number.isSafeInteger(event.data.shadowedTokenCount) || event.data.shadowedTokenCount < 0) fail("compaction/summary shadowedTokenCount must be a non-negative safe integer");
+		return {
+			kind: "summary",
+			compactionId: open.compactionId,
+			sourceCommandId: open.sourceCommandId,
+			startSeq: open.startSeq,
+			turn: open.turn
+		};
+	}
+	validateId(event.data.compactionId, "compaction/end compactionId", fail);
+	if (event.data.sourceCommandId !== void 0) validateId(event.data.sourceCommandId, "compaction/end sourceCommandId", fail);
+	if (open === void 0) fail("compaction/end has no matching compaction/start");
+	if (event.data.compactionId !== open.compactionId) fail(`compaction/end id ${event.data.compactionId} does not match compaction/start id ${open.compactionId}`);
+	validateSourceCommandId("compaction/end", event.data.sourceCommandId, open.sourceCommandId, fail);
+	if (event.data.turn !== open.turn) fail(`compaction/end owner ${String(event.data.turn)} does not match compaction/start owner ${String(open.turn)}`);
+	validateOwner(open.turn, trace.openTurn, event.type, fail);
+	if (event.data.error === void 0 && !open.summarized) fail("successful compaction/end requires one compaction/summary");
+	return { kind: "end" };
+}
+/** Apply one committed compaction transition. */
+function applyCompactionTransition(transition) {
+	if (transition.kind === "start") return {
+		compactionId: transition.compactionId,
+		sourceCommandId: transition.sourceCommandId,
+		startSeq: transition.startSeq,
+		turn: transition.turn,
+		summarized: false
+	};
+	if (transition.kind === "summary") return {
+		compactionId: transition.compactionId,
+		sourceCommandId: transition.sourceCommandId,
+		startSeq: transition.startSeq,
+		turn: transition.turn,
+		summarized: true
+	};
+}
+/** Install compaction start/summary/end checks. */
+const install = Object.assign((ctx, fail) => {
+	const traces = /* @__PURE__ */ new WeakMap();
+	const staged = /* @__PURE__ */ new WeakMap();
+	const seed = (session) => {
+		const trace = {
+			openTurn: null,
+			compaction: void 0
+		};
+		traces.set(session, trace);
+		const staleOrphanStartSeqs = inheritedOrphanStartSeqs(session.events);
+		for (const event of session.events) {
+			if (trace.compaction === void 0 || !staleOrphanStartSeqs.has(trace.compaction.startSeq)) validateTurnBoundary(trace, event, fail);
+			const transition = validateCompactionEvent(trace, event, fail);
+			if (transition !== void 0) trace.compaction = applyCompactionTransition(transition);
+			applyTurnBoundary(trace, event);
+		}
+		return trace;
+	};
+	const traceFor = (session) => traces.get(session) ?? seed(session);
+	for (const session of ctx.sessions.list()) seed(session);
+	ctx.on("session/created", (session) => {
+		seed(session);
+	}, { global: true });
+	ctx.on("session/event", (session, event) => {
+		const trace = traceFor(session);
+		validateTurnBoundary(trace, event, fail);
+		if (applyTurnBoundary(trace, event)) return;
+		if (event.type !== "session/end-seed" && event.type !== "compaction/start" && event.type !== "compaction/summary" && event.type !== "compaction/end") return;
+		const candidate = staged.get(event);
+		/* v8 ignore next -- internal/dispatch stages every compaction event */
+		if (candidate === void 0 || candidate.session !== session) return fail("compaction event published without pre-commit validation");
+		staged.delete(event);
+		trace.compaction = applyCompactionTransition(candidate.transition);
+	}, { global: true });
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [session, event] = args;
+		const trace = traceFor(session);
+		validateTurnBoundary(trace, event, fail);
+		const transition = validateCompactionEvent(trace, event, fail);
+		if (transition !== void 0) staged.set(event, {
+			session,
+			transition
+		});
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register the compact invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/brand.d.ts

@@ -0,0 +1,10 @@
+import type { Branded } from '@hydraharness/harness-brand';
+/** Stable identity shared by one compact start/summary/checkpoint/end transaction. */
+export type CompactionId = Branded<'CompactionId'>;
+/**
+ * Brand an implementation-minted compaction identity.
+ * @param id - opaque transaction identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export declare function CompactionId(id: string): CompactionId;
+//# sourceMappingURL=brand.d.ts.map

package/lib/types/brand.js

@@ -0,0 +1,9 @@
+/**
+ * Brand an implementation-minted compaction identity.
+ * @param id - opaque transaction identity.
+ * @returns the same string, branded; no validation is performed.
+ */
+export function CompactionId(id) {
+    return id;
+}
+//# sourceMappingURL=brand.js.map

package/lib/types/checkpoint.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Compaction checkpoint provenance: the correlated source constructor and type
+ * every backend uses for its replacement user message, plus the predicate that
+ * recognizes persisted checkpoints.
+ *
+ * The seam itself lives in `@hydraharness/harness-compaction`, which re-exports these
+ * contracts; this module is a pure type/value/predicate outlet (no cordis
+ * imports, no module augmentation) so client and wire programs can name the
+ * checkpoint source without loading the host plugin's Context merges — the
+ * `hydra-commands/brand` shape.
+ *
+ * @module @hydraharness/harness-compaction/checkpoint
+ */
+import type { MessageSource } from '@hydraharness/harness-llm/message';
+import type { CommandId } from '@hydraharness/harness-commands/brand';
+import type { CompactionId } from './brand.ts';
+declare const COMPACT_CHECKPOINT_MARKER: Readonly<{
+    readonly kind: "plugin";
+    readonly plugin: "compact";
+}>;
+/** Message provenance carried by a concrete compaction checkpoint. */
+export type CompactionCheckpointSource = typeof COMPACT_CHECKPOINT_MARKER & {
+    readonly compactionId: CompactionId;
+    readonly sourceCommandId?: CommandId;
+};
+/**
+ * Create checkpoint provenance correlated with one compaction transaction.
+ * @param compactionId - owning compaction identity.
+ * @param sourceCommandId - initiating manual command, when present.
+ * @returns immutable checkpoint source.
+ */
+export declare function compactCheckpointSource(compactionId: CompactionId, sourceCommandId?: CommandId): CompactionCheckpointSource;
+/**
+ * Test whether a persisted message source identifies a compaction checkpoint.
+ * @param source - source restored from a surface user message.
+ * @returns whether the source carries the backend-independent checkpoint marker.
+ */
+export declare function isCompactCheckpointSource(source: MessageSource): boolean;
+export {};
+//# sourceMappingURL=checkpoint.d.ts.map

package/lib/types/checkpoint.js

@@ -0,0 +1,36 @@
+/**
+ * Compaction checkpoint provenance: the correlated source constructor and type
+ * every backend uses for its replacement user message, plus the predicate that
+ * recognizes persisted checkpoints.
+ *
+ * The seam itself lives in `@hydraharness/harness-compaction`, which re-exports these
+ * contracts; this module is a pure type/value/predicate outlet (no cordis
+ * imports, no module augmentation) so client and wire programs can name the
+ * checkpoint source without loading the host plugin's Context merges — the
+ * `hydra-commands/brand` shape.
+ *
+ * @module @hydraharness/harness-compaction/checkpoint
+ */
+const COMPACT_CHECKPOINT_MARKER = Object.freeze({ kind: 'plugin', plugin: 'compact' });
+/**
+ * Create checkpoint provenance correlated with one compaction transaction.
+ * @param compactionId - owning compaction identity.
+ * @param sourceCommandId - initiating manual command, when present.
+ * @returns immutable checkpoint source.
+ */
+export function compactCheckpointSource(compactionId, sourceCommandId) {
+    return Object.freeze({
+        ...COMPACT_CHECKPOINT_MARKER,
+        compactionId,
+        ...sourceCommandId === undefined ? {} : { sourceCommandId },
+    });
+}
+/**
+ * Test whether a persisted message source identifies a compaction checkpoint.
+ * @param source - source restored from a surface user message.
+ * @returns whether the source carries the backend-independent checkpoint marker.
+ */
+export function isCompactCheckpointSource(source) {
+    return source.kind === 'plugin' && source.plugin === COMPACT_CHECKPOINT_MARKER.plugin;
+}
+//# sourceMappingURL=checkpoint.js.map