diff --git a/CMakeLists.txt b/CMakeLists.txt index 00b96241f..00d1d719a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1441,6 +1441,14 @@ add_dependencies(onebit npu_answer_parser_test) add_executable(batch_check_compare_test tests/batch_check_compare_test.cpp) target_include_directories(batch_check_compare_test PRIVATE npu/forward/include) add_test(NAME batch_check_compare COMMAND batch_check_compare_test) + +# engine#1780: the DFlash draft block's acceptance arithmetic -- tokens = accepted + bonus, the break-even rule, and the +# published OGA-route counts as known answers. Header-only and host-only: no container, no device, no NPU runtime, so it +# runs wherever this file is built. Registered at top level with the same hook as the row above, for the same reason. +add_executable(dflash_accept_test tests/dflash_accept_test.cpp) +target_include_directories(dflash_accept_test PRIVATE npu/forward/include) +add_test(NAME dflash_accept COMMAND dflash_accept_test) +add_dependencies(onebit dflash_accept_test) # direction B (tools/ci/ci_targets_check.py): a target ci.yml's --target list does not name is "never built", and ci.yml # is a workflow file no lane can patch. The documented hook is the one onebit_npu_forward_syntax uses. add_dependencies(onebit batch_check_compare_test) diff --git a/npu/forward/include/dflash_accept.h b/npu/forward/include/dflash_accept.h new file mode 100644 index 000000000..b53018ed1 --- /dev/null +++ b/npu/forward/include/dflash_accept.h @@ -0,0 +1,72 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// engine#1780: what a DFlash draft block has to clear before it is worth running. +// +// A speculative round offers `k` drafted positions behind one verify pass and yields the positions the target accepted +// plus the one token the verify pass commits past them: `tokens = accepted + bonus`. With `rounds` rounds that is +// +// tokens_per_round = (accepted + bonus) / rounds +// +// and the round costs `cost_steps` ordinary decode steps, so the draft pays only while `tokens_per_round > cost_steps`. +// A one-pass round (verify only) costs ~1.05 steps and a two-pass round (`mtp::run`: verify, then the step that consumes +// the committed token) costs ~2.05, both measured on the OGA route (docs/oga-drafter-path.md). That is why the same +// acceptance can be a pass in one round shape and a fail in the other, and why this is a function rather than a number. +// +// The `bonus` is not always one per round: when the sequence ends, the final round(s) commit no extra token. Measured on +// the OGA route at k=4 and k=7, the shortfall is 2, 2 and 4 rounds of the 54/46/47 -- which is exactly the difference +// between the ideal `1 + accepted/round` and the published 2.963 / 3.478 / 3.404. Carrying `bonus` explicitly keeps that +// visible instead of hiding it in a rounding difference. +#ifndef ONEBIT_NPU_DFLASH_ACCEPT_H +#define ONEBIT_NPU_DFLASH_ACCEPT_H + +#include + +namespace onebit { +namespace dflash { + +/* Accepted positions per offered draft, the draft's own quality: 108/216 = 0.5 at k=4 on the OGA route. */ +inline double per_position_acceptance(std::int64_t accepted, std::int64_t offered) { + if (offered <= 0) return 0.0; + return static_cast(accepted) / static_cast(offered); +} + +/* Tokens a round yields: the accepted positions plus the tokens the verify pass commits past them. */ +inline double tokens_per_round(std::int64_t accepted, std::int64_t bonus, std::int64_t rounds) { + if (rounds <= 0) return 0.0; + return static_cast(accepted + bonus) / static_cast(rounds); +} + +/* The ideal form, `1 + accepted/round`, which assumes every round earns its bonus. Only for comparison: a measured + * round whose sequence ended early is lower, and the difference is the shortfall below, not noise. */ +inline double ideal_tokens_per_round(std::int64_t accepted, std::int64_t rounds) { + if (rounds <= 0) return 0.0; + return 1.0 + static_cast(accepted) / static_cast(rounds); +} + +/* Rounds that committed no extra token -- the sequence-ending rounds. 0 for an ideal run. */ +inline std::int64_t bonus_shortfall(std::int64_t rounds, std::int64_t bonus) { + return rounds > bonus ? rounds - bonus : 0; +} + +/* The break-even rule. `cost_steps` is the round's cost in ordinary decode steps (1.05 one pass, 2.05 two). */ +inline bool pays(double tokens_per_round_value, double cost_steps) { + return tokens_per_round_value > cost_steps; +} + +} // namespace dflash +} // namespace onebit + +#endif // ONEBIT_NPU_DFLASH_ACCEPT_H diff --git a/tests/dflash_accept_test.cpp b/tests/dflash_accept_test.cpp new file mode 100644 index 000000000..43361a8cd --- /dev/null +++ b/tests/dflash_accept_test.cpp @@ -0,0 +1,80 @@ +// Copyright 2026 bong-water-water-bong +// SPDX-License-Identifier: Apache-2.0 +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// engine#1780: known answers for the draft block's acceptance arithmetic, taken from the OGA-route measurement rather +// than invented. The three rows are docs/oga-drafter-path.md's counts: k=4 over 54 rounds, and k=7 over two replays. +// Host-only: no container, no device, no NPU runtime -- so it runs wherever this file is built. +#include "dflash_accept.h" + +#include +#include +#include + +namespace df = onebit::dflash; + +static int failures = 0; + +static void check(bool ok, const std::string& what) { + if (!ok) { + ++failures; + std::printf("FAIL %s\n", what.c_str()); + } +} + +static bool near(double a, double b) { return std::fabs(a - b) < 5e-4; } + +int main() { + /* The three measured rows. `tokens` is what the tool printed; `accepted` is the drafts the target took. */ + struct Row { int k; std::int64_t offered, rounds, accepted, tokens; double want_train; }; + const Row rows[] = { + {4, 216, 54, 108, 160, 2.963}, + {7, 322, 46, 116, 160, 3.478}, + {7, 329, 47, 117, 160, 3.404}, + }; + for (const Row& r : rows) { + const std::int64_t bonus = r.tokens - r.accepted; + const double tpr = df::tokens_per_round(r.accepted, bonus, r.rounds); + check(near(tpr, r.want_train), + "accept: k=" + std::to_string(r.k) + " reproduces the published tokens/round (" + std::to_string(tpr) + ")"); + /* tokens = accepted + bonus is exact, so the shortfall is exactly the rounds that ended the sequence. */ + check(r.accepted + bonus == r.tokens, "accept: tokens == accepted + bonus (the decomposition is exact)"); + const std::int64_t shortfall = df::bonus_shortfall(r.rounds, bonus); + const double ideal = df::ideal_tokens_per_round(r.accepted, r.rounds); + check(near(ideal - static_cast(shortfall) / static_cast(r.rounds), tpr), + "accept: the gap from the ideal form is exactly shortfall/rounds, not rounding"); + check(shortfall > 0 && shortfall <= 4, + "accept: and the shortfall is a handful of sequence-ending rounds (" + std::to_string(shortfall) + ")"); + } + + /* Per-position acceptance, the draft's own quality: 0.5 at k=4, ~0.36 at k=7. */ + check(near(df::per_position_acceptance(108, 216), 0.5), "accept: 108 of 216 offers is 0.5 per position"); + check(near(df::per_position_acceptance(116, 322), 0.3602), "accept: 116 of 322 is 0.3602"); + + /* The break-even rule, and the case that makes it a function: the same acceptance passes one round shape and + * fails the other. 2.963 tokens/round against 1.05 steps pays; against 2.05 it barely pays; a draft at 1.5 does not. */ + check(df::pays(3.000, 1.05), "accept: 3.0 tokens/round pays for a one-pass round (1.05 steps)"); + check(df::pays(3.000, 2.05), "accept: 3.0 tokens/round also pays for a two-pass round (2.05 steps)"); + check(!df::pays(1.500, 2.05), "accept: 1.5 tokens/round does NOT pay for a two-pass round -- the distinction"); + check(df::pays(1.500, 1.05), "accept: but it does pay for a one-pass round"); + /* A drafter that accepts nothing is the identity, 1.0 token/round, and must never be reported as a win. */ + check(near(df::tokens_per_round(0, 54, 54), 1.0), "accept: a drafter that accepts nothing gives 1.0 token/round"); + check(!df::pays(1.0, 1.0), "accept: and 1.0 does not pay for a round that costs a step (the rule is strict)"); + /* Degenerate inputs are answers, not crashes: a forward can be handed a zero-length run. */ + check(df::tokens_per_round(0, 0, 0) == 0.0 && df::per_position_acceptance(0, 0) == 0.0 && df::bonus_shortfall(0, 0) == 0, + "accept: zero rounds, zero offers and zero bonus are answers rather than division by zero"); + + if (failures == 0) std::printf("dflash accept: all checks passed\n"); + return failures == 0 ? 0 : 1; +}