[leehack]

Summary

• First PR of the DecisionEngine stack (#604). Adds the design doc doc/decision_engine.md and the pure-Dart core for Laya-style decision models under lib/src/core/decision/:
  • python_json.dart: byte parity with Python json.dumps, including float repr, NaN/Infinity and ensure_ascii.
  • decision_question.dart, decision_result.dart: the question, request and answer types, in Laya's system_one wire format.
  • decision_sequence.dart: Laya 0.3.5 option rendering and sequence assembly, with the option squeeze, 512-token cut and marker-overflow error.
  • decision_decoder.dart: temperature buckets and clamping, confidence, act features, answer decoding.
• Adds LlamaDecisionException.
• Adds the parity fixture test/fixtures/decision/: 24 rows from official laya 0.3.5 (checkpoint 1c5edc17…, FP32 CPU), with the scripts that produced it and their provenance.

Production-readiness scope

• User-facing scope: none yet. Nothing new is exported from lib/llamadart.dart. LlamaDecisionException does become public, because exceptions.dart is already exported whole, but nothing throws it publicly until the next PR.
• Supported platforms/paths: pure Dart, runs on the VM and in the browser.
• Unsupported or intentionally unavailable paths: none. fromJson is stricter than Laya in two places, and both are documented: score criteria must be a list, and noul criteria must be null or a map.
• Out of scope / follow-ups: the native backend, facade, export, docs and changelog come in the next PR of #604.

Completeness checklist

• Declared scope is fully implemented, or explicitly reduced above.
• Unsupported platform/option combinations fail loudly with actionable diagnostics or are clearly documented as unavailable.
• Public API docs, README/website docs, examples, support matrices, and changelog entries are updated where relevant. (Internal only; public docs and the changelog land with the export.)
• Regression coverage covers the original issue plus key negative/version-skew paths where relevant.
• Security/privacy review completed: no secrets, bearer tokens, signed URLs, or raw secret-bearing paths leak through logs, cache keys, metadata, errors, or snapshots.
• Follow-up work that is useful but not required for this PR is tracked in GitHub Issues, or explicitly marked "None" above.

Test Plan

• dart run tool/prepare_workspace.dart
• dart format --output=none --set-exit-if-changed .
• dart analyze
• dart test -p vm test/unit/core/decision test/unit/core/exceptions_test.dart test/unit/test_structure (209 pass). The full VM suite runs in CI.
• dart test -p chrome test/unit/core/decision (112 pass). The 24-row fixture tests are VM-only because the fixture is read with dart:io.
• Other: dart run tool/testing/check_platform_boundaries.dart. Parity was checked against laya 0.3.5 on randomized inputs for json.dumps, sequence assembly and decoding. A mutation pass left no surviving mutant in the new code, apart from two that were judged not worth a test: the exception's superclass and a wire constant that has no consumer yet.

Matrix Evidence

Matrix row	Scope covered	Platform / model / backend	Result	Evidence / notes
static-format-analyze	format, analyzer, import boundaries	macOS arm64, Flutter 3.47.1	PASS	local
root-vm	new decision tests	macOS arm64	PASS	targeted locally; full suite in CI
root-chrome	new decision tests	Chrome	PASS	targeted locally; full suite in CI
coverage-lib	lib/src/core/decision	macOS arm64	PASS	100% line coverage of the new files locally

Review Notes

• Independent review status: an automated three-lens review (Python differential parity, repo rules, mutation testing) found 27 issues: 21 fixed, 3 needing no change, 3 rejected with reasons. I also reviewed the diff myself.
• CI status / head SHA: pending

High-risk regression review

• Classification: standard (classify_high_risk_changes.dart over every changed path)
• Implementation task: N/A
• Independent blocking QA task: N/A
• Exact head / current base: N/A
• Production-branch deletion, bypass, or miswire proof: N/A
• Affected-family real-model/artifact evidence: N/A
• Explicit unavailable-family or other N/A evidence: N/A
• Known PR-caused P1 regressions: 0
• Unresolved review threads: 0

[leehack]

Folded into #606: this core exports nothing on its own, and the pending type-safe API and cleanups change both halves. Its commit 038dea663 is the first commit of #606.

[github-actions]

Chat app preview removed for leehack/llamadart-chat-pr-605.