mons-web 0.1.134 → 0.2.0

package/README.md

@@ -1,53 +1,88 @@
-# mons-rust
-
-`cargo add mons-rust`
-
-or
-
-`npm install mons-rust`
-
-## Automove
-
-Docs:
-
-- runbook: `HOW_TO_ITERATE_ON_AUTOMOVE.md`
-- next mechanism: `AUTOMOVE_IDEAS.md`
-- durable evidence and lessons: `docs/automove-knowledge.md`
-
-Shipping surface:
-
-- Fast and Normal retain shipping search; Pro uses the promoted bounded tactical policy
-- complete independently cold selector calls must remain below `700ms`
-
-Experiments use a small candidate-specific `#[cfg(test)]` harness:
-
-- `cargo test --release --lib <test_name> -- --ignored --nocapture --test-threads=1`
-- `./scripts/check-automove-hygiene.sh`
-
-## Real-player complete games
-
-The immutable, move-only corpus of 1,527 complete games played by real players is
-documented in [test-data/complete-games/v1](https://github.com/supermetalmons/mons-rust/tree/main/test-data/complete-games/v1).
-It is repository research data, not part of the Rust or npm package surface. Run
-`node ./scripts/check-complete-games.cjs` to verify its pinned bytes and schema.
-
-## Rules Tests
-
-Runner:
-
-- `./scripts/run-rules-tests.sh`
-- `./scripts/run-rules-tests.sh --limit 100`
-- `./scripts/run-rules-tests.sh --log /tmp/rules-tests.log`
-
-The checked-in corpus is `test-data/rules-regressions.jsonl.gz`. Its manifest records
-the deterministic 10,000-case selection policy, source archive hashes, coverage, and
-artifact hashes. The runner verifies the complete stream even when `--limit` executes
-only a prefix.
-
-## Publishing
-
-- Set the release version in `Cargo.toml` and regenerate `Cargo.lock`, then commit the
-  complete release change set. Publishing requires a clean worktree.
-- Run `./publish.sh --check-only` for the complete rules, Rust, release-gate, Wasm,
-  public-surface, cold-route, and npm-size validation without publishing.
-- Run `./publish.sh` only after the check-only path passes and the release commit is clean.
+# Mons TypeScript engine
+
+The Mons rules engine is implemented in strict TypeScript and distributed as two
+dependency-free npm packages:
+
+- `mons-web` is an ES module for browsers and bundlers.
+- `mons-rust` is the existing CommonJS package for Node.js. Its historical package
+  name is unchanged for compatibility.
+
+Both packages expose the same 23 named game APIs and the same TypeScript declarations.
+
+```ts
+import { GameVariant, MonsGameModel } from "mons-web";
+
+const game = MonsGameModel.new(GameVariant.Classic);
+const output = game.process_input_fen("l10,5;l9,4");
+```
+
+```js
+const { GameVariant, MonsGameModel } = require("mons-rust");
+
+const game = MonsGameModel.new(GameVariant.Classic);
+```
+
+## Migrating `mons-web` initialization
+
+`mons-web` no longer has a default initializer or an `initSync` export. Remove the
+default import and initialization call; named imports are ready to use immediately.
+The generated `InitInput`, `SyncInitInput`, and `InitOutput` TypeScript types are
+removed with those loaders.
+
+```diff
+-import initMonsWeb, { MonsGameModel } from "mons-web";
+-await initMonsWeb();
++import { MonsGameModel } from "mons-web";
+```
+
+The named API is otherwise preserved, including enum values, FEN formats, model
+classes, event ordering, random automoves, and smart-automove preferences.
+
+Incoming strings retain the previous runtime normalization: unpaired UTF-16
+surrogates become U+FFFD before parsing or echoing. One intentional error-policy
+change applies to malformed data: native `RuntimeError("unreachable")` traps from
+invalid UTF-8 slice boundaries or genuine board/location bounds failures are
+deterministic TypeScript `RangeError`s. Wrapped location indices that resolve inside
+the board remain compatible aliases.
+
+Published JavaScript targets ES2020. The Node package uses Node's built-in performance
+and cryptographic-random services directly; the browser package uses the corresponding
+`globalThis` APIs. Node.js 22.13 through 22.x, or Node.js 24 or newer, is required
+only for repository development and release tooling.
+
+## Validation
+
+Install the workspace with Node.js 22.13 through 22.x, or Node.js 24 or newer, and
+run the standard checks:
+
+```sh
+npm ci --engine-strict
+npm run format:check
+npm run lint
+npm run typecheck
+npm run build
+npm test
+npm run test:automove-parity
+```
+
+Run `./scripts/run-rules-tests.sh` with no options to replay the deterministic
+compressed stream of 699,994 canonical unique rules transitions recovered from
+699,999 historical raw fixtures. The command validates and streams the corpus without
+unpacking or rewriting it.
+
+Run `node ./scripts/check-complete-games.cjs` to validate the immutable public corpus
+of 1,527 complete real-player games. Run `npm run test:complete-games` to replay all
+25,185 turns and 169,480 inputs through the TypeScript engine across all 12 variants.
+
+## Release
+
+Run `./publish.sh --check-only` to execute the complete Node-only validation, build
+both package tarballs, and perform npm dry runs without publishing. Publishing is an
+explicit release operation: run `./publish.sh` from a clean worktree only when both
+packages should be released to the `latest` tag.
+
+A real publish acquires the transient `mons-npm-publish-lock` tag on `origin`, or on
+the shared remote named by `MONS_PUBLISH_LOCK_REMOTE`. All publishers must use this
+script and the same remote for the lock to serialize releases across hosts. If a
+process terminates without releasing the tag, the script prints inspection and
+lease-protected stale-lock recovery commands.

package/mons-web.d.ts

@@ -10,52 +10,27 @@
 export function winner(fen_w: string, fen_b: string, flat_moves_string_w: string, flat_moves_string_b: string): string;
 /**
 */
-export enum GameVariant {
-  Classic = 0,
-  SwappedManaRows = 1,
-  OffsetArcManaRows = 2,
-  CenterSpokeManaRows = 3,
-  AlternatingManaRows = 4,
-  InnerWedgeManaRows = 5,
-  OuterWedgeManaRows = 6,
-  BentCenterManaRows = 7,
-  OuterEdgeManaRows = 8,
-  SplitFlankManaRows = 9,
-  ForwardBridgeManaRows = 10,
-  CornerChainManaRows = 11,
-}
-/**
-*/
-export enum MonKind {
-  Demon = 0,
-  Drainer = 1,
-  Angel = 2,
-  Spirit = 3,
-  Mystic = 4,
-}
-/**
-*/
-export enum Modifier {
-  SelectPotion = 0,
-  SelectBomb = 1,
-  Cancel = 2,
-}
-/**
-*/
-export enum OutputModelKind {
-  InvalidInput = 0,
-  LocationsToStartFrom = 1,
-  NextInputOptions = 2,
-  Events = 3,
-}
-/**
-*/
-export enum ItemModelKind {
-  Mon = 0,
-  Mana = 1,
-  MonWithMana = 2,
-  MonWithConsumable = 3,
-  Consumable = 4,
+export enum EventModelKind {
+  MonMove = 0,
+  ManaMove = 1,
+  ManaScored = 2,
+  MysticAction = 3,
+  DemonAction = 4,
+  DemonAdditionalStep = 5,
+  SpiritTargetMove = 6,
+  PickupBomb = 7,
+  PickupPotion = 8,
+  PickupMana = 9,
+  MonFainted = 10,
+  ManaDropped = 11,
+  SupermanaBackToBase = 12,
+  BombAttack = 13,
+  MonAwake = 14,
+  BombExplosion = 15,
+  NextTurn = 16,
+  GameOver = 17,
+  Takeback = 18,
+  UsePotion = 19,
 }
 /**
 */
@@ -76,14 +51,6 @@ export enum SquareModelKind {
 }
 /**
 */
-export enum AvailableMoveKind {
-  MonMove = 0,
-  ManaMove = 1,
-  Action = 2,
-  Potion = 3,
-}
-/**
-*/
 export enum NextInputKind {
   MonMove = 0,
   ManaMove = 1,
@@ -97,33 +64,66 @@ export enum NextInputKind {
 }
 /**
 */
+export enum OutputModelKind {
+  InvalidInput = 0,
+  LocationsToStartFrom = 1,
+  NextInputOptions = 2,
+  Events = 3,
+}
+/**
+*/
 export enum ManaKind {
   Regular = 0,
   Supermana = 1,
 }
 /**
 */
-export enum EventModelKind {
+export enum AvailableMoveKind {
   MonMove = 0,
   ManaMove = 1,
-  ManaScored = 2,
-  MysticAction = 3,
-  DemonAction = 4,
-  DemonAdditionalStep = 5,
-  SpiritTargetMove = 6,
-  PickupBomb = 7,
-  PickupPotion = 8,
-  PickupMana = 9,
-  MonFainted = 10,
-  ManaDropped = 11,
-  SupermanaBackToBase = 12,
-  BombAttack = 13,
-  MonAwake = 14,
-  BombExplosion = 15,
-  NextTurn = 16,
-  GameOver = 17,
-  Takeback = 18,
-  UsePotion = 19,
+  Action = 2,
+  Potion = 3,
+}
+/**
+*/
+export enum MonKind {
+  Demon = 0,
+  Drainer = 1,
+  Angel = 2,
+  Spirit = 3,
+  Mystic = 4,
+}
+/**
+*/
+export enum GameVariant {
+  Classic = 0,
+  SwappedManaRows = 1,
+  OffsetArcManaRows = 2,
+  CenterSpokeManaRows = 3,
+  AlternatingManaRows = 4,
+  InnerWedgeManaRows = 5,
+  OuterWedgeManaRows = 6,
+  BentCenterManaRows = 7,
+  OuterEdgeManaRows = 8,
+  SplitFlankManaRows = 9,
+  ForwardBridgeManaRows = 10,
+  CornerChainManaRows = 11,
+}
+/**
+*/
+export enum ItemModelKind {
+  Mon = 0,
+  Mana = 1,
+  MonWithMana = 2,
+  MonWithConsumable = 3,
+  Consumable = 4,
+}
+/**
+*/
+export enum Modifier {
+  SelectPotion = 0,
+  SelectBomb = 1,
+  Cancel = 2,
 }
 /**
 */
@@ -447,141 +447,3 @@ export class VerboseTrackingEntityModel {
 */
   events(): (EventModel)[];
 }
-
-export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
-
-export interface InitOutput {
-  readonly memory: WebAssembly.Memory;
-  readonly __wbg_eventmodel_free: (a: number) => void;
-  readonly __wbg_get_eventmodel_color: (a: number) => number;
-  readonly __wbg_get_eventmodel_item: (a: number) => number;
-  readonly __wbg_get_eventmodel_kind: (a: number) => number;
-  readonly __wbg_get_eventmodel_loc1: (a: number) => number;
-  readonly __wbg_get_eventmodel_loc2: (a: number) => number;
-  readonly __wbg_get_eventmodel_mana: (a: number) => number;
-  readonly __wbg_get_eventmodel_mon: (a: number) => number;
-  readonly __wbg_get_itemmodel_consumable: (a: number) => number;
-  readonly __wbg_get_itemmodel_kind: (a: number) => number;
-  readonly __wbg_get_itemmodel_mana: (a: number) => number;
-  readonly __wbg_get_itemmodel_mon: (a: number) => number;
-  readonly __wbg_get_location_i: (a: number) => number;
-  readonly __wbg_get_location_j: (a: number) => number;
-  readonly __wbg_get_manamodel_color: (a: number) => number;
-  readonly __wbg_get_manamodel_kind: (a: number) => number;
-  readonly __wbg_get_mon_color: (a: number) => number;
-  readonly __wbg_get_mon_kind: (a: number) => number;
-  readonly __wbg_get_nextinputmodel_actor_mon_item: (a: number) => number;
-  readonly __wbg_get_nextinputmodel_kind: (a: number) => number;
-  readonly __wbg_get_nextinputmodel_modifier: (a: number) => number;
-  readonly __wbg_get_outputmodel_kind: (a: number) => number;
-  readonly __wbg_get_squaremodel_color: (a: number) => number;
-  readonly __wbg_get_squaremodel_kind: (a: number) => number;
-  readonly __wbg_get_squaremodel_mon_kind: (a: number) => number;
-  readonly __wbg_itemmodel_free: (a: number) => void;
-  readonly __wbg_location_free: (a: number) => void;
-  readonly __wbg_manamodel_free: (a: number) => void;
-  readonly __wbg_mon_free: (a: number) => void;
-  readonly __wbg_monsgamemodel_free: (a: number) => void;
-  readonly __wbg_nextinputmodel_free: (a: number) => void;
-  readonly __wbg_outputmodel_free: (a: number) => void;
-  readonly __wbg_set_eventmodel_color: (a: number, b: number) => void;
-  readonly __wbg_set_eventmodel_item: (a: number, b: number) => void;
-  readonly __wbg_set_eventmodel_kind: (a: number, b: number) => void;
-  readonly __wbg_set_eventmodel_loc1: (a: number, b: number) => void;
-  readonly __wbg_set_eventmodel_loc2: (a: number, b: number) => void;
-  readonly __wbg_set_eventmodel_mana: (a: number, b: number) => void;
-  readonly __wbg_set_eventmodel_mon: (a: number, b: number) => void;
-  readonly __wbg_set_itemmodel_consumable: (a: number, b: number) => void;
-  readonly __wbg_set_itemmodel_kind: (a: number, b: number) => void;
-  readonly __wbg_set_itemmodel_mana: (a: number, b: number) => void;
-  readonly __wbg_set_itemmodel_mon: (a: number, b: number) => void;
-  readonly __wbg_set_location_i: (a: number, b: number) => void;
-  readonly __wbg_set_location_j: (a: number, b: number) => void;
-  readonly __wbg_set_manamodel_color: (a: number, b: number) => void;
-  readonly __wbg_set_manamodel_kind: (a: number, b: number) => void;
-  readonly __wbg_set_mon_color: (a: number, b: number) => void;
-  readonly __wbg_set_mon_kind: (a: number, b: number) => void;
-  readonly __wbg_set_nextinputmodel_actor_mon_item: (a: number, b: number) => void;
-  readonly __wbg_set_nextinputmodel_kind: (a: number, b: number) => void;
-  readonly __wbg_set_nextinputmodel_modifier: (a: number, b: number) => void;
-  readonly __wbg_set_outputmodel_kind: (a: number, b: number) => void;
-  readonly __wbg_set_squaremodel_color: (a: number, b: number) => void;
-  readonly __wbg_set_squaremodel_kind: (a: number, b: number) => void;
-  readonly __wbg_set_squaremodel_mon_kind: (a: number, b: number) => void;
-  readonly __wbg_squaremodel_free: (a: number) => void;
-  readonly __wbg_verbosetrackingentitymodel_free: (a: number) => void;
-  readonly location_new: (a: number, b: number) => number;
-  readonly mon_decrease_cooldown: (a: number) => void;
-  readonly mon_faint: (a: number) => void;
-  readonly mon_is_fainted: (a: number) => number;
-  readonly mon_new: (a: number, b: number, c: number) => number;
-  readonly monsgamemodel_active_color: (a: number) => number;
-  readonly monsgamemodel_automove: (a: number) => number;
-  readonly monsgamemodel_available_move_kinds: (a: number, b: number) => void;
-  readonly monsgamemodel_black_score: (a: number) => number;
-  readonly monsgamemodel_can_takeback: (a: number, b: number) => number;
-  readonly monsgamemodel_clearTracking: (a: number) => void;
-  readonly monsgamemodel_fen: (a: number, b: number) => void;
-  readonly monsgamemodel_fromFenForSimulation: (a: number, b: number) => number;
-  readonly monsgamemodel_from_fen: (a: number, b: number) => number;
-  readonly monsgamemodel_inactive_player_items_counters: (a: number, b: number) => void;
-  readonly monsgamemodel_is_later_than: (a: number, b: number, c: number) => number;
-  readonly monsgamemodel_is_moves_verified: (a: number) => number;
-  readonly monsgamemodel_item: (a: number, b: number) => number;
-  readonly monsgamemodel_locations_with_content: (a: number, b: number) => void;
-  readonly monsgamemodel_new: (a: number) => number;
-  readonly monsgamemodel_newForSimulation: (a: number) => number;
-  readonly monsgamemodel_process_input: (a: number, b: number, c: number, d: number) => number;
-  readonly monsgamemodel_process_input_fen: (a: number, b: number, c: number) => number;
-  readonly monsgamemodel_remove_item: (a: number, b: number) => void;
-  readonly monsgamemodel_setVerboseTracking: (a: number, b: number) => void;
-  readonly monsgamemodel_smartAutomove: (a: number, b: number, c: number, d: number) => void;
-  readonly monsgamemodel_square: (a: number, b: number) => number;
-  readonly monsgamemodel_takeback: (a: number) => number;
-  readonly monsgamemodel_takeback_fens: (a: number, b: number) => void;
-  readonly monsgamemodel_turn_number: (a: number) => number;
-  readonly monsgamemodel_verbose_tracking_entities: (a: number, b: number) => void;
-  readonly monsgamemodel_verify_moves: (a: number, b: number, c: number, d: number, e: number) => number;
-  readonly monsgamemodel_white_score: (a: number) => number;
-  readonly monsgamemodel_winner_color: (a: number) => number;
-  readonly monsgamemodel_without_last_turn: (a: number, b: number, c: number) => number;
-  readonly outputmodel_events: (a: number, b: number) => void;
-  readonly outputmodel_input_fen: (a: number, b: number) => void;
-  readonly outputmodel_locations: (a: number, b: number) => void;
-  readonly outputmodel_next_inputs: (a: number, b: number) => void;
-  readonly verbosetrackingentitymodel_color: (a: number) => number;
-  readonly verbosetrackingentitymodel_events: (a: number, b: number) => void;
-  readonly verbosetrackingentitymodel_events_fen: (a: number, b: number) => void;
-  readonly verbosetrackingentitymodel_fen: (a: number, b: number) => void;
-  readonly winner: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
-  readonly __wbg_set_nextinputmodel_location: (a: number, b: number) => void;
-  readonly __wbg_set_mon_cooldown: (a: number, b: number) => void;
-  readonly __wbg_get_mon_cooldown: (a: number) => number;
-  readonly __wbg_get_nextinputmodel_location: (a: number) => number;
-  readonly __wbindgen_malloc: (a: number, b: number) => number;
-  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
-  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_exn_store: (a: number) => void;
-}
-
-export type SyncInitInput = BufferSource | WebAssembly.Module;
-/**
-* Instantiates the given `module`, which can either be bytes or
-* a precompiled `WebAssembly.Module`.
-*
-* @param {SyncInitInput} module
-*
-* @returns {InitOutput}
-*/
-export function initSync(module: SyncInitInput): InitOutput;
-
-/**
-* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
-* for everything else, calls `WebAssembly.instantiate` directly.
-*
-* @param {InitInput | Promise<InitInput>} module_or_path
-*
-* @returns {Promise<InitOutput>}
-*/
-export default function __wbg_init (module_or_path?: InitInput | Promise<InitInput>): Promise<InitOutput>;