dexbot 1.7.1 → 1.7.2

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.
Files changed (51) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/claw/package.json +1 -1
  3. package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
  4. package/claw/runtimes/openclaw-plugin/package.json +1 -1
  5. package/dist/modules/account_bots.d.ts +1 -0
  6. package/dist/modules/account_bots.js +7 -5
  7. package/dist/modules/constants.d.ts +2 -0
  8. package/dist/modules/constants.js +16 -2
  9. package/dist/modules/dexbot_class.d.ts +22 -0
  10. package/dist/modules/dexbot_class.js +30 -0
  11. package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
  12. package/dist/modules/dexbot_cow_runtime.js +68 -56
  13. package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
  14. package/dist/modules/dexbot_maintenance_runtime.js +33 -6
  15. package/dist/modules/node_flap_score.d.ts +6 -6
  16. package/dist/modules/node_flap_score.js +6 -6
  17. package/dist/modules/order/accounting.d.ts +9 -4
  18. package/dist/modules/order/accounting.js +89 -26
  19. package/dist/modules/order/async_lock.d.ts +7 -1
  20. package/dist/modules/order/async_lock.js +7 -1
  21. package/dist/modules/order/export.js +25 -18
  22. package/dist/modules/order/fill_ledger.d.ts +99 -0
  23. package/dist/modules/order/fill_ledger.js +103 -0
  24. package/dist/modules/order/grid.d.ts +75 -18
  25. package/dist/modules/order/grid.js +207 -61
  26. package/dist/modules/order/grid_reconcile_internal.js +16 -4
  27. package/dist/modules/order/index.d.ts +14 -5
  28. package/dist/modules/order/index.js +5 -5
  29. package/dist/modules/order/lifecycle.js +3 -3
  30. package/dist/modules/order/manager.d.ts +15 -24
  31. package/dist/modules/order/manager.js +40 -27
  32. package/dist/modules/order/sync_engine.d.ts +66 -118
  33. package/dist/modules/order/sync_engine.js +118 -162
  34. package/dist/modules/order/utils/math.d.ts +7 -3
  35. package/dist/modules/order/utils/math.js +7 -3
  36. package/dist/modules/order/utils/order.d.ts +40 -41
  37. package/dist/modules/order/utils/order.js +110 -84
  38. package/dist/modules/order/utils/system.d.ts +81 -6
  39. package/dist/modules/order/utils/system.js +167 -29
  40. package/dist/modules/timing_policy.js +2 -2
  41. package/dist/modules/types.d.ts +22 -27
  42. package/docs/COW_INVARIANTS.md +5 -1
  43. package/docs/DEXBOT_COMPARISON.md +4 -4
  44. package/docs/EVOLUTION.md +6 -5
  45. package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
  46. package/docs/GRID_RECONCILE.md +3 -3
  47. package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +38 -30
  48. package/docs/README.md +1 -1
  49. package/docs/architecture.md +26 -8
  50. package/modules/README.md +3 -0
  51. package/package.json +3 -3
@@ -4,7 +4,7 @@
4
4
  * Price derivation, persistence, grid correction, and UI/interactive utilities.
5
5
  *
6
6
  * ===============================================================================
7
- * TABLE OF CONTENTS (43 exported functions + 11 structural view types)
7
+ * TABLE OF CONTENTS (52 exported functions + 12 structural view types)
8
8
  * ===============================================================================
9
9
  *
10
10
  * SECTION 1: PRICE DERIVATION (9 functions + 1 internal)
@@ -50,7 +50,18 @@
50
50
  * - resetLastFillPivot(manager) - Clear the pivot to cold state
51
51
  * - restoreLastFillPivot(manager) - Restore the persisted pivot into the manager
52
52
  *
53
- * SECTION 7: UI & INTERACTIVE UTILITIES (6 functions)
53
+ * SECTION 7: FILL PIPELINE & LAST-FILL GUARD (9 functions)
54
+ * - reanchorBoundaryFromLastFill(manager, ...) - Re-anchor a rebuilt boundary to the last fill
55
+ * - rearmLastFillPivotFromMarketFill(manager) - Re-arm the pivot from the last market fill
56
+ * - isLastFillGuardBlocked(price, type, lastPrice, lastType) - LAST-FILL-GUARD predicate
57
+ * - isLastFillPlacementBlocked(manager, price, type) - Placement-side LAST-FILL-GUARD wrapper
58
+ * - readFillPipelineState(source) - Projection of the fill-pipeline state
59
+ * - resolveGridUpdateBlockers(source, options) - Blockers that forbid a grid update right now
60
+ * - noteGridUpdateBlockers(...) - Log/record the blockers for one decision
61
+ * - hasUnsettledFills(source) - Whether any fill is still unsettled (with a reason)
62
+ * - getPipelineInFlightAgeMs(source, nowMs) - Age of the oldest in-flight pipeline work
63
+ *
64
+ * SECTION 8: UI & INTERACTIVE UTILITIES (6 functions)
54
65
  * - ensureProfilesDirectory(profilesDir) - Ensure profiles directory exists
55
66
  * - sleep(ms) - Pause execution for specified duration
56
67
  * - readInput(prompt, options) - Read user input from stdin
@@ -59,7 +70,7 @@
59
70
  * - withBlockchainRetry(fn, label, options) - Blockchain op with timeout + retry + node failover
60
71
  * (withTimeout lives in ./timeout)
61
72
  *
62
- * SECTION 8: GENERAL UTILITIES (7 functions)
73
+ * SECTION 9: GENERAL UTILITIES (7 functions)
63
74
  * - resolveAccountRef(manager, account) - Resolve best account reference
64
75
  * - deepFreeze(obj) - Recursively freeze object for immutability
65
76
  * - cloneMap(map) - Create shallow clone of Map
@@ -70,8 +81,8 @@
70
81
  *
71
82
  * STRUCTURAL VIEW TYPES:
72
83
  * AssetMeta, PoolReserve, PoolEntry, BitSharesClient, AmaCenterSnapshot,
73
- * FeeCacheEntryData, SpreadCorrectionRefusalReason, SpreadCorrectionReadiness,
74
- * UnmatchedChainOrderLike, GridResizeResult, CowResult
84
+ * FeeCacheEntryData, SpreadCorrectionReadiness, GridUpdateBlockerCode,
85
+ * GridUpdateBlocker, FillPipelineState, GridResizeResult, CowResult
75
86
  *
76
87
  * ===============================================================================
77
88
  */
