instar 1.3.721 → 1.3.722
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/server.d.ts.map +1 -1
- package/dist/commands/server.js +24 -1
- package/dist/commands/server.js.map +1 -1
- package/dist/core/TopicPinFoldView.d.ts +33 -1
- package/dist/core/TopicPinFoldView.d.ts.map +1 -1
- package/dist/core/TopicPinFoldView.js +58 -2
- package/dist/core/TopicPinFoldView.js.map +1 -1
- package/package.json +1 -1
- package/src/data/builtin-manifest.json +2 -2
- package/upgrades/1.3.722.md +73 -0
- package/upgrades/side-effects/u4-1-poolreference-skew-fix.md +47 -0
|
@@ -39,6 +39,32 @@ import { type MergedReplicatedPin } from './TopicPinReplicatedStore.js';
|
|
|
39
39
|
import type { PinFoldOffsets, PinFoldResult } from './CoherenceJournalReader.js';
|
|
40
40
|
import type { TopicPinSkewQuarantine } from './TopicPinSkewQuarantine.js';
|
|
41
41
|
import type { TopicPlacement } from './PlacementExecutor.js';
|
|
42
|
+
/**
|
|
43
|
+
* The pool-relative physical-time floor for the skew gate (foundation spec
|
|
44
|
+
* §3.4; fb-1d51e996-0a3): `max(now, freshest clock-OK peer heartbeat
|
|
45
|
+
* self-stamp)`. `receive()` deliberately never consults `now()` itself — its
|
|
46
|
+
* reference is `max(last.physical, poolReference)` — so the CALLER must supply
|
|
47
|
+
* a floor that MOVES with wall time. Without one, a quiet fold clock's
|
|
48
|
+
* `last.physical` freezes at its construction seed (server boot) and every
|
|
49
|
+
* honest record authored more than `maxDriftMs` later is falsely quarantined
|
|
50
|
+
* as "skew-ahead" — STICKILY, by design. Pins are rare operator events, so the
|
|
51
|
+
* pin stream is almost always quiet: the frozen reference killed pin
|
|
52
|
+
* replication between long-running servers (live-reproduced 2026-07-02).
|
|
53
|
+
*
|
|
54
|
+
* Pool-relative, per §3.4: a receiver whose own NTP lags must not quarantine a
|
|
55
|
+
* legitimately-ahead peer, so the freshest self-reported heartbeat stamp of
|
|
56
|
+
* each clock-OK peer raises the floor above a slow local `now()`. A peer whose
|
|
57
|
+
* clock the registry's skew FSM already distrusts (`clockSkewStatus !== 'ok'`)
|
|
58
|
+
* NEVER raises the floor — a suspect clock must not widen the acceptance
|
|
59
|
+
* window. `now()` participates only as a FLOOR inside the max (§3.4 forbids
|
|
60
|
+
* the BARE local now() AS the reference — a floor can only raise the
|
|
61
|
+
* reference, never cause a false rejection). Degenerate case (single machine /
|
|
62
|
+
* no peers): `now()` alone — the pool is self.
|
|
63
|
+
*/
|
|
64
|
+
export declare function poolReferenceFromCapacities(nowMs: number, capacities: Array<{
|
|
65
|
+
clockSkewStatus?: string;
|
|
66
|
+
selfReportedLastSeen?: string;
|
|
67
|
+
}>): number;
|
|
42
68
|
/** The reader seam (CoherenceJournalReader.foldPinRecords — injectable for tests). */
|
|
43
69
|
export interface PinFoldReader {
|
|
44
70
|
foldPinRecords(opts: {
|
|
@@ -55,7 +81,12 @@ export interface TopicPinFoldViewDeps {
|
|
|
55
81
|
maxDriftMs?: number;
|
|
56
82
|
/** ws13FoldMaxBytes, read live (default 64MB upstream). */
|
|
57
83
|
foldMaxBytes?: () => number;
|
|
58
|
-
/**
|
|
84
|
+
/** Observed pool-relative physical-time floor for the skew gate (§3.4 —
|
|
85
|
+
* `poolReferenceFromCapacities` in production). The fold ALWAYS floors the
|
|
86
|
+
* reference at its own `now()` regardless (fb-1d51e996-0a3: a missing dep
|
|
87
|
+
* must never re-freeze the reference at the fold clock's boot seed); this
|
|
88
|
+
* dep adds the pool-relative part (clock-OK peer heartbeat stamps) so a
|
|
89
|
+
* slow LOCAL clock doesn't falsely quarantine an ahead-but-honest peer. */
|
|
59
90
|
poolReference?: () => number | undefined;
|
|
60
91
|
now?: () => number;
|
|
61
92
|
/** Fired ONCE per newly-quarantined record (upstream dedupes per-origin, P17). */
|
|
@@ -133,6 +164,7 @@ export declare class TopicPinFoldView {
|
|
|
133
164
|
recordKeys: number;
|
|
134
165
|
truncationEpisodeOpen: boolean;
|
|
135
166
|
quarantined: number;
|
|
167
|
+
skewReference: number;
|
|
136
168
|
};
|
|
137
169
|
}
|
|
138
170
|
//# sourceMappingURL=TopicPinFoldView.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"TopicPinFoldView.d.ts","sourceRoot":"","sources":["../../src/core/TopicPinFoldView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC3F,OAAO,EAAmC,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACzG,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,IAAI,EAAE;QAAE,YAAY,CAAC,EAAE,cAAc,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa,CAAC;CAC3F;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,sBAAsB,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC9B,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B
|
|
1
|
+
{"version":3,"file":"TopicPinFoldView.d.ts","sourceRoot":"","sources":["../../src/core/TopicPinFoldView.ts"],"names":[],"mappings":"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"}
|
|
@@ -36,6 +36,39 @@
|
|
|
36
36
|
*/
|
|
37
37
|
import { HybridLogicalClock, coerceHlc } from './HybridLogicalClock.js';
|
|
38
38
|
import { compareHlc, isValidPinMachineId } from './TopicPinReplicatedStore.js';
|
|
39
|
+
/**
|
|
40
|
+
* The pool-relative physical-time floor for the skew gate (foundation spec
|
|
41
|
+
* §3.4; fb-1d51e996-0a3): `max(now, freshest clock-OK peer heartbeat
|
|
42
|
+
* self-stamp)`. `receive()` deliberately never consults `now()` itself — its
|
|
43
|
+
* reference is `max(last.physical, poolReference)` — so the CALLER must supply
|
|
44
|
+
* a floor that MOVES with wall time. Without one, a quiet fold clock's
|
|
45
|
+
* `last.physical` freezes at its construction seed (server boot) and every
|
|
46
|
+
* honest record authored more than `maxDriftMs` later is falsely quarantined
|
|
47
|
+
* as "skew-ahead" — STICKILY, by design. Pins are rare operator events, so the
|
|
48
|
+
* pin stream is almost always quiet: the frozen reference killed pin
|
|
49
|
+
* replication between long-running servers (live-reproduced 2026-07-02).
|
|
50
|
+
*
|
|
51
|
+
* Pool-relative, per §3.4: a receiver whose own NTP lags must not quarantine a
|
|
52
|
+
* legitimately-ahead peer, so the freshest self-reported heartbeat stamp of
|
|
53
|
+
* each clock-OK peer raises the floor above a slow local `now()`. A peer whose
|
|
54
|
+
* clock the registry's skew FSM already distrusts (`clockSkewStatus !== 'ok'`)
|
|
55
|
+
* NEVER raises the floor — a suspect clock must not widen the acceptance
|
|
56
|
+
* window. `now()` participates only as a FLOOR inside the max (§3.4 forbids
|
|
57
|
+
* the BARE local now() AS the reference — a floor can only raise the
|
|
58
|
+
* reference, never cause a false rejection). Degenerate case (single machine /
|
|
59
|
+
* no peers): `now()` alone — the pool is self.
|
|
60
|
+
*/
|
|
61
|
+
export function poolReferenceFromCapacities(nowMs, capacities) {
|
|
62
|
+
let ref = nowMs;
|
|
63
|
+
for (const c of capacities) {
|
|
64
|
+
if (c.clockSkewStatus !== 'ok')
|
|
65
|
+
continue; // a suspect clock never raises the floor
|
|
66
|
+
const t = c.selfReportedLastSeen ? Date.parse(c.selfReportedLastSeen) : Number.NaN;
|
|
67
|
+
if (Number.isFinite(t) && t > ref)
|
|
68
|
+
ref = t;
|
|
69
|
+
}
|
|
70
|
+
return ref;
|
|
71
|
+
}
|
|
39
72
|
export class TopicPinFoldView {
|
|
40
73
|
d;
|
|
41
74
|
/** Per-key HLC winner (puts AND tombstones — tombstone-respecting by construction). */
|
|
@@ -85,6 +118,19 @@ export class TopicPinFoldView {
|
|
|
85
118
|
this.lastScannedBytes = res.scannedBytes;
|
|
86
119
|
this.totalFolds++;
|
|
87
120
|
const clock = this.foldClock();
|
|
121
|
+
// fb-1d51e996-0a3 (§3.4): ONE moving, pool-relative reference per refresh.
|
|
122
|
+
// receive()'s reference is max(last.physical, poolReference) and NEVER the
|
|
123
|
+
// bare now() — so without this floor a quiet fold clock freezes at its
|
|
124
|
+
// construction seed and falsely skew-quarantines (stickily) every honest
|
|
125
|
+
// record authored > maxDriftMs later. now() is the floor; the wired dep
|
|
126
|
+
// raises it with clock-OK peer heartbeat stamps (pool-relative). A faulty
|
|
127
|
+
// dep degrades to the now() floor — never back to the frozen reference.
|
|
128
|
+
let observedPool = 0;
|
|
129
|
+
try {
|
|
130
|
+
observedPool = this.d.poolReference?.() ?? 0;
|
|
131
|
+
}
|
|
132
|
+
catch { /* @silent-fallback-ok — the now() floor stands; a dep fault must not re-freeze the gate or fail the fold */ }
|
|
133
|
+
const poolReference = Math.max(this.now(), Number.isFinite(observedPool) ? observedPool : 0);
|
|
88
134
|
for (const entry of res.entries) {
|
|
89
135
|
const recordKey = typeof entry.data.recordKey === 'string' ? entry.data.recordKey : null;
|
|
90
136
|
if (recordKey === null)
|
|
@@ -103,8 +149,7 @@ export class TopicPinFoldView {
|
|
|
103
149
|
continue;
|
|
104
150
|
// The skew gate (R-r2-1): the existing receive() contract. Rejection ⇒
|
|
105
151
|
// durable quarantine + loud (deduped upstream) escalation; NEVER merged.
|
|
106
|
-
const
|
|
107
|
-
const received = clock.receive(hlc, poolReference !== undefined ? { poolReference } : {});
|
|
152
|
+
const received = clock.receive(hlc, { poolReference });
|
|
108
153
|
if (received.rejected) {
|
|
109
154
|
const newlyAdded = this.d.quarantine.add({ key: recordKey, hlc, origin: entry.origin });
|
|
110
155
|
if (newlyAdded) {
|
|
@@ -222,6 +267,16 @@ export class TopicPinFoldView {
|
|
|
222
267
|
quarantined = this.d.quarantine.all().length;
|
|
223
268
|
}
|
|
224
269
|
catch { /* best-effort */ }
|
|
270
|
+
// The LIVE skew-gate floor a refresh would use right now (fb-1d51e996-0a3
|
|
271
|
+
// diagnosability: a frozen reference is visible on GET /pool/pin-quarantine
|
|
272
|
+
// instead of only in a quarantine log line after the damage).
|
|
273
|
+
let skewReference = this.now();
|
|
274
|
+
try {
|
|
275
|
+
const observed = this.d.poolReference?.() ?? 0;
|
|
276
|
+
if (Number.isFinite(observed) && observed > skewReference)
|
|
277
|
+
skewReference = observed;
|
|
278
|
+
}
|
|
279
|
+
catch { /* @silent-fallback-ok — observability read; the now() floor stands */ }
|
|
225
280
|
return {
|
|
226
281
|
lastFoldAt: this.lastFoldAtMs ? new Date(this.lastFoldAtMs).toISOString() : null,
|
|
227
282
|
totalFolds: this.totalFolds,
|
|
@@ -229,6 +284,7 @@ export class TopicPinFoldView {
|
|
|
229
284
|
recordKeys: this.winners.size,
|
|
230
285
|
truncationEpisodeOpen: this.truncationEpisodeOpen,
|
|
231
286
|
quarantined,
|
|
287
|
+
skewReference,
|
|
232
288
|
};
|
|
233
289
|
}
|
|
234
290
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"TopicPinFoldView.js","sourceRoot":"","sources":["../../src/core/TopicPinFoldView.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAqB,MAAM,yBAAyB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAA4B,MAAM,8BAA8B,CAAC;
|
|
1
|
+
{"version":3,"file":"TopicPinFoldView.js","sourceRoot":"","sources":["../../src/core/TopicPinFoldView.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "./builtin-manifest.schema.json",
|
|
3
3
|
"schemaVersion": 1,
|
|
4
|
-
"generatedAt": "2026-07-
|
|
5
|
-
"instarVersion": "1.3.
|
|
4
|
+
"generatedAt": "2026-07-02T18:19:29.791Z",
|
|
5
|
+
"instarVersion": "1.3.722",
|
|
6
6
|
"entryCount": 202,
|
|
7
7
|
"entries": {
|
|
8
8
|
"hook:session-start": {
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Upgrade Guide — vNEXT
|
|
2
|
+
|
|
3
|
+
<!-- assembled-by: assemble-next-md -->
|
|
4
|
+
<!-- bump: patch -->
|
|
5
|
+
|
|
6
|
+
## What Changed
|
|
7
|
+
|
|
8
|
+
Fixes fb-1d51e996-0a3 (live-reproduced 2026-07-02). PR #1332's U4.1 pin fold
|
|
9
|
+
(`TopicPinFoldView`) skew-gates every replicated `topic-pin-record` HLC through
|
|
10
|
+
`HybridLogicalClock.receive(hlc, {poolReference})` — but nothing supplied the
|
|
11
|
+
`poolReference` dep. `receive()` deliberately references
|
|
12
|
+
`max(last.physical, poolReference ?? 0)` and never the bare local `now()`
|
|
13
|
+
(foundation spec §3.4), so a QUIET fold clock's reference froze at its
|
|
14
|
+
construction seed (server boot). Pins are rare operator events, so the stream is
|
|
15
|
+
almost always quiet: any honest pin record authored more than `maxDriftMs`
|
|
16
|
+
(default 5min) after the receiver's last acceptance was falsely quarantined as
|
|
17
|
+
"skew-ahead" — STICKILY, by design — killing pin replication between
|
|
18
|
+
long-running servers (and even author-side: a machine quarantined its OWN fresh
|
|
19
|
+
PUT after a peer bounce).
|
|
20
|
+
|
|
21
|
+
The fix, per the converged u4-1 spec's §2C gate composed with foundation §3.4:
|
|
22
|
+
|
|
23
|
+
- New `poolReferenceFromCapacities()` export — `max(now, freshest clock-OK peer
|
|
24
|
+
heartbeat self-stamp)`; peers the registry's skew FSM distrusts never raise
|
|
25
|
+
the floor; single-machine → now alone.
|
|
26
|
+
- `TopicPinFoldView.refresh()` floors the reference at its own `now()` on every
|
|
27
|
+
fold regardless of wiring (a future unwired construction site can never
|
|
28
|
+
re-freeze the gate), and passes the moving reference on every `receive()`.
|
|
29
|
+
- `src/commands/server.ts` wires the dep at the single production construction
|
|
30
|
+
site from `machinePoolRegistry.getCapacities()`.
|
|
31
|
+
- `status().skewReference` (additive) exposes the live gate floor on
|
|
32
|
+
`GET /pool/pin-quarantine` for diagnosability.
|
|
33
|
+
|
|
34
|
+
The sticky quarantine is NOT weakened: existing false-positive entries clear via
|
|
35
|
+
`pruneSuperseded` on the next accepted PUT/tombstone or the explicit readmit
|
|
36
|
+
route; a genuinely future-skewed record (beyond `maxDriftMs` of the MOVING pool
|
|
37
|
+
reference) is still rejected, stickily quarantined, and escalated.
|
|
38
|
+
|
|
39
|
+
## What to Tell Your User
|
|
40
|
+
|
|
41
|
+
<!-- audience: user, maturity: preview -->
|
|
42
|
+
- **Machine pins now stick reliably**: when you pin a conversation to a specific
|
|
43
|
+
machine ("run this on the mini"), that choice now replicates dependably
|
|
44
|
+
between your machines even after they have been running quietly for a long
|
|
45
|
+
time. Previously a long-running machine could wrongly treat a fresh pin or
|
|
46
|
+
unpin from another machine as suspicious and ignore it; that misjudgment is
|
|
47
|
+
fixed, and the protection against genuinely wrong clocks is unchanged.
|
|
48
|
+
|
|
49
|
+
## Summary of New Capabilities
|
|
50
|
+
|
|
51
|
+
None — a correctness fix to the existing U4.1 pin-persistence machinery, plus a
|
|
52
|
+
diagnostic field on an existing read surface.
|
|
53
|
+
|
|
54
|
+
## Evidence
|
|
55
|
+
|
|
56
|
+
Live reproduction, 2026-07-02 (two machines, Laptop + Mini):
|
|
57
|
+
|
|
58
|
+
- The Laptop quarantined the Mini's honest unpin tombstone:
|
|
59
|
+
`[TopicPinFoldView] skew-quarantined pin record key=30223 origin=m_4cbc0d4a0c… (physical 1783012672666 > reference 1783009909639 + 300000ms)` —
|
|
60
|
+
the reference (16:31:49Z) was the Laptop server's BOOT time, 46 minutes stale
|
|
61
|
+
against the record's honest 17:17:52Z author time.
|
|
62
|
+
- After a Laptop bounce, the Mini's fold quarantined its OWN freshly-authored
|
|
63
|
+
PUT: `(physical 1783013064633 > reference 1783012686688 + 300000ms)` — its own
|
|
64
|
+
fold clock frozen at ITS boot.
|
|
65
|
+
- Control: with a freshly-booted receiver (reference near now), the SAME record
|
|
66
|
+
was ACCEPTED and the full transfer actuated in ~90s — isolating the defect to
|
|
67
|
+
reference sourcing; the rest of the pipeline is correct.
|
|
68
|
+
|
|
69
|
+
After the fix, the new regression suite models exactly those traces (a record
|
|
70
|
+
authored 46min after the fold-clock seed on a quiet stream) and it is accepted;
|
|
71
|
+
a stash-revert run proves the 9 new tests fail on the pre-fix code while all 25
|
|
72
|
+
pre-existing u41 tests still pass. Full u41 family (unit + integration + e2e):
|
|
73
|
+
52/52 green.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Side-Effects Review — wire the pool-relative skew reference (poolReference) into the U4.1 pin fold
|
|
2
|
+
|
|
3
|
+
**Spec:** docs/specs/u4-1-pin-persistence.md (converged 2026-07-02 + approved) §2C skew gate, composed with docs/specs/multi-machine-replicated-store-foundation.md §3.4 (pool-relative reference) / §10.2-family maxDriftMs clamp / §15 risk-5/risk-6 (maxDriftMs sourcing — BLOCKER-5).
|
|
4
|
+
**Defect:** fb-1d51e996-0a3 (live-reproduced 2026-07-02). PR #1332 shipped `TopicPinFoldView` whose skew gate calls `HybridLogicalClock.receive(hlc, {poolReference})`, but NOTHING supplied the `poolReference` dep. `receive()` deliberately references `max(last.physical, poolReference ?? 0)` and NEVER `now()` (§3.4 — a slow receiver must not quarantine an ahead-but-honest peer), so with the dep unwired a QUIET fold clock's reference froze at its construction seed (server boot). Pins are rare operator events → the pin stream is almost always quiet → ANY honest record authored more than maxDriftMs (default 5min) after boot was falsely quarantined as "skew-ahead", STICKILY (dismissal ≠ re-admission, by design). Pin replication was effectively dead between long-running servers; F6 fired even author-side (the Mini quarantined its OWN fresh PUT after a Laptop bounce).
|
|
5
|
+
**Files:** src/core/TopicPinFoldView.ts, src/commands/server.ts (the single production construction site — grep-verified; routes.ts/AgentServer.ts references are type-only).
|
|
6
|
+
|
|
7
|
+
## What changed
|
|
8
|
+
|
|
9
|
+
1. **`poolReferenceFromCapacities()` (new export, TopicPinFoldView.ts):** the production sourcing helper — `max(nowMs, freshest clock-OK peer heartbeat self-stamp)`. A peer whose `clockSkewStatus !== 'ok'` (the registry's skew FSM already distrusts it) NEVER raises the floor; malformed/absent stamps are ignored; no peers → now alone (single-machine degenerate case: the pool is self).
|
|
10
|
+
2. **`TopicPinFoldView.refresh()`:** computes ONE reference per refresh — `max(now(), poolReference dep ?? 0)` — and passes it on EVERY `receive()`. The fold now floors the reference at its own `now()` regardless of wiring, so a future construction site that forgets the dep can never re-freeze the gate (Structure > Willpower: the component is correct by construction). A THROWING/non-finite dep degrades to the now() floor — never back to the frozen reference, never a fold fault (the fold's "never throws" contract holds).
|
|
11
|
+
3. **`server.ts` wiring:** the fold-view construction supplies `poolReference: () => poolReferenceFromCapacities(Date.now(), machinePoolRegistry?.getCapacities() ?? [])` (late-bound closure — the registry is assigned later in boot and read at fold time; registry fault → `Date.now()`).
|
|
12
|
+
4. **`status().skewReference` (additive):** the LIVE gate floor is exposed on `GET /pool/pin-quarantine`'s fold block, so a frozen reference is diagnosable from the read surface instead of only in a quarantine log line after the damage.
|
|
13
|
+
|
|
14
|
+
## Why now() as a FLOOR is spec-faithful (§3.4)
|
|
15
|
+
|
|
16
|
+
§3.4 forbids the BARE local `now()` AS the reference — its concern is FALSE REJECTION when the receiver's own NTP lags. `now()` inside the max can only RAISE the reference (never lower it), so it can never cause a false rejection; the pool-relative arm (peer heartbeat stamps) is what protects the slow-local-clock case, exactly as §3.4 prescribes ("its own last durable HLC, plus — when available — the observed pool physical time carried in the capacity heartbeat"). The spec's named heartbeat-median primitive does not exist yet (§15 risk-6 tracks derived skew measurement); the freshest clock-OK self-stamp is the available observed-pool signal, and the registry's categorical skew FSM (its real §3.4 purpose) keeps a suspect clock from widening the acceptance window.
|
|
17
|
+
|
|
18
|
+
## Blast radius
|
|
19
|
+
|
|
20
|
+
- **The sticky quarantine is NOT weakened.** The quarantine store's `(key, hlc)` exclusion still runs BEFORE the gate on every fold; ack ≠ re-admission; only supersession by a newer honest record (`pruneSuperseded`) or the explicit `POST /pool/pin-quarantine/readmit` clears an entry. Existing FALSE-POSITIVE entries in the field clear exactly that way — no auto-reclassification of quarantined entries is added (stickiness protects against real poison, and a bulk auto-clear could re-admit a genuinely poisoned record).
|
|
21
|
+
- **The real protection is intact:** a record more than maxDriftMs ahead of the MOVING pool reference is still rejected + stickily quarantined + escalated (P17-deduped). Proven by the moving-reference rejection test.
|
|
22
|
+
- **Gate posture unchanged:** the fold view remains read-only over journal bytes and actuates nothing; ws13 flags/dev-gates untouched; no new config key (the reference sourcing is derived state, not tunable — maxDriftMs remains the existing clamped knob).
|
|
23
|
+
- **`skewReference` is additive observability** on an existing Bearer-gated read; no consumer asserts the exact status shape (grep-verified).
|
|
24
|
+
|
|
25
|
+
## Risk + mitigation
|
|
26
|
+
|
|
27
|
+
- **Risk:** a fast-clocked PEER's heartbeat self-stamp raises the floor and admits a near-poison record. **Mitigation:** stamps from peers the registry's skew FSM distrusts (`divergence-detected-once` / `suspect-clock-removed`) never participate; a tolerated stamp is within the registry's clockSkewToleranceMs of router receive time, so the widening is bounded by an already-accepted tolerance. Proven by the suspect-clock helper test.
|
|
28
|
+
- **Risk:** the dep faults mid-fold and kills pin resolution. **Mitigation:** try/catch at BOTH layers (wiring closure and refresh()) degrading to the moving now() floor; proven by the faulty-dep test.
|
|
29
|
+
- **Risk:** the fix silently un-quarantines existing sticky entries. **Mitigation:** none needed — the sticky set is consulted before the gate; the fix changes only NEW verdicts. Existing false-positive entries clear via supersession on the next accepted PUT/tombstone for that key, or explicit readmit.
|
|
30
|
+
|
|
31
|
+
## Migration parity
|
|
32
|
+
|
|
33
|
+
None required — pure code fix. No config defaults added or changed (no `migrateConfig`), no CLAUDE.md template change (no new operator-facing capability — `skewReference` is a diagnostic field on an existing documented surface), no hook/skill/template change. Verified against the Migration Parity Standard checklist: no agent-installed file is touched.
|
|
34
|
+
|
|
35
|
+
## Rollback
|
|
36
|
+
|
|
37
|
+
Revert the commit. The dep is optional and the fold's now() floor is internal — reverting restores the (broken) frozen-reference behavior with no state migration in either direction; quarantine files remain valid either way.
|
|
38
|
+
|
|
39
|
+
## Tests
|
|
40
|
+
|
|
41
|
+
- `tests/unit/u41-pin-persistence.test.ts` — new describe `pool-relative skew reference — quiet streams accept honest records (fb-1d51e996-0a3)`: (1) honest record 46min after the fold-clock seed on a QUIET stream → ACCEPTED (the live Laptop-quarantines-Mini evidence; FAILS without the fix — verified by stash-revert run: 9/9 new fail, 25/25 pre-existing pass); (2) author-side own-PUT acceptance after a quiet period (the Mini-quarantines-its-own-PUT arm); (3) genuinely future-skewed record vs the MOVING reference → still REJECTED + stickily quarantined + escalated; (4) the wired dep raises the floor when the LOCAL clock lags (§3.4 pool-relative); (5) faulty dep degrades to the now() floor; (6) `status().skewReference` moves with time; (7) `poolReferenceFromCapacities` matrix (degenerate/raise/suspect-clock/malformed); (8) wiring-integrity source-grep: the server.ts construction supplies the dep from the registry helper.
|
|
42
|
+
- `tests/integration/u41-pin-persistence-routes.test.ts` — the quarantine read's fold block exposes a finite `skewReference` within 60s of the live wall clock (not frozen at a seed).
|
|
43
|
+
- Full u41 family green with the fix: 52/52 across unit + integration (routes, answer-complete) + e2e (alive/lease-handover). tsc clean; `npm run lint` clean.
|
|
44
|
+
|
|
45
|
+
## Agent awareness
|
|
46
|
+
|
|
47
|
+
No CLAUDE.md template change — this repairs the documented U4.1 pin-persistence behavior (pins replicate between machines as already described); it adds no new capability or trigger an agent must know about. <!-- tracked: fb-1d51e996-0a3 -->
|