docs(durable): rename collapse to compaction

This commit is contained in:
Mario Zechner 2026-09-29 21:38:50 +02:00
parent e5960c483f
commit c4f5ef9451
3 changed files with 16 additions and 16 deletions

View file

@ -591,22 +591,22 @@ current committed tail, empty source conversations, document fork policies,
configuration overrides through `init`, foreground subagent cascade, and
background supervisor recovery before and after submission admission.
## 19. Collapse and overflow
## 19. Compaction and overflow
Implement manual, threshold, and generation-overflow collapse; exchange-boundary
Implement manual, threshold, and generation-overflow compaction; exchange-boundary
range selection; summarization; retry policy; staleness checks; and headed
summary entries. Wire generation's real overflow path directly to the collapse
task, and complete `Conversation.collapse()` so it returns the admitted task ID.
summary entries. Wire generation's real overflow path directly to the compaction
task, and complete `Conversation.compact()` so it returns the admitted task ID.
Generation preparation no longer rechecks the transcript before appending its
system entries (§7.4, §12): only run tasks and turn boundaries write to a busy
conversation. A collapse summary for a busy conversation must therefore be
conversation. A compaction summary for a busy conversation must therefore be
placed at a turn boundary or as a step of the run, never appended concurrently.
Test model context before and after collapse, raw history preservation, provider
Test model context before and after compaction, raw history preservation, provider
failure, declined and stale work, manual/threshold/overflow admission, late-join
presentation state, and reopen from every phase. Rerun generation overflow
integration without a fake collapse kind.
integration without a fake compaction kind.
## 20. Reload and final conformance
@ -624,7 +624,7 @@ acquisition and an already-running callback that remains caller-owned across
shutdown. Verify service withdrawal and client detach.
Run the exhaustive public conformance matrix: stable persisted root identity;
all root/create/lookup/fork/reset/collapse/abort/idle paths; every configuration
all root/create/lookup/fork/reset/compact/abort/idle paths; every configuration
getter/setter and fork override; typed input/write submissions; task wait/abort;
generic document access; registry changes before open, between open and resume,
and while work runs; structural watches; and blocked tasks surviving open. Compile-test every §2.2 and §3 owner/key/seed overload,

View file

@ -490,7 +490,7 @@ interface Conversation {
options: ConversationCreateOptions,
context: Context,
): Promise<Conversation>;
collapse(instructions: string | undefined, context: Context): Promise<TaskId>;
compact(instructions: string | undefined, context: Context): Promise<TaskId>;
reset(handoff: string | undefined, context: Context): Promise<void>;
abort(context: Context): Promise<void>;
waitForIdle(context: Context): Promise<void>;
@ -677,7 +677,7 @@ because `Harness extends Session`.
`fork()` requires a concrete visible parent entry and explicit ownership, then
applies section 3.7.
`collapse()` returns the newly admitted background collapse task ID, not its
`compact()` returns the newly admitted background compaction task ID, not its
future summary entry. `reset()` durably admits a write submission of a
`pi.reset` entry (section 8.1) with `head: "self"`, carrying the handoff text as
a user message when given, and then resolves; while busy, placement follows
@ -1859,7 +1859,7 @@ selects the first item of that mode, `all` every item of that mode.
| `final` | all | first/all by mode | first/all by mode |
A boundary places its selected writes first, in ID order, and then its selected
user items, in ID order. A user item queued before a reset or collapse summary
user items, in ID order. A user item queued before a reset or compaction summary
therefore lands after it and runs in the new context. Queued user items never
become stale because of a head.
@ -2114,7 +2114,7 @@ errors always propagate.
| `beforeTool` | argument replacement chain; first block wins | block tool with error text |
| `afterTool` | result replacement chain | report, continue |
| `afterTools` | all observers | report, continue |
| `beforeCollapse` | first decision wins | report, continue |
| `beforeCompact` | first decision wins | report, continue |
Hooks use task memos for durable first-writer-wins decisions. There is no public
semantic event channel; current UI status is document state.
@ -2649,7 +2649,7 @@ The initial implementation provides:
| `pi.generation` | prepare system/loadout, request or poll model, retry, classify response |
| `pi.tool` | validate, hook, execute, persist output and details, append result |
| `pi.post-tools` | wait for tools, apply controls, run boundary, continue generation |
| `pi.collapse` | select a transcript range, summarize, append a headed summary |
| `pi.compaction` | select a transcript range, summarize, append a headed summary |
Generation uses `HarnessOptions.models` without a Pico-specific model adapter. It
resolves `models.getModel(ref.provider, ref.modelId)`, builds a pi-ai `Context`
@ -2758,7 +2758,7 @@ Post-tools removes `tools`. Slot updates apply only while a slot with the task's
`taskId` exists; without one, the durable partial output, details, and
diagnostics are empty.
Compaction status joins this document with the collapse task. Partials are
Compaction status joins this document with the compaction task. Partials are
normalized to strict JSON before assignment. Every terminal path of a run task
removes `run`, `generation`, and `tools` in the commit that settles the run's
inputs. `tx.settleSubmission()` stages each input's new status
@ -3288,7 +3288,7 @@ Events derive from committed changes:
- `auto_retry_start`/`auto_retry_end`, `deferred_poll`: `pi.live.generation`
gains or drops `retry`, or gains `deferred` or moves its `pollAt`.
- `task_failed`: a task of the conversation settles `faulted` or `orphaned`.
- `compaction_start`/`compaction_end` are added with collapse (Package 19).
- `compaction_start`/`compaction_end` are added with compaction (Package 19).
One commit produces one batch, in this order: `tool_execution_start`,
`message_start` of a first partial, `message_update`, `tool_execution_update`,

View file

@ -53,7 +53,7 @@ describe("conversation context", () => {
expect(ids(view.entries)).toEqual([reset.id, after.id]);
expect(view.messages.map(describeMessage)).toEqual(["user:fresh start", "assistant:after reset"]);
// A collapse summary heads an earlier kept entry; older head markers in range drop out.
// A compaction summary heads an earlier kept entry; older head markers in range drop out.
const summary = await append({ kind: "summary", head: after.id, model: [user("summary")] });
const tail = await message(user("next"));
view = await root.context(context);