@@ -80,7 +91,7 @@ const require = createRequire(import.meta.url);
80
91
  import { path } from '../../path_api.js';
81
92
  import { getStorage } from '../../storage/index.js';
82
93
  const storage = getStorage();
83
- import { API_LIMITS, ORDER_TYPES, ORDER_STATES, COW_ACTIONS, FEE_PARAMETERS, BTS_PRECISION, PIPELINE_TIMING, NATIVE_CLIENT, GRID_LIMITS, TIMING } from '../../constants.js';
94
+ import { API_LIMITS, ORDER_TYPES, ORDER_STATES, COW_ACTIONS, FEE_PARAMETERS, BTS_PRECISION, PIPELINE_TIMING, NATIVE_CLIENT, GRID_LIMITS, TIMING, FILL_PROCESSING } from '../../constants.js';
84
95
  import { PATHS } from '../../paths.js';
85
96
  import { toFiniteNumber, isValidNumber, toKnownNumber } from '../format.js';
86
97
  import * as MathUtils from './math.js';
@@ -863,6 +874,9 @@ export async function initializeFeeCache(botsConfig, BitShares) {
863
874
  (hasDiskFallback ? '. Using previously cached value from disk.' : '.'));
864
875
  }
865
876
  }
877
+ // The math-side fee-cache entry is a narrower structural view of the same
878
+ // row this module persists. Cast through the setter's own parameter type
879
+ // instead of naming a type that is not exported from utils/math.ts.
866
880
  MathUtils._setFeeCache(cache);
867
881
  _saveFeeCacheToDisk(cache);
868
882
  return cache;
@@ -1769,9 +1783,148 @@ export function isLastFillPlacementBlocked(manager, price, type) {
1769
1783
  return { blocked: true, pivot, reason: 'direction' };
1770
1784
  return { blocked: false, pivot };
1771
1785
  }
1786
+ /**
1787
+ * Read the fill-pipeline counters ONCE, from a bot or a bare manager.
1788
+ *
1789
+ * This is the only place that peeks these fields. The previous projection
1790
+ * (`hasUnsettledFills`) swallowed every read error and returned "settled",
1791
+ * which is a fail-OPEN answer in a fail-closed system: an unreadable queue
1792
+ * looked like an idle one and the grid was updated from a stale master.
1793
+ * Unreadable is now a first-class state (`ok: false`), surfaced as
1794
+ * `unknown-blocker`.
1795
+ *
1796
+ * These counters are pipeline bookkeeping, not lifecycle evidence: absence
1797
+ * decisions still use the lifecycle registry (INV-LIFE-003), so this reader
1798
+ * cannot become a second evidence set.
1799
+ */
1800
+ export function readFillPipelineState(source) {
1801
+ const settled = { ok: true, queued: 0, deferred: false, inFlight: 0, owed: 0 };
1802
+ if (!source || typeof source !== 'object')
1803
+ return settled;
1804
+ try {
1805
+ const outer = source;
1806
+ const mgr = (outer.manager && typeof outer.manager === 'object'
1807
+ ? outer.manager
1808
+ : outer);
1809
+ const queue = outer._incomingFillQueue;
1810
+ if (queue !== undefined && queue !== null && !Array.isArray(queue)) {
1811
+ return { ...settled, ok: false, error: '_incomingFillQueue is not an array' };
1812
+ }
1813
+ const crawls = mgr._pendingFillCrawls;
1814
+ if (crawls !== undefined && crawls !== null && !Array.isArray(crawls)) {
1815
+ return { ...settled, ok: false, error: '_pendingFillCrawls is not an array' };
1816
+ }
1817
+ const inFlightRaw = mgr._fillBatchInFlight;
1818
+ const inFlight = Number(inFlightRaw);
1819
+ if (inFlightRaw !== undefined && inFlightRaw !== null && !Number.isFinite(inFlight)) {
1820
+ return { ...settled, ok: false, error: '_fillBatchInFlight is not a number' };
1821
+ }
1822
+ return {
1823
+ ok: true,
1824
+ queued: Array.isArray(queue) ? queue.length : 0,
1825
+ deferred: outer._deferredFillsPending === true,
1826
+ inFlight: Number.isFinite(inFlight) && inFlight > 0 ? inFlight : 0,
1827
+ owed: Array.isArray(crawls) ? crawls.length : 0,
1828
+ };
1829
+ }
1830
+ catch (err) {
1831
+ return { ok: false, queued: 0, deferred: false, inFlight: 0, owed: 0, error: getErrorMessage(err) };
1832
+ }
1833
+ }
1834
+ /**
1835
+ * Every reason the grid must NOT be mutated this cycle, as codes.
1836
+ *
1837
+ * Composition only — no new evidence: the fill counters come from
1838
+ * `readFillPipelineState`, the broadcast policy from `getLivePendingBroadcasts`
1839
+ * (INV-BROADCAST-005), the region from `isPlacementActive`, the rebuild flag
1840
+ * from the manager. A grid blocker (may the grid mutate?) is deliberately NOT
1841
+ * the per-action fresh-placement grace and NOT a known-wrong-side fact; those
1842
+ * stay with the planner and the correction queue (INV-RECON-006).
1843
+ */
1844
+ function fillStateBlockers(state) {
1845
+ if (!state.ok) {
1846
+ return [{ code: 'unknown-blocker', detail: state.error || 'fill pipeline state unreadable' }];
1847
+ }
1848
+ const blockers = [];
1849
+ if (state.queued > 0)
1850
+ blockers.push({ code: 'fill-queued', detail: `${state.queued} fill(s) queued for processing` });
1851
+ if (state.deferred)
1852
+ blockers.push({ code: 'fill-deferred', detail: 'deferred fill drain pending' });
1853
+ if (state.inFlight > 0)
1854
+ blockers.push({ code: 'fill-in-flight', detail: 'fill batch in flight' });
1855
+ if (state.owed > 0)
1856
+ blockers.push({ code: 'crawl-owed', detail: `${state.owed} owed boundary crawl(s)` });
1857
+ return blockers;
1858
+ }
1859
+ export function resolveGridUpdateBlockers(source, options = {}) {
1860
+ const now = Number.isFinite(Number(options.now)) ? Number(options.now) : Date.now();
1861
+ const blockers = fillStateBlockers(readFillPipelineState(source));
1862
+ if (!source || typeof source !== 'object')
1863
+ return blockers;
1864
+ const outer = source;
1865
+ const mgr = (outer.manager && typeof outer.manager === 'object' ? outer.manager : source);
1866
+ try {
1867
+ if (typeof mgr.isPlacementActive === 'function' && mgr.isPlacementActive() === true) {
1868
+ const kind = typeof mgr.placementKind === 'function' ? mgr.placementKind() : '';
1869
+ blockers.push({ code: 'placement-held', detail: `placement region held by ${kind || 'unknown'}` });
1870
+ }
1871
+ if (typeof mgr.isStructuralRebuildInProgress === 'function' && mgr.isStructuralRebuildInProgress() === true) {
1872
+ blockers.push({ code: 'rebuild-active', detail: 'structural rebuild in progress' });
1873
+ }
1874
+ // Read-only: a predicate must not GC the pending set or emit log lines.
1875
+ const pending = OrderUtils.getLivePendingBroadcasts(mgr, { now, gc: false });
1876
+ const pendingCount = Array.isArray(pending) ? pending.length : 0;
1877
+ if (pendingCount > 0) {
1878
+ blockers.push({ code: 'broadcast-pending', detail: `${pendingCount} unresolved broadcast(s)` });
1879
+ }
1880
+ }
1881
+ catch (err) {
1882
+ if (!blockers.some((b) => b.code === 'unknown-blocker')) {
1883
+ blockers.push({ code: 'unknown-blocker', detail: `blocker probe failed: ${getErrorMessage(err)}` });
1884
+ }
1885
+ }
1886
+ return blockers;
1887
+ }
1888
+ /**
1889
+ * Count consecutive blocked cycles and decide whether the state is STUCK.
1890
+ *
1891
+ * Escalation is deliberately narrow: only `unknown-blocker` (unreadable
1892
+ * pipeline state) escalates. A busy pipeline (`fill-in-flight`,
1893
+ * `broadcast-pending`, a held region) is normal work and must not trigger a
1894
+ * structural resync — the placement/broadcast watchdogs own those bounds. The
1895
+ * counter is a cycle count, not a timing window: it is NOT a `TIMING` entry and
1896
+ * must not be classified in `modules/timing_policy.ts`.
1897
+ *
1898
+ * @returns `{ cycles, escalate }`; `escalate` is true exactly when the state
1899
+ * stayed unreadable for `FILL_PROCESSING.GRID_BLOCKED_ESCALATE_CYCLES`
1900
+ * consecutive attempts.
1901
+ */
1902
+ export function noteGridUpdateBlockers(source, blockers, options = {}) {
1903
+ if (!source || typeof source !== 'object')
1904
+ return { cycles: 0, escalate: false };
1905
+ const holder = source.manager && typeof source.manager === 'object'
1906
+ ? source.manager
1907
+ : source;
1908
+ const list = Array.isArray(blockers) ? blockers : [];
1909
+ const unreadable = list.some((b) => b && b.code === 'unknown-blocker');
1910
+ if (list.length === 0 || !unreadable) {
1911
+ holder._gridUpdateBlockedCycles = 0;
1912
+ return { cycles: 0, escalate: false };
1913
+ }
1914
+ const prev = Number(holder._gridUpdateBlockedCycles);
1915
+ const cycles = (Number.isFinite(prev) && prev > 0 ? prev : 0) + 1;
1916
+ holder._gridUpdateBlockedCycles = cycles;
1917
+ const rawLimit = Number(options.limit ?? FILL_PROCESSING.GRID_BLOCKED_ESCALATE_CYCLES);
1918
+ const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : 12;
1919
+ return { cycles, escalate: cycles >= limit };
1920
+ }
1772
1921
  /**
1773
1922
  * Are fills still UNSETTLED (arrived but not yet absorbed by the grid)?
1774
1923
  *
1924
+ * Projection over `resolveGridUpdateBlockers` so the prose reason and the code
1925
+ * cannot disagree. Kept as a boolean for its existing callers; new callers
1926
+ * should ask for the codes.
1927
+ *
1775
1928
  * While this returns true the master grid still holds filled slots as ACTIVE
1776
1929
  * and the boundary has not crawled for them, so any geometry-derived plan
1777
1930
  * (window top-up, startup-style reconcile) is built on the PREVIOUS book. The
@@ -1786,29 +1939,14 @@ export function isLastFillPlacementBlocked(manager, price, type) {
1786
1939
  * @returns {{unsettled: boolean, reason: string|null}}
1787
1940
  */
