feat: package exact solver with strict TypeScript, configuration and CLI

[Marcus-Rise]

The minimum-action solver becomes a reusable TypeScript package with a small public contract, shared library/CLI core and verified browser/Node distribution.

This revision addresses readability across every source file and the GitHub delivery tooling. Search orchestration, matrix row operations, predecessor storage, input validation and publication steps now have named responsibilities. Domain bounds, storage units and sentinels are explicit; deeply nested operations are split into short functions without changing search order or adding dependencies. Oxlint limits nesting to three levels in src/ and .github/scripts/.

• Keep ten flat src/*.ts files and two build entries: index.ts and cli.ts.
• Export solveLock(state, links, config?) and createSolverConfig(overrides?); preserve readonly tuple typing, immutable defaults and CLI --config.
• Build four self-contained browser/library files and one standalone CLI with Vite; keep strict TypeScript 7 and the coverage gate.
• Keep tests under tests/ and maintained documentation under wiki/. Generate reports, snapshots, coverage and traces only as artifacts.
• Use one release.yml workflow with three jobs: readonly verification, npm delivery and GitHub release. Main verification/build runs once. The same tested archive passes between jobs; publication uses trusted main tooling and separate permissions.
• Preserve actual PR-base / preceding-release comparisons, source and file identity checks, explicit performance acceptance, canaries and recovery from partial publication.

Local tests and the full benchmark completed before workflow YAML changes. An independent reviewer examined all ten source files, all seven delivery scripts and the workflow data flow; findings were resolved without adding reviewer reports to the repository.

Local verification	Result
Node source tests	277 passed on Node 24 and Node 26
Distribution / real-browser tests	13 / 528 passed
Static / installed browser consumers	24 / 24 passed
Same installed archive	Node 22.23.2, 24.19.0 and 26.8.1; CLI exits 0/1/2, exports and types
Coverage: statements / branches / functions / lines	96.44% / 92.72% / 100% / 96.26%
All 45 exact command paths	Unchanged from the pre-refactor implementation
45-input quality vs PR target	483 actions, 245 distinct-plate totals, 1,723 unit shifts, 438 switches; unchanged
Local timing / memory	Inconclusive / inconclusive; raw calibration and bounded repeats retained

Reproduce from the repository root:

pnpm install --frozen-lockfile
pnpm exec playwright install --with-deps chromium firefox webkit
pnpm test
pnpm verify:package --node /path/to/node22 --node /path/to/node26
git worktree add --detach ../gothic-lock-solver-base 3cbbeedbb409a2d8ffa5b00c778cfcb0b07c0ec6
pnpm benchmark --baseline-module ../gothic-lock-solver-base/src/index.mjs --baseline-format legacy --output-dir artifacts/benchmark

The benchmark compares the separately checked-out target source, not a candidate-owned expected snapshot. Inconclusive performance does not certify the absence of a regression and is not silently accepted for publication.

Hosted CI on b66d3d8 passed on its first attempt. Verification completed; the npm/GitHub publication jobs were skipped for this PR.

Verification artifacts contain the five builds, one archive tested in Node 22/24/26, coverage, real-browser reports, the baseline snapshot and the complete 45-input benchmark with calibration and bounded repeats. The downloaded artifact, report hashes, module hashes, source SHA and archive SHA were checked.

Hosted quality remains A/U/C/switches = 483/245/1723/438. Timing and memory both remain inconclusive. Sums of per-lock medians were 60.685 ms for the candidate and 55.259 ms for the target; these descriptive sums are not whole-workload latency or proof of a speedup. The report identifies candidate b66d3d8d371b2d7f17d85bf6bed9186006eab87c and separately checked-out target 3cbbeedbb409a2d8ffa5b00c778cfcb0b07c0ec6.

This PR remains a draft. The reference branch and history are preserved. No package publication, GitHub release or merge is part of this revision.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
gothic-lock-solver	Error		Sep 7, 2026 9:33am UTC

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-07T17:26:03.782319Z	b66d3d8	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b66d3d8d37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Require an explicit release action before npm delivery

In the inspected release.yml, every push to main—including a PR merge—satisfies this condition whenever NPM_PUBLICATION_READY remains true; because RELEASE_KIND defaults to stable, the workflow then proceeds directly to npm publish. This couples merging to publication and risks creating an immutable npm release from an ordinary merge, so stable delivery should require an explicit dispatch or equivalent separate release signal.

AGENTS.md reference: AGENTS.md:L58-L61

Useful? React with 👍 / 👎.