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.
- package/CHANGELOG.md +28 -0
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/dist/modules/account_bots.d.ts +1 -0
- package/dist/modules/account_bots.js +7 -5
- package/dist/modules/constants.d.ts +2 -0
- package/dist/modules/constants.js +16 -2
- package/dist/modules/dexbot_class.d.ts +22 -0
- package/dist/modules/dexbot_class.js +30 -0
- package/dist/modules/dexbot_cow_runtime.d.ts +31 -1
- package/dist/modules/dexbot_cow_runtime.js +68 -56
- package/dist/modules/dexbot_maintenance_runtime.d.ts +1 -1
- package/dist/modules/dexbot_maintenance_runtime.js +33 -6
- package/dist/modules/node_flap_score.d.ts +6 -6
- package/dist/modules/node_flap_score.js +6 -6
- package/dist/modules/order/accounting.d.ts +9 -4
- package/dist/modules/order/accounting.js +89 -26
- package/dist/modules/order/async_lock.d.ts +7 -1
- package/dist/modules/order/async_lock.js +7 -1
- package/dist/modules/order/export.js +25 -18
- package/dist/modules/order/fill_ledger.d.ts +99 -0
- package/dist/modules/order/fill_ledger.js +103 -0
- package/dist/modules/order/grid.d.ts +75 -18
- package/dist/modules/order/grid.js +207 -61
- package/dist/modules/order/grid_reconcile_internal.js +16 -4
- package/dist/modules/order/index.d.ts +14 -5
- package/dist/modules/order/index.js +5 -5
- package/dist/modules/order/lifecycle.js +3 -3
- package/dist/modules/order/manager.d.ts +15 -24
- package/dist/modules/order/manager.js +40 -27
- package/dist/modules/order/sync_engine.d.ts +66 -118
- package/dist/modules/order/sync_engine.js +118 -162
- package/dist/modules/order/utils/math.d.ts +7 -3
- package/dist/modules/order/utils/math.js +7 -3
- package/dist/modules/order/utils/order.d.ts +40 -41
- package/dist/modules/order/utils/order.js +110 -84
- package/dist/modules/order/utils/system.d.ts +81 -6
- package/dist/modules/order/utils/system.js +167 -29
- package/dist/modules/timing_policy.js +2 -2
- package/dist/modules/types.d.ts +22 -27
- package/docs/COW_INVARIANTS.md +5 -1
- package/docs/DEXBOT_COMPARISON.md +4 -4
- package/docs/EVOLUTION.md +6 -5
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +1 -1
- package/docs/GRID_RECONCILE.md +3 -3
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +38 -30
- package/docs/README.md +1 -1
- package/docs/architecture.md +26 -8
- package/modules/README.md +3 -0
- 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 (
|
|
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:
|
|
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
|
|
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,
|
|
74
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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}
|
|
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: '
|
|
173
|
-
removal: 'Delete
|
|
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
|
/**
|
package/dist/modules/types.d.ts
CHANGED
|
@@ -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/
|
|
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;
|
package/docs/COW_INVARIANTS.md
CHANGED
|
@@ -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
|
|
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.
|
|
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.
|
|
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.
|
|
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,
|
|
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.
|
|
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,
|
|
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
|
|
12
|
-
- **Releases**:
|
|
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,
|
|
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.
|
|
808
|
+
*Technical Reference for DEXBot2 v1.7.2 release*
|
package/docs/GRID_RECONCILE.md
CHANGED
|
@@ -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
|
|
135
|
-
(
|
|
136
|
-
|
|
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.
|
|
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.
|
|
12
|
-
>
|
|
13
|
-
> addendum; §9.10 closes the v1.6.18 review pass and §9.11 carries v1.6.18 →
|
|
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 →
|
|
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.
|
|
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
|
|
579
|
-
> `
|
|
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; `
|
|
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.
|
|
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` |
|
|
717
|
-
| `ed52f9ef` |
|
|
718
|
-
| `970fedfd` |
|
|
719
|
-
| `ad081e3d` |
|
|
720
|
-
| `7a3571a4` |
|
|
721
|
-
| `94223d19` |
|
|
722
|
-
| `8bab9881` |
|
|
723
|
-
| `4d5e3d81` |
|
|
724
|
-
| `7618f299` |
|
|
725
|
-
| `826d84a3` |
|
|
726
|
-
| `7252d7d3` |
|
|
727
|
-
| `84b935d9` |
|
|
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 →
|
|
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 (
|
|
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
|
|
977
|
-
recorded once. The legacy maps survive as live views, so no call site had
|
|
978
|
-
rewritten to get one truth.
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
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
|