1788
1941
  export function hasUnsettledFills(source) {
1789
- if (!source || typeof source !== 'object')
1942
+ // Fill state only: this predicate answers "have the fills settled?", not
1943
+ // "is the host busy?" (placement/broadcast/rebuild are the full resolver's
1944
+ // business). A projection that pulled the host codes in would report fills
1945
+ // unsettled whenever, say, a placement probe threw.
1946
+ const fill = fillStateBlockers(readFillPipelineState(source))[0];
1947
+ if (!fill)
1790
1948
  return { unsettled: false, reason: null };
1791
- const outer = source;
1792
- const mgr = (outer.manager && typeof outer.manager === 'object'
1793
- ? outer.manager
1794
- : outer);
1795
- try {
1796
- const queued = Array.isArray(outer._incomingFillQueue) ? outer._incomingFillQueue.length : 0;
1797
- if (queued > 0)
1798
- return { unsettled: true, reason: `${queued} fill(s) queued for processing` };
1799
- if (outer._deferredFillsPending === true)
1800
- return { unsettled: true, reason: 'deferred fill drain pending' };
1801
- const inFlight = Number(mgr._fillBatchInFlight);
1802
- if (Number.isFinite(inFlight) && inFlight > 0)
1803
- return { unsettled: true, reason: 'fill batch in flight' };
1804
- const owed = Array.isArray(mgr._pendingFillCrawls) ? mgr._pendingFillCrawls.length : 0;
1805
- if (owed > 0)
1806
- return { unsettled: true, reason: `${owed} owed boundary crawl(s)` };
1807
- }
1808
- catch {
1809
- return { unsettled: false, reason: null };
1810
- }
1811
- return { unsettled: false, reason: null };
1949
+ return { unsettled: true, reason: fill.detail };
1812
1950
  }
