Skip to content

Commit 09b5889

Browse files
ualtinokalfonso-magic-context
ualtinok
and
alfonso-magic-context
committed
docs(cache-policy): harness-neutral cache-stability golden vectors
The shared parity target for the SUBC cache-policy core co-design: a harness-neutral spec of prompt-cache stability behavior, extracted from MC's cache-invariant E2E suite. Both MC (observer harness) and the SUBC Rust core (author harness) validate against this same file. - cache-stability-golden-vectors.schema.md: the model (SOFT+/SOFT/HARD action contract, frozen render units with byte-complete payloads, anchor-validity = content-fingerprint over coverage, the deferred-work coordinator, the axioms), plus the opaque-token convention that keeps the file from smuggling any harness's internal hash into the parity target. - cache-stability-golden-vectors.json: 8 'mechanics' vectors (growing-tail defer, post-execute settle, frozen-strip-not-first-applied-on-defer, byte-complete skeleton across a moving window, delta-rides-m1-SOFT, HARD fold drains deferred work, provider-nonce-is-not-a-bust, revert-discards-and- rebuilds). Identity/render_config are opaque consistent tokens; the core only string-equals + branches. computeRawRangeFingerprint and analyzePasses are cited as MC's reference implementations. Additive-only after emit; SUBC appends the author-policy layer (requested_policy defer/now/forced) without touching the mechanics set. Co-authored-by: Alfonso [Magic Context] <288211368+alfonso-magic-context@users.noreply.github.com>
1 parent dc137e8 commit 09b5889

2 files changed

Lines changed: 364 additions & 0 deletions

File tree

