feat(offline): port DAWG cursor + move generator to TS (parity-pinned)
CI / changes (pull_request) Successful in 1s
CI / unit (pull_request) Successful in 10s
CI / integration (pull_request) Successful in 15s
CI / ui (pull_request) Successful in 1m8s
CI / conformance (pull_request) Successful in 9s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m38s

First engine-first step of PWA offline mode (Phase A): the client-side move
generator — the "robot brain" a local vs_ai game will run on-device — with no
runtime wiring yet (Phase B).

- dawg.ts: add the step-by-step cursor (root/final/next/arcs), a faithful port
  of dafsa traverse.go over the reader's existing bitstream.
- generate.ts: the Appel-Jacobson generator (leftPart/extendRight + cross-sets +
  counts-rack + board transpose + moveKey ranking), reusing the cursor and
  validate.ts evaluate/connected. A cross-set LetterSet is a Uint8Array, so the
  33-letter Russian alphabet (index 32) is exact under JS bit ops.
- validate.ts: export connected for the generator's connectivity filter.
- backend/cmd/movegen: dev tool building small sample dictionaries and emitting
  golden move-generation fixtures from the real Go solver (EN + RU).
- tests: dawg.cursor.test.ts (enumeration bijection vs indexOf) and
  generate.parity.test.ts (7/7 vs the Go solver: empty board, mid-game, blank,
  single-word rule, Russian index-32 cross-set). The committed EN sample also
  unblocks the existing skipped dawg.parity.test.ts once wired with DICT_* in CI.

Pure additive library code; no runtime behavior change.
This commit is contained in:
Ilia Denisov
2026-07-06 01:35:11 +02:00
parent 3a85f64726
commit c334a9d7b7
12 changed files with 12195 additions and 2 deletions
+79
View File
@@ -95,6 +95,85 @@ export class Dawg {
return this.indexOf(word) >= 0;
}
// --- Step-by-step traversal (the move generator's primitive) ---------------
//
// A `Node` is a bit offset into the graph; 0 denotes the root (which resolves
// to firstNodeOffset). These mirror dafsa's traverse.go Cursor (Root/Final/
// Next/Arcs) over the same bitstream this reader already decodes, so the ported
// generator can drive the automaton one transition at a time. Single-threaded
// JS shares this reader's position across calls; every method re-seeks to its
// node on entry, and arcs brackets the callback with a save/restore, so nested
// use during a walk is safe. Mirrors dafsa (*Cursor).
/** root returns the start state of the automaton. */
root(): number {
return 0;
}
/** final reports whether node is an accepting state (a stored word ends there). */
final(node: number): boolean {
if (this.numEdges <= 0) {
return this.hasEmptyWord && node === 0;
}
this.p = node === 0 ? this.firstNodeOffset : node;
return this.readBits(1) === 1;
}
/**
* next follows the edge labelled ch (an alphabet index) from node, returning the
* destination node, or -1 when no such edge exists.
*/
next(node: number, ch: number): number {
return this.getEdge(node, ch) ? this.eNode : -1;
}
/**
* arcs calls fn for each out-edge of node in ascending label order, passing the
* edge's label, its destination node and whether that destination is accepting.
* It stops early if fn returns false. Mirrors dafsa (*Cursor).Arcs.
*/
arcs(node: number, fn: (label: number, dest: number, final: boolean) => boolean): void {
if (this.numEdges <= 0) {
return;
}
this.p = node === 0 ? this.firstNodeOffset : node;
this.readBits(1); // node final flag — not needed here
const fallthrough = this.readBits(1);
if (fallthrough === 1) {
const label = this.readBits(this.cbits);
// The reader now sits at the destination node, whose first bit is its final flag.
const dest = this.p;
const final = this.readBits(1) === 1;
fn(label, dest, final);
return;
}
const nskiplen = bitsLen(this.wbits);
let nskip = 0;
let numEdges = 1;
if (this.readBits(1) !== 1) {
// not a single edge
numEdges = this.readUnsigned();
nskip = this.readBits(nskiplen);
}
for (let i = 0; i < numEdges; i++) {
const label = this.readBits(this.cbits);
if (i > 0) {
this.readBits(nskip); // per-edge skip count, unused for traversal
}
const dest = this.readBits(this.abits);
const resume = this.p;
this.p = dest;
const final = this.readBits(1) === 1;
if (!fn(label, dest, final)) {
return;
}
this.p = resume;
}
}
// getEdge resolves the outgoing edge for ch from the node at the given bit
// offset. On success it fills eNode/eCount/eFinal and returns true. Mirrors
// dafsa (*dawg).getEdge.