1813
1951
  /**
1814
1952
  * Age of the most recent bot-level pipeline raise.
@@ -2205,7 +2343,7 @@ export async function retryPersistenceIfNeeded(manager) {
2205
2343
  *
2206
2344
  * @param {Object} manager - OrderManager instance
2207
2345
  * @param {Object} accountOrders - AccountOrders data accessor
2208
- * @param {string} botKey - Bot identifier for persistence
2346
+ * @param {string} _botKey - Unused; persistence is keyed off the manager.
2209
2347
  * @param {Function} updateOrdersOnChainBatchFn - Batch update function for blockchain operations
2210
2348
  * @param {Function} updateGridFromBlockchainSnapshotFn - Grid resize function (injected to avoid circular dependency with grid.ts)
2211
2349
  * @returns {Promise<void>}
@@ -169,8 +169,8 @@ export const TIMING_CLASSIFICATIONS = Object.freeze({
169
169
  },
170
170
  FILL_DEDUPE_WINDOW_MS: {
171
171
  kind: 'self-healing',
172
- rationale: 'Coalescing window for duplicate fill events.',
173
- removal: 'Delete when fill identity is a chain tuple (tx+op) everywhere; the window would then be redundant with that key.',
172
+ rationale: 'Lease on a fill CLAIM accepted but not yet booked (deferral/crash). The processed-fill store refuses a booked key while retained, at any age; FILL_RECORD_RETENTION_MS bounds retention, not an expiry.',
173
+ removal: 'Delete once startup recovery reconciles a restored claim against chain-balance evidence (recomputing the credit from chain truth) instead of bounding it by age.',
174
174
  },
175
175
  });
176
176
  /**
@@ -146,24 +146,17 @@ export interface ChainOrdersLike {
146
146
  wasRecentlyOwnCancelled?(orderId: string): boolean;
147
147
  [key: string]: unknown;
148
148
  }
149
- /**
150
- * Minimal runtime surface shared by the `dexbot_*_runtime.ts` layer. This is
151
- * a seeded interface to grow as each runtime file is typed — the index
152
- * signature keeps the many `_camelCase` internals reachable (as `unknown`)
153
- * while the common surface gets real types. Replace index-signature reads with
154
- * named fields as the relevant owners are typed.
155
- */
156
- /**
157
- * The DexBot runtime surface used by the `dexbot_*_runtime.ts` layer (and the
158
- * `DexBot` class itself, which structurally satisfies it). No index signature:
159
- * every member the runtime touches is enumerated, so a typo or an undeclared
160
- * internal is a compile error instead of a silent `unknown`.
161
- */
162
149
  /** Credential-daemon signing token (used until the private key is unlocked). */
163
150
  export interface SigningToken {
164
151
  accountName: string;
165
152
  socketPath?: string;
166
153
  }
