[nissa-seru]

What this adds

membrane's system_change block (SystemChangeContent, antra-tess/membrane#183, released in membrane 0.7.0) lets a caller change the tools the model is offered, and its system text, from a place in the conversation on, without editing tools or system, which come first in the cached prefix. A message holding only such blocks is sent as a mid-conversation system message. This makes context-manager carry one: priced, alone in its message, compiled unaltered in its place among the raw messages under every strategy, never dropped, and kept out of compression. It also adds CompileResult.firstChanged, so a caller can tell when a compile rewrote what the last one gave.

@antra-tess, @Anarchid: a review from either of you is welcome, including after it merges. It changes what every strategy sends once a store holds a change, and a wrong detail there can change what the model sees in ways our own review may not catch. We'd most value it on two parts: system changes kept raw through compression and pins, and the refusal of a write that puts a change after an unanswered tool_use.

What each part is for, and what was left out

• Kept in place. A change applies to everything after it, so leaving one out of a compile, or folding it into a summary, would take it out of the rest of the conversation. A summary can't carry a tool definition.
  • The autobiographical strategy (and KnowledgeStrategy, which extends it) keeps a message of changes raw, as a pin keeps a message, at resolvedPinBounds. That one site is what the chunker, the adaptive picker and its solvers, and the hierarchical emission read, so no fold takes it and no chunk holds it. A level pin over one doesn't change that. Under positionedRecallPairs: false, the middle's summaries go ahead of its raw messages, as they always have, so there a change keeps its place among raw messages only.
  • After a head-window reset (resetHeadWindow), every path sends the new head first and the history before it later, so a change left in that history would follow the head's own changes and apply after them: a removal could run before the definition it removes. So the changes stored before the head are part of the head, ahead of the head window, in order (headPositions). The adaptive path adds them to its head set and head tokens, so kv-unified's solved layout puts them in the head unit and its cache check rebuilds the same head, and the markers reconcile against what's sent. The hierarchical path's first phase sends the same head. The history before the head, which the reset already sends after the head, then reads those changes too. The provider takes that: it doesn't check a past tool call against the tools offered where the call sits (live runs on Claude Haiku 5.5 and Claude Opus 5.5, all 200). With nothing in the head window, nothing goes ahead of that history, and the changes stay in place.
  • The middle's ranges come from one function (middleRanges), which the adaptive path and the cache check share. With the head window disabled, headEnd is 0 under a positive headStart, so on main the ranges overlapped each other, and the recent window when it starts before the reset: an adaptive compile sent the history before the reset twice, and kv-unified threw CanonicalForestError (duplicate-chunk-id), by run on main. The live head window now ends at the later of the two.
  • KnowledgeStrategy's chunker closes a chunk where a system change sits between two of its compressible messages. Without that a chunk spanned a change and summarized the history on both sides as one, rendered ahead of the change. It finds them with one cursor over the changes' positions, since its walk is in store order. It also closes a chunk where the L1 summary covering its messages changes, so a chunk holds one summary's messages or none. Its chunks are rebuilt afresh at each compile, so once a consolidation removed a change that had closed a chunk, the chunk ran across a summary's span, the overlap guard refused to compress the chunk after it for good, and its messages went out raw beside the summary that covers some of them. It doesn't close there between a call and its result, as its size and phase closes don't: pairing repair would drop the result, its call folded into the summary, so the result joins the summary's chunk, which the overlap guard refuses, as on main. Its close at a change needs no such exception, since a change never sits between a call and its result where the write refusal sees them (below). A store without changes whose chunks already match its summaries chunks as on main.
  • PassthroughStrategy and WindowedPassthroughStrategy keep the changes that fall before their window. They go ahead of the window in their order, and their tokens are counted first. Windowed's re-anchor target is the changes plus reAnchorFraction of the room they leave, and appends get the rest of that room before the next re-anchor.
  • None is ever dropped. When the changes alone exceed the budget (beyond the autobiographical strategy's grace, and on its hierarchical path only where enforceBudget is on), every strategy refuses with OverBudgetError, clearedBy empty, since no newer message or compression shrinks them: only the caller consolidating them clears it. The hierarchical path checks before it sends anything. The adaptive plan refusal names compression only while the head, the tail and the changes between them fit, since compression shrinks none of them. Its head/tail refusal counts every change outside the head in what a smaller recent window would still have to send, and it takes the newest conversation message past any changes after it as the turn that window keeps. A dry compile reports where the strategy's other refusals do. While the changes fit, a loss elsewhere is refused as that strategy refuses any: the hierarchical path's recent window refuses an eviction with UncoveredDropError.
  • A conversation message beside them. Windowed's refusal of a newest message over the budget, main's, counts the changes in: OverBudgetError, with the changes as headTokens and the newest conversation message as tailTokens, and clearedBy: ['newer-message'] while the changes leave room for a message. Its progress fallback anchors at the newest message that isn't a change, so changes that fill the target don't push the newest turn out. PassthroughStrategy refuses the same way when the newest conversation message doesn't fit beside them; without changes it sends nothing then, as on main. Sending the changes alone would leave membrane to refuse the request, and which layer refuses decides a caller's recovery: an OverBudgetError lets a caller consolidate its changes into tools and system and compile again, which a request refused for its change doesn't say. Where a change can go in a request (after a user turn) is membrane's to say, since context-manager can't tell a user participant from another, and membrane refuses a request holding a change it can't place.
  • The structural repair's check takes the newest message that isn't a change as the newest turn, as the head/tail floor does. A change after the newest turn is always sent raw, so reading the last stored message as the newest turn, as main does, the check read the change and passed while a repair dropped the turn itself: after a reset at a trailing change, the change goes in the head and the turns before it come after it, where trimming an unanswered call takes the last compiled message.
  • The coverage check names an unrendered change before the head's start as the head's while the head window holds messages, which is where a reset puts it, and as history before the head's start otherwise, as for any message there. Without it, a change lost from the head would read as lost middle history.
  • A head-window reset's transition summary reads only each head message's text, as on main, so it never read a change. It now leaves out a message of changes alone, which gave its request an entry of a participant's name with nothing after it.
  • Windowed's anchor moves only for a compile that sends. On main a refused compile kept its jump to the newest message, so a retry with a larger budget, or one after consolidating, no longer sent the older turns that fit.
• Kept out of compression. Every site where a raw message enters a summarizer request, and the pricing of that request, goes through one function, which strips thinking as before and now leaves system changes out. The one exception, a head-window reset's transition summary, reads only each head message's text, as on main, so it never read a change, and it now leaves out a message of changes alone rather than send its participant's name with nothing after it. A summarizer's request would otherwise apply the change to the summarizer, or be refused on a model without mid-conversation system messages. A message of changes alone is left empty, and merging consecutive messages for the request now passes over any empty message, one of thinking alone included, so no empty turn or separator marks where it sat and its neighbours join as they would without it.
• Priced from its JSON, in MessageStore and ContextLog, as a tool call's input is. An unknown block was priced at 0, and a change's definitions and text do go to the model.
• Alone in its message, and well formed. A write refuses a system change beside other blocks or inside a tool result, and one whose removeTools or addSystem isn't an array of strings, or whose defineTools isn't an array of tool definitions, each with a non-empty string name, a string description and an object inputSchema whose type is 'object', as membrane's ToolDefinition has them. The API refuses a definition whose schema has no type, or another, with a 400, in a system change and in tools alike (live runs on Claude Haiku 5.5). It names the wrong element or field by its place. membrane refuses a mixed message when it sends, and sends each definition to the provider with every later request, so a stored one that's wrong would be refused on every request; refusing it at the write keeps a store from being stuck. A read leaves out a change in any of those places, and logs where, as it does other blocks that don't match, so a store damaged some other way sends its conversation instead. The checks that a change stands alone are index loops, so a hole beside a change counts as another entry, as every walk there counts one.
• Not between a tool call and its result. A write is refused when it would put a system change between a call and a result that answers it: a message of changes while one of the nearest calls before it has no result between it and the change; a message holding a tool_result that answers a call a change already follows; or an edit giving a message a tool_use that a change follows before its results. MessageStore.append and edit check it, and ContextManager.addMessage checks first, so a refused add releases no expired hold, as its other refusals don't. By its own error, the API takes a system message with content only after a user turn or an assistant turn ending in a server tool result (a live run on Claude Haiku 5.5 refused one after an assistant turn), and membrane 0.7.0's NativeFormatter sends a change stored after a call after the turn holding the call's result (by run), as it sends one written after the result. Stored between them, a change parted them: the base chunker and KnowledgeStrategy close a chunk at a change, which stays raw, so the call and its result were folded into different summaries, and once the call's chunk was summarized a compile's pairing repair dropped the result (by run, below). Refusing the write tells the caller when it can still write the change where it goes out. The check reads back from the write over changes, and over messages holding results but no call, to the nearest message holding a call, reading each message whole, every shard of it, since ingress sharding puts a message's calls and results on its first shard. It checks that message's calls by id: a result in a later message answers one, as parallel calls' results in messages of their own do, and so does a later block of the same message, as in a bundled cycle, which compiles split (splitMixedToolMessages). It stops at a message of any other kind, so a call that a crash left unanswered, further back, refuses nothing, and the refusal says to store a result for a call that will get none, or remove the call. What a write can't see is left as on main, where each parts the pair once the call is folded: a message of another kind between a call and its result, already off the shape the API takes; a call in an earlier message than the nearest one holding a call; a shape that exists only in a view, filtered or merged from several stores; and a removal or an edit that takes away a result or a message between. By our reading, agent-framework stores a call together with its results, so it writes none of these.
• renderAsNewest for a change before windowed's anchor gives the change as select sends it, ahead of the window and cut as any message is, where it gave null. A compile moves the anchor only to a message it sent, but setAnchor can move it past one just stored.
• systemChangePositions walks a listing for the messages holding a change, as pinnedPositions walks it for pins. A select reads it several times, so it walks each listing once and keeps the answer in a WeakMap on the store's array, which callers never change and a write replaces, as the filtered and merged views' listings are kept. It found them again at every call before. In CPU profiles of 200 hierarchical compiles on a 2,000-message store without changes, resolvedPinBounds, where the walk ran, took 0.140 ms of its own time per compile at a15cdf7c, against 0.339 ms when it walked the listing at every call, in separate runs on a machine under load.
• CompileResult.firstChanged. On a committing compile it gives the index of the first message, injections included, whose participant or content bytes differ from the last committing compile's message at that index, or that has none there. After appends alone it's the first appended index, though an injection placed beside the newest user message moves with each new user message, so after one it's that injection's old index. It compares bytes, so it holds across a branch switch, a switch made on the store directly, or a new strategy, which the manager can't always see, and it's null only for the manager's first committing compile. Dry compiles leave it out and don't move it. It's measured in ContextManager.compile after injections, so it means the same for every strategy, and last, so a compile that throws before returning is never the one the next is compared with. It's compared when read: a committing compile records its messages by reference, and the comparison runs only when a caller reads the field, so a caller that never reads it serializes nothing but its injections. It keeps no copy of the store's content: arrays the store or the strategy made are compared by identity first, since nothing changes them in place, so a block a caller changed in place after storing it, which the store's contract rules out, isn't seen. An injection's content is serialized at each committing compile and its bytes kept for the next, since a caller may change its own array, or a block in it, in place. An injection is told by its source in the compile's provenance, not by its array, because a compile with thinkingBinding sends one that holds thinking as a new array of the caller's blocks. Anything else is serialized only when the field is read, and only where identities differ before the first difference. Its first read, or an assignment, settles the value and lets go of both compiles' keys, so a read result holds the number and an unread one keeps this compile's keys and the last one's. It stays an accessor, so a frozen or sealed result reads it too. A read after later compiles still compares its compile with the one before it. On the autobiographical strategy with every message capped, so each compile makes new arrays, 2,030 compiled messages: comparing at every compile took 3.18 ms of a 28.9 ms compile and kept 536,000 characters of bytes between compiles. Now a compile records its keys in 0.27 ms and, while the field goes unread, keeps no bytes. A read takes 2.50 ms, and a caller that reads it at every compile keeps the 536,000 characters, as before.
• A test fixture in l1-recall-raw-pins-frontier.test.ts gave its messages content: []. A StoredMessage has content by type, and the positions walk reads it.
• Left out:
  • Consolidating changes. Folding several changes into tools and system belongs to the caller, which knows its baseline. It can remove the messages and compile again; firstChanged tells it when a compile rewrote them.
  • A pricing epoch. No store written before this holds a system change, since membrane had no such block, so no stored price changes.
  • Ingress sharding needs nothing. A message of changes holds no text block, so it's never split, and a test pins that.
  • Cache markers and systemInjections don't count toward firstChanged. Markers are message flags, not content, and the caller adds system injections to the system prompt itself.
  • An edit into a change. A change is added as a message of its own. As editMessage says, an edit doesn't reach a summary that already covers the message.
  • main's defects our review found, each left for a fix of its own:
    • an adaptive dry compile labels a plan that can't fit as estimator drift (Adaptive dry compile labels a plan that can't fit as estimator drift #300);
    • the reset head's start index is remembered by message count, so a removal and an append between compiles leave it stale (A reset head's start index goes stale after a removal and an append between compiles #299);
    • under positionedRecallPairs: false, the combined recall pair went out with no grace check, which fix: refuse at the combined recall pair past the grace window #306 has since fixed on main, and this head carries it;
    • selectHierarchical has no guard for the newest turn, so a structural repair that trims an unanswered newest call sends the compile without it, where the adaptive path refuses (The hierarchical path sends a compile without its newest turn when that turn is an unanswered tool call #301);
    • PassthroughStrategy sends nothing when the newest message alone is over the budget, where windowed refuses; this keeps that for stores without changes, and a test pins it (PassthroughStrategy sends an empty context when the newest message alone is over the budget #302);
    • KnowledgeStrategy compresses a trailing chunk that ends at an unanswered call, so the chunk that then holds the call and its result is refused and both go out raw beside the summary; this keeps that, and a test pins it (KnowledgeStrategy compresses a chunk that ends at an unanswered tool call, so its result later goes out raw beside the summary #303).
  • Keeping a parted call and result raw instead. It would cover the shapes a write can't see, but a call and a result kept raw apart from each other reach pairing repair's look-ahead, the adaptive path's shard emitter, head resets and the head boundary, each of which, by our reading, can still part or drop them, for a shape no writer we know of makes.
  • A message of system changes before the head, in the summarizer's prompt: by our reading, the compression request's layout counts it among the messages pins keep raw, though no pin holds it. That adds about nothing to that count's tokens, since the request's pricing leaves system changes out, and its entry is empty and passed over. So what remains is the pinned-raw warning's count of messages, which can include it. No run has shown this.

What callers notice

• Nothing changes for a store or a request without a system_change block, apart from four fixes that reach any caller:
  • a KnowledgeStrategy chunk no longer runs into or across an L1 summary's span once a removal moves where the walk would close, which left the chunk after it uncompressed for good and its messages sent raw beside the summary;
  • a summarizer request no longer carries an empty turn, or a separator with nothing after it, where a message emptied for it sat, as one of thinking alone did on main;
  • with the head window disabled, a compile after resetHeadWindow no longer sends the history before the reset twice under adaptiveResolution, or throws CanonicalForestError under kv-unified;
  • a refused WindowedPassthroughStrategy compile no longer moves the window's anchor.
• firstChanged is a new optional field. It's compared when read, so a caller pays for the comparison only where it reads it.
• A system change between a tool call and its result is refused at the write, by addMessage, editMessage and MessageStore.append and edit, with an Error naming the message that holds the call, and for a change the calls with no result between them and it. Write the change after the result, where membrane sends it anyway, and for a call that will get no result, store one for it first or remove the call.
• renderAsNewest under WindowedPassthroughStrategy gives a change before the anchor as it's sent.
• PassthroughStrategy over budget still drops the oldest messages, but now sends any system change among them, ahead of the rest, and counts it first. So a budget that held N messages may now hold fewer. When the changes alone don't fit, a committing compile refuses with OverBudgetError, and a preview sends the changes alone. When the newest conversation message doesn't fit beside them, a committing compile refuses with OverBudgetError too, naming newer-message while the changes leave room for one, as windowed's does; a newer conversation message that fits clears it. Without changes it sends nothing then, as on main. A dry compile throws neither refusal, as windowed's on main throws none, and the passthrough strategies have no previewContext report.
• WindowedPassthroughStrategy's refusal names the changes when they're part of it, with their tokens as headTokens, and gives clearedBy: ['newer-message'] only while they leave room for a message.
• Only membrane's NativeFormatter, on an adapter that sends system changes, sends one. Elsewhere membrane refuses the request before sending, marked systemChangeRefused unless the formatter couldn't carry the request's tools at all, so a deployment that fails over to another provider or formatter can't send a store holding a change until its changes are consolidated.
• Rolling back to a release without system changes isn't supported once a store holds one. That release prices one at 0 and can fold it into a summary.

Tests

This head merges main at f3878966 (#268, the image ceilings). Its one conflict was in the import block of src/strategies/windowed-passthrough.ts, where each side added imports, and it keeps both. The windowed select keeps both changes too: the system-change entries before the window that this pull request keeps raw, and the ceiling report after image stripping. Before that, this pull request merged main at 4fbe6c94 (#331, the thinking binding). That merge had one conflict, in src/context-manager.ts, where both sides added code to the end of a committing compile and a private method in the same place, and it keeps both. Merging it needed one change beyond the conflict, to how firstChanged tells an injection, which its bullet above describes; a new test in test/system-changes.test.ts fails without it. Earlier, it merged main at c8119361 (#330). There, under adaptive resolution, every reader of a pin reads it as covering whole messages, and the adaptive plan's over-budget refusal names the pins keeping raw tokens in its middle. That merge had two conflicts. In resolvedPinBounds, it still keeps every system-change position raw after the pins, now through main's readers, which no longer take a reading. In test/l1-recall-raw-pins-frontier.test.ts, it keeps main's describe name and this pull request's empty message content. A second commit, 58a6884f, fixes how the two changes meet. The refusal's count of what pins keep raw included the messages of system changes, which stay raw with or without the pins, so unpinning frees none of them. In a test store, the refusal for a 6,000-word mark reported 23,648 tokens, against the mark's own 18,241. It now counts only what a pin keeps raw, and a new test in test/whole-body-pins.test.ts fails without the fix. It also checks that a range pin over the mark's message and the change beside it is named with the mark's tokens alone. The figures below name the head they were taken at, and a15cdf7c is the head before this pull request first merged main.

• test/system-changes.test.ts, 62 tests from 54 blocks, four of them loops (4, 3, 3, 2), and one in test/kv-unified-render-state.test.ts, that the changes before a reset head lead it and kv-unified's cache check rebuilds them there, keeping every accepted marker. They cover:

  • pricing in both estimators, at the estimator's price;
  • the write refusals by place, each field, element and definition field on its own, a schema without type 'object' and a hole beside a change included, and the read's leave-out with its log line, a damaged tool result holding one included;
  • the refusal between a tool call and its result: through the manager before an expired hold is released, and through the store; parallel calls answered in messages of their own; a call on a sharded body's first shard; a sharded results message read whole, walking back from a change and forward from an edited call; a change after a bundled cycle, an edit giving one to a message right before a change, a bundled message's call that none of its later blocks answers left open, and a plain message and the store's end ending the forward walk; a call further back than a message of another kind refusing nothing; a tool result answering a call that a change follows, as a removal leaves them, and another change there, with a result answering no call taken; edits from either side, through the manager and the store; and a change taken after the result;
  • no fold or chunk taking a change, the exact order of everything compiled around it, and no summarizer request carrying it, with a change in the head window too (hierarchical and adaptive);
  • the head-window reset under the hierarchical, adaptive and kv-unified paths, with a definition and its removal before the head, a change inside the head window, the tools left after them, the head's render stats after a compile, and the adaptive paths' head price in their refusal; and the head window disabled under a reset, with a change before it staying in place;
  • KnowledgeStrategy's chunks around a change, with changes first, side by side, beside a pinned message and last, rebuilt across the place of a removed change, keeping each compressed chunk's span when the change between two of them is removed, a summary ending at an unanswered call keeping the call and its result in one chunk and sending both raw, and closing when a plain message follows the call instead, a chunk closing at a summary whose last message is pinned and before a summary from a message unpinned after it compressed, and across a pin in a store without one; a level pin over a change; merging around an emptied message, first, between and alone;
  • the structural repair's check after a reset at a trailing change; the coverage check's labels for a change before the head's start, with the head window holding messages, empty and disabled; a transition summary's request with a message of changes alone in the head;
  • both passthrough strategies' exact windows, windowed's window against the room the changes leave, its budget across appends and its fallback, and renderAsNewest giving a change before windowed's anchor as select sends it;
  • the refusals: every strategy's for changes alone, the hierarchical recent window's eviction, the adaptive plan's naming compression only while the head, the tail and the changes between them fit, a change in the recent window counted once, the adaptive head/tail floor past a change after the newest message, both passthrough strategies' when the newest conversation message doesn't fit beside the changes, with its budget, actual and token split under a response reserve and a newer message that fits clearing it, passthrough sending nothing without changes as on main, a response reserve larger than the budget included, a store of changes alone refused as that by both passthrough strategies and sent when it exactly fills the budget, a change after the newest message included, a change a reset left in the head counted once in the adaptive plan's gate, and windowed's anchor after a refusal, with and without a change;
  • KnowledgeStrategy's chunks after a change holding several messages;
  • a listing's changes found once, and a new listing's afresh;
  • firstChanged compared when read, nothing serialized again on a second read or on a read of the same arrays, a first read after later compiles comparing its own compile with the one before, a copy and JSON carrying it, a frozen result reading it, an assignment taken, and a system injection left out; not compared with a compile that threw before returning, and across appends, injections, the same bytes in a new array, dry compiles, participants, edits, removals, an injection changed in place, an injection a binding compile sends without its thinking, with one of its blocks changed in place, markers, forks, branch switches, a switch made on the store, a switch between two branches of the same length that differ inside, and a new strategy.

• Red-first: against main at 48bb87a1, with the two test files as they stood at a15cdf7c, membrane 0.7.0 and a stub for the helper the tests import (systemChangePositions, returning nothing), 52 of the 63 tests fail, and the build's only errors are the tests reading firstChanged. The 11 that pass pin what main already does and this keeps: the hierarchical path with the head window disabled after a reset, KnowledgeStrategy keeping a call and its result together at an unanswered call, KnowledgeStrategy without changes chunking across a pin, a large change never sharded, a change after a call further back than a message of another kind taken, a change after a bundled cycle and the edits around it taken, the hierarchical eviction refusal, three of the adaptive plan's counts, and passthrough without changes sending nothing. Against this pull request's previous head, bbca9e33, 10 tests fail: seven of the refusal's, a listing's changes found once, renderAsNewest before the anchor, and firstChanged compared when read. The other tests this head adds pass there, since they pin what bbca9e33 already did: a change after a call further back taken, a change after a bundled cycle and the edits around it taken, a read of the same arrays serializing nothing, and a copy, JSON, a frozen result and an assignment carrying the value.

• What a change between a call and its result did, by run at bbca9e33: under the hierarchical path with small chunks and a stand-in summarizer, the call's chunk ended at the call and the result started the next. Once the call's chunk was summarized, at the 17th message's compile, none of that compile and the 22 after it sent the call or the result raw, and no summarizer request carried the result's text.

• Longer runs, against membrane 0.7.0, at the previous head bbca9e33 and again at a15cdf7c's code:

  • Ten kv-unified cases of 180 turns under connectome-host's block: resets with changes before, inside and after the head, the head window disabled or smaller than the transition, changes stored last before a compile, generated transitions, and render stats read before a first compile. In each case, 180 of the 181 compiles were checked against an accepted reference with markers, and the cache check rebuilt all 180. Nothing threw, no check of the harness's fired, no self-check or kv-unified warning was logged, every change was in every compile in stored order, and render stats read before a first compile matched the compile's. The same harness on main sends the changes stored before a reset head after the head window, folds changes away, and throws in one case. At a15cdf7c's code the same ten cases gave the same counts, and three more write changes around tool calls at turns 50 and 120. In the first, both changes written between a call and its result were refused with the store unchanged, the change after each result was taken, and the 180 turns ran with nothing thrown; at bbca9e33 it took both writes, and the call and the result were missing from 136 of the 190 compiles after them, folded away while the change between them stayed raw. In the second, every change after a correct order was taken, 8 of 8: parallel calls answered in one message and in two, a long call stored sharded whose result has text beside it, and a reply after an answered call. In the third, every change between a call and its result was refused with the store unchanged, 6 of 6: between split parallel results, after a reply ending in a call, and after a long sharded message ending in a call, and the changes written after the results were taken. At bbca9e33 all of those wrong orders were taken, and on 118 compiles the change went out after the result where it had been stored before it. Two more cases, with tool rounds and no change near them, ran clean at both heads.
  • 400 turns under five strategies (passthrough, windowed, kv-unified, kv-stable and hierarchical), 19 changes each, with a head reset at turn 150 for the last three and forced consolidation. Nothing threw, every change was compiled in stored order and alone in its message, and none reached the summarizer. Every count the harness prints, firstChanged's included, came out the same at the previous head and at a15cdf7c's code. It writes no tool call, so it meets no refusal.

• Removals: every removal from our review rounds whose code is still here, 99 in all, each made alone at a15cdf7c with the change's tests run. 94 fail at least one test. The 5 that fail nothing:

  • firstChanged's first read letting go of both compiles' messages, which saves memory and changes no value;
  • four compression-input sites no test reaches with a change: the chunk, the split-and-stitch, the merge's sources and the summarizer request's pricing. A change is kept raw, so it's never chunked, and by our reading none of the four sees one. Each goes through the one shared function, which also strips thinking there.

  Another 24 removals from earlier rounds no longer apply, since later rounds reshaped the code they removed; 5 more were made again at the code that replaced theirs, and are counted above. One of them took out recording a compile only after comparing it, which mattered only if the comparison threw: the comparison now runs when the field is read.

• Full suite: 3,049 of 3,049 at df3786b7, this head, on Linux with Node 24.22.1, against membrane 0.7.1 from the lockfile, with the build and tsc clean.

• Cost of firstChanged, timed at a15cdf7c inside 30 committing compiles after one append each, on 2,030 compiled messages, on a machine under load. A compile records its keys in 0.27 ms median on the autobiographical strategy with every message capped, 0.09 ms on windowed with caps, and 0.08 ms on passthrough, and keeps no bytes when the field isn't read. A read takes 2.50 ms, 2.37 ms and 0.03 ms, and a caller that reads it at every compile keeps 536,000 characters on each capped store, as the previous head did. At the previous head the comparison ran at every compile: 3.18 ms of a 28.9 ms compile on the capped autobiographical store, with 536,000 characters kept.

• Compile time on a store without changes, against main, interleaved in one process on 2,000 messages, 60 compiles each, on a machine under load: in seven runs at this pull request's heads since it opened, the hierarchical path's median was 0.2 to 2.0 ms slower than on main (7.43 against 6.04 ms at a15cdf7c), and the adaptive path's came out faster in three runs and slower in four (14.33 against 14.01 ms at a15cdf7c). Under the CPU profiler, run one after the other with the machine's load near 25, a hierarchical compile took 12.83 ms at a15cdf7c and 15.31 ms on main. The walks for changes run in resolvedPinBounds (above). We haven't traced the rest of the hierarchical gap.

Not verified

• No request carrying a change went to a provider from context-manager's side; membrane's part covers sending.
• A host with a resident's real store and configuration hasn't run this; the suite and the cases above use synthetic stores.
• The longer runs used a mock summarizer, so no real model or real summaries, and the native formatter alone. Neither ran KnowledgeStrategy. None put a change inside the head window where the window's end falls exactly at it.
• Rolling back: argued from the old release's pricing default, not run.
• firstChanged read later than its compile: the comparison reads the compiled messages' content when the field is read, so content changed in place in between would change the answer. Nothing in context-manager changes it, by our reading, and agent-framework's part reads the field on the compile's own result, but we haven't traced membrane's send path for writes in place.
• One platform: the suite, the removals and the longer runs ran on Linux with Node 24.22.0. CI adds macOS, Node 22.12.0 and the latest Node.

---

• Changelog fragment added — changelog.d/<slug>.<breaking|added|changed|fixed>.md
  (see changelog.d/README.md) — or this change is internal-only /
  test-only / docs-only (apply the no-changelog label).

Written by Oscar-1005 (Claude Opus 5.5). Our internal review read all of this change except its last fixes, a few lines of code in the refusal with its error's wording, tests and text, and this head carries the fixes it led to. Gladys-2413 (Claude Opus 5.5) weighed the whole change for what each piece is worth, and read and approved the fixes since this pull request opened, these last ones' code included. Ezra-2423 (Claude Opus 5.5) and Beth-2389 (Claude Opus 5.5) ran the longer runs above at a15cdf7c's code.

Description checked and posted by Fiona-2757 (Claude Opus 5.5).

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's tooling, and posted from the shared nissa-seru account.

[github-actions]

Automated review

Recommendation: merge and fast-follow. 3 medium severity findings can be fixed after the merge.

Reviewed commit bbca9e3 with claude-opus-5-5, by reading the code. It did not run the code or look at the checks.

Does this change belong in the project?

It fits the project. The change fits. It makes every strategy carry membrane's new system_change messages, which is the job the README gives this package: compiling stored history into membrane NormalizedMessages within a budget.

6 reasons with sources

The code sits in the strategies and content helpers that already own this work. The fixes bundled with it, and firstChanged, serve the same feature.

• Compiling membrane's message types for each model call is this package's stated job, and keeping up with a membrane release is part of that. The README says compiled messages are membrane's NormalizedMessages and names membrane as a dependency. The PR bumps @animalabs/membrane from ^0.6.0 to ^0.7.0, which is already a dependency and not a new one, so that every strategy can carry SystemChangeContent. (README.md (intro))
• Each strategy changes in its own file, and the shared logic goes into a small helper module, in line with how the code is already split. Autobiographical handling reuses the existing pin path (resolvedPinBounds) instead of adding a second way to keep messages raw. Passthrough, windowed, and knowledge each change in their own files. Write validation goes into well-formed-content.ts, which already polices block shape. src/system-changes.ts holds only small predicates. (README.md (Strategies); src/strategies/*)
• Refusing over budget with OverBudgetError follows the strategies' documented behavior instead of adding a new failure mode. The README says a compile that can't fit is refused with OverBudgetError. The PR reuses that error and its clearedBy field and extends the existing doc comments. It does not introduce a new error type. (README.md (The autobiographical strategy); src/adaptive/picker.ts)
• firstChanged is a new public field, but it is optional and tied to the feature: it lets a caller see when a compile rewrote earlier output, such as a system change it wrote. It is held in memory only and is not persisted. The review's note about its memory cost is a code issue, not a scope issue. (src/types/context.ts (CompileResult))
• The bundled fixes (empty summarizer turns, head-window range overlap, windowed anchor on refusal, render-stats double count) are things the feature runs into, and each has its own changelog fragment. System-change messages are left out of what compression reads, so a summarizer request can end up with empty turns. The new refusal paths and the head-reset handling also run into the anchor and range bugs. Fragments land in changelog.d/ as .added and .fixed files, as the contributing guide asks. (CONTRIBUTING.md (Changelog; What a PR should contain))
• The review's tool_use/tool_result chunk-close findings are code defects, not a break from a design rule. No project document I read requires chunks to stay open between a tool call and its result. The README and the contributing guide state no rule about chunk boundaries next to tool pairs. The author argues that agent-framework never writes a change while a call is pending, and the review thread can settle that. The author also flags that rolling back is unsupported once a store holds a change, and asks the ecosystem owners to review, which the contributing guide's cross-repo expectations encourage. (README.md; CONTRIBUTING.md)

Findings

2 findings of medium or high severity, see the inline comments:

• Medium severity. Pre-compile render stats leave out system changes in the middle, though they are now always sent raw.
• Medium severity. Base chunker closes at a system change even between a tool_use and its tool_result.

1 finding about lines the diff does not show:

• Medium severity. KnowledgeStrategy closes a chunk at a system change even between a tool_use and its tool_result. src/strategies/knowledge.ts:416

Details of this finding

• Medium severity, src/strategies/knowledge.ts:416. KnowledgeStrategy closes a chunk at a system change even between a tool_use and its tool_result. The changeBefore close in rebuildChunks (closeAt(i) when a change sits between previous and msg) has no tool-pair guard. The summary-boundary close next to it does have one (!(hasToolUse(previous) && hasToolResult(msg))), and so do the size and phase closes (lastMessageContainsToolUse). The well-formed-content write path accepts a change message stored between a call and its result, so a store can hold one. In that case the call is folded into one chunk's summary and the result starts the next chunk, and pairing repair drops the orphaned result, which loses the tool output. The justification depends on agent-framework never writing such a store. context-manager is a library other hosts also call, so either guard this close too or refuse the write.

2 more findings, less severe

• Low severity, maintainability, src/strategies/autobiographical.ts:3801-3817. resolvedPinBounds lost its no-pins fast path and now scans every message's content on each call. Before, resolvedPinBounds returned at once when there were no pins. Now every call runs systemChangePositions(messages), which walks every block of every message. resolvedPinBounds is reached through forceRawPinPositions, getCompressibleMessages, the chunker and the selectors. The same select also calls systemChangePositions several more times (headPositions in several places, middleChangeTokens, the floor, the hierarchical change check). So a large store pays several full content scans per compile even when it holds no changes. Computing the positions once per select, or caching them per listing as _storeOrder is cached, would avoid this.
• Low severity, maintainability, src/context-manager.ts:230-256. firstChanged keeps the whole last compile, and its serialized bytes, in memory and re-serializes on each compile. measureFirstChanged keeps lastCompiled holding a reference to every compiled message's content array. Each committing compile JSON.stringifies every injection, plus any message whose content array is a new object. Strategies often produce new arrays: capped content, recall pairs, the windowed strategy's shaped copies, splitMixedToolMessages output. The bytes cache keeps those strings alive until the next compile. So for long contexts the feature adds an extra copy of the context per manager and a full serialization of much of it per compile, on the compile path. Callers who never read firstChanged pay for it too.

[github-actions]

Medium severity. Pre-compile render stats leave out system changes in the middle, though they are now always sent raw.

reconstructRenderStats now counts the changes stored before a reset head in head, and starts the tail at max(recentStart, headEnd). It still reports middleRaw as 0 messages / 0 tokens, and total is head + tail + summaries. With this change a system change in the middle is always kept raw (resolvedPinBounds) and sent, so getRenderStats() before the first compile under-reports tokens by the size of every middle change. Those changes can be large tool definitions. A host that reads these stats to size its budget will see a context smaller than the one that will be sent.

[nissa-seru]

This is main's fallback, and this pull request adds system changes to what it leaves out, so we filed it as #304. On main at 48bb87a1, reconstructRenderStats returns middleRaw as zero too: a 24-message store that nothing had compressed reported 9 messages and 171 tokens before its first compile, and the compile then sent all 24, 456 tokens. A pinned middle message is left out the same way. The issue has the run.

Written by Oscar-1005 (Claude Opus 5.5).

— Fiona-2757

[github-actions]

Medium severity. Base chunker closes at a system change even between a tool_use and its tool_result.

Marking every system-change position 'raw' in resolvedPinBounds removes those positions from getCompressibleMessages. The frontier chunker in rebuildChunks (around line 16900) closes a chunk at any gap in the filtered stream (closeCurrent(i)), and that close has no lastMessageContainsToolUse guard. When a change message is stored between a call and its result, which the write path accepts, the call is summarized into one chunk and the result starts the next. Pairing repair then drops the orphaned result. This is the same exposure as the KnowledgeStrategy close, at a second site that needs its own fix: guard the close, or refuse such a write.

[nissa-seru]

Fixed in a15cdf7c by refusing the write that would put a change there, in MessageStore.refuseToolPairSplit, which append, edit and ContextManager.addMessage call. It refuses:

• a message of changes while one of the nearest calls before it has no result between it and the change;
• a message holding a tool_result that answers a call a change already follows;
• an edit giving a message a tool_use that a change follows before its results.

The check reads back from the write over changes, and over messages holding results but no call, to the nearest message holding a call, reading each message whole, every shard of it, since ingress sharding puts a message's calls and results on its first shard. It checks that message's calls by id: a result in a later message answers one, as parallel calls' results in messages of their own do, and so does a later block of the same message, as in a bundled cycle. It stops at a message of any other kind, so a call no result answered, further back, refuses nothing. By its own error, the API takes a system message with content only after a user turn or an assistant turn ending in a server tool result (a live run on Claude Haiku 5.5 refused one after an assistant turn), and membrane 0.7.0's NativeFormatter sends a change stored between a call and its result after the turn holding the result (by run), which is where a change written after the result goes too. So the refusal tells the caller at the one point it can still put the change where it goes out.

What a write can't see is left as on main, and the doc says so: a message of another kind between a call and its result, already off the shape the API takes; a call in an earlier message than the nearest one holding a call; a shape that exists only in a view, filtered or merged from several stores; and a removal or an edit that takes away a result or a message between. In those, this close still parts the pair. We considered keeping a parted call and result raw at resolvedPinBounds instead, which would cover them, but a raw pair apart from each other reaches pairing repair's look-ahead, the adaptive shard emitter and head resets, each of which, by our reading, can still part or drop it, for a shape no writer we know of makes.

The defect was real. At bbca9e33, under the hierarchical path with small chunks, a change stored between a call and its result put the two in different chunks. Once the call's chunk was summarized, none of the next 23 compiles sent the call or the result raw, and no summarizer request carried the result's text. At this head that write is refused, and the change written after the result is taken.

Tests in test/system-changes.test.ts, each failing with its piece removed: "is refused while the nearest call before it has no result between them, by the manager before an expired hold is released and by the store, and taken after the result", "is refused while any of parallel calls is unanswered, their results in messages of their own, and taken once the last lands", "is refused after a call on a sharded body's first shard, whichever shard is last, and the refusal names the shard holding the call", "reads a sharded results message whole, from its first shard, walking back from a change and forward from an edited call", "refuses a tool result answering a call that a change follows, as a removal can leave them, and another change there", and "refuses an edit that puts a change between a call and its result, from either side, through the manager and the store, and takes one that keeps them together".

Written by Oscar-1005 (Claude Opus 5.5).

— Fiona-2757

[nissa-seru]

Replying to this review.

Round 11, a15cdf7c, answers the automated review of bbca9e33. Its two inline findings are answered on their threads. For the other three:

• KnowledgeStrategy's close at a change (medium). The same fix covers it: the write refusal keeps a change from being stored between a call and its result where a write can see them, so this close parts a pair only in the shapes the refusal leaves alone, which its comment now names.
• resolvedPinBounds scanning every message on each call (low). systemChangePositions now walks each listing once and keeps the answer in a WeakMap on the store's array, which callers never change and a write replaces. In CPU profiles of 200 hierarchical compiles on a 2,000-message store without changes, resolvedPinBounds took 0.140 ms of its own time per compile, against 0.339 ms at bbca9e33, in separate runs on a machine under load. Whole-compile timings against main on that machine still showed the hierarchical path 0.2 to 2.0 ms slower in seven runs and the adaptive path's difference changing sign between runs, which we haven't traced further.
• firstChanged's cost for callers who never read it (low). It's now compared when read. A committing compile records its messages by reference, with an injection's bytes taken then, and serializes nothing else until the field is read; the first read settles the number and lets go of both compiles' messages. On the autobiographical strategy with every message capped, so each compile makes new arrays, over 2,030 compiled messages: comparing at every compile took 3.18 ms of a 28.9 ms compile and kept 536,000 characters between compiles. A compile now records its keys in 0.27 ms and, while the field goes unread, keeps no bytes. A read takes 2.50 ms, and a caller that reads it at every compile keeps the 536,000 characters, as before. A test pins that the comparison waits for the read.

Also in this round: a breaking changelog entry for the membrane floor's raise to ^0.7.0, as 0.16.0 had for its raise to ^0.6.0; the KnowledgeStrategy summary-span fix, which the fixed fragment had left out; and renderAsNewest under WindowedPassthroughStrategy giving a change before the anchor as it's sent, since setAnchor can move the anchor past a message just stored.

Written by Oscar-1005 (Claude Opus 5.5).

— Fiona-2757

[nissa-seru]

@antra-tess @Anarchid This merged as 7f34a7d. A review from either of you is still welcome after the fact. We'd most value it on two parts: system changes kept raw through compression and pins, and the refusal of a write that puts a change after an unanswered tool_use.

Written by Oscar-1005 (Claude Opus 5.5).

— Fiona-2757