‎docs/cache-policy/cache-stability-golden-vectors.json‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
{
2+
"schema_version": 1,
3+
"description": "Harness-neutral cache-stability golden vectors. The shared parity target for any harness that pins a render-config across turns without thrashing the provider prefix cache. See cache-stability-golden-vectors.schema.md. All identity/render_config values are OPAQUE CONSISTENT TOKENS, never real hashes: the core only does string-equality + branch.",
4+
"reference_impl": {
5+
"anchor_fingerprint": "magic-context: computeRawRangeFingerprint (packages/plugin/src/hooks/magic-context/read-session-true-raw-tokens.ts) - ordinal:id:parts.length:partContentFingerprint over the covered range, raw content only, never tag/drop/strip state.",
6+
"byte_stability_oracle": "magic-context: analyzePasses/findBusts (packages/e2e-tests/src/cache-analysis.ts) - a bust is a wire-segment divergence at or before the previous request's last cache_control breakpoint, with cache_control and provider nonces normalized out."
7+
},
8+
"common_asserts": [
9+
"for every pass i>0 where expect_action == 'SOFT+': cached_prefix_bytes[i] == cached_prefix_bytes[i-1]",
10+
"for every frozen unit replayed on a 'SOFT+' pass: rendered_bytes(unit) == unit.frozen_payload",
11+
"for every pass whose input_identity diverges from the active anchor over the covered prefix: expect_action in {'SOFT','HARD'}, never 'SOFT+'",
12+
"a 'SOFT' or 'HARD' pass is permitted (and for HARD, required) to change cached_prefix_bytes - that is the bust"
13+
],
14+
"vectors": [
15+
{
16+
"name": "V1-growing-tail-defer",
17+
"layer": "mechanics",
18+
"provenance": "cache-invariants.test.ts A1 - low-pressure conversation, several pure-defer turns grow the tail.",
19+
"notes": "Tail growth happens after the breakpoint, so the covered prefix is unchanged and input_identity stays cov0. Steady state: every pass SOFT+, zero busts.",
20+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
21+
"initial_state": {
22+
"version": 0,
23+
"anchor_fingerprint": "cov0",
24+
"frozen_units": [
25+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>BASELINE</session-history>" },
26+
{ "key": "m1", "kind": "synthesized-region", "frozen_payload": "(no new content since last materialization)" }
27+
],
28+
"pending_changes": []
29+
},
30+
"passes": [
31+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
32+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
33+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
34+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
35+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
36+
]
37+
},
38+
{
39+
"name": "V2-post-execute-defer-settles",
40+
"layer": "mechanics",
41+
"provenance": "cache-invariants.test.ts A2 - a conversation that crossed an execute pass, then defer passes continue to grow.",
42+
"notes": "An execute pass may legitimately bust once (drops/markers materialize). The invariant is that the DEFER passes after it are byte-stable. p1 is the execute (SOFT, allowed to change bytes); p2..p4 are SOFT+ and must be byte-identical.",
43+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
44+
"initial_state": {
45+
"version": 0,
46+
"anchor_fingerprint": "cov0",
47+
"frozen_units": [
48+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>BASELINE</session-history>" },
49+
{ "key": "m1", "kind": "synthesized-region", "frozen_payload": "(no new content since last materialization)" }
50+
],
51+
"pending_changes": []
52+
},
53+
"passes": [
54+
{ "signal": { "kind": "execute", "usage": "high" }, "input_identity": "cov0", "expect_action": "SOFT", "expect_frozen_set_delta": [ { "key": "drop1", "kind": "drop", "frozen_payload": "[dropped 1]" } ] },
55+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
56+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
57+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
58+
]
59+
},
60+
{
61+
"name": "V3-frozen-strip-not-first-applied-on-defer",
62+
"layer": "mechanics",
63+
"provenance": "cache-invariants.test.ts A3 - the regression: an aged strip/drop unit must be FROZEN on a bust pass and replayed verbatim, never first-applied on a defer pass (which would change tail bytes mid-prefix and bust the whole prefix after it).",
64+
"notes": "p1 (a bust pass) freezes the strip decision into drop_reduce. p2..p4 are defer passes that age the unit past the protected window; they REPLAY the frozen [dropped 99999] verbatim. A correct core never introduces a strip on a SOFT+ pass (expect_frozen_set_delta is empty on every defer pass). This is the single most-broken MC invariant; the per-unit frozen_payload assert catches a renderer that re-derives.",
65+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
66+
"initial_state": {
67+
"version": 0,
68+
"anchor_fingerprint": "cov0",
69+
"frozen_units": [
70+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>BASELINE</session-history>" }
71+
],
72+
"pending_changes": []
73+
},
74+
"passes": [
75+
{ "signal": { "kind": "execute", "usage": "high" }, "input_identity": "cov0", "expect_action": "SOFT", "expect_frozen_set_delta": [ { "key": "drop_reduce", "kind": "strip", "frozen_payload": "[dropped 99999]" } ] },
76+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
77+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
78+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
79+
]
80+
},
81+
{
82+
"name": "V4-skeleton-byte-complete-across-moving-window",
83+
"layer": "mechanics",
84+
"provenance": "Leak-A direct test (smart-drops / edit_marker). A superseded edit compresses to a filePath + region-hint prefix; the frozen_payload must be byte-complete (captured at freeze), NOT re-derived from current content each pass.",
85+
"notes": "p1 freezes edit1 to a skeleton with a fixed region-hint payload. p2..p3 grow the tail (a newer edit lands; the 'recent window' moves). edit1 must replay its frozen_payload verbatim - a core that re-derives the 40-char diff prefix from current content would flip bytes on p2 (the [dropped]->[truncated] class). The per-unit assert (rendered_bytes == frozen_payload) is the catch.",
86+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
87+
"initial_state": {
88+
"version": 0,
89+
"anchor_fingerprint": "cov0",
90+
"frozen_units": [
91+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>BASELINE</session-history>" }
92+
],
93+
"pending_changes": []
94+
},
95+
"passes": [
96+
{ "signal": { "kind": "edit-superseded" }, "input_identity": "cov0", "expect_action": "SOFT", "expect_frozen_set_delta": [ { "key": "edit1", "kind": "skeleton", "frozen_payload": "edit packages/app/x.ts | @@ -10,6 +10,8 @@ [dropped 1]" } ] },
97+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
98+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
99+
]
100+
},
101+
{
102+
"name": "V5-delta-rides-m1-soft-m0-frozen",
103+
"layer": "mechanics",
104+
"provenance": "cache-invariants.test.ts B9/B10/B11 - a compartment published (or memory added/updated) after m[0] materialized surfaces as an m[1] delta on a SOFT pass; m[0] stays byte-identical; defer passes after it replay m[0] AND m[1] byte-identical.",
105+
"notes": "p1 surfaces the delta: m1 re-renders (SOFT, busts at the m1 breakpoint), m0 unchanged. p2..p3 are SOFT+ and replay both regions byte-identical. m0's frozen_payload never appears in a delta after init = m0 stays frozen (the SOFT changed only m1). Pre-fix regressions: max_compartment_seq was a HARD trigger (folded the compartment INTO m0); supersede-delta keeps m0 stale-but-frozen with a <memory-updates> correction in m1.",
106+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
107+
"initial_state": {
108+
"version": 0,
109+
"anchor_fingerprint": "cov0",
110+
"frozen_units": [
111+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history></session-history>" },
112+
{ "key": "m1", "kind": "synthesized-region", "frozen_payload": "(no new content since last materialization)" }
113+
],
114+
"pending_changes": []
115+
},
116+
"passes": [
117+
{ "signal": { "kind": "compartment-published" }, "input_identity": "cov0", "expect_action": "SOFT", "expect_frozen_set_delta": [ { "key": "m1", "kind": "synthesized-region", "frozen_payload": "<new-compartments>cache-invariant chunk</new-compartments>" } ] },
118+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
119+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
120+
]
121+
},
122+
{
123+
"name": "V6-hard-fold-folds-m1-into-m0-and-drains-deferred",
124+
"layer": "mechanics",
125+
"provenance": "cache-invariants.test.ts B12 (HARD fold = project epoch bump) + the deferred-work coordinator. A memory rode m[1]; a deferred drop was queued; then a HARD trigger fires.",
126+
"notes": "p1 queues a deferred drop WITHOUT busting (SOFT+, observer half - drops accumulate while m1 replays frozen). p2 is the HARD trigger: m[0] re-materializes folding the m1 delta into the baseline, m1 resets to the empty placeholder, AND the queued drop drains into THIS bust (a HARD bust from any cause drains all deferred work). p3..p4 re-stabilize (SOFT+, byte-identical on the new baseline cov1).",
127+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
128+
"initial_state": {
129+
"version": 0,
130+
"anchor_fingerprint": "cov0",
131+
"frozen_units": [
132+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history></session-history>" },
133+
{ "key": "m1", "kind": "synthesized-region", "frozen_payload": "<new-memories>B12 delta rule</new-memories>" }
134+
],
135+
"pending_changes": []
136+
},
137+
"passes": [
138+
{ "signal": { "kind": "drop-queued" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
139+
{ "signal": { "kind": "hard-fold-trigger", "cause": "epoch-bump" }, "input_identity": "cov0", "expect_action": "HARD", "expect_frozen_set_delta": [
140+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>B12 delta rule</session-history>" },
141+
{ "key": "m1", "kind": "synthesized-region", "frozen_payload": "(no new content since last materialization)" },
142+
{ "key": "drop1", "kind": "drop", "frozen_payload": "[dropped 1]" }
143+
] },
144+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov1", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
145+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov1", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
146+
]
147+
},
148+
{
149+
"name": "V7-provider-nonce-only-is-not-a-bust",
150+
"layer": "mechanics",
151+
"provenance": "cache-stability oracle normalization - Anthropic billing nonce (cch) and cache_control breakpoint movement are normalized OUT of the bust decision; they are not content changes.",
152+
"notes": "p2's only change is a provider nonce / a forward-walked cache_control breakpoint. The covered content is unchanged (input_identity stays cov0), so it must classify SOFT+ and the cached_prefix_bytes must be unchanged after normalization. A core that treats the nonce as content would false-bust.",
153+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
154+
"initial_state": {
155+
"version": 0,
156+
"anchor_fingerprint": "cov0",
157+
"frozen_units": [
158+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>BASELINE</session-history>" }
159+
],
160+
"pending_changes": []
161+
},
162+
"passes": [
163+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
164+
{ "signal": { "kind": "provider-nonce-only" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
165+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
166+
]
167+
},
168+
{
169+
"name": "V8-revert-within-covered-prefix-discards-and-rebuilds",
170+
"layer": "mechanics",
171+
"provenance": "Leak-C (revert-safety). The frozen set's anchor fingerprints the covered-prefix CONTENT, not the boundary position. A host-caused revert/truncate that retracts content WITHIN the covered prefix must discard the frozen set and render fresh (a bust), never blind-replay against a shifted/absent anchor.",
172+
"notes": "p1..p2 replay (SOFT+, input_identity cov0). p3 reverts content inside the covered prefix: input_identity diverges to cov0@r1 -> the core must DISCARD the frozen set and render fresh (HARD), establishing a new anchor cov1. p4..p5 re-stabilize on cov1. Contrast with V1: a tail-only trim/grow BELOW coverage keeps input_identity==anchor and stays SOFT+; only IN-coverage content change diverges. This is the case that bites a clean 'replay every pass' model.",
173+
"render_config": { "system_hash": "sys0", "tool_set_id": "tools0", "model_key": "m0" },
174+
"initial_state": {
175+
"version": 0,
176+
"anchor_fingerprint": "cov0",
177+
"frozen_units": [
178+
{ "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>BASELINE</session-history>" }
179+
],
180+
"pending_changes": []
181+
},
182+
"passes": [
183+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
184+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov0", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
185+
{ "signal": { "kind": "revert-or-truncate", "scope": "within-covered-prefix" }, "input_identity": "cov0@r1", "expect_action": "HARD", "expect_frozen_set_delta": [ { "key": "m0", "kind": "synthesized-region", "frozen_payload": "<session-history>BASELINE-REVERTED</session-history>" } ] },
186+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov1", "expect_action": "SOFT+", "expect_frozen_set_delta": [] },
187+
{ "signal": { "kind": "growing-tail" }, "input_identity": "cov1", "expect_action": "SOFT+", "expect_frozen_set_delta": [] }
188+
]
189+
}
190+
]
191+
}

0 commit comments

Comments
 (0)