154
+ /**
155
+ * The `DEXBot` runtime surface used by the `dexbot_*_runtime.ts` layer (the
156
+ * `DEXBot` class itself structurally satisfies it). No index signature: every
157
+ * member the runtime touches is enumerated, so a typo or an undeclared internal
158
+ * is a compile error instead of a silent `unknown`.
159
+ */
167
160
  export interface BotLike {
168
161
  config: GridConfig;
169
162
  manager: OrderManagerLike;
@@ -742,11 +735,11 @@ interface AccountTotalsGate {
742
735
  ok: boolean;
743
736
  [key: string]: unknown;
744
737
  }
745
- /** Accountant surface the sync engine calls directly. */
746
738
  /** Result of `accountant.processFillAccounting()`. */
747
739
  interface FillAccountingResult extends UnknownRecord {
748
740
  status: string;
749
741
  }
742
+ /** Accountant surface the sync engine calls directly. */
750
743
  interface AccountantLike {
751
744
  processFillAccounting(fillOp: unknown, fillKey: string, options?: UnknownRecord): Promise<boolean>;
752
745
  adjustTotalBalance(orderType: string, delta: number, operation: string): Promise<unknown>;
@@ -914,6 +907,8 @@ export interface AccountOrdersLike {
914
907
  }
915
908
  /** Batch-persistence handle for processed fill keys. */
916
909
  export interface ProcessedFillStoreLike {
910
+ /** In-memory booked keys (key -> processedAt). The dedupe authority at credit time. */
911
+ tracker: Map<string, number>;
917
912
  configure(options?: {
918
913
  accountOrders?: AccountOrdersLike | null;
919
914
  }): void;
@@ -958,17 +953,6 @@ interface ManagerRecoveryState {
958
953
  structuralResyncRequested?: boolean;
959
954
  [key: string]: unknown;
960
955
  }
961
- /**
962
- * The contract the order engine consumes from `OrderManager`. This is the
963
- * decoupled interface the `modules/order/**` layer types its `manager`
964
- * parameters against, so the engine does not need to import the concrete
965
- * class (avoiding a runtime import cycle). `OrderManager` structurally
966
- * satisfies it.
967
- *
968
- * Optional members are either wired in later by the runtime layer
969
- * (e.g. `requestStructuralGridResync`, `notifyBoundaryUpdate`) or read only
970
- * defensively; keep them optional so partial test doubles still type-check.
971
- */
972
956
  /**
973
957
  * Three-valued result of an operation whose outcome is not always knowable.
974
958
  *
@@ -1036,6 +1020,17 @@ export interface CreditRuntimeLike {
1036
1020
  runCreditWatchdog(): Promise<unknown>;
1037
1021
  shutdown(): Promise<unknown>;
1038
1022
  }
1023
+ /**
1024
+ * The contract the order engine consumes from `OrderManager`. This is the
1025
+ * decoupled interface the `modules/order/**` layer types its `manager`
1026
+ * parameters against, so the engine does not need to import the concrete
1027
+ * class (avoiding a runtime import cycle). `OrderManager` structurally
1028
+ * satisfies it.
1029
+ *
1030
+ * Optional members are either wired in later by the runtime layer
1031
+ * (e.g. `requestStructuralGridResync`, `notifyBoundaryUpdate`) or read only
1032
+ * defensively; keep them optional so partial test doubles still type-check.
1033
+ */
1039
1034
  export interface OrderManagerLike {
1040
1035
  /**
1041
1036
  * Unified order-lifecycle read surface (see modules/order/lifecycle.ts).
@@ -1136,6 +1131,7 @@ export interface OrderManagerLike {
1136
1131
  _pauseRecalcLogging: boolean;
1137
1132
  _throwOnIllegalState: boolean;
1138
1133
  _fillBatchInFlight: number;
1134
+ _gridUpdateBlockedCycles?: number;
1139
1135
  _fillProcessingLock: ManagerLock;
1140
1136
  _syncLock: ManagerLock;
1141
1137
  _divergenceLock: ManagerLock;
@@ -1267,14 +1263,13 @@ export interface OrderManagerLike {
1267
1263
  _clearStalePlacementRegion?: (maxAgeMs?: number, options?: {
1268
1264
  batchInFlightMs?: number;
1269
1265
  }) => boolean;
1270
- /** Pass-1 chain-size markers (see note/consumeChainSizeAppliedFill). */
1266
+ /** Pass-1 chain-size markers (see note/consumeChainSizeAppliedFillAmount). */
1271
1267
  _chainSizeAppliedFills?: Map<string, {
1272
1268
  filledInt: number;
1273
1269
  at: number;
1274
1270
  }>;
1275
1271
  noteChainSizeAppliedFill?: (orderId: string, filledInt: number, maxAgeMs?: number) => void;
1276
1272
  consumeChainSizeAppliedFillAmount?: (orderId: string, filledInt: number, maxAgeMs?: number) => number;
1277
- consumeChainSizeAppliedFill?: (orderId: string, filledInt: number, maxAgeMs?: number) => boolean;
1278
1273
  snapshotChainSizeAppliedFills?: () => Record<string, {
1279
1274
  filledInt: number;
1280
1275
  at: number;
@@ -221,6 +221,8 @@ not by the seven per-site structures that used to disagree
221
221
  - `INV-SYNC-008` SPREAD-typed fills resolve the real side
222
222
  - A SPREAD slot can carry an on-chain order (spread-correction activation). Fill processing must resolve the real BUY/SELL side (chain order type, pays asset, or price-vs-startPrice convention) before pushing the fill or computing the transition.
223
223
  - A SPREAD-typed fill would silently drop the `deriveTargetBoundary` shift and produce an illegal SPREAD+on-chain state rejected by `validateOrder`.
224
+ - The pays-asset mapping has ONE implementation (`order/fill_ledger.ts` `resolveTradedSide`, used by `_computeFillContext`, the unmatched-fill attribution and the queued pivot refresh). The SPREAD price fallback stays with the caller that owns the ladder (`resolveSpreadOrderSide`).
225
+ - `slot.type` is the ACCOUNTING side and is retagged to the traded side by a partial-fill transition (so `size` stays dimensionally consistent for `recalculateFunds`). It is NOT rail identity: a repair proof must also read the level's geometry (`geometryTypeForSlotIndex`), and a fill-retagged slot on the opposite rail is still wrong-side. See `docs/FILL_PIPELINE.md` INV-FILL-002/INV-FILL-006.
224
226
 
225
227
  ---
226
228
 
@@ -307,7 +309,9 @@ not by the seven per-site structures that used to disagree
307
309
  - SELL placements must use nearest available free slots first (ascending price).
308
310
 
309
311
  - `INV-RECON-006` Fresh-placement cancels are deferred for a grace window
310
- - A CANCEL action targeting an `orderId` placed within `TIMING.SURPLUS_CANCEL_GRACE_MS` (15 min) is deferred. The timestamp is written by the lifecycle write funnel (and by `recordOrderPlacement` for manager-shaped callers) into `manager._placedAt`, and tested by `isFreshlyPlacedOrder`.
312
+ - A CANCEL action targeting an `orderId` placed within `TIMING.SURPLUS_CANCEL_GRACE_MS` (15 min) is deferred. The timestamp is written only by the lifecycle write funnel into `manager._placedAt`, and tested by `isFreshlyPlacedOrder`.
313
+ - **Exemption (chain-observed wrong side).** A CANCEL for an order the correction queue holds as a chain-observed `typeMismatch` (`entry.typeMismatch === true` with a `chainOrderId`) is exempt: the chain already proved the side is wrong, so parking it adds a second 15-minute wait after the pre-batch drain deferred (active region) or failed. A plan-shaped CANCEL whose reason is `type-mismatch` is NOT exempt — it only proves master ≠ target, which is the stale-target lag this grace exists for. The exemption is a queue-provenance fact, not a grid blocker: see `docs/FILL_PIPELINE.md` INV-FILL-004.
314
+ - A queued `typeMismatch` entry stays valid while the level's stored type OR its rail geometry still disagrees with the chain side; a retagged `slot.type` alone is not a repair (INV-SYNC-008 / `docs/FILL_PIPELINE.md` INV-FILL-006).
311
315
  - `COWRebalanceEngine.execute` drops the whole slot's action group for a deferred cancel (dropping only the CANCEL would let a paired CREATE fold back into an UPDATE and re-materialize the placement), then re-syncs the deferred slots from master via `workingGrid.syncFromMaster` so the commit does not virtualize a still-live order.
312
316
  - Divergence correction (`applyGridDivergenceCorrections`) applies the same guard after dropping any queued committed-size UPDATE for the not-desired/size-0 slot.
313
317
  - `grid-load`/`grid-init` load contexts are excluded so restarts do not suppress the sweep.
@@ -1,7 +1,7 @@
1
1
  # DEXBot vs DEXBot2 — Detailed Comparison Report
2
2
 
3
3
  > **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
4
- > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.1).
4
+ > **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.7.2).
5
5
  > **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
6
6
 
7
7
  ---
@@ -36,7 +36,7 @@
36
36
 
37
37
  | Attribute | DEXBot (original) | DEXBot2 |
38
38
  |---|---|---|
39
- | **Release Track** | 1.0.0 | v1.7.1 |
39
+ | **Release Track** | 1.0.0 | v1.7.2 |
40
40
  | **Language** | Python 3.6+ | TypeScript 5.x |
41
41
  | **Status** | Released 1.0.0, unmaintained | Active development |
42
42
  | **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
@@ -776,10 +776,10 @@ Where:
776
776
 
777
777
  | Metric | DEXBot | DEXBot2 |
778
778
  |---|---|---|
779
- | **Release Track** | 1.0.0 | v1.7.1 |
779
+ | **Release Track** | 1.0.0 | v1.7.2 |
780
780
  | **Active Since** | ~2018 | December 2025 |
781
781
  | **Last Commit** | May 23, 2020 | 2026-11-04 |
782
- | **Total Commits** | 2281 | 2,492 (current HEAD, v1.7.1 line) |
782
+ | **Total Commits** | 2281 | 2,506 (current HEAD, v1.7.2 line) |
783
783
  | **Lines of Code** | ~10,846 Python LOC in `dexbot/` | Large TypeScript runtime + adapter + Claw + analysis + tests |
784
784
  | **Source Files** | 72 Python files in `dexbot/` | ~656 TS files across the repo |
785
785
  | **Test Files** | 16 Python test files | 367 `test_*.ts` files (350 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
package/docs/EVOLUTION.md CHANGED
@@ -2,14 +2,14 @@
2
2
 
3
3
  ## Executive Summary
4
4
 
5
- DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.1 release.
5
+ DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.7.2 stable release.
6
6
 
7
7
  ### Key Milestones
8
8
  - **Project Inception**: December 2, 2025
9
- - **Growth Phase**: 2,492 commits over ~9 active months
9
+ - **Growth Phase**: 2,506 commits over ~9 active months
10
10
  - **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
11
- - **Stability**: Progression from manual testing to a suite of 353 automated test files (14 live tests skipped)
12
- - **Releases**: 152 version entries in the changelog (v0.1.0 to v1.7.1)
11
+ - **Stability**: Progression from manual testing to a suite of 358 automated test files (live tests included in `test:live`)
12
+ - **Releases**: 153 changelog entries (v0.1.0 to v1.7.2)
13
13
 
14
14
  > **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
15
15
  > bug families, and lessons — lives in
@@ -177,12 +177,13 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
177
177
  | v1.6.16 → v1.6.17 | 11 | Last-fill direction guard, placeable-slot spread planning with named stalls, chain-truth funding + fill-anchored boundary re-anchor, owed-crawl consumption, restart auth-before-stop with cleared vault secret, pool-priced LP-share collateral, AMA slowPeriod/slope retune, BTS & per-token supply distribution analyzers |
178
178
  | v1.6.17 → v1.6.18 | 19 | Partial-fill re-anchor recovery (stale-evac skip, residual allow-list, crawl subsumption, rotation-only repair), rail-derived boundary + live fill/chain prices, edge-fill pivot exclusion, guard arity pinning with explicit re-arm, per-slot last-fill exclusion count, CLI `--flag=value` walker, `__test` seam guard, export-surface cleanup |
179
179
  | v1.6.18 → v1.7.0 | 11 | Liquidity depth chart + `dexbot liquid`/`liq`/`liqu`, `dexbot asset` supply distribution shortcut, pool id/pool-token chart targets + shared spawn runner, case-insensitive asset lookup, asset-report chain-request cuts, shared CLI terminal output, orphan-fill attribution + dark-level revive, stale-grid re-buy discipline, pivot clock provenance & read-time TTL |
180
+ | v1.7.1 → v1.7.2 | 13 | One fill contract + fill-pipeline ratchet, fail-closed grid-update blockers with bounded escalation, single fill identity (`fill_ledger`), credit-time fill-key claim with all-or-nothing balance credits, single-winner concurrent claim, removal of the duplicate applied-amount channel and the second grace-stamp writer, COW broadcast-region leak repair, chain-observed wrong-side cancel exemptions, fill side derived from the paid asset + rail-geometry repair check, fill-anchored rebuild/load boundary, spread rotation into orphaned rail slots, consecutive grid-blocked escalation counter, live-suite env fix |
180
181
  | v1.7.0 → v1.7.1 | 22 | One existence record per slot (life-cycle registry, unknown-is-never-gone), typed three-valued broadcast outcome, timing-window policy inventory, reconciliation interleaving fuzzer, one writer per life-cycle clock, serialized placement region with lease re-verification, fill-marker idempotency, forced-retreat gap evacuation + committed-geometry sweep, unknown-gap-geometry fix, replay-safe stranded-boundary repair, stability-ranked node selection + flap scoring, chain-account `<bot>` targets for `credit`/`order`, fee-adjusted pool depth chart with both spreads, atomic branch promotion preflight |
181
182
 
182
183
  ---
183
184
 
184
185
  **Report Originally Generated**: February 19, 2026
185
186
  **Last Updated**: November 4, 2026
186
- **Total Commits**: 2,492
187
+ **Total Commits**: 2,506
187
188
  **Date Range**: December 2, 2025 – November 4, 2026
188
189
  **Repository**: DEXBot2 (BitShares DEX Trading Bot)
@@ -805,4 +805,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
805
805
  **TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
806
806
 
807
807
  ---
808
- *Technical Reference for DEXBot2 v1.7.1 release*
808
+ *Technical Reference for DEXBot2 v1.7.2 release*
@@ -131,9 +131,9 @@ remain unchanged.
131
131
 
132
132
  **Fresh-placement grace (`TIMING.SURPLUS_CANCEL_GRACE_MS`, 15 min):** surplus
133
133
  and cancel-only cancellations also skip any order whose `orderId` was placed
134
- inside the grace window. The timestamp is written by the lifecycle write funnel
135
- (and by `recordOrderPlacement` for manager-shaped callers) into
136
- `manager._placedAt` and tested with `isFreshlyPlacedOrder`; the reconciler's CANCEL
134
+ inside the grace window. The timestamp is written only by the lifecycle write
135
+ funnel (`_syncLifecycleFromMutation` -> `markPlaced`) into `manager._placedAt`
136
+ and tested with `isFreshlyPlacedOrder`; the reconciler's CANCEL
137
137
  actions are filtered by `COWRebalanceEngine.execute`, which drops the whole slot's
138
138
  action group (a paired CANCEL+CREATE must not lose only its CANCEL, or the CREATE
139
139
  folds back into an UPDATE and re-materializes the placement) and re-syncs the
@@ -4,13 +4,13 @@
4
4
  > misbehaving (Part I) and the preserved **incident & fix ledger** (Part II), formerly
5
5
  > `CONSOLIDATED_ORPHAN_FIX_SUMMARY.md`.
6
6
  >
7
- > **Sources:** `CHANGELOG.md` v1.0.0 → v1.7.0 (plus the unreleased post-1.7.0 arc);
7
+ > **Sources:** `CHANGELOG.md` v1.0.0 → v1.7.1 (plus the post-1.7.1 arc);
8
8
  > `docs/GRID_PRICE_INVARIANT.md`; `docs/COW_INVARIANTS.md`; `docs/ORDER_LIFECYCLE.md`.
9
9
  > Generic terms only — no live markets, accounts, or order ids.
10
10
  >
11
- > **Scope / snapshot:** v1.0.0 → v1.7.0 (`5644aa3a`, 2026-11-02), extended through the
12
- > unreleased post-1.7.0 work at `84b935d9` (2026-11-04). §9 is the v1.6.4 → v1.6.17
13
- > addendum; §9.10 closes the v1.6.18 review pass and §9.11 carries v1.6.18 → unreleased.
11
+ > **Scope / snapshot:** v1.0.0 → v1.7.1 (`2a85a501`, 2026-11-04), extended through the
12
+ > post-1.7.1 work at `bc20d574` (2026-11-04). §9 is the v1.6.4 → v1.6.17
13
+ > addendum; §9.10 closes the v1.6.18 review pass and §9.11 carries v1.6.18 → v1.7.1.
14
14
  >
15
15
  > **Section numbering:** Part II deliberately keeps its original `§0`–`§8` numbers because
16
16
  > source-code comments and tests cite them (e.g. `… §2 fix #1`, `… §3 lineage`); §9 is a
@@ -49,7 +49,7 @@
49
49
  - 8. Provenance & supersession record
50
50
  - 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17) — addendum
51
51
  - 9.10 Review pass over v1.6.12 → v1.6.17 (findings P1–P5), released in v1.6.18
52
- - 9.11 v1.6.18 → unreleased: fill identity, absence and the geometry budget
52
+ - 9.11 v1.6.18 → v1.7.1: fill identity, absence and the geometry budget
53
53
  - A. Grid-Price Invariant — former failure trace (appendix)
54
54
 
55
55
  ---
@@ -568,17 +568,17 @@ Original doc regression excerpts preserved: GAP P6 A/B/C; LADDER §2.8 checks (1
568
568
  - [x] No other doc/index lists the four (verified 2026-08-31); `analysis/README.md` documents the `grid_correction_check` tool.
569
569
  - [x] Stale `*.md` filename references in code comments/tests updated to the consolidated doc (9 module files, 6 test files), then re-pointed to this hub when it absorbed the summary.
570
570
 
571
- *Generated 2026-08-31 from the 4 test-only docs at their HEAD contents; statuses corrected against `test` HEAD `a54863ca` the same day, then refreshed against `1382f267` (2026-09-13), extended through v1.6.14 at `f6c0df32` (2026-10-12), through v1.6.17 at `78ccbb8e`, through the v1.6.18 review pass (`§9.10`: `f4d6da8c`, `a2bf6ba5`, `56481b16`, `3d16f9e4`), and through v1.7.0 + the unreleased post-1.7.0 arc (`§9.11`, HEAD `84b935d9`). Landed/reverted/superseded annotations carry commit hashes where known; **line references in §§1-4 were re-verified at `a54863ca` and are subject to drift** — treat them as pointers, not assertions. The GRID-PRICE-INVARIANT guard is **BLOCKING** at all six emission sites (CREATE / UPDATE / CREATE-FALLBACK in `modules/dexbot_cow_runtime.ts`, RECONCILE-CREATE / RECONCILE-UPDATE / STARTUP-CREATE in `modules/order/grid_reconcile_internal.ts`): an off-grid emission is skipped, not merely counted, so a `violated>0` line means an emission was *prevented* rather than a writer merely *pinned*. Counters are still reported (`site=`, `checked=`, `violated=`, `unchecked=`) for observability — see `docs/GRID_PRICE_INVARIANT.md`.*
571
+ *Generated 2026-08-31 from the 4 test-only docs at their HEAD contents; statuses corrected against `test` HEAD `a54863ca` the same day, then refreshed against `1382f267` (2026-09-13), extended through v1.6.14 at `f6c0df32` (2026-10-12), through v1.6.17 at `78ccbb8e`, through the v1.6.18 review pass (`§9.10`: `f4d6da8c`, `a2bf6ba5`, `56481b16`, `3d16f9e4`), and through v1.7.1 at `2a85a501` plus the post-1.7.1 arc (`§9.11`, HEAD `bc20d574`). Landed/reverted/superseded annotations carry commit hashes where known; **line references in §§1-4 were re-verified at `a54863ca` and are subject to drift** — treat them as pointers, not assertions. The GRID-PRICE-INVARIANT guard is **BLOCKING** at all six emission sites (CREATE / UPDATE / CREATE-FALLBACK in `modules/dexbot_cow_runtime.ts`, RECONCILE-CREATE / RECONCILE-UPDATE / STARTUP-CREATE in `modules/order/grid_reconcile_internal.ts`): an off-grid emission is skipped, not merely counted, so a `violated>0` line means an emission was *prevented* rather than a writer merely *pinned*. Counters are still reported (`site=`, `checked=`, `violated=`, `unchecked=`) for observability — see `docs/GRID_PRICE_INVARIANT.md`.*
572
572
 
573
573
  ---
574
574
 
575
575
  ### 9. COW Broadcast, Resync & Geometry Safety (v1.6.4 → v1.6.17)
576
576
 
577
577
  > **Source:** `CHANGELOG.md` v1.6.4 → v1.6.17 · **Snapshot:** `78ccbb8e` (v1.6.17 tag);
578
- > §9.10 and §9.11 extend past it — §9.10 released in v1.6.18, §9.11 unreleased to HEAD
579
- > `84b935d9`.
578
+ > §9.10 and §9.11 extend past it — §9.10 released in v1.6.18; §9.11 released in v1.7.1,
579
+ > with the post-1.7.1 additions at HEAD `bc20d574`.
580
580
  > Extends the §§1–8 ledger; the `§0`–`§8` numbers are unchanged (code and tests cite them).
581
- > The ledger labels each row with its release; `unreleased` means "in no tag yet".
581
+ > The ledger labels each row with its release; `post-1.7.1` means after the v1.7.1 tag.
582
582
 
583
583
  Sections 1–4 end with the prevention sweeps reverted: a cancel sweep on ambiguous evidence
584
584
  proved worse than the orphan it targets. The post-1.6.3 arc is the constructive inverse —
@@ -668,7 +668,7 @@ fail-closed behind `_assertGenesisInvariant`. This is R4's "removing writers and
668
668
  truth" carried to its end: the no-ladder state that Appendix A's `slot.price` corruption
669
669
  required is no longer reachable at runtime.
670
670
 
671
- #### 9.5 Ledger (order-engine commits, v1.6.4 → v1.7.0 + unreleased)
671
+ #### 9.5 Ledger (order-engine commits, v1.6.4 → v1.7.1 + post-1.7.1)
672
672
 
673
673
  | Commit | Release | Change |
674
674
  |---|---|---|
@@ -713,18 +713,24 @@ required is no longer reachable at runtime.
713
713
  | `a93f7eef` | 1.7.0 | Stale-grid re-buys: unsettled-fill gate, attribution, same-level refusal (§9.11.1) |
714
714
  | `8705381b` | 1.7.0 | Orphan-fill attribution by price; dark-level revive (§9.11.1) |
715
715
  | `8aff50bb` | 1.7.0 | Anchor-aware residual allow-list, pivot clock provenance, read-time TTL (§9.11.2) |
716
- | `c493a604` | unreleased | Stranded-boundary repair without re-arming on replays (§9.11.3) |
717
- | `ed52f9ef` | unreleased | Exclusive placement region; no create-only re-plan after a rebuild (§9.11.3) |
718
- | `970fedfd` | unreleased | Remaining placement races; fill-accounting double-apply |
719
- | `ad081e3d` | unreleased | Placement lifecycle + fill-marker idempotency |
720
- | `7a3571a4` | unreleased | Follow-up gaps: one teardown, one lease check, one pending-broadcast policy |
721
- | `94223d19` | unreleased | Re-verify the placement lease before a region holder broadcasts |
722
- | `8bab9881` | unreleased | Unknown gap geometry is not gap 0 |
723
- | `4d5e3d81` | unreleased | Forced retreats evacuate, then re-plan the committed band |
724
- | `7618f299` | unreleased | Cancel teeth may not destroy the rotation that evacuates |
725
- | `826d84a3` | unreleased | Chain existence unified behind the lifecycle registry (§9.11.3) |
726
- | `7252d7d3` | unreleased | Broadcast uncertainty as a typed three-valued outcome (§9.11.3) |
727
- | `84b935d9` | unreleased | One writer per life-cycle clock, one guard per absence decision (§9.11.3) |
716
+ | `c493a604` | 1.7.1 | Stranded-boundary repair without re-arming on replays (§9.11.3) |
717
+ | `ed52f9ef` | 1.7.1 | Exclusive placement region; no create-only re-plan after a rebuild (§9.11.3) |
718
+ | `970fedfd` | 1.7.1 | Remaining placement races; fill-accounting double-apply |
719
+ | `ad081e3d` | 1.7.1 | Placement lifecycle + fill-marker idempotency |
720
+ | `7a3571a4` | 1.7.1 | Follow-up gaps: one teardown, one lease check, one pending-broadcast policy |
721
+ | `94223d19` | 1.7.1 | Re-verify the placement lease before a region holder broadcasts |
722
+ | `8bab9881` | 1.7.1 | Unknown gap geometry is not gap 0 |
723
+ | `4d5e3d81` | 1.7.1 | Forced retreats evacuate, then re-plan the committed band |
724
+ | `7618f299` | 1.7.1 | Cancel teeth may not destroy the rotation that evacuates |
725
+ | `826d84a3` | 1.7.1 | Chain existence unified behind the lifecycle registry (§9.11.3) |
726
+ | `7252d7d3` | 1.7.1 | Broadcast uncertainty as a typed three-valued outcome (§9.11.3) |
727
+ | `84b935d9` | 1.7.1 | One writer per life-cycle clock, one guard per absence decision (§9.11.3) |
728
+ | `3edf8cb3` | post-1.7.1 | Release leaked broadcast regions; cancel wrong-side fills |
729
+ | `6afa0c4b` | post-1.7.1 | Fill side from the paid asset at every call site; backlog coalescing |
730
+ | `cb1041b6` | post-1.7.1 | Never park a chain-observed wrong-side cancel; the repair proof checks rail geometry |
731
+ | `b2f43d8a` | post-1.7.1 | One fill contract, fail-closed grid blockers, one fill identity (P0–P2) |
732
+ | `39675d8a` | post-1.7.1 | Claim the fill key at credit time; drop the duplicate amount channel (P2 tail) |
733
+ | `bc20d574` | post-1.7.1 | One grace-stamp writer, ledger side in export, single-winner fill claim |
728
734
 
729
735
  #### 9.6 Invariants added
730
736
 
@@ -905,7 +911,7 @@ extraction) · `56481b16` (P5) · `3d16f9e4` (this document, the doc-level invar
905
911
  and the log rows it cites). **Released in v1.6.18:** the review pass itself carried no
906
912
  version bump, but every commit above is an ancestor of the `v1.6.18` tag (2026-11-01).
907
913
 
908
- #### 9.11 v1.6.18 → unreleased: fill identity, absence and the geometry budget
914
+ #### 9.11 v1.6.18 → v1.7.1: fill identity, absence and the geometry budget
909
915
 
910
916
  The post-1.6.17 work stopped asking "which guard is missing?" and started asking
911
917
  "which *identity* is the code using?". Three answers landed: a fill is identified
@@ -962,7 +968,7 @@ Three defects of the same shape:
962
968
  Price, side and clock now travel as one row, and the TTL is enforced where the reference
963
969
  is **read**; an unknown age never expires.
964
970
 
965
- ##### 9.11.3 Absence gets one record; repairs must reduce the violation (unreleased)
971
+ ##### 9.11.3 Absence gets one record; repairs must reduce the violation (v1.7.1)
966
972
 
967
973
  Chain existence used to be answered by seven structures with seven clocks
968
974
  (`_pendingBroadcasts`, `createUncertain`, `_committedOrderIds`,
@@ -973,12 +979,14 @@ the bug reappeared at the next.
973
979
 
974
980
  `modules/order/lifecycle.ts` (`826d84a3`, `7252d7d3`, `84b935d9`) now owns one
975
981
  record per slot: a six-phase vocabulary in which `unknown` is a real state (a
976
- lost receipt is *not* an absence), a monotonic evidence rank, and every clock
977
- recorded once. The legacy maps survive as live views, so no call site had to be
978
- rewritten to get one truth. Three rules fall out of it: one absence guard
979
- (`isInFlight()`, time-bounded), one teardown authority for a hung region
980
- (`_clearStalePlacementRegion`, `7a3571a4`), and one pending-broadcast liveness
981
- policy (`getLivePendingBroadcasts`).
982
+ lost receipt is *not* an absence), a monotonic evidence rank, and every existence
983
+ clock recorded once. The legacy maps survive as live views, so no call site had
984
+ to be rewritten to get one truth. The persisted `createUncertain` flag is still
985
+ read as evidence; `_lastUnmatchedChainOrders` remains a chain-diff cache for
986
+ orphan diagnostics, not an existence answer. Three rules fall out of it: one
987
+ absence guard (`isInFlight()`, time-bounded), one teardown authority for a hung
988
+ region (`_clearStalePlacementRegion`, `7a3571a4`), and one pending-broadcast
989
+ liveness policy (`getLivePendingBroadcasts`).
982
990
 
983
991
  Geometry gained the matching rule. A boundary writer may move the boundary only
984
992
  when the move strands **strictly fewer** placed orders